comparison en/ch03-concepts.xml @ 828:477d6a3e5023

Many final changes.

827:d2aacc06e562

      </figure>

      <para id="x_2f3">As the illustration shows, there is
	<emphasis>not</emphasis> a <quote>one to one</quote>
	relationship between revisions in the changelog, manifest, or
	filelog. If the manifest hasn't changed between two
	changesets, the changelog entries for those changesets will
	point to the same revision of the manifest.  If a file that
	Mercurial tracks hasn't changed between two changesets, the
	entry for that file in the two revisions of the manifest will
	point to the same revision of its filelog.</para>

    </sect2>
  </sect1>
  <sect1>
    <title>Safe, efficient storage</title>

    </sect2>
    <sect2>
      <title>Fast retrieval</title>

      <para id="x_2fa">Mercurial cleverly avoids a pitfall common to all earlier
	revision control systems: the problem of <emphasis>inefficient
	  retrieval</emphasis>. Most revision control systems store
	the contents of a revision as an incremental series of
	modifications against a <quote>snapshot</quote>.  To
	reconstruct a specific revision, you must first read the
	snapshot, and then every one of the revisions between the
	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>

      <figure id="fig:concepts:snapshot">
	<title>Snapshot of a revlog, with incremental deltas</title>
	<mediaobject>
	  <imageobject><imagedata fileref="figs/snapshot.png"/></imageobject>

	read to reconstruct a particular revision.</para>

      <sect3>
	<title>Aside: the influence of video compression</title>

	<para id="x_2fe">If you're familiar with video compression or have ever
	  watched a TV feed through a digital cable or satellite
	  service, you may know that most video compression schemes
	  store each frame of video as a delta against its predecessor
	  frame.  In addition, these schemes use <quote>lossy</quote>
	  compression techniques to increase the compression ratio, so
	  visual errors accumulate over the course of a number of
	  inter-frame deltas.</para>

	<para id="x_2ff">Because it's possible for a video stream to <quote>drop
	    out</quote> occasionally due to signal glitches, and to
	  limit the accumulation of artefacts introduced by the lossy
	  compression process, video encoders periodically insert a
	  complete frame (called a <quote>key frame</quote>) into the
	  video stream; the next delta is generated against that
	  frame.  This means that if the video signal gets
	  interrupted, it will resume once the next key frame is
	  received.  Also, the accumulation of encoding errors
	  restarts anew with each key frame.</para>

      </sect3>
    </sect2>
    <sect2>
      <title>Identification and strong integrity</title>

	corrupted due to a hardware error or system bug, it's often
	possible to reconstruct some or most revisions from the
	uncorrupted sections of the revlog, both before and after the
	corrupted section.  This would not be possible with a
	delta-only storage model.</para>

    </sect2>
  </sect1>
  <sect1>
    <title>Revision history, branching, and merging</title>

    <para id="x_304">Every entry in a Mercurial revlog knows the identity of its
      immediate ancestor revision, usually referred to as its

      at the time that changeset was committed, and which revision of
      each file was then current.  It then recreates a copy of each of
      those files, with the same contents it had when the changeset
      was committed.</para>

    <para id="x_309">The <emphasis>dirstate</emphasis> contains Mercurial's
      knowledge of the working directory.  This details which
      changeset the working directory is updated to, and all of the
      files that Mercurial is tracking in the working
      directory.</para>

    <para id="x_30a">Just as a revision of a revlog has room for two parents, so
      that it can represent either a normal revision (with one parent)
      or a merge of two earlier revisions, the dirstate has slots for
      two parents.  When you use the <command role="hg-cmd">hg

	  <textobject><phrase>XXX add text</phrase></textobject>
	</mediaobject>
      </figure>

      <note>
	<para id="x_315">  If you're new to Mercurial, you should keep in mind a
	  common <quote>error</quote>, which is to use the <command
	    role="hg-cmd">hg pull</command> command without any
	  options.  By default, the <command role="hg-cmd">hg
	    pull</command> command <emphasis>does not</emphasis>
	  update the working directory, so you'll bring new changesets
	  into your repository, but the working directory will stay
	  synced at the same changeset as before the pull.  If you
	  make some changes and commit afterwards, you'll thus create
	  a new head, because your working directory isn't synced to
	  whatever the current tip is.</para>

	<para id="x_316">  I put the word <quote>error</quote> in
	  quotes because all that you need to do to rectify this
	  situation is <command role="hg-cmd">hg merge</command>, then
	  <command role="hg-cmd">hg commit</command>.  In other words,
	  this almost never has negative consequences; it's just
	  something of a surprise for newcomers.  I'll discuss other
	  ways to avoid this behavior, and why Mercurial behaves in
	  this initially surprising way, later on.</para>
      </note>

    </sect2>
    <sect2>
      <title>Merging changes</title>

	  changeset I'm about to commit</quote>.  After the <command
	  role="hg-cmd">hg merge</command> command completes, the
	working directory has two parents; these will become the
	parents of the new changeset.</para>

      <para id="x_322">Mercurial lets you perform multiple merges, but you must
	commit the results of each individual merge as you go.  This
	is necessary because Mercurial only tracks two parents for
	both revisions and the working directory.  While it would be
	technically possible to merge multiple changesets at once, the
	prospect of user confusion and making a terrible mess of a
	merge immediately becomes overwhelming.</para>

    </sect2>

    <sect2>
      <title>Merging and renames</title>

	  compression of the entire stream (instead of a revision at a
	  time) substantially reduces the number of bytes to be
	  transferred, yielding better network performance over most
	  kinds of network.</para>

	<para id="x_329">(If the connection is over <command>ssh</command>,
	  Mercurial <emphasis>doesn't</emphasis> recompress the
	  stream, because <command>ssh</command> can already do this
	  itself.)</para>

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

      <para id="x_32a">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 <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 id="x_32b">A writer starts a transaction by writing filelog and
	manifest data, and doesn't write any changelog data until
	those are finished.  A reader starts by reading changelog

	Mercurial never needs to <emphasis>lock</emphasis> a
	repository when it's reading data, even if the repository is
	being written to while the read is occurring. This has a big
	effect on scalability; you can have an arbitrary number of
	Mercurial processes safely reading data from a repository
	safely all at once, no matter whether it's being written to or
	not.</para>

      <para id="x_32e">The lockless nature of reading means that if you're
	sharing a repository on a multi-user system, you don't need to
	grant other local users permission to

	this idea of making a complete private copy of a file is not
	very efficient in its use of storage.  While this is true,
	storage is cheap, and this method gives the highest
	performance while deferring most book-keeping to the operating
	system.  An alternative scheme would most likely reduce
	performance and increase the complexity of the software, each
	of which is much more important to the <quote>feel</quote> of
	day-to-day use.</para>

    </sect2>
    <sect2>
      <title>Other contents of the dirstate</title>

	<command role="hg-cmd">hg rename</command> or <command
	  role="hg-cmd">hg copy</command> files, Mercurial updates the
	dirstate so that it knows what to do with those files when you
	commit.</para>

      <para id="x_337">When Mercurial is checking the states of files in the
	working directory, it first checks a file's modification time.
	If that has not changed, the file must not have been modified.
	If the file's size has changed, the file must have been
	modified.  If the modification time has changed, but the size
	has not, only then does Mercurial need to read the actual
	contents of the file to see if they've changed. Storing these
	few extra pieces of information dramatically reduces the
	amount of data that Mercurial needs to read, which yields
	large performance improvements compared to other revision
	control systems.</para>

    </sect2>
  </sect1>
