Mercurial > hgbook
annotate en/ch04-concepts.xml @ 723:3c5e1c03cc3e
Add XSL stylesheets for DocBook
author | Dongsheng Song <dongsheng.song@gmail.com> |
---|---|
date | Thu, 12 Mar 2009 15:47:15 +0800 |
parents | 13513d2a128d |
children | cfdb601a3c8b |
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 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
7 <para>Unlike many revision control systems, the concepts upon which |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
8 Mercurial is built are simple enough that it's easy to understand |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
9 how the software really works. Knowing this certainly isn't |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
10 necessary, but I find it useful to have a <quote>mental |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
11 model</quote> of what's going on.</para> |
56
b8539d91c84d
Begining of concepts chapter
Josef "Jeff" Sipek <jeffpc@josefsipek.net>
parents:
diff
changeset
|
12 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
13 <para>This understanding gives me confidence that Mercurial has been |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
14 carefully designed to be both <emphasis>safe</emphasis> and |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
15 <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
|
16 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
|
17 when I perform a revision control task, I'm less likely to be |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
18 surprised by its behaviour.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
19 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
20 <para>In this chapter, we'll initially cover the core concepts |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
21 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
|
22 interesting details of its implementation.</para> |
112 | 23 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
24 <sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
25 <title>Mercurial's historical record</title> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
26 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
27 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
28 <title>Tracking the history of a single file</title> |
56
b8539d91c84d
Begining of concepts chapter
Josef "Jeff" Sipek <jeffpc@josefsipek.net>
parents:
diff
changeset
|
29 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
30 <para>When Mercurial tracks modifications to a file, it stores |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
31 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
|
32 <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
|
33 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
|
34 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
|
35 the <filename role="special" |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
36 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
|
37 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
|
38 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
|
39 efficiently.</para> |
56
b8539d91c84d
Begining of concepts chapter
Josef "Jeff" Sipek <jeffpc@josefsipek.net>
parents:
diff
changeset
|
40 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
41 <para>A file that is large, or has a lot of history, has its |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
42 filelog stored in separate data |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
43 (<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
|
44 (<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
|
45 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
|
46 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
|
47 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
|
48 directory and the filelog that tracks its history in the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
49 repository is illustrated in figure <xref |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
50 linkend="fig:concepts:filelog"/>.</para> |
56
b8539d91c84d
Begining of concepts chapter
Josef "Jeff" Sipek <jeffpc@josefsipek.net>
parents:
diff
changeset
|
51 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
52 <informalfigure id="fig:concepts:filelog"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
53 <mediaobject><imageobject><imagedata |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
54 fileref="filelog"/></imageobject><textobject><phrase>XXX |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
55 add text</phrase></textobject> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
56 <caption><para>Relationships between files in working |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
57 directory and filelogs in |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
58 repository</para></caption></mediaobject> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
59 </informalfigure> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
60 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
61 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
62 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
63 <title>Managing tracked files</title> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
64 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
65 <para>Mercurial uses a structure called a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
66 <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
|
67 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
|
68 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
|
69 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
|
70 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
|
71 of file metadata.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
72 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
73 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
74 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
75 <title>Recording changeset information</title> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
76 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
77 <para>The <emphasis>changelog</emphasis> contains information |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
78 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
|
79 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
|
80 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
|
81 manifest to use.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
82 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
83 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
84 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
85 <title>Relationships between revisions</title> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
86 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
87 <para>Within a changelog, a manifest, or a filelog, each |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
88 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
|
89 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
|
90 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
|
91 <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
|
92 hierarchical in nature.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
93 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
94 <para>For every changeset in a repository, there is exactly one |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
95 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
|
96 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
|
97 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
|
98 single revision of each filelog tracked when that changeset |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
99 was created. These relationships are illustrated in figure |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
100 <xref linkend="fig:concepts:metadata"/>.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
101 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
102 <informalfigure id="fig:concepts:metadata"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
103 <mediaobject><imageobject><imagedata |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
104 fileref="metadata"/></imageobject><textobject><phrase>XXX |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
105 add text</phrase></textobject><caption><para>Metadata |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
106 relationships</para></caption> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
107 </mediaobject> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
108 </informalfigure> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
109 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
110 <para>As the illustration shows, there is |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
111 <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
|
112 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
|
113 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
|
114 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
|
115 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
|
116 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
|
117 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
|
118 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
|
119 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
120 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
121 </sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
122 <sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
123 <title>Safe, efficient storage</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
124 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
125 <para>The underpinnings of changelogs, manifests, and filelogs are |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
126 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
|
127 <emphasis>revlog</emphasis>.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
128 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
129 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
130 <title>Efficient storage</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
131 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
132 <para>The revlog provides efficient storage of revisions using a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
133 <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
|
134 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
|
135 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
|
136 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
|
137 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
|
138 of a file.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
139 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
140 <para>Some obsolete revision control systems can only work with |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
141 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
|
142 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
|
143 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
|
144 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
|
145 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
|
146 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
147 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
148 <sect2 id="sec:concepts:txn"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
149 <title>Safe operation</title> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
150 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
151 <para>Mercurial only ever <emphasis>appends</emphasis> data to |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
152 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
|
153 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
|
154 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
|
155 data.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
156 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
157 <para>In addition, Mercurial treats every write as part of a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
158 <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
|
159 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
|
160 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
|
161 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
|
162 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
|
163 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
|
164 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
|
165 result that might confuse it.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
166 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
167 <para>The fact that Mercurial only appends to files makes it |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
168 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
|
169 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
|
170 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
|
171 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
172 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
173 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
174 <title>Fast retrieval</title> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
175 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
176 <para>Mercurial cleverly avoids a pitfall common to all earlier |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
177 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
|
178 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
|
179 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
|
180 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
|
181 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
|
182 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
|
183 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
|
184 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
|
185 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
|
186 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
187 <informalfigure id="fig:concepts:snapshot"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
188 <mediaobject><imageobject><imagedata |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
189 fileref="snapshot"/></imageobject><textobject><phrase>XXX |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
190 add text</phrase></textobject><caption><para>Snapshot of |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
191 a revlog, with incremental |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
192 deltas</para></caption></mediaobject> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
193 </informalfigure> |
110 | 194 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
195 <para>The innovation that Mercurial applies to this problem is |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
196 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
|
197 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
|
198 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
|
199 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
|
200 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
|
201 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
|
202 copied by several other revision control systems.</para> |
110 | 203 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
204 <para>Figure <xref linkend="fig:concepts:snapshot"/> illustrates |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
205 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
|
206 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
|
207 read to reconstruct a particular revision.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
208 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
209 <sect3> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
210 <title>Aside: the influence of video compression</title> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
211 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
212 <para>If you're familiar with video compression or have ever |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
213 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
|
214 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
|
215 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
|
216 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
|
217 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
|
218 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
|
219 inter-frame deltas.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
220 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
221 <para>Because it's possible for a video stream to <quote>drop |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
222 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
|
223 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
|
224 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
|
225 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
|
226 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
|
227 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
|
228 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
|
229 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
|
230 restarts anew with each key frame.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
231 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
232 </sect3> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
233 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
234 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
235 <title>Identification and strong integrity</title> |
110 | 236 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
237 <para>Along with delta or snapshot information, a revlog entry |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
238 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
|
239 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
|
240 and easy to detect accidental corruption.</para> |
112 | 241 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
242 <para>Hashes provide more than a mere check against corruption; |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
243 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
|
244 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
|
245 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
|
246 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
|
247 scenes.</para> |
110 | 248 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
249 <para>Mercurial verifies that hashes are correct when it |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
250 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
|
251 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
|
252 will complain and stop whatever it's doing.</para> |
110 | 253 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
254 <para>In addition to the effect it has on retrieval efficiency, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
255 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
|
256 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
|
257 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
|
258 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
|
259 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
|
260 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
|
261 delta-only storage model.</para> |
110 | 262 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
263 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
264 </sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
265 <sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
266 <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
|
267 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
268 <para>Every entry in a Mercurial revlog knows the identity of its |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
269 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
|
270 <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
|
271 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
|
272 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
|
273 <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
|
274 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
|
275 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
276 <para>In figure <xref linkend="fig:concepts:revlog"/>, you can see |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
277 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
|
278 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
|
279 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
|
280 snapshot.</para> |
115
b74102b56df5
Wow! Lots more work detailing the working directory, merging, etc.
Bryan O'Sullivan <bos@serpentine.com>
parents:
113
diff
changeset
|
281 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
282 <para>The first revision in a revlog (at the bottom of the image) |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
283 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
|
284 <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
|
285 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
|
286 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
|
287 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
|
288 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
|
289 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
|
290 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
291 <informalfigure id="fig:concepts:revlog"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
292 <mediaobject><imageobject><imagedata |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
293 fileref="revlog"/></imageobject><textobject><phrase>XXX |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
294 add text</phrase></textobject></mediaobject> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
295 </informalfigure> |
110 | 296 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
297 </sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
298 <sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
299 <title>The working directory</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
300 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
301 <para>In the working directory, Mercurial stores a snapshot of the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
302 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
|
303 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
304 <para>The working directory <quote>knows</quote> which changeset |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
305 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
|
306 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
|
307 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
|
308 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
|
309 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
|
310 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
|
311 was committed.</para> |
113
a0f57b3e677e
More concepts, this time working directory stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
112
diff
changeset
|
312 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
313 <para>The <emphasis>dirstate</emphasis> contains Mercurial's |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
314 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
|
315 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
|
316 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
|
317 directory.</para> |
113
a0f57b3e677e
More concepts, this time working directory stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
112
diff
changeset
|
318 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
319 <para>Just as a revision of a revlog has room for two parents, so |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
320 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
|
321 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
|
322 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
|
323 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
|
324 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
|
325 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
|
326 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
|
327 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
|
328 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
|
329 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
|
330 dirstate are.</para> |
113
a0f57b3e677e
More concepts, this time working directory stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
112
diff
changeset
|
331 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
332 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
333 <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
|
334 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
335 <para>The dirstate stores parent information for more than just |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
336 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
|
337 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
|
338 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
|
339 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
340 <informalfigure id="fig:concepts:wdir"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
341 <mediaobject><imageobject><imagedata |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
342 fileref="wdir"/></imageobject><textobject><phrase>XXX |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
343 add text</phrase></textobject><caption><para>The working |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
344 directory can have two |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
345 parents</para></caption></mediaobject> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
346 </informalfigure> |
113
a0f57b3e677e
More concepts, this time working directory stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
112
diff
changeset
|
347 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
348 <para>Figure <xref linkend="fig:concepts:wdir"/> shows the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
349 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
|
350 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
|
351 <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
|
352 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
|
353 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
354 <informalfigure id="fig:concepts:wdir-after-commit"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
355 <mediaobject><imageobject><imagedata |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
356 fileref="wdir-after-commit"/></imageobject><textobject><phrase>XXX |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
357 add text</phrase></textobject><caption><para>The working |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
358 directory gains new parents after a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
359 commit</para></caption></mediaobject> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
360 </informalfigure> |
113
a0f57b3e677e
More concepts, this time working directory stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
112
diff
changeset
|
361 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
362 <para>It's useful to think of the working directory as |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
363 <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
|
364 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
|
365 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
|
366 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
|
367 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
|
368 directory as its parents.</para> |
113
a0f57b3e677e
More concepts, this time working directory stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
112
diff
changeset
|
369 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
370 <para>After a commit, Mercurial will update the parents of the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
371 working directory, so that the first parent is the ID of the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
372 new changeset, and the second is the null ID. This is shown |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
373 in figure <xref linkend="fig:concepts:wdir-after-commit"/>. |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
374 Mercurial |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
375 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
|
376 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
|
377 parents.</para> |
113
a0f57b3e677e
More concepts, this time working directory stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
112
diff
changeset
|
378 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
379 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
380 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
381 <title>Creating a new head</title> |
112 | 382 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
383 <para>It's perfectly normal to update the working directory to a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
384 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
|
385 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
|
386 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
|
387 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
|
388 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
|
389 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
|
390 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
|
391 committed that changeset. The effect of this is shown in |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
392 figure <xref linkend="fig:concepts:wdir-pre-branch"/>.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
393 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
394 <informalfigure id="fig:concepts:wdir-pre-branch"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
395 <mediaobject><imageobject><imagedata |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
396 fileref="wdir-pre-branch"/></imageobject><textobject><phrase>XXX |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
397 add text</phrase></textobject><caption><para>The working |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
398 directory, updated to an older |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
399 changeset</para></caption></mediaobject> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
400 </informalfigure> |
112 | 401 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
402 <para>Having updated the working directory to an older |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
403 changeset, what happens if you make some changes, and then |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
404 commit? Mercurial behaves in the same way as I outlined |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
405 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
|
406 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
|
407 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
|
408 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
|
409 <emphasis>heads</emphasis>. You can see the structure that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
410 this creates in figure <xref |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
411 linkend="fig:concepts:wdir-branch"/>.</para> |
112 | 412 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
413 <informalfigure id="fig:concepts:wdir-branch"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
414 <mediaobject><imageobject><imagedata |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
415 fileref="wdir-branch"/></imageobject><textobject><phrase>XXX |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
416 add text</phrase></textobject><caption><para>After a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
417 commit made while synced to an older |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
418 changeset</para></caption></mediaobject> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
419 </informalfigure> |
115
b74102b56df5
Wow! Lots more work detailing the working directory, merging, etc.
Bryan O'Sullivan <bos@serpentine.com>
parents:
113
diff
changeset
|
420 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
421 <note> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
422 <para> If you're new to Mercurial, you should keep in mind a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
423 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
|
424 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
|
425 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
|
426 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
|
427 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
|
428 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
|
429 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
|
430 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
|
431 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
|
432 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
|
433 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
434 <para> I put the word <quote>error</quote> in quotes because |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
435 all that you need to do to rectify this situation is |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
436 <command role="hg-cmd">hg merge</command>, then <command |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
437 role="hg-cmd">hg commit</command>. In other words, this |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
438 almost never has negative consequences; it just surprises |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
439 people. I'll discuss other ways to avoid this behaviour, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
440 and why Mercurial behaves in this initially surprising way, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
441 later on.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
442 </note> |
115
b74102b56df5
Wow! Lots more work detailing the working directory, merging, etc.
Bryan O'Sullivan <bos@serpentine.com>
parents:
113
diff
changeset
|
443 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
444 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
445 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
446 <title>Merging heads</title> |
115
b74102b56df5
Wow! Lots more work detailing the working directory, merging, etc.
Bryan O'Sullivan <bos@serpentine.com>
parents:
113
diff
changeset
|
447 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
448 <para>When you run the <command role="hg-cmd">hg merge</command> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
449 command, Mercurial leaves the first parent of the working |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
450 directory unchanged, and sets the second parent to the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
451 changeset you're merging with, as shown in figure <xref |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
452 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
|
453 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
454 <informalfigure id="fig:concepts:wdir-merge"> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
455 <mediaobject><imageobject><imagedata |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
456 fileref="wdir-merge"/></imageobject><textobject><phrase>XXX |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
457 add text</phrase></textobject><caption><para>Merging two |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
458 heads</para></caption></mediaobject> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
459 </informalfigure> |
112 | 460 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
461 <para>Mercurial also has to modify the working directory, to |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
462 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
|
463 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
|
464 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
|
465 <itemizedlist> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
466 <listitem><para>If neither changeset has modified a file, do |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
467 nothing with that file.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
468 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
469 <listitem><para>If one changeset has modified a file, and the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
470 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
|
471 working directory.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
472 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
473 <listitem><para>If one changeset has removed a file, and the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
474 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
|
475 from the working directory.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
476 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
477 <listitem><para>If one changeset has removed a file, but the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
478 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
|
479 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
|
480 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
481 <listitem><para>If both changesets have modified a file, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
482 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
|
483 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
|
484 the user.</para> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
485 </listitem> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
486 <listitem><para>If one changeset has modified a file, and the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
487 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
|
488 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
|
489 </listitem></itemizedlist> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
490 <para>There are more details&emdash;merging has plenty of corner |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
491 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
|
492 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
|
493 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
|
494 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
|
495 conflicts.</para> |
115
b74102b56df5
Wow! Lots more work detailing the working directory, merging, etc.
Bryan O'Sullivan <bos@serpentine.com>
parents:
113
diff
changeset
|
496 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
497 <para>When you're thinking about what happens when you commit |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
498 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
|
499 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
|
500 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
|
501 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
|
502 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
|
503 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
504 <para>Mercurial lets you perform multiple merges, but you must |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
505 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
|
506 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
|
507 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
|
508 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
|
509 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
|
510 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
|
511 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
512 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
513 </sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
514 <sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
515 <title>Other interesting design features</title> |
110 | 516 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
517 <para>In the sections above, I've tried to highlight some of the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
518 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
|
519 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
|
520 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
|
521 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
|
522 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
|
523 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
|
524 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
|
525 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
|
526 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
527 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
528 <title>Clever compression</title> |
110 | 529 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
530 <para>When appropriate, Mercurial will store both snapshots and |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
531 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
|
532 <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
|
533 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
|
534 the uncompressed version.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
535 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
536 <para>This means that Mercurial does <quote>the right |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
537 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
|
538 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
|
539 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
|
540 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
|
541 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
|
542 <literal>zip</literal> or JPEG.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
543 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
544 <para>Deltas between revisions of a compressed file are usually |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
545 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
|
546 <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
|
547 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
|
548 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
|
549 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
|
550 approach.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
551 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
552 <sect3> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
553 <title>Network recompression</title> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
554 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
555 <para>When storing revisions on disk, Mercurial uses the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
556 <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
|
557 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
|
558 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
|
559 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
|
560 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
|
561 revision data.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
562 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
563 <para>If the connection is over HTTP, Mercurial recompresses |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
564 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
|
565 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
|
566 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
|
567 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
|
568 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
|
569 time) substantially reduces the number of bytes to be |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
570 transferred, yielding better network performance over almost |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
571 all kinds of network.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
572 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
573 <para>(If the connection is over <command>ssh</command>, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
574 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
|
575 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
|
576 itself.)</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
577 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
578 </sect3> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
579 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
580 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
581 <title>Read/write ordering and atomicity</title> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
582 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
583 <para>Appending to files isn't the whole story when it comes to |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
584 guaranteeing that a reader won't see a partial write. If you |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
585 recall figure <xref linkend="fig:concepts:metadata"/>, |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
586 revisions in the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
587 changelog point to revisions in the manifest, and revisions in |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
588 the manifest point to revisions in filelogs. This hierarchy |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
589 is deliberate.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
590 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
591 <para>A writer starts a transaction by writing filelog and |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
592 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
|
593 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
|
594 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
|
595 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
596 <para>Since the writer has always finished writing filelog and |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
597 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
|
598 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
|
599 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
|
600 partially written filelog revision from the manifest.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
601 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
602 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
603 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
604 <title>Concurrent access</title> |
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 <para>The read/write ordering and atomicity guarantees mean that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
607 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
|
608 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
|
609 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
|
610 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
|
611 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
|
612 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
|
613 not.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
614 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
615 <para>The lockless nature of reading means that if you're |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
616 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
|
617 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
|
618 <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
|
619 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
|
620 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
|
621 <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
|
622 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
|
623 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
|
624 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
|
625 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
|
626 security and administrative problems.)</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
627 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
628 <para>Mercurial uses locks to ensure that only one process can |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
629 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
|
630 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
|
631 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
|
632 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
|
633 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
|
634 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
|
635 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
|
636 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
|
637 timeout is configurable, from zero to infinity.)</para> |
110 | 638 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
639 <sect3> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
640 <title>Safe dirstate access</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
641 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
642 <para>As with revision data, Mercurial doesn't take a lock to |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
643 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
|
644 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
|
645 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
|
646 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
|
647 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
|
648 <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
|
649 <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
|
650 complete, not partially written.</para> |
110 | 651 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
652 </sect3> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
653 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
654 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
655 <title>Avoiding seeks</title> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
656 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
657 <para>Critical to Mercurial's performance is the avoidance of |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
658 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
|
659 than even a comparatively large read operation.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
660 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
661 <para>This is why, for example, the dirstate is stored in a |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
662 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
|
663 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
|
664 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
|
665 one step.</para> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
666 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
667 <para>Mercurial also uses a <quote>copy on write</quote> scheme |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
668 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
|
669 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
|
670 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
|
671 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
|
672 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
|
673 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
|
674 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
|
675 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
|
676 copy of the file that is private to this repository.</para> |
111 | 677 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
678 <para>A few revision control developers have pointed out that |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
679 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
|
680 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
|
681 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
|
682 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
|
683 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
|
684 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
|
685 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
|
686 day-to-day use.</para> |
111 | 687 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
688 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
689 <sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
690 <title>Other contents of the dirstate</title> |
109
1b67dc96f27a
Snapshot of concepts chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
108
diff
changeset
|
691 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
692 <para>Because Mercurial doesn't force you to tell it when you're |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
693 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
|
694 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
|
695 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
|
696 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
|
697 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
|
698 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
699 <para>When you explicitly <command role="hg-cmd">hg |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
700 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
|
701 <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
|
702 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
|
703 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
|
704 commit.</para> |
115
b74102b56df5
Wow! Lots more work detailing the working directory, merging, etc.
Bryan O'Sullivan <bos@serpentine.com>
parents:
113
diff
changeset
|
705 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
706 <para>When Mercurial is checking the states of files in the |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
707 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
|
708 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
|
709 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
|
710 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
|
711 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
|
712 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
|
713 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
|
714 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
|
715 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
|
716 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
|
717 |
658
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
718 </sect2> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
719 </sect1> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
720 </chapter> |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
721 |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
722 <!-- |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
723 local variables: |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
724 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
|
725 end: |
b90b024729f1
WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents:
650
diff
changeset
|
726 --> |