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