</chapter>

<!--

828:477d6a3e5023

      </figure>

      <para id="x_2f3">As the illustration shows, there is
	<emphasis>not</emphasis> a <quote>one to one</quote>
	relationship between revisions in the changelog, manifest, or
	filelog. If a file that
	Mercurial tracks hasn't changed between two changesets, the
	entry for that file in the two revisions of the manifest will
	point to the same revision of its filelog<footnote>
	  <para>It is possible (though unusual) for the manifest to
	    remain the same between two changesets, in which case the
	    changelog entries for those changesets will point to the
	    same revision of the manifest.</para>
	</footnote>.</para>

    </sect2>
  </sect1>
  <sect1>
    <title>Safe, efficient storage</title>

    </sect2>
    <sect2>
      <title>Fast retrieval</title>

      <para id="x_2fa">Mercurial cleverly avoids a pitfall common to
	all earlier revision control systems: the problem of
	<emphasis>inefficient retrieval</emphasis>. Most revision
	control systems store the contents of a revision as an
	incremental series of modifications against a
	<quote>snapshot</quote>.  (Some base the snapshot on the
	oldest revision, others on the newest.)  To reconstruct a
	specific revision, you must first read the snapshot, and then
	every one of the revisions between the 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>

      <figure id="fig:concepts:snapshot">
	<title>Snapshot of a revlog, with incremental deltas</title>
	<mediaobject>
	  <imageobject><imagedata fileref="figs/snapshot.png"/></imageobject>

	read to reconstruct a particular revision.</para>

      <sect3>
	<title>Aside: the influence of video compression</title>

	<para id="x_2fe">If you're familiar with video compression or
	  have ever watched a TV feed through a digital cable or
	  satellite service, you may know that most video compression
	  schemes store each frame of video as a delta against its
	  predecessor frame.</para>

	<para id="x_2ff">Mercurial borrows this idea to make it
	  possible to reconstruct a revision from a snapshot and a
	  small number of deltas.</para>

      </sect3>
    </sect2>
    <sect2>
      <title>Identification and strong integrity</title>

	corrupted due to a hardware error or system bug, it's often
	possible to reconstruct some or most revisions from the
	uncorrupted sections of the revlog, both before and after the
	corrupted section.  This would not be possible with a
	delta-only storage model.</para>
    </sect2>
  </sect1>

  <sect1>
    <title>Revision history, branching, and merging</title>

    <para id="x_304">Every entry in a Mercurial revlog knows the identity of its
      immediate ancestor revision, usually referred to as its

      at the time that changeset was committed, and which revision of
      each file was then current.  It then recreates a copy of each of
      those files, with the same contents it had when the changeset
      was committed.</para>

    <para id="x_309">The <emphasis>dirstate</emphasis> is a special
      structure that contains Mercurial's knowledge of the working
      directory.  It is maintained as a file named
      <filename>.hg/dirstate</filename> inside a repository.  The
      dirstate details which changeset the working directory is
      updated to, and all of the files that Mercurial is tracking in
      the working directory. It also lets Mercurial quickly notice
      changed files, by recording their checkout times and
      sizes.</para>

    <para id="x_30a">Just as a revision of a revlog has room for two parents, so
      that it can represent either a normal revision (with one parent)
      or a merge of two earlier revisions, the dirstate has slots for
      two parents.  When you use the <command role="hg-cmd">hg

	  <textobject><phrase>XXX add text</phrase></textobject>
	</mediaobject>
      </figure>

      <note>
	<para id="x_315">If you're new to Mercurial, you should keep
	  in mind a common <quote>error</quote>, which is to use the
	  <command role="hg-cmd">hg pull</command> command without any
	  options.  By default, the <command role="hg-cmd">hg
	    pull</command> command <emphasis>does not</emphasis>
	  update the working directory, so you'll bring new changesets
	  into your repository, but the working directory will stay
	  synced at the same changeset as before the pull.  If you
	  make some changes and commit afterwards, you'll thus create
	  a new head, because your working directory isn't synced to
	  whatever the current tip is.  To combine the operation of a
	  pull, followed by an update, run <command>hg pull
	    -u</command>.</para>

	<para id="x_316">I put the word <quote>error</quote> in quotes
	  because all that you need to do to rectify the situation
	  where you created a new head by accident is
	  <command role="hg-cmd">hg merge</command>, then <command
	    role="hg-cmd">hg commit</command>.  In other words, this
	  almost never has negative consequences; it's just something
	  of a surprise for newcomers.  I'll discuss other ways to
	  avoid this behavior, and why Mercurial behaves in this
	  initially surprising way, later on.</para>
      </note>

    </sect2>
    <sect2>
      <title>Merging changes</title>

	  changeset I'm about to commit</quote>.  After the <command
	  role="hg-cmd">hg merge</command> command completes, the
	working directory has two parents; these will become the
	parents of the new changeset.</para>

      <para id="x_322">Mercurial lets you perform multiple merges, but
	you must commit the results of each individual merge as you
	go.  This is necessary because Mercurial only tracks two
	parents for both revisions and the working directory.  While
	it would be technically feasible to merge multiple changesets
	at once, Mercurial avoids this for simplicity.  With multi-way
	merges, the risks of user confusion, nasty conflict
	resolution, and making a terrible mess of a merge would grow
	intolerable.</para>

    </sect2>

    <sect2>
      <title>Merging and renames</title>

	  compression of the entire stream (instead of a revision at a
	  time) substantially reduces the number of bytes to be
	  transferred, yielding better network performance over most
	  kinds of network.</para>

	<para id="x_329">If the connection is over
	  <command>ssh</command>, Mercurial
	  <emphasis>doesn't</emphasis> recompress the stream, because
	  <command>ssh</command> can already do this itself.  You can
	  tell Mercurial to always use <command>ssh</command>'s
	  compression feature by editing the
	  <filename>.hgrc</filename> file in your home directory as
	  follows.</para>

	<programlisting>[ui]
