Diff for "TutorialHistory"

Differences between revisions 1 and 29 (spanning 28 versions)

Tutorial - Examining repository history

(This page is part 3 of 9 of the [:Tutorial] series. Previous part is [:TutorialClone], next part is [:TutorialFirstChange])

At this point, we have followed TutorialClone to clone a repository; our local copy is called my-hello.

Let's take a look at the history of this [:Repository:repository]. To do this, we use the log command. This prints a summary of every event that has occurred in the repository, going backwards in time from the most recent.

$ cd my-hello
$ hg log
changeset:   1:82e55d328c8c
tag:         tip
user:        mpm@selenic.com
date:        Fri Aug 26 01:21:28 2005 -0700
summary:     Create a makefile

changeset:   0:0a04b987be5a
user:        mpm@selenic.com
date:        Fri Aug 26 01:20:50 2005 -0700
summary:     Create a standard "hello, world" program

These lines of output bear some describing.

Each paragraph describes a particular [:ChangeSet:changeset]. A changeset is a modification of one or more files, grouped together into a logical unit.
- In our case above, we can see that the repository's history consists of two changesets.
changeset identifies a changeset.
- The first number before the colon is a [:RevisionNumber:revision number]; it is a local short-hand way of identifying the changeset. It is only valid within this repository.
- The hexadecimal string after the colon is a short-form [:ChangeSetID:changeset ID]; it identifies the changeset, and is the same in all repositories that contain this changeset. If you are ever discussing a changeset with someone else, use the changeset ID, not the revision number.
tag is a [:Tag:tag], an arbitrary symbolic name for a changeset.
- You can assign one or more tags to any changeset. Actually, not that many changeset will have tags associated with them, so the tag line will seldom be present.
- The special tag named tip always identifies the [:Tip:tip], which is the most recent changeset in the repository. If you create another changeset (and we will, soon), the tip tag will be removed from the most recent changeset and will be added to the new changeset.
user identifies the person who created the changeset. This is a free-form string; it usually contains an email address, and sometimes a person's name, too.
date describes when the changeset was created. These dates are printed in the local time zone the creator of the changeset was in.
summary gives the first line of the description of the changeset. This was entered by the creator of the changeset at the time they created it, to help themselves and others understand the purpose of the changeset (see also ["ChangeSetComments"]).
parent identifies the [:Parent:parent] changesets, in case there are more than one, which happens when you [:Merge:merge] changes from several repositories.
- Most of the times there is only one parent, which is the one changeset older than itself. This is the case in our example above.

We can get more detailed history information by asking for verbose output with the -v option, or the --debug global option for everything under the sun:

$ hg log -v
changeset:   1:82e55d328c8c
tag:         tip
user:        mpm@selenic.com
date:        Fri Aug 26 01:21:28 2005 -0700
files:       Makefile
description:
Create a makefile

(...)

$ hg log --debug
changeset:   1:82e55d328c8ca4ee16520036c0aaace03a5beb65
tag:         tip
parent:      0:0a04b987be5ae354b710cefeba0e2d9de7ad41a9
parent:      -1:0000000000000000000000000000000000000000
manifest:    1:0c7c1d435e6703e03ac6634a7c32da3a082d1600
user:        mpm@selenic.com
date:        Fri Aug 26 01:21:28 2005 -0700
files+:      Makefile
extra:       branch=default
description:
Create a makefile

(...)

Verbose output contains a few more fields than the default output.

files lists the files modified in this changeset.
description contains the complete multi-line description of the changeset, rather than just the first line.
- In our case, the descriptions are only one-line long, so there's not much difference.

The --debug output adds the following fields to the verbose output (see also [:DebuggingFeatures]):

changeset now gives the unabbreviated changeset ID.
two parent fields giving the changeset ID of both parents for this changeset, where -1:0000000000000000000000000000000000000000 refers to a non-existant parent.
manifest gives the [:Manifest:manifest] ID for this changeset.
file+ lists the file(s) added in this changeset.
file- lists the file(s) removed in this changeset.

The log command comes with a -r option to view specific changesets.

