Mercurial > hg > mercurial-crew-with-dirclash
annotate doc/FAQ.txt @ 870:a82eae840447
Teach walk code about absolute paths.
The first consequence of this is that absolute and relative paths now
all work in the same way. The second is that paths that lie outside
the repository now cause an error to be reported, instead of something
arbitrary and expensive being done.
Internally, all of the serious work is in the util package. The new
canonpath function takes an arbitrary path and either returns a
canonical path or raises an error. Because it needs to know where the
repository root is, it must be fed a repository or dirstate object, which
has given commands.matchpats and friends a new parameter to pass along.
The util.matcher function uses this to canonicalise globs and relative
path names.
Meanwhile, I've moved the Abort exception from commands to util, and
killed off the redundant util.CommandError exception.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Sun, 07 Aug 2005 12:43:11 -0800 |
parents | d2422f10c136 |
children |
rev | line source |
---|---|
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 |