|
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
|
|
|
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
|
|
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
|
|
|
127 You can add a section called "[tags]" to your .hg/hgrc which contains
|
|
|
128 a list of tag = changeset ID pairs. Unlike traditional tags, these are
|
|
|
129 only visible in the local repository, but otherwise act just like
|
|
|
130 normal tags.
|
|
|
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
|
|
|
155 The outgoing tree contains all the changes you intend for merger 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
|
|
|
199 certainly features it is missing and you can give up feedback on how
|
|
|
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
|
|
|
259 manifest and reconstruction 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
|
