1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/en/ch08-branch.xml	Wed Feb 18 00:22:09 2009 -0800
     1.3 @@ -0,0 +1,485 @@
     1.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5 +
     1.6 +<chapter id="chap:branch">
     1.7 +  <title>Managing releases and branchy development</title>
     1.8 +
     1.9 +  <para>Mercurial provides several mechanisms for you to manage a
    1.10 +    project that is making progress on multiple fronts at once.  To
    1.11 +    understand these mechanisms, let's first take a brief look at a
    1.12 +    fairly normal software project structure.</para>
    1.13 +
    1.14 +  <para>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 +    records of project milestones such as releases.  We'll then
    1.22 +    continue on to talk about the flow of work between different
    1.23 +    phases of a project, and how Mercurial can help you to isolate and
    1.24 +    manage this work.</para>
    1.25 +
    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 +      revision a <quote>release</quote>, it's a good idea to record
    1.31 +      the identity of that revision. This will let you reproduce that
    1.32 +      release at a later date, for whatever purpose you might need at
    1.33 +      the time (reproducing a bug, porting to a new platform, etc).
    1.34 +      <!-- &interaction.tag.init; --></para>
    1.35 +
    1.36 +    <para>Mercurial lets you give a permanent name to any revision
    1.37 +      using the <command role="hg-cmd">hg tag</command> command.  Not
    1.38 +      surprisingly, these names are called <quote>tags</quote>. <!--
    1.39 +      &interaction.tag.tag; --></para>
    1.40 +
    1.41 +    <para>A tag is nothing more than a <quote>symbolic name</quote>
    1.42 +      for a revision.  Tags exist purely for your convenience, so that
    1.43 +      you have a handy permanent way to refer to a revision; Mercurial
    1.44 +      doesn't interpret the tag names you use in any way.  Neither
    1.45 +      does Mercurial place any restrictions on the name of a tag,
    1.46 +      beyond a few that are necessary to ensure that a tag can be
    1.47 +      parsed unambiguously.  A tag name cannot contain any of the
    1.48 +      following characters:</para>
    1.49 +    <itemizedlist>
    1.50 +      <listitem><para>Colon (ASCII 58,
    1.51 +	  <quote><literal>:</literal></quote>)</para>
    1.52 +      </listitem>
    1.53 +      <listitem><para>Carriage return (ASCII 13,
    1.54 +	  <quote><literal>\r</literal></quote>)</para>
    1.55 +      </listitem>
    1.56 +      <listitem><para>Newline (ASCII 10,
    1.57 +	  <quote><literal>\n</literal></quote>)</para>
    1.58 +      </listitem></itemizedlist>
    1.59 +
    1.60 +    <para>You can use the <command role="hg-cmd">hg tags</command>
    1.61 +      command to display the tags present in your repository.  In the
    1.62 +      output, each tagged revision is identified first by its name,
    1.63 +      then by revision number, and finally by the unique hash of the
    1.64 +      revision. <!-- &interaction.tag.tags; --> Notice that
    1.65 +      <literal>tip</literal> is listed in the output of <command
    1.66 +	role="hg-cmd">hg tags</command>.  The <literal>tip</literal>
    1.67 +      tag is a special <quote>floating</quote> tag, which always
    1.68 +      identifies the newest revision in the repository.</para>
    1.69 +
    1.70 +    <para>In the output of the <command role="hg-cmd">hg
    1.71 +	tags</command> command, tags are listed in reverse order, by
    1.72 +      revision number.  This usually means that recent tags are listed
    1.73 +      before older tags.  It also means that <literal>tip</literal> is
    1.74 +      always going to be the first tag listed in the output of
    1.75 +      <command role="hg-cmd">hg tags</command>.</para>
    1.76 +
    1.77 +    <para>When you run <command role="hg-cmd">hg log</command>, if it
    1.78 +      displays a revision that has tags associated with it, it will
    1.79 +      print those tags. <!-- &interaction.tag.log; --></para>
    1.80 +
    1.81 +    <para>Any time you need to provide a revision ID to a Mercurial
    1.82 +      command, the command will accept a tag name in its place.
    1.83 +      Internally, Mercurial will translate your tag name into the
    1.84 +      corresponding revision ID, then use that. <!--
    1.85 +      &interaction.tag.log.v1.0; --></para>
    1.86 +
    1.87 +    <para>There's no limit on the number of tags you can have in a
    1.88 +      repository, or on the number of tags that a single revision can
    1.89 +      have.  As a practical matter, it's not a great idea to have
    1.90 +      <quote>too many</quote> (a number which will vary from project
    1.91 +      to project), simply because tags are supposed to help you to
    1.92 +      find revisions.  If you have lots of tags, the ease of using
    1.93 +      them to identify revisions diminishes rapidly.</para>
    1.94 +
    1.95 +    <para>For example, if your project has milestones as frequent as
    1.96 +      every few days, it's perfectly reasonable to tag each one of
    1.97 +      those.  But if you have a continuous build system that makes
    1.98 +      sure every revision can be built cleanly, you'd be introducing a
    1.99 +      lot of noise if you were to tag every clean build.  Instead, you
   1.100 +      could tag failed builds (on the assumption that they're rare!),
   1.101 +      or simply not use tags to track buildability.</para>
   1.102 +
   1.103 +    <para>If you want to remove a tag that you no longer want, use
   1.104 +      <command role="hg-cmd">hg tag --remove</command>. <!--
   1.105 +      &interaction.tag.remove; --> You can also modify a tag at any
   1.106 +      time, so that it identifies a different revision, by simply
   1.107 +      issuing a new <command role="hg-cmd">hg tag</command> command.
   1.108 +      You'll have to use the <option role="hg-opt-tag">-f</option>
   1.109 +      option to tell Mercurial that you <emphasis>really</emphasis>
   1.110 +      want to update the tag. <!-- &interaction.tag.replace; --> There
   1.111 +      will still be a permanent record of the previous identity of the
   1.112 +      tag, but Mercurial will no longer use it.  There's thus no
   1.113 +      penalty to tagging the wrong revision; all you have to do is
   1.114 +      turn around and tag the correct revision once you discover your
   1.115 +      error.</para>
   1.116 +
   1.117 +    <para>Mercurial stores tags in a normal revision-controlled file
   1.118 +      in your repository.  If you've created any tags, you'll find
   1.119 +      them in a file named <filename
   1.120 +	role="special">.hgtags</filename>.  When you run the <command
   1.121 +	role="hg-cmd">hg tag</command> command, Mercurial modifies
   1.122 +      this file, then automatically commits the change to it.  This
   1.123 +      means that every time you run <command role="hg-cmd">hg
   1.124 +	tag</command>, you'll see a corresponding changeset in the
   1.125 +      output of <command role="hg-cmd">hg log</command>. <!--
   1.126 +      &interaction.tag.tip; --></para>
   1.127 +
   1.128 +    <sect2>
   1.129 +      <title>Handling tag conflicts during a merge</title>
   1.130 +
   1.131 +      <para>You won't often need to care about the <filename
   1.132 +	  role="special">.hgtags</filename> file, but it sometimes
   1.133 +	makes its presence known during a merge.  The format of the
   1.134 +	file is simple: it consists of a series of lines.  Each line
   1.135 +	starts with a changeset hash, followed by a space, followed by
   1.136 +	the name of a tag.</para>
   1.137 +
   1.138 +      <para>If you're resolving a conflict in the <filename
   1.139 +	  role="special">.hgtags</filename> file during a merge,
   1.140 +	there's one twist to modifying the <filename
   1.141 +	  role="special">.hgtags</filename> file: when Mercurial is
   1.142 +	parsing the tags in a repository, it
   1.143 +	<emphasis>never</emphasis> reads the working copy of the
   1.144 +	<filename role="special">.hgtags</filename> file.  Instead, it
   1.145 +	reads the <emphasis>most recently committed</emphasis>
   1.146 +	revision of the file.</para>
   1.147 +
   1.148 +      <para>An unfortunate consequence of this design is that you
   1.149 +	can't actually verify that your merged <filename
   1.150 +	  role="special">.hgtags</filename> file is correct until
   1.151 +	<emphasis>after</emphasis> you've committed a change.  So if
   1.152 +	you find yourself resolving a conflict on <filename
   1.153 +	  role="special">.hgtags</filename> during a merge, be sure to
   1.154 +	run <command role="hg-cmd">hg tags</command> after you commit.
   1.155 +	If it finds an error in the <filename
   1.156 +	  role="special">.hgtags</filename> file, it will report the
   1.157 +	location of the error, which you can then fix and commit.  You
   1.158 +	should then run <command role="hg-cmd">hg tags</command>
   1.159 +	again, just to be sure that your fix is correct.</para>
   1.160 +
   1.161 +    </sect2>
   1.162 +    <sect2>
   1.163 +      <title>Tags and cloning</title>
   1.164 +
   1.165 +      <para>You may have noticed that the <command role="hg-cmd">hg
   1.166 +	  clone</command> command has a <option
   1.167 +	  role="hg-opt-clone">-r</option> option that lets you clone
   1.168 +	an exact copy of the repository as of a particular changeset.
   1.169 +	The new clone will not contain any project history that comes
   1.170 +	after the revision you specified.  This has an interaction
   1.171 +	with tags that can surprise the unwary.</para>
   1.172 +
   1.173 +      <para>Recall that a tag is stored as a revision to the <filename
   1.174 +	  role="special">.hgtags</filename> file, so that when you
   1.175 +	create a tag, the changeset in which it's recorded necessarily
   1.176 +	refers to an older changeset.  When you run <command
   1.177 +	  role="hg-cmd">hg clone -r foo</command> to clone a
   1.178 +	repository as of tag <literal>foo</literal>, the new clone
   1.179 +	<emphasis>will not contain the history that created the
   1.180 +	  tag</emphasis> that you used to clone the repository.  The
   1.181 +	result is that you'll get exactly the right subset of the
   1.182 +	project's history in the new repository, but
   1.183 +	<emphasis>not</emphasis> the tag you might have
   1.184 +	expected.</para>
   1.185 +
   1.186 +    </sect2>
   1.187 +    <sect2>
   1.188 +      <title>When permanent tags are too much</title>
   1.189 +
   1.190 +      <para>Since Mercurial's tags are revision controlled and carried
   1.191 +	around with a project's history, everyone you work with will
   1.192 +	see the tags you create.  But giving names to revisions has
   1.193 +	uses beyond simply noting that revision
   1.194 +	<literal>4237e45506ee</literal> is really
   1.195 +	<literal>v2.0.2</literal>.  If you're trying to track down a
   1.196 +	subtle bug, you might want a tag to remind you of something
   1.197 +	like <quote>Anne saw the symptoms with this
   1.198 +	  revision</quote>.</para>
   1.199 +
   1.200 +      <para>For cases like this, what you might want to use are
   1.201 +	<emphasis>local</emphasis> tags. You can create a local tag
   1.202 +	with the <option role="hg-opt-tag">-l</option> option to the
   1.203 +	<command role="hg-cmd">hg tag</command> command.  This will
   1.204 +	store the tag in a file called <filename
   1.205 +	  role="special">.hg/localtags</filename>.  Unlike <filename
   1.206 +	  role="special">.hgtags</filename>, <filename
   1.207 +	  role="special">.hg/localtags</filename> is not revision
   1.208 +	controlled.  Any tags you create using <option
   1.209 +	  role="hg-opt-tag">-l</option> remain strictly local to the
   1.210 +	repository you're currently working in.</para>
   1.211 +
   1.212 +    </sect2>
   1.213 +  </sect1>
   1.214 +  <sect1>
   1.215 +    <title>The flow of changes&emdash;big picture vs. little</title>
   1.216 +
   1.217 +    <para>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 +      a new minor bugfix release to the last main release; and an
   1.223 +      unexpected <quote>hot fix</quote> to an old release that is now
   1.224 +      in maintenance mode.</para>
   1.225 +
   1.226 +    <para>The usual way people refer to these different concurrent
   1.227 +      directions of development is as <quote>branches</quote>.
   1.228 +      However, we've already seen numerous times that Mercurial treats
   1.229 +      <emphasis>all of history</emphasis> as a series of branches and
   1.230 +      merges.  Really, what we have here is two ideas that are
   1.231 +      peripherally related, but which happen to share a name.</para>
   1.232 +    <itemizedlist>
   1.233 +      <listitem><para><quote>Big picture</quote> branches represent
   1.234 +	  the sweep of a project's evolution; people give them names,
   1.235 +	  and talk about them in conversation.</para>
   1.236 +      </listitem>
   1.237 +      <listitem><para><quote>Little picture</quote> branches are
   1.238 +	  artefacts of the day-to-day activity of developing and
   1.239 +	  merging changes.  They expose the narrative of how the code
   1.240 +	  was developed.</para>
   1.241 +      </listitem></itemizedlist>
   1.242 +
   1.243 +  </sect1>
   1.244 +  <sect1>
   1.245 +    <title>Managing big-picture branches in repositories</title>
   1.246 +
   1.247 +    <para>The easiest way to isolate a <quote>big picture</quote>
   1.248 +      branch in Mercurial is in a dedicated repository.  If you have
   1.249 +      an existing shared repository&emdash;let's call it
   1.250 +      <literal>myproject</literal>&emdash;that reaches a
   1.251 +      <quote>1.0</quote> milestone, you can start to prepare for
   1.252 +      future maintenance releases on top of version 1.0 by tagging the
   1.253 +      revision from which you prepared the 1.0 release. <!--
   1.254 +      &interaction.branch-repo.tag; --> You can then clone a new
   1.255 +      shared <literal>myproject-1.0.1</literal> repository as of that
   1.256 +      tag. <!-- &interaction.branch-repo.clone; --></para>
   1.257 +
   1.258 +    <para>Afterwards, if someone needs to work on a bug fix that ought
   1.259 +      to go into an upcoming 1.0.1 minor release, they clone the
   1.260 +      <literal>myproject-1.0.1</literal> repository, make their
   1.261 +      changes, and push them back. <!--
   1.262 +      &interaction.branch-repo.bugfix; --> Meanwhile, development for
   1.263 +      the next major release can continue, isolated and unabated, in
   1.264 +      the <literal>myproject</literal> repository. <!--
   1.265 +      &interaction.branch-repo.new; --></para>
   1.266 +
   1.267 +  </sect1>
   1.268 +  <sect1>
   1.269 +    <title>Don't repeat yourself: merging across branches</title>
   1.270 +
   1.271 +    <para>In many cases, if you have a bug to fix on a maintenance
   1.272 +      branch, the chances are good that the bug exists on your
   1.273 +      project's main branch (and possibly other maintenance branches,
   1.274 +      too).  It's a rare developer who wants to fix the same bug
   1.275 +      multiple times, so let's look at a few ways that Mercurial can
   1.276 +      help you to manage these bugfixes without duplicating your
   1.277 +      work.</para>
   1.278 +
   1.279 +    <para>In the simplest instance, all you need to do is pull changes
   1.280 +      from your maintenance branch into your local clone of the target
   1.281 +      branch. <!-- &interaction.branch-repo.pull; --> You'll then need
   1.282 +      to merge the heads of the two branches, and push back to the
   1.283 +      main branch. <!-- &interaction.branch-repo.merge; --></para>
   1.284 +
   1.285 +  </sect1>
   1.286 +  <sect1>
   1.287 +    <title>Naming branches within one repository</title>
   1.288 +
   1.289 +    <para>In most instances, isolating branches in repositories is the
   1.290 +      right approach.  Its simplicity makes it easy to understand; and
   1.291 +      so it's hard to make mistakes.  There's a one-to-one
   1.292 +      relationship between branches you're working in and directories
   1.293 +      on your system.  This lets you use normal (non-Mercurial-aware)
   1.294 +      tools to work on files within a branch/repository.</para>
   1.295 +
   1.296 +    <para>If you're more in the <quote>power user</quote> category
   1.297 +      (<emphasis>and</emphasis> your collaborators are too), there is
   1.298 +      an alternative way of handling branches that you can consider.
   1.299 +      I've already mentioned the human-level distinction between
   1.300 +      <quote>small picture</quote> and <quote>big picture</quote>
   1.301 +      branches.  While Mercurial works with multiple <quote>small
   1.302 +	picture</quote> branches in a repository all the time (for
   1.303 +      example after you pull changes in, but before you merge them),
   1.304 +      it can <emphasis>also</emphasis> work with multiple <quote>big
   1.305 +	picture</quote> branches.</para>
   1.306 +
   1.307 +    <para>The key to working this way is that Mercurial lets you
   1.308 +      assign a persistent <emphasis>name</emphasis> to a branch.
   1.309 +      There always exists a branch named <literal>default</literal>.
   1.310 +      Even before you start naming branches yourself, you can find
   1.311 +      traces of the <literal>default</literal> branch if you look for
   1.312 +      them.</para>
   1.313 +
   1.314 +    <para>As an example, when you run the <command role="hg-cmd">hg
   1.315 +	commit</command> command, and it pops up your editor so that
   1.316 +      you can enter a commit message, look for a line that contains
   1.317 +      the text <quote><literal>HG: branch default</literal></quote> at
   1.318 +      the bottom. This is telling you that your commit will occur on
   1.319 +      the branch named <literal>default</literal>.</para>
   1.320 +
   1.321 +    <para>To start working with named branches, use the <command
   1.322 +	role="hg-cmd">hg branches</command> command.  This command
   1.323 +      lists the named branches already present in your repository,
   1.324 +      telling you which changeset is the tip of each. <!--
   1.325 +      &interaction.branch-named.branches; --> Since you haven't
   1.326 +      created any named branches yet, the only one that exists is
   1.327 +      <literal>default</literal>.</para>
   1.328 +
   1.329 +    <para>To find out what the <quote>current</quote> branch is, run
   1.330 +      the <command role="hg-cmd">hg branch</command> command, giving
   1.331 +      it no arguments.  This tells you what branch the parent of the
   1.332 +      current changeset is on. <!-- &interaction.branch-named.branch;
   1.333 +      --></para>
   1.334 +
   1.335 +    <para>To create a new branch, run the <command role="hg-cmd">hg
   1.336 +	branch</command> command again.  This time, give it one
   1.337 +      argument: the name of the branch you want to create. <!--
   1.338 +      &interaction.branch-named.create; --></para>
   1.339 +
   1.340 +    <para>After you've created a branch, you might wonder what effect
   1.341 +      the <command role="hg-cmd">hg branch</command> command has had.
   1.342 +      What do the <command role="hg-cmd">hg status</command> and
   1.343 +      <command role="hg-cmd">hg tip</command> commands report? <!--
   1.344 +      &interaction.branch-named.status; --> Nothing has changed in the
   1.345 +      working directory, and there's been no new history created.  As
   1.346 +      this suggests, running the <command role="hg-cmd">hg
   1.347 +	branch</command> command has no permanent effect; it only
   1.348 +      tells Mercurial what branch name to use the
   1.349 +      <emphasis>next</emphasis> time you commit a changeset.</para>
   1.350 +
   1.351 +    <para>When you commit a change, Mercurial records the name of the
   1.352 +      branch on which you committed.  Once you've switched from the
   1.353 +      <literal>default</literal> branch to another and committed,
   1.354 +      you'll see the name of the new branch show up in the output of
   1.355 +      <command role="hg-cmd">hg log</command>, <command
   1.356 +	role="hg-cmd">hg tip</command>, and other commands that
   1.357 +      display the same kind of output. <!--
   1.358 +      &interaction.branch-named.commit; --> The <command
   1.359 +	role="hg-cmd">hg log</command>-like commands will print the
   1.360 +      branch name of every changeset that's not on the
   1.361 +      <literal>default</literal> branch.  As a result, if you never
   1.362 +      use named branches, you'll never see this information.</para>
   1.363 +
   1.364 +    <para>Once you've named a branch and committed a change with that
   1.365 +      name, every subsequent commit that descends from that change
   1.366 +      will inherit the same branch name.  You can change the name of a
   1.367 +      branch at any time, using the <command role="hg-cmd">hg
   1.368 +	branch</command> command. <!--
   1.369 +      &interaction.branch-named.rebranch; --> In practice, this is
   1.370 +      something you won't do very often, as branch names tend to have
   1.371 +      fairly long lifetimes.  (This isn't a rule, just an
   1.372 +      observation.)</para>
   1.373 +
   1.374 +  </sect1>
   1.375 +  <sect1>
   1.376 +    <title>Dealing with multiple named branches in a
   1.377 +      repository</title>
   1.378 +
   1.379 +    <para>If you have more than one named branch in a repository,
   1.380 +      Mercurial will remember the branch that your working directory
   1.381 +      on when you start a command like <command role="hg-cmd">hg
   1.382 +	update</command> or <command role="hg-cmd">hg pull
   1.383 +	-u</command>.  It will update the working directory to the tip
   1.384 +      of this branch, no matter what the <quote>repo-wide</quote> tip
   1.385 +      is.  To update to a revision that's on a different named branch,
   1.386 +      you may need to use the <option role="hg-opt-update">-C</option>
   1.387 +      option to <command role="hg-cmd">hg update</command>.</para>
   1.388 +
   1.389 +    <para>This behaviour is a little subtle, so let's see it in
   1.390 +      action.  First, let's remind ourselves what branch we're
   1.391 +      currently on, and what branches are in our repository. <!--
   1.392 +      &interaction.branch-named.parents; --> We're on the
   1.393 +      <literal>bar</literal> branch, but there also exists an older
   1.394 +      <command role="hg-cmd">hg foo</command> branch.</para>
   1.395 +
   1.396 +    <para>We can <command role="hg-cmd">hg update</command> back and
   1.397 +      forth between the tips of the <literal>foo</literal> and
   1.398 +      <literal>bar</literal> branches without needing to use the
   1.399 +      <option role="hg-opt-update">-C</option> option, because this
   1.400 +      only involves going backwards and forwards linearly through our
   1.401 +      change history. <!-- &interaction.branch-named.update-switchy;
   1.402 +      --></para>
   1.403 +
   1.404 +    <para>If we go back to the <literal>foo</literal> branch and then
   1.405 +      run <command role="hg-cmd">hg update</command>, it will keep us
   1.406 +      on <literal>foo</literal>, not move us to the tip of
   1.407 +      <literal>bar</literal>. <!--
   1.408 +      &interaction.branch-named.update-nothing; --></para>
   1.409 +
   1.410 +    <para>Committing a new change on the <literal>foo</literal> branch
   1.411 +      introduces a new head. <!--
   1.412 +      &interaction.branch-named.foo-commit; --></para>
   1.413 +
   1.414 +  </sect1>
   1.415 +  <sect1>
   1.416 +    <title>Branch names and merging</title>
   1.417 +
   1.418 +    <para>As you've probably noticed, merges in Mercurial are not
   1.419 +      symmetrical. Let's say our repository has two heads, 17 and 23.
   1.420 +      If I <command role="hg-cmd">hg update</command> to 17 and then
   1.421 +      <command role="hg-cmd">hg merge</command> with 23, Mercurial
   1.422 +      records 17 as the first parent of the merge, and 23 as the
   1.423 +      second.  Whereas if I <command role="hg-cmd">hg update</command>
   1.424 +      to 23 and then <command role="hg-cmd">hg merge</command> with
   1.425 +      17, it records 23 as the first parent, and 17 as the
   1.426 +      second.</para>
   1.427 +
   1.428 +    <para>This affects Mercurial's choice of branch name when you
   1.429 +      merge.  After a merge, Mercurial will retain the branch name of
   1.430 +      the first parent when you commit the result of the merge.  If
   1.431 +      your first parent's branch name is <literal>foo</literal>, and
   1.432 +      you merge with <literal>bar</literal>, the branch name will
   1.433 +      still be <literal>foo</literal> after you merge.</para>
   1.434 +
   1.435 +    <para>It's not unusual for a repository to contain multiple heads,
   1.436 +      each with the same branch name.  Let's say I'm working on the
   1.437 +      <literal>foo</literal> branch, and so are you.  We commit
   1.438 +      different changes; I pull your changes; I now have two heads,
   1.439 +      each claiming to be on the <literal>foo</literal> branch.  The
   1.440 +      result of a merge will be a single head on the
   1.441 +      <literal>foo</literal> branch, as you might hope.</para>
   1.442 +
   1.443 +    <para>But if I'm working on the <literal>bar</literal> branch, and
   1.444 +      I merge work from the <literal>foo</literal> branch, the result
   1.445 +      will remain on the <literal>bar</literal> branch. <!--
   1.446 +      &interaction.branch-named.merge; --></para>
   1.447 +
   1.448 +    <para>To give a more concrete example, if I'm working on the
   1.449 +      <literal>bleeding-edge</literal> branch, and I want to bring in
   1.450 +      the latest fixes from the <literal>stable</literal> branch,
   1.451 +      Mercurial will choose the <quote>right</quote>
   1.452 +      (<literal>bleeding-edge</literal>) branch name when I pull and
   1.453 +      merge from <literal>stable</literal>.</para>
   1.454 +
   1.455 +  </sect1>
   1.456 +  <sect1>
   1.457 +    <title>Branch naming is generally useful</title>
   1.458 +
   1.459 +    <para>You shouldn't think of named branches as applicable only to
   1.460 +      situations where you have multiple long-lived branches
   1.461 +      cohabiting in a single repository.  They're very useful even in
   1.462 +      the one-branch-per-repository case.</para>
   1.463 +
   1.464 +    <para>In the simplest case, giving a name to each branch gives you
   1.465 +      a permanent record of which branch a changeset originated on.
   1.466 +      This gives you more context when you're trying to follow the
   1.467 +      history of a long-lived branchy project.</para>
   1.468 +
   1.469 +    <para>If you're working with shared repositories, you can set up a
   1.470 +      <literal role="hook">pretxnchangegroup</literal> hook on each
   1.471 +      that will block incoming changes that have the
   1.472 +      <quote>wrong</quote> branch name.  This provides a simple, but
   1.473 +      effective, defence against people accidentally pushing changes
   1.474 +      from a <quote>bleeding edge</quote> branch to a
   1.475 +      <quote>stable</quote> branch.  Such a hook might look like this
   1.476 +      inside the shared repo's <filename role="special">
   1.477 +	/.hgrc</filename>.</para>
   1.478 +    <programlisting>[hooks] pretxnchangegroup.branch = hg heads
   1.479 +      --template '{branches} ' | grep mybranch</programlisting>
   1.480 +
   1.481 +  </sect1>
   1.482 +</chapter>
   1.483 +
   1.484 +<!--
   1.485 +local variables: 
   1.486 +sgml-parent-document: ("00book.xml" "book" "chapter")
   1.487 +end:
   1.488 +-->