comparison en/ch02-tour-merge.xml @ 718:4e23c220d1b0

Update chapter 2

717:2b193ab0df9a

      &interaction.tour.merge.update;

      <para id="x_345">Mercurial is telling us that the <command role="hg-cmd">hg
	  update</command> command won't do a merge; it won't update
	the working directory when it thinks we might be wanting to do
	a merge, unless we force it to do so.  Instead, we use the
	<command role="hg-cmd">hg merge</command> command to merge the
	two heads.</para>

      &interaction.tour.merge.merge;

      <figure id="fig:tour-merge:merge">
	<title>Working directory and repository during merge, and
	  following commit</title>
	<mediaobject>

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

      <para id="x_347">This updates the working directory so that it contains
	changes from <emphasis>both</emphasis> heads, which is
	reflected in both the output of <command role="hg-cmd">hg
	  parents</command> and the contents of
	<filename>hello.c</filename>.</para>

      &interaction.tour.merge.parents;

    </sect2>
    <sect2>
      <title>Committing the results of the merge</title>

      <para id="x_348">Whenever we've done a merge, <command role="hg-cmd">hg
	  parents</command> will display two parents until we <command
	  role="hg-cmd">hg commit</command> the results of the
	  merge.</para>

	&interaction.tour.merge.commit;

      <para id="x_349">We now have a new tip revision; notice that it has
	<emphasis>both</emphasis> of our former heads as its parents.
	These are the same revisions that were previously displayed by
	<command role="hg-cmd">hg parents</command>.</para>

      &interaction.tour.merge.tip;

      <para id="x_34a">In <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
	changeset.</para>

    </sect2>
  </sect1>
  <sect1>
    <title>Merging conflicting changes</title>

    <para id="x_34b">Most merges are simple affairs, but sometimes you'll find
      yourself merging changes where each modifies the same portions
      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>

      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 id="x_34e">Mercurial doesn't have a built-in facility for handling
      conflicts. Instead, it runs an external program called
      <command>hgmerge</command>.  This is a shell script that is
      bundled with Mercurial; you can change it to behave however you
      please.  What it does by default is try to find one of several
      different merging tools that are likely to be installed on your
      system.  It first tries a few fully automatic merging tools; if
      these don't succeed (because the resolution process requires
      human guidance) or aren't present, the script tries a few
      different graphical merging tools.</para>

    <para id="x_34f">It's also possible to get Mercurial to run another program
      or script instead of <command>hgmerge</command>, by setting the
      <envar>HGMERGE</envar> environment variable to the name of your

	different versions of the file, we'll set up an environment
	suitable for running our merge.</para>

      &interaction.tour-merge-conflict.pull;

      <para id="x_35d">In this example, I won't use Mercurial's normal
	<command>hgmerge</command> program to do the merge, because it
	would drop my nice automated example-running tool into a
	graphical user interface.  Instead, I'll set
	<envar>HGMERGE</envar> to tell Mercurial to use the
	non-interactive <command>merge</command> command.  This is
	bundled with many Unix-like systems. If you're following this
	example on your computer, don't bother setting
	<envar>HGMERGE</envar>.</para>

      <para id="x_35e"><emphasis role="bold">XXX FIX THIS
	  EXAMPLE.</emphasis></para>

      &interaction.tour-merge-conflict.merge;

      <para id="x_35f">Because <command>merge</command> can't resolve the
	conflicting changes, it leaves <emphasis>merge

    <title>Simplifying the pull-merge-commit sequence</title>

    <para id="x_362">The process of merging changes as outlined above is
      straightforward, but requires running three commands in
      sequence.</para>
    <programlisting>hg pull
hg merge
hg commit -m 'Merged remote changes'</programlisting>
    <para id="x_363">In the case of the final commit, you also need to enter a
      commit message, which is almost always going to be a piece of
      uninteresting <quote>boilerplate</quote> text.</para>

      Mercurial small and easy to deal with.  Some extensions add new
      commands that you can use from the command line, while others
      work <quote>behind the scenes,</quote> for example adding
      capabilities to the server.</para>

    <para id="x_366">The <literal role="hg-ext">fetch</literal> extension adds a
      new command called, not surprisingly, <command role="hg-cmd">hg
	fetch</command>.  This extension acts as a combination of
      <command role="hg-cmd">hg pull</command>, <command
	role="hg-cmd">hg update</command> and <command
	role="hg-cmd">hg merge</command>.  It begins by pulling
      changes from another repository into the current repository.  If
      it finds that the changes added a new head to the repository, it
      begins a merge, then commits the result of the merge with an
      automatically-generated commit message.  If no new heads were
      added, it updates the working directory to the new tip
      changeset.</para>

    <para id="x_367">Enabling the <literal role="hg-ext">fetch</literal>
      extension is easy.  Edit your <filename
	role="special">.hgrc</filename>, and either go to the <literal
	role="rc-extensions">extensions</literal> section or create an
      <literal role="rc-extensions">extensions</literal> section. Then
      add a line that simply reads <quote><literal>fetch
	</literal></quote>.</para>
    <programlisting>[extensions]
fetch =</programlisting>
    <para id="x_368">(Normally, on the right-hand side of the
      <quote><literal>=</literal></quote> would appear the location of
      the extension, but since the <literal
	role="hg-ext">fetch</literal> extension is in the standard
      distribution, Mercurial knows where to search for it.)</para>

  </sect1>