$ hg log -r1
changeset:   1:82e55d328c8c
tag:         tip
user:        mpm@selenic.com
date:        Fri Aug 26 01:21:28 2005 -0700
summary:     Create a makefile

The -r option actually supports a very flexible syntax to select a range of changesets. However, due to limited number of changesets available in our sample repository, we are unable to provide a good demonstration. Please consult the [http://www.cadifra.com/mercurial/hg.1.html#log manpage] for more information.

The log command also comes with a -p option to show the patches associated with the changesets:

$ hg log -r1 -p
changeset:   1:82e55d328c8c
tag:         tip
user:        mpm@selenic.com
date:        Fri Aug 26 01:21:28 2005 -0700
summary:     Create a makefile

diff -r 0a04b987be5a -r 82e55d328c8c Makefile
--- /dev/null   Fri Aug 26 01:20:50 2005 -0700
+++ b/Makefile  Fri Aug 26 01:21:28 2005 -0700
@@ -0,0 +1,1 @@
+all: hello

We can also use the tip command to show info of the tip, i.e. the latest, changeset. The tip command may be considered a shortcut to log -r tip.

$ hg tip
changeset:   1:82e55d328c8c
tag:         tip
user:        mpm@selenic.com
date:        Fri Aug 26 01:21:28 2005 -0700
summary:     Create a makefile

$ hg log -r tip
changeset:   1:82e55d328c8c
tag:         tip
user:        mpm@selenic.com
date:        Fri Aug 26 01:21:28 2005 -0700
summary:     Create a makefile

Now that we have some slight idea of what has happened, let's jump in and make some changes! Onwards, to [:TutorialFirstChange]!

CategoryTutorial

-  ⇤ ← Revision 1 as of 2005-08-26 00:58:33 → 
  Size: 3633
  Editor: waste
  Comment:
+   ← Revision 29 as of 2008-05-07 09:41:54 → ⇥
  Size: 6537
  Editor: abuehl
  Comment: adding navigation on top
-Deletions are marked like this.
+Additions are marked like this.
 Line 1:
-== ["Tutorial"] - examining repository history ==
+== Tutorial - Examining repository history ==
 Line 3:
-At this point, we have followed TutorialClone to clone a ["Repository"]; our local copy is called ''my-hello''.
+''(This page is part 3 of 9 of the [:Tutorial] series. Previous part is [:TutorialClone], next part is [:TutorialFirstChange])''
 Line 5:
-Let's take a look at the history of this repository.  To do this, we use the ''log'' command.  This prints a summary of every event that has occurred in the ["Repository"], going backwards in time from the most recent.
+At this point, we have followed TutorialClone to clone a repository; our local copy is called {{{my-hello}}}.

Let's take a look at the history of this [:Repository:repository].  To do this, we use the {{{log}}} command.  This prints a summary of every event that has occurred in the repository, going backwards in time from the most recent.
-Line 8:
+Line 10:
- $ cd my-hello
 $ hg log
 changeset:   2:bd2fb7137c85cd5e6b04db4c72a45699e0d90ea9
 tag:         tip
 user:        bos@camp4.serpentine.com
 date:        Wed Jun 29 12:04:20 2005
 summary:     Add a helpful, descriptive comment to the makefile.
}}}
+$ cd my-hello
$ hg log
changeset:   1:82e55d328c8c
tag:         tip
user:        mpm@selenic.com
date:        Fri Aug 26 01:21:28 2005 -0700
summary:     Create a makefile
-Line 17:
+Line 18:
-{{{
 changeset:   1:4a17053ec93dd51ea37340f639db457c42065da6
 user:        bos@camp4.serpentine.com
 date:        Wed Jun 29 12:03:45 2005
 summary:     Add description to hello.c.
}}}

