Mercurial > hg > mercurial-crew-with-dirclash
annotate doc/FAQ.txt @ 684:4ccf3de52989 0.6b
Turn off signing with hgeditor by default
manifest hash: f2732475351ee22d78e0dab629db03f1f215b21f
| author | Matt Mackall <mpm@selenic.com> |
|---|---|
| date | Mon, 11 Jul 2005 21:56:29 -0800 |
| parents | a287f6cd9c6b |
| children | 7dae73778114 c6b912f8b5b2 |
| 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 | |
| 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 | |
|
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 | |
| 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 |