1.1 --- a/fr/ch08-branch.xml	Sun Aug 16 04:58:01 2009 +0200
     1.2 +++ b/fr/ch08-branch.xml	Thu Apr 22 12:39:32 2010 +0200
     1.3 @@ -1,473 +1,533 @@
     1.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5  
     1.6 -<chapter>
     1.7 -<title>Managing releases and branchy development</title>
     1.8 -<para>\label{chap:branch}</para>
     1.9 -
    1.10 -<para>Mercurial provides several mechanisms for you to manage a project that
    1.11 -is making progress on multiple fronts at once.  To understand these
    1.12 -mechanisms, let's first take a brief look at a fairly normal software
    1.13 -project structure.</para>
    1.14 -
    1.15 -<para>Many software projects issue periodic <quote>major</quote> releases that contain
    1.16 -substantial new features.  In parallel, they may issue <quote>minor</quote>
    1.17 -releases.  These are usually identical to the major releases off which
    1.18 -they're based, but with a few bugs fixed.</para>
    1.19 -
    1.20 -<para>In this chapter, we'll start by talking about how to keep records of
    1.21 -project milestones such as releases.  We'll then continue on to talk
    1.22 -about the flow of work between different phases of a project, and how
    1.23 -Mercurial can help you to isolate and manage this work.</para>
    1.24 -
    1.25 -<sect1>
    1.26 -<title>Giving a persistent name to a revision</title>
    1.27 -
    1.28 -<para>Once you decide that you'd like to call a particular revision a
    1.29 -<quote>release</quote>, it's a good idea to record the identity of that revision.
    1.30 -This will let you reproduce that release at a later date, for whatever
    1.31 -purpose you might need at the time (reproducing a bug, porting to a
    1.32 -new platform, etc).
    1.33 -<!-- &interaction.tag.init; --></para>
    1.34 -
    1.35 -<para>Mercurial lets you give a permanent name to any revision using the
    1.36 -<command role="hg-cmd">hg tag</command> command.  Not surprisingly, these names are called
    1.37 -<quote>tags</quote>.
    1.38 -<!-- &interaction.tag.tag; --></para>
    1.39 -
    1.40 -<para>A tag is nothing more than a <quote>symbolic name</quote> for a revision.  Tags
    1.41 -exist purely for your convenience, so that you have a handy permanent
    1.42 -way to refer to a revision; Mercurial doesn't interpret the tag names
    1.43 -you use in any way.  Neither does Mercurial place any restrictions on
    1.44 -the name of a tag, beyond a few that are necessary to ensure that a
    1.45 -tag can be parsed unambiguously.  A tag name cannot contain any of the
    1.46 -following characters:</para>
    1.47 -<itemizedlist>
    1.48 -<listitem><para>Colon (ASCII 58, <quote><literal>:</literal></quote>)</para>
    1.49 -</listitem>
    1.50 -<listitem><para>Carriage return (ASCII 13, <quote><literal>\r</literal></quote>)
    1.51 -</para>
    1.52 -</listitem>
    1.53 -<listitem><para>Newline (ASCII 10, <quote><literal>\n</literal></quote>)
    1.54 -</para>
    1.55 -</listitem></itemizedlist>
    1.56 -
    1.57 -<para>You can use the <command role="hg-cmd">hg tags</command> command to display the tags present in
    1.58 -your repository.  In the output, each tagged revision is identified
    1.59 -first by its name, then by revision number, and finally by the unique
    1.60 -hash of the revision.
    1.61 -<!-- &interaction.tag.tags; -->
    1.62 -Notice that <literal>tip</literal> is listed in the output of <command role="hg-cmd">hg tags</command>.  The
    1.63 -<literal>tip</literal> tag is a special <quote>floating</quote> tag, which always
    1.64 -identifies the newest revision in the repository.
    1.65 -</para>
    1.66 -
    1.67 -<para>In the output of the <command role="hg-cmd">hg tags</command> command, tags are listed in reverse
    1.68 -order, by revision number.  This usually means that recent tags are
    1.69 -listed before older tags.  It also means that <literal>tip</literal> is always
    1.70 -going to be the first tag listed in the output of <command role="hg-cmd">hg tags</command>.
    1.71 -</para>
    1.72 -
    1.73 -<para>When you run <command role="hg-cmd">hg log</command>, if it displays a revision that has tags
    1.74 -associated with it, it will print those tags.
    1.75 -<!-- &interaction.tag.log; -->
    1.76 -</para>
    1.77 -
    1.78 -<para>Any time you need to provide a revision ID to a Mercurial command, the
    1.79 -command will accept a tag name in its place.  Internally, Mercurial
    1.80 -will translate your tag name into the corresponding revision ID, then
    1.81 -use that.
    1.82 -<!-- &interaction.tag.log.v1.0; -->
    1.83 -</para>
    1.84 -
    1.85 -<para>There's no limit on the number of tags you can have in a repository,
    1.86 -or on the number of tags that a single revision can have.  As a
    1.87 -practical matter, it's not a great idea to have <quote>too many</quote> (a number
    1.88 -which will vary from project to project), simply because tags are
    1.89 -supposed to help you to find revisions.  If you have lots of tags, the
    1.90 -ease of using them to identify revisions diminishes rapidly.
    1.91 -</para>
    1.92 -
    1.93 -<para>For example, if your project has milestones as frequent as every few
    1.94 -days, it's perfectly reasonable to tag each one of those.  But if you
    1.95 -have a continuous build system that makes sure every revision can be
    1.96 -built cleanly, you'd be introducing a lot of noise if you were to tag
    1.97 -every clean build.  Instead, you could tag failed builds (on the
    1.98 -assumption that they're rare!), or simply not use tags to track
    1.99 -buildability.
   1.100 -</para>
   1.101 -
   1.102 -<para>If you want to remove a tag that you no longer want, use
   1.103 -<command role="hg-cmd">hg tag --remove</command>.
   1.104 -<!-- &interaction.tag.remove; -->
   1.105 -You can also modify a tag at any time, so that it identifies a
   1.106 -different revision, by simply issuing a new <command role="hg-cmd">hg tag</command> command.
   1.107 -You'll have to use the <option role="hg-opt-tag">-f</option> option to tell Mercurial that
   1.108 -you <emphasis>really</emphasis> want to update the tag.
   1.109 -<!-- &interaction.tag.replace; -->
   1.110 -There will still be a permanent record of the previous identity of the
   1.111 -tag, but Mercurial will no longer use it.  There's thus no penalty to
   1.112 -tagging the wrong revision; all you have to do is turn around and tag
   1.113 -the correct revision once you discover your error.
   1.114 -</para>
   1.115 -
   1.116 -<para>Mercurial stores tags in a normal revision-controlled file in your
   1.117 -repository.  If you've created any tags, you'll find them in a file
   1.118 -named <filename role="special">.hgtags</filename>.  When you run the <command role="hg-cmd">hg tag</command> command,
   1.119 -Mercurial modifies this file, then automatically commits the change to
   1.120 -it.  This means that every time you run <command role="hg-cmd">hg tag</command>, you'll see a
   1.121 -corresponding changeset in the output of <command role="hg-cmd">hg log</command>.
   1.122 -<!-- &interaction.tag.tip; -->
   1.123 -</para>
   1.124 -
   1.125 -<sect2>
   1.126 -<title>Handling tag conflicts during a merge</title>
   1.127 -
   1.128 -<para>You won't often need to care about the <filename role="special">.hgtags</filename> file, but
   1.129 -it sometimes makes its presence known during a merge.  The format of
   1.130 -the file is simple: it consists of a series of lines.  Each line
   1.131 -starts with a changeset hash, followed by a space, followed by the
   1.132 -name of a tag.
   1.133 -</para>
   1.134 -
   1.135 -<para>If you're resolving a conflict in the <filename role="special">.hgtags</filename> file during
   1.136 -a merge, there's one twist to modifying the <filename role="special">.hgtags</filename> file:
   1.137 -when Mercurial is parsing the tags in a repository, it <emphasis>never</emphasis>
   1.138 -reads the working copy of the <filename role="special">.hgtags</filename> file.  Instead, it
   1.139 -reads the <emphasis>most recently committed</emphasis> revision of the file.
   1.140 -</para>
   1.141 -
   1.142 -<para>An unfortunate consequence of this design is that you can't actually
   1.143 -verify that your merged <filename role="special">.hgtags</filename> file is correct until
   1.144 -<emphasis>after</emphasis> you've committed a change.  So if you find yourself
   1.145 -resolving a conflict on <filename role="special">.hgtags</filename> during a merge, be sure to
   1.146 -run <command role="hg-cmd">hg tags</command> after you commit.  If it finds an error in the
   1.147 -<filename role="special">.hgtags</filename> file, it will report the location of the error,
   1.148 -which you can then fix and commit.  You should then run <command role="hg-cmd">hg tags</command>
   1.149 -again, just to be sure that your fix is correct.
   1.150 -</para>
   1.151 -
   1.152 -</sect2>
   1.153 -<sect2>
   1.154 -<title>Tags and cloning</title>
   1.155 -
   1.156 -<para>You may have noticed that the <command role="hg-cmd">hg clone</command> command has a
   1.157 -<option role="hg-opt-clone">-r</option> option that lets you clone an exact copy of the
   1.158 -repository as of a particular changeset.  The new clone will not
   1.159 -contain any project history that comes after the revision you
   1.160 -specified.  This has an interaction with tags that can surprise the
   1.161 -unwary.
   1.162 -</para>
   1.163 -
   1.164 -<para>Recall that a tag is stored as a revision to the <filename role="special">.hgtags</filename>
   1.165 -file, so that when you create a tag, the changeset in which it's
   1.166 -recorded necessarily refers to an older changeset.  When you run
   1.167 -<command role="hg-cmd">hg clone -r foo</command> to clone a repository as of tag
   1.168 -<literal>foo</literal>, the new clone \emph{will not contain the history that
   1.169 -  created the tag} that you used to clone the repository.  The result
   1.170 -is that you'll get exactly the right subset of the project's history
   1.171 -in the new repository, but <emphasis>not</emphasis> the tag you might have expected.
   1.172 -</para>
   1.173 -
   1.174 -</sect2>
   1.175 -<sect2>
   1.176 -<title>When permanent tags are too much</title>
   1.177 -
   1.178 -<para>Since Mercurial's tags are revision controlled and carried around with
   1.179 -a project's history, everyone you work with will see the tags you
   1.180 -create.  But giving names to revisions has uses beyond simply noting
   1.181 -that revision <literal>4237e45506ee</literal> is really <literal>v2.0.2</literal>.  If
   1.182 -you're trying to track down a subtle bug, you might want a tag to
   1.183 -remind you of something like <quote>Anne saw the symptoms with this
   1.184 -revision</quote>.
   1.185 -</para>
   1.186 -
   1.187 -<para>For cases like this, what you might want to use are <emphasis>local</emphasis> tags.
   1.188 -You can create a local tag with the <option role="hg-opt-tag">-l</option> option to the
   1.189 -<command role="hg-cmd">hg tag</command> command.  This will store the tag in a file called
   1.190 -<filename role="special">.hg/localtags</filename>.  Unlike <filename role="special">.hgtags</filename>,
   1.191 -<filename role="special">.hg/localtags</filename> is not revision controlled.  Any tags you
   1.192 -create using <option role="hg-opt-tag">-l</option> remain strictly local to the repository
   1.193 -you're currently working in.
   1.194 -</para>
   1.195 -
   1.196 -</sect2>
   1.197 -</sect1>
   1.198 -<sect1>
   1.199 -<title>The flow of changes&emdash;big picture vs. little</title>
   1.200 -
   1.201 -<para>To return to the outline I sketched at the beginning of a chapter,
   1.202 -let's think about a project that has multiple concurrent pieces of
   1.203 -work under development at once.
   1.204 -</para>
   1.205 -
   1.206 -<para>There might be a push for a new <quote>main</quote> release; a new minor bugfix
   1.207 -release to the last main release; and an unexpected <quote>hot fix</quote> to an
   1.208 -old release that is now in maintenance mode.
   1.209 -</para>
   1.210 -
   1.211 -<para>The usual way people refer to these different concurrent directions of
   1.212 -development is as <quote>branches</quote>.  However, we've already seen numerous
   1.213 -times that Mercurial treats <emphasis>all of history</emphasis> as a series of
   1.214 -branches and merges.  Really, what we have here is two ideas that are
   1.215 -peripherally related, but which happen to share a name.
   1.216 -</para>
   1.217 -<itemizedlist>
   1.218 -<listitem><para><quote>Big picture</quote> branches represent the sweep of a project's
   1.219 -  evolution; people give them names, and talk about them in
   1.220 -  conversation.
   1.221 -</para>
   1.222 -</listitem>
   1.223 -<listitem><para><quote>Little picture</quote> branches are artefacts of the day-to-day
   1.224 -  activity of developing and merging changes.  They expose the
   1.225 -  narrative of how the code was developed.
   1.226 -</para>
   1.227 -</listitem></itemizedlist>
   1.228 -
   1.229 -</sect1>
   1.230 -<sect1>
   1.231 -<title>Managing big-picture branches in repositories</title>
   1.232 -
   1.233 -<para>The easiest way to isolate a <quote>big picture</quote> branch in Mercurial is in
   1.234 -a dedicated repository.  If you have an existing shared
   1.235 -repository&emdash;let's call it <literal>myproject</literal>&emdash;that reaches a <quote>1.0</quote>
   1.236 -milestone, you can start to prepare for future maintenance releases on
   1.237 -top of version 1.0 by tagging the revision from which you prepared
   1.238 -the 1.0 release.
   1.239 -<!-- &interaction.branch-repo.tag; -->
   1.240 -You can then clone a new shared <literal>myproject-1.0.1</literal> repository as
   1.241 -of that tag.
   1.242 -<!-- &interaction.branch-repo.clone; -->
   1.243 -</para>
   1.244 -
   1.245 -<para>Afterwards, if someone needs to work on a bug fix that ought to go
   1.246 -into an upcoming 1.0.1 minor release, they clone the
   1.247 -<literal>myproject-1.0.1</literal> repository, make their changes, and push them
   1.248 -back.
   1.249 -<!-- &interaction.branch-repo.bugfix; -->
   1.250 -Meanwhile, development for the next major release can continue,
   1.251 -isolated and unabated, in the <literal>myproject</literal> repository.
   1.252 -<!-- &interaction.branch-repo.new; -->
   1.253 -</para>
   1.254 -
   1.255 -</sect1>
   1.256 -<sect1>
   1.257 -<title>Don't repeat yourself: merging across branches</title>
   1.258 -
   1.259 -<para>In many cases, if you have a bug to fix on a maintenance branch, the
   1.260 -chances are good that the bug exists on your project's main branch
   1.261 -(and possibly other maintenance branches, too).  It's a rare developer
   1.262 -who wants to fix the same bug multiple times, so let's look at a few
   1.263 -ways that Mercurial can help you to manage these bugfixes without
   1.264 -duplicating your work.
   1.265 -</para>
   1.266 -
   1.267 -<para>In the simplest instance, all you need to do is pull changes from your
   1.268 -maintenance branch into your local clone of the target branch.
   1.269 -<!-- &interaction.branch-repo.pull; -->
   1.270 -You'll then need to merge the heads of the two branches, and push back
   1.271 -to the main branch.
   1.272 -<!-- &interaction.branch-repo.merge; -->
   1.273 -</para>
   1.274 -
   1.275 -</sect1>
   1.276 -<sect1>
   1.277 -<title>Naming branches within one repository</title>
   1.278 -
   1.279 -<para>In most instances, isolating branches in repositories is the right
   1.280 -approach.  Its simplicity makes it easy to understand; and so it's
   1.281 -hard to make mistakes.  There's a one-to-one relationship between
   1.282 -branches you're working in and directories on your system.  This lets
   1.283 -you use normal (non-Mercurial-aware) tools to work on files within a
   1.284 -branch/repository.
   1.285 -</para>
   1.286 -
   1.287 -<para>If you're more in the <quote>power user</quote> category (<emphasis>and</emphasis> your
   1.288 -collaborators are too), there is an alternative way of handling
   1.289 -branches that you can consider.  I've already mentioned the
   1.290 -human-level distinction between <quote>small picture</quote> and <quote>big picture</quote>
   1.291 -branches.  While Mercurial works with multiple <quote>small picture</quote>
   1.292 -branches in a repository all the time (for example after you pull
   1.293 -changes in, but before you merge them), it can <emphasis>also</emphasis> work with
   1.294 -multiple <quote>big picture</quote> branches.
   1.295 -</para>
   1.296 -
   1.297 -<para>The key to working this way is that Mercurial lets you assign a
   1.298 -persistent <emphasis>name</emphasis> to a branch.  There always exists a branch
   1.299 -named <literal>default</literal>.  Even before you start naming branches
   1.300 -yourself, you can find traces of the <literal>default</literal> branch if you
   1.301 -look for them.
   1.302 -</para>
   1.303 -
   1.304 -<para>As an example, when you run the <command role="hg-cmd">hg commit</command> command, and it pops up
   1.305 -your editor so that you can enter a commit message, look for a line
   1.306 -that contains the text <quote><literal>HG: branch default</literal></quote> at the bottom.
   1.307 -This is telling you that your commit will occur on the branch named
   1.308 -<literal>default</literal>.
   1.309 -</para>
   1.310 -
   1.311 -<para>To start working with named branches, use the <command role="hg-cmd">hg branches</command>
   1.312 -command.  This command lists the named branches already present in
   1.313 -your repository, telling you which changeset is the tip of each.
   1.314 -<!-- &interaction.branch-named.branches; -->
   1.315 -Since you haven't created any named branches yet, the only one that
   1.316 -exists is <literal>default</literal>.
   1.317 -</para>
   1.318 -
   1.319 -<para>To find out what the <quote>current</quote> branch is, run the <command role="hg-cmd">hg branch</command>
   1.320 -command, giving it no arguments.  This tells you what branch the
   1.321 -parent of the current changeset is on.
   1.322 -<!-- &interaction.branch-named.branch; -->
   1.323 -</para>
   1.324 -
   1.325 -<para>To create a new branch, run the <command role="hg-cmd">hg branch</command> command again.  This
   1.326 -time, give it one argument: the name of the branch you want to create.
   1.327 -<!-- &interaction.branch-named.create; -->
   1.328 -</para>
   1.329 -
   1.330 -<para>After you've created a branch, you might wonder what effect the
   1.331 -<command role="hg-cmd">hg branch</command> command has had.  What do the <command role="hg-cmd">hg status</command> and
   1.332 -<command role="hg-cmd">hg tip</command> commands report?
   1.333 -<!-- &interaction.branch-named.status; -->
   1.334 -Nothing has changed in the working directory, and there's been no new
   1.335 -history created.  As this suggests, running the <command role="hg-cmd">hg branch</command> command
   1.336 -has no permanent effect; it only tells Mercurial what branch name to
   1.337 -use the <emphasis>next</emphasis> time you commit a changeset.
   1.338 -</para>
   1.339 -
   1.340 -<para>When you commit a change, Mercurial records the name of the branch on
   1.341 -which you committed.  Once you've switched from the <literal>default</literal>
   1.342 -branch to another and committed, you'll see the name of the new branch
   1.343 -show up in the output of <command role="hg-cmd">hg log</command>, <command role="hg-cmd">hg tip</command>, and other commands
   1.344 -that display the same kind of output.
   1.345 -<!-- &interaction.branch-named.commit; -->
   1.346 -The <command role="hg-cmd">hg log</command>-like commands will print the branch name of every
   1.347 -changeset that's not on the <literal>default</literal> branch.  As a result, if
   1.348 -you never use named branches, you'll never see this information.
   1.349 -</para>
   1.350 -
   1.351 -<para>Once you've named a branch and committed a change with that name,
   1.352 -every subsequent commit that descends from that change will inherit
   1.353 -the same branch name.  You can change the name of a branch at any
   1.354 -time, using the <command role="hg-cmd">hg branch</command> command.
   1.355 -<!-- &interaction.branch-named.rebranch; -->
   1.356 -In practice, this is something you won't do very often, as branch
   1.357 -names tend to have fairly long lifetimes.  (This isn't a rule, just an
   1.358 -observation.)
   1.359 -</para>
   1.360 -
   1.361 -</sect1>
   1.362 -<sect1>
   1.363 -<title>Dealing with multiple named branches in a repository</title>
   1.364 -
   1.365 -<para>If you have more than one named branch in a repository, Mercurial will
   1.366 -remember the branch that your working directory on when you start a
   1.367 -command like <command role="hg-cmd">hg update</command> or <command role="hg-cmd">hg pull -u</command>.  It will update
   1.368 -the working directory to the tip of this branch, no matter what the
   1.369 -<quote>repo-wide</quote> tip is.  To update to a revision that's on a different
   1.370 -named branch, you may need to use the <option role="hg-opt-update">-C</option> option to
   1.371 -<command role="hg-cmd">hg update</command>.
   1.372 -</para>
   1.373 -
   1.374 -<para>This behaviour is a little subtle, so let's see it in action.  First,
   1.375 -let's remind ourselves what branch we're currently on, and what
   1.376 -branches are in our repository.
   1.377 -<!-- &interaction.branch-named.parents; -->
   1.378 -We're on the <literal>bar</literal> branch, but there also exists an older
   1.379 -<command role="hg-cmd">hg foo</command> branch.
   1.380 -</para>
   1.381 -
   1.382 -<para>We can <command role="hg-cmd">hg update</command> back and forth between the tips of the
   1.383 -<literal>foo</literal> and <literal>bar</literal> branches without needing to use the
   1.384 -<option role="hg-opt-update">-C</option> option, because this only involves going backwards
   1.385 -and forwards linearly through our change history.
   1.386 -<!-- &interaction.branch-named.update-switchy; -->
   1.387 -</para>
   1.388 -
   1.389 -<para>If we go back to the <literal>foo</literal> branch and then run <command role="hg-cmd">hg update</command>,
   1.390 -it will keep us on <literal>foo</literal>, not move us to the tip of
   1.391 -<literal>bar</literal>.
   1.392 -<!-- &interaction.branch-named.update-nothing; -->
   1.393 -</para>
   1.394 -
   1.395 -<para>Committing a new change on the <literal>foo</literal> branch introduces a new
   1.396 -head.
   1.397 -<!-- &interaction.branch-named.foo-commit; -->
   1.398 -</para>
   1.399 -
   1.400 -</sect1>
   1.401 -<sect1>
   1.402 -<title>Branch names and merging</title>
   1.403 -
   1.404 -<para>As you've probably noticed, merges in Mercurial are not symmetrical.
   1.405 -Let's say our repository has two heads, 17 and 23.  If I
   1.406 -<command role="hg-cmd">hg update</command> to 17 and then <command role="hg-cmd">hg merge</command> with 23, Mercurial records
   1.407 -17 as the first parent of the merge, and 23 as the second.  Whereas if
   1.408 -I <command role="hg-cmd">hg update</command> to 23 and then <command role="hg-cmd">hg merge</command> with 17, it records 23
   1.409 -as the first parent, and 17 as the second.
   1.410 -</para>
   1.411 -
   1.412 -<para>This affects Mercurial's choice of branch name when you merge.  After
   1.413 -a merge, Mercurial will retain the branch name of the first parent
   1.414 -when you commit the result of the merge.  If your first parent's
   1.415 -branch name is <literal>foo</literal>, and you merge with <literal>bar</literal>, the
   1.416 -branch name will still be <literal>foo</literal> after you merge.
   1.417 -</para>
   1.418 -
   1.419 -<para>It's not unusual for a repository to contain multiple heads, each with
   1.420 -the same branch name.  Let's say I'm working on the <literal>foo</literal>
   1.421 -branch, and so are you.  We commit different changes; I pull your
   1.422 -changes; I now have two heads, each claiming to be on the <literal>foo</literal>
   1.423 -branch.  The result of a merge will be a single head on the
   1.424 -<literal>foo</literal> branch, as you might hope.
   1.425 -</para>
   1.426 -
   1.427 -<para>But if I'm working on the <literal>bar</literal> branch, and I merge work from
   1.428 -the <literal>foo</literal> branch, the result will remain on the <literal>bar</literal>
   1.429 -branch.
   1.430 -<!-- &interaction.branch-named.merge; -->
   1.431 -</para>
   1.432 -
   1.433 -<para>To give a more concrete example, if I'm working on the
   1.434 -<literal>bleeding-edge</literal> branch, and I want to bring in the latest fixes
   1.435 -from the <literal>stable</literal> branch, Mercurial will choose the <quote>right</quote>
   1.436 -(<literal>bleeding-edge</literal>) branch name when I pull and merge from
   1.437 -<literal>stable</literal>.
   1.438 -</para>
   1.439 -
   1.440 -</sect1>
   1.441 -<sect1>
   1.442 -<title>Branch naming is generally useful</title>
   1.443 -
   1.444 -<para>You shouldn't think of named branches as applicable only to situations
   1.445 -where you have multiple long-lived branches cohabiting in a single
   1.446 -repository.  They're very useful even in the one-branch-per-repository
   1.447 -case.
   1.448 -</para>
   1.449 -
   1.450 -<para>In the simplest case, giving a name to each branch gives you a
   1.451 -permanent record of which branch a changeset originated on.  This
   1.452 -gives you more context when you're trying to follow the history of a
   1.453 -long-lived branchy project.
   1.454 -</para>
   1.455 -
   1.456 -<para>If you're working with shared repositories, you can set up a
   1.457 -<literal role="hook">pretxnchangegroup</literal> hook on each that will block incoming changes
   1.458 -that have the <quote>wrong</quote> branch name.  This provides a simple, but
   1.459 -effective, defence against people accidentally pushing changes from a
   1.460 -<quote>bleeding edge</quote> branch to a <quote>stable</quote> branch.  Such a hook might
   1.461 -look like this inside the shared repo's <filename role="special"> /.hgrc</filename>.
   1.462 -</para>
   1.463 -<programlisting>
   1.464 -<para>  [hooks]
   1.465 -  pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch
   1.466 -</para>
   1.467 -</programlisting>
   1.468 -
   1.469 -</sect1>
   1.470 +<chapter id="chap:branch">
   1.471 +  <?dbhtml filename="managing-releases-and-branchy-development.html"?>
   1.472 +  <title>Managing releases and branchy development</title>
   1.473 +
   1.474 +  <para id="x_369">Mercurial provides several mechanisms for you to manage a
   1.475 +    project that is making progress on multiple fronts at once.  To
   1.476 +    understand these mechanisms, let's first take a brief look at a
   1.477 +    fairly normal software project structure.</para>
   1.478 +
   1.479 +  <para id="x_36a">Many software projects issue periodic <quote>major</quote>
   1.480 +    releases that contain substantial new features.  In parallel, they
   1.481 +    may issue <quote>minor</quote> releases.  These are usually
   1.482 +    identical to the major releases off which they're based, but with
   1.483 +    a few bugs fixed.</para>
   1.484 +
   1.485 +  <para id="x_36b">In this chapter, we'll start by talking about how to keep
   1.486 +    records of project milestones such as releases.  We'll then
   1.487 +    continue on to talk about the flow of work between different
   1.488 +    phases of a project, and how Mercurial can help you to isolate and
   1.489 +    manage this work.</para>
   1.490 +
   1.491 +  <sect1>
   1.492 +    <title>Giving a persistent name to a revision</title>
   1.493 +
   1.494 +    <para id="x_36c">Once you decide that you'd like to call a particular
   1.495 +      revision a <quote>release</quote>, it's a good idea to record
   1.496 +      the identity of that revision. This will let you reproduce that
   1.497 +      release at a later date, for whatever purpose you might need at
   1.498 +      the time (reproducing a bug, porting to a new platform, etc).
   1.499 +      &interaction.tag.init;</para>
   1.500 +
   1.501 +    <para id="x_36d">Mercurial lets you give a permanent name to any revision
   1.502 +      using the <command role="hg-cmd">hg tag</command> command.  Not
   1.503 +      surprisingly, these names are called <quote>tags</quote>.</para>
   1.504 +
   1.505 +    &interaction.tag.tag;
   1.506 +
   1.507 +    <para id="x_36e">A tag is nothing more than a <quote>symbolic name</quote>
   1.508 +      for a revision.  Tags exist purely for your convenience, so that
   1.509 +      you have a handy permanent way to refer to a revision; Mercurial
   1.510 +      doesn't interpret the tag names you use in any way.  Neither
   1.511 +      does Mercurial place any restrictions on the name of a tag,
   1.512 +      beyond a few that are necessary to ensure that a tag can be
   1.513 +      parsed unambiguously.  A tag name cannot contain any of the
   1.514 +      following characters:</para>
   1.515 +    <itemizedlist>
   1.516 +      <listitem><para id="x_36f">Colon (ASCII 58,
   1.517 +	  <quote><literal>:</literal></quote>)</para>
   1.518 +      </listitem>
   1.519 +      <listitem><para id="x_370">Carriage return (ASCII 13,
   1.520 +	  <quote><literal>\r</literal></quote>)</para>
   1.521 +      </listitem>
   1.522 +      <listitem><para id="x_371">Newline (ASCII 10,
   1.523 +	  <quote><literal>\n</literal></quote>)</para>
   1.524 +      </listitem></itemizedlist>
   1.525 +
   1.526 +    <para id="x_372">You can use the <command role="hg-cmd">hg tags</command>
   1.527 +      command to display the tags present in your repository.  In the
   1.528 +      output, each tagged revision is identified first by its name,
   1.529 +      then by revision number, and finally by the unique hash of the
   1.530 +      revision.</para>
   1.531 +
   1.532 +    &interaction.tag.tags;
   1.533 +
   1.534 +    <para id="x_373">Notice that <literal>tip</literal> is listed in the output
   1.535 +      of <command role="hg-cmd">hg tags</command>.  The
   1.536 +      <literal>tip</literal> tag is a special <quote>floating</quote>
   1.537 +      tag, which always identifies the newest revision in the
   1.538 +      repository.</para>
   1.539 +
   1.540 +    <para id="x_374">In the output of the <command role="hg-cmd">hg
   1.541 +	tags</command> command, tags are listed in reverse order, by
   1.542 +      revision number.  This usually means that recent tags are listed
   1.543 +      before older tags.  It also means that <literal>tip</literal> is
   1.544 +      always going to be the first tag listed in the output of
   1.545 +      <command role="hg-cmd">hg tags</command>.</para>
   1.546 +
   1.547 +    <para id="x_375">When you run <command role="hg-cmd">hg log</command>, if it
   1.548 +      displays a revision that has tags associated with it, it will
   1.549 +      print those tags.</para>
   1.550 +
   1.551 +    &interaction.tag.log;
   1.552 +
   1.553 +    <para id="x_376">Any time you need to provide a revision ID to a Mercurial
   1.554 +      command, the command will accept a tag name in its place.
   1.555 +      Internally, Mercurial will translate your tag name into the
   1.556 +      corresponding revision ID, then use that.</para>
   1.557 +
   1.558 +    &interaction.tag.log.v1.0;
   1.559 +
   1.560 +    <para id="x_377">There's no limit on the number of tags you can have in a
   1.561 +      repository, or on the number of tags that a single revision can
   1.562 +      have.  As a practical matter, it's not a great idea to have
   1.563 +      <quote>too many</quote> (a number which will vary from project
   1.564 +      to project), simply because tags are supposed to help you to
   1.565 +      find revisions.  If you have lots of tags, the ease of using
   1.566 +      them to identify revisions diminishes rapidly.</para>
   1.567 +
   1.568 +    <para id="x_378">For example, if your project has milestones as frequent as
   1.569 +      every few days, it's perfectly reasonable to tag each one of
   1.570 +      those.  But if you have a continuous build system that makes
   1.571 +      sure every revision can be built cleanly, you'd be introducing a
   1.572 +      lot of noise if you were to tag every clean build.  Instead, you
   1.573 +      could tag failed builds (on the assumption that they're rare!),
   1.574 +      or simply not use tags to track buildability.</para>
   1.575 +
   1.576 +    <para id="x_379">If you want to remove a tag that you no longer want, use
   1.577 +      <command role="hg-cmd">hg tag --remove</command>.</para>
   1.578 +
   1.579 +    &interaction.tag.remove;
   1.580 +
   1.581 +    <para id="x_37a">You can also modify a tag at any time, so that it identifies
   1.582 +      a different revision, by simply issuing a new <command
   1.583 +	role="hg-cmd">hg tag</command> command. You'll have to use the
   1.584 +      <option role="hg-opt-tag">-f</option> option to tell Mercurial
   1.585 +      that you <emphasis>really</emphasis> want to update the
   1.586 +      tag.</para>
   1.587 +
   1.588 +    &interaction.tag.replace;
   1.589 +
   1.590 +    <para id="x_37b">There will still be a permanent record of the previous
   1.591 +      identity of the tag, but Mercurial will no longer use it.
   1.592 +      There's thus no penalty to tagging the wrong revision; all you
   1.593 +      have to do is turn around and tag the correct revision once you
   1.594 +      discover your error.</para>
   1.595 +
   1.596 +    <para id="x_37c">Mercurial stores tags in a normal revision-controlled file
   1.597 +      in your repository.  If you've created any tags, you'll find
   1.598 +      them in a file in the root of your repository named <filename
   1.599 +	role="special">.hgtags</filename>.  When you run the <command
   1.600 +	role="hg-cmd">hg tag</command> command, Mercurial modifies
   1.601 +      this file, then automatically commits the change to it.  This
   1.602 +      means that every time you run <command role="hg-cmd">hg
   1.603 +	tag</command>, you'll see a corresponding changeset in the
   1.604 +      output of <command role="hg-cmd">hg log</command>.</para>
   1.605 +
   1.606 +    &interaction.tag.tip;
   1.607 +
   1.608 +    <sect2>
   1.609 +      <title>Handling tag conflicts during a merge</title>
   1.610 +
   1.611 +      <para id="x_37d">You won't often need to care about the <filename
   1.612 +	  role="special">.hgtags</filename> file, but it sometimes
   1.613 +	makes its presence known during a merge.  The format of the
   1.614 +	file is simple: it consists of a series of lines.  Each line
   1.615 +	starts with a changeset hash, followed by a space, followed by
   1.616 +	the name of a tag.</para>
   1.617 +
   1.618 +      <para id="x_37e">If you're resolving a conflict in the <filename
   1.619 +	  role="special">.hgtags</filename> file during a merge,
   1.620 +	there's one twist to modifying the <filename
   1.621 +	  role="special">.hgtags</filename> file: when Mercurial is
   1.622 +	parsing the tags in a repository, it
   1.623 +	<emphasis>never</emphasis> reads the working copy of the
   1.624 +	<filename role="special">.hgtags</filename> file.  Instead, it
   1.625 +	reads the <emphasis>most recently committed</emphasis>
   1.626 +	revision of the file.</para>
   1.627 +
   1.628 +      <para id="x_37f">An unfortunate consequence of this design is that you
   1.629 +	can't actually verify that your merged <filename
   1.630 +	  role="special">.hgtags</filename> file is correct until
   1.631 +	<emphasis>after</emphasis> you've committed a change.  So if
   1.632 +	you find yourself resolving a conflict on <filename
   1.633 +	  role="special">.hgtags</filename> during a merge, be sure to
   1.634 +	run <command role="hg-cmd">hg tags</command> after you commit.
   1.635 +	If it finds an error in the <filename
   1.636 +	  role="special">.hgtags</filename> file, it will report the
   1.637 +	location of the error, which you can then fix and commit.  You
   1.638 +	should then run <command role="hg-cmd">hg tags</command>
   1.639 +	again, just to be sure that your fix is correct.</para>
   1.640 +    </sect2>
   1.641 +
   1.642 +    <sect2>
   1.643 +      <title>Tags and cloning</title>
   1.644 +
   1.645 +      <para id="x_380">You may have noticed that the <command role="hg-cmd">hg
   1.646 +	  clone</command> command has a <option
   1.647 +	  role="hg-opt-clone">-r</option> option that lets you clone
   1.648 +	an exact copy of the repository as of a particular changeset.
   1.649 +	The new clone will not contain any project history that comes
   1.650 +	after the revision you specified.  This has an interaction
   1.651 +	with tags that can surprise the unwary.</para>
   1.652 +
   1.653 +      <para id="x_381">Recall that a tag is stored as a revision to
   1.654 +	the <filename role="special">.hgtags</filename> file. When you
   1.655 +	create a tag, the changeset in which its recorded refers to an
   1.656 +	older changeset.  When you run <command role="hg-cmd">hg clone
   1.657 +	  -r foo</command> to clone a repository as of tag
   1.658 +	<literal>foo</literal>, the new clone <emphasis>will not
   1.659 +	  contain any revision newer than the one the tag refers to,
   1.660 +	  including the revision where the tag was created</emphasis>.
   1.661 +	The result is that you'll get exactly the right subset of the
   1.662 +	project's history in the new repository, but
   1.663 +	<emphasis>not</emphasis> the tag you might have
   1.664 +	expected.</para>
   1.665 +    </sect2>
   1.666 +
   1.667 +    <sect2>
   1.668 +      <title>When permanent tags are too much</title>
   1.669 +
   1.670 +      <para id="x_382">Since Mercurial's tags are revision controlled and carried
   1.671 +	around with a project's history, everyone you work with will
   1.672 +	see the tags you create.  But giving names to revisions has
   1.673 +	uses beyond simply noting that revision
   1.674 +	<literal>4237e45506ee</literal> is really
   1.675 +	<literal>v2.0.2</literal>.  If you're trying to track down a
   1.676 +	subtle bug, you might want a tag to remind you of something
   1.677 +	like <quote>Anne saw the symptoms with this
   1.678 +	  revision</quote>.</para>
   1.679 +
   1.680 +      <para id="x_383">For cases like this, what you might want to use are
   1.681 +	<emphasis>local</emphasis> tags. You can create a local tag
   1.682 +	with the <option role="hg-opt-tag">-l</option> option to the
   1.683 +	<command role="hg-cmd">hg tag</command> command.  This will
   1.684 +	store the tag in a file called <filename
   1.685 +	  role="special">.hg/localtags</filename>.  Unlike <filename
   1.686 +	  role="special">.hgtags</filename>, <filename
   1.687 +	  role="special">.hg/localtags</filename> is not revision
   1.688 +	controlled.  Any tags you create using <option
   1.689 +	  role="hg-opt-tag">-l</option> remain strictly local to the
   1.690 +	repository you're currently working in.</para>
   1.691 +    </sect2>
   1.692 +  </sect1>
   1.693 +
   1.694 +  <sect1>
   1.695 +    <title>The flow of changes&emdash;big picture vs. little</title>
   1.696 +
   1.697 +    <para id="x_384">To return to the outline I sketched at the
   1.698 +      beginning of the chapter, let's think about a project that has
   1.699 +      multiple concurrent pieces of work under development at
   1.700 +      once.</para>
   1.701 +
   1.702 +    <para id="x_385">There might be a push for a new <quote>main</quote> release;
   1.703 +      a new minor bugfix release to the last main release; and an
   1.704 +      unexpected <quote>hot fix</quote> to an old release that is now
   1.705 +      in maintenance mode.</para>
   1.706 +
   1.707 +    <para id="x_386">The usual way people refer to these different concurrent
   1.708 +      directions of development is as <quote>branches</quote>.
   1.709 +      However, we've already seen numerous times that Mercurial treats
   1.710 +      <emphasis>all of history</emphasis> as a series of branches and
   1.711 +      merges.  Really, what we have here is two ideas that are
   1.712 +      peripherally related, but which happen to share a name.</para>
   1.713 +    <itemizedlist>
   1.714 +      <listitem><para id="x_387"><quote>Big picture</quote> branches represent
   1.715 +	  the sweep of a project's evolution; people give them names,
   1.716 +	  and talk about them in conversation.</para>
   1.717 +      </listitem>
   1.718 +      <listitem><para id="x_388"><quote>Little picture</quote> branches are
   1.719 +	  artefacts of the day-to-day activity of developing and
   1.720 +	  merging changes.  They expose the narrative of how the code
   1.721 +	  was developed.</para>
   1.722 +      </listitem></itemizedlist>
   1.723 +  </sect1>
   1.724 +
   1.725 +  <sect1>
   1.726 +    <title>Managing big-picture branches in repositories</title>
   1.727 +
   1.728 +    <para id="x_389">The easiest way to isolate a <quote>big picture</quote>
   1.729 +      branch in Mercurial is in a dedicated repository.  If you have
   1.730 +      an existing shared repository&emdash;let's call it
   1.731 +      <literal>myproject</literal>&emdash;that reaches a
   1.732 +      <quote>1.0</quote> milestone, you can start to prepare for
   1.733 +      future maintenance releases on top of version 1.0 by tagging the
   1.734 +      revision from which you prepared the 1.0 release.</para>
   1.735 +
   1.736 +    &interaction.branch-repo.tag;
   1.737 +
   1.738 +    <para id="x_38a">You can then clone a new shared
   1.739 +      <literal>myproject-1.0.1</literal> repository as of that
   1.740 +      tag.</para>
   1.741 +
   1.742 +    &interaction.branch-repo.clone;
   1.743 +
   1.744 +    <para id="x_38b">Afterwards, if someone needs to work on a bug fix that ought
   1.745 +      to go into an upcoming 1.0.1 minor release, they clone the
   1.746 +      <literal>myproject-1.0.1</literal> repository, make their
   1.747 +      changes, and push them back.</para>
   1.748 +
   1.749 +    &interaction.branch-repo.bugfix;
   1.750 +
   1.751 +    <para id="x_38c">Meanwhile, development for
   1.752 +      the next major release can continue, isolated and unabated, in
   1.753 +      the <literal>myproject</literal> repository.</para>
   1.754 +
   1.755 +    &interaction.branch-repo.new;
   1.756 +  </sect1>
   1.757 +
   1.758 +  <sect1>
   1.759 +    <title>Don't repeat yourself: merging across branches</title>
   1.760 +
   1.761 +    <para id="x_38d">In many cases, if you have a bug to fix on a maintenance
   1.762 +      branch, the chances are good that the bug exists on your
   1.763 +      project's main branch (and possibly other maintenance branches,
   1.764 +      too).  It's a rare developer who wants to fix the same bug
   1.765 +      multiple times, so let's look at a few ways that Mercurial can
   1.766 +      help you to manage these bugfixes without duplicating your
   1.767 +      work.</para>
   1.768 +
   1.769 +    <para id="x_38e">In the simplest instance, all you need to do is pull changes
   1.770 +      from your maintenance branch into your local clone of the target
   1.771 +      branch.</para>
   1.772 +
   1.773 +    &interaction.branch-repo.pull;
   1.774 +
   1.775 +    <para id="x_38f">You'll then need to merge the heads of the two branches, and
   1.776 +      push back to the main branch.</para>
   1.777 +
   1.778 +    &interaction.branch-repo.merge;
   1.779 +  </sect1>
   1.780 +
   1.781 +  <sect1>
   1.782 +    <title>Naming branches within one repository</title>
   1.783 +
   1.784 +    <para id="x_390">In most instances, isolating branches in repositories is the
   1.785 +      right approach.  Its simplicity makes it easy to understand; and
   1.786 +      so it's hard to make mistakes.  There's a one-to-one
   1.787 +      relationship between branches you're working in and directories
   1.788 +      on your system.  This lets you use normal (non-Mercurial-aware)
   1.789 +      tools to work on files within a branch/repository.</para>
   1.790 +
   1.791 +    <para id="x_391">If you're more in the <quote>power user</quote> category
   1.792 +      (<emphasis>and</emphasis> your collaborators are too), there is
   1.793 +      an alternative way of handling branches that you can consider.
   1.794 +      I've already mentioned the human-level distinction between
   1.795 +      <quote>small picture</quote> and <quote>big picture</quote>
   1.796 +      branches.  While Mercurial works with multiple <quote>small
   1.797 +	picture</quote> branches in a repository all the time (for
   1.798 +      example after you pull changes in, but before you merge them),
   1.799 +      it can <emphasis>also</emphasis> work with multiple <quote>big
   1.800 +	picture</quote> branches.</para>
   1.801 +
   1.802 +    <para id="x_392">The key to working this way is that Mercurial lets you
   1.803 +      assign a persistent <emphasis>name</emphasis> to a branch.
   1.804 +      There always exists a branch named <literal>default</literal>.
   1.805 +      Even before you start naming branches yourself, you can find
   1.806 +      traces of the <literal>default</literal> branch if you look for
   1.807 +      them.</para>
   1.808 +
   1.809 +    <para id="x_393">As an example, when you run the <command role="hg-cmd">hg
   1.810 +	commit</command> command, and it pops up your editor so that
   1.811 +      you can enter a commit message, look for a line that contains
   1.812 +      the text <quote><literal>HG: branch default</literal></quote> at
   1.813 +      the bottom. This is telling you that your commit will occur on
   1.814 +      the branch named <literal>default</literal>.</para>
   1.815 +
   1.816 +    <para id="x_394">To start working with named branches, use the <command
   1.817 +	role="hg-cmd">hg branches</command> command.  This command
   1.818 +      lists the named branches already present in your repository,
   1.819 +      telling you which changeset is the tip of each.</para>
   1.820 +
   1.821 +    &interaction.branch-named.branches;
   1.822 +
   1.823 +    <para id="x_395">Since you haven't created any named branches yet, the only
   1.824 +      one that exists is <literal>default</literal>.</para>
   1.825 +
   1.826 +    <para id="x_396">To find out what the <quote>current</quote> branch is, run
   1.827 +      the <command role="hg-cmd">hg branch</command> command, giving
   1.828 +      it no arguments.  This tells you what branch the parent of the
   1.829 +      current changeset is on.</para>
   1.830 +
   1.831 +    &interaction.branch-named.branch;
   1.832 +
   1.833 +    <para id="x_397">To create a new branch, run the <command role="hg-cmd">hg
   1.834 +	branch</command> command again.  This time, give it one
   1.835 +      argument: the name of the branch you want to create.</para>
   1.836 +
   1.837 +    &interaction.branch-named.create;
   1.838 +
   1.839 +    <para id="x_398">After you've created a branch, you might wonder what effect
   1.840 +      the <command role="hg-cmd">hg branch</command> command has had.
   1.841 +      What do the <command role="hg-cmd">hg status</command> and
   1.842 +      <command role="hg-cmd">hg tip</command> commands report?</para>
   1.843 +
   1.844 +    &interaction.branch-named.status;
   1.845 +
   1.846 +    <para id="x_399">Nothing has changed in the
   1.847 +      working directory, and there's been no new history created.  As
   1.848 +      this suggests, running the <command role="hg-cmd">hg
   1.849 +	branch</command> command has no permanent effect; it only
   1.850 +      tells Mercurial what branch name to use the
   1.851 +      <emphasis>next</emphasis> time you commit a changeset.</para>
   1.852 +
   1.853 +    <para id="x_39a">When you commit a change, Mercurial records the name of the
   1.854 +      branch on which you committed.  Once you've switched from the
   1.855 +      <literal>default</literal> branch to another and committed,
   1.856 +      you'll see the name of the new branch show up in the output of
   1.857 +      <command role="hg-cmd">hg log</command>, <command
   1.858 +	role="hg-cmd">hg tip</command>, and other commands that
   1.859 +      display the same kind of output.</para>
   1.860 +
   1.861 +    &interaction.branch-named.commit;
   1.862 +
   1.863 +    <para id="x_39b">The <command role="hg-cmd">hg log</command>-like commands
   1.864 +      will print the branch name of every changeset that's not on the
   1.865 +      <literal>default</literal> branch.  As a result, if you never
   1.866 +      use named branches, you'll never see this information.</para>
   1.867 +
   1.868 +    <para id="x_39c">Once you've named a branch and committed a change with that
   1.869 +      name, every subsequent commit that descends from that change
   1.870 +      will inherit the same branch name.  You can change the name of a
   1.871 +      branch at any time, using the <command role="hg-cmd">hg
   1.872 +	branch</command> command.</para>
   1.873 +
   1.874 +    &interaction.branch-named.rebranch;
   1.875 +
   1.876 +    <para id="x_39d">In practice, this is something you won't do very often, as
   1.877 +      branch names tend to have fairly long lifetimes.  (This isn't a
   1.878 +      rule, just an observation.)</para>
   1.879 +  </sect1>
   1.880 +
   1.881 +  <sect1>
   1.882 +    <title>Dealing with multiple named branches in a
   1.883 +      repository</title>
   1.884 +
   1.885 +    <para id="x_39e">If you have more than one named branch in a repository,
   1.886 +      Mercurial will remember the branch that your working directory
   1.887 +      is on when you start a command like <command role="hg-cmd">hg
   1.888 +	update</command> or <command role="hg-cmd">hg pull
   1.889 +	-u</command>.  It will update the working directory to the tip
   1.890 +      of this branch, no matter what the <quote>repo-wide</quote> tip
   1.891 +      is.  To update to a revision that's on a different named branch,
   1.892 +      you may need to use the <option role="hg-opt-update">-C</option>
   1.893 +      option to <command role="hg-cmd">hg update</command>.</para>
   1.894 +
   1.895 +    <para id="x_39f">This behavior is a little subtle, so let's see it in
   1.896 +      action.  First, let's remind ourselves what branch we're
   1.897 +      currently on, and what branches are in our repository.</para>
   1.898 +
   1.899 +    &interaction.branch-named.parents;
   1.900 +
   1.901 +    <para id="x_3a0">We're on the <literal>bar</literal> branch, but there also
   1.902 +      exists an older <command role="hg-cmd">hg foo</command>
   1.903 +      branch.</para>
   1.904 +
   1.905 +    <para id="x_3a1">We can <command role="hg-cmd">hg update</command> back and
   1.906 +      forth between the tips of the <literal>foo</literal> and
   1.907 +      <literal>bar</literal> branches without needing to use the
   1.908 +      <option role="hg-opt-update">-C</option> option, because this
   1.909 +      only involves going backwards and forwards linearly through our
   1.910 +      change history.</para>
   1.911 +
   1.912 +    &interaction.branch-named.update-switchy;
   1.913 +
   1.914 +    <para id="x_3a2">If we go back to the <literal>foo</literal> branch and then
   1.915 +      run <command role="hg-cmd">hg update</command>, it will keep us
   1.916 +      on <literal>foo</literal>, not move us to the tip of
   1.917 +      <literal>bar</literal>.</para>
   1.918 +
   1.919 +    &interaction.branch-named.update-nothing;
   1.920 +
   1.921 +    <para id="x_3a3">Committing a new change on the <literal>foo</literal> branch
   1.922 +      introduces a new head.</para>
   1.923 +
   1.924 +    &interaction.branch-named.foo-commit;
   1.925 +  </sect1>
   1.926 +
   1.927 +  <sect1>
   1.928 +    <title>Branch names and merging</title>
   1.929 +
   1.930 +    <para id="x_3a4">As you've probably noticed, merges in Mercurial are not
   1.931 +      symmetrical. Let's say our repository has two heads, 17 and 23.
   1.932 +      If I <command role="hg-cmd">hg update</command> to 17 and then
   1.933 +      <command role="hg-cmd">hg merge</command> with 23, Mercurial
   1.934 +      records 17 as the first parent of the merge, and 23 as the
   1.935 +      second.  Whereas if I <command role="hg-cmd">hg update</command>
   1.936 +      to 23 and then <command role="hg-cmd">hg merge</command> with
   1.937 +      17, it records 23 as the first parent, and 17 as the
   1.938 +      second.</para>
   1.939 +
   1.940 +    <para id="x_3a5">This affects Mercurial's choice of branch name when you
   1.941 +      merge.  After a merge, Mercurial will retain the branch name of
   1.942 +      the first parent when you commit the result of the merge.  If
   1.943 +      your first parent's branch name is <literal>foo</literal>, and
   1.944 +      you merge with <literal>bar</literal>, the branch name will
   1.945 +      still be <literal>foo</literal> after you merge.</para>
   1.946 +
   1.947 +    <para id="x_3a6">It's not unusual for a repository to contain multiple heads,
   1.948 +      each with the same branch name.  Let's say I'm working on the
   1.949 +      <literal>foo</literal> branch, and so are you.  We commit
   1.950 +      different changes; I pull your changes; I now have two heads,
   1.951 +      each claiming to be on the <literal>foo</literal> branch.  The
   1.952 +      result of a merge will be a single head on the
   1.953 +      <literal>foo</literal> branch, as you might hope.</para>
   1.954 +
   1.955 +    <para id="x_3a7">But if I'm working on the <literal>bar</literal> branch, and
   1.956 +      I merge work from the <literal>foo</literal> branch, the result
   1.957 +      will remain on the <literal>bar</literal> branch.</para>
   1.958 +
   1.959 +    &interaction.branch-named.merge;
   1.960 +
   1.961 +    <para id="x_3a8">To give a more concrete example, if I'm working on the
   1.962 +      <literal>bleeding-edge</literal> branch, and I want to bring in
   1.963 +      the latest fixes from the <literal>stable</literal> branch,
   1.964 +      Mercurial will choose the <quote>right</quote>
   1.965 +      (<literal>bleeding-edge</literal>) branch name when I pull and
   1.966 +      merge from <literal>stable</literal>.</para>
   1.967 +  </sect1>
   1.968 +
   1.969 +  <sect1>
   1.970 +    <title>Branch naming is generally useful</title>
   1.971 +
   1.972 +    <para id="x_3a9">You shouldn't think of named branches as applicable only to
   1.973 +      situations where you have multiple long-lived branches
   1.974 +      cohabiting in a single repository.  They're very useful even in
   1.975 +      the one-branch-per-repository case.</para>
   1.976 +
   1.977 +    <para id="x_3aa">In the simplest case, giving a name to each branch gives you
   1.978 +      a permanent record of which branch a changeset originated on.
   1.979 +      This gives you more context when you're trying to follow the
   1.980 +      history of a long-lived branchy project.</para>
   1.981 +
   1.982 +    <para id="x_3ab">If you're working with shared repositories, you can set up a
   1.983 +      <literal role="hook">pretxnchangegroup</literal> hook on each
   1.984 +      that will block incoming changes that have the
   1.985 +      <quote>wrong</quote> branch name.  This provides a simple, but
   1.986 +      effective, defence against people accidentally pushing changes
   1.987 +      from a <quote>bleeding edge</quote> branch to a
   1.988 +      <quote>stable</quote> branch.  Such a hook might look like this
   1.989 +      inside the shared repo's <filename role="special">
   1.990 +	/.hgrc</filename>.</para>
   1.991 +    <programlisting>[hooks]
   1.992 +pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch</programlisting>
   1.993 +  </sect1>
   1.994  </chapter>
   1.995  
   1.996  <!--
   1.997  local variables: 
   1.998  sgml-parent-document: ("00book.xml" "book" "chapter")
   1.999  end:
  1.1000 --->
  1.1001 \ No newline at end of file
  1.1002 +-->