bos@559: <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
bos@559: 
bos@559: <chapter id="chap:branch">
bos@572:   <?dbhtml filename="managing-releases-and-branchy-development.html"?>
bos@559:   <title>Managing releases and branchy development</title>
bos@559: 
bos@584:   <para id="x_369">Mercurial provides several mechanisms for you to manage a
bos@559:     project that is making progress on multiple fronts at once.  To
bos@559:     understand these mechanisms, let's first take a brief look at a
bos@559:     fairly normal software project structure.</para>
bos@559: 
bos@584:   <para id="x_36a">Many software projects issue periodic <quote>major</quote>
bos@559:     releases that contain substantial new features.  In parallel, they
bos@559:     may issue <quote>minor</quote> releases.  These are usually
bos@559:     identical to the major releases off which they're based, but with
bos@559:     a few bugs fixed.</para>
bos@559: 
bos@584:   <para id="x_36b">In this chapter, we'll start by talking about how to keep
bos@559:     records of project milestones such as releases.  We'll then
bos@559:     continue on to talk about the flow of work between different
bos@559:     phases of a project, and how Mercurial can help you to isolate and
bos@559:     manage this work.</para>
bos@559: 
bos@559:   <sect1>
bos@559:     <title>Giving a persistent name to a revision</title>
bos@559: 
bos@584:     <para id="x_36c">Once you decide that you'd like to call a particular
bos@559:       revision a <quote>release</quote>, it's a good idea to record
bos@559:       the identity of that revision. This will let you reproduce that
bos@559:       release at a later date, for whatever purpose you might need at
bos@559:       the time (reproducing a bug, porting to a new platform, etc).
bos@567:       &interaction.tag.init;</para>
bos@559: 
bos@584:     <para id="x_36d">Mercurial lets you give a permanent name to any revision
bos@559:       using the <command role="hg-cmd">hg tag</command> command.  Not
bos@567:       surprisingly, these names are called <quote>tags</quote>.</para>
bos@567: 
bos@567:     &interaction.tag.tag;
bos@559: 
bos@584:     <para id="x_36e">A tag is nothing more than a <quote>symbolic name</quote>
bos@559:       for a revision.  Tags exist purely for your convenience, so that
bos@559:       you have a handy permanent way to refer to a revision; Mercurial
bos@559:       doesn't interpret the tag names you use in any way.  Neither
bos@559:       does Mercurial place any restrictions on the name of a tag,
bos@559:       beyond a few that are necessary to ensure that a tag can be
bos@559:       parsed unambiguously.  A tag name cannot contain any of the
bos@559:       following characters:</para>
bos@559:     <itemizedlist>
bos@584:       <listitem><para id="x_36f">Colon (ASCII 58,
bos@559: 	  <quote><literal>:</literal></quote>)</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_370">Carriage return (ASCII 13,
bos@559: 	  <quote><literal>\r</literal></quote>)</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_371">Newline (ASCII 10,
bos@559: 	  <quote><literal>\n</literal></quote>)</para>
bos@559:       </listitem></itemizedlist>
bos@559: 
bos@584:     <para id="x_372">You can use the <command role="hg-cmd">hg tags</command>
bos@559:       command to display the tags present in your repository.  In the
bos@559:       output, each tagged revision is identified first by its name,
bos@559:       then by revision number, and finally by the unique hash of the
bos@567:       revision.</para>
bos@567: 
bos@567:     &interaction.tag.tags;
bos@567: 
bos@584:     <para id="x_373">Notice that <literal>tip</literal> is listed in the output
bos@567:       of <command role="hg-cmd">hg tags</command>.  The
bos@567:       <literal>tip</literal> tag is a special <quote>floating</quote>
bos@567:       tag, which always identifies the newest revision in the
bos@567:       repository.</para>
bos@559: 
bos@584:     <para id="x_374">In the output of the <command role="hg-cmd">hg
bos@559: 	tags</command> command, tags are listed in reverse order, by
bos@559:       revision number.  This usually means that recent tags are listed
bos@559:       before older tags.  It also means that <literal>tip</literal> is
bos@559:       always going to be the first tag listed in the output of
bos@559:       <command role="hg-cmd">hg tags</command>.</para>
bos@559: 
bos@584:     <para id="x_375">When you run <command role="hg-cmd">hg log</command>, if it
bos@559:       displays a revision that has tags associated with it, it will
bos@567:       print those tags.</para>
bos@567: 
bos@567:     &interaction.tag.log;
bos@559: 
bos@584:     <para id="x_376">Any time you need to provide a revision ID to a Mercurial
bos@559:       command, the command will accept a tag name in its place.
bos@559:       Internally, Mercurial will translate your tag name into the
bos@567:       corresponding revision ID, then use that.</para>
bos@567: 
bos@567:     &interaction.tag.log.v1.0;
bos@559: 
bos@584:     <para id="x_377">There's no limit on the number of tags you can have in a
bos@559:       repository, or on the number of tags that a single revision can
bos@559:       have.  As a practical matter, it's not a great idea to have
bos@559:       <quote>too many</quote> (a number which will vary from project
bos@559:       to project), simply because tags are supposed to help you to
bos@559:       find revisions.  If you have lots of tags, the ease of using
bos@559:       them to identify revisions diminishes rapidly.</para>
bos@559: 
bos@584:     <para id="x_378">For example, if your project has milestones as frequent as
bos@559:       every few days, it's perfectly reasonable to tag each one of
bos@559:       those.  But if you have a continuous build system that makes
bos@559:       sure every revision can be built cleanly, you'd be introducing a
bos@559:       lot of noise if you were to tag every clean build.  Instead, you
bos@559:       could tag failed builds (on the assumption that they're rare!),
bos@559:       or simply not use tags to track buildability.</para>
bos@559: 
bos@584:     <para id="x_379">If you want to remove a tag that you no longer want, use
bos@567:       <command role="hg-cmd">hg tag --remove</command>.</para>
bos@567: 
bos@567:     &interaction.tag.remove;
bos@567: 
bos@584:     <para id="x_37a">You can also modify a tag at any time, so that it identifies
bos@567:       a different revision, by simply issuing a new <command
bos@567: 	role="hg-cmd">hg tag</command> command. You'll have to use the
bos@567:       <option role="hg-opt-tag">-f</option> option to tell Mercurial
bos@567:       that you <emphasis>really</emphasis> want to update the
bos@567:       tag.</para>
bos@567: 
bos@567:     &interaction.tag.replace;
bos@567: 
bos@584:     <para id="x_37b">There will still be a permanent record of the previous
bos@567:       identity of the tag, but Mercurial will no longer use it.
bos@567:       There's thus no penalty to tagging the wrong revision; all you
bos@567:       have to do is turn around and tag the correct revision once you
bos@567:       discover your error.</para>
bos@559: 
bos@584:     <para id="x_37c">Mercurial stores tags in a normal revision-controlled file
bos@559:       in your repository.  If you've created any tags, you'll find
bos@559:       them in a file named <filename
bos@559: 	role="special">.hgtags</filename>.  When you run the <command
bos@559: 	role="hg-cmd">hg tag</command> command, Mercurial modifies
bos@559:       this file, then automatically commits the change to it.  This
bos@559:       means that every time you run <command role="hg-cmd">hg
bos@559: 	tag</command>, you'll see a corresponding changeset in the
bos@567:       output of <command role="hg-cmd">hg log</command>.</para>
bos@567: 
bos@567:     &interaction.tag.tip;
bos@559: 
bos@559:     <sect2>
bos@559:       <title>Handling tag conflicts during a merge</title>
bos@559: 
bos@584:       <para id="x_37d">You won't often need to care about the <filename
bos@559: 	  role="special">.hgtags</filename> file, but it sometimes
bos@559: 	makes its presence known during a merge.  The format of the
bos@559: 	file is simple: it consists of a series of lines.  Each line
bos@559: 	starts with a changeset hash, followed by a space, followed by
bos@559: 	the name of a tag.</para>
bos@559: 
bos@584:       <para id="x_37e">If you're resolving a conflict in the <filename
bos@559: 	  role="special">.hgtags</filename> file during a merge,
bos@559: 	there's one twist to modifying the <filename
bos@559: 	  role="special">.hgtags</filename> file: when Mercurial is
bos@559: 	parsing the tags in a repository, it
bos@559: 	<emphasis>never</emphasis> reads the working copy of the
bos@559: 	<filename role="special">.hgtags</filename> file.  Instead, it
bos@559: 	reads the <emphasis>most recently committed</emphasis>
bos@559: 	revision of the file.</para>
bos@559: 
bos@584:       <para id="x_37f">An unfortunate consequence of this design is that you
bos@559: 	can't actually verify that your merged <filename
bos@559: 	  role="special">.hgtags</filename> file is correct until
bos@559: 	<emphasis>after</emphasis> you've committed a change.  So if
bos@559: 	you find yourself resolving a conflict on <filename
bos@559: 	  role="special">.hgtags</filename> during a merge, be sure to
bos@559: 	run <command role="hg-cmd">hg tags</command> after you commit.
bos@559: 	If it finds an error in the <filename
bos@559: 	  role="special">.hgtags</filename> file, it will report the
bos@559: 	location of the error, which you can then fix and commit.  You
bos@559: 	should then run <command role="hg-cmd">hg tags</command>
bos@559: 	again, just to be sure that your fix is correct.</para>
bos@559: 
bos@559:     </sect2>
bos@559:     <sect2>
bos@559:       <title>Tags and cloning</title>
bos@559: 
bos@584:       <para id="x_380">You may have noticed that the <command role="hg-cmd">hg
bos@559: 	  clone</command> command has a <option
bos@559: 	  role="hg-opt-clone">-r</option> option that lets you clone
bos@559: 	an exact copy of the repository as of a particular changeset.
bos@559: 	The new clone will not contain any project history that comes
bos@559: 	after the revision you specified.  This has an interaction
bos@559: 	with tags that can surprise the unwary.</para>
bos@559: 
bos@584:       <para id="x_381">Recall that a tag is stored as a revision to the <filename
bos@559: 	  role="special">.hgtags</filename> file, so that when you
bos@559: 	create a tag, the changeset in which it's recorded necessarily
bos@559: 	refers to an older changeset.  When you run <command
bos@559: 	  role="hg-cmd">hg clone -r foo</command> to clone a
bos@559: 	repository as of tag <literal>foo</literal>, the new clone
bos@559: 	<emphasis>will not contain the history that created the
bos@559: 	  tag</emphasis> that you used to clone the repository.  The
bos@559: 	result is that you'll get exactly the right subset of the
bos@559: 	project's history in the new repository, but
bos@559: 	<emphasis>not</emphasis> the tag you might have
bos@559: 	expected.</para>
bos@559: 
bos@559:     </sect2>
bos@559:     <sect2>
bos@559:       <title>When permanent tags are too much</title>
bos@559: 
bos@584:       <para id="x_382">Since Mercurial's tags are revision controlled and carried
bos@559: 	around with a project's history, everyone you work with will
bos@559: 	see the tags you create.  But giving names to revisions has
bos@559: 	uses beyond simply noting that revision
bos@559: 	<literal>4237e45506ee</literal> is really
bos@559: 	<literal>v2.0.2</literal>.  If you're trying to track down a
bos@559: 	subtle bug, you might want a tag to remind you of something
bos@559: 	like <quote>Anne saw the symptoms with this
bos@559: 	  revision</quote>.</para>
bos@559: 
bos@584:       <para id="x_383">For cases like this, what you might want to use are
bos@559: 	<emphasis>local</emphasis> tags. You can create a local tag
bos@559: 	with the <option role="hg-opt-tag">-l</option> option to the
bos@559: 	<command role="hg-cmd">hg tag</command> command.  This will
bos@559: 	store the tag in a file called <filename
bos@559: 	  role="special">.hg/localtags</filename>.  Unlike <filename
bos@559: 	  role="special">.hgtags</filename>, <filename
bos@559: 	  role="special">.hg/localtags</filename> is not revision
bos@559: 	controlled.  Any tags you create using <option
bos@559: 	  role="hg-opt-tag">-l</option> remain strictly local to the
bos@559: 	repository you're currently working in.</para>
bos@559: 
bos@559:     </sect2>
bos@559:   </sect1>
bos@559:   <sect1>
bos@559:     <title>The flow of changes&emdash;big picture vs. little</title>
bos@559: 
bos@584:     <para id="x_384">To return to the outline I sketched at the beginning of a
bos@559:       chapter, let's think about a project that has multiple
bos@559:       concurrent pieces of work under development at once.</para>
bos@559: 
bos@584:     <para id="x_385">There might be a push for a new <quote>main</quote> release;
bos@559:       a new minor bugfix release to the last main release; and an
bos@559:       unexpected <quote>hot fix</quote> to an old release that is now
bos@559:       in maintenance mode.</para>
bos@559: 
bos@584:     <para id="x_386">The usual way people refer to these different concurrent
bos@559:       directions of development is as <quote>branches</quote>.
bos@559:       However, we've already seen numerous times that Mercurial treats
bos@559:       <emphasis>all of history</emphasis> as a series of branches and
bos@559:       merges.  Really, what we have here is two ideas that are
bos@559:       peripherally related, but which happen to share a name.</para>
bos@559:     <itemizedlist>
bos@584:       <listitem><para id="x_387"><quote>Big picture</quote> branches represent
bos@559: 	  the sweep of a project's evolution; people give them names,
bos@559: 	  and talk about them in conversation.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_388"><quote>Little picture</quote> branches are
bos@559: 	  artefacts of the day-to-day activity of developing and
bos@559: 	  merging changes.  They expose the narrative of how the code
bos@559: 	  was developed.</para>
bos@559:       </listitem></itemizedlist>
bos@559: 
bos@559:   </sect1>
bos@559:   <sect1>
bos@559:     <title>Managing big-picture branches in repositories</title>
bos@559: 
bos@584:     <para id="x_389">The easiest way to isolate a <quote>big picture</quote>
bos@559:       branch in Mercurial is in a dedicated repository.  If you have
bos@559:       an existing shared repository&emdash;let's call it
bos@559:       <literal>myproject</literal>&emdash;that reaches a
bos@559:       <quote>1.0</quote> milestone, you can start to prepare for
bos@559:       future maintenance releases on top of version 1.0 by tagging the
bos@567:       revision from which you prepared the 1.0 release.</para>
bos@567: 
bos@567:     &interaction.branch-repo.tag;
bos@567: 
bos@584:     <para id="x_38a">You can then clone a new shared
bos@567:       <literal>myproject-1.0.1</literal> repository as of that
bos@567:       tag.</para>
bos@567: 
bos@567:     &interaction.branch-repo.clone;
bos@559: 
bos@584:     <para id="x_38b">Afterwards, if someone needs to work on a bug fix that ought
bos@559:       to go into an upcoming 1.0.1 minor release, they clone the
bos@559:       <literal>myproject-1.0.1</literal> repository, make their
bos@567:       changes, and push them back.</para>
bos@567: 
bos@567:     &interaction.branch-repo.bugfix;
bos@567: 
bos@584:     <para id="x_38c">Meanwhile, development for
bos@559:       the next major release can continue, isolated and unabated, in
bos@567:       the <literal>myproject</literal> repository.</para>
bos@567: 
bos@567:     &interaction.branch-repo.new;
bos@559: 
bos@559:   </sect1>
bos@559:   <sect1>
bos@559:     <title>Don't repeat yourself: merging across branches</title>
bos@559: 
bos@584:     <para id="x_38d">In many cases, if you have a bug to fix on a maintenance
bos@559:       branch, the chances are good that the bug exists on your
bos@559:       project's main branch (and possibly other maintenance branches,
bos@559:       too).  It's a rare developer who wants to fix the same bug
bos@559:       multiple times, so let's look at a few ways that Mercurial can
bos@559:       help you to manage these bugfixes without duplicating your
bos@559:       work.</para>
bos@559: 
bos@584:     <para id="x_38e">In the simplest instance, all you need to do is pull changes
bos@559:       from your maintenance branch into your local clone of the target
bos@567:       branch.</para>
bos@567: 
bos@567:     &interaction.branch-repo.pull;
bos@567: 
bos@584:     <para id="x_38f">You'll then need to merge the heads of the two branches, and
bos@567:       push back to the main branch.</para>
bos@567: 
bos@567:     &interaction.branch-repo.merge;
bos@559: 
bos@559:   </sect1>
bos@559:   <sect1>
bos@559:     <title>Naming branches within one repository</title>
bos@559: 
bos@584:     <para id="x_390">In most instances, isolating branches in repositories is the
bos@559:       right approach.  Its simplicity makes it easy to understand; and
bos@559:       so it's hard to make mistakes.  There's a one-to-one
bos@559:       relationship between branches you're working in and directories
bos@559:       on your system.  This lets you use normal (non-Mercurial-aware)
bos@559:       tools to work on files within a branch/repository.</para>
bos@559: 
bos@584:     <para id="x_391">If you're more in the <quote>power user</quote> category
bos@559:       (<emphasis>and</emphasis> your collaborators are too), there is
bos@559:       an alternative way of handling branches that you can consider.
bos@559:       I've already mentioned the human-level distinction between
bos@559:       <quote>small picture</quote> and <quote>big picture</quote>
bos@559:       branches.  While Mercurial works with multiple <quote>small
bos@559: 	picture</quote> branches in a repository all the time (for
bos@559:       example after you pull changes in, but before you merge them),
bos@559:       it can <emphasis>also</emphasis> work with multiple <quote>big
bos@559: 	picture</quote> branches.</para>
bos@559: 
bos@584:     <para id="x_392">The key to working this way is that Mercurial lets you
bos@559:       assign a persistent <emphasis>name</emphasis> to a branch.
bos@559:       There always exists a branch named <literal>default</literal>.
bos@559:       Even before you start naming branches yourself, you can find
bos@559:       traces of the <literal>default</literal> branch if you look for
bos@559:       them.</para>
bos@559: 
bos@584:     <para id="x_393">As an example, when you run the <command role="hg-cmd">hg
bos@559: 	commit</command> command, and it pops up your editor so that
bos@559:       you can enter a commit message, look for a line that contains
bos@559:       the text <quote><literal>HG: branch default</literal></quote> at
bos@559:       the bottom. This is telling you that your commit will occur on
bos@559:       the branch named <literal>default</literal>.</para>
bos@559: 
bos@584:     <para id="x_394">To start working with named branches, use the <command
bos@559: 	role="hg-cmd">hg branches</command> command.  This command
bos@559:       lists the named branches already present in your repository,
bos@567:       telling you which changeset is the tip of each.</para>
bos@567: 
bos@567:     &interaction.branch-named.branches;
bos@567: 
bos@584:     <para id="x_395">Since you haven't created any named branches yet, the only
bos@567:       one that exists is <literal>default</literal>.</para>
bos@559: 
bos@584:     <para id="x_396">To find out what the <quote>current</quote> branch is, run
bos@559:       the <command role="hg-cmd">hg branch</command> command, giving
bos@559:       it no arguments.  This tells you what branch the parent of the
bos@567:       current changeset is on.</para>
bos@567: 
bos@567:     &interaction.branch-named.branch;
bos@559: 
bos@584:     <para id="x_397">To create a new branch, run the <command role="hg-cmd">hg
bos@559: 	branch</command> command again.  This time, give it one
bos@567:       argument: the name of the branch you want to create.</para>
bos@567: 
bos@567:     &interaction.branch-named.create;
bos@559: 
bos@584:     <para id="x_398">After you've created a branch, you might wonder what effect
bos@559:       the <command role="hg-cmd">hg branch</command> command has had.
bos@559:       What do the <command role="hg-cmd">hg status</command> and
bos@567:       <command role="hg-cmd">hg tip</command> commands report?</para>
bos@567: 
bos@567:     &interaction.branch-named.status;
bos@567: 
bos@584:     <para id="x_399">Nothing has changed in the
bos@559:       working directory, and there's been no new history created.  As
bos@559:       this suggests, running the <command role="hg-cmd">hg
bos@559: 	branch</command> command has no permanent effect; it only
bos@559:       tells Mercurial what branch name to use the
bos@559:       <emphasis>next</emphasis> time you commit a changeset.</para>
bos@559: 
bos@584:     <para id="x_39a">When you commit a change, Mercurial records the name of the
bos@559:       branch on which you committed.  Once you've switched from the
bos@559:       <literal>default</literal> branch to another and committed,
bos@559:       you'll see the name of the new branch show up in the output of
bos@559:       <command role="hg-cmd">hg log</command>, <command
bos@559: 	role="hg-cmd">hg tip</command>, and other commands that
bos@567:       display the same kind of output.</para>
bos@567: 
bos@567:     &interaction.branch-named.commit;
bos@567: 
bos@584:     <para id="x_39b">The <command role="hg-cmd">hg log</command>-like commands
bos@567:       will print the branch name of every changeset that's not on the
bos@559:       <literal>default</literal> branch.  As a result, if you never
bos@559:       use named branches, you'll never see this information.</para>
bos@559: 
bos@584:     <para id="x_39c">Once you've named a branch and committed a change with that
bos@559:       name, every subsequent commit that descends from that change
bos@559:       will inherit the same branch name.  You can change the name of a
bos@559:       branch at any time, using the <command role="hg-cmd">hg
bos@567: 	branch</command> command.</para>
bos@567: 
bos@567:     &interaction.branch-named.rebranch;
bos@567: 
bos@584:     <para id="x_39d">In practice, this is something you won't do very often, as
bos@567:       branch names tend to have fairly long lifetimes.  (This isn't a
bos@567:       rule, just an observation.)</para>
bos@559: 
bos@559:   </sect1>
bos@559:   <sect1>
bos@559:     <title>Dealing with multiple named branches in a
bos@559:       repository</title>
bos@559: 
bos@584:     <para id="x_39e">If you have more than one named branch in a repository,
bos@559:       Mercurial will remember the branch that your working directory
bos@559:       on when you start a command like <command role="hg-cmd">hg
bos@559: 	update</command> or <command role="hg-cmd">hg pull
bos@559: 	-u</command>.  It will update the working directory to the tip
bos@559:       of this branch, no matter what the <quote>repo-wide</quote> tip
bos@559:       is.  To update to a revision that's on a different named branch,
bos@559:       you may need to use the <option role="hg-opt-update">-C</option>
bos@559:       option to <command role="hg-cmd">hg update</command>.</para>
bos@559: 
bos@584:     <para id="x_39f">This behaviour is a little subtle, so let's see it in
bos@559:       action.  First, let's remind ourselves what branch we're
bos@567:       currently on, and what branches are in our repository.</para>
bos@567: 
bos@567:     &interaction.branch-named.parents;
bos@567: 
bos@584:     <para id="x_3a0">We're on the <literal>bar</literal> branch, but there also
bos@567:       exists an older <command role="hg-cmd">hg foo</command>
bos@567:       branch.</para>
bos@559: 
bos@584:     <para id="x_3a1">We can <command role="hg-cmd">hg update</command> back and
bos@559:       forth between the tips of the <literal>foo</literal> and
bos@559:       <literal>bar</literal> branches without needing to use the
bos@559:       <option role="hg-opt-update">-C</option> option, because this
bos@559:       only involves going backwards and forwards linearly through our
bos@567:       change history.</para>
bos@567: 
bos@567:     &interaction.branch-named.update-switchy;
bos@559: 
bos@584:     <para id="x_3a2">If we go back to the <literal>foo</literal> branch and then
bos@559:       run <command role="hg-cmd">hg update</command>, it will keep us
bos@559:       on <literal>foo</literal>, not move us to the tip of
bos@567:       <literal>bar</literal>.</para>
bos@567: 
bos@567:     &interaction.branch-named.update-nothing;
bos@559: 
bos@584:     <para id="x_3a3">Committing a new change on the <literal>foo</literal> branch
bos@567:       introduces a new head.</para>
bos@567: 
bos@567:     &interaction.branch-named.foo-commit;
bos@559: 
bos@559:   </sect1>
bos@559:   <sect1>
bos@559:     <title>Branch names and merging</title>
bos@559: 
bos@584:     <para id="x_3a4">As you've probably noticed, merges in Mercurial are not
bos@559:       symmetrical. Let's say our repository has two heads, 17 and 23.
bos@559:       If I <command role="hg-cmd">hg update</command> to 17 and then
bos@559:       <command role="hg-cmd">hg merge</command> with 23, Mercurial
bos@559:       records 17 as the first parent of the merge, and 23 as the
bos@559:       second.  Whereas if I <command role="hg-cmd">hg update</command>
bos@559:       to 23 and then <command role="hg-cmd">hg merge</command> with
bos@559:       17, it records 23 as the first parent, and 17 as the
bos@559:       second.</para>
bos@559: 
bos@584:     <para id="x_3a5">This affects Mercurial's choice of branch name when you
bos@559:       merge.  After a merge, Mercurial will retain the branch name of
bos@559:       the first parent when you commit the result of the merge.  If
bos@559:       your first parent's branch name is <literal>foo</literal>, and
bos@559:       you merge with <literal>bar</literal>, the branch name will
bos@559:       still be <literal>foo</literal> after you merge.</para>
bos@559: 
bos@584:     <para id="x_3a6">It's not unusual for a repository to contain multiple heads,
bos@559:       each with the same branch name.  Let's say I'm working on the
bos@559:       <literal>foo</literal> branch, and so are you.  We commit
bos@559:       different changes; I pull your changes; I now have two heads,
bos@559:       each claiming to be on the <literal>foo</literal> branch.  The
bos@559:       result of a merge will be a single head on the
bos@559:       <literal>foo</literal> branch, as you might hope.</para>
bos@559: 
bos@584:     <para id="x_3a7">But if I'm working on the <literal>bar</literal> branch, and
bos@559:       I merge work from the <literal>foo</literal> branch, the result
bos@567:       will remain on the <literal>bar</literal> branch.</para>
bos@567: 
bos@567:     &interaction.branch-named.merge;
bos@559: 
bos@584:     <para id="x_3a8">To give a more concrete example, if I'm working on the
bos@559:       <literal>bleeding-edge</literal> branch, and I want to bring in
bos@559:       the latest fixes from the <literal>stable</literal> branch,
bos@559:       Mercurial will choose the <quote>right</quote>
bos@559:       (<literal>bleeding-edge</literal>) branch name when I pull and
bos@559:       merge from <literal>stable</literal>.</para>
bos@559: 
bos@559:   </sect1>
bos@559:   <sect1>
bos@559:     <title>Branch naming is generally useful</title>
bos@559: 
bos@584:     <para id="x_3a9">You shouldn't think of named branches as applicable only to
bos@559:       situations where you have multiple long-lived branches
bos@559:       cohabiting in a single repository.  They're very useful even in
bos@559:       the one-branch-per-repository case.</para>
bos@559: 
bos@584:     <para id="x_3aa">In the simplest case, giving a name to each branch gives you
bos@559:       a permanent record of which branch a changeset originated on.
bos@559:       This gives you more context when you're trying to follow the
bos@559:       history of a long-lived branchy project.</para>
bos@559: 
bos@584:     <para id="x_3ab">If you're working with shared repositories, you can set up a
bos@559:       <literal role="hook">pretxnchangegroup</literal> hook on each
bos@559:       that will block incoming changes that have the
bos@559:       <quote>wrong</quote> branch name.  This provides a simple, but
bos@559:       effective, defence against people accidentally pushing changes
bos@559:       from a <quote>bleeding edge</quote> branch to a
bos@559:       <quote>stable</quote> branch.  Such a hook might look like this
bos@559:       inside the shared repo's <filename role="special">
bos@559: 	/.hgrc</filename>.</para>
bos@580:     <programlisting>[hooks]
bos@580: pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch</programlisting>
bos@559: 
bos@559:   </sect1>
bos@559: </chapter>
bos@559: 
bos@559: <!--
bos@559: local variables: 
bos@559: sgml-parent-document: ("00book.xml" "book" "chapter")
bos@559: end:
bos@559: -->