1.1 --- a/en/ch07-branch.xml	Thu Mar 19 20:54:12 2009 -0700
     1.2 +++ b/en/ch07-branch.xml	Thu Mar 26 22:07:30 2009 -0700
     1.3 @@ -4,18 +4,18 @@
     1.4    <?dbhtml filename="managing-releases-and-branchy-development.html"?>
     1.5    <title>Managing releases and branchy development</title>
     1.6  
     1.7 -  <para>Mercurial provides several mechanisms for you to manage a
     1.8 +  <para id="x_369">Mercurial provides several mechanisms for you to manage a
     1.9      project that is making progress on multiple fronts at once.  To
    1.10      understand these mechanisms, let's first take a brief look at a
    1.11      fairly normal software project structure.</para>
    1.12  
    1.13 -  <para>Many software projects issue periodic <quote>major</quote>
    1.14 +  <para id="x_36a">Many software projects issue periodic <quote>major</quote>
    1.15      releases that contain substantial new features.  In parallel, they
    1.16      may issue <quote>minor</quote> releases.  These are usually
    1.17      identical to the major releases off which they're based, but with
    1.18      a few bugs fixed.</para>
    1.19  
    1.20 -  <para>In this chapter, we'll start by talking about how to keep
    1.21 +  <para id="x_36b">In this chapter, we'll start by talking about how to keep
    1.22      records of project milestones such as releases.  We'll then
    1.23      continue on to talk about the flow of work between different
    1.24      phases of a project, and how Mercurial can help you to isolate and
    1.25 @@ -24,20 +24,20 @@
    1.26    <sect1>
    1.27      <title>Giving a persistent name to a revision</title>
    1.28  
    1.29 -    <para>Once you decide that you'd like to call a particular
    1.30 +    <para id="x_36c">Once you decide that you'd like to call a particular
    1.31        revision a <quote>release</quote>, it's a good idea to record
    1.32        the identity of that revision. This will let you reproduce that
    1.33        release at a later date, for whatever purpose you might need at
    1.34        the time (reproducing a bug, porting to a new platform, etc).
    1.35        &interaction.tag.init;</para>
    1.36  
    1.37 -    <para>Mercurial lets you give a permanent name to any revision
    1.38 +    <para id="x_36d">Mercurial lets you give a permanent name to any revision
    1.39        using the <command role="hg-cmd">hg tag</command> command.  Not
    1.40        surprisingly, these names are called <quote>tags</quote>.</para>
    1.41  
    1.42      &interaction.tag.tag;
    1.43  
    1.44 -    <para>A tag is nothing more than a <quote>symbolic name</quote>
    1.45 +    <para id="x_36e">A tag is nothing more than a <quote>symbolic name</quote>
    1.46        for a revision.  Tags exist purely for your convenience, so that
    1.47        you have a handy permanent way to refer to a revision; Mercurial
    1.48        doesn't interpret the tag names you use in any way.  Neither
    1.49 @@ -46,17 +46,17 @@
    1.50        parsed unambiguously.  A tag name cannot contain any of the
    1.51        following characters:</para>
    1.52      <itemizedlist>
    1.53 -      <listitem><para>Colon (ASCII 58,
    1.54 +      <listitem><para id="x_36f">Colon (ASCII 58,
    1.55  	  <quote><literal>:</literal></quote>)</para>
    1.56        </listitem>
    1.57 -      <listitem><para>Carriage return (ASCII 13,
    1.58 +      <listitem><para id="x_370">Carriage return (ASCII 13,
    1.59  	  <quote><literal>\r</literal></quote>)</para>
    1.60        </listitem>
    1.61 -      <listitem><para>Newline (ASCII 10,
    1.62 +      <listitem><para id="x_371">Newline (ASCII 10,
    1.63  	  <quote><literal>\n</literal></quote>)</para>
    1.64        </listitem></itemizedlist>
    1.65  
    1.66 -    <para>You can use the <command role="hg-cmd">hg tags</command>
    1.67 +    <para id="x_372">You can use the <command role="hg-cmd">hg tags</command>
    1.68        command to display the tags present in your repository.  In the
    1.69        output, each tagged revision is identified first by its name,
    1.70        then by revision number, and finally by the unique hash of the
    1.71 @@ -64,33 +64,33 @@
    1.72  
    1.73      &interaction.tag.tags;
    1.74  
    1.75 -    <para>Notice that <literal>tip</literal> is listed in the output
    1.76 +    <para id="x_373">Notice that <literal>tip</literal> is listed in the output
    1.77        of <command role="hg-cmd">hg tags</command>.  The
    1.78        <literal>tip</literal> tag is a special <quote>floating</quote>
    1.79        tag, which always identifies the newest revision in the
    1.80        repository.</para>
    1.81  
    1.82 -    <para>In the output of the <command role="hg-cmd">hg
    1.83 +    <para id="x_374">In the output of the <command role="hg-cmd">hg
    1.84  	tags</command> command, tags are listed in reverse order, by
    1.85        revision number.  This usually means that recent tags are listed
    1.86        before older tags.  It also means that <literal>tip</literal> is
    1.87        always going to be the first tag listed in the output of
    1.88        <command role="hg-cmd">hg tags</command>.</para>
    1.89  
    1.90 -    <para>When you run <command role="hg-cmd">hg log</command>, if it
    1.91 +    <para id="x_375">When you run <command role="hg-cmd">hg log</command>, if it
    1.92        displays a revision that has tags associated with it, it will
    1.93        print those tags.</para>
    1.94  
    1.95      &interaction.tag.log;
    1.96  
    1.97 -    <para>Any time you need to provide a revision ID to a Mercurial
    1.98 +    <para id="x_376">Any time you need to provide a revision ID to a Mercurial
    1.99        command, the command will accept a tag name in its place.
   1.100        Internally, Mercurial will translate your tag name into the
   1.101        corresponding revision ID, then use that.</para>
   1.102  
   1.103      &interaction.tag.log.v1.0;
   1.104  
   1.105 -    <para>There's no limit on the number of tags you can have in a
   1.106 +    <para id="x_377">There's no limit on the number of tags you can have in a
   1.107        repository, or on the number of tags that a single revision can
   1.108        have.  As a practical matter, it's not a great idea to have
   1.109        <quote>too many</quote> (a number which will vary from project
   1.110 @@ -98,7 +98,7 @@
   1.111        find revisions.  If you have lots of tags, the ease of using
   1.112        them to identify revisions diminishes rapidly.</para>
   1.113  
   1.114 -    <para>For example, if your project has milestones as frequent as
   1.115 +    <para id="x_378">For example, if your project has milestones as frequent as
   1.116        every few days, it's perfectly reasonable to tag each one of
   1.117        those.  But if you have a continuous build system that makes
   1.118        sure every revision can be built cleanly, you'd be introducing a
   1.119 @@ -106,12 +106,12 @@
   1.120        could tag failed builds (on the assumption that they're rare!),
   1.121        or simply not use tags to track buildability.</para>
   1.122  
   1.123 -    <para>If you want to remove a tag that you no longer want, use
   1.124 +    <para id="x_379">If you want to remove a tag that you no longer want, use
   1.125        <command role="hg-cmd">hg tag --remove</command>.</para>
   1.126  
   1.127      &interaction.tag.remove;
   1.128  
   1.129 -    <para>You can also modify a tag at any time, so that it identifies
   1.130 +    <para id="x_37a">You can also modify a tag at any time, so that it identifies
   1.131        a different revision, by simply issuing a new <command
   1.132  	role="hg-cmd">hg tag</command> command. You'll have to use the
   1.133        <option role="hg-opt-tag">-f</option> option to tell Mercurial
   1.134 @@ -120,13 +120,13 @@
   1.135  
   1.136      &interaction.tag.replace;
   1.137  
   1.138 -    <para>There will still be a permanent record of the previous
   1.139 +    <para id="x_37b">There will still be a permanent record of the previous
   1.140        identity of the tag, but Mercurial will no longer use it.
   1.141        There's thus no penalty to tagging the wrong revision; all you
   1.142        have to do is turn around and tag the correct revision once you
   1.143        discover your error.</para>
   1.144  
   1.145 -    <para>Mercurial stores tags in a normal revision-controlled file
   1.146 +    <para id="x_37c">Mercurial stores tags in a normal revision-controlled file
   1.147        in your repository.  If you've created any tags, you'll find
   1.148        them in a file named <filename
   1.149  	role="special">.hgtags</filename>.  When you run the <command
   1.150 @@ -141,14 +141,14 @@
   1.151      <sect2>
   1.152        <title>Handling tag conflicts during a merge</title>
   1.153  
   1.154 -      <para>You won't often need to care about the <filename
   1.155 +      <para id="x_37d">You won't often need to care about the <filename
   1.156  	  role="special">.hgtags</filename> file, but it sometimes
   1.157  	makes its presence known during a merge.  The format of the
   1.158  	file is simple: it consists of a series of lines.  Each line
   1.159  	starts with a changeset hash, followed by a space, followed by
   1.160  	the name of a tag.</para>
   1.161  
   1.162 -      <para>If you're resolving a conflict in the <filename
   1.163 +      <para id="x_37e">If you're resolving a conflict in the <filename
   1.164  	  role="special">.hgtags</filename> file during a merge,
   1.165  	there's one twist to modifying the <filename
   1.166  	  role="special">.hgtags</filename> file: when Mercurial is
   1.167 @@ -158,7 +158,7 @@
   1.168  	reads the <emphasis>most recently committed</emphasis>
   1.169  	revision of the file.</para>
   1.170  
   1.171 -      <para>An unfortunate consequence of this design is that you
   1.172 +      <para id="x_37f">An unfortunate consequence of this design is that you
   1.173  	can't actually verify that your merged <filename
   1.174  	  role="special">.hgtags</filename> file is correct until
   1.175  	<emphasis>after</emphasis> you've committed a change.  So if
   1.176 @@ -175,7 +175,7 @@
   1.177      <sect2>
   1.178        <title>Tags and cloning</title>
   1.179  
   1.180 -      <para>You may have noticed that the <command role="hg-cmd">hg
   1.181 +      <para id="x_380">You may have noticed that the <command role="hg-cmd">hg
   1.182  	  clone</command> command has a <option
   1.183  	  role="hg-opt-clone">-r</option> option that lets you clone
   1.184  	an exact copy of the repository as of a particular changeset.
   1.185 @@ -183,7 +183,7 @@
   1.186  	after the revision you specified.  This has an interaction
   1.187  	with tags that can surprise the unwary.</para>
   1.188  
   1.189 -      <para>Recall that a tag is stored as a revision to the <filename
   1.190 +      <para id="x_381">Recall that a tag is stored as a revision to the <filename
   1.191  	  role="special">.hgtags</filename> file, so that when you
   1.192  	create a tag, the changeset in which it's recorded necessarily
   1.193  	refers to an older changeset.  When you run <command
   1.194 @@ -200,7 +200,7 @@
   1.195      <sect2>
   1.196        <title>When permanent tags are too much</title>
   1.197  
   1.198 -      <para>Since Mercurial's tags are revision controlled and carried
   1.199 +      <para id="x_382">Since Mercurial's tags are revision controlled and carried
   1.200  	around with a project's history, everyone you work with will
   1.201  	see the tags you create.  But giving names to revisions has
   1.202  	uses beyond simply noting that revision
   1.203 @@ -210,7 +210,7 @@
   1.204  	like <quote>Anne saw the symptoms with this
   1.205  	  revision</quote>.</para>
   1.206  
   1.207 -      <para>For cases like this, what you might want to use are
   1.208 +      <para id="x_383">For cases like this, what you might want to use are
   1.209  	<emphasis>local</emphasis> tags. You can create a local tag
   1.210  	with the <option role="hg-opt-tag">-l</option> option to the
   1.211  	<command role="hg-cmd">hg tag</command> command.  This will
   1.212 @@ -227,27 +227,27 @@
   1.213    <sect1>
   1.214      <title>The flow of changes&emdash;big picture vs. little</title>
   1.215  
   1.216 -    <para>To return to the outline I sketched at the beginning of a
   1.217 +    <para id="x_384">To return to the outline I sketched at the beginning of a
   1.218        chapter, let's think about a project that has multiple
   1.219        concurrent pieces of work under development at once.</para>
   1.220  
   1.221 -    <para>There might be a push for a new <quote>main</quote> release;
   1.222 +    <para id="x_385">There might be a push for a new <quote>main</quote> release;
   1.223        a new minor bugfix release to the last main release; and an
   1.224        unexpected <quote>hot fix</quote> to an old release that is now
   1.225        in maintenance mode.</para>
   1.226  
   1.227 -    <para>The usual way people refer to these different concurrent
   1.228 +    <para id="x_386">The usual way people refer to these different concurrent
   1.229        directions of development is as <quote>branches</quote>.
   1.230        However, we've already seen numerous times that Mercurial treats
   1.231        <emphasis>all of history</emphasis> as a series of branches and
   1.232        merges.  Really, what we have here is two ideas that are
   1.233        peripherally related, but which happen to share a name.</para>
   1.234      <itemizedlist>
   1.235 -      <listitem><para><quote>Big picture</quote> branches represent
   1.236 +      <listitem><para id="x_387"><quote>Big picture</quote> branches represent
   1.237  	  the sweep of a project's evolution; people give them names,
   1.238  	  and talk about them in conversation.</para>
   1.239        </listitem>
   1.240 -      <listitem><para><quote>Little picture</quote> branches are
   1.241 +      <listitem><para id="x_388"><quote>Little picture</quote> branches are
   1.242  	  artefacts of the day-to-day activity of developing and
   1.243  	  merging changes.  They expose the narrative of how the code
   1.244  	  was developed.</para>
   1.245 @@ -257,7 +257,7 @@
   1.246    <sect1>
   1.247      <title>Managing big-picture branches in repositories</title>
   1.248  
   1.249 -    <para>The easiest way to isolate a <quote>big picture</quote>
   1.250 +    <para id="x_389">The easiest way to isolate a <quote>big picture</quote>
   1.251        branch in Mercurial is in a dedicated repository.  If you have
   1.252        an existing shared repository&emdash;let's call it
   1.253        <literal>myproject</literal>&emdash;that reaches a
   1.254 @@ -267,20 +267,20 @@
   1.255  
   1.256      &interaction.branch-repo.tag;
   1.257  
   1.258 -    <para>You can then clone a new shared
   1.259 +    <para id="x_38a">You can then clone a new shared
   1.260        <literal>myproject-1.0.1</literal> repository as of that
   1.261        tag.</para>
   1.262  
   1.263      &interaction.branch-repo.clone;
   1.264  
   1.265 -    <para>Afterwards, if someone needs to work on a bug fix that ought
   1.266 +    <para id="x_38b">Afterwards, if someone needs to work on a bug fix that ought
   1.267        to go into an upcoming 1.0.1 minor release, they clone the
   1.268        <literal>myproject-1.0.1</literal> repository, make their
   1.269        changes, and push them back.</para>
   1.270  
   1.271      &interaction.branch-repo.bugfix;
   1.272  
   1.273 -    <para>Meanwhile, development for
   1.274 +    <para id="x_38c">Meanwhile, development for
   1.275        the next major release can continue, isolated and unabated, in
   1.276        the <literal>myproject</literal> repository.</para>
   1.277  
   1.278 @@ -290,7 +290,7 @@
   1.279    <sect1>
   1.280      <title>Don't repeat yourself: merging across branches</title>
   1.281  
   1.282 -    <para>In many cases, if you have a bug to fix on a maintenance
   1.283 +    <para id="x_38d">In many cases, if you have a bug to fix on a maintenance
   1.284        branch, the chances are good that the bug exists on your
   1.285        project's main branch (and possibly other maintenance branches,
   1.286        too).  It's a rare developer who wants to fix the same bug
   1.287 @@ -298,13 +298,13 @@
   1.288        help you to manage these bugfixes without duplicating your
   1.289        work.</para>
   1.290  
   1.291 -    <para>In the simplest instance, all you need to do is pull changes
   1.292 +    <para id="x_38e">In the simplest instance, all you need to do is pull changes
   1.293        from your maintenance branch into your local clone of the target
   1.294        branch.</para>
   1.295  
   1.296      &interaction.branch-repo.pull;
   1.297  
   1.298 -    <para>You'll then need to merge the heads of the two branches, and
   1.299 +    <para id="x_38f">You'll then need to merge the heads of the two branches, and
   1.300        push back to the main branch.</para>
   1.301  
   1.302      &interaction.branch-repo.merge;
   1.303 @@ -313,14 +313,14 @@
   1.304    <sect1>
   1.305      <title>Naming branches within one repository</title>
   1.306  
   1.307 -    <para>In most instances, isolating branches in repositories is the
   1.308 +    <para id="x_390">In most instances, isolating branches in repositories is the
   1.309        right approach.  Its simplicity makes it easy to understand; and
   1.310        so it's hard to make mistakes.  There's a one-to-one
   1.311        relationship between branches you're working in and directories
   1.312        on your system.  This lets you use normal (non-Mercurial-aware)
   1.313        tools to work on files within a branch/repository.</para>
   1.314  
   1.315 -    <para>If you're more in the <quote>power user</quote> category
   1.316 +    <para id="x_391">If you're more in the <quote>power user</quote> category
   1.317        (<emphasis>and</emphasis> your collaborators are too), there is
   1.318        an alternative way of handling branches that you can consider.
   1.319        I've already mentioned the human-level distinction between
   1.320 @@ -331,58 +331,58 @@
   1.321        it can <emphasis>also</emphasis> work with multiple <quote>big
   1.322  	picture</quote> branches.</para>
   1.323  
   1.324 -    <para>The key to working this way is that Mercurial lets you
   1.325 +    <para id="x_392">The key to working this way is that Mercurial lets you
   1.326        assign a persistent <emphasis>name</emphasis> to a branch.
   1.327        There always exists a branch named <literal>default</literal>.
   1.328        Even before you start naming branches yourself, you can find
   1.329        traces of the <literal>default</literal> branch if you look for
   1.330        them.</para>
   1.331  
   1.332 -    <para>As an example, when you run the <command role="hg-cmd">hg
   1.333 +    <para id="x_393">As an example, when you run the <command role="hg-cmd">hg
   1.334  	commit</command> command, and it pops up your editor so that
   1.335        you can enter a commit message, look for a line that contains
   1.336        the text <quote><literal>HG: branch default</literal></quote> at
   1.337        the bottom. This is telling you that your commit will occur on
   1.338        the branch named <literal>default</literal>.</para>
   1.339  
   1.340 -    <para>To start working with named branches, use the <command
   1.341 +    <para id="x_394">To start working with named branches, use the <command
   1.342  	role="hg-cmd">hg branches</command> command.  This command
   1.343        lists the named branches already present in your repository,
   1.344        telling you which changeset is the tip of each.</para>
   1.345  
   1.346      &interaction.branch-named.branches;
   1.347  
   1.348 -    <para>Since you haven't created any named branches yet, the only
   1.349 +    <para id="x_395">Since you haven't created any named branches yet, the only
   1.350        one that exists is <literal>default</literal>.</para>
   1.351  
   1.352 -    <para>To find out what the <quote>current</quote> branch is, run
   1.353 +    <para id="x_396">To find out what the <quote>current</quote> branch is, run
   1.354        the <command role="hg-cmd">hg branch</command> command, giving
   1.355        it no arguments.  This tells you what branch the parent of the
   1.356        current changeset is on.</para>
   1.357  
   1.358      &interaction.branch-named.branch;
   1.359  
   1.360 -    <para>To create a new branch, run the <command role="hg-cmd">hg
   1.361 +    <para id="x_397">To create a new branch, run the <command role="hg-cmd">hg
   1.362  	branch</command> command again.  This time, give it one
   1.363        argument: the name of the branch you want to create.</para>
   1.364  
   1.365      &interaction.branch-named.create;
   1.366  
   1.367 -    <para>After you've created a branch, you might wonder what effect
   1.368 +    <para id="x_398">After you've created a branch, you might wonder what effect
   1.369        the <command role="hg-cmd">hg branch</command> command has had.
   1.370        What do the <command role="hg-cmd">hg status</command> and
   1.371        <command role="hg-cmd">hg tip</command> commands report?</para>
   1.372  
   1.373      &interaction.branch-named.status;
   1.374  
   1.375 -    <para>Nothing has changed in the
   1.376 +    <para id="x_399">Nothing has changed in the
   1.377        working directory, and there's been no new history created.  As
   1.378        this suggests, running the <command role="hg-cmd">hg
   1.379  	branch</command> command has no permanent effect; it only
   1.380        tells Mercurial what branch name to use the
   1.381        <emphasis>next</emphasis> time you commit a changeset.</para>
   1.382  
   1.383 -    <para>When you commit a change, Mercurial records the name of the
   1.384 +    <para id="x_39a">When you commit a change, Mercurial records the name of the
   1.385        branch on which you committed.  Once you've switched from the
   1.386        <literal>default</literal> branch to another and committed,
   1.387        you'll see the name of the new branch show up in the output of
   1.388 @@ -392,12 +392,12 @@
   1.389  
   1.390      &interaction.branch-named.commit;
   1.391  
   1.392 -    <para>The <command role="hg-cmd">hg log</command>-like commands
   1.393 +    <para id="x_39b">The <command role="hg-cmd">hg log</command>-like commands
   1.394        will print the branch name of every changeset that's not on the
   1.395        <literal>default</literal> branch.  As a result, if you never
   1.396        use named branches, you'll never see this information.</para>
   1.397  
   1.398 -    <para>Once you've named a branch and committed a change with that
   1.399 +    <para id="x_39c">Once you've named a branch and committed a change with that
   1.400        name, every subsequent commit that descends from that change
   1.401        will inherit the same branch name.  You can change the name of a
   1.402        branch at any time, using the <command role="hg-cmd">hg
   1.403 @@ -405,7 +405,7 @@
   1.404  
   1.405      &interaction.branch-named.rebranch;
   1.406  
   1.407 -    <para>In practice, this is something you won't do very often, as
   1.408 +    <para id="x_39d">In practice, this is something you won't do very often, as
   1.409        branch names tend to have fairly long lifetimes.  (This isn't a
   1.410        rule, just an observation.)</para>
   1.411  
   1.412 @@ -414,7 +414,7 @@
   1.413      <title>Dealing with multiple named branches in a
   1.414        repository</title>
   1.415  
   1.416 -    <para>If you have more than one named branch in a repository,
   1.417 +    <para id="x_39e">If you have more than one named branch in a repository,
   1.418        Mercurial will remember the branch that your working directory
   1.419        on when you start a command like <command role="hg-cmd">hg
   1.420  	update</command> or <command role="hg-cmd">hg pull
   1.421 @@ -424,17 +424,17 @@
   1.422        you may need to use the <option role="hg-opt-update">-C</option>
   1.423        option to <command role="hg-cmd">hg update</command>.</para>
   1.424  
   1.425 -    <para>This behaviour is a little subtle, so let's see it in
   1.426 +    <para id="x_39f">This behaviour is a little subtle, so let's see it in
   1.427        action.  First, let's remind ourselves what branch we're
   1.428        currently on, and what branches are in our repository.</para>
   1.429  
   1.430      &interaction.branch-named.parents;
   1.431  
   1.432 -    <para>We're on the <literal>bar</literal> branch, but there also
   1.433 +    <para id="x_3a0">We're on the <literal>bar</literal> branch, but there also
   1.434        exists an older <command role="hg-cmd">hg foo</command>
   1.435        branch.</para>
   1.436  
   1.437 -    <para>We can <command role="hg-cmd">hg update</command> back and
   1.438 +    <para id="x_3a1">We can <command role="hg-cmd">hg update</command> back and
   1.439        forth between the tips of the <literal>foo</literal> and
   1.440        <literal>bar</literal> branches without needing to use the
   1.441        <option role="hg-opt-update">-C</option> option, because this
   1.442 @@ -443,14 +443,14 @@
   1.443  
   1.444      &interaction.branch-named.update-switchy;
   1.445  
   1.446 -    <para>If we go back to the <literal>foo</literal> branch and then
   1.447 +    <para id="x_3a2">If we go back to the <literal>foo</literal> branch and then
   1.448        run <command role="hg-cmd">hg update</command>, it will keep us
   1.449        on <literal>foo</literal>, not move us to the tip of
   1.450        <literal>bar</literal>.</para>
   1.451  
   1.452      &interaction.branch-named.update-nothing;
   1.453  
   1.454 -    <para>Committing a new change on the <literal>foo</literal> branch
   1.455 +    <para id="x_3a3">Committing a new change on the <literal>foo</literal> branch
   1.456        introduces a new head.</para>
   1.457  
   1.458      &interaction.branch-named.foo-commit;
   1.459 @@ -459,7 +459,7 @@
   1.460    <sect1>
   1.461      <title>Branch names and merging</title>
   1.462  
   1.463 -    <para>As you've probably noticed, merges in Mercurial are not
   1.464 +    <para id="x_3a4">As you've probably noticed, merges in Mercurial are not
   1.465        symmetrical. Let's say our repository has two heads, 17 and 23.
   1.466        If I <command role="hg-cmd">hg update</command> to 17 and then
   1.467        <command role="hg-cmd">hg merge</command> with 23, Mercurial
   1.468 @@ -469,14 +469,14 @@
   1.469        17, it records 23 as the first parent, and 17 as the
   1.470        second.</para>
   1.471  
   1.472 -    <para>This affects Mercurial's choice of branch name when you
   1.473 +    <para id="x_3a5">This affects Mercurial's choice of branch name when you
   1.474        merge.  After a merge, Mercurial will retain the branch name of
   1.475        the first parent when you commit the result of the merge.  If
   1.476        your first parent's branch name is <literal>foo</literal>, and
   1.477        you merge with <literal>bar</literal>, the branch name will
   1.478        still be <literal>foo</literal> after you merge.</para>
   1.479  
   1.480 -    <para>It's not unusual for a repository to contain multiple heads,
   1.481 +    <para id="x_3a6">It's not unusual for a repository to contain multiple heads,
   1.482        each with the same branch name.  Let's say I'm working on the
   1.483        <literal>foo</literal> branch, and so are you.  We commit
   1.484        different changes; I pull your changes; I now have two heads,
   1.485 @@ -484,13 +484,13 @@
   1.486        result of a merge will be a single head on the
   1.487        <literal>foo</literal> branch, as you might hope.</para>
   1.488  
   1.489 -    <para>But if I'm working on the <literal>bar</literal> branch, and
   1.490 +    <para id="x_3a7">But if I'm working on the <literal>bar</literal> branch, and
   1.491        I merge work from the <literal>foo</literal> branch, the result
   1.492        will remain on the <literal>bar</literal> branch.</para>
   1.493  
   1.494      &interaction.branch-named.merge;
   1.495  
   1.496 -    <para>To give a more concrete example, if I'm working on the
   1.497 +    <para id="x_3a8">To give a more concrete example, if I'm working on the
   1.498        <literal>bleeding-edge</literal> branch, and I want to bring in
   1.499        the latest fixes from the <literal>stable</literal> branch,
   1.500        Mercurial will choose the <quote>right</quote>
   1.501 @@ -501,17 +501,17 @@
   1.502    <sect1>
   1.503      <title>Branch naming is generally useful</title>
   1.504  
   1.505 -    <para>You shouldn't think of named branches as applicable only to
   1.506 +    <para id="x_3a9">You shouldn't think of named branches as applicable only to
   1.507        situations where you have multiple long-lived branches
   1.508        cohabiting in a single repository.  They're very useful even in
   1.509        the one-branch-per-repository case.</para>
   1.510  
   1.511 -    <para>In the simplest case, giving a name to each branch gives you
   1.512 +    <para id="x_3aa">In the simplest case, giving a name to each branch gives you
   1.513        a permanent record of which branch a changeset originated on.
   1.514        This gives you more context when you're trying to follow the
   1.515        history of a long-lived branchy project.</para>
   1.516  
   1.517 -    <para>If you're working with shared repositories, you can set up a
   1.518 +    <para id="x_3ab">If you're working with shared repositories, you can set up a
   1.519        <literal role="hook">pretxnchangegroup</literal> hook on each
   1.520        that will block incoming changes that have the
   1.521        <quote>wrong</quote> branch name.  This provides a simple, but