comparison en/ch08-branch.xml @ 666:8fcd44708f41

Uncomment all the mangled interaction examples.

665:27043f385f3f

    <para>Once you decide that you'd like to call a particular
      revision a <quote>release</quote>, it's a good idea to record
      the identity of that revision. This will let you reproduce that
      release at a later date, for whatever purpose you might need at
      the time (reproducing a bug, porting to a new platform, etc).
      <!-- &interaction.tag.init; --></para>

    <para>Mercurial lets you give a permanent name to any revision
      using the <command role="hg-cmd">hg tag</command> command.  Not
      surprisingly, these names are called <quote>tags</quote>. <!--
      &interaction.tag.tag; --></para>

    <para>A tag is nothing more than a <quote>symbolic name</quote>
      for a revision.  Tags exist purely for your convenience, so that
      you have a handy permanent way to refer to a revision; Mercurial
      doesn't interpret the tag names you use in any way.  Neither

    <para>You can use the <command role="hg-cmd">hg tags</command>
      command to display the tags present in your repository.  In the
      output, each tagged revision is identified first by its name,
      then by revision number, and finally by the unique hash of the
      revision. <!-- &interaction.tag.tags; --> Notice that
      <literal>tip</literal> is listed in the output of <command
	role="hg-cmd">hg tags</command>.  The <literal>tip</literal>
      tag is a special <quote>floating</quote> tag, which always
      identifies the newest revision in the repository.</para>

    <para>In the output of the <command role="hg-cmd">hg
	tags</command> command, tags are listed in reverse order, by
      revision number.  This usually means that recent tags are listed
      before older tags.  It also means that <literal>tip</literal> is
      always going to be the first tag listed in the output of
      <command role="hg-cmd">hg tags</command>.</para>

    <para>When you run <command role="hg-cmd">hg log</command>, if it
      displays a revision that has tags associated with it, it will
      print those tags. <!-- &interaction.tag.log; --></para>

    <para>Any time you need to provide a revision ID to a Mercurial
      command, the command will accept a tag name in its place.
      Internally, Mercurial will translate your tag name into the
      corresponding revision ID, then use that. <!--
      &interaction.tag.log.v1.0; --></para>

    <para>There's no limit on the number of tags you can have in a
      repository, or on the number of tags that a single revision can
      have.  As a practical matter, it's not a great idea to have
      <quote>too many</quote> (a number which will vary from project

      lot of noise if you were to tag every clean build.  Instead, you
      could tag failed builds (on the assumption that they're rare!),
      or simply not use tags to track buildability.</para>

    <para>If you want to remove a tag that you no longer want, use
      <command role="hg-cmd">hg tag --remove</command>. <!--
      &interaction.tag.remove; --> You can also modify a tag at any
      time, so that it identifies a different revision, by simply
      issuing a new <command role="hg-cmd">hg tag</command> command.
      You'll have to use the <option role="hg-opt-tag">-f</option>
      option to tell Mercurial that you <emphasis>really</emphasis>
      want to update the tag. <!-- &interaction.tag.replace; --> There
      will still be a permanent record of the previous identity of the
      tag, but Mercurial will no longer use it.  There's thus no
      penalty to tagging the wrong revision; all you have to do is
      turn around and tag the correct revision once you discover your
      error.</para>

    <para>Mercurial stores tags in a normal revision-controlled file
      in your repository.  If you've created any tags, you'll find
      them in a file named <filename
	role="special">.hgtags</filename>.  When you run the <command
	role="hg-cmd">hg tag</command> command, Mercurial modifies
      this file, then automatically commits the change to it.  This
      means that every time you run <command role="hg-cmd">hg
	tag</command>, you'll see a corresponding changeset in the
      output of <command role="hg-cmd">hg log</command>. <!--
      &interaction.tag.tip; --></para>

    <sect2>
      <title>Handling tag conflicts during a merge</title>

      <para>You won't often need to care about the <filename

      branch in Mercurial is in a dedicated repository.  If you have
      an existing shared repository&emdash;let's call it
      <literal>myproject</literal>&emdash;that reaches a
      <quote>1.0</quote> milestone, you can start to prepare for
      future maintenance releases on top of version 1.0 by tagging the
      revision from which you prepared the 1.0 release. <!--
      &interaction.branch-repo.tag; --> You can then clone a new
      shared <literal>myproject-1.0.1</literal> repository as of that
      tag. <!-- &interaction.branch-repo.clone; --></para>

    <para>Afterwards, if someone needs to work on a bug fix that ought
      to go into an upcoming 1.0.1 minor release, they clone the
      <literal>myproject-1.0.1</literal> repository, make their
      changes, and push them back. <!--
      &interaction.branch-repo.bugfix; --> Meanwhile, development for
      the next major release can continue, isolated and unabated, in
      the <literal>myproject</literal> repository. <!--
      &interaction.branch-repo.new; --></para>

  </sect1>
  <sect1>
    <title>Don't repeat yourself: merging across branches</title>

      help you to manage these bugfixes without duplicating your
      work.</para>

    <para>In the simplest instance, all you need to do is pull changes
      from your maintenance branch into your local clone of the target
      branch. <!-- &interaction.branch-repo.pull; --> You'll then need
      to merge the heads of the two branches, and push back to the
      main branch. <!-- &interaction.branch-repo.merge; --></para>

  </sect1>
  <sect1>
    <title>Naming branches within one repository</title>

      the branch named <literal>default</literal>.</para>

    <para>To start working with named branches, use the <command
	role="hg-cmd">hg branches</command> command.  This command
      lists the named branches already present in your repository,
      telling you which changeset is the tip of each. <!--
      &interaction.branch-named.branches; --> Since you haven't
      created any named branches yet, the only one that exists is
      <literal>default</literal>.</para>

    <para>To find out what the <quote>current</quote> branch is, run
      the <command role="hg-cmd">hg branch</command> command, giving
      it no arguments.  This tells you what branch the parent of the
      current changeset is on. <!-- &interaction.branch-named.branch;
      --></para>

    <para>To create a new branch, run the <command role="hg-cmd">hg
	branch</command> command again.  This time, give it one
      argument: the name of the branch you want to create. <!--
      &interaction.branch-named.create; --></para>

    <para>After you've created a branch, you might wonder what effect
      the <command role="hg-cmd">hg branch</command> command has had.
      What do the <command role="hg-cmd">hg status</command> and
      <command role="hg-cmd">hg tip</command> commands report? <!--
      &interaction.branch-named.status; --> Nothing has changed in the
      working directory, and there's been no new history created.  As
      this suggests, running the <command role="hg-cmd">hg
	branch</command> command has no permanent effect; it only
      tells Mercurial what branch name to use the
      <emphasis>next</emphasis> time you commit a changeset.</para>

      branch on which you committed.  Once you've switched from the
      <literal>default</literal> branch to another and committed,
      you'll see the name of the new branch show up in the output of
      <command role="hg-cmd">hg log</command>, <command
	role="hg-cmd">hg tip</command>, and other commands that
      display the same kind of output. <!--
      &interaction.branch-named.commit; --> The <command
	role="hg-cmd">hg log</command>-like commands will print the
      branch name of every changeset that's not on the
      <literal>default</literal> branch.  As a result, if you never
      use named branches, you'll never see this information.</para>

    <para>Once you've named a branch and committed a change with that
      name, every subsequent commit that descends from that change
      will inherit the same branch name.  You can change the name of a
      branch at any time, using the <command role="hg-cmd">hg
	branch</command> command. <!--
      &interaction.branch-named.rebranch; --> In practice, this is
      something you won't do very often, as branch names tend to have
      fairly long lifetimes.  (This isn't a rule, just an
      observation.)</para>

  </sect1>
  <sect1>
    <title>Dealing with multiple named branches in a
      repository</title>

      you may need to use the <option role="hg-opt-update">-C</option>
      option to <command role="hg-cmd">hg update</command>.</para>

    <para>This behaviour is a little subtle, so let's see it in
      action.  First, let's remind ourselves what branch we're
      currently on, and what branches are in our repository. <!--
      &interaction.branch-named.parents; --> We're on the
      <literal>bar</literal> branch, but there also exists an older
      <command role="hg-cmd">hg foo</command> branch.</para>

    <para>We can <command role="hg-cmd">hg update</command> back and
      forth between the tips of the <literal>foo</literal> and
      <literal>bar</literal> branches without needing to use the
      <option role="hg-opt-update">-C</option> option, because this
      only involves going backwards and forwards linearly through our
      change history. <!-- &interaction.branch-named.update-switchy;
      --></para>

    <para>If we go back to the <literal>foo</literal> branch and then
      run <command role="hg-cmd">hg update</command>, it will keep us
      on <literal>foo</literal>, not move us to the tip of
      <literal>bar</literal>. <!--
      &interaction.branch-named.update-nothing; --></para>

    <para>Committing a new change on the <literal>foo</literal> branch
      introduces a new head. <!--
      &interaction.branch-named.foo-commit; --></para>

  </sect1>
  <sect1>
    <title>Branch names and merging</title>

      result of a merge will be a single head on the
      <literal>foo</literal> branch, as you might hope.</para>

    <para>But if I'm working on the <literal>bar</literal> branch, and
      I merge work from the <literal>foo</literal> branch, the result
      will remain on the <literal>bar</literal> branch. <!--
      &interaction.branch-named.merge; --></para>

    <para>To give a more concrete example, if I'm working on the
      <literal>bleeding-edge</literal> branch, and I want to bring in
      the latest fixes from the <literal>stable</literal> branch,
      Mercurial will choose the <quote>right</quote>

666:8fcd44708f41

    <para>Once you decide that you'd like to call a particular
      revision a <quote>release</quote>, it's a good idea to record
      the identity of that revision. This will let you reproduce that
      release at a later date, for whatever purpose you might need at
      the time (reproducing a bug, porting to a new platform, etc).
      &interaction.tag.init;</para>

    <para>Mercurial lets you give a permanent name to any revision
      using the <command role="hg-cmd">hg tag</command> command.  Not
      surprisingly, these names are called <quote>tags</quote>.</para>

    &interaction.tag.tag;

    <para>A tag is nothing more than a <quote>symbolic name</quote>
      for a revision.  Tags exist purely for your convenience, so that
      you have a handy permanent way to refer to a revision; Mercurial
      doesn't interpret the tag names you use in any way.  Neither

    <para>You can use the <command role="hg-cmd">hg tags</command>
      command to display the tags present in your repository.  In the
      output, each tagged revision is identified first by its name,
      then by revision number, and finally by the unique hash of the
      revision.</para>

    &interaction.tag.tags;

    <para>Notice that <literal>tip</literal> is listed in the output
      of <command role="hg-cmd">hg tags</command>.  The
      <literal>tip</literal> tag is a special <quote>floating</quote>
      tag, which always identifies the newest revision in the
      repository.</para>

    <para>In the output of the <command role="hg-cmd">hg
	tags</command> command, tags are listed in reverse order, by
      revision number.  This usually means that recent tags are listed
      before older tags.  It also means that <literal>tip</literal> is
      always going to be the first tag listed in the output of
      <command role="hg-cmd">hg tags</command>.</para>

    <para>When you run <command role="hg-cmd">hg log</command>, if it
      displays a revision that has tags associated with it, it will
      print those tags.</para>

    &interaction.tag.log;

    <para>Any time you need to provide a revision ID to a Mercurial
      command, the command will accept a tag name in its place.
      Internally, Mercurial will translate your tag name into the
      corresponding revision ID, then use that.</para>

    &interaction.tag.log.v1.0;

    <para>There's no limit on the number of tags you can have in a
      repository, or on the number of tags that a single revision can
      have.  As a practical matter, it's not a great idea to have
      <quote>too many</quote> (a number which will vary from project

      lot of noise if you were to tag every clean build.  Instead, you
      could tag failed builds (on the assumption that they're rare!),
      or simply not use tags to track buildability.</para>

    <para>If you want to remove a tag that you no longer want, use
      <command role="hg-cmd">hg tag --remove</command>.</para>

    &interaction.tag.remove;

    <para>You can also modify a tag at any time, so that it identifies
      a different revision, by simply issuing a new <command
	role="hg-cmd">hg tag</command> command. You'll have to use the
      <option role="hg-opt-tag">-f</option> option to tell Mercurial
      that you <emphasis>really</emphasis> want to update the
      tag.</para>

    &interaction.tag.replace;

    <para>There will still be a permanent record of the previous
      identity of the tag, but Mercurial will no longer use it.
      There's thus no penalty to tagging the wrong revision; all you
      have to do is turn around and tag the correct revision once you
      discover your error.</para>

    <para>Mercurial stores tags in a normal revision-controlled file
      in your repository.  If you've created any tags, you'll find
      them in a file named <filename
	role="special">.hgtags</filename>.  When you run the <command
	role="hg-cmd">hg tag</command> command, Mercurial modifies
      this file, then automatically commits the change to it.  This
      means that every time you run <command role="hg-cmd">hg
	tag</command>, you'll see a corresponding changeset in the
      output of <command role="hg-cmd">hg log</command>.</para>

    &interaction.tag.tip;

    <sect2>
      <title>Handling tag conflicts during a merge</title>

      <para>You won't often need to care about the <filename

      branch in Mercurial is in a dedicated repository.  If you have
      an existing shared repository&emdash;let's call it
      <literal>myproject</literal>&emdash;that reaches a
      <quote>1.0</quote> milestone, you can start to prepare for
      future maintenance releases on top of version 1.0 by tagging the
      revision from which you prepared the 1.0 release.</para>

    &interaction.branch-repo.tag;

    <para>You can then clone a new shared
      <literal>myproject-1.0.1</literal> repository as of that
      tag.</para>

    &interaction.branch-repo.clone;

    <para>Afterwards, if someone needs to work on a bug fix that ought
      to go into an upcoming 1.0.1 minor release, they clone the
      <literal>myproject-1.0.1</literal> repository, make their
      changes, and push them back.</para>

    &interaction.branch-repo.bugfix;

    <para>Meanwhile, development for
      the next major release can continue, isolated and unabated, in
      the <literal>myproject</literal> repository.</para>

    &interaction.branch-repo.new;

  </sect1>
  <sect1>
    <title>Don't repeat yourself: merging across branches</title>

      help you to manage these bugfixes without duplicating your
      work.</para>

    <para>In the simplest instance, all you need to do is pull changes
      from your maintenance branch into your local clone of the target
      branch.</para>

    &interaction.branch-repo.pull;

    <para>You'll then need to merge the heads of the two branches, and
      push back to the main branch.</para>

    &interaction.branch-repo.merge;

  </sect1>
  <sect1>
    <title>Naming branches within one repository</title>

      the branch named <literal>default</literal>.</para>

    <para>To start working with named branches, use the <command
	role="hg-cmd">hg branches</command> command.  This command
      lists the named branches already present in your repository,
      telling you which changeset is the tip of each.</para>

    &interaction.branch-named.branches;

    <para>Since you haven't created any named branches yet, the only
      one that exists is <literal>default</literal>.</para>

    <para>To find out what the <quote>current</quote> branch is, run
      the <command role="hg-cmd">hg branch</command> command, giving
      it no arguments.  This tells you what branch the parent of the
      current changeset is on.</para>

    &interaction.branch-named.branch;

    <para>To create a new branch, run the <command role="hg-cmd">hg
	branch</command> command again.  This time, give it one
      argument: the name of the branch you want to create.</para>

    &interaction.branch-named.create;

    <para>After you've created a branch, you might wonder what effect
      the <command role="hg-cmd">hg branch</command> command has had.
      What do the <command role="hg-cmd">hg status</command> and
      <command role="hg-cmd">hg tip</command> commands report?</para>

    &interaction.branch-named.status;

    <para>Nothing has changed in the
      working directory, and there's been no new history created.  As
      this suggests, running the <command role="hg-cmd">hg
	branch</command> command has no permanent effect; it only
      tells Mercurial what branch name to use the
      <emphasis>next</emphasis> time you commit a changeset.</para>

      branch on which you committed.  Once you've switched from the
      <literal>default</literal> branch to another and committed,
      you'll see the name of the new branch show up in the output of
      <command role="hg-cmd">hg log</command>, <command
	role="hg-cmd">hg tip</command>, and other commands that
      display the same kind of output.</para>

    &interaction.branch-named.commit;

    <para>The <command role="hg-cmd">hg log</command>-like commands
      will print the branch name of every changeset that's not on the
      <literal>default</literal> branch.  As a result, if you never
      use named branches, you'll never see this information.</para>

    <para>Once you've named a branch and committed a change with that
      name, every subsequent commit that descends from that change
      will inherit the same branch name.  You can change the name of a
      branch at any time, using the <command role="hg-cmd">hg
	branch</command> command.</para>

    &interaction.branch-named.rebranch;

    <para>In practice, this is something you won't do very often, as
      branch names tend to have fairly long lifetimes.  (This isn't a
      rule, just an observation.)</para>

  </sect1>
  <sect1>
    <title>Dealing with multiple named branches in a
      repository</title>

      you may need to use the <option role="hg-opt-update">-C</option>
      option to <command role="hg-cmd">hg update</command>.</para>

    <para>This behaviour is a little subtle, so let's see it in
      action.  First, let's remind ourselves what branch we're
      currently on, and what branches are in our repository.</para>

    &interaction.branch-named.parents;

    <para>We're on the <literal>bar</literal> branch, but there also
      exists an older <command role="hg-cmd">hg foo</command>
      branch.</para>

    <para>We can <command role="hg-cmd">hg update</command> back and
      forth between the tips of the <literal>foo</literal> and
      <literal>bar</literal> branches without needing to use the
      <option role="hg-opt-update">-C</option> option, because this
      only involves going backwards and forwards linearly through our
      change history.</para>

    &interaction.branch-named.update-switchy;

    <para>If we go back to the <literal>foo</literal> branch and then
      run <command role="hg-cmd">hg update</command>, it will keep us
      on <literal>foo</literal>, not move us to the tip of
      <literal>bar</literal>.</para>

    &interaction.branch-named.update-nothing;

    <para>Committing a new change on the <literal>foo</literal> branch
      introduces a new head.</para>

    &interaction.branch-named.foo-commit;

  </sect1>
  <sect1>
    <title>Branch names and merging</title>

      result of a merge will be a single head on the
      <literal>foo</literal> branch, as you might hope.</para>

    <para>But if I'm working on the <literal>bar</literal> branch, and
      I merge work from the <literal>foo</literal> branch, the result
      will remain on the <literal>bar</literal> branch.</para>

    &interaction.branch-named.merge;

    <para>To give a more concrete example, if I'm working on the
      <literal>bleeding-edge</literal> branch, and I want to bring in
      the latest fixes from the <literal>stable</literal> branch,
      Mercurial will choose the <quote>right</quote>