Mercurial > hg > mercurial-crew-with-dirclash

comparison doc/FAQ.txt @ 449:df83b2c306ac

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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