hgbook
changeset 206:6519f3b983b4
More material about named branches.
line diff
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