comparison en/ch03-tour-merge.xml @ 739:a13813534ccd

Fix all xref to figs

738:1a3d882149fd

    &interaction.tour.merge.clone;

    <para>We should now have two copies of
      <filename>hello.c</filename> with different contents.  The
      histories of the two repositories have also diverged, as
      illustrated in figure <xref
	linkend="fig.tour-merge.sep-repos"/>.</para>

    &interaction.tour.merge.cat;

    <informalfigure id="fig.tour-merge.sep-repos">
      <mediaobject>
	<imageobject><imagedata fileref="images/tour-merge-sep-repos.png"/></imageobject>
	<textobject><phrase>XXX add text</phrase></textobject>
	<caption><para>Divergent recent histories of the <filename
	      class="directory">my-hello</filename> and <filename
	      class="directory">my-new-hello</filename>
	    repositories</para></caption>
      </mediaobject>
    </informalfigure>

	because the newest revision in a repository doesn't have any
	children, but a repository can contain more than one
	head.</para>

      <informalfigure id="fig.tour-merge.pull">
	<mediaobject><imageobject><imagedata
				    fileref="images/tour-merge-pull.png"/></imageobject><textobject><phrase>XXX 
	      add text</phrase></textobject>
	  <caption><para>Repository contents after pulling from
	      <filename class="directory">my-hello</filename> into
	      <filename
		class="directory">my-new-hello</filename></para></caption>
	</mediaobject>
      </informalfigure>

      <para>In figure <xref linkend="fig.tour-merge.pull"/>, you can
	see the effect of the pull from <filename
	  class="directory">my-hello</filename> into <filename
	  class="directory">my-new-hello</filename>.  The history that
	was already present in <filename
	  class="directory">my-new-hello</filename> is untouched, but
	a new revision has been added.  By referring to figure <xref
	  linkend="fig.tour-merge.sep-repos"/>, we can see that the
	<emphasis>changeset ID</emphasis> remains the same in the new
	repository, but the <emphasis>revision number</emphasis> has
	changed.  (This, incidentally, is a fine example of why it's
	not safe to use revision numbers when discussing changesets.)

	two heads.</para>

      &interaction.tour.merge.merge;

      <informalfigure id="fig.tour-merge.merge">

	<mediaobject><imageobject><imagedata
				    fileref="images/tour-merge-merge.png"/></imageobject><textobject><phrase>XXX 
	      add text</phrase></textobject>
	  <caption><para>Working directory and repository during
	      merge, and following commit</para></caption>
	</mediaobject>
      </informalfigure>

      <para>This updates the working directory so that it contains
	changes from <emphasis>both</emphasis> heads, which is

	These are the same revisions that were previously displayed by
	<command role="hg-cmd">hg parents</command>.</para>

      &interaction.tour.merge.tip;

      <para>In figure <xref
	  linkend="fig.tour-merge.merge"/>, you can see a
	representation of what happens to the working directory during
	the merge, and how this affects the repository when the commit
	happens.  During the merge, the working directory has two
	parent changesets, and these become the parents of the new

      of the same files.  Unless both modifications are identical,
      this results in a <emphasis>conflict</emphasis>, where you have
      to decide how to reconcile the different changes into something
      coherent.</para>

    <informalfigure>

      <mediaobject id="fig.tour-merge.conflict">
	<imageobject><imagedata fileref="images/tour-merge-conflict.png"/></imageobject>
	<textobject><phrase>XXX add text</phrase></textobject>
	<caption><para>Conflicting changes to a
	    document</para></caption>      </mediaobject>
    </informalfigure>

    <para>Figure <xref linkend="fig.tour-merge.conflict"/> illustrates
      an instance of two conflicting changes to a document.  We
      started with a single version of the file; then we made some
      changes; while someone else made different changes to the same
      text.  Our task in resolving the conflicting changes is to
      decide what the file should look like.</para>

      <para>My preferred graphical merge tool is
	<command>kdiff3</command>, which I'll use to describe the
	features that are common to graphical file merging tools.  You
	can see a screenshot of <command>kdiff3</command> in action in
	figure <xref linkend="fig.tour-merge.kdiff3"/>.  The kind of
	merge it is performing is called a <emphasis>three-way
	  merge</emphasis>, because there are three different versions
	of the file of interest to us.  The tool thus splits the upper
	portion of the window into three panes:</para>
      <itemizedlist>

	  together</emphasis>; if we scroll vertically or horizontally
	in any of them, the others are updated to display the
	corresponding sections of their respective files.</para>

      <informalfigure id="fig.tour-merge.kdiff3">
	<mediaobject><imageobject><imagedata width="100%"
				    fileref="images/kdiff3.png"/></imageobject><textobject><phrase>XXX 
	      add text</phrase></textobject>
	  <caption><para>Using <command>kdiff3</command> to merge
	      versions of a file</para></caption>
	</mediaobject>
      </informalfigure>

      <para>For each conflicting portion of the file, we can choose to
	resolve the conflict using some combination of text from the
	base version, ours, or theirs.  We can also manually edit the

    </sect2>
    <sect2>
      <title>A worked example</title>

      <para>In this example, we will reproduce the file modification
	history of figure <xref linkend="fig.tour-merge.conflict"/>
	above.  Let's begin by creating a repository with a base
	version of our document.</para>

      &interaction.tour-merge-conflict.wife;

