Mercurial > hg
comparison doc/FAQ.txt @ 449:df83b2c306ac
Cleaned up some asciidoc bits in the FAQ
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Cleaned up some asciidoc bits in the FAQ
manifest hash: d21d57210696587dbb6a30a711f77612ed20f40e
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.0 (GNU/Linux)
iD8DBQFCuzPpywK+sNU5EO8RAm6JAJ4kgJKyU2v0e/TL3elPWt+8IiN+2wCeKwVa
iaJSNgsrzdNmNhhlzaQ267c=
=A8Xr
-----END PGP SIGNATURE-----
author | mpm@selenic.com |
---|---|
date | Thu, 23 Jun 2005 14:12:57 -0800 |
parents | 8cc0ee3f18fb |
children | 8d43dfdfb514 |
comparison
equal
deleted
inserted
replaced
448:20fc66131bc0 | 449:df83b2c306ac |
---|---|
1 Mercurial Frequently Asked Questions | 1 Mercurial Frequently Asked Questions |
2 ==================================== | |
2 | 3 |
3 Section 1: General Usage | 4 Section 1: General Usage |
4 ------------------------ | 5 ------------------------ |
5 | 6 |
6 Q. I did an 'hg pull' and my working directory is empty! | 7 .Q. I did an "hg pull" and my working directory is empty! |
7 | 8 |
8 There are two parts to Mercurial: the repository and the working | 9 There are two parts to Mercurial: the repository and the working |
9 directory. 'hg pull' pulls all new changes from a remote repository | 10 directory. "hg pull" pulls all new changes from a remote repository |
10 into the local one but doesn't alter the working directory. | 11 into the local one but doesn't alter the working directory. |
11 | 12 |
12 This keeps you from upsetting your work in progress, which may not be | 13 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 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 to manage merging more easily (see below about best practices). |
15 | 16 |
16 To update your working directory, run 'hg update'. If you're sure you | 17 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 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 pull -u". This will refuse to merge or overwrite local changes. |
19 | 20 |
20 | 21 |
21 Q. What is the difference between revision numbers, changeset IDs, | 22 .Q. What are revision numbers, changeset IDs, and tags? |
22 and tags? | |
23 | 23 |
24 Mercurial will generally allow you to refer to a revision in three | 24 Mercurial will generally allow you to refer to a revision in three |
25 ways: by revision number, by changeset ID, and by tag. | 25 ways: by revision number, by changeset ID, and by tag. |
26 | 26 |
27 A revision number is a simple decimal number that corresponds with the | 27 A revision number is a simple decimal number that corresponds with the |
44 Finally, a tag is an arbitrary string that has been assigned a | 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 | 45 correspondence to a changeset ID. This lets you refer to revisions |
46 symbolically. | 46 symbolically. |
47 | 47 |
48 | 48 |
49 Q. What are branches, heads, and the tip? | 49 .Q. What are branches, heads, and the tip? |
50 | 50 |
51 The central concept of Mercurial is branching. A 'branch' is simply | 51 The central concept of Mercurial is branching. A 'branch' is simply |
52 an independent line of development. In most other version control | 52 an independent line of development. In most other version control |
53 systems, all users generally commit to the same line of development | 53 systems, all users generally commit to the same line of development |
54 called 'the trunk' or 'the main branch'. In Mercurial, every developer | 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 | 55 effectively works on a private branch and there is no internal concept |
56 of 'the main branch'. | 56 of 'the main branch'. |
57 | 57 |
58 Thus Mercurial works hard to make repeated merging between branches | 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. | 59 easy. Simply run "hg pull" and "hg update -m" and commit the result. |
60 | 60 |
61 'Heads' are simply the most recent commits on a branch. Technically, | 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 | 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 | 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. | 64 heads. Use "hg heads" to find the heads in the current repository. |
65 | 65 |
66 The 'tip' is the most recently changed head, and also the highest | 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 | 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 | 68 the head. Alternately, if you have just pulled from another |
69 repository, the tip of that repository becomes the current tip. | 69 repository, the tip of that repository becomes the current tip. |
70 | 70 |
71 The 'tip' is the default revision for many commands such as update, | 71 The 'tip' is the default revision for many commands such as update, |
72 and also functions as a special symbolic tag. | 72 and also functions as a special symbolic tag. |
73 | 73 |
74 | 74 |
75 Q. How does merging work? | 75 .Q. How does merging work? |
76 | 76 |
77 The merge process is simple. Usually you will want to merge the tip | 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 | 78 into your working directory. Thus you run "hg update -m" and Mercurial |
79 will incorporate the changes from tip into your local changes. | 79 will incorporate the changes from tip into your local changes. |
80 | 80 |
81 The first step of this process is tracing back through the history of | 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 | 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 | 83 are being merged. This is done on a project-wide and a file by file |
97 allow you to perform another merge until you've done this commit as | 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 | 98 that would lose important history that will be needed for future |
99 merges. | 99 merges. |
100 | 100 |
101 | 101 |
102 Q. How do tags work in Mercurial? | 102 .Q. How do tags work in Mercurial? |
103 | 103 |
104 Tags work slightly differently in Mercurial than most revision | 104 Tags work slightly differently in Mercurial than most revision |
105 systems. The design attempts to meet the following requirements: | 105 systems. The design attempts to meet the following requirements: |
106 | 106 |
107 - be version controlled and mergeable just like any other file | 107 - be version controlled and mergeable just like any other file |
110 - allow changing tags in the future | 110 - allow changing tags in the future |
111 | 111 |
112 Thus Mercurial stores tags as a file in the working dir. This file is | 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 | 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 | 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' | 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 | 116 command will do this for you and "hg tags" will show the currently |
117 effective tags. | 117 effective tags. |
118 | 118 |
119 Note that because tags refer to changeset IDs and the changeset ID is | 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 | 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 | 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. | 122 a tag. Thus tagging a revision must be done as a second step. |
123 | 123 |
124 Q. How do tags work with multiple heads? | 124 |
125 .Q. How do tags work with multiple heads? | |
125 | 126 |
126 The tags that are in effect at any given time are the tags specified | 127 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 in each head, with heads closer to the tip taking precedence. |
128 | 129 |
129 | 130 |
130 Q. What are some best practices for distributed development with Mercurial? | 131 .Q. What are some best practices for distributed development with Mercurial? |
131 | 132 |
132 First, merge often! This makes merging easier for everyone and you | 133 First, merge often! This makes merging easier for everyone and you |
133 find out about conflicts (which are often rooted in incompatible | 134 find out about conflicts (which are often rooted in incompatible |
134 design decisions) earlier. | 135 design decisions) earlier. |
135 | 136 |
141 upstream repository. This works as a cache so that you don't have to | 142 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 pull multiple copies over the network. No need to check files out here |
143 as you won't be changing them. | 144 as you won't be changing them. |
144 | 145 |
145 The outgoing tree contains all the changes you intend for merger into | 146 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 upsteam. Publish this tree with 'hg serve" or hgweb.cgi or use 'hg |
147 push' to push it to another publicly availabe repository. | 148 push" to push it to another publicly availabe repository. |
148 | 149 |
149 Then, for each feature you work on, create a new tree. Commit early | 150 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 and commit often, merge with incoming regularly, and once you're |
151 satisfied with your feature, pull the changes into your outgoing tree. | 152 satisfied with your feature, pull the changes into your outgoing tree. |
152 | 153 |
153 | 154 |
154 Q. How do I import from a repository created in a different SCM? | 155 .Q. How do I import from a repository created in a different SCM? |
155 | 156 |
156 Take a look at contrib/convert-repo. This is an extensible | 157 Take a look at contrib/convert-repo. This is an extensible |
157 framework for converting between repository types. | 158 framework for converting between repository types. |
158 | 159 |
159 | 160 |
160 Q. What about Windows support? | 161 .Q. What about Windows support? |
161 | 162 |
162 Patches to support Windows are being actively integrated, a fully | 163 Patches to support Windows are being actively integrated, a fully |
163 working Windows version is probably not far off | 164 working Windows version is probably not far off |
164 | 165 |
165 | 166 |
166 Section 2: Technical | 167 Section 2: Technical |
167 -------------------- | 168 -------------------- |
168 | 169 |
169 Q. What limits does Mercurial have? | 170 .Q. What limits does Mercurial have? |
170 | 171 |
171 Mercurial currently assumes that single files, indices, and manifests | 172 Mercurial currently assumes that single files, indices, and manifests |
172 can fit in memory for efficiency. | 173 can fit in memory for efficiency. |
173 | 174 |
174 Offsets in revlogs are currently tracked with 32 bits, so a revlog for | 175 Offsets in revlogs are currently tracked with 32 bits, so a revlog for |
184 | 185 |
185 Mercurial is primarily developed for UNIX systems, so some UNIXisms | 186 Mercurial is primarily developed for UNIX systems, so some UNIXisms |
186 may be present in ports. | 187 may be present in ports. |
187 | 188 |
188 | 189 |
189 Q. How does signing work? | 190 .Q. How does signing work? |
190 | 191 |
191 Take a look at the hgeditor script for an example. The basic idea | 192 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 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 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 complete history, and thus signing the manifest hash signs the entire |
199 list of each file in the project along with its current file hash. | 200 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 This manifest is hashed similarly to the file hashes, incorporating |
201 the hashes of the parent revisions. | 202 the hashes of the parent revisions. |
202 | 203 |
203 | 204 |
204 Q. What about hash collisions? What about weaknesses in SHA1? | 205 .Q. What about hash collisions? What about weaknesses in SHA1? |
205 | 206 |
206 The SHA1 hashes are large enough that the odds of accidental hash collision | 207 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 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 The known weaknesses in SHA1 are currently still not practical to |
209 attack, and Mercurial will switch to SHA256 hashing before that | 210 attack, and Mercurial will switch to SHA256 hashing before that |