|
1 Mercurial Frequently Asked Questions |
|
2 |
|
3 Section 1: General Usage |
|
4 ------------------------ |
|
5 |
|
6 Q. I did an 'hg pull' and my working directory is empty! |
|
7 |
|
8 There are two parts to Mercurial: the repository and the working |
|
9 directory. 'hg pull' pulls all new changes from a remote repository |
|
10 into the local one but doesn't alter the working directory. |
|
11 |
|
12 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 to manage merging more easily (see below about best practices). |
|
15 |
|
16 To update your working directory, run 'hg update'. If you're sure you |
|
17 want to update your working directory on a pull, you can also use 'hg |
|
18 pull -u'. This will refuse to merge or overwrite local changes. |
|
19 |
|
20 |
|
21 Q. What is the difference between revision numbers, changeset IDs, |
|
22 and tags? |
|
23 |
|
24 Mercurial will generally allow you to refer to a revision in three |
|
25 ways: by revision number, by changeset ID, and by tag. |
|
26 |
|
27 A revision number is a simple decimal number that corresponds with the |
|
28 ordering of commits in the local repository. It is important to |
|
29 understand that this ordering can change from machine to machine due |
|
30 to Mercurial's distributed, decentralized architecture. |
|
31 |
|
32 This is where changeset IDs come in. A changeset ID is a 160-bit |
|
33 identifier that uniquely describes a changeset and its position in the |
|
34 change history, regardless of which machine it's on. This is |
|
35 represented to the user as a 40 digit hexadecimal number. As that |
|
36 tends to be unwieldy, Mercurial will accept any unambiguous substring |
|
37 of that number when specifying versions. It will also generally print |
|
38 these numbers in "short form", which is the first 12 digits. |
|
39 |
|
40 You should always use some form of changeset ID rather than the local |
|
41 revision number when discussing revisions with other Mercurial users |
|
42 as they may have different revision numbering on their system. |
|
43 |
|
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 |
|
46 symbolically. |
|
47 |
|
48 |
|
49 Q. What are branches, heads, and the tip? |
|
50 |
|
51 The central concept of Mercurial is branching. A 'branch' is simply |
|
52 an independent line of development. In most other version control |
|
53 systems, all users generally commit to the same line of development |
|
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 |
|
56 of 'the main branch'. |
|
57 |
|
58 Thus Mercurial works hard to make repeated merging between branches |
|
59 easy. Simply run 'hg pull' and 'hg update -m' and commit the result. |
|
60 |
|
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 |
|
63 joining points on two branches into one, usually at their current |
|
64 heads. Use 'hg heads' to find the heads in the current repository. |
|
65 |
|
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 |
|
68 the head. Alternately, if you have just pulled from another |
|
69 repository, the tip of that repository becomes the current tip. |
|
70 |
|
71 The 'tip' is the default revision for many commands such as update, |
|
72 and also functions as a special symbolic tag. |
|
73 |
|
74 |
|
75 Q. How does merging work? |
|
76 |
|
77 The merge process is simple. Usually you will want to merge the tip |
|
78 into your working directory. Thus you run 'hg update -m' and Mercurial |
|
79 will incorporate the changes from tip into your local changes. |
|
80 |
|
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 |
|
83 are being merged. This is done on a project-wide and a file by file |
|
84 basis. |
|
85 |
|
86 For files that have been changed in both projects, a three-way merge |
|
87 is attempted to add the changes made remotely into the changes made |
|
88 locally. If there are conflicts between these changes, the user is |
|
89 prompted to interactively resolve them. |
|
90 |
|
91 Mercurial uses a helper tool for this, which is usually found by the |
|
92 hgmerge script. Example tools include tkdiff, kdiff3, and the classic |
|
93 RCS merge. |
|
94 |
|
95 After you've completed the merge and you're satisfied that the results |
|
96 are correct, it's a good idea to commit your changes. Mercurial won't |
|
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 |
|
99 merges. |
|
100 |
|
101 |
|
102 Q. How do tags work in Mercurial? |
|
103 |
|
104 Tags work slightly differently in Mercurial than most revision |
|
105 systems. The design attempts to meet the following requirements: |
|
106 |
|
107 - be version controlled and mergeable just like any other file |
|
108 - allow signing of tags |
|
109 - allow adding a tag to an already committed changeset |
|
110 - allow changing tags in the future |
|
111 |
|
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 |
|
114 corresponding tags. To add a tag to the system, simply add a line to |
|
115 this file and then commit it for it to take effect. The 'hg tag' |
|
116 command will do this for you and 'hg tags' will show the currently |
|
117 effective tags. |
|
118 |
|
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 |
|
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. |
|
123 |
|
124 Q. How do tags work with multiple heads? |
|
125 |
|
126 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 |
|
129 |
|
130 Q. What are some best practices for distributed development with Mercurial? |
|
131 |
|
132 First, merge often! This makes merging easier for everyone and you |
|
133 find out about conflicts (which are often rooted in incompatible |
|
134 design decisions) earlier. |
|
135 |
|
136 Second, don't hesitate to use multiple trees locally. Mercurial makes |
|
137 this fast and light-weight. Typical usage is to have an incoming tree, |
|
138 an outgoing tree, and a separate tree for each area being worked on. |
|
139 |
|
140 The incoming tree is best maintained as a pristine copy of the |
|
141 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 as you won't be changing them. |
|
144 |
|
145 The outgoing tree contains all the changes you intend for merger into |
|
146 upsteam. Publish this tree with 'hg serve' or hgweb.cgi or use 'hg |
|
147 push' to push it to another publicly availabe repository. |
|
148 |
|
149 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 satisfied with your feature, pull the changes into your outgoing tree. |
|
152 |
|
153 |
|
154 Q. How do I import from a repository created in a different SCM? |
|
155 |
|
156 Take a look at contrib/convert-repo. This is an extensible |
|
157 framework for converting between repository types. |
|
158 |
|
159 |
|
160 Q. What about Windows support? |
|
161 |
|
162 Patches to support Windows are being actively integrated, a fully |
|
163 working Windows version is probably not far off |
|
164 |
|
165 |
|
166 Section 2: Technical |
|
167 -------------------- |
|
168 |
|
169 Q. What limits does Mercurial have? |
|
170 |
|
171 Mercurial currently assumes that single files, indices, and manifests |
|
172 can fit in memory for efficiency. |
|
173 |
|
174 Offsets in revlogs are currently tracked with 32 bits, so a revlog for |
|
175 a single file can currently not grow beyond 4G. |
|
176 |
|
177 There should otherwise be no limits on file name length, file size, |
|
178 file contents, number of files, or number of revisions. |
|
179 |
|
180 The network protocol is big-endian. |
|
181 |
|
182 File names cannot contain the null character. Committer addresses |
|
183 cannot contain newlines. |
|
184 |
|
185 Mercurial is primarily developed for UNIX systems, so some UNIXisms |
|
186 may be present in ports. |
|
187 |
|
188 |
|
189 Q. How does signing work? |
|
190 |
|
191 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 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 project to that point. |
|
196 |
|
197 More precisely: each file hash is an SHA1 hash of the contents of that |
|
198 file and the hashes of its parent revisions. The manifest contains a |
|
199 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 the hashes of the parent revisions. |
|
202 |
|
203 |
|
204 Q. What about hash collisions? What about weaknesses in SHA1? |
|
205 |
|
206 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 The known weaknesses in SHA1 are currently still not practical to |
|
209 attack, and Mercurial will switch to SHA256 hashing before that |
|
210 becomes a realistic concern. |
|
211 |
|
212 Collisions with the "short hashes" are not a concern as they're always |
|
213 checked for ambiguity and are still long enough that they're not |
|
214 likely to happen for reasonably-sized projects (< 1M changes). |