| rev |
line source |
|
bos@559
|
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
|
|
bos@559
|
2
|
|
dongsheng@625
|
3 <chapter id="chap.branch">
|
|
bos@572
|
4 <?dbhtml filename="managing-releases-and-branchy-development.html"?>
|
|
bos@559
|
5 <title>Managing releases and branchy development</title>
|
|
bos@559
|
6
|
|
bos@559
|
7 <para>Mercurial provides several mechanisms for you to manage a
|
|
bos@559
|
8 project that is making progress on multiple fronts at once. To
|
|
bos@559
|
9 understand these mechanisms, let's first take a brief look at a
|
|
bos@559
|
10 fairly normal software project structure.</para>
|
|
bos@559
|
11
|
|
bos@559
|
12 <para>Many software projects issue periodic <quote>major</quote>
|
|
bos@559
|
13 releases that contain substantial new features. In parallel, they
|
|
bos@559
|
14 may issue <quote>minor</quote> releases. These are usually
|
|
bos@559
|
15 identical to the major releases off which they're based, but with
|
|
bos@559
|
16 a few bugs fixed.</para>
|
|
bos@559
|
17
|
|
bos@559
|
18 <para>In this chapter, we'll start by talking about how to keep
|
|
bos@559
|
19 records of project milestones such as releases. We'll then
|
|
bos@559
|
20 continue on to talk about the flow of work between different
|
|
bos@559
|
21 phases of a project, and how Mercurial can help you to isolate and
|
|
bos@559
|
22 manage this work.</para>
|
|
bos@559
|
23
|
|
bos@559
|
24 <sect1>
|
|
bos@559
|
25 <title>Giving a persistent name to a revision</title>
|
|
bos@559
|
26
|
|
bos@559
|
27 <para>Once you decide that you'd like to call a particular
|
|
bos@559
|
28 revision a <quote>release</quote>, it's a good idea to record
|
|
bos@559
|
29 the identity of that revision. This will let you reproduce that
|
|
bos@559
|
30 release at a later date, for whatever purpose you might need at
|
|
bos@559
|
31 the time (reproducing a bug, porting to a new platform, etc).
|
|
bos@567
|
32 &interaction.tag.init;</para>
|
|
bos@559
|
33
|
|
bos@559
|
34 <para>Mercurial lets you give a permanent name to any revision
|
|
bos@559
|
35 using the <command role="hg-cmd">hg tag</command> command. Not
|
|
bos@567
|
36 surprisingly, these names are called <quote>tags</quote>.</para>
|
|
bos@567
|
37
|
|
bos@567
|
38 &interaction.tag.tag;
|
|
bos@559
|
39
|
|
bos@559
|
40 <para>A tag is nothing more than a <quote>symbolic name</quote>
|
|
bos@559
|
41 for a revision. Tags exist purely for your convenience, so that
|
|
bos@559
|
42 you have a handy permanent way to refer to a revision; Mercurial
|
|
bos@559
|
43 doesn't interpret the tag names you use in any way. Neither
|
|
bos@559
|
44 does Mercurial place any restrictions on the name of a tag,
|
|
bos@559
|
45 beyond a few that are necessary to ensure that a tag can be
|
|
bos@559
|
46 parsed unambiguously. A tag name cannot contain any of the
|
|
bos@559
|
47 following characters:</para>
|
|
bos@559
|
48 <itemizedlist>
|
|
bos@559
|
49 <listitem><para>Colon (ASCII 58,
|
|
bos@559
|
50 <quote><literal>:</literal></quote>)</para>
|
|
bos@559
|
51 </listitem>
|
|
bos@559
|
52 <listitem><para>Carriage return (ASCII 13,
|
|
bos@559
|
53 <quote><literal>\r</literal></quote>)</para>
|
|
bos@559
|
54 </listitem>
|
|
bos@559
|
55 <listitem><para>Newline (ASCII 10,
|
|
bos@559
|
56 <quote><literal>\n</literal></quote>)</para>
|
|
bos@559
|
57 </listitem></itemizedlist>
|
|
bos@559
|
58
|
|
bos@559
|
59 <para>You can use the <command role="hg-cmd">hg tags</command>
|
|
bos@559
|
60 command to display the tags present in your repository. In the
|
|
bos@559
|
61 output, each tagged revision is identified first by its name,
|
|
bos@559
|
62 then by revision number, and finally by the unique hash of the
|
|
bos@567
|
63 revision.</para>
|
|
bos@567
|
64
|
|
bos@567
|
65 &interaction.tag.tags;
|
|
bos@567
|
66
|
|
bos@567
|
67 <para>Notice that <literal>tip</literal> is listed in the output
|
|
bos@567
|
68 of <command role="hg-cmd">hg tags</command>. The
|
|
bos@567
|
69 <literal>tip</literal> tag is a special <quote>floating</quote>
|
|
bos@567
|
70 tag, which always identifies the newest revision in the
|
|
bos@567
|
71 repository.</para>
|
|
bos@559
|
72
|
|
bos@559
|
73 <para>In the output of the <command role="hg-cmd">hg
|
|
bos@559
|
74 tags</command> command, tags are listed in reverse order, by
|
|
bos@559
|
75 revision number. This usually means that recent tags are listed
|
|
bos@559
|
76 before older tags. It also means that <literal>tip</literal> is
|
|
bos@559
|
77 always going to be the first tag listed in the output of
|
|
bos@559
|
78 <command role="hg-cmd">hg tags</command>.</para>
|
|
bos@559
|
79
|
|
bos@559
|
80 <para>When you run <command role="hg-cmd">hg log</command>, if it
|
|
bos@559
|
81 displays a revision that has tags associated with it, it will
|
|
bos@567
|
82 print those tags.</para>
|
|
bos@567
|
83
|
|
bos@567
|
84 &interaction.tag.log;
|
|
bos@559
|
85
|
|
bos@559
|
86 <para>Any time you need to provide a revision ID to a Mercurial
|
|
bos@559
|
87 command, the command will accept a tag name in its place.
|
|
bos@559
|
88 Internally, Mercurial will translate your tag name into the
|
|
bos@567
|
89 corresponding revision ID, then use that.</para>
|
|
bos@567
|
90
|
|
bos@567
|
91 &interaction.tag.log.v1.0;
|
|
bos@559
|
92
|
|
bos@559
|
93 <para>There's no limit on the number of tags you can have in a
|
|
bos@559
|
94 repository, or on the number of tags that a single revision can
|
|
bos@559
|
95 have. As a practical matter, it's not a great idea to have
|
|
bos@559
|
96 <quote>too many</quote> (a number which will vary from project
|
|
bos@559
|
97 to project), simply because tags are supposed to help you to
|
|
bos@559
|
98 find revisions. If you have lots of tags, the ease of using
|
|
bos@559
|
99 them to identify revisions diminishes rapidly.</para>
|
|
bos@559
|
100
|
|
bos@559
|
101 <para>For example, if your project has milestones as frequent as
|
|
bos@559
|
102 every few days, it's perfectly reasonable to tag each one of
|
|
bos@559
|
103 those. But if you have a continuous build system that makes
|
|
bos@559
|
104 sure every revision can be built cleanly, you'd be introducing a
|
|
bos@559
|
105 lot of noise if you were to tag every clean build. Instead, you
|
|
bos@559
|
106 could tag failed builds (on the assumption that they're rare!),
|
|
bos@559
|
107 or simply not use tags to track buildability.</para>
|
|
bos@559
|
108
|
|
bos@559
|
109 <para>If you want to remove a tag that you no longer want, use
|
|
bos@567
|
110 <command role="hg-cmd">hg tag --remove</command>.</para>
|
|
bos@567
|
111
|
|
bos@567
|
112 &interaction.tag.remove;
|
|
bos@567
|
113
|
|
bos@567
|
114 <para>You can also modify a tag at any time, so that it identifies
|
|
bos@567
|
115 a different revision, by simply issuing a new <command
|
|
bos@567
|
116 role="hg-cmd">hg tag</command> command. You'll have to use the
|
|
bos@567
|
117 <option role="hg-opt-tag">-f</option> option to tell Mercurial
|
|
bos@567
|
118 that you <emphasis>really</emphasis> want to update the
|
|
bos@567
|
119 tag.</para>
|
|
bos@567
|
120
|
|
bos@567
|
121 &interaction.tag.replace;
|
|
bos@567
|
122
|
|
bos@567
|
123 <para>There will still be a permanent record of the previous
|
|
bos@567
|
124 identity of the tag, but Mercurial will no longer use it.
|
|
bos@567
|
125 There's thus no penalty to tagging the wrong revision; all you
|
|
bos@567
|
126 have to do is turn around and tag the correct revision once you
|
|
bos@567
|
127 discover your error.</para>
|
|
bos@559
|
128
|
|
bos@559
|
129 <para>Mercurial stores tags in a normal revision-controlled file
|
|
bos@559
|
130 in your repository. If you've created any tags, you'll find
|
|
bos@559
|
131 them in a file named <filename
|
|
bos@559
|
132 role="special">.hgtags</filename>. When you run the <command
|
|
bos@559
|
133 role="hg-cmd">hg tag</command> command, Mercurial modifies
|
|
bos@559
|
134 this file, then automatically commits the change to it. This
|
|
bos@559
|
135 means that every time you run <command role="hg-cmd">hg
|
|
bos@559
|
136 tag</command>, you'll see a corresponding changeset in the
|
|
bos@567
|
137 output of <command role="hg-cmd">hg log</command>.</para>
|
|
bos@567
|
138
|
|
bos@567
|
139 &interaction.tag.tip;
|
|
bos@559
|
140
|
|
bos@559
|
141 <sect2>
|
|
bos@559
|
142 <title>Handling tag conflicts during a merge</title>
|
|
bos@559
|
143
|
|
bos@559
|
144 <para>You won't often need to care about the <filename
|
|
bos@559
|
145 role="special">.hgtags</filename> file, but it sometimes
|
|
bos@559
|
146 makes its presence known during a merge. The format of the
|
|
bos@559
|
147 file is simple: it consists of a series of lines. Each line
|
|
bos@559
|
148 starts with a changeset hash, followed by a space, followed by
|
|
bos@559
|
149 the name of a tag.</para>
|
|
bos@559
|
150
|
|
bos@559
|
151 <para>If you're resolving a conflict in the <filename
|
|
bos@559
|
152 role="special">.hgtags</filename> file during a merge,
|
|
bos@559
|
153 there's one twist to modifying the <filename
|
|
bos@559
|
154 role="special">.hgtags</filename> file: when Mercurial is
|
|
bos@559
|
155 parsing the tags in a repository, it
|
|
bos@559
|
156 <emphasis>never</emphasis> reads the working copy of the
|
|
bos@559
|
157 <filename role="special">.hgtags</filename> file. Instead, it
|
|
bos@559
|
158 reads the <emphasis>most recently committed</emphasis>
|
|
bos@559
|
159 revision of the file.</para>
|
|
bos@559
|
160
|
|
bos@559
|
161 <para>An unfortunate consequence of this design is that you
|
|
bos@559
|
162 can't actually verify that your merged <filename
|
|
bos@559
|
163 role="special">.hgtags</filename> file is correct until
|
|
bos@559
|
164 <emphasis>after</emphasis> you've committed a change. So if
|
|
bos@559
|
165 you find yourself resolving a conflict on <filename
|
|
bos@559
|
166 role="special">.hgtags</filename> during a merge, be sure to
|
|
bos@559
|
167 run <command role="hg-cmd">hg tags</command> after you commit.
|
|
bos@559
|
168 If it finds an error in the <filename
|
|
bos@559
|
169 role="special">.hgtags</filename> file, it will report the
|
|
bos@559
|
170 location of the error, which you can then fix and commit. You
|
|
bos@559
|
171 should then run <command role="hg-cmd">hg tags</command>
|
|
bos@559
|
172 again, just to be sure that your fix is correct.</para>
|
|
bos@559
|
173
|
|
bos@559
|
174 </sect2>
|
|
bos@559
|
175 <sect2>
|
|
bos@559
|
176 <title>Tags and cloning</title>
|
|
bos@559
|
177
|
|
bos@559
|
178 <para>You may have noticed that the <command role="hg-cmd">hg
|
|
bos@559
|
179 clone</command> command has a <option
|
|
bos@559
|
180 role="hg-opt-clone">-r</option> option that lets you clone
|
|
bos@559
|
181 an exact copy of the repository as of a particular changeset.
|
|
bos@559
|
182 The new clone will not contain any project history that comes
|
|
bos@559
|
183 after the revision you specified. This has an interaction
|
|
bos@559
|
184 with tags that can surprise the unwary.</para>
|
|
bos@559
|
185
|
|
bos@559
|
186 <para>Recall that a tag is stored as a revision to the <filename
|
|
bos@559
|
187 role="special">.hgtags</filename> file, so that when you
|
|
bos@559
|
188 create a tag, the changeset in which it's recorded necessarily
|
|
bos@559
|
189 refers to an older changeset. When you run <command
|
|
bos@559
|
190 role="hg-cmd">hg clone -r foo</command> to clone a
|
|
bos@559
|
191 repository as of tag <literal>foo</literal>, the new clone
|
|
bos@559
|
192 <emphasis>will not contain the history that created the
|
|
bos@559
|
193 tag</emphasis> that you used to clone the repository. The
|
|
bos@559
|
194 result is that you'll get exactly the right subset of the
|
|
bos@559
|
195 project's history in the new repository, but
|
|
bos@559
|
196 <emphasis>not</emphasis> the tag you might have
|
|
bos@559
|
197 expected.</para>
|
|
bos@559
|
198
|
|
bos@559
|
199 </sect2>
|
|
bos@559
|
200 <sect2>
|
|
bos@559
|
201 <title>When permanent tags are too much</title>
|
|
bos@559
|
202
|
|
bos@559
|
203 <para>Since Mercurial's tags are revision controlled and carried
|
|
bos@559
|
204 around with a project's history, everyone you work with will
|
|
bos@559
|
205 see the tags you create. But giving names to revisions has
|
|
bos@559
|
206 uses beyond simply noting that revision
|
|
bos@559
|
207 <literal>4237e45506ee</literal> is really
|
|
bos@559
|
208 <literal>v2.0.2</literal>. If you're trying to track down a
|
|
bos@559
|
209 subtle bug, you might want a tag to remind you of something
|
|
bos@559
|
210 like <quote>Anne saw the symptoms with this
|
|
bos@559
|
211 revision</quote>.</para>
|
|
bos@559
|
212
|
|
bos@559
|
213 <para>For cases like this, what you might want to use are
|
|
bos@559
|
214 <emphasis>local</emphasis> tags. You can create a local tag
|
|
bos@559
|
215 with the <option role="hg-opt-tag">-l</option> option to the
|
|
bos@559
|
216 <command role="hg-cmd">hg tag</command> command. This will
|
|
bos@559
|
217 store the tag in a file called <filename
|
|
bos@559
|
218 role="special">.hg/localtags</filename>. Unlike <filename
|
|
bos@559
|
219 role="special">.hgtags</filename>, <filename
|
|
bos@559
|
220 role="special">.hg/localtags</filename> is not revision
|
|
bos@559
|
221 controlled. Any tags you create using <option
|
|
bos@559
|
222 role="hg-opt-tag">-l</option> remain strictly local to the
|
|
bos@559
|
223 repository you're currently working in.</para>
|
|
bos@559
|
224
|
|
bos@559
|
225 </sect2>
|
|
bos@559
|
226 </sect1>
|
|
bos@559
|
227 <sect1>
|
|
bos@559
|
228 <title>The flow of changes&emdash;big picture vs. little</title>
|
|
bos@559
|
229
|
|
bos@559
|
230 <para>To return to the outline I sketched at the beginning of a
|
|
bos@559
|
231 chapter, let's think about a project that has multiple
|
|
bos@559
|
232 concurrent pieces of work under development at once.</para>
|
|
bos@559
|
233
|
|
bos@559
|
234 <para>There might be a push for a new <quote>main</quote> release;
|
|
bos@559
|
235 a new minor bugfix release to the last main release; and an
|
|
bos@559
|
236 unexpected <quote>hot fix</quote> to an old release that is now
|
|
bos@559
|
237 in maintenance mode.</para>
|
|
bos@559
|
238
|
|
bos@559
|
239 <para>The usual way people refer to these different concurrent
|
|
bos@559
|
240 directions of development is as <quote>branches</quote>.
|
|
bos@559
|
241 However, we've already seen numerous times that Mercurial treats
|
|
bos@559
|
242 <emphasis>all of history</emphasis> as a series of branches and
|
|
bos@559
|
243 merges. Really, what we have here is two ideas that are
|
|
bos@559
|
244 peripherally related, but which happen to share a name.</para>
|
|
bos@559
|
245 <itemizedlist>
|
|
bos@559
|
246 <listitem><para><quote>Big picture</quote> branches represent
|
|
bos@559
|
247 the sweep of a project's evolution; people give them names,
|
|
bos@559
|
248 and talk about them in conversation.</para>
|
|
bos@559
|
249 </listitem>
|
|
bos@559
|
250 <listitem><para><quote>Little picture</quote> branches are
|
|
bos@559
|
251 artefacts of the day-to-day activity of developing and
|
|
bos@559
|
252 merging changes. They expose the narrative of how the code
|
|
bos@559
|
253 was developed.</para>
|
|
bos@559
|
254 </listitem></itemizedlist>
|
|
bos@559
|
255
|
|
bos@559
|
256 </sect1>
|
|
bos@559
|
257 <sect1>
|
|
bos@559
|
258 <title>Managing big-picture branches in repositories</title>
|
|
bos@559
|
259
|
|
bos@559
|
260 <para>The easiest way to isolate a <quote>big picture</quote>
|
|
bos@559
|
261 branch in Mercurial is in a dedicated repository. If you have
|
|
bos@559
|
262 an existing shared repository&emdash;let's call it
|
|
bos@559
|
263 <literal>myproject</literal>&emdash;that reaches a
|
|
bos@559
|
264 <quote>1.0</quote> milestone, you can start to prepare for
|
|
bos@559
|
265 future maintenance releases on top of version 1.0 by tagging the
|
|
bos@567
|
266 revision from which you prepared the 1.0 release.</para>
|
|
bos@567
|
267
|
|
bos@567
|
268 &interaction.branch-repo.tag;
|
|
bos@567
|
269
|
|
bos@567
|
270 <para>You can then clone a new shared
|
|
bos@567
|
271 <literal>myproject-1.0.1</literal> repository as of that
|
|
bos@567
|
272 tag.</para>
|
|
bos@567
|
273
|
|
bos@567
|
274 &interaction.branch-repo.clone;
|
|
bos@559
|
275
|
|
bos@559
|
276 <para>Afterwards, if someone needs to work on a bug fix that ought
|
|
bos@559
|
277 to go into an upcoming 1.0.1 minor release, they clone the
|
|
bos@559
|
278 <literal>myproject-1.0.1</literal> repository, make their
|
|
bos@567
|
279 changes, and push them back.</para>
|
|
bos@567
|
280
|
|
bos@567
|
281 &interaction.branch-repo.bugfix;
|
|
bos@567
|
282
|
|
bos@567
|
283 <para>Meanwhile, development for
|
|
bos@559
|
284 the next major release can continue, isolated and unabated, in
|
|
bos@567
|
285 the <literal>myproject</literal> repository.</para>
|
|
bos@567
|
286
|
|
bos@567
|
287 &interaction.branch-repo.new;
|
|
bos@559
|
288
|
|
bos@559
|
289 </sect1>
|
|
bos@559
|
290 <sect1>
|
|
bos@559
|
291 <title>Don't repeat yourself: merging across branches</title>
|
|
bos@559
|
292
|
|
bos@559
|
293 <para>In many cases, if you have a bug to fix on a maintenance
|
|
bos@559
|
294 branch, the chances are good that the bug exists on your
|
|
bos@559
|
295 project's main branch (and possibly other maintenance branches,
|
|
bos@559
|
296 too). It's a rare developer who wants to fix the same bug
|
|
bos@559
|
297 multiple times, so let's look at a few ways that Mercurial can
|
|
bos@559
|
298 help you to manage these bugfixes without duplicating your
|
|
bos@559
|
299 work.</para>
|
|
bos@559
|
300
|
|
bos@559
|
301 <para>In the simplest instance, all you need to do is pull changes
|
|
bos@559
|
302 from your maintenance branch into your local clone of the target
|
|
bos@567
|
303 branch.</para>
|
|
bos@567
|
304
|
|
bos@567
|
305 &interaction.branch-repo.pull;
|
|
bos@567
|
306
|
|
bos@567
|
307 <para>You'll then need to merge the heads of the two branches, and
|
|
bos@567
|
308 push back to the main branch.</para>
|
|
bos@567
|
309
|
|
bos@567
|
310 &interaction.branch-repo.merge;
|
|
bos@559
|
311
|
|
bos@559
|
312 </sect1>
|
|
bos@559
|
313 <sect1>
|
|
bos@559
|
314 <title>Naming branches within one repository</title>
|
|
bos@559
|
315
|
|
bos@559
|
316 <para>In most instances, isolating branches in repositories is the
|
|
bos@559
|
317 right approach. Its simplicity makes it easy to understand; and
|
|
bos@559
|
318 so it's hard to make mistakes. There's a one-to-one
|
|
bos@559
|
319 relationship between branches you're working in and directories
|
|
bos@559
|
320 on your system. This lets you use normal (non-Mercurial-aware)
|
|
bos@559
|
321 tools to work on files within a branch/repository.</para>
|
|
bos@559
|
322
|
|
bos@559
|
323 <para>If you're more in the <quote>power user</quote> category
|
|
bos@559
|
324 (<emphasis>and</emphasis> your collaborators are too), there is
|
|
bos@559
|
325 an alternative way of handling branches that you can consider.
|
|
bos@559
|
326 I've already mentioned the human-level distinction between
|
|
bos@559
|
327 <quote>small picture</quote> and <quote>big picture</quote>
|
|
bos@559
|
328 branches. While Mercurial works with multiple <quote>small
|
|
bos@559
|
329 picture</quote> branches in a repository all the time (for
|
|
bos@559
|
330 example after you pull changes in, but before you merge them),
|
|
bos@559
|
331 it can <emphasis>also</emphasis> work with multiple <quote>big
|
|
bos@559
|
332 picture</quote> branches.</para>
|
|
bos@559
|
333
|
|
bos@559
|
334 <para>The key to working this way is that Mercurial lets you
|
|
bos@559
|
335 assign a persistent <emphasis>name</emphasis> to a branch.
|
|
bos@559
|
336 There always exists a branch named <literal>default</literal>.
|
|
bos@559
|
337 Even before you start naming branches yourself, you can find
|
|
bos@559
|
338 traces of the <literal>default</literal> branch if you look for
|
|
bos@559
|
339 them.</para>
|
|
bos@559
|
340
|
|
bos@559
|
341 <para>As an example, when you run the <command role="hg-cmd">hg
|
|
bos@559
|
342 commit</command> command, and it pops up your editor so that
|
|
bos@559
|
343 you can enter a commit message, look for a line that contains
|
|
bos@559
|
344 the text <quote><literal>HG: branch default</literal></quote> at
|
|
bos@559
|
345 the bottom. This is telling you that your commit will occur on
|
|
bos@559
|
346 the branch named <literal>default</literal>.</para>
|
|
bos@559
|
347
|
|
bos@559
|
348 <para>To start working with named branches, use the <command
|
|
bos@559
|
349 role="hg-cmd">hg branches</command> command. This command
|
|
bos@559
|
350 lists the named branches already present in your repository,
|
|
bos@567
|
351 telling you which changeset is the tip of each.</para>
|
|
bos@567
|
352
|
|
bos@567
|
353 &interaction.branch-named.branches;
|
|
bos@567
|
354
|
|
bos@567
|
355 <para>Since you haven't created any named branches yet, the only
|
|
bos@567
|
356 one that exists is <literal>default</literal>.</para>
|
|
bos@559
|
357
|
|
bos@559
|
358 <para>To find out what the <quote>current</quote> branch is, run
|
|
bos@559
|
359 the <command role="hg-cmd">hg branch</command> command, giving
|
|
bos@559
|
360 it no arguments. This tells you what branch the parent of the
|
|
bos@567
|
361 current changeset is on.</para>
|
|
bos@567
|
362
|
|
bos@567
|
363 &interaction.branch-named.branch;
|
|
bos@559
|
364
|
|
bos@559
|
365 <para>To create a new branch, run the <command role="hg-cmd">hg
|
|
bos@559
|
366 branch</command> command again. This time, give it one
|
|
bos@567
|
367 argument: the name of the branch you want to create.</para>
|
|
bos@567
|
368
|
|
bos@567
|
369 &interaction.branch-named.create;
|
|
bos@559
|
370
|
|
bos@559
|
371 <para>After you've created a branch, you might wonder what effect
|
|
bos@559
|
372 the <command role="hg-cmd">hg branch</command> command has had.
|
|
bos@559
|
373 What do the <command role="hg-cmd">hg status</command> and
|
|
bos@567
|
374 <command role="hg-cmd">hg tip</command> commands report?</para>
|
|
bos@567
|
375
|
|
bos@567
|
376 &interaction.branch-named.status;
|
|
bos@567
|
377
|
|
bos@567
|
378 <para>Nothing has changed in the
|
|
bos@559
|
379 working directory, and there's been no new history created. As
|
|
bos@559
|
380 this suggests, running the <command role="hg-cmd">hg
|
|
bos@559
|
381 branch</command> command has no permanent effect; it only
|
|
bos@559
|
382 tells Mercurial what branch name to use the
|
|
bos@559
|
383 <emphasis>next</emphasis> time you commit a changeset.</para>
|
|
bos@559
|
384
|
|
bos@559
|
385 <para>When you commit a change, Mercurial records the name of the
|
|
bos@559
|
386 branch on which you committed. Once you've switched from the
|
|
bos@559
|
387 <literal>default</literal> branch to another and committed,
|
|
bos@559
|
388 you'll see the name of the new branch show up in the output of
|
|
bos@559
|
389 <command role="hg-cmd">hg log</command>, <command
|
|
bos@559
|
390 role="hg-cmd">hg tip</command>, and other commands that
|
|
bos@567
|
391 display the same kind of output.</para>
|
|
bos@567
|
392
|
|
bos@567
|
393 &interaction.branch-named.commit;
|
|
bos@567
|
394
|
|
bos@567
|
395 <para>The <command role="hg-cmd">hg log</command>-like commands
|
|
bos@567
|
396 will print the branch name of every changeset that's not on the
|
|
bos@559
|
397 <literal>default</literal> branch. As a result, if you never
|
|
bos@559
|
398 use named branches, you'll never see this information.</para>
|
|
bos@559
|
399
|
|
bos@559
|
400 <para>Once you've named a branch and committed a change with that
|
|
bos@559
|
401 name, every subsequent commit that descends from that change
|
|
bos@559
|
402 will inherit the same branch name. You can change the name of a
|
|
bos@559
|
403 branch at any time, using the <command role="hg-cmd">hg
|
|
bos@567
|
404 branch</command> command.</para>
|
|
bos@567
|
405
|
|
bos@567
|
406 &interaction.branch-named.rebranch;
|
|
bos@567
|
407
|
|
bos@567
|
408 <para>In practice, this is something you won't do very often, as
|
|
bos@567
|
409 branch names tend to have fairly long lifetimes. (This isn't a
|
|
bos@567
|
410 rule, just an observation.)</para>
|
|
bos@559
|
411
|
|
bos@559
|
412 </sect1>
|
|
bos@559
|
413 <sect1>
|
|
bos@559
|
414 <title>Dealing with multiple named branches in a
|
|
bos@559
|
415 repository</title>
|
|
bos@559
|
416
|
|
bos@559
|
417 <para>If you have more than one named branch in a repository,
|
|
bos@559
|
418 Mercurial will remember the branch that your working directory
|
|
bos@559
|
419 on when you start a command like <command role="hg-cmd">hg
|
|
bos@559
|
420 update</command> or <command role="hg-cmd">hg pull
|
|
bos@559
|
421 -u</command>. It will update the working directory to the tip
|
|
bos@559
|
422 of this branch, no matter what the <quote>repo-wide</quote> tip
|
|
bos@559
|
423 is. To update to a revision that's on a different named branch,
|
|
bos@559
|
424 you may need to use the <option role="hg-opt-update">-C</option>
|
|
bos@559
|
425 option to <command role="hg-cmd">hg update</command>.</para>
|
|
bos@559
|
426
|
|
bos@559
|
427 <para>This behaviour is a little subtle, so let's see it in
|
|
bos@559
|
428 action. First, let's remind ourselves what branch we're
|
|
bos@567
|
429 currently on, and what branches are in our repository.</para>
|
|
bos@567
|
430
|
|
bos@567
|
431 &interaction.branch-named.parents;
|
|
bos@567
|
432
|
|
bos@567
|
433 <para>We're on the <literal>bar</literal> branch, but there also
|
|
bos@567
|
434 exists an older <command role="hg-cmd">hg foo</command>
|
|
bos@567
|
435 branch.</para>
|
|
bos@559
|
436
|
|
bos@559
|
437 <para>We can <command role="hg-cmd">hg update</command> back and
|
|
bos@559
|
438 forth between the tips of the <literal>foo</literal> and
|
|
bos@559
|
439 <literal>bar</literal> branches without needing to use the
|
|
bos@559
|
440 <option role="hg-opt-update">-C</option> option, because this
|
|
bos@559
|
441 only involves going backwards and forwards linearly through our
|
|
bos@567
|
442 change history.</para>
|
|
bos@567
|
443
|
|
bos@567
|
444 &interaction.branch-named.update-switchy;
|
|
bos@559
|
445
|
|
bos@559
|
446 <para>If we go back to the <literal>foo</literal> branch and then
|
|
bos@559
|
447 run <command role="hg-cmd">hg update</command>, it will keep us
|
|
bos@559
|
448 on <literal>foo</literal>, not move us to the tip of
|
|
bos@567
|
449 <literal>bar</literal>.</para>
|
|
bos@567
|
450
|
|
bos@567
|
451 &interaction.branch-named.update-nothing;
|
|
bos@559
|
452
|
|
bos@559
|
453 <para>Committing a new change on the <literal>foo</literal> branch
|
|
bos@567
|
454 introduces a new head.</para>
|
|
bos@567
|
455
|
|
bos@567
|
456 &interaction.branch-named.foo-commit;
|
|
bos@559
|
457
|
|
bos@559
|
458 </sect1>
|
|
bos@559
|
459 <sect1>
|
|
bos@559
|
460 <title>Branch names and merging</title>
|
|
bos@559
|
461
|
|
bos@559
|
462 <para>As you've probably noticed, merges in Mercurial are not
|
|
bos@559
|
463 symmetrical. Let's say our repository has two heads, 17 and 23.
|
|
bos@559
|
464 If I <command role="hg-cmd">hg update</command> to 17 and then
|
|
bos@559
|
465 <command role="hg-cmd">hg merge</command> with 23, Mercurial
|
|
bos@559
|
466 records 17 as the first parent of the merge, and 23 as the
|
|
bos@559
|
467 second. Whereas if I <command role="hg-cmd">hg update</command>
|
|
bos@559
|
468 to 23 and then <command role="hg-cmd">hg merge</command> with
|
|
bos@559
|
469 17, it records 23 as the first parent, and 17 as the
|
|
bos@559
|
470 second.</para>
|
|
bos@559
|
471
|
|
bos@559
|
472 <para>This affects Mercurial's choice of branch name when you
|
|
bos@559
|
473 merge. After a merge, Mercurial will retain the branch name of
|
|
bos@559
|
474 the first parent when you commit the result of the merge. If
|
|
bos@559
|
475 your first parent's branch name is <literal>foo</literal>, and
|
|
bos@559
|
476 you merge with <literal>bar</literal>, the branch name will
|
|
bos@559
|
477 still be <literal>foo</literal> after you merge.</para>
|
|
bos@559
|
478
|
|
bos@559
|
479 <para>It's not unusual for a repository to contain multiple heads,
|
|
bos@559
|
480 each with the same branch name. Let's say I'm working on the
|
|
bos@559
|
481 <literal>foo</literal> branch, and so are you. We commit
|
|
bos@559
|
482 different changes; I pull your changes; I now have two heads,
|
|
bos@559
|
483 each claiming to be on the <literal>foo</literal> branch. The
|
|
bos@559
|
484 result of a merge will be a single head on the
|
|
bos@559
|
485 <literal>foo</literal> branch, as you might hope.</para>
|
|
bos@559
|
486
|
|
bos@559
|
487 <para>But if I'm working on the <literal>bar</literal> branch, and
|
|
bos@559
|
488 I merge work from the <literal>foo</literal> branch, the result
|
|
bos@567
|
489 will remain on the <literal>bar</literal> branch.</para>
|
|
bos@567
|
490
|
|
bos@567
|
491 &interaction.branch-named.merge;
|
|
bos@559
|
492
|
|
bos@559
|
493 <para>To give a more concrete example, if I'm working on the
|
|
bos@559
|
494 <literal>bleeding-edge</literal> branch, and I want to bring in
|
|
bos@559
|
495 the latest fixes from the <literal>stable</literal> branch,
|
|
bos@559
|
496 Mercurial will choose the <quote>right</quote>
|
|
bos@559
|
497 (<literal>bleeding-edge</literal>) branch name when I pull and
|
|
bos@559
|
498 merge from <literal>stable</literal>.</para>
|
|
bos@559
|
499
|
|
bos@559
|
500 </sect1>
|
|
bos@559
|
501 <sect1>
|
|
bos@559
|
502 <title>Branch naming is generally useful</title>
|
|
bos@559
|
503
|
|
bos@559
|
504 <para>You shouldn't think of named branches as applicable only to
|
|
bos@559
|
505 situations where you have multiple long-lived branches
|
|
bos@559
|
506 cohabiting in a single repository. They're very useful even in
|
|
bos@559
|
507 the one-branch-per-repository case.</para>
|
|
bos@559
|
508
|
|
bos@559
|
509 <para>In the simplest case, giving a name to each branch gives you
|
|
bos@559
|
510 a permanent record of which branch a changeset originated on.
|
|
bos@559
|
511 This gives you more context when you're trying to follow the
|
|
bos@559
|
512 history of a long-lived branchy project.</para>
|
|
bos@559
|
513
|
|
bos@559
|
514 <para>If you're working with shared repositories, you can set up a
|
|
bos@559
|
515 <literal role="hook">pretxnchangegroup</literal> hook on each
|
|
bos@559
|
516 that will block incoming changes that have the
|
|
bos@559
|
517 <quote>wrong</quote> branch name. This provides a simple, but
|
|
bos@559
|
518 effective, defence against people accidentally pushing changes
|
|
bos@559
|
519 from a <quote>bleeding edge</quote> branch to a
|
|
bos@559
|
520 <quote>stable</quote> branch. Such a hook might look like this
|
|
bos@559
|
521 inside the shared repo's <filename role="special">
|
|
bos@559
|
522 /.hgrc</filename>.</para>
|
|
bos@580
|
523 <programlisting>[hooks]
|
|
bos@580
|
524 pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch</programlisting>
|
|
bos@559
|
525
|
|
bos@559
|
526 </sect1>
|
|
bos@559
|
527 </chapter>
|
|
bos@559
|
528
|
|
bos@559
|
529 <!--
|
|
bos@559
|
530 local variables:
|
|
bos@559
|
531 sgml-parent-document: ("00book.xml" "book" "chapter")
|
|
bos@559
|
532 end:
|
|
bos@559
|
533 -->
|
