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