| rev |
line source |
|
bos@559
|
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
|
|
bos@559
|
2
|
|
bos@559
|
3 <chapter id="chap:concepts">
|
|
bos@559
|
4 <title>Behind the scenes</title>
|
|
bos@559
|
5
|
|
bos@559
|
6 <para>Unlike many revision control systems, the concepts upon which
|
|
bos@559
|
7 Mercurial is built are simple enough that it's easy to understand
|
|
bos@559
|
8 how the software really works. Knowing this certainly isn't
|
|
bos@559
|
9 necessary, but I find it useful to have a <quote>mental
|
|
bos@559
|
10 model</quote> of what's going on.</para>
|
|
bos@559
|
11
|
|
bos@559
|
12 <para>This understanding gives me confidence that Mercurial has been
|
|
bos@559
|
13 carefully designed to be both <emphasis>safe</emphasis> and
|
|
bos@559
|
14 <emphasis>efficient</emphasis>. And just as importantly, if it's
|
|
bos@559
|
15 easy for me to retain a good idea of what the software is doing
|
|
bos@559
|
16 when I perform a revision control task, I'm less likely to be
|
|
bos@559
|
17 surprised by its behaviour.</para>
|
|
bos@559
|
18
|
|
bos@559
|
19 <para>In this chapter, we'll initially cover the core concepts
|
|
bos@559
|
20 behind Mercurial's design, then continue to discuss some of the
|
|
bos@559
|
21 interesting details of its implementation.</para>
|
|
bos@559
|
22
|
|
bos@559
|
23 <sect1>
|
|
bos@559
|
24 <title>Mercurial's historical record</title>
|
|
bos@559
|
25
|
|
bos@559
|
26 <sect2>
|
|
bos@559
|
27 <title>Tracking the history of a single file</title>
|
|
bos@559
|
28
|
|
bos@559
|
29 <para>When Mercurial tracks modifications to a file, it stores
|
|
bos@559
|
30 the history of that file in a metadata object called a
|
|
bos@559
|
31 <emphasis>filelog</emphasis>. Each entry in the filelog
|
|
bos@559
|
32 contains enough information to reconstruct one revision of the
|
|
bos@559
|
33 file that is being tracked. Filelogs are stored as files in
|
|
bos@559
|
34 the <filename role="special"
|
|
bos@559
|
35 class="directory">.hg/store/data</filename> directory. A
|
|
bos@559
|
36 filelog contains two kinds of information: revision data, and
|
|
bos@559
|
37 an index to help Mercurial to find a revision
|
|
bos@559
|
38 efficiently.</para>
|
|
bos@559
|
39
|
|
bos@559
|
40 <para>A file that is large, or has a lot of history, has its
|
|
bos@559
|
41 filelog stored in separate data
|
|
bos@559
|
42 (<quote><literal>.d</literal></quote> suffix) and index
|
|
bos@559
|
43 (<quote><literal>.i</literal></quote> suffix) files. For
|
|
bos@559
|
44 small files without much history, the revision data and index
|
|
bos@559
|
45 are combined in a single <quote><literal>.i</literal></quote>
|
|
bos@559
|
46 file. The correspondence between a file in the working
|
|
bos@559
|
47 directory and the filelog that tracks its history in the
|
|
bos@559
|
48 repository is illustrated in figure <xref
|
|
bos@559
|
49 linkend="fig:concepts:filelog"/>.</para>
|
|
bos@559
|
50
|
|
bos@559
|
51 <informalfigure id="fig:concepts:filelog">
|
|
bos@559
|
52 <mediaobject><imageobject><imagedata
|
|
bos@559
|
53 fileref="filelog"/></imageobject><textobject><phrase>XXX
|
|
bos@559
|
54 add text</phrase></textobject>
|
|
bos@559
|
55 <caption><para>Relationships between files in working
|
|
bos@559
|
56 directory and filelogs in
|
|
bos@559
|
57 repository</para></caption></mediaobject>
|
|
bos@559
|
58 </informalfigure>
|
|
bos@559
|
59
|
|
bos@559
|
60 </sect2>
|
|
bos@559
|
61 <sect2>
|
|
bos@559
|
62 <title>Managing tracked files</title>
|
|
bos@559
|
63
|
|
bos@559
|
64 <para>Mercurial uses a structure called a
|
|
bos@559
|
65 <emphasis>manifest</emphasis> to collect together information
|
|
bos@559
|
66 about the files that it tracks. Each entry in the manifest
|
|
bos@559
|
67 contains information about the files present in a single
|
|
bos@559
|
68 changeset. An entry records which files are present in the
|
|
bos@559
|
69 changeset, the revision of each file, and a few other pieces
|
|
bos@559
|
70 of file metadata.</para>
|
|
bos@559
|
71
|
|
bos@559
|
72 </sect2>
|
|
bos@559
|
73 <sect2>
|
|
bos@559
|
74 <title>Recording changeset information</title>
|
|
bos@559
|
75
|
|
bos@559
|
76 <para>The <emphasis>changelog</emphasis> contains information
|
|
bos@559
|
77 about each changeset. Each revision records who committed a
|
|
bos@559
|
78 change, the changeset comment, other pieces of
|
|
bos@559
|
79 changeset-related information, and the revision of the
|
|
bos@559
|
80 manifest to use.</para>
|
|
bos@559
|
81
|
|
bos@559
|
82 </sect2>
|
|
bos@559
|
83 <sect2>
|
|
bos@559
|
84 <title>Relationships between revisions</title>
|
|
bos@559
|
85
|
|
bos@559
|
86 <para>Within a changelog, a manifest, or a filelog, each
|
|
bos@559
|
87 revision stores a pointer to its immediate parent (or to its
|
|
bos@559
|
88 two parents, if it's a merge revision). As I mentioned above,
|
|
bos@559
|
89 there are also relationships between revisions
|
|
bos@559
|
90 <emphasis>across</emphasis> these structures, and they are
|
|
bos@559
|
91 hierarchical in nature.</para>
|
|
bos@559
|
92
|
|
bos@559
|
93 <para>For every changeset in a repository, there is exactly one
|
|
bos@559
|
94 revision stored in the changelog. Each revision of the
|
|
bos@559
|
95 changelog contains a pointer to a single revision of the
|
|
bos@559
|
96 manifest. A revision of the manifest stores a pointer to a
|
|
bos@559
|
97 single revision of each filelog tracked when that changeset
|
|
bos@559
|
98 was created. These relationships are illustrated in figure
|
|
bos@559
|
99 <xref linkend="fig:concepts:metadata"/>.</para>
|
|
bos@559
|
100
|
|
bos@559
|
101 <informalfigure id="fig:concepts:metadata">
|
|
bos@559
|
102 <mediaobject><imageobject><imagedata
|
|
bos@559
|
103 fileref="metadata"/></imageobject><textobject><phrase>XXX
|
|
bos@559
|
104 add text</phrase></textobject><caption><para>Metadata
|
|
bos@559
|
105 relationships</para></caption>
|
|
bos@559
|
106 </mediaobject>
|
|
bos@559
|
107 </informalfigure>
|
|
bos@559
|
108
|
|
bos@559
|
109 <para>As the illustration shows, there is
|
|
bos@559
|
110 <emphasis>not</emphasis> a <quote>one to one</quote>
|
|
bos@559
|
111 relationship between revisions in the changelog, manifest, or
|
|
bos@559
|
112 filelog. If the manifest hasn't changed between two
|
|
bos@559
|
113 changesets, the changelog entries for those changesets will
|
|
bos@559
|
114 point to the same revision of the manifest. If a file that
|
|
bos@559
|
115 Mercurial tracks hasn't changed between two changesets, the
|
|
bos@559
|
116 entry for that file in the two revisions of the manifest will
|
|
bos@559
|
117 point to the same revision of its filelog.</para>
|
|
bos@559
|
118
|
|
bos@559
|
119 </sect2>
|
|
bos@559
|
120 </sect1>
|
|
bos@559
|
121 <sect1>
|
|
bos@559
|
122 <title>Safe, efficient storage</title>
|
|
bos@559
|
123
|
|
bos@559
|
124 <para>The underpinnings of changelogs, manifests, and filelogs are
|
|
bos@559
|
125 provided by a single structure called the
|
|
bos@559
|
126 <emphasis>revlog</emphasis>.</para>
|
|
bos@559
|
127
|
|
bos@559
|
128 <sect2>
|
|
bos@559
|
129 <title>Efficient storage</title>
|
|
bos@559
|
130
|
|
bos@559
|
131 <para>The revlog provides efficient storage of revisions using a
|
|
bos@559
|
132 <emphasis>delta</emphasis> mechanism. Instead of storing a
|
|
bos@559
|
133 complete copy of a file for each revision, it stores the
|
|
bos@559
|
134 changes needed to transform an older revision into the new
|
|
bos@559
|
135 revision. For many kinds of file data, these deltas are
|
|
bos@559
|
136 typically a fraction of a percent of the size of a full copy
|
|
bos@559
|
137 of a file.</para>
|
|
bos@559
|
138
|
|
bos@559
|
139 <para>Some obsolete revision control systems can only work with
|
|
bos@559
|
140 deltas of text files. They must either store binary files as
|
|
bos@559
|
141 complete snapshots or encoded into a text representation, both
|
|
bos@559
|
142 of which are wasteful approaches. Mercurial can efficiently
|
|
bos@559
|
143 handle deltas of files with arbitrary binary contents; it
|
|
bos@559
|
144 doesn't need to treat text as special.</para>
|
|
bos@559
|
145
|
|
bos@559
|
146 </sect2>
|
|
bos@559
|
147 <sect2 id="sec:concepts:txn">
|
|
bos@559
|
148 <title>Safe operation</title>
|
|
bos@559
|
149
|
|
bos@559
|
150 <para>Mercurial only ever <emphasis>appends</emphasis> data to
|
|
bos@559
|
151 the end of a revlog file. It never modifies a section of a
|
|
bos@559
|
152 file after it has written it. This is both more robust and
|
|
bos@559
|
153 efficient than schemes that need to modify or rewrite
|
|
bos@559
|
154 data.</para>
|
|
bos@559
|
155
|
|
bos@559
|
156 <para>In addition, Mercurial treats every write as part of a
|
|
bos@559
|
157 <emphasis>transaction</emphasis> that can span a number of
|
|
bos@559
|
158 files. A transaction is <emphasis>atomic</emphasis>: either
|
|
bos@559
|
159 the entire transaction succeeds and its effects are all
|
|
bos@559
|
160 visible to readers in one go, or the whole thing is undone.
|
|
bos@559
|
161 This guarantee of atomicity means that if you're running two
|
|
bos@559
|
162 copies of Mercurial, where one is reading data and one is
|
|
bos@559
|
163 writing it, the reader will never see a partially written
|
|
bos@559
|
164 result that might confuse it.</para>
|
|
bos@559
|
165
|
|
bos@559
|
166 <para>The fact that Mercurial only appends to files makes it
|
|
bos@559
|
167 easier to provide this transactional guarantee. The easier it
|
|
bos@559
|
168 is to do stuff like this, the more confident you should be
|
|
bos@559
|
169 that it's done correctly.</para>
|
|
bos@559
|
170
|
|
bos@559
|
171 </sect2>
|
|
bos@559
|
172 <sect2>
|
|
bos@559
|
173 <title>Fast retrieval</title>
|
|
bos@559
|
174
|
|
bos@559
|
175 <para>Mercurial cleverly avoids a pitfall common to all earlier
|
|
bos@559
|
176 revision control systems: the problem of <emphasis>inefficient
|
|
bos@559
|
177 retrieval</emphasis>. Most revision control systems store
|
|
bos@559
|
178 the contents of a revision as an incremental series of
|
|
bos@559
|
179 modifications against a <quote>snapshot</quote>. To
|
|
bos@559
|
180 reconstruct a specific revision, you must first read the
|
|
bos@559
|
181 snapshot, and then every one of the revisions between the
|
|
bos@559
|
182 snapshot and your target revision. The more history that a
|
|
bos@559
|
183 file accumulates, the more revisions you must read, hence the
|
|
bos@559
|
184 longer it takes to reconstruct a particular revision.</para>
|
|
bos@559
|
185
|
|
bos@559
|
186 <informalfigure id="fig:concepts:snapshot">
|
|
bos@559
|
187 <mediaobject><imageobject><imagedata
|
|
bos@559
|
188 fileref="snapshot"/></imageobject><textobject><phrase>XXX
|
|
bos@559
|
189 add text</phrase></textobject><caption><para>Snapshot of
|
|
bos@559
|
190 a revlog, with incremental
|
|
bos@559
|
191 deltas</para></caption></mediaobject>
|
|
bos@559
|
192 </informalfigure>
|
|
bos@559
|
193
|
|
bos@559
|
194 <para>The innovation that Mercurial applies to this problem is
|
|
bos@559
|
195 simple but effective. Once the cumulative amount of delta
|
|
bos@559
|
196 information stored since the last snapshot exceeds a fixed
|
|
bos@559
|
197 threshold, it stores a new snapshot (compressed, of course),
|
|
bos@559
|
198 instead of another delta. This makes it possible to
|
|
bos@559
|
199 reconstruct <emphasis>any</emphasis> revision of a file
|
|
bos@559
|
200 quickly. This approach works so well that it has since been
|
|
bos@559
|
201 copied by several other revision control systems.</para>
|
|
bos@559
|
202
|
|
bos@559
|
203 <para>Figure <xref linkend="fig:concepts:snapshot"/> illustrates
|
|
bos@559
|
204 the idea. In an entry in a revlog's index file, Mercurial
|
|
bos@559
|
205 stores the range of entries from the data file that it must
|
|
bos@559
|
206 read to reconstruct a particular revision.</para>
|
|
bos@559
|
207
|
|
bos@559
|
208 <sect3>
|
|
bos@559
|
209 <title>Aside: the influence of video compression</title>
|
|
bos@559
|
210
|
|
bos@559
|
211 <para>If you're familiar with video compression or have ever
|
|
bos@559
|
212 watched a TV feed through a digital cable or satellite
|
|
bos@559
|
213 service, you may know that most video compression schemes
|
|
bos@559
|
214 store each frame of video as a delta against its predecessor
|
|
bos@559
|
215 frame. In addition, these schemes use <quote>lossy</quote>
|
|
bos@559
|
216 compression techniques to increase the compression ratio, so
|
|
bos@559
|
217 visual errors accumulate over the course of a number of
|
|
bos@559
|
218 inter-frame deltas.</para>
|
|
bos@559
|
219
|
|
bos@559
|
220 <para>Because it's possible for a video stream to <quote>drop
|
|
bos@559
|
221 out</quote> occasionally due to signal glitches, and to
|
|
bos@559
|
222 limit the accumulation of artefacts introduced by the lossy
|
|
bos@559
|
223 compression process, video encoders periodically insert a
|
|
bos@559
|
224 complete frame (called a <quote>key frame</quote>) into the
|
|
bos@559
|
225 video stream; the next delta is generated against that
|
|
bos@559
|
226 frame. This means that if the video signal gets
|
|
bos@559
|
227 interrupted, it will resume once the next key frame is
|
|
bos@559
|
228 received. Also, the accumulation of encoding errors
|
|
bos@559
|
229 restarts anew with each key frame.</para>
|
|
bos@559
|
230
|
|
bos@559
|
231 </sect3>
|
|
bos@559
|
232 </sect2>
|
|
bos@559
|
233 <sect2>
|
|
bos@559
|
234 <title>Identification and strong integrity</title>
|
|
bos@559
|
235
|
|
bos@559
|
236 <para>Along with delta or snapshot information, a revlog entry
|
|
bos@559
|
237 contains a cryptographic hash of the data that it represents.
|
|
bos@559
|
238 This makes it difficult to forge the contents of a revision,
|
|
bos@559
|
239 and easy to detect accidental corruption.</para>
|
|
bos@559
|
240
|
|
bos@559
|
241 <para>Hashes provide more than a mere check against corruption;
|
|
bos@559
|
242 they are used as the identifiers for revisions. The changeset
|
|
bos@559
|
243 identification hashes that you see as an end user are from
|
|
bos@559
|
244 revisions of the changelog. Although filelogs and the
|
|
bos@559
|
245 manifest also use hashes, Mercurial only uses these behind the
|
|
bos@559
|
246 scenes.</para>
|
|
bos@559
|
247
|
|
bos@559
|
248 <para>Mercurial verifies that hashes are correct when it
|
|
bos@559
|
249 retrieves file revisions and when it pulls changes from
|
|
bos@559
|
250 another repository. If it encounters an integrity problem, it
|
|
bos@559
|
251 will complain and stop whatever it's doing.</para>
|
|
bos@559
|
252
|
|
bos@559
|
253 <para>In addition to the effect it has on retrieval efficiency,
|
|
bos@559
|
254 Mercurial's use of periodic snapshots makes it more robust
|
|
bos@559
|
255 against partial data corruption. If a revlog becomes partly
|
|
bos@559
|
256 corrupted due to a hardware error or system bug, it's often
|
|
bos@559
|
257 possible to reconstruct some or most revisions from the
|
|
bos@559
|
258 uncorrupted sections of the revlog, both before and after the
|
|
bos@559
|
259 corrupted section. This would not be possible with a
|
|
bos@559
|
260 delta-only storage model.</para>
|
|
bos@559
|
261
|
|
bos@559
|
262 </sect2>
|
|
bos@559
|
263 </sect1>
|
|
bos@559
|
264 <sect1>
|
|
bos@559
|
265 <title>Revision history, branching, and merging</title>
|
|
bos@559
|
266
|
|
bos@559
|
267 <para>Every entry in a Mercurial revlog knows the identity of its
|
|
bos@559
|
268 immediate ancestor revision, usually referred to as its
|
|
bos@559
|
269 <emphasis>parent</emphasis>. In fact, a revision contains room
|
|
bos@559
|
270 for not one parent, but two. Mercurial uses a special hash,
|
|
bos@559
|
271 called the <quote>null ID</quote>, to represent the idea
|
|
bos@559
|
272 <quote>there is no parent here</quote>. This hash is simply a
|
|
bos@559
|
273 string of zeroes.</para>
|
|
bos@559
|
274
|
|
bos@559
|
275 <para>In figure <xref linkend="fig:concepts:revlog"/>, you can see
|
|
bos@559
|
276 an example of the conceptual structure of a revlog. Filelogs,
|
|
bos@559
|
277 manifests, and changelogs all have this same structure; they
|
|
bos@559
|
278 differ only in the kind of data stored in each delta or
|
|
bos@559
|
279 snapshot.</para>
|
|
bos@559
|
280
|
|
bos@559
|
281 <para>The first revision in a revlog (at the bottom of the image)
|
|
bos@559
|
282 has the null ID in both of its parent slots. For a
|
|
bos@559
|
283 <quote>normal</quote> revision, its first parent slot contains
|
|
bos@559
|
284 the ID of its parent revision, and its second contains the null
|
|
bos@559
|
285 ID, indicating that the revision has only one real parent. Any
|
|
bos@559
|
286 two revisions that have the same parent ID are branches. A
|
|
bos@559
|
287 revision that represents a merge between branches has two normal
|
|
bos@559
|
288 revision IDs in its parent slots.</para>
|
|
bos@559
|
289
|
|
bos@559
|
290 <informalfigure id="fig:concepts:revlog">
|
|
bos@559
|
291 <mediaobject><imageobject><imagedata
|
|
bos@559
|
292 fileref="revlog"/></imageobject><textobject><phrase>XXX
|
|
bos@559
|
293 add text</phrase></textobject></mediaobject>
|
|
bos@559
|
294 </informalfigure>
|
|
bos@559
|
295
|
|
bos@559
|
296 </sect1>
|
|
bos@559
|
297 <sect1>
|
|
bos@559
|
298 <title>The working directory</title>
|
|
bos@559
|
299
|
|
bos@559
|
300 <para>In the working directory, Mercurial stores a snapshot of the
|
|
bos@559
|
301 files from the repository as of a particular changeset.</para>
|
|
bos@559
|
302
|
|
bos@559
|
303 <para>The working directory <quote>knows</quote> which changeset
|
|
bos@559
|
304 it contains. When you update the working directory to contain a
|
|
bos@559
|
305 particular changeset, Mercurial looks up the appropriate
|
|
bos@559
|
306 revision of the manifest to find out which files it was tracking
|
|
bos@559
|
307 at the time that changeset was committed, and which revision of
|
|
bos@559
|
308 each file was then current. It then recreates a copy of each of
|
|
bos@559
|
309 those files, with the same contents it had when the changeset
|
|
bos@559
|
310 was committed.</para>
|
|
bos@559
|
311
|
|
bos@559
|
312 <para>The <emphasis>dirstate</emphasis> contains Mercurial's
|
|
bos@559
|
313 knowledge of the working directory. This details which
|
|
bos@559
|
314 changeset the working directory is updated to, and all of the
|
|
bos@559
|
315 files that Mercurial is tracking in the working
|
|
bos@559
|
316 directory.</para>
|
|
bos@559
|
317
|
|
bos@559
|
318 <para>Just as a revision of a revlog has room for two parents, so
|
|
bos@559
|
319 that it can represent either a normal revision (with one parent)
|
|
bos@559
|
320 or a merge of two earlier revisions, the dirstate has slots for
|
|
bos@559
|
321 two parents. When you use the <command role="hg-cmd">hg
|
|
bos@559
|
322 update</command> command, the changeset that you update to is
|
|
bos@559
|
323 stored in the <quote>first parent</quote> slot, and the null ID
|
|
bos@559
|
324 in the second. When you <command role="hg-cmd">hg
|
|
bos@559
|
325 merge</command> with another changeset, the first parent
|
|
bos@559
|
326 remains unchanged, and the second parent is filled in with the
|
|
bos@559
|
327 changeset you're merging with. The <command role="hg-cmd">hg
|
|
bos@559
|
328 parents</command> command tells you what the parents of the
|
|
bos@559
|
329 dirstate are.</para>
|
|
bos@559
|
330
|
|
bos@559
|
331 <sect2>
|
|
bos@559
|
332 <title>What happens when you commit</title>
|
|
bos@559
|
333
|
|
bos@559
|
334 <para>The dirstate stores parent information for more than just
|
|
bos@559
|
335 book-keeping purposes. Mercurial uses the parents of the
|
|
bos@559
|
336 dirstate as <emphasis>the parents of a new
|
|
bos@559
|
337 changeset</emphasis> when you perform a commit.</para>
|
|
bos@559
|
338
|
|
bos@559
|
339 <informalfigure id="fig:concepts:wdir">
|
|
bos@559
|
340 <mediaobject><imageobject><imagedata
|
|
bos@559
|
341 fileref="wdir"/></imageobject><textobject><phrase>XXX
|
|
bos@559
|
342 add text</phrase></textobject><caption><para>The working
|
|
bos@559
|
343 directory can have two
|
|
bos@559
|
344 parents</para></caption></mediaobject>
|
|
bos@559
|
345 </informalfigure>
|
|
bos@559
|
346
|
|
bos@559
|
347 <para>Figure <xref linkend="fig:concepts:wdir"/> shows the
|
|
bos@559
|
348 normal state of the working directory, where it has a single
|
|
bos@559
|
349 changeset as parent. That changeset is the
|
|
bos@559
|
350 <emphasis>tip</emphasis>, the newest changeset in the
|
|
bos@559
|
351 repository that has no children.</para>
|
|
bos@559
|
352
|
|
bos@559
|
353 <informalfigure id="fig:concepts:wdir-after-commit">
|
|
bos@559
|
354 <mediaobject><imageobject><imagedata
|
|
bos@559
|
355 fileref="wdir-after-commit"/></imageobject><textobject><phrase>XXX
|
|
bos@559
|
356 add text</phrase></textobject><caption><para>The working
|
|
bos@559
|
357 directory gains new parents after a
|
|
bos@559
|
358 commit</para></caption></mediaobject>
|
|
bos@559
|
359 </informalfigure>
|
|
bos@559
|
360
|
|
bos@559
|
361 <para>It's useful to think of the working directory as
|
|
bos@559
|
362 <quote>the changeset I'm about to commit</quote>. Any files
|
|
bos@559
|
363 that you tell Mercurial that you've added, removed, renamed,
|
|
bos@559
|
364 or copied will be reflected in that changeset, as will
|
|
bos@559
|
365 modifications to any files that Mercurial is already tracking;
|
|
bos@559
|
366 the new changeset will have the parents of the working
|
|
bos@559
|
367 directory as its parents.</para>
|
|
bos@559
|
368
|
|
bos@559
|
369 <para>After a commit, Mercurial will update the parents of the
|
|
bos@559
|
370 working directory, so that the first parent is the ID of the
|
|
bos@559
|
371 new changeset, and the second is the null ID. This is shown
|
|
bos@559
|
372 in figure <xref linkend="fig:concepts:wdir-after-commit"/>.
|
|
bos@559
|
373 Mercurial
|
|
bos@559
|
374 doesn't touch any of the files in the working directory when
|
|
bos@559
|
375 you commit; it just modifies the dirstate to note its new
|
|
bos@559
|
376 parents.</para>
|
|
bos@559
|
377
|
|
bos@559
|
378 </sect2>
|
|
bos@559
|
379 <sect2>
|
|
bos@559
|
380 <title>Creating a new head</title>
|
|
bos@559
|
381
|
|
bos@559
|
382 <para>It's perfectly normal to update the working directory to a
|
|
bos@559
|
383 changeset other than the current tip. For example, you might
|
|
bos@559
|
384 want to know what your project looked like last Tuesday, or
|
|
bos@559
|
385 you could be looking through changesets to see which one
|
|
bos@559
|
386 introduced a bug. In cases like this, the natural thing to do
|
|
bos@559
|
387 is update the working directory to the changeset you're
|
|
bos@559
|
388 interested in, and then examine the files in the working
|
|
bos@559
|
389 directory directly to see their contents as they were when you
|
|
bos@559
|
390 committed that changeset. The effect of this is shown in
|
|
bos@559
|
391 figure <xref linkend="fig:concepts:wdir-pre-branch"/>.</para>
|
|
bos@559
|
392
|
|
bos@559
|
393 <informalfigure id="fig:concepts:wdir-pre-branch">
|
|
bos@559
|
394 <mediaobject><imageobject><imagedata
|
|
bos@559
|
395 fileref="wdir-pre-branch"/></imageobject><textobject><phrase>XXX
|
|
bos@559
|
396 add text</phrase></textobject><caption><para>The working
|
|
bos@559
|
397 directory, updated to an older
|
|
bos@559
|
398 changeset</para></caption></mediaobject>
|
|
bos@559
|
399 </informalfigure>
|
|
bos@559
|
400
|
|
bos@559
|
401 <para>Having updated the working directory to an older
|
|
bos@559
|
402 changeset, what happens if you make some changes, and then
|
|
bos@559
|
403 commit? Mercurial behaves in the same way as I outlined
|
|
bos@559
|
404 above. The parents of the working directory become the
|
|
bos@559
|
405 parents of the new changeset. This new changeset has no
|
|
bos@559
|
406 children, so it becomes the new tip. And the repository now
|
|
bos@559
|
407 contains two changesets that have no children; we call these
|
|
bos@559
|
408 <emphasis>heads</emphasis>. You can see the structure that
|
|
bos@559
|
409 this creates in figure <xref
|
|
bos@559
|
410 linkend="fig:concepts:wdir-branch"/>.</para>
|
|
bos@559
|
411
|
|
bos@559
|
412 <informalfigure id="fig:concepts:wdir-branch">
|
|
bos@559
|
413 <mediaobject><imageobject><imagedata
|
|
bos@559
|
414 fileref="wdir-branch"/></imageobject><textobject><phrase>XXX
|
|
bos@559
|
415 add text</phrase></textobject><caption><para>After a
|
|
bos@559
|
416 commit made while synced to an older
|
|
bos@559
|
417 changeset</para></caption></mediaobject>
|
|
bos@559
|
418 </informalfigure>
|
|
bos@559
|
419
|
|
bos@559
|
420 <note>
|
|
bos@559
|
421 <para> If you're new to Mercurial, you should keep in mind a
|
|
bos@559
|
422 common <quote>error</quote>, which is to use the <command
|
|
bos@559
|
423 role="hg-cmd">hg pull</command> command without any
|
|
bos@559
|
424 options. By default, the <command role="hg-cmd">hg
|
|
bos@559
|
425 pull</command> command <emphasis>does not</emphasis>
|
|
bos@559
|
426 update the working directory, so you'll bring new changesets
|
|
bos@559
|
427 into your repository, but the working directory will stay
|
|
bos@559
|
428 synced at the same changeset as before the pull. If you
|
|
bos@559
|
429 make some changes and commit afterwards, you'll thus create
|
|
bos@559
|
430 a new head, because your working directory isn't synced to
|
|
bos@559
|
431 whatever the current tip is.</para>
|
|
bos@559
|
432
|
|
bos@559
|
433 <para> I put the word <quote>error</quote> in quotes because
|
|
bos@559
|
434 all that you need to do to rectify this situation is
|
|
bos@559
|
435 <command role="hg-cmd">hg merge</command>, then <command
|
|
bos@559
|
436 role="hg-cmd">hg commit</command>. In other words, this
|
|
bos@559
|
437 almost never has negative consequences; it just surprises
|
|
bos@559
|
438 people. I'll discuss other ways to avoid this behaviour,
|
|
bos@559
|
439 and why Mercurial behaves in this initially surprising way,
|
|
bos@559
|
440 later on.</para>
|
|
bos@559
|
441 </note>
|
|
bos@559
|
442
|
|
bos@559
|
443 </sect2>
|
|
bos@559
|
444 <sect2>
|
|
bos@559
|
445 <title>Merging heads</title>
|
|
bos@559
|
446
|
|
bos@559
|
447 <para>When you run the <command role="hg-cmd">hg merge</command>
|
|
bos@559
|
448 command, Mercurial leaves the first parent of the working
|
|
bos@559
|
449 directory unchanged, and sets the second parent to the
|
|
bos@559
|
450 changeset you're merging with, as shown in figure <xref
|
|
bos@559
|
451 linkend="fig:concepts:wdir-merge"/>.</para>
|
|
bos@559
|
452
|
|
bos@559
|
453 <informalfigure id="fig:concepts:wdir-merge">
|
|
bos@559
|
454 <mediaobject><imageobject><imagedata
|
|
bos@559
|
455 fileref="wdir-merge"/></imageobject><textobject><phrase>XXX
|
|
bos@559
|
456 add text</phrase></textobject><caption><para>Merging two
|
|
bos@559
|
457 heads</para></caption></mediaobject>
|
|
bos@559
|
458 </informalfigure>
|
|
bos@559
|
459
|
|
bos@559
|
460 <para>Mercurial also has to modify the working directory, to
|
|
bos@559
|
461 merge the files managed in the two changesets. Simplified a
|
|
bos@559
|
462 little, the merging process goes like this, for every file in
|
|
bos@559
|
463 the manifests of both changesets.</para>
|
|
bos@559
|
464 <itemizedlist>
|
|
bos@559
|
465 <listitem><para>If neither changeset has modified a file, do
|
|
bos@559
|
466 nothing with that file.</para>
|
|
bos@559
|
467 </listitem>
|
|
bos@559
|
468 <listitem><para>If one changeset has modified a file, and the
|
|
bos@559
|
469 other hasn't, create the modified copy of the file in the
|
|
bos@559
|
470 working directory.</para>
|
|
bos@559
|
471 </listitem>
|
|
bos@559
|
472 <listitem><para>If one changeset has removed a file, and the
|
|
bos@559
|
473 other hasn't (or has also deleted it), delete the file
|
|
bos@559
|
474 from the working directory.</para>
|
|
bos@559
|
475 </listitem>
|
|
bos@559
|
476 <listitem><para>If one changeset has removed a file, but the
|
|
bos@559
|
477 other has modified the file, ask the user what to do: keep
|
|
bos@559
|
478 the modified file, or remove it?</para>
|
|
bos@559
|
479 </listitem>
|
|
bos@559
|
480 <listitem><para>If both changesets have modified a file,
|
|
bos@559
|
481 invoke an external merge program to choose the new
|
|
bos@559
|
482 contents for the merged file. This may require input from
|
|
bos@559
|
483 the user.</para>
|
|
bos@559
|
484 </listitem>
|
|
bos@559
|
485 <listitem><para>If one changeset has modified a file, and the
|
|
bos@559
|
486 other has renamed or copied the file, make sure that the
|
|
bos@559
|
487 changes follow the new name of the file.</para>
|
|
bos@559
|
488 </listitem></itemizedlist>
|
|
bos@559
|
489 <para>There are more details&emdash;merging has plenty of corner
|
|
bos@559
|
490 cases&emdash;but these are the most common choices that are
|
|
bos@559
|
491 involved in a merge. As you can see, most cases are
|
|
bos@559
|
492 completely automatic, and indeed most merges finish
|
|
bos@559
|
493 automatically, without requiring your input to resolve any
|
|
bos@559
|
494 conflicts.</para>
|
|
bos@559
|
495
|
|
bos@559
|
496 <para>When you're thinking about what happens when you commit
|
|
bos@559
|
497 after a merge, once again the working directory is <quote>the
|
|
bos@559
|
498 changeset I'm about to commit</quote>. After the <command
|
|
bos@559
|
499 role="hg-cmd">hg merge</command> command completes, the
|
|
bos@559
|
500 working directory has two parents; these will become the
|
|
bos@559
|
501 parents of the new changeset.</para>
|
|
bos@559
|
502
|
|
bos@559
|
503 <para>Mercurial lets you perform multiple merges, but you must
|
|
bos@559
|
504 commit the results of each individual merge as you go. This
|
|
bos@559
|
505 is necessary because Mercurial only tracks two parents for
|
|
bos@559
|
506 both revisions and the working directory. While it would be
|
|
bos@559
|
507 technically possible to merge multiple changesets at once, the
|
|
bos@559
|
508 prospect of user confusion and making a terrible mess of a
|
|
bos@559
|
509 merge immediately becomes overwhelming.</para>
|
|
bos@559
|
510
|
|
bos@559
|
511 </sect2>
|
|
bos@559
|
512 </sect1>
|
|
bos@559
|
513 <sect1>
|
|
bos@559
|
514 <title>Other interesting design features</title>
|
|
bos@559
|
515
|
|
bos@559
|
516 <para>In the sections above, I've tried to highlight some of the
|
|
bos@559
|
517 most important aspects of Mercurial's design, to illustrate that
|
|
bos@559
|
518 it pays careful attention to reliability and performance.
|
|
bos@559
|
519 However, the attention to detail doesn't stop there. There are
|
|
bos@559
|
520 a number of other aspects of Mercurial's construction that I
|
|
bos@559
|
521 personally find interesting. I'll detail a few of them here,
|
|
bos@559
|
522 separate from the <quote>big ticket</quote> items above, so that
|
|
bos@559
|
523 if you're interested, you can gain a better idea of the amount
|
|
bos@559
|
524 of thinking that goes into a well-designed system.</para>
|
|
bos@559
|
525
|
|
bos@559
|
526 <sect2>
|
|
bos@559
|
527 <title>Clever compression</title>
|
|
bos@559
|
528
|
|
bos@559
|
529 <para>When appropriate, Mercurial will store both snapshots and
|
|
bos@559
|
530 deltas in compressed form. It does this by always
|
|
bos@559
|
531 <emphasis>trying to</emphasis> compress a snapshot or delta,
|
|
bos@559
|
532 but only storing the compressed version if it's smaller than
|
|
bos@559
|
533 the uncompressed version.</para>
|
|
bos@559
|
534
|
|
bos@559
|
535 <para>This means that Mercurial does <quote>the right
|
|
bos@559
|
536 thing</quote> when storing a file whose native form is
|
|
bos@559
|
537 compressed, such as a <literal>zip</literal> archive or a JPEG
|
|
bos@559
|
538 image. When these types of files are compressed a second
|
|
bos@559
|
539 time, the resulting file is usually bigger than the
|
|
bos@559
|
540 once-compressed form, and so Mercurial will store the plain
|
|
bos@559
|
541 <literal>zip</literal> or JPEG.</para>
|
|
bos@559
|
542
|
|
bos@559
|
543 <para>Deltas between revisions of a compressed file are usually
|
|
bos@559
|
544 larger than snapshots of the file, and Mercurial again does
|
|
bos@559
|
545 <quote>the right thing</quote> in these cases. It finds that
|
|
bos@559
|
546 such a delta exceeds the threshold at which it should store a
|
|
bos@559
|
547 complete snapshot of the file, so it stores the snapshot,
|
|
bos@559
|
548 again saving space compared to a naive delta-only
|
|
bos@559
|
549 approach.</para>
|
|
bos@559
|
550
|
|
bos@559
|
551 <sect3>
|
|
bos@559
|
552 <title>Network recompression</title>
|
|
bos@559
|
553
|
|
bos@559
|
554 <para>When storing revisions on disk, Mercurial uses the
|
|
bos@559
|
555 <quote>deflate</quote> compression algorithm (the same one
|
|
bos@559
|
556 used by the popular <literal>zip</literal> archive format),
|
|
bos@559
|
557 which balances good speed with a respectable compression
|
|
bos@559
|
558 ratio. However, when transmitting revision data over a
|
|
bos@559
|
559 network connection, Mercurial uncompresses the compressed
|
|
bos@559
|
560 revision data.</para>
|
|
bos@559
|
561
|
|
bos@559
|
562 <para>If the connection is over HTTP, Mercurial recompresses
|
|
bos@559
|
563 the entire stream of data using a compression algorithm that
|
|
bos@559
|
564 gives a better compression ratio (the Burrows-Wheeler
|
|
bos@559
|
565 algorithm from the widely used <literal>bzip2</literal>
|
|
bos@559
|
566 compression package). This combination of algorithm and
|
|
bos@559
|
567 compression of the entire stream (instead of a revision at a
|
|
bos@559
|
568 time) substantially reduces the number of bytes to be
|
|
bos@559
|
569 transferred, yielding better network performance over almost
|
|
bos@559
|
570 all kinds of network.</para>
|
|
bos@559
|
571
|
|
bos@559
|
572 <para>(If the connection is over <command>ssh</command>,
|
|
bos@559
|
573 Mercurial <emphasis>doesn't</emphasis> recompress the
|
|
bos@559
|
574 stream, because <command>ssh</command> can already do this
|
|
bos@559
|
575 itself.)</para>
|
|
bos@559
|
576
|
|
bos@559
|
577 </sect3>
|
|
bos@559
|
578 </sect2>
|
|
bos@559
|
579 <sect2>
|
|
bos@559
|
580 <title>Read/write ordering and atomicity</title>
|
|
bos@559
|
581
|
|
bos@559
|
582 <para>Appending to files isn't the whole story when it comes to
|
|
bos@559
|
583 guaranteeing that a reader won't see a partial write. If you
|
|
bos@559
|
584 recall figure <xref linkend="fig:concepts:metadata"/>,
|
|
bos@559
|
585 revisions in the
|
|
bos@559
|
586 changelog point to revisions in the manifest, and revisions in
|
|
bos@559
|
587 the manifest point to revisions in filelogs. This hierarchy
|
|
bos@559
|
588 is deliberate.</para>
|
|
bos@559
|
589
|
|
bos@559
|
590 <para>A writer starts a transaction by writing filelog and
|
|
bos@559
|
591 manifest data, and doesn't write any changelog data until
|
|
bos@559
|
592 those are finished. A reader starts by reading changelog
|
|
bos@559
|
593 data, then manifest data, followed by filelog data.</para>
|
|
bos@559
|
594
|
|
bos@559
|
595 <para>Since the writer has always finished writing filelog and
|
|
bos@559
|
596 manifest data before it writes to the changelog, a reader will
|
|
bos@559
|
597 never read a pointer to a partially written manifest revision
|
|
bos@559
|
598 from the changelog, and it will never read a pointer to a
|
|
bos@559
|
599 partially written filelog revision from the manifest.</para>
|
|
bos@559
|
600
|
|
bos@559
|
601 </sect2>
|
|
bos@559
|
602 <sect2>
|
|
bos@559
|
603 <title>Concurrent access</title>
|
|
bos@559
|
604
|
|
bos@559
|
605 <para>The read/write ordering and atomicity guarantees mean that
|
|
bos@559
|
606 Mercurial never needs to <emphasis>lock</emphasis> a
|
|
bos@559
|
607 repository when it's reading data, even if the repository is
|
|
bos@559
|
608 being written to while the read is occurring. This has a big
|
|
bos@559
|
609 effect on scalability; you can have an arbitrary number of
|
|
bos@559
|
610 Mercurial processes safely reading data from a repository
|
|
bos@559
|
611 safely all at once, no matter whether it's being written to or
|
|
bos@559
|
612 not.</para>
|
|
bos@559
|
613
|
|
bos@559
|
614 <para>The lockless nature of reading means that if you're
|
|
bos@559
|
615 sharing a repository on a multi-user system, you don't need to
|
|
bos@559
|
616 grant other local users permission to
|
|
bos@559
|
617 <emphasis>write</emphasis> to your repository in order for
|
|
bos@559
|
618 them to be able to clone it or pull changes from it; they only
|
|
bos@559
|
619 need <emphasis>read</emphasis> permission. (This is
|
|
bos@559
|
620 <emphasis>not</emphasis> a common feature among revision
|
|
bos@559
|
621 control systems, so don't take it for granted! Most require
|
|
bos@559
|
622 readers to be able to lock a repository to access it safely,
|
|
bos@559
|
623 and this requires write permission on at least one directory,
|
|
bos@559
|
624 which of course makes for all kinds of nasty and annoying
|
|
bos@559
|
625 security and administrative problems.)</para>
|
|
bos@559
|
626
|
|
bos@559
|
627 <para>Mercurial uses locks to ensure that only one process can
|
|
bos@559
|
628 write to a repository at a time (the locking mechanism is safe
|
|
bos@559
|
629 even over filesystems that are notoriously hostile to locking,
|
|
bos@559
|
630 such as NFS). If a repository is locked, a writer will wait
|
|
bos@559
|
631 for a while to retry if the repository becomes unlocked, but
|
|
bos@559
|
632 if the repository remains locked for too long, the process
|
|
bos@559
|
633 attempting to write will time out after a while. This means
|
|
bos@559
|
634 that your daily automated scripts won't get stuck forever and
|
|
bos@559
|
635 pile up if a system crashes unnoticed, for example. (Yes, the
|
|
bos@559
|
636 timeout is configurable, from zero to infinity.)</para>
|
|
bos@559
|
637
|
|
bos@559
|
638 <sect3>
|
|
bos@559
|
639 <title>Safe dirstate access</title>
|
|
bos@559
|
640
|
|
bos@559
|
641 <para>As with revision data, Mercurial doesn't take a lock to
|
|
bos@559
|
642 read the dirstate file; it does acquire a lock to write it.
|
|
bos@559
|
643 To avoid the possibility of reading a partially written copy
|
|
bos@559
|
644 of the dirstate file, Mercurial writes to a file with a
|
|
bos@559
|
645 unique name in the same directory as the dirstate file, then
|
|
bos@559
|
646 renames the temporary file atomically to
|
|
bos@559
|
647 <filename>dirstate</filename>. The file named
|
|
bos@559
|
648 <filename>dirstate</filename> is thus guaranteed to be
|
|
bos@559
|
649 complete, not partially written.</para>
|
|
bos@559
|
650
|
|
bos@559
|
651 </sect3>
|
|
bos@559
|
652 </sect2>
|
|
bos@559
|
653 <sect2>
|
|
bos@559
|
654 <title>Avoiding seeks</title>
|
|
bos@559
|
655
|
|
bos@559
|
656 <para>Critical to Mercurial's performance is the avoidance of
|
|
bos@559
|
657 seeks of the disk head, since any seek is far more expensive
|
|
bos@559
|
658 than even a comparatively large read operation.</para>
|
|
bos@559
|
659
|
|
bos@559
|
660 <para>This is why, for example, the dirstate is stored in a
|
|
bos@559
|
661 single file. If there were a dirstate file per directory that
|
|
bos@559
|
662 Mercurial tracked, the disk would seek once per directory.
|
|
bos@559
|
663 Instead, Mercurial reads the entire single dirstate file in
|
|
bos@559
|
664 one step.</para>
|
|
bos@559
|
665
|
|
bos@559
|
666 <para>Mercurial also uses a <quote>copy on write</quote> scheme
|
|
bos@559
|
667 when cloning a repository on local storage. Instead of
|
|
bos@559
|
668 copying every revlog file from the old repository into the new
|
|
bos@559
|
669 repository, it makes a <quote>hard link</quote>, which is a
|
|
bos@559
|
670 shorthand way to say <quote>these two names point to the same
|
|
bos@559
|
671 file</quote>. When Mercurial is about to write to one of a
|
|
bos@559
|
672 revlog's files, it checks to see if the number of names
|
|
bos@559
|
673 pointing at the file is greater than one. If it is, more than
|
|
bos@559
|
674 one repository is using the file, so Mercurial makes a new
|
|
bos@559
|
675 copy of the file that is private to this repository.</para>
|
|
bos@559
|
676
|
|
bos@559
|
677 <para>A few revision control developers have pointed out that
|
|
bos@559
|
678 this idea of making a complete private copy of a file is not
|
|
bos@559
|
679 very efficient in its use of storage. While this is true,
|
|
bos@559
|
680 storage is cheap, and this method gives the highest
|
|
bos@559
|
681 performance while deferring most book-keeping to the operating
|
|
bos@559
|
682 system. An alternative scheme would most likely reduce
|
|
bos@559
|
683 performance and increase the complexity of the software, each
|
|
bos@559
|
684 of which is much more important to the <quote>feel</quote> of
|
|
bos@559
|
685 day-to-day use.</para>
|
|
bos@559
|
686
|
|
bos@559
|
687 </sect2>
|
|
bos@559
|
688 <sect2>
|
|
bos@559
|
689 <title>Other contents of the dirstate</title>
|
|
bos@559
|
690
|
|
bos@559
|
691 <para>Because Mercurial doesn't force you to tell it when you're
|
|
bos@559
|
692 modifying a file, it uses the dirstate to store some extra
|
|
bos@559
|
693 information so it can determine efficiently whether you have
|
|
bos@559
|
694 modified a file. For each file in the working directory, it
|
|
bos@559
|
695 stores the time that it last modified the file itself, and the
|
|
bos@559
|
696 size of the file at that time.</para>
|
|
bos@559
|
697
|
|
bos@559
|
698 <para>When you explicitly <command role="hg-cmd">hg
|
|
bos@559
|
699 add</command>, <command role="hg-cmd">hg remove</command>,
|
|
bos@559
|
700 <command role="hg-cmd">hg rename</command> or <command
|
|
bos@559
|
701 role="hg-cmd">hg copy</command> files, Mercurial updates the
|
|
bos@559
|
702 dirstate so that it knows what to do with those files when you
|
|
bos@559
|
703 commit.</para>
|
|
bos@559
|
704
|
|
bos@559
|
705 <para>When Mercurial is checking the states of files in the
|
|
bos@559
|
706 working directory, it first checks a file's modification time.
|
|
bos@559
|
707 If that has not changed, the file must not have been modified.
|
|
bos@559
|
708 If the file's size has changed, the file must have been
|
|
bos@559
|
709 modified. If the modification time has changed, but the size
|
|
bos@559
|
710 has not, only then does Mercurial need to read the actual
|
|
bos@559
|
711 contents of the file to see if they've changed. Storing these
|
|
bos@559
|
712 few extra pieces of information dramatically reduces the
|
|
bos@559
|
713 amount of data that Mercurial needs to read, which yields
|
|
bos@559
|
714 large performance improvements compared to other revision
|
|
bos@559
|
715 control systems.</para>
|
|
bos@559
|
716
|
|
bos@559
|
717 </sect2>
|
|
bos@559
|
718 </sect1>
|
|
bos@559
|
719 </chapter>
|
|
bos@559
|
720
|
|
bos@559
|
721 <!--
|
|
bos@559
|
722 local variables:
|
|
bos@559
|
723 sgml-parent-document: ("00book.xml" "book" "chapter")
|
|
bos@559
|
724 end:
|
|
bos@559
|
725 -->
|