ssh = ssh -C</programlisting>

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

      <para id="x_32a">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 <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 id="x_32b">A writer starts a transaction by writing filelog and
	manifest data, and doesn't write any changelog data until
	those are finished.  A reader starts by reading changelog

	Mercurial never needs to <emphasis>lock</emphasis> a
	repository when it's reading data, even if the repository is
	being written to while the read is occurring. This has a big
	effect on scalability; you can have an arbitrary number of
	Mercurial processes safely reading data from a repository
	all at once, no matter whether it's being written to or
	not.</para>

      <para id="x_32e">The lockless nature of reading means that if you're
	sharing a repository on a multi-user system, you don't need to
	grant other local users permission to

	this idea of making a complete private copy of a file is not
	very efficient in its use of storage.  While this is true,
	storage is cheap, and this method gives the highest
	performance while deferring most book-keeping to the operating
	system.  An alternative scheme would most likely reduce
	performance and increase the complexity of the software, but
	speed and simplicity are key to the <quote>feel</quote> of
	day-to-day use.</para>

    </sect2>
    <sect2>
      <title>Other contents of the dirstate</title>

	<command role="hg-cmd">hg rename</command> or <command
	  role="hg-cmd">hg copy</command> files, Mercurial updates the
	dirstate so that it knows what to do with those files when you
	commit.</para>

      <para id="x_337">The dirstate helps Mercurial to efficiently
	  check the status of files in a repository.</para>

      <itemizedlist>
	<listitem>
	  <para>When Mercurial checks the state of a file in the
	    working directory, it first checks a file's modification
	    time against the time in the dirstate that records when
	    Mercurial last wrote the file. If the last modified time
	    is the same as the time when Mercurial wrote the file, the
	    file must not have been modified, so Mercurial does not
	    need to check any further.</para>
	</listitem>
	<listitem>
	  <para>If the file's size has changed, the file must have
	    been modified.  If the modification time has changed, but
	    the size has not, only then does Mercurial need to
	    actually read the contents of the file to see if it has
	    changed.</para>
	</listitem>
      </itemizedlist>

      <para>Storing the modification time and size dramatically
	reduces the number of read operations that Mercurial needs to
	perform when we run commands like <command>hg status</command>.
	This results in large performance improvements.</para>
    </sect2>
  </sect1>
</chapter>

<!--