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

     2.1 --- a/en/examples/branch-named	Mon Apr 23 13:52:15 2007 -0700
     2.2 +++ b/en/examples/branch-named	Mon Apr 23 15:28:13 2007 -0700
     2.3 @@ -29,3 +29,46 @@
     2.4  echo 'hello again' >> myfile
     2.5  hg commit -m 'Second commit'
     2.6  hg tip
     2.7 +
     2.8 +#$ name: rebranch
     2.9 +
    2.10 +hg branch
    2.11 +hg branch bar
    2.12 +echo new file > newfile
    2.13 +hg commit -A -m 'Third commit'
    2.14 +hg tip
    2.15 +
    2.16 +#$ name: parents
    2.17 +
    2.18 +hg parents
    2.19 +hg branches
    2.20 +
    2.21 +#$ name: update-switchy
    2.22 +
    2.23 +hg update foo
    2.24 +hg parents
    2.25 +hg update bar
    2.26 +hg parents
    2.27 +
    2.28 +#$ name: update-nothing
    2.29 +
    2.30 +hg update foo
    2.31 +hg update
    2.32 +
    2.33 +#$ name: foo-commit
    2.34 +
    2.35 +echo something > somefile
    2.36 +hg commit -A -m 'New file'
    2.37 +hg heads
    2.38 +
    2.39 +#$ name: update-bar
    2.40 +
    2.41 +hg update bar
    2.42 +hg update -C bar
    2.43 +
    2.44 +#$ name: merge
    2.45 +
    2.46 +hg branch
    2.47 +hg merge
    2.48 +hg commit -m 'Merge'
    2.49 +hg tip

     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/en/examples/branch-named.branch.out	Mon Apr 23 15:28:13 2007 -0700
     3.3 @@ -0,0 +1,2 @@
     3.4 +$ \textbf{hg branch}
     3.5 +default

     4.1 --- a/en/examples/branch-named.branches.out	Mon Apr 23 13:52:15 2007 -0700
     4.2 +++ b/en/examples/branch-named.branches.out	Mon Apr 23 15:28:13 2007 -0700
     4.3 @@ -1,2 +1,9 @@
     4.4 +$ \textbf{hg tip}
     4.5 +changeset:   
     4.6 +tag:         tip
     4.7 +user:        Bryan O'Sullivan <bos@serpentine.com>
     4.8 +
     4.9 +summary:     Initial commit
    4.10 +
    4.11  $ \textbf{hg branches}
    4.12  default                        

     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/en/examples/branch-named.commit.out	Mon Apr 23 15:28:13 2007 -0700
     5.3 @@ -0,0 +1,10 @@
     5.4 +$ \textbf{echo 'hello again' >> myfile}
     5.5 +$ \textbf{hg commit -m 'Second commit'}
     5.6 +$ \textbf{hg tip}
     5.7 +changeset:   
     5.8 +branch:      foo
     5.9 +tag:         tip
    5.10 +user:        Bryan O'Sullivan <bos@serpentine.com>
    5.11 +
    5.12 +summary:     Second commit
    5.13 +

     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/en/examples/branch-named.create.out	Mon Apr 23 15:28:13 2007 -0700
     6.3 @@ -0,0 +1,3 @@
     6.4 +$ \textbf{hg branch foo}
     6.5 +$ \textbf{hg branch}
     6.6 +foo

     7.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.2 +++ b/en/examples/branch-named.foo-commit.out	Mon Apr 23 15:28:13 2007 -0700
     7.3 @@ -0,0 +1,18 @@
     7.4 +$ \textbf{echo something > somefile}
     7.5 +$ \textbf{hg commit -A -m 'New file'}
     7.6 +adding somefile
     7.7 +$ \textbf{hg heads}
     7.8 +changeset:   
     7.9 +branch:      foo
    7.10 +tag:         tip
    7.11 +parent:      
    7.12 +user:        Bryan O'Sullivan <bos@serpentine.com>
    7.13 +
    7.14 +summary:     New file
    7.15 +
    7.16 +changeset:   
    7.17 +branch:      bar
    7.18 +user:        Bryan O'Sullivan <bos@serpentine.com>
    7.19 +
    7.20 +summary:     Third commit
    7.21 +

     8.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     8.2 +++ b/en/examples/branch-named.merge.out	Mon Apr 23 15:28:13 2007 -0700
     8.3 @@ -0,0 +1,16 @@
     8.4 +$ \textbf{hg branch}
     8.5 +bar
     8.6 +$ \textbf{hg merge}
     8.7 +1 files updated, 0 files merged, 0 files removed, 0 files unresolved
     8.8 +(branch merge, don't forget to commit)
     8.9 +$ \textbf{hg commit -m 'Merge'}
    8.10 +$ \textbf{hg tip}
    8.11 +changeset:   
    8.12 +branch:      bar
    8.13 +tag:         tip
    8.14 +parent:      
    8.15 +parent:      
    8.16 +user:        Bryan O'Sullivan <bos@serpentine.com>
    8.17 +
    8.18 +summary:     Merge
    8.19 +

     9.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     9.2 +++ b/en/examples/branch-named.parents.out	Mon Apr 23 15:28:13 2007 -0700
     9.3 @@ -0,0 +1,12 @@
     9.4 +$ \textbf{hg parents}
     9.5 +changeset:   
     9.6 +branch:      bar
     9.7 +tag:         tip
     9.8 +user:        Bryan O'Sullivan <bos@serpentine.com>
     9.9 +
    9.10 +summary:     Third commit
    9.11 +
    9.12 +$ \textbf{hg branches}
    9.13 +bar                            
    9.14 +foo                            
    9.15 +default                        

    10.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    10.2 +++ b/en/examples/branch-named.rebranch.out	Mon Apr 23 15:28:13 2007 -0700
    10.3 @@ -0,0 +1,14 @@
    10.4 +$ \textbf{hg branch}
    10.5 +foo
    10.6 +$ \textbf{hg branch bar}
    10.7 +$ \textbf{echo new file > newfile}
    10.8 +$ \textbf{hg commit -A -m 'Third commit'}
    10.9 +adding newfile
   10.10 +$ \textbf{hg tip}
   10.11 +changeset:   
   10.12 +branch:      bar
   10.13 +tag:         tip
   10.14 +user:        Bryan O'Sullivan <bos@serpentine.com>
   10.15 +
   10.16 +summary:     Third commit
   10.17 +

    11.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    11.2 +++ b/en/examples/branch-named.status.out	Mon Apr 23 15:28:13 2007 -0700
    11.3 @@ -0,0 +1,8 @@
    11.4 +$ \textbf{hg status}
    11.5 +$ \textbf{hg tip}
    11.6 +changeset:   
    11.7 +tag:         tip
    11.8 +user:        Bryan O'Sullivan <bos@serpentine.com>
    11.9 +
   11.10 +summary:     Initial commit
   11.11 +

    12.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    12.2 +++ b/en/examples/branch-named.update-bar.out	Mon Apr 23 15:28:13 2007 -0700
    12.3 @@ -0,0 +1,4 @@
    12.4 +$ \textbf{hg update bar}
    12.5 +abort: update spans branches, use 'hg merge' or 'hg update -C' to lose changes
    12.6 +$ \textbf{hg update -C bar}
    12.7 +1 files updated, 0 files merged, 1 files removed, 0 files unresolved

    13.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    13.2 +++ b/en/examples/branch-named.update-foo.out	Mon Apr 23 15:28:13 2007 -0700
    13.3 @@ -0,0 +1,13 @@
    13.4 +$ \textbf{hg update foo}
    13.5 +0 files updated, 0 files merged, 1 files removed, 0 files unresolved
    13.6 +$ \textbf{hg update}
    13.7 +0 files updated, 0 files merged, 0 files removed, 0 files unresolved
    13.8 +$ \textbf{hg parents}
    13.9 +changeset:   
   13.10 +branch:      foo
   13.11 +user:        Bryan O'Sullivan <bos@serpentine.com>
   13.12 +
   13.13 +summary:     Second commit
   13.14 +
   13.15 +$ \textbf{hg update bar}
   13.16 +1 files updated, 0 files merged, 0 files removed, 0 files unresolved

    14.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    14.2 +++ b/en/examples/branch-named.update-nothing.out	Mon Apr 23 15:28:13 2007 -0700
    14.3 @@ -0,0 +1,4 @@
    14.4 +$ \textbf{hg update foo}
    14.5 +0 files updated, 0 files merged, 1 files removed, 0 files unresolved
    14.6 +$ \textbf{hg update}
    14.7 +0 files updated, 0 files merged, 0 files removed, 0 files unresolved

    15.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    15.2 +++ b/en/examples/branch-named.update-switchy.out	Mon Apr 23 15:28:13 2007 -0700
    15.3 @@ -0,0 +1,19 @@
    15.4 +$ \textbf{hg update foo}
    15.5 +0 files updated, 0 files merged, 1 files removed, 0 files unresolved
    15.6 +$ \textbf{hg parents}
    15.7 +changeset:   
    15.8 +branch:      foo
    15.9 +user:        Bryan O'Sullivan <bos@serpentine.com>
   15.10 +
   15.11 +summary:     Second commit
   15.12 +
   15.13 +$ \textbf{hg update bar}
   15.14 +1 files updated, 0 files merged, 0 files removed, 0 files unresolved
   15.15 +$ \textbf{hg parents}
   15.16 +changeset:   
   15.17 +branch:      bar
   15.18 +tag:         tip
   15.19 +user:        Bryan O'Sullivan <bos@serpentine.com>
   15.20 +
   15.21 +summary:     Third commit
   15.22 +

    16.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    16.2 +++ b/en/examples/branch-named.update.out	Mon Apr 23 15:28:13 2007 -0700
    16.3 @@ -0,0 +1,13 @@
    16.4 +$ \textbf{hg update foo}
    16.5 +0 files updated, 0 files merged, 1 files removed, 0 files unresolved
    16.6 +$ \textbf{hg update}
    16.7 +0 files updated, 0 files merged, 0 files removed, 0 files unresolved
    16.8 +$ \textbf{hg parent}
    16.9 +changeset:   
   16.10 +branch:      foo
   16.11 +user:        Bryan O'Sullivan <bos@serpentine.com>
   16.12 +
   16.13 +summary:     Second commit
   16.14 +
   16.15 +$ \textbf{hg update bar}
   16.16 +1 files updated, 0 files merged, 0 files removed, 0 files unresolved