718:4e23c220d1b0

      &interaction.tour.merge.update;

      <para id="x_345">Mercurial is telling us that the <command role="hg-cmd">hg
	  update</command> command won't do a merge; it won't update
	the working directory when it thinks we might want to do
	a merge, unless we force it to do so.  Instead, we use the
	<command role="hg-cmd">hg merge</command> command to merge the
	two heads.</para>

      &interaction.tour.merge.merge;

      <para id="x_347">This updates the working directory so that it contains
	changes from <emphasis>both</emphasis> heads, which is
	reflected in both the output of <command role="hg-cmd">hg
	  parents</command> and the contents of
	<filename>hello.c</filename>.</para>

      &interaction.tour.merge.parents;

    </sect2>
    <sect2>
      <title>Committing the results of the merge</title>

      <para id="x_348">Whenever we've done a merge, <command role="hg-cmd">hg
	  parents</command> will display two parents until we <command
	  role="hg-cmd">hg commit</command> the results of the
	  merge.</para>

	&interaction.tour.merge.commit;

      <para id="x_349">We now have a new tip revision; notice that it has
	<emphasis>both</emphasis> of our former heads as its parents.
	These are the same revisions that were previously displayed by
	<command role="hg-cmd">hg parents</command>.</para>

      &interaction.tour.merge.tip;

      <para id="x_34a">In <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
	changeset.</para>

      <figure id="fig:tour-merge:merge">
	<title>Working directory and repository during merge, and
	  following commit</title>
	<mediaobject>

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

      <para>We sometimes talk about a merge having
	<emphasis>sides</emphasis>: the left side is the first parent
	in the output of <command rold="hg-cmd">hg parents</command>,
	and the right side is the second.  If the working directory
	was at e.g. revision 5 before we began a merge, that revision
	will become the left side of the merge.</para>
    </sect2>
  </sect1>

  <sect1>
    <title>Merging conflicting changes</title>

    <para id="x_34b">Most merges are simple affairs, but sometimes you'll find
      yourself merging changes where each side modifies the same portions
      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>

      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 id="x_34e">Mercurial doesn't have a built-in facility for handling
      conflicts. Instead, it runs an external program, usually one
      that displays some kind of graphical conflict resolution
      interface.  By default, Mercurial tries to find one of several
      different merging tools that are likely to be installed on your
      system.  It first tries a few fully automatic merging tools; if
      these don't succeed (because the resolution process requires
      human guidance) or aren't present, it tries a few
      different graphical merging tools.</para>

    <para id="x_34f">It's also possible to get Mercurial to run another program
      or script instead of <command>hgmerge</command>, by setting the
      <envar>HGMERGE</envar> environment variable to the name of your

	different versions of the file, we'll set up an environment
	suitable for running our merge.</para>

      &interaction.tour-merge-conflict.pull;

      <para id="x_35d">In this example, I'll set
	<envar>HGMERGE</envar> to tell Mercurial to use the
	non-interactive <command>merge</command> command.  This is
	bundled with many Unix-like systems. (If you're following this
	example on your computer, don't bother setting
	<envar>HGMERGE</envar>.)</para>

      &interaction.tour-merge-conflict.merge;

      <para id="x_35f">Because <command>merge</command> can't resolve the
	conflicting changes, it leaves <emphasis>merge

    <title>Simplifying the pull-merge-commit sequence</title>

    <para id="x_362">The process of merging changes as outlined above is
      straightforward, but requires running three commands in
      sequence.</para>
    <programlisting>hg pull -u
hg merge
hg commit -m 'Merged remote changes'</programlisting>
    <para id="x_363">In the case of the final commit, you also need to enter a
      commit message, which is almost always going to be a piece of
      uninteresting <quote>boilerplate</quote> text.</para>

      Mercurial small and easy to deal with.  Some extensions add new
      commands that you can use from the command line, while others
      work <quote>behind the scenes,</quote> for example adding
      capabilities to the server.</para>

    <para id="x_366">The <literal role="hg-ext">fetch</literal>
      extension adds a new command called, not surprisingly, <command
	role="hg-cmd">hg fetch</command>.  This extension acts as a
      combination of <command role="hg-cmd">hg pull -u</command>,
      <command role="hg-cmd">hg merge</command> and <command
	role="hg-cmd">hg commit</command>.  It begins by pulling
      changes from another repository into the current repository.  If
      it finds that the changes added a new head to the repository, it
      begins a merge, then (if the merge succeeded) commits the result
      of the merge with an automatically-generated commit message.  If
      no new heads were added, it updates the working directory to the
      new tip changeset.</para>

    <para id="x_367">Enabling the <literal
	role="hg-ext">fetch</literal> extension is easy.  Edit the
      <filename role="special">.hgrc</filename> file in your home
      directory, and either go to the <literal
	role="rc-extensions">extensions</literal> section or create an
      <literal role="rc-extensions">extensions</literal> section. Then
      add a line that simply reads
      <quote><literal>fetch=</literal></quote>.</para>

    <programlisting>[extensions]
fetch =</programlisting>

    <para id="x_368">(Normally, the right-hand side of the
      <quote><literal>=</literal></quote> would indicate where to find
      the extension, but since the <literal
	role="hg-ext">fetch</literal> extension is in the standard
      distribution, Mercurial knows where to search for it.)</para>

  </sect1>