Mercurial > hgbook

comparison en/ch03-concepts.xml @ 690:b788b405e141

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Replace uses of <informalfigure> with <figure>
author Bryan O'Sullivan <bos@serpentine.com>
date Thu, 26 Mar 2009 21:07:39 -0700
parents c838b3975bc6
children 4ce9d0754af3
comparison
equal deleted inserted replaced
689:a2923aa93da9 690:b788b405e141
47 file. The correspondence between a file in the working 47 file. The correspondence between a file in the working
48 directory and the filelog that tracks its history in the 48 directory and the filelog that tracks its history in the
49 repository is illustrated in figure <xref 49 repository is illustrated in figure <xref
50 linkend="fig:concepts:filelog"/>.</para> 50 linkend="fig:concepts:filelog"/>.</para>
51 51
52 <informalfigure id="fig:concepts:filelog"> 52 <figure id="fig:concepts:filelog">
53 <mediaobject><imageobject><imagedata 53 <title>Relationships between files in working directory and
54 fileref="filelog"/></imageobject><textobject><phrase>XXX 54 filelogs in repository</title>
55 add text</phrase></textobject> 55 <mediaobject>
56 <caption><para id="x_2ed">Relationships between files in working 56 <imageobject><imagedata fileref="filelog"/></imageobject>
57 directory and filelogs in 57 <textobject><phrase>XXX add text</phrase></textobject>
58 repository</para></caption></mediaobject> 58 </mediaobject>
59 </informalfigure> 59 </figure>
60 60
61 </sect2> 61 </sect2>
62 <sect2> 62 <sect2>
63 <title>Managing tracked files</title> 63 <title>Managing tracked files</title>
64 64
97 manifest. A revision of the manifest stores a pointer to a 97 manifest. A revision of the manifest stores a pointer to a
98 single revision of each filelog tracked when that changeset 98 single revision of each filelog tracked when that changeset
99 was created. These relationships are illustrated in figure 99 was created. These relationships are illustrated in figure
100 <xref linkend="fig:concepts:metadata"/>.</para> 100 <xref linkend="fig:concepts:metadata"/>.</para>
101 101
102 <informalfigure id="fig:concepts:metadata"> 102 <figure id="fig:concepts:metadata">
103 <mediaobject><imageobject><imagedata 103 <title>Metadata relationships</title>
104 fileref="metadata"/></imageobject><textobject><phrase>XXX 104 <mediaobject>
105 add text</phrase></textobject><caption><para id="x_2f2">Metadata 105 <imageobject><imagedata fileref="metadata"/></imageobject>
106 relationships</para></caption> 106 <textobject><phrase>XXX add text</phrase></textobject>
107 </mediaobject> 107 </mediaobject>
108 </informalfigure> 108 </figure>
109 109
110 <para id="x_2f3">As the illustration shows, there is 110 <para id="x_2f3">As the illustration shows, there is
111 <emphasis>not</emphasis> a <quote>one to one</quote> 111 <emphasis>not</emphasis> a <quote>one to one</quote>
112 relationship between revisions in the changelog, manifest, or 112 relationship between revisions in the changelog, manifest, or
113 filelog. If the manifest hasn't changed between two 113 filelog. If the manifest hasn't changed between two
182 snapshot, and then every one of the revisions between the 182 snapshot, and then every one of the revisions between the
183 snapshot and your target revision. The more history that a 183 snapshot and your target revision. The more history that a
184 file accumulates, the more revisions you must read, hence the 184 file accumulates, the more revisions you must read, hence the
185 longer it takes to reconstruct a particular revision.</para> 185 longer it takes to reconstruct a particular revision.</para>
186 186
187 <informalfigure id="fig:concepts:snapshot"> 187 <figure id="fig:concepts:snapshot">
188 <mediaobject><imageobject><imagedata 188 <title>Snapshot of a revlog, with incremental deltas</title>
189 fileref="snapshot"/></imageobject><textobject><phrase>XXX 189 <mediaobject>
190 add text</phrase></textobject><caption><para id="x_2fb">Snapshot of 190 <imageobject><imagedata fileref="snapshot"/></imageobject>
191 a revlog, with incremental 191 <textobject><phrase>XXX add text</phrase></textobject>
192 deltas</para></caption></mediaobject> 192 </mediaobject>
193 </informalfigure> 193 </figure>
194 194
195 <para id="x_2fc">The innovation that Mercurial applies to this problem is 195 <para id="x_2fc">The innovation that Mercurial applies to this problem is
196 simple but effective. Once the cumulative amount of delta 196 simple but effective. Once the cumulative amount of delta
197 information stored since the last snapshot exceeds a fixed 197 information stored since the last snapshot exceeds a fixed
198 threshold, it stores a new snapshot (compressed, of course), 198 threshold, it stores a new snapshot (compressed, of course),
286 ID, indicating that the revision has only one real parent. Any 286 ID, indicating that the revision has only one real parent. Any
287 two revisions that have the same parent ID are branches. A 287 two revisions that have the same parent ID are branches. A
288 revision that represents a merge between branches has two normal 288 revision that represents a merge between branches has two normal
289 revision IDs in its parent slots.</para> 289 revision IDs in its parent slots.</para>
290 290
291 <informalfigure id="fig:concepts:revlog"> 291 <figure id="fig:concepts:revlog">
292 <mediaobject><imageobject><imagedata 292 <title>The conceptual structure of a revlog</title>
293 fileref="revlog"/></imageobject><textobject><phrase>XXX 293 <mediaobject>
294 add text</phrase></textobject></mediaobject> 294 <imageobject><imagedata fileref="revlog"/></imageobject>
295 </informalfigure> 295 <textobject><phrase>XXX add text</phrase></textobject>
296 </mediaobject>
297 </figure>
296 298
297 </sect1> 299 </sect1>
298 <sect1> 300 <sect1>
299 <title>The working directory</title> 301 <title>The working directory</title>
300 302
335 <para id="x_30b">The dirstate stores parent information for more than just 337 <para id="x_30b">The dirstate stores parent information for more than just
336 book-keeping purposes. Mercurial uses the parents of the 338 book-keeping purposes. Mercurial uses the parents of the
337 dirstate as <emphasis>the parents of a new 339 dirstate as <emphasis>the parents of a new
338 changeset</emphasis> when you perform a commit.</para> 340 changeset</emphasis> when you perform a commit.</para>
339 341
340 <informalfigure id="fig:concepts:wdir"> 342 <figure id="fig:concepts:wdir">
341 <mediaobject><imageobject><imagedata 343 <title>The working directory can have two parents</title>
342 fileref="wdir"/></imageobject><textobject><phrase>XXX 344 <mediaobject>
343 add text</phrase></textobject><caption><para id="x_30c">The working 345 <imageobject><imagedata fileref="wdir"/></imageobject>
344 directory can have two 346 <textobject><phrase>XXX add text</phrase></textobject>
345 parents</para></caption></mediaobject> 347 </mediaobject>
346 </informalfigure> 348 </figure>
347 349
348 <para id="x_30d">Figure <xref linkend="fig:concepts:wdir"/> shows the 350 <para id="x_30d">Figure <xref linkend="fig:concepts:wdir"/> shows the
349 normal state of the working directory, where it has a single 351 normal state of the working directory, where it has a single
350 changeset as parent. That changeset is the 352 changeset as parent. That changeset is the
351 <emphasis>tip</emphasis>, the newest changeset in the 353 <emphasis>tip</emphasis>, the newest changeset in the
352 repository that has no children.</para> 354 repository that has no children.</para>
353 355
354 <informalfigure id="fig:concepts:wdir-after-commit"> 356 <figure id="fig:concepts:wdir-after-commit">
355 <mediaobject><imageobject><imagedata 357 <title>The working directory gains new parents after a
356 fileref="wdir-after-commit"/></imageobject><textobject><phrase>XXX 358 commit</title>
357 add text</phrase></textobject><caption><para id="x_30e">The working 359 <mediaobject>
358 directory gains new parents after a 360 <imageobject><imagedata fileref="wdir-after-commit"/></imageobject>
359 commit</para></caption></mediaobject> 361 <textobject><phrase>XXX add text</phrase></textobject>
360 </informalfigure> 362 </mediaobject>
363 </figure>
361 364
362 <para id="x_30f">It's useful to think of the working directory as 365 <para id="x_30f">It's useful to think of the working directory as
363 <quote>the changeset I'm about to commit</quote>. Any files 366 <quote>the changeset I'm about to commit</quote>. Any files
364 that you tell Mercurial that you've added, removed, renamed, 367 that you tell Mercurial that you've added, removed, renamed,
365 or copied will be reflected in that changeset, as will 368 or copied will be reflected in that changeset, as will
389 interested in, and then examine the files in the working 392 interested in, and then examine the files in the working
390 directory directly to see their contents as they were when you 393 directory directly to see their contents as they were when you
391 committed that changeset. The effect of this is shown in 394 committed that changeset. The effect of this is shown in
392 figure <xref linkend="fig:concepts:wdir-pre-branch"/>.</para> 395 figure <xref linkend="fig:concepts:wdir-pre-branch"/>.</para>
393 396
394 <informalfigure id="fig:concepts:wdir-pre-branch"> 397 <figure id="fig:concepts:wdir-pre-branch">
395 <mediaobject><imageobject><imagedata 398 <title>The working directory, updated to an older
396 fileref="wdir-pre-branch"/></imageobject><textobject><phrase>XXX 399 changeset</title>
397 add text</phrase></textobject><caption><para id="x_312">The working 400 <mediaobject>
398 directory, updated to an older 401 <imageobject><imagedata fileref="wdir-pre-branch"/></imageobject>
399 changeset</para></caption></mediaobject> 402 <textobject><phrase>XXX add text</phrase></textobject>
400 </informalfigure> 403 </mediaobject>
404 </figure>
401 405
402 <para id="x_313">Having updated the working directory to an older 406 <para id="x_313">Having updated the working directory to an older
403 changeset, what happens if you make some changes, and then 407 changeset, what happens if you make some changes, and then
404 commit? Mercurial behaves in the same way as I outlined 408 commit? Mercurial behaves in the same way as I outlined
405 above. The parents of the working directory become the 409 above. The parents of the working directory become the
408 contains two changesets that have no children; we call these 412 contains two changesets that have no children; we call these
409 <emphasis>heads</emphasis>. You can see the structure that 413 <emphasis>heads</emphasis>. You can see the structure that
410 this creates in figure <xref 414 this creates in figure <xref
411 linkend="fig:concepts:wdir-branch"/>.</para> 415 linkend="fig:concepts:wdir-branch"/>.</para>
412 416
413 <informalfigure id="fig:concepts:wdir-branch"> 417 <figure id="fig:concepts:wdir-branch">
414 <mediaobject><imageobject><imagedata 418 <title>After a commit made while synced to an older
415 fileref="wdir-branch"/></imageobject><textobject><phrase>XXX 419 changeset</title>
416 add text</phrase></textobject><caption><para id="x_314">After a 420 <mediaobject>
417 commit made while synced to an older 421 <imageobject><imagedata fileref="wdir-branch"/></imageobject>
418 changeset</para></caption></mediaobject> 422 <textobject><phrase>XXX add text</phrase></textobject>
419 </informalfigure> 423 </mediaobject>
424 </figure>
420 425
421 <note> 426 <note>
422 <para id="x_315"> If you're new to Mercurial, you should keep in mind a 427 <para id="x_315"> If you're new to Mercurial, you should keep in mind a
423 common <quote>error</quote>, which is to use the <command 428 common <quote>error</quote>, which is to use the <command
424 role="hg-cmd">hg pull</command> command without any 429 role="hg-cmd">hg pull</command> command without any
449 command, Mercurial leaves the first parent of the working 454 command, Mercurial leaves the first parent of the working
450 directory unchanged, and sets the second parent to the 455 directory unchanged, and sets the second parent to the
451 changeset you're merging with, as shown in figure <xref 456 changeset you're merging with, as shown in figure <xref
452 linkend="fig:concepts:wdir-merge"/>.</para> 457 linkend="fig:concepts:wdir-merge"/>.</para>
453 458
454 <informalfigure id="fig:concepts:wdir-merge"> 459 <figure id="fig:concepts:wdir-merge">
455 <mediaobject><imageobject><imagedata 460 <title>Merging two heads</title>
456 fileref="wdir-merge"/></imageobject><textobject><phrase>XXX 461 <mediaobject>
457 add text</phrase></textobject><caption><para id="x_318">Merging two 462 <imageobject>
458 heads</para></caption></mediaobject> 463 <imagedata fileref="wdir-merge"/>
459 </informalfigure> 464 </imageobject>
465 <textobject><phrase>XXX add text</phrase></textobject>
466 </mediaobject>
467 </figure>
460 468
461 <para id="x_319">Mercurial also has to modify the working directory, to 469 <para id="x_319">Mercurial also has to modify the working directory, to
462 merge the files managed in the two changesets. Simplified a 470 merge the files managed in the two changesets. Simplified a
463 little, the merging process goes like this, for every file in 471 little, the merging process goes like this, for every file in
464 the manifests of both changesets.</para> 472 the manifests of both changesets.</para>