739:a13813534ccd

    &interaction.tour.merge.clone;

    <para>We should now have two copies of
      <filename>hello.c</filename> with different contents.  The
      histories of the two repositories have also diverged, as
      illustrated in figure <xref endterm="fig.tour-merge.sep-repos.caption"
	linkend="fig.tour-merge.sep-repos"/>.</para>

    &interaction.tour.merge.cat;

    <informalfigure id="fig.tour-merge.sep-repos">
      <mediaobject>
	<imageobject><imagedata fileref="images/tour-merge-sep-repos.png"/></imageobject>
	<textobject><phrase>XXX add text</phrase></textobject>
	<caption><para id="fig.tour-merge.sep-repos.caption">Divergent recent
	  histories of the <filename
	      class="directory">my-hello</filename> and <filename
	      class="directory">my-new-hello</filename>
	    repositories</para></caption>
      </mediaobject>
    </informalfigure>

	because the newest revision in a repository doesn't have any
	children, but a repository can contain more than one
	head.</para>

      <informalfigure id="fig.tour-merge.pull">
	<mediaobject>
	  <imageobject><imagedata fileref="images/tour-merge-pull.png"/></imageobject>
	  <textobject><phrase>XXX add text</phrase></textobject>
	  <caption><para id="fig.tour-merge.pull.caption">Repository contents after
	    pulling from <filename class="directory">my-hello</filename> into
	    <filename class="directory">my-new-hello</filename></para></caption>
	</mediaobject>
      </informalfigure>

      <para>In figure <xref endterm="fig.tour-merge.pull.caption"
        linkend="fig.tour-merge.pull"/>, you can
	see the effect of the pull from <filename
	  class="directory">my-hello</filename> into <filename
	  class="directory">my-new-hello</filename>.  The history that
	was already present in <filename
	  class="directory">my-new-hello</filename> is untouched, but
	a new revision has been added.  By referring to figure <xref
	  endterm="fig.tour-merge.sep-repos.caption" 
	  linkend="fig.tour-merge.sep-repos"/>, we can see that the
	<emphasis>changeset ID</emphasis> remains the same in the new
	repository, but the <emphasis>revision number</emphasis> has
	changed.  (This, incidentally, is a fine example of why it's
	not safe to use revision numbers when discussing changesets.)

	two heads.</para>

      &interaction.tour.merge.merge;

      <informalfigure id="fig.tour-merge.merge">
	<mediaobject>
	  <imageobject><imagedata fileref="images/tour-merge-merge.png"/></imageobject>
	  <textobject><phrase>XXX add text</phrase></textobject>
	  <caption><para id="fig.tour-merge.merge.caption">Working directory and
	      repository during merge, and following commit</para></caption>
	</mediaobject>
      </informalfigure>

      <para>This updates the working directory so that it contains
	changes from <emphasis>both</emphasis> heads, which is

	These are the same revisions that were previously displayed by
	<command role="hg-cmd">hg parents</command>.</para>

      &interaction.tour.merge.tip;

      <para>In figure <xref endterm="fig.tour-merge.merge.caption"
	  linkend="fig.tour-merge.merge"/>, you can see a
	representation of what happens to the working directory during
	the merge, and how this affects the repository when the commit
	happens.  During the merge, the working directory has two
	parent changesets, and these become the parents of the new

      of the same files.  Unless both modifications are identical,
      this results in a <emphasis>conflict</emphasis>, where you have
      to decide how to reconcile the different changes into something
      coherent.</para>

    <informalfigure id="fig.tour-merge.conflict">
      <mediaobject>
        <imageobject><imagedata fileref="images/tour-merge-conflict.png"/>
        </imageobject>
        <textobject><phrase>XXX add text</phrase></textobject>
        <caption><para id="fig.tour-merge.conflict.caption">Conflicting
          changes to a document</para></caption>
      </mediaobject>
    </informalfigure>

    <para>Figure <xref endterm="fig.tour-merge.conflict.caption"
      linkend="fig.tour-merge.conflict"/> illustrates
      an instance of two conflicting changes to a document.  We
      started with a single version of the file; then we made some
      changes; while someone else made different changes to the same
      text.  Our task in resolving the conflicting changes is to
      decide what the file should look like.</para>

      <para>My preferred graphical merge tool is
	<command>kdiff3</command>, which I'll use to describe the
	features that are common to graphical file merging tools.  You
	can see a screenshot of <command>kdiff3</command> in action in
	figure <xref endterm="fig.tour-merge.kdiff3.caption"
	linkend="fig.tour-merge.kdiff3"/>.  The kind of
	merge it is performing is called a <emphasis>three-way
	  merge</emphasis>, because there are three different versions
	of the file of interest to us.  The tool thus splits the upper
	portion of the window into three panes:</para>
      <itemizedlist>

	  together</emphasis>; if we scroll vertically or horizontally
	in any of them, the others are updated to display the
	corresponding sections of their respective files.</para>

      <informalfigure id="fig.tour-merge.kdiff3">
        <mediaobject>
          <imageobject><imagedata width="100%" fileref="images/kdiff3.png"/>
          </imageobject>
          <textobject><phrase>XXX add text</phrase></textobject>
          <caption><para id="fig.tour-merge.kdiff3.caption">Using
            <command>kdiff3</command> to merge versions of a file</para>
          </caption>
        </mediaobject>
      </informalfigure>

      <para>For each conflicting portion of the file, we can choose to
	resolve the conflict using some combination of text from the
	base version, ours, or theirs.  We can also manually edit the

    </sect2>
    <sect2>
      <title>A worked example</title>

      <para>In this example, we will reproduce the file modification
	history of figure <xref endterm="fig.tour-merge.conflict.caption"
	linkend="fig.tour-merge.conflict"/>
	above.  Let's begin by creating a repository with a base
	version of our document.</para>

      &interaction.tour-merge-conflict.wife;