annotate en/ch03-concepts.xml @ 778:64858a216741

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