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