1.1 --- a/en/branch.tex	Mon Apr 23 13:52:15 2007 -0700
     1.2 +++ b/en/branch.tex	Mon Apr 23 15:28:13 2007 -0700
     1.3 @@ -291,7 +291,48 @@
     1.4  
     1.5  Once you've named a branch and committed a change with that name,
     1.6  every subsequent commit that descends from that change will inherit
     1.7 -the same branch name.
     1.8 +the same branch name.  You can change the name of a branch at any
     1.9 +time, using the \hgcmd{branch} command.  
    1.10 +\interaction{branch-named.rebranch}
    1.11 +In practice, this is something you won't do very often, as branch
    1.12 +names tend to have fairly long lifetimes.  (This isn't a rule, just an
    1.13 +observation.)
    1.14 +
    1.15 +\section{Dealing with multiple named branches in a repository}
    1.16 +
    1.17 +If you have more than one named branch in a repository, Mercurial will
    1.18 +remember the branch that your working directory on when you start a
    1.19 +command like \hgcmd{update} or \hgcmdargs{pull}{-u}.  It will update
    1.20 +the working directory to the tip of this branch, no matter what the
    1.21 +``repo-wide'' tip is.  To update to a revision that's on a different
    1.22 +named branch, you may need to use the \hgopt{update}{-C} option to
    1.23 +\hgcmd{update}.
    1.24 +
    1.25 +This behaviour is a little subtle, so let's see it in action.  First,
    1.26 +let's remind ourselves what branch we're currently on, and what
    1.27 +branches are in our repository.
    1.28 +\interaction{branch-named.parents}
    1.29 +We're on the \texttt{bar} branch, but there also exists an older
    1.30 +\hgcmd{foo} branch.
    1.31 +
    1.32 +We can \hgcmd{update} back and forth between the tips of the
    1.33 +\texttt{foo} and \texttt{bar} branches without needing to use the
    1.34 +\hgopt{update}{-C} option, because this only involves going backwards
    1.35 +and forwards linearly through our change history.
    1.36 +\interaction{branch-named.update-switchy}
    1.37 +
    1.38 +If we go back to the \texttt{foo} branch and then run \hgcmd{update},
    1.39 +it will keep us on \texttt{foo}, not move us to the tip of
    1.40 +\texttt{bar}.
    1.41 +\interaction{branch-named.update-nothing}
    1.42 +
    1.43 +Committing a new change on the \texttt{foo} branch introduces a new
    1.44 +head.
    1.45 +\interaction{branch-named.foo-commit}
    1.46 +We can no longer update from \texttt{foo} to \texttt{bar} without
    1.47 +going ``sideways'' in history, so Mercurial forces us to provide the
    1.48 +\hgopt{update}{-C} option to \hgcmd{update}.
    1.49 +\interaction{branch-named.update-bar}
    1.50  
    1.51  \section{Branch names and merging}
    1.52  
    1.53 @@ -302,10 +343,47 @@
    1.54  I \hgcmd{update} to 23 and then \hgcmd{merge} with 17, it records 23
    1.55  as the first parent, and 17 as the second.
    1.56  
    1.57 -This behaviour affects Mercurial's choice of branch name when you
    1.58 -merge.  During a merge, Mercurial will by default use the name of the
    1.59 -first parent.
    1.60 -
    1.61 +This affects Mercurial's choice of branch name when you merge.  After
    1.62 +a merge, Mercurial will retain the branch name of the first parent
    1.63 +when you commit the result of the merge.  If your first parent's
    1.64 +branch name is \texttt{foo}, and you merge with \texttt{bar}, the
    1.65 +branch name will still be \texttt{foo} after you merge.
    1.66 +
    1.67 +It's not unusual for a repository to contain multiple heads, each with
    1.68 +the same branch name.  Let's say I'm working on the \texttt{foo}
    1.69 +branch, and so are you.  We commit different changes; I pull your
    1.70 +changes; I now have two heads, each claiming to be on the \texttt{foo}
    1.71 +branch.  The result of a merge will be a single head on the
    1.72 +\texttt{foo} branch, as you might hope.
    1.73 +
    1.74 +But if I'm working on the \texttt{bar} branch, and I merge work from
    1.75 +the \texttt{foo} branch, the result will remain on the \texttt{bar}
    1.76 +branch.
    1.77 +\interaction{branch-named.merge}
    1.78 +
    1.79 +To give a more concrete example, if I'm working on the
    1.80 +\texttt{bleeding-edge} branch, and I want to bring in the latest fixes
    1.81 +from the \texttt{stable} branch, Mercurial will choose the ``right''
    1.82 +(\texttt{bleeding-edge}) branch name when I pull and merge from
    1.83 +\texttt{stable}.
    1.84 +
    1.85 +\section{Branch naming is generally useful}
    1.86 +
    1.87 +You shouldn't think of named branches as applicable only to situations
    1.88 +where you have multiple long-lived branches cohabiting in a single
    1.89 +repository.  They're very useful even in the one-branch-per-repository
    1.90 +case.  
    1.91 +
    1.92 +In the simplest case, giving a name to each branch gives you a
    1.93 +permanent record of which branch a changeset originated on.  This
    1.94 +gives you a more context when you're trying to follow the history of a
    1.95 +long-lived branchy project.
    1.96 +
    1.97 +If you're working with multiple shared repositories, you can set up a
    1.98 +hook on each that will block incoming changes that have the ``wrong''
    1.99 +branch name.  This provides a simple, but effective, defence against
   1.100 +people accidentally pushing changes from a ``bleeding edge'' branch to
   1.101 +a ``stable'' branch.
   1.102  
   1.103  %%% Local Variables: 
   1.104  %%% mode: latex