hgbook

annotate fr/ch04-concepts.xml @ 991:e6894aa7baf2

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