author | Bryan O'Sullivan <bos@serpentine.com> |
Sat, 13 Aug 2005 14:41:51 -0800 | |
changeset 891 | a9b843b114f9 |
parent 740 | d2422f10c136 |
permissions | -rw-r--r-- |
446 | 1 |
Mercurial Frequently Asked Questions |
449 | 2 |
==================================== |
446 | 3 |
|
4 |
Section 1: General Usage |
|
5 |
------------------------ |
|
6 |
||
449 | 7 |
.Q. I did an "hg pull" and my working directory is empty! |
446 | 8 |
|
9 |
There are two parts to Mercurial: the repository and the working |
|
449 | 10 |
directory. "hg pull" pulls all new changes from a remote repository |
446 | 11 |
into the local one but doesn't alter the working directory. |
12 |
||
13 |
This keeps you from upsetting your work in progress, which may not be |
|
14 |
ready to merge with the new changes you've pulled and also allows you |
|
15 |
to manage merging more easily (see below about best practices). |
|
16 |
||
449 | 17 |
To update your working directory, run "hg update". If you're sure you |
18 |
want to update your working directory on a pull, you can also use "hg |
|
19 |
pull -u". This will refuse to merge or overwrite local changes. |
|
446 | 20 |
|
21 |
||
449 | 22 |
.Q. What are revision numbers, changeset IDs, and tags? |
446 | 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 |
||
449 | 49 |
.Q. What are branches, heads, and the tip? |
446 | 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 |
|
449 | 59 |
easy. Simply run "hg pull" and "hg update -m" and commit the result. |
446 | 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 |
|
449 | 64 |
heads. Use "hg heads" to find the heads in the current repository. |
446 | 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 |
|
718 | 68 |
the tip. Alternately, if you have just pulled from another |
446 | 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 |
||
449 | 75 |
.Q. How does merging work? |
446 | 76 |
|
77 |
The merge process is simple. Usually you will want to merge the tip |
|
449 | 78 |
into your working directory. Thus you run "hg update -m" and Mercurial |
446 | 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 |
||
449 | 102 |
.Q. How do tags work in Mercurial? |
446 | 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 |
|
449 | 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 |
|
446 | 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 |
||
449 | 124 |
|
455 | 125 |
.Q. What if I want to just keep local tags? |
126 |
||
631
a287f6cd9c6b
Update documentation of hg tag
Radoslaw Szkodzinski <astralstorm@gorzow.mm.pl>
parents:
456
diff
changeset
|
127 |
You can use "hg tag" command with an option "-l" or "--local". This |
a287f6cd9c6b
Update documentation of hg tag
Radoslaw Szkodzinski <astralstorm@gorzow.mm.pl>
parents:
456
diff
changeset
|
128 |
will store the tag in the file .hg/localtags, which will not be |
a287f6cd9c6b
Update documentation of hg tag
Radoslaw Szkodzinski <astralstorm@gorzow.mm.pl>
parents:
456
diff
changeset
|
129 |
distributed or versioned. The format of this file is identical to the |
a287f6cd9c6b
Update documentation of hg tag
Radoslaw Szkodzinski <astralstorm@gorzow.mm.pl>
parents:
456
diff
changeset
|
130 |
one of .hgtags and the tags stored there are handled the same. |
455 | 131 |
|
132 |
||
449 | 133 |
.Q. How do tags work with multiple heads? |
446 | 134 |
|
135 |
The tags that are in effect at any given time are the tags specified |
|
455 | 136 |
in each head, with heads closer to the tip taking precedence. Local |
137 |
tags override all other tags. |
|
446 | 138 |
|
139 |
||
449 | 140 |
.Q. What are some best practices for distributed development with Mercurial? |
446 | 141 |
|
142 |
First, merge often! This makes merging easier for everyone and you |
|
143 |
find out about conflicts (which are often rooted in incompatible |
|
144 |
design decisions) earlier. |
|
145 |
||
146 |
Second, don't hesitate to use multiple trees locally. Mercurial makes |
|
147 |
this fast and light-weight. Typical usage is to have an incoming tree, |
|
148 |
an outgoing tree, and a separate tree for each area being worked on. |
|
149 |
||
150 |
The incoming tree is best maintained as a pristine copy of the |
|
151 |
upstream repository. This works as a cache so that you don't have to |
|
152 |
pull multiple copies over the network. No need to check files out here |
|
153 |
as you won't be changing them. |
|
154 |
||
718 | 155 |
The outgoing tree contains all the changes you intend for merge into |
449 | 156 |
upsteam. Publish this tree with 'hg serve" or hgweb.cgi or use 'hg |
157 |
push" to push it to another publicly availabe repository. |
|
446 | 158 |
|
159 |
Then, for each feature you work on, create a new tree. Commit early |
|
160 |
and commit often, merge with incoming regularly, and once you're |
|
161 |
satisfied with your feature, pull the changes into your outgoing tree. |
|
162 |
||
163 |
||
449 | 164 |
.Q. How do I import from a repository created in a different SCM? |
446 | 165 |
|
166 |
Take a look at contrib/convert-repo. This is an extensible |
|
167 |
framework for converting between repository types. |
|
168 |
||
169 |
||
449 | 170 |
.Q. What about Windows support? |
446 | 171 |
|
172 |
Patches to support Windows are being actively integrated, a fully |
|
173 |
working Windows version is probably not far off |
|
174 |
||
175 |
||
456 | 176 |
Section 2: Bugs and Features |
177 |
---------------------------- |
|
178 |
||
179 |
.Q. I found a bug, what do I do? |
|
180 |
||
181 |
Report it to the mercurial mailing list, mercurial@selenic.com. |
|
182 |
||
183 |
||
184 |
.Q. What should I include in my bug report? |
|
185 |
||
186 |
Enough information to reproduce or diagnose the bug. If you can, try |
|
187 |
using the hg -v and hg -d switches to figure out exactly what |
|
188 |
Mercurial is doing. |
|
189 |
||
190 |
If you can reproduce the bug in a simple repository, that is very |
|
191 |
helpful. The best is to create a simple shell script to automate this |
|
192 |
process, which can then be added to our test suite. |
|
193 |
||
194 |
||
195 |
.Q. Can Mercurial do <x>? |
|
196 |
||
197 |
If you'd like to request a feature, send your request to |
|
198 |
mercurial@selenic.com. As Mercurial is still very new, there are |
|
718 | 199 |
certainly features it is missing and you can give us feedback on how |
456 | 200 |
best to implement them. |
201 |
||
202 |
||
203 |
Section 3: Technical |
|
446 | 204 |
-------------------- |
205 |
||
449 | 206 |
.Q. What limits does Mercurial have? |
446 | 207 |
|
208 |
Mercurial currently assumes that single files, indices, and manifests |
|
209 |
can fit in memory for efficiency. |
|
210 |
||
211 |
Offsets in revlogs are currently tracked with 32 bits, so a revlog for |
|
212 |
a single file can currently not grow beyond 4G. |
|
213 |
||
214 |
There should otherwise be no limits on file name length, file size, |
|
215 |
file contents, number of files, or number of revisions. |
|
216 |
||
217 |
The network protocol is big-endian. |
|
218 |
||
219 |
File names cannot contain the null character. Committer addresses |
|
220 |
cannot contain newlines. |
|
221 |
||
222 |
Mercurial is primarily developed for UNIX systems, so some UNIXisms |
|
223 |
may be present in ports. |
|
224 |
||
225 |
||
455 | 226 |
.Q. How does Mercurial store its data? |
227 |
||
228 |
The fundamental storage type in Mercurial is a "revlog". A revlog is |
|
229 |
the set of all revisions of a named object. Each revision is either |
|
230 |
stored compressed in its entirety or as a compressed binary delta |
|
231 |
against the previous version. The decision of when to store a full |
|
232 |
version is made based on how much data would be needed to reconstruct |
|
233 |
the file. This lets us ensure that we never need to read huge amounts |
|
234 |
of data to reconstruct a object, regardless of how many revisions of it |
|
235 |
we store. |
|
236 |
||
237 |
In fact, we should always be able to do it with a single read, |
|
238 |
provided we know when and where to read. This is where the index comes |
|
239 |
in. Each revlog has an index containing a special hash (nodeid) of the |
|
240 |
text, hashes for its parents, and where and how much of the revlog |
|
241 |
data we need to read to reconstruct it. Thus, with one read of the |
|
242 |
index and one read of the data, we can reconstruct any version in time |
|
243 |
proportional to the object size. |
|
244 |
||
245 |
Similarly, revlogs and their indices are append-only. This means that |
|
246 |
adding a new version is also O(1) seeks. |
|
247 |
||
248 |
Revlogs are used to represent all revisions of files, manifests, and |
|
249 |
changesets. Compression for typical objects with lots of revisions can |
|
250 |
range from 100 to 1 for things like project makefiles to over 2000 to |
|
251 |
1 for objects like the manifest. |
|
252 |
||
253 |
||
254 |
.Q. How are manifests and changesets stored? |
|
255 |
||
256 |
A manifest is simply a list of all files in a given revision of a |
|
257 |
project along with the nodeids of the corresponding file revisions. So |
|
258 |
grabbing a given version of the project means simply looking up its |
|
718 | 259 |
manifest and reconstructing all the file revisions pointed to by it. |
446 | 260 |
|
455 | 261 |
A changeset is a list of all files changed in a check-in along with a |
262 |
change description and some metadata like user and date. It also |
|
263 |
contains a nodeid to the relevent revision of the manifest. |
|
264 |
||
265 |
||
266 |
.Q. How do Mercurial hashes get calculated? |
|
267 |
||
268 |
Mercurial hashes both the contents of an object and the hash of its |
|
269 |
parents to create an identifier that uniquely identifies an object's |
|
270 |
contents and history. This greatly simplifies merging of histories |
|
271 |
because it avoid graph cycles that can occur when a object is reverted |
|
272 |
to an earlier state. |
|
273 |
||
274 |
All file revisions have an associated hash value. These are listed in |
|
275 |
the manifest of a given project revision, and the manifest hash is |
|
276 |
listed in the changeset. The changeset hash is again a hash of the |
|
277 |
changeset contents and its parents, so it uniquely identifies the |
|
278 |
entire history of the project to that point. |
|
279 |
||
446 | 280 |
|
455 | 281 |
.Q. What checks are there on repository integrity? |
282 |
||
283 |
Every time a revlog object is retrieved, it is checked against its |
|
284 |
hash for integrity. It is also incidentally doublechecked by the |
|
285 |
Adler32 checksum used by the underlying zlib compression. |
|
286 |
||
287 |
Running 'hg verify' decompresses and reconstitutes each revision of |
|
288 |
each object in the repository and cross-checks all of the index |
|
289 |
metadata with those contents. |
|
290 |
||
291 |
But this alone is not enough to ensure that someone hasn't tampered |
|
292 |
with a repository. For that, you need cryptographic signing. |
|
293 |
||
294 |
||
295 |
.Q. How does signing work with Mercurial? |
|
296 |
||
297 |
Take a look at the hgeditor script for an example. The basic idea is |
|
298 |
to use GPG to sign the manifest ID inside that changelog entry. The |
|
299 |
manifest ID is a recursive hash of all of the files in the system and |
|
300 |
their complete history, and thus signing the manifest hash signs the |
|
301 |
entire project contents. |
|
446 | 302 |
|
303 |
||
449 | 304 |
.Q. What about hash collisions? What about weaknesses in SHA1? |
446 | 305 |
|
306 |
The SHA1 hashes are large enough that the odds of accidental hash collision |
|
307 |
are negligible for projects that could be handled by the human race. |
|
308 |
The known weaknesses in SHA1 are currently still not practical to |
|
309 |
attack, and Mercurial will switch to SHA256 hashing before that |
|
310 |
becomes a realistic concern. |
|
311 |
||
312 |
Collisions with the "short hashes" are not a concern as they're always |
|
313 |
checked for ambiguity and are still long enough that they're not |
|
314 |
likely to happen for reasonably-sized projects (< 1M changes). |
|
455 | 315 |
|
316 |
||
317 |