{{{
 changeset:   0:5931063e4b0fb17fc4625447b69296356ca6cdfc
 user:        bos@camp4.serpentine.com
 date:        Wed Jun 29 12:02:36 2005
 summary:     Add hello, world.
+changeset:   0:0a04b987be5a
user:        mpm@selenic.com
date:        Fri Aug 26 01:20:50 2005 -0700
summary:     Create a standard "hello, world" program
-Line 33:
+Line 26:
- * Each paragraph describes a particular ChangeSet.  A ChangeSet is a modification of one or more files, grouped together into a logical unit.
 * In the case above, we can see that the ["Repository"]'s history consists of four ["ChangeSet"]s.
 * ''changeset'' identifies a ChangeSet.
** The first number before the colon is a RevisionNumber; it is a local short-hand way of identifying the ChangeSet.  It is only valid within this ["Repository"].
** The long hexadecimal string after the colon is a ChangeSetID; it uniquely  identifies the ChangeSet, and is the same in all repositories that contain this ChangeSet.  If you are ever discussing a ChangeSet with someone else, use the ChangeSetID, not the RevisionNumber.
 * ''tag'' is a ["Tag"], an arbitrary symbolic name for a ChangeSet.
** You can assign one or more ["Tag"]s to any ChangeSet.  Naturally, not all ["ChangeSet"]s will have ["Tag"]s associated with them, so the ''tag'' line will not always be present.
** The special ["Tag"] named ''tip'' always identifies the ["Tip"], which is the most recent ChangeSet in the ["Repository"].  If you create another ChangeSet (and we will, soon), that will become the ["Tip"].
 * ''user'' identifies the person who created the ChangeSet.  This is a free-form string; it usually contains an email address, and sometimes a person's name, too.
 * ''date'' describes when the ChangeSet was created.  These dates are printed in your local time zone, no matter what time zone the creator of the ChangeSet was in.
 * ''summary'' gives the first line of the description of the ChangeSet.  This was entered by the creator of the ChangeSet at the time they created it, to help themselves and others understand the purpose of the ChangeSet.
+ * Each paragraph describes a particular [:ChangeSet:changeset].  A changeset is a modification of one or more files, grouped together into a logical unit.
   * In our case above, we can see that the repository's history consists of two changesets.
 * {{{changeset}}} identifies a changeset.
   * The first number before the colon is a [:RevisionNumber:revision number]; it is a local short-hand way of identifying the changeset.  It is only valid within this repository.
   * The hexadecimal string after the colon is a short-form [:ChangeSetID:changeset ID]; it identifies the changeset, and is the same in all repositories that contain this changeset. If you are ever discussing a changeset with someone else, use the changeset ID, not the revision number.
 * {{{tag}}} is a [:Tag:tag], an arbitrary symbolic name for a changeset.
   * You can assign one or more tags to any changeset.  Actually, not that many changeset will have tags associated with them, so the {{{tag}}} line will seldom be present.
   * The special tag named {{{tip}}} always identifies the [:Tip:tip], which is the most recent changeset in the repository.  If you create another changeset (and we will, soon), the {{{tip}}} tag will be removed from the most recent changeset and will be added to the new changeset.
 * {{{user}}} identifies the person who created the changeset.  This is a free-form string; it usually contains an email address, and sometimes a person's name, too.
 * {{{date}}} describes when the changeset was created.  These dates are printed in the local time zone the creator of the changeset was in.
 * {{{summary}}} gives the first line of the description of the changeset.  This was entered by the creator of the changeset at the time they created it, to help themselves and others understand the purpose of the changeset (see also ["ChangeSetComments"]).
 * {{{parent}}} identifies the [:Parent:parent] changesets, in case there are more than one, which happens when you [:Merge:merge] changes from several repositories.
   * Most of the times there is only one parent, which is the one changeset older than itself. This is the case in our example above.
-Line 45:
+Line 40:
-We can get more detailed history information by asking for verbose output:
+We can get more detailed history information by asking for verbose output with the {{{-v}}} option, or the {{{--debug}}} global option for everything under the sun:
-Line 48:
+Line 43:
- $ hg -v log
 revision:    1:1c18e981f8b0bd07d2b3343825486c010a82ad6a
 changeset:   1:4a17053ec93dd51ea37340f639db457c42065da6
 user:        bos@camp4.serpentine.com
 date:        Wed Jun 29 12:03:45 2005
 files:       hello.c
 description:
 Add description to hello.c.
}}}
+$ hg log -v
changeset:   1:82e55d328c8c
tag:         tip
user:        mpm@selenic.com
date:        Fri Aug 26 01:21:28 2005 -0700
files:       Makefile
description:
Create a makefile
-Line 58:
+Line 52:
-{{{
 ...
+(...)

$ hg log --debug
changeset:   1:82e55d328c8ca4ee16520036c0aaace03a5beb65
tag:         tip
parent:      0:0a04b987be5ae354b710cefeba0e2d9de7ad41a9
parent:      -1:0000000000000000000000000000000000000000
manifest:    1:0c7c1d435e6703e03ac6634a7c32da3a082d1600
user:        mpm@selenic.com
date:        Fri Aug 26 01:21:28 2005 -0700
files+:      Makefile
extra:       branch=default
description:
Create a makefile

(...)
-Line 64:
+Line 72:
- * ''revision'' is a field you can safely ignore.
 * ''files'' lists the files modified in this ChangeSet.
 * ''description'' contains the complete multi-line description of the ChangeSet, rather than just the first line.
+ * {{{files}}} lists the files modified in this changeset.
 * {{{description}}} contains the complete multi-line description of the changeset, rather than just the first line.
   * In our case, the descriptions are only one-line long, so there's not much difference.
-Line 68:
+Line 76:
-Now that we have some slight idea of what has happened, let's jump in and make some changes!  Onwards, to TutorialFirstChange!
+The `--debug` output adds the following fields to the verbose output (see also [:DebuggingFeatures]):

 * {{{changeset}}} now gives the unabbreviated changeset ID.
 * two {{{parent}}} fields giving the changeset ID of both parents for this changeset, where {{{-1:0000000000000000000000000000000000000000}}} refers to a non-existant parent.
 * {{{manifest}}} gives the [:Manifest:manifest] ID for this changeset.
 * {{{file+}}} lists the file(s) added in this changeset.
 * {{{file-}}} lists the file(s) removed in this changeset.


The {{{log}}} command comes with a {{{-r}}} option to view specific changesets. 

{{{
$ hg log -r1
changeset:   1:82e55d328c8c
tag:         tip
user:        mpm@selenic.com
date:        Fri Aug 26 01:21:28 2005 -0700
summary:     Create a makefile
}}}

<!> The {{{-r}}} option actually supports a very flexible syntax to select a range of changesets. However, due to limited number of changesets available in our sample repository, we are unable to provide a good demonstration. Please consult the [http://www.cadifra.com/mercurial/hg.1.html#log manpage] for more information.

The {{{log}}} command also comes with a  {{{-p}}} option to show the patches associated with the changesets:

{{{
$ hg log -r1 -p
changeset:   1:82e55d328c8c
tag:         tip
user:        mpm@selenic.com
date:        Fri Aug 26 01:21:28 2005 -0700
summary:     Create a makefile

diff -r 0a04b987be5a -r 82e55d328c8c Makefile
--- /dev/null   Fri Aug 26 01:20:50 2005 -0700
+++ b/Makefile  Fri Aug 26 01:21:28 2005 -0700
@@ -0,0 +1,1 @@
+all: hello
}}}

We can also use the {{{tip}}} command to show info of the ''tip'', i.e. the latest, changeset. The {{{tip}}} command may be considered a shortcut to {{{log -r tip}}}.

{{{
$ hg tip
changeset:   1:82e55d328c8c
tag:         tip
user:        mpm@selenic.com
date:        Fri Aug 26 01:21:28 2005 -0700
summary:     Create a makefile

$ hg log -r tip
changeset:   1:82e55d328c8c
tag:         tip
user:        mpm@selenic.com
date:        Fri Aug 26 01:21:28 2005 -0700
summary:     Create a makefile
}}}

Now that we have some slight idea of what has happened, let's jump in and make some changes!  Onwards, to [:TutorialFirstChange]!

----
CategoryTutorial