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