Mercurial > hgbook
annotate ja/branch.tex @ 301:828f5606faf0
started branch.tex
author | Yoshiki Yazawa <yaz@cc.rim.or.jp> |
---|---|
date | Fri, 08 Feb 2008 19:44:10 +0900 |
parents | 89db0aaf6a29 |
children | 6a31e428ba3b |
rev | line source |
---|---|
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
1 %\chapter{Managing releases and branchy development} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
2 \chapter{$B%j%j!<%9$H%V%i%s%A3+H/$N4IM}(B} |
187
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
3 \label{chap:branch} |
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
4 |
301 | 5 %Mercurial provides several mechanisms for you to manage a project that |
6 %is making progress on multiple fronts at once. To understand these | |
7 %mechanisms, let's first take a brief look at a fairly normal software | |
8 %project structure. | |
9 | |
10 Mercurial$B$OF1;~$KJ#?t$N6ILL$G?J9T$7$F$$$/%W%m%8%'%/%H$r4IM}$9$k$N$KLrN)(B | |
11 $B$D5!G=$r;}$C$F$$$k!%$3$l$i$N5!G=$rM}2r$9$k$?$a!$$^$:DL>o$N%=%U%H%&%'%"%W(B | |
12 $B%m%8%'%/%H$N9=B$$r9M$($k!%(B | |
187
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
13 |
301 | 14 %Many software projects issue periodic ``major'' releases that contain |
15 %substantial new features. In parallel, they may issue ``minor'' | |
16 %releases. These are usually identical to the major releases off which | |
17 %they're based, but with a few bugs fixed. | |
18 | |
19 $BB?$/$N%=%U%H%&%'%"%W%m%8%'%/%H$G$O!$?75!G=$r;}$D%a%8%c!<%j%j!<%9$rDj4|E*(B | |
20 $B$K%j%j!<%9$9$k!%JB9T$7$FB??t$N%^%$%J!<%j%j!<%9$b9T$J$o$l$k!%$3$l$i$O%a(B | |
21 $B%8%c!<%j%j!<%9$N%P%0$r=$@5$7$?$b$N$G$"$k!%(B | |
196
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
22 |
301 | 23 %In this chapter, we'll start by talking about how to keep records of |
24 %project milestones such as releases. We'll then continue on to talk | |
25 %about the flow of work between different phases of a project, and how | |
26 %Mercurial can help you to isolate and manage this work. | |
27 | |
28 $B$3$N>O$G$O$^$:%j%j!<%9$N$h$&$J%W%m%8%'%/%H$N%^%$%k%9%H!<%s$K8@5Z$9$k!%<!$$(B | |
29 $B$G%W%m%8%'%/%H$N3F%U%'!<%:$G$NN.$l$r@bL@$7!$(BMercurial$B$G$I$N$h$&$K6hJ,$1(B | |
30 $B$7!$4IM}$G$-$k$N$+$r@bL@$9$k!%(B | |
197 | 31 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
32 %\section{Giving a persistent name to a revision} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
33 \section{$B%j%S%8%g%s$K1JB3E*$JL>A0$rIU$1$k(B} |
196
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
34 |
301 | 35 %Once you decide that you'd like to call a particular revision a |
36 %``release'', it's a good idea to record the identity of that revision. | |
37 %This will let you reproduce that release at a later date, for whatever | |
38 %purpose you might need at the time (reproducing a bug, porting to a | |
39 %new platform, etc). | |
40 %\interaction{tag.init} | |
41 | |
42 $B$"$k%j%S%8%g%s$r%j%j!<%9$H7h$a$?;~$K!$$3$l$r5-O?$7$F$*$/$N$ONI$$9M$($G$"(B | |
43 $B$k!%$3$l$O8eF|!$%P%0$N:F8=$d%=%U%H%&%'%"$N0\?"$J$I$NL\E*$G%j%j!<%9$r:F8=(B | |
44 $B$9$k$N$KLrN)$D!%(B | |
196
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
45 \interaction{tag.init} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
46 |
301 | 47 %Mercurial lets you give a permanent name to any revision using the |
48 %\hgcmd{tag} command. Not surprisingly, these names are called | |
49 %``tags''. | |
50 %\interaction{tag.tag} | |
51 | |
52 $BFCDj$N%j%S%8%g%s$K(BMercurial$B$G1JB3E*$JL>A0$rIU$1$k$3$H$,$G$-$k!%$3$NL>A0(B | |
53 $B$O%?%0$H8F$P$l$k!%(B | |
196
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
54 \interaction{tag.tag} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
55 |
301 | 56 %A tag is nothing more than a ``symbolic name'' for a revision. Tags |
57 %exist purely for your convenience, so that you have a handy permanent | |
58 %way to refer to a revision; Mercurial doesn't interpret the tag names | |
59 %you use in any way. | |
60 %Neither does Mercurial place any restrictions on | |
61 %the name of a tag, beyond a few that are necessary to ensure that a | |
62 %tag can be parsed unambiguously. A tag name cannot contain any of the | |
63 %following characters: | |
64 %\begin{itemize} | |
65 %\item Colon (ASCII 58, ``\texttt{:}'') | |
66 %\item Carriage return (ASCII 13, ``\Verb+\r+'') | |
67 %\item Newline (ASCII 10, ``\Verb+\n+'') | |
68 %\end{itemize} | |
69 | |
70 $B%?%0$O<B$N$H$3$m%j%S%8%g%s$KIU$1$i$l$?%7%s%\%j%C%/%M!<%`$KB>$J$i$J$$!%%?(B | |
71 $B%0$OC1$K%f!<%6$NJX59$N$?$a$KIU$1$i$l$k!%%?%0$OFCDj$N%j%S%8%g%s$r;2>H$9$k(B | |
72 $B$?$a$N<j7Z$G1JB3E*$JJ}K!$G!$(BMercurial$B$O%?%0$rK]Lu$7$J$$!%%?%0$NL>A0$K$O!$(B | |
73 $BL@3N$K%Q!<%9$9$k$?$a$N$$$/$D$+$N$b$N0J30$N@)8B$O$J$$!%%?%0%M!<%`$O0J2<$N(B | |
74 $BJ8;z$r4^$`$3$H$O$G$-$J$$!%(B | |
196
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
75 \begin{itemize} |
301 | 76 \item $B%3%m%s(B (ASCII 58, ``\texttt{:}'') |
77 \item $BI|5"J8;z(B (ASCII 13, ``\Verb+\r+'') | |
78 \item $B2~9TJ8;z(B (ASCII 10, ``\Verb+\n+'') | |
196
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
79 \end{itemize} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
80 |
301 | 81 |
82 %You can use the \hgcmd{tags} command to display the tags present in | |
83 %your repository. In the output, each tagged revision is identified | |
84 %first by its name, then by revision number, and finally by the unique | |
85 %hash of the revision. | |
86 %\interaction{tag.tags} | |
87 %Notice that \texttt{tip} is listed in the output of \hgcmd{tags}. The | |
88 %\texttt{tip} tag is a special ``floating'' tag, which always | |
89 %identifies the newest revision in the repository. | |
90 | |
91 \hgcmd{tags}$B%3%^%s%I$G%j%]%8%H%j$KB8:_$9$k%?%0$rI=<($9$k$3$H$,$G$-$k!%=P(B | |
92 $BNO$G$O!$%?%0IU$1$5$l$?%j%S%8%g%s$OL>A0!$%j%S%8%g%sHV9f!$8GM-$N%O%C%7%eCM(B | |
93 $B$N=g$K6hJL$5$l$k!%(B | |
196
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
94 \interaction{tag.tags} |
301 | 95 \hgcmd{tags}$B$N=PNO$K(B\texttt{tip}$B$,4^$^$l$F$$$k$3$H$KCm0U!%(B\texttt{tip}$B%?(B |
96 $B%0$O!$%j%]%8%H%j$NCf$G>o$K:G?7$N%j%S%8%g%s$KIU$1$i$l$F$$$kFCJL$J%U%m!<%F%#(B | |
97 $B%s%0%?%0$G$"$k!%(B | |
98 | |
99 %In the output of the \hgcmd{tags} command, tags are listed in reverse | |
100 %order, by revision number. This usually means that recent tags are | |
101 %listed before older tags. It also means that \texttt{tip} is always | |
102 %going to be the first tag listed in the output of \hgcmd{tags}. | |
196
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
103 |
301 | 104 \hgcmd{tags}$B%3%^%s%I$N=PNO$K$*$$$F!$%?%0$O%j%S%8%g%sHV9f$K$h$C$F5U=g$GI=(B |
105 $B<($5$l$F$$$k!%$3$l$K$h$C$F!$DL>o!$?7$7$$%?%0$,8E$$%?%0$h$j$bA0$KI=<($5$l(B | |
106 $B$k!%(B\texttt{tip}$B%?%0$O(B\hgcmd{tags}$B%3%^%s%I$N=PNO$N0lHV@hF,$KI=<($5$l$k!%(B | |
196
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
107 |
301 | 108 %When you run \hgcmd{log}, if it displays a revision that has tags |
109 %associated with it, it will print those tags. | |
110 %\interaction{tag.log} | |
111 | |
112 \hgcmd{log}$B%3%^%s%I$O%?%0$N7k$S$D$1$i$l$?%j%S%8%g%s$rI=<($9$k:]$K%?%0$b(B | |
113 $BI=<($9$k!%(B | |
196
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
114 \interaction{tag.log} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
115 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
116 Any time you need to provide a revision~ID to a Mercurial command, the |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
117 command will accept a tag name in its place. Internally, Mercurial |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
118 will translate your tag name into the corresponding revision~ID, then |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
119 use that. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
120 \interaction{tag.log.v1.0} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
121 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
122 There's no limit on the number of tags you can have in a repository, |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
123 or on the number of tags that a single revision can have. As a |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
124 practical matter, it's not a great idea to have ``too many'' (a number |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
125 which will vary from project to project), simply because tags are |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
126 supposed to help you to find revisions. If you have lots of tags, the |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
127 ease of using them to identify revisions diminishes rapidly. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
128 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
129 For example, if your project has milestones as frequent as every few |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
130 days, it's perfectly reasonable to tag each one of those. But if you |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
131 have a continuous build system that makes sure every revision can be |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
132 built cleanly, you'd be introducing a lot of noise if you were to tag |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
133 every clean build. Instead, you could tag failed builds (on the |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
134 assumption that they're rare!), or simply not use tags to track |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
135 buildability. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
136 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
137 If you want to remove a tag that you no longer want, use |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
138 \hgcmdargs{tag}{--remove}. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
139 \interaction{tag.remove} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
140 You can also modify a tag at any time, so that it identifies a |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
141 different revision, by simply issuing a new \hgcmd{tag} command. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
142 You'll have to use the \hgopt{tag}{-f} option to tell Mercurial that |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
143 you \emph{really} want to update the tag. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
144 \interaction{tag.replace} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
145 There will still be a permanent record of the previous identity of the |
197 | 146 tag, but Mercurial will no longer use it. There's thus no penalty to |
147 tagging the wrong revision; all you have to do is turn around and tag | |
148 the correct revision once you discover your error. | |
196
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
149 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
150 Mercurial stores tags in a normal revision-controlled file in your |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
151 repository. If you've created any tags, you'll find them in a file |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
152 named \sfilename{.hgtags}. When you run the \hgcmd{tag} command, |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
153 Mercurial modifies this file, then automatically commits the change to |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
154 it. This means that every time you run \hgcmd{tag}, you'll see a |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
155 corresponding changeset in the output of \hgcmd{log}. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
156 \interaction{tag.tip} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
157 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
158 %\subsection{Handling tag conflicts during a merge} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
159 \subsection{$B%^!<%8$N:]$K%?%0$N%3%s%U%j%/%H$r2r7h$9$k(B} |
196
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
160 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
161 You won't often need to care about the \sfilename{.hgtags} file, but |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
162 it sometimes makes its presence known during a merge. The format of |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
163 the file is simple: it consists of a series of lines. Each line |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
164 starts with a changeset hash, followed by a space, followed by the |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
165 name of a tag. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
166 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
167 If you're resolving a conflict in the \sfilename{.hgtags} file during |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
168 a merge, there's one twist to modifying the \sfilename{.hgtags} file: |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
169 when Mercurial is parsing the tags in a repository, it \emph{never} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
170 reads the working copy of the \sfilename{.hgtags} file. Instead, it |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
171 reads the \emph{most recently committed} revision of the file. |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
172 |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
173 An unfortunate consequence of this design is that you can't actually |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
174 verify that your merged \sfilename{.hgtags} file is correct until |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
175 \emph{after} you've committed a change. So if you find yourself |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
176 resolving a conflict on \sfilename{.hgtags} during a merge, be sure to |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
177 run \hgcmd{tags} after you commit. If it finds an error in the |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
178 \sfilename{.hgtags} file, it will report the location of the error, |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
179 which you can then fix and commit. You should then run \hgcmd{tags} |
4237e45506ee
Add early material describing tags.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
180 again, just to be sure that your fix is correct. |
187
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
181 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
182 %\subsection{Tags and cloning} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
183 \subsection{$B%?%0$H%/%m!<%s(B} |
198
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
184 |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
185 You may have noticed that the \hgcmd{clone} command has a |
259 | 186 \hgopt{clone}{-r} option that lets you clone an exact copy of the |
198
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
187 repository as of a particular changeset. The new clone will not |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
188 contain any project history that comes after the revision you |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
189 specified. This has an interaction with tags that can surprise the |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
190 unwary. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
191 |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
192 Recall that a tag is stored as a revision to the \sfilename{.hgtags} |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
193 file, so that when you create a tag, the changeset in which it's |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
194 recorded necessarily refers to an older changeset. When you run |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
195 \hgcmdargs{clone}{-r foo} to clone a repository as of tag |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
196 \texttt{foo}, the new clone \emph{will not contain the history that |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
197 created the tag} that you used to clone the repository. The result |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
198 is that you'll get exactly the right subset of the project's history |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
199 in the new repository, but \emph{not} the tag you might have expected. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
200 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
201 %\subsection{When permanent tags are too much} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
202 \subsection{$B1J5W%?%0$,I,MW$G$J$$>l9g(B} |
197 | 203 |
204 Since Mercurial's tags are revision controlled and carried around with | |
205 a project's history, everyone you work with will see the tags you | |
206 create. But giving names to revisions has uses beyond simply noting | |
207 that revision \texttt{4237e45506ee} is really \texttt{v2.0.2}. If | |
208 you're trying to track down a subtle bug, you might want a tag to | |
209 remind you of something like ``Anne saw the symptoms with this | |
210 revision''. | |
211 | |
212 For cases like this, what you might want to use are \emph{local} tags. | |
213 You can create a local tag with the \hgopt{tag}{-l} option to the | |
214 \hgcmd{tag} command. This will store the tag in a file called | |
215 \sfilename{.hg/localtags}. Unlike \sfilename{.hgtags}, | |
216 \sfilename{.hg/localtags} is not revision controlled. Any tags you | |
217 create using \hgopt{tag}{-l} remain strictly local to the repository | |
218 you're currently working in. | |
219 | |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
220 %\section{The flow of changes---big picture vs. little} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
221 \section{$B99?7$NN.$l(B---$BBg6IE*(B vs.$B6I=jE*(B} |
198
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
222 |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
223 To return to the outline I sketched at the beginning of a chapter, |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
224 let's think about a project that has multiple concurrent pieces of |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
225 work under development at once. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
226 |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
227 There might be a push for a new ``main'' release; a new minor bugfix |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
228 release to the last main release; and an unexpected ``hot fix'' to an |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
229 old release that is now in maintenance mode. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
230 |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
231 The usual way people refer to these different concurrent directions of |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
232 development is as ``branches''. However, we've already seen numerous |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
233 times that Mercurial treats \emph{all of history} as a series of |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
234 branches and merges. Really, what we have here is two ideas that are |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
235 peripherally related, but which happen to share a name. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
236 \begin{itemize} |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
237 \item ``Big picture'' branches represent the sweep of a project's |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
238 evolution; people give them names, and talk about them in |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
239 conversation. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
240 \item ``Little picture'' branches are artefacts of the day-to-day |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
241 activity of developing and merging changes. They expose the |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
242 narrative of how the code was developed. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
243 \end{itemize} |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
244 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
245 %\section{Managing big-picture branches in repositories} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
246 \section{$B%j%]%8%H%j4V$G$NBg6IE*%V%i%s%A$N4IM}(B} |
198
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
247 |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
248 The easiest way to isolate a ``big picture'' branch in Mercurial is in |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
249 a dedicated repository. If you have an existing shared |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
250 repository---let's call it \texttt{myproject}---that reaches a ``1.0'' |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
251 milestone, you can start to prepare for future maintenance releases on |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
252 top of version~1.0 by tagging the revision from which you prepared |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
253 the~1.0 release. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
254 \interaction{branch-repo.tag} |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
255 You can then clone a new shared \texttt{myproject-1.0.1} repository as |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
256 of that tag. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
257 \interaction{branch-repo.clone} |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
258 |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
259 Afterwards, if someone needs to work on a bug fix that ought to go |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
260 into an upcoming~1.0.1 minor release, they clone the |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
261 \texttt{myproject-1.0.1} repository, make their changes, and push them |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
262 back. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
263 \interaction{branch-repo.bugfix} |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
264 Meanwhile, development for the next major release can continue, |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
265 isolated and unabated, in the \texttt{myproject} repository. |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
266 \interaction{branch-repo.new} |
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
267 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
268 %\section{Don't repeat yourself: merging across branches} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
269 \section{$B<+F02=$5$l$?%V%i%s%A4V$G$N%^!<%8(B} |
198
615f3c6b30e1
Start to describe branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
197
diff
changeset
|
270 |
199
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
271 In many cases, if you have a bug to fix on a maintenance branch, the |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
272 chances are good that the bug exists on your project's main branch |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
273 (and possibly other maintenance branches, too). It's a rare developer |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
274 who wants to fix the same bug multiple times, so let's look at a few |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
275 ways that Mercurial can help you to manage these bugfixes without |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
276 duplicating your work. |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
277 |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
278 In the simplest instance, all you need to do is pull changes from your |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
279 maintenance branch into your local clone of the target branch. |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
280 \interaction{branch-repo.pull} |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
281 You'll then need to merge the heads of the two branches, and push back |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
282 to the main branch. |
58e3a6c76725
More branch/merge stuff.
Bryan O'Sullivan <bos@serpentine.com>
parents:
198
diff
changeset
|
283 \interaction{branch-repo.merge} |
197 | 284 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
285 %\section{Naming branches within one repository} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
286 \section{1$B$D$N%j%]%8%H%jFb$G$N%V%i%s%A$NL?L>(B} |
202
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
287 |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
288 In most instances, isolating branches in repositories is the right |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
289 approach. Its simplicity makes it easy to understand; and so it's |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
290 hard to make mistakes. There's a one-to-one relationship between |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
291 branches you're working in and directories on your system. This lets |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
292 you use normal (non-Mercurial-aware) tools to work on files within a |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
293 branch/repository. |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
294 |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
295 If you're more in the ``power user'' category (\emph{and} your |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
296 collaborators are too), there is an alternative way of handling |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
297 branches that you can consider. I've already mentioned the |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
298 human-level distinction between ``small picture'' and ``big picture'' |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
299 branches. While Mercurial works with multiple ``small picture'' |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
300 branches in a repository all the time (for example after you pull |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
301 changes in, but before you merge them), it can \emph{also} work with |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
302 multiple ``big picture'' branches. |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
303 |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
304 The key to working this way is that Mercurial lets you assign a |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
305 persistent \emph{name} to a branch. There always exists a branch |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
306 named \texttt{default}. Even before you start naming branches |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
307 yourself, you can find traces of the \texttt{default} branch if you |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
308 look for them. |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
309 |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
310 As an example, when you run the \hgcmd{commit} command, and it pops up |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
311 your editor so that you can enter a commit message, look for a line |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
312 that contains the text ``\texttt{HG: branch default}'' at the bottom. |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
313 This is telling you that your commit will occur on the branch named |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
314 \texttt{default}. |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
315 |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
316 To start working with named branches, use the \hgcmd{branches} |
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
317 command. This command lists the named branches already present in |
203
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
318 your repository, telling you which changeset is the tip of each. |
202
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
319 \interaction{branch-named.branches} |
203
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
320 Since you haven't created any named branches yet, the only one that |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
321 exists is \texttt{default}. |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
322 |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
323 To find out what the ``current'' branch is, run the \hgcmd{branch} |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
324 command, giving it no arguments. This tells you what branch the |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
325 parent of the current changeset is on. |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
326 \interaction{branch-named.branch} |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
327 |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
328 To create a new branch, run the \hgcmd{branch} command again. This |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
329 time, give it one argument: the name of the branch you want to create. |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
330 \interaction{branch-named.create} |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
331 |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
332 After you've created a branch, you might wonder what effect the |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
333 \hgcmd{branch} command has had. What do the \hgcmd{status} and |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
334 \hgcmd{tip} commands report? |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
335 \interaction{branch-named.status} |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
336 Nothing has changed in the working directory, and there's been no new |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
337 history created. As this suggests, running the \hgcmd{branch} command |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
338 has no permanent effect; it only tells Mercurial what branch name to |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
339 use the \emph{next} time you commit a changeset. |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
340 |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
341 When you commit a change, Mercurial records the name of the branch on |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
342 which you committed. Once you've switched from the \texttt{default} |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
343 branch to another and committed, you'll see the name of the new branch |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
344 show up in the output of \hgcmd{log}, \hgcmd{tip}, and other commands |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
345 that display the same kind of output. |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
346 \interaction{branch-named.commit} |
d7615e15510f
More about named branches, and early use of them.
Bryan O'Sullivan <bos@serpentine.com>
parents:
202
diff
changeset
|
347 The \hgcmd{log}-like commands will print the branch name of every |
205 | 348 changeset that's not on the \texttt{default} branch. As a result, if |
349 you never use named branches, you'll never see this information. | |
350 | |
351 Once you've named a branch and committed a change with that name, | |
352 every subsequent commit that descends from that change will inherit | |
206
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
353 the same branch name. You can change the name of a branch at any |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
354 time, using the \hgcmd{branch} command. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
355 \interaction{branch-named.rebranch} |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
356 In practice, this is something you won't do very often, as branch |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
357 names tend to have fairly long lifetimes. (This isn't a rule, just an |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
358 observation.) |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
359 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
360 %\section{Dealing with multiple named branches in a repository} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
361 \section{$B%j%]%8%H%jFb$GJ#?t$NL>A0$NIU$$$?%V%i%s%A$N<h$j07$$(B} |
206
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
362 |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
363 If you have more than one named branch in a repository, Mercurial will |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
364 remember the branch that your working directory on when you start a |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
365 command like \hgcmd{update} or \hgcmdargs{pull}{-u}. It will update |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
366 the working directory to the tip of this branch, no matter what the |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
367 ``repo-wide'' tip is. To update to a revision that's on a different |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
368 named branch, you may need to use the \hgopt{update}{-C} option to |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
369 \hgcmd{update}. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
370 |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
371 This behaviour is a little subtle, so let's see it in action. First, |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
372 let's remind ourselves what branch we're currently on, and what |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
373 branches are in our repository. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
374 \interaction{branch-named.parents} |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
375 We're on the \texttt{bar} branch, but there also exists an older |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
376 \hgcmd{foo} branch. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
377 |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
378 We can \hgcmd{update} back and forth between the tips of the |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
379 \texttt{foo} and \texttt{bar} branches without needing to use the |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
380 \hgopt{update}{-C} option, because this only involves going backwards |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
381 and forwards linearly through our change history. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
382 \interaction{branch-named.update-switchy} |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
383 |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
384 If we go back to the \texttt{foo} branch and then run \hgcmd{update}, |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
385 it will keep us on \texttt{foo}, not move us to the tip of |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
386 \texttt{bar}. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
387 \interaction{branch-named.update-nothing} |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
388 |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
389 Committing a new change on the \texttt{foo} branch introduces a new |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
390 head. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
391 \interaction{branch-named.foo-commit} |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
392 We can no longer update from \texttt{foo} to \texttt{bar} without |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
393 going ``sideways'' in history, so Mercurial forces us to provide the |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
394 \hgopt{update}{-C} option to \hgcmd{update}. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
395 \interaction{branch-named.update-bar} |
205 | 396 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
397 %\section{Branch names and merging} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
398 \section{$B%V%i%s%AL>$H%^!<%8(B} |
205 | 399 |
400 As you've probably noticed, merges in Mercurial are not symmetrical. | |
401 Let's say our repository has two heads, 17 and 23. If I | |
402 \hgcmd{update} to 17 and then \hgcmd{merge} with 23, Mercurial records | |
403 17 as the first parent of the merge, and 23 as the second. Whereas if | |
404 I \hgcmd{update} to 23 and then \hgcmd{merge} with 17, it records 23 | |
405 as the first parent, and 17 as the second. | |
406 | |
206
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
407 This affects Mercurial's choice of branch name when you merge. After |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
408 a merge, Mercurial will retain the branch name of the first parent |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
409 when you commit the result of the merge. If your first parent's |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
410 branch name is \texttt{foo}, and you merge with \texttt{bar}, the |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
411 branch name will still be \texttt{foo} after you merge. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
412 |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
413 It's not unusual for a repository to contain multiple heads, each with |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
414 the same branch name. Let's say I'm working on the \texttt{foo} |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
415 branch, and so are you. We commit different changes; I pull your |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
416 changes; I now have two heads, each claiming to be on the \texttt{foo} |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
417 branch. The result of a merge will be a single head on the |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
418 \texttt{foo} branch, as you might hope. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
419 |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
420 But if I'm working on the \texttt{bar} branch, and I merge work from |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
421 the \texttt{foo} branch, the result will remain on the \texttt{bar} |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
422 branch. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
423 \interaction{branch-named.merge} |
205 | 424 |
206
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
425 To give a more concrete example, if I'm working on the |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
426 \texttt{bleeding-edge} branch, and I want to bring in the latest fixes |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
427 from the \texttt{stable} branch, Mercurial will choose the ``right'' |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
428 (\texttt{bleeding-edge}) branch name when I pull and merge from |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
429 \texttt{stable}. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
430 |
296
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
431 %\section{Branch naming is generally useful} |
89db0aaf6a29
translated chapter & section name within branch.tex.
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
293
diff
changeset
|
432 \section{$B%V%i%s%A$KL>A0$rIU$1$k$3$H$OLr$KN)$D(B} |
206
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
433 |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
434 You shouldn't think of named branches as applicable only to situations |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
435 where you have multiple long-lived branches cohabiting in a single |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
436 repository. They're very useful even in the one-branch-per-repository |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
437 case. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
438 |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
439 In the simplest case, giving a name to each branch gives you a |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
440 permanent record of which branch a changeset originated on. This |
266 | 441 gives you more context when you're trying to follow the history of a |
206
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
442 long-lived branchy project. |
6519f3b983b4
More material about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
205
diff
changeset
|
443 |
207
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
444 If you're working with shared repositories, you can set up a |
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
445 \hook{pretxnchangegroup} hook on each that will block incoming changes |
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
446 that have the ``wrong'' branch name. This provides a simple, but |
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
447 effective, defence against people accidentally pushing changes from a |
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
448 ``bleeding edge'' branch to a ``stable'' branch. Such a hook might |
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
449 look like this inside the shared repo's \hgrc. |
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
450 \begin{codesample2} |
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
451 [hooks] |
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
452 pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch |
54ca4e00e569
Add an example hook to enforce branch naming.
Bryan O'Sullivan <bos@serpentine.com>
parents:
206
diff
changeset
|
453 \end{codesample2} |
202
6f167e644762
Start writing about named branches.
Bryan O'Sullivan <bos@serpentine.com>
parents:
199
diff
changeset
|
454 |
187
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
455 %%% Local Variables: |
293
3b1291f24c0d
- replaved latex-mode to yatex-mode
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
290
diff
changeset
|
456 %%% mode: yatex |
187
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
457 %%% TeX-master: "00book" |
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
458 %%% End: |