comparison en/ch04-concepts.xml @ 739:a13813534ccd

Fix all xref to figs

738:1a3d882149fd

	small files without much history, the revision data and index
	are combined in a single <quote><literal>.i</literal></quote>
	file.  The correspondence between a file in the working
	directory and the filelog that tracks its history in the
	repository is illustrated in figure <xref
	  linkend="fig.concepts.filelog"/>.</para>

      <informalfigure id="fig.concepts.filelog">
	<mediaobject><imageobject><imagedata
				    fileref="images/filelog.png"/></imageobject><textobject><phrase>XXX 
	      add text</phrase></textobject>
	  <caption><para>Relationships between files in working
	      directory and filelogs in
	      repository</para></caption></mediaobject>
      </informalfigure>

    </sect2>
    <sect2>
      <title>Managing tracked files</title>

	revision stored in the changelog.  Each revision of the
	changelog contains a pointer to a single revision of the
	manifest.  A revision of the manifest stores a pointer to a
	single revision of each filelog tracked when that changeset
	was created.  These relationships are illustrated in figure
	<xref linkend="fig.concepts.metadata"/>.</para>

      <informalfigure id="fig.concepts.metadata">
	<mediaobject><imageobject><imagedata
				    fileref="images/metadata.png"/></imageobject><textobject><phrase>XXX 
	      add text</phrase></textobject><caption><para>Metadata
	      relationships</para></caption>
	</mediaobject>
      </informalfigure>

      <para>As the illustration shows, there is
	<emphasis>not</emphasis> a <quote>one to one</quote>
	relationship between revisions in the changelog, manifest, or

	snapshot and your target revision.  The more history that a
	file accumulates, the more revisions you must read, hence the
	longer it takes to reconstruct a particular revision.</para>

      <informalfigure id="fig.concepts.snapshot">
	<mediaobject><imageobject><imagedata
				    fileref="images/snapshot.png"/></imageobject><textobject><phrase>XXX 
	      add text</phrase></textobject><caption><para>Snapshot of
	      a revlog, with incremental
	      deltas</para></caption></mediaobject>
      </informalfigure>

      <para>The innovation that Mercurial applies to this problem is
	simple but effective.  Once the cumulative amount of delta
	information stored since the last snapshot exceeds a fixed

	instead of another delta.  This makes it possible to
	reconstruct <emphasis>any</emphasis> revision of a file
	quickly.  This approach works so well that it has since been
	copied by several other revision control systems.</para>

      <para>Figure <xref linkend="fig.concepts.snapshot"/> illustrates
	the idea.  In an entry in a revlog's index file, Mercurial
	stores the range of entries from the data file that it must
	read to reconstruct a particular revision.</para>

      <sect3>

      for not one parent, but two.  Mercurial uses a special hash,
      called the <quote>null ID</quote>, to represent the idea
      <quote>there is no parent here</quote>.  This hash is simply a
      string of zeroes.</para>

    <para>In figure <xref linkend="fig.concepts.revlog"/>, you can see
      an example of the conceptual structure of a revlog.  Filelogs,
      manifests, and changelogs all have this same structure; they
      differ only in the kind of data stored in each delta or
      snapshot.</para>

      two revisions that have the same parent ID are branches.  A
      revision that represents a merge between branches has two normal
      revision IDs in its parent slots.</para>

    <informalfigure id="fig.concepts.revlog">
      <mediaobject><imageobject><imagedata
				  fileref="images/revlog.png"/></imageobject><textobject><phrase>XXX 
	    add text</phrase></textobject></mediaobject>
    </informalfigure>

  </sect1>
  <sect1>
    <title>The working directory</title>

	book-keeping purposes.  Mercurial uses the parents of the
	dirstate as <emphasis>the parents of a new
	  changeset</emphasis> when you perform a commit.</para>

      <informalfigure id="fig.concepts.wdir">
	<mediaobject><imageobject><imagedata
				    fileref="images/wdir.png"/></imageobject><textobject><phrase>XXX 
	      add text</phrase></textobject><caption><para>The working
	      directory can have two
	      parents</para></caption></mediaobject>
      </informalfigure>

      <para>Figure <xref linkend="fig.concepts.wdir"/> shows the
	normal state of the working directory, where it has a single
	changeset as parent.  That changeset is the
	<emphasis>tip</emphasis>, the newest changeset in the
	repository that has no children.</para>

      <informalfigure id="fig.concepts.wdir-after-commit">
	<mediaobject><imageobject><imagedata
				    fileref="images/wdir-after-commit.png"/></imageobject><textobject><phrase>XXX 
	      add text</phrase></textobject><caption><para>The working
	      directory gains new parents after a
	      commit</para></caption></mediaobject>
      </informalfigure>

      <para>It's useful to think of the working directory as
	<quote>the changeset I'm about to commit</quote>.  Any files
	that you tell Mercurial that you've added, removed, renamed,

	directory as its parents.</para>

      <para>After a commit, Mercurial will update the parents of the
	working directory, so that the first parent is the ID of the
	new changeset, and the second is the null ID.  This is shown
	in figure <xref linkend="fig.concepts.wdir-after-commit"/>.
	Mercurial
	doesn't touch any of the files in the working directory when
	you commit; it just modifies the dirstate to note its new
	parents.</para>

	introduced a bug.  In cases like this, the natural thing to do
	is update the working directory to the changeset you're
	interested in, and then examine the files in the working
	directory directly to see their contents as they were when you
	committed that changeset.  The effect of this is shown in
	figure <xref linkend="fig.concepts.wdir-pre-branch"/>.</para>

      <informalfigure id="fig.concepts.wdir-pre-branch">
	<mediaobject><imageobject><imagedata
				    fileref="images/wdir-pre-branch.png"/></imageobject><textobject><phrase>XXX 
	      add text</phrase></textobject><caption><para>The working
	      directory, updated to an older
	      changeset</para></caption></mediaobject>
      </informalfigure>

      <para>Having updated the working directory to an older
	changeset, what happens if you make some changes, and then
	commit?  Mercurial behaves in the same way as I outlined

	parents of the new changeset.  This new changeset has no
	children, so it becomes the new tip.  And the repository now
	contains two changesets that have no children; we call these
	<emphasis>heads</emphasis>.  You can see the structure that
	this creates in figure <xref
	  linkend="fig.concepts.wdir-branch"/>.</para>

      <informalfigure id="fig.concepts.wdir-branch">
	<mediaobject><imageobject><imagedata
				    fileref="images/wdir-branch.png"/></imageobject><textobject><phrase>XXX 
	      add text</phrase></textobject><caption><para>After a
	      commit made while synced to an older
	      changeset</para></caption></mediaobject>
      </informalfigure>

      <note>
	<para>  If you're new to Mercurial, you should keep in mind a
	  common <quote>error</quote>, which is to use the <command

      <para>When you run the <command role="hg-cmd">hg merge</command>
	command, Mercurial leaves the first parent of the working
	directory unchanged, and sets the second parent to the
	changeset you're merging with, as shown in figure <xref
	  linkend="fig.concepts.wdir-merge"/>.</para>

      <informalfigure id="fig.concepts.wdir-merge">
	<mediaobject><imageobject><imagedata
				    fileref="images/wdir-merge.png"/></imageobject><textobject><phrase>XXX 
	      add text</phrase></textobject><caption><para>Merging two
	      heads</para></caption></mediaobject>
      </informalfigure>

      <para>Mercurial also has to modify the working directory, to
	merge the files managed in the two changesets.  Simplified a
	little, the merging process goes like this, for every file in

    <sect2>
      <title>Read/write ordering and atomicity</title>

      <para>Appending to files isn't the whole story when it comes to
	guaranteeing that a reader won't see a partial write.  If you
	recall figure <xref linkend="fig.concepts.metadata"/>,
	revisions in the
	changelog point to revisions in the manifest, and revisions in
	the manifest point to revisions in filelogs.  This hierarchy
	is deliberate.</para>

      <para>A writer starts a transaction by writing filelog and

739:a13813534ccd

	small files without much history, the revision data and index
	are combined in a single <quote><literal>.i</literal></quote>
	file.  The correspondence between a file in the working
	directory and the filelog that tracks its history in the
	repository is illustrated in figure <xref
	  endterm="fig.concepts.filelog.caption"
	  linkend="fig.concepts.filelog"/>.</para>

      <informalfigure id="fig.concepts.filelog">
        <mediaobject>
          <imageobject><imagedata fileref="images/filelog.png"/></imageobject>
          <textobject><phrase>XXX add text</phrase></textobject>
          <caption><para id="fig.concepts.filelog.caption">Relationships between
            files in working directory and filelogs in repository</para>
          </caption>
        </mediaobject>
      </informalfigure>

    </sect2>
    <sect2>
      <title>Managing tracked files</title>

	revision stored in the changelog.  Each revision of the
	changelog contains a pointer to a single revision of the
	manifest.  A revision of the manifest stores a pointer to a
	single revision of each filelog tracked when that changeset
	was created.  These relationships are illustrated in figure
	<xref endterm="fig.concepts.metadata.caption"
	  linkend="fig.concepts.metadata"/>.</para>

      <informalfigure id="fig.concepts.metadata">
        <mediaobject>
          <imageobject><imagedata fileref="images/metadata.png"/></imageobject>
          <textobject><phrase>XXX add text</phrase></textobject>
          <caption><para id="fig.concepts.metadata.caption">Metadata
            relationships</para></caption>
        </mediaobject>
      </informalfigure>

      <para>As the illustration shows, there is
	<emphasis>not</emphasis> a <quote>one to one</quote>
	relationship between revisions in the changelog, manifest, or

	snapshot and your target revision.  The more history that a
	file accumulates, the more revisions you must read, hence the
	longer it takes to reconstruct a particular revision.</para>

      <informalfigure id="fig.concepts.snapshot">
        <mediaobject>
          <imageobject><imagedata fileref="images/snapshot.png"/></imageobject>
          <textobject><phrase>XXX add text</phrase></textobject>
          <caption><para id="fig.concepts.snapshot.caption">Snapshot of
            a revlog, with incremental deltas</para></caption>
        </mediaobject>
      </informalfigure>

      <para>The innovation that Mercurial applies to this problem is
	simple but effective.  Once the cumulative amount of delta
	information stored since the last snapshot exceeds a fixed

	instead of another delta.  This makes it possible to
	reconstruct <emphasis>any</emphasis> revision of a file
	quickly.  This approach works so well that it has since been
	copied by several other revision control systems.</para>

      <para>Figure <xref endterm="fig.concepts.snapshot.caption"
          linkend="fig.concepts.snapshot"/> illustrates
	the idea.  In an entry in a revlog's index file, Mercurial
	stores the range of entries from the data file that it must
	read to reconstruct a particular revision.</para>

      <sect3>

      for not one parent, but two.  Mercurial uses a special hash,
      called the <quote>null ID</quote>, to represent the idea
      <quote>there is no parent here</quote>.  This hash is simply a
      string of zeroes.</para>

    <para>In figure <xref endterm="fig.concepts.revlog.caption"
        linkend="fig.concepts.revlog"/>, you can see
      an example of the conceptual structure of a revlog.  Filelogs,
      manifests, and changelogs all have this same structure; they
      differ only in the kind of data stored in each delta or
      snapshot.</para>

      two revisions that have the same parent ID are branches.  A
      revision that represents a merge between branches has two normal
      revision IDs in its parent slots.</para>

    <informalfigure id="fig.concepts.revlog">
      <mediaobject>
        <imageobject><imagedata fileref="images/revlog.png"/></imageobject>
        <textobject><phrase>XXX add text</phrase></textobject>        
	<caption><para id="fig.concepts.revlog.caption">Revision in revlog</para>
	</caption>
      </mediaobject>
    </informalfigure>

  </sect1>
  <sect1>
    <title>The working directory</title>

	book-keeping purposes.  Mercurial uses the parents of the
	dirstate as <emphasis>the parents of a new
	  changeset</emphasis> when you perform a commit.</para>

      <informalfigure id="fig.concepts.wdir">
        <mediaobject>
          <imageobject><imagedata fileref="images/wdir.png"/></imageobject>
          <textobject><phrase>XXX add text</phrase></textobject>
          <caption><para id="fig.concepts.wdir.caption">The working
            directory can have two parents</para></caption>
        </mediaobject>
      </informalfigure>

      <para>Figure <xref endterm="fig.concepts.wdir.caption"
          linkend="fig.concepts.wdir"/> shows the
	normal state of the working directory, where it has a single
	changeset as parent.  That changeset is the
	<emphasis>tip</emphasis>, the newest changeset in the
	repository that has no children.</para>

      <informalfigure id="fig.concepts.wdir-after-commit">
        <mediaobject>
          <imageobject><imagedata fileref="images/wdir-after-commit.png"/>
          </imageobject>
          <textobject><phrase>XXX add text</phrase></textobject>
          <caption><para id="fig.concepts.wdir-after-commit.caption">The working
            directory gains new parents after a commit</para></caption>
        </mediaobject>
      </informalfigure>

      <para>It's useful to think of the working directory as
	<quote>the changeset I'm about to commit</quote>.  Any files
	that you tell Mercurial that you've added, removed, renamed,

	directory as its parents.</para>

      <para>After a commit, Mercurial will update the parents of the
	working directory, so that the first parent is the ID of the
	new changeset, and the second is the null ID.  This is shown
	in figure <xref endterm="fig.concepts.wdir-after-commit.caption"
	  linkend="fig.concepts.wdir-after-commit"/>.
	Mercurial
	doesn't touch any of the files in the working directory when
	you commit; it just modifies the dirstate to note its new
	parents.</para>

	introduced a bug.  In cases like this, the natural thing to do
	is update the working directory to the changeset you're
	interested in, and then examine the files in the working
	directory directly to see their contents as they were when you
	committed that changeset.  The effect of this is shown in
	figure <xref endterm="fig.concepts.wdir-pre-branch.caption"
	  linkend="fig.concepts.wdir-pre-branch"/>.</para>

      <informalfigure id="fig.concepts.wdir-pre-branch">
        <mediaobject>
          <imageobject><imagedata fileref="images/wdir-pre-branch.png"/>
          </imageobject>
          <textobject><phrase>XXX add text</phrase></textobject>
          <caption><para id="fig.concepts.wdir-pre-branch.caption">The working
            directory, updated to an older changeset</para></caption>
        </mediaobject>
      </informalfigure>

      <para>Having updated the working directory to an older
	changeset, what happens if you make some changes, and then
	commit?  Mercurial behaves in the same way as I outlined

	parents of the new changeset.  This new changeset has no
	children, so it becomes the new tip.  And the repository now
	contains two changesets that have no children; we call these
	<emphasis>heads</emphasis>.  You can see the structure that
	this creates in figure <xref
	  endterm="fig.concepts.wdir-branch.caption"
	  linkend="fig.concepts.wdir-branch"/>.</para>

      <informalfigure id="fig.concepts.wdir-branch">
        <mediaobject>
          <imageobject><imagedata fileref="images/wdir-branch.png"/>
          </imageobject>
          <textobject><phrase>XXX add text</phrase></textobject>
          <caption><para id="fig.concepts.wdir-branch.caption">After a
            commit made while synced to an older changeset</para></caption>
        </mediaobject>
      </informalfigure>

      <note>
	<para>  If you're new to Mercurial, you should keep in mind a
	  common <quote>error</quote>, which is to use the <command

      <para>When you run the <command role="hg-cmd">hg merge</command>
	command, Mercurial leaves the first parent of the working
	directory unchanged, and sets the second parent to the
	changeset you're merging with, as shown in figure <xref
	  endterm="fig.concepts.wdir-merge.caption" 
	  linkend="fig.concepts.wdir-merge"/>.</para>

      <informalfigure id="fig.concepts.wdir-merge">
        <mediaobject>
          <imageobject><imagedata fileref="images/wdir-merge.png"/>
          </imageobject>
          <textobject><phrase>XXX add text</phrase></textobject>
          <caption><para id="fig.concepts.wdir-merge.caption">Merging two
            heads</para></caption>
        </mediaobject>
      </informalfigure>

      <para>Mercurial also has to modify the working directory, to
	merge the files managed in the two changesets.  Simplified a
	little, the merging process goes like this, for every file in

    <sect2>
      <title>Read/write ordering and atomicity</title>

      <para>Appending to files isn't the whole story when it comes to
	guaranteeing that a reader won't see a partial write.  If you
	recall figure <xref endterm="fig.concepts.metadata.caption"
	linkend="fig.concepts.metadata"/>, revisions in the
	changelog point to revisions in the manifest, and revisions in
	the manifest point to revisions in filelogs.  This hierarchy
	is deliberate.</para>

      <para>A writer starts a transaction by writing filelog and