annotate en/concepts.tex @ 201:80fc720338a5

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