Mercurial > hg > mercurial-crew-with-dirclash
comparison doc/FAQ.txt @ 446:8cc0ee3f18fb
The beginnings of a FAQ file
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
The beginnings of a FAQ file
manifest hash: 234ee7d9fb5cd3b0bd794e615a74f96a4cc234e0
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.0 (GNU/Linux)
iD8DBQFCuy48ywK+sNU5EO8RAmdYAJ923bFC/a6q28nVYumWsaQ+axlKawCfS7IC
kh1xVlj5OYOloicyaHDhLU4=
=7CJ2
-----END PGP SIGNATURE-----
author | mpm@selenic.com |
---|---|
date | Thu, 23 Jun 2005 13:48:44 -0800 |
parents | |
children | df83b2c306ac |
comparison
equal
deleted
inserted
replaced
445:fe48ffa3665f | 446:8cc0ee3f18fb |
---|---|
1 Mercurial Frequently Asked Questions | |
2 | |
3 Section 1: General Usage | |
4 ------------------------ | |
5 | |
6 Q. I did an 'hg pull' and my working directory is empty! | |
7 | |
8 There are two parts to Mercurial: the repository and the working | |
9 directory. 'hg pull' pulls all new changes from a remote repository | |
10 into the local one but doesn't alter the working directory. | |
11 | |
12 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 to manage merging more easily (see below about best practices). | |
15 | |
16 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 pull -u'. This will refuse to merge or overwrite local changes. | |
19 | |
20 | |
21 Q. What is the difference between revision numbers, changeset IDs, | |
22 and tags? | |
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 | |
49 Q. What are branches, heads, and the tip? | |
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 | |
59 easy. Simply run 'hg pull' and 'hg update -m' and commit the result. | |
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 | |
64 heads. Use 'hg heads' to find the heads in the current repository. | |
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 | |
75 Q. How does merging work? | |
76 | |
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 | |
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 | |
102 Q. How do tags work in Mercurial? | |
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 | |
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 | |
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 | |
124 Q. How do tags work with multiple heads? | |
125 | |
126 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 | |
129 | |
130 Q. What are some best practices for distributed development with Mercurial? | |
131 | |
132 First, merge often! This makes merging easier for everyone and you | |
133 find out about conflicts (which are often rooted in incompatible | |
134 design decisions) earlier. | |
135 | |
136 Second, don't hesitate to use multiple trees locally. Mercurial makes | |
137 this fast and light-weight. Typical usage is to have an incoming tree, | |
138 an outgoing tree, and a separate tree for each area being worked on. | |
139 | |
140 The incoming tree is best maintained as a pristine copy of the | |
141 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 as you won't be changing them. | |
144 | |
145 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 push' to push it to another publicly availabe repository. | |
148 | |
149 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 satisfied with your feature, pull the changes into your outgoing tree. | |
152 | |
153 | |
154 Q. How do I import from a repository created in a different SCM? | |
155 | |
156 Take a look at contrib/convert-repo. This is an extensible | |
157 framework for converting between repository types. | |
158 | |
159 | |
160 Q. What about Windows support? | |
161 | |
162 Patches to support Windows are being actively integrated, a fully | |
163 working Windows version is probably not far off | |
164 | |
165 | |
166 Section 2: Technical | |
167 -------------------- | |
168 | |
169 Q. What limits does Mercurial have? | |
170 | |
171 Mercurial currently assumes that single files, indices, and manifests | |
172 can fit in memory for efficiency. | |
173 | |
174 Offsets in revlogs are currently tracked with 32 bits, so a revlog for | |
175 a single file can currently not grow beyond 4G. | |
176 | |
177 There should otherwise be no limits on file name length, file size, | |
178 file contents, number of files, or number of revisions. | |
179 | |
180 The network protocol is big-endian. | |
181 | |
182 File names cannot contain the null character. Committer addresses | |
183 cannot contain newlines. | |
184 | |
185 Mercurial is primarily developed for UNIX systems, so some UNIXisms | |
186 may be present in ports. | |
187 | |
188 | |
189 Q. How does signing work? | |
190 | |
191 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 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 project to that point. | |
196 | |
197 More precisely: each file hash is an SHA1 hash of the contents of that | |
198 file and the hashes of its parent revisions. The manifest contains a | |
199 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 the hashes of the parent revisions. | |
202 | |
203 | |
204 Q. What about hash collisions? What about weaknesses in SHA1? | |
205 | |
206 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 The known weaknesses in SHA1 are currently still not practical to | |
209 attack, and Mercurial will switch to SHA256 hashing before that | |
210 becomes a realistic concern. | |
211 | |
212 Collisions with the "short hashes" are not a concern as they're always | |
213 checked for ambiguity and are still long enough that they're not | |
214 likely to happen for reasonably-sized projects (< 1M changes). |