1 Mercurial Frequently Asked Questions

     1 Mercurial Frequently Asked Questions

     2 

     3 

     3 Section 1: General Usage

     4 Section 1: General Usage

     4 ------------------------

     5 ------------------------

     5 

     6 

     7 

     8 

     8 There are two parts to Mercurial: the repository and the working

     9 There are two parts to Mercurial: the repository and the working

    10 into the local one but doesn't alter the working directory.

    11 into the local one but doesn't alter the working directory.

    11 

    12 

    12 This keeps you from upsetting your work in progress, which may not be

    13 This keeps you from upsetting your work in progress, which may not be

    13 ready to merge with the new changes you've pulled and also allows you

    14 ready to merge with the new changes you've pulled and also allows you

    14 to manage merging more easily (see below about best practices).

    15 to manage merging more easily (see below about best practices).

    15 

    16 

    23 

    23 

    24 Mercurial will generally allow you to refer to a revision in three

    24 Mercurial will generally allow you to refer to a revision in three

    25 ways: by revision number, by changeset ID, and by tag.

    25 ways: by revision number, by changeset ID, and by tag.

    26 

    26 

    27 A revision number is a simple decimal number that corresponds with the

    27 A revision number is a simple decimal number that corresponds with the

    44 Finally, a tag is an arbitrary string that has been assigned a

    44 Finally, a tag is an arbitrary string that has been assigned a

    45 correspondence to a changeset ID. This lets you refer to revisions

    45 correspondence to a changeset ID. This lets you refer to revisions

    46 symbolically.

    46 symbolically.

    47 

    47 

    48 

    48 

    50 

    50 

    51 The central concept of Mercurial is branching. A 'branch' is simply

    51 The central concept of Mercurial is branching. A 'branch' is simply

    52 an independent line of development. In most other version control

    52 an independent line of development. In most other version control

    53 systems, all users generally commit to the same line of development

    53 systems, all users generally commit to the same line of development

    54 called 'the trunk' or 'the main branch'. In Mercurial, every developer

    54 called 'the trunk' or 'the main branch'. In Mercurial, every developer

    55 effectively works on a private branch and there is no internal concept

    55 effectively works on a private branch and there is no internal concept

    56 of 'the main branch'.

    56 of 'the main branch'.

    57 

    57 

    58 Thus Mercurial works hard to make repeated merging between branches

    58 Thus Mercurial works hard to make repeated merging between branches

    60 

    60 

    61 'Heads' are simply the most recent commits on a branch. Technically,

    61 'Heads' are simply the most recent commits on a branch. Technically,

    62 they are changesets which have no children. Merging is the process of

    62 they are changesets which have no children. Merging is the process of

    63 joining points on two branches into one, usually at their current

    63 joining points on two branches into one, usually at their current

    65 

    65 

    66 The 'tip' is the most recently changed head, and also the highest

    66 The 'tip' is the most recently changed head, and also the highest

    67 numbered revision. If you have just made a commit, that commit will be

    67 numbered revision. If you have just made a commit, that commit will be

    68 the head. Alternately, if you have just pulled from another

    68 the head. Alternately, if you have just pulled from another

    69 repository, the tip of that repository becomes the current tip.

    69 repository, the tip of that repository becomes the current tip.

    70 

    70 

    71 The 'tip' is the default revision for many commands such as update,

    71 The 'tip' is the default revision for many commands such as update,

    72 and also functions as a special symbolic tag.

    72 and also functions as a special symbolic tag.

    73 

    73 

    74 

    74 

    76 

    76 

    77 The merge process is simple. Usually you will want to merge the tip

    77 The merge process is simple. Usually you will want to merge the tip

    79 will incorporate the changes from tip into your local changes.

    79 will incorporate the changes from tip into your local changes.

    80 

    80 

    81 The first step of this process is tracing back through the history of

    81 The first step of this process is tracing back through the history of

    82 changesets and finding the 'common ancestor' of the two versions that

    82 changesets and finding the 'common ancestor' of the two versions that

    83 are being merged. This is done on a project-wide and a file by file

    83 are being merged. This is done on a project-wide and a file by file

    97 allow you to perform another merge until you've done this commit as

    97 allow you to perform another merge until you've done this commit as

    98 that would lose important history that will be needed for future

    98 that would lose important history that will be needed for future

    99 merges.

    99 merges.

   100 

   100 

   101 

   101 

   103 

   103 

   104 Tags work slightly differently in Mercurial than most revision

   104 Tags work slightly differently in Mercurial than most revision

   105 systems. The design attempts to meet the following requirements:

   105 systems. The design attempts to meet the following requirements:

   106 

   106 

   107 - be version controlled and mergeable just like any other file

   107 - be version controlled and mergeable just like any other file

   110 - allow changing tags in the future

   110 - allow changing tags in the future

   111 

   111 

   112 Thus Mercurial stores tags as a file in the working dir. This file is

   112 Thus Mercurial stores tags as a file in the working dir. This file is

   113 called .hgtags and consists of a list of changeset IDs and their

   113 called .hgtags and consists of a list of changeset IDs and their

   114 corresponding tags. To add a tag to the system, simply add a line to

   114 corresponding tags. To add a tag to the system, simply add a line to

   117 effective tags.

   117 effective tags.

   118 

   118 

   119 Note that because tags refer to changeset IDs and the changeset ID is

   119 Note that because tags refer to changeset IDs and the changeset ID is

   120 effectively the sum of all the contents of the repository for that

   120 effectively the sum of all the contents of the repository for that

   121 change, it is impossible in Mercurial to simultaneously commit and add

   121 change, it is impossible in Mercurial to simultaneously commit and add

   122 a tag. Thus tagging a revision must be done as a second step.

   122 a tag. Thus tagging a revision must be done as a second step.

   123 

   123 

   125 

   126 

   126 The tags that are in effect at any given time are the tags specified

   127 The tags that are in effect at any given time are the tags specified

   127 in each head, with heads closer to the tip taking precedence.

   128 in each head, with heads closer to the tip taking precedence.

   128 

   129 

   129 

   130 

   131 

   132 

   132 First, merge often! This makes merging easier for everyone and you

   133 First, merge often! This makes merging easier for everyone and you

   133 find out about conflicts (which are often rooted in incompatible

   134 find out about conflicts (which are often rooted in incompatible

   134 design decisions) earlier.

   135 design decisions) earlier.

   135 

   136 

   141 upstream repository. This works as a cache so that you don't have to

   142 upstream repository. This works as a cache so that you don't have to

   142 pull multiple copies over the network. No need to check files out here

   143 pull multiple copies over the network. No need to check files out here

   143 as you won't be changing them.

   144 as you won't be changing them.

   144 

   145 

   145 The outgoing tree contains all the changes you intend for merger into

   146 The outgoing tree contains all the changes you intend for merger into

   148 

   149 

   149 Then, for each feature you work on, create a new tree. Commit early

   150 Then, for each feature you work on, create a new tree. Commit early

   150 and commit often, merge with incoming regularly, and once you're

   151 and commit often, merge with incoming regularly, and once you're

   151 satisfied with your feature, pull the changes into your outgoing tree.

   152 satisfied with your feature, pull the changes into your outgoing tree.

   152 

   153 

   153 

   154 

   155 

   156 

   156 Take a look at contrib/convert-repo. This is an extensible

   157 Take a look at contrib/convert-repo. This is an extensible

   157 framework for converting between repository types.

   158 framework for converting between repository types.

   158 

   159 

   159 

   160 

   161 

   162 

   162 Patches to support Windows are being actively integrated, a fully

   163 Patches to support Windows are being actively integrated, a fully

   163 working Windows version is probably not far off

   164 working Windows version is probably not far off

   164 

   165 

   165 

   166 

   166 Section 2: Technical

   167 Section 2: Technical

   167 --------------------

   168 --------------------

   168 

   169 

   170 

   171 

   171 Mercurial currently assumes that single files, indices, and manifests

   172 Mercurial currently assumes that single files, indices, and manifests

   172 can fit in memory for efficiency.

   173 can fit in memory for efficiency.

   173 

   174 

   174 Offsets in revlogs are currently tracked with 32 bits, so a revlog for

   175 Offsets in revlogs are currently tracked with 32 bits, so a revlog for

   184 

   185 

   185 Mercurial is primarily developed for UNIX systems, so some UNIXisms

   186 Mercurial is primarily developed for UNIX systems, so some UNIXisms

   186 may be present in ports.

   187 may be present in ports.

   187 

   188 

   188 

   189 

   190 

   191 

   191 Take a look at the hgeditor script for an example. The basic idea

   192 Take a look at the hgeditor script for an example. The basic idea

   192 is to sign the manifest ID inside that changelog entry. The manifest

   193 is to sign the manifest ID inside that changelog entry. The manifest

   193 ID is a recursive hash of all of the files in the system and their

   194 ID is a recursive hash of all of the files in the system and their

   194 complete history, and thus signing the manifest hash signs the entire

   195 complete history, and thus signing the manifest hash signs the entire

   199 list of each file in the project along with its current file hash.

   200 list of each file in the project along with its current file hash.

   200 This manifest is hashed similarly to the file hashes, incorporating

   201 This manifest is hashed similarly to the file hashes, incorporating

   201 the hashes of the parent revisions.

   202 the hashes of the parent revisions.

   202 

   203 

   203 

   204 

   205 

   206 

   206 The SHA1 hashes are large enough that the odds of accidental hash collision

   207 The SHA1 hashes are large enough that the odds of accidental hash collision

   207 are negligible for projects that could be handled by the human race.

   208 are negligible for projects that could be handled by the human race.

   208 The known weaknesses in SHA1 are currently still not practical to

   209 The known weaknesses in SHA1 are currently still not practical to

   209 attack, and Mercurial will switch to SHA256 hashing before that

   210 attack, and Mercurial will switch to SHA256 hashing before that