hgbook
diff en/ch07-branch.xml @ 583:28b5a5befb08
Fold preface and intro into one
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Thu Mar 19 20:54:12 2009 -0700 (2009-03-19) |
parents | en/ch08-branch.xml@8366882f67f2 |
children | c838b3975bc6 |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/en/ch07-branch.xml Thu Mar 19 20:54:12 2009 -0700 1.3 @@ -0,0 +1,533 @@ 1.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 1.5 + 1.6 +<chapter id="chap:branch"> 1.7 + <?dbhtml filename="managing-releases-and-branchy-development.html"?> 1.8 + <title>Managing releases and branchy development</title> 1.9 + 1.10 + <para>Mercurial provides several mechanisms for you to manage a 1.11 + project that is making progress on multiple fronts at once. To 1.12 + understand these mechanisms, let's first take a brief look at a 1.13 + fairly normal software project structure.</para> 1.14 + 1.15 + <para>Many software projects issue periodic <quote>major</quote> 1.16 + releases that contain substantial new features. In parallel, they 1.17 + may issue <quote>minor</quote> releases. These are usually 1.18 + identical to the major releases off which they're based, but with 1.19 + a few bugs fixed.</para> 1.20 + 1.21 + <para>In this chapter, we'll start by talking about how to keep 1.22 + records of project milestones such as releases. We'll then 1.23 + continue on to talk about the flow of work between different 1.24 + phases of a project, and how Mercurial can help you to isolate and 1.25 + manage this work.</para> 1.26 + 1.27 + <sect1> 1.28 + <title>Giving a persistent name to a revision</title> 1.29 + 1.30 + <para>Once you decide that you'd like to call a particular 1.31 + revision a <quote>release</quote>, it's a good idea to record 1.32 + the identity of that revision. This will let you reproduce that 1.33 + release at a later date, for whatever purpose you might need at 1.34 + the time (reproducing a bug, porting to a new platform, etc). 1.35 + &interaction.tag.init;</para> 1.36 + 1.37 + <para>Mercurial lets you give a permanent name to any revision 1.38 + using the <command role="hg-cmd">hg tag</command> command. Not 1.39 + surprisingly, these names are called <quote>tags</quote>.</para> 1.40 + 1.41 + &interaction.tag.tag; 1.42 + 1.43 + <para>A tag is nothing more than a <quote>symbolic name</quote> 1.44 + for a revision. Tags exist purely for your convenience, so that 1.45 + you have a handy permanent way to refer to a revision; Mercurial 1.46 + doesn't interpret the tag names you use in any way. Neither 1.47 + does Mercurial place any restrictions on the name of a tag, 1.48 + beyond a few that are necessary to ensure that a tag can be 1.49 + parsed unambiguously. A tag name cannot contain any of the 1.50 + following characters:</para> 1.51 + <itemizedlist> 1.52 + <listitem><para>Colon (ASCII 58, 1.53 + <quote><literal>:</literal></quote>)</para> 1.54 + </listitem> 1.55 + <listitem><para>Carriage return (ASCII 13, 1.56 + <quote><literal>\r</literal></quote>)</para> 1.57 + </listitem> 1.58 + <listitem><para>Newline (ASCII 10, 1.59 + <quote><literal>\n</literal></quote>)</para> 1.60 + </listitem></itemizedlist> 1.61 + 1.62 + <para>You can use the <command role="hg-cmd">hg tags</command> 1.63 + command to display the tags present in your repository. In the 1.64 + output, each tagged revision is identified first by its name, 1.65 + then by revision number, and finally by the unique hash of the 1.66 + revision.</para> 1.67 + 1.68 + &interaction.tag.tags; 1.69 + 1.70 + <para>Notice that <literal>tip</literal> is listed in the output 1.71 + of <command role="hg-cmd">hg tags</command>. The 1.72 + <literal>tip</literal> tag is a special <quote>floating</quote> 1.73 + tag, which always identifies the newest revision in the 1.74 + repository.</para> 1.75 + 1.76 + <para>In the output of the <command role="hg-cmd">hg 1.77 + tags</command> command, tags are listed in reverse order, by 1.78 + revision number. This usually means that recent tags are listed 1.79 + before older tags. It also means that <literal>tip</literal> is 1.80 + always going to be the first tag listed in the output of 1.81 + <command role="hg-cmd">hg tags</command>.</para> 1.82 + 1.83 + <para>When you run <command role="hg-cmd">hg log</command>, if it 1.84 + displays a revision that has tags associated with it, it will 1.85 + print those tags.</para> 1.86 + 1.87 + &interaction.tag.log; 1.88 + 1.89 + <para>Any time you need to provide a revision ID to a Mercurial 1.90 + command, the command will accept a tag name in its place. 1.91 + Internally, Mercurial will translate your tag name into the 1.92 + corresponding revision ID, then use that.</para> 1.93 + 1.94 + &interaction.tag.log.v1.0; 1.95 + 1.96 + <para>There's no limit on the number of tags you can have in a 1.97 + repository, or on the number of tags that a single revision can 1.98 + have. As a practical matter, it's not a great idea to have 1.99 + <quote>too many</quote> (a number which will vary from project 1.100 + to project), simply because tags are supposed to help you to 1.101 + find revisions. If you have lots of tags, the ease of using 1.102 + them to identify revisions diminishes rapidly.</para> 1.103 + 1.104 + <para>For example, if your project has milestones as frequent as 1.105 + every few days, it's perfectly reasonable to tag each one of 1.106 + those. But if you have a continuous build system that makes 1.107 + sure every revision can be built cleanly, you'd be introducing a 1.108 + lot of noise if you were to tag every clean build. Instead, you 1.109 + could tag failed builds (on the assumption that they're rare!), 1.110 + or simply not use tags to track buildability.</para> 1.111 + 1.112 + <para>If you want to remove a tag that you no longer want, use 1.113 + <command role="hg-cmd">hg tag --remove</command>.</para> 1.114 + 1.115 + &interaction.tag.remove; 1.116 + 1.117 + <para>You can also modify a tag at any time, so that it identifies 1.118 + a different revision, by simply issuing a new <command 1.119 + role="hg-cmd">hg tag</command> command. You'll have to use the 1.120 + <option role="hg-opt-tag">-f</option> option to tell Mercurial 1.121 + that you <emphasis>really</emphasis> want to update the 1.122 + tag.</para> 1.123 + 1.124 + &interaction.tag.replace; 1.125 + 1.126 + <para>There will still be a permanent record of the previous 1.127 + identity of the tag, but Mercurial will no longer use it. 1.128 + There's thus no penalty to tagging the wrong revision; all you 1.129 + have to do is turn around and tag the correct revision once you 1.130 + discover your error.</para> 1.131 + 1.132 + <para>Mercurial stores tags in a normal revision-controlled file 1.133 + in your repository. If you've created any tags, you'll find 1.134 + them in a file named <filename 1.135 + role="special">.hgtags</filename>. When you run the <command 1.136 + role="hg-cmd">hg tag</command> command, Mercurial modifies 1.137 + this file, then automatically commits the change to it. This 1.138 + means that every time you run <command role="hg-cmd">hg 1.139 + tag</command>, you'll see a corresponding changeset in the 1.140 + output of <command role="hg-cmd">hg log</command>.</para> 1.141 + 1.142 + &interaction.tag.tip; 1.143 + 1.144 + <sect2> 1.145 + <title>Handling tag conflicts during a merge</title> 1.146 + 1.147 + <para>You won't often need to care about the <filename 1.148 + role="special">.hgtags</filename> file, but it sometimes 1.149 + makes its presence known during a merge. The format of the 1.150 + file is simple: it consists of a series of lines. Each line 1.151 + starts with a changeset hash, followed by a space, followed by 1.152 + the name of a tag.</para> 1.153 + 1.154 + <para>If you're resolving a conflict in the <filename 1.155 + role="special">.hgtags</filename> file during a merge, 1.156 + there's one twist to modifying the <filename 1.157 + role="special">.hgtags</filename> file: when Mercurial is 1.158 + parsing the tags in a repository, it 1.159 + <emphasis>never</emphasis> reads the working copy of the 1.160 + <filename role="special">.hgtags</filename> file. Instead, it 1.161 + reads the <emphasis>most recently committed</emphasis> 1.162 + revision of the file.</para> 1.163 + 1.164 + <para>An unfortunate consequence of this design is that you 1.165 + can't actually verify that your merged <filename 1.166 + role="special">.hgtags</filename> file is correct until 1.167 + <emphasis>after</emphasis> you've committed a change. So if 1.168 + you find yourself resolving a conflict on <filename 1.169 + role="special">.hgtags</filename> during a merge, be sure to 1.170 + run <command role="hg-cmd">hg tags</command> after you commit. 1.171 + If it finds an error in the <filename 1.172 + role="special">.hgtags</filename> file, it will report the 1.173 + location of the error, which you can then fix and commit. You 1.174 + should then run <command role="hg-cmd">hg tags</command> 1.175 + again, just to be sure that your fix is correct.</para> 1.176 + 1.177 + </sect2> 1.178 + <sect2> 1.179 + <title>Tags and cloning</title> 1.180 + 1.181 + <para>You may have noticed that the <command role="hg-cmd">hg 1.182 + clone</command> command has a <option 1.183 + role="hg-opt-clone">-r</option> option that lets you clone 1.184 + an exact copy of the repository as of a particular changeset. 1.185 + The new clone will not contain any project history that comes 1.186 + after the revision you specified. This has an interaction 1.187 + with tags that can surprise the unwary.</para> 1.188 + 1.189 + <para>Recall that a tag is stored as a revision to the <filename 1.190 + role="special">.hgtags</filename> file, so that when you 1.191 + create a tag, the changeset in which it's recorded necessarily 1.192 + refers to an older changeset. When you run <command 1.193 + role="hg-cmd">hg clone -r foo</command> to clone a 1.194 + repository as of tag <literal>foo</literal>, the new clone 1.195 + <emphasis>will not contain the history that created the 1.196 + tag</emphasis> that you used to clone the repository. The 1.197 + result is that you'll get exactly the right subset of the 1.198 + project's history in the new repository, but 1.199 + <emphasis>not</emphasis> the tag you might have 1.200 + expected.</para> 1.201 + 1.202 + </sect2> 1.203 + <sect2> 1.204 + <title>When permanent tags are too much</title> 1.205 + 1.206 + <para>Since Mercurial's tags are revision controlled and carried 1.207 + around with a project's history, everyone you work with will 1.208 + see the tags you create. But giving names to revisions has 1.209 + uses beyond simply noting that revision 1.210 + <literal>4237e45506ee</literal> is really 1.211 + <literal>v2.0.2</literal>. If you're trying to track down a 1.212 + subtle bug, you might want a tag to remind you of something 1.213 + like <quote>Anne saw the symptoms with this 1.214 + revision</quote>.</para> 1.215 + 1.216 + <para>For cases like this, what you might want to use are 1.217 + <emphasis>local</emphasis> tags. You can create a local tag 1.218 + with the <option role="hg-opt-tag">-l</option> option to the 1.219 + <command role="hg-cmd">hg tag</command> command. This will 1.220 + store the tag in a file called <filename 1.221 + role="special">.hg/localtags</filename>. Unlike <filename 1.222 + role="special">.hgtags</filename>, <filename 1.223 + role="special">.hg/localtags</filename> is not revision 1.224 + controlled. Any tags you create using <option 1.225 + role="hg-opt-tag">-l</option> remain strictly local to the 1.226 + repository you're currently working in.</para> 1.227 + 1.228 + </sect2> 1.229 + </sect1> 1.230 + <sect1> 1.231 + <title>The flow of changes&emdash;big picture vs. little</title> 1.232 + 1.233 + <para>To return to the outline I sketched at the beginning of a 1.234 + chapter, let's think about a project that has multiple 1.235 + concurrent pieces of work under development at once.</para> 1.236 + 1.237 + <para>There might be a push for a new <quote>main</quote> release; 1.238 + a new minor bugfix release to the last main release; and an 1.239 + unexpected <quote>hot fix</quote> to an old release that is now 1.240 + in maintenance mode.</para> 1.241 + 1.242 + <para>The usual way people refer to these different concurrent 1.243 + directions of development is as <quote>branches</quote>. 1.244 + However, we've already seen numerous times that Mercurial treats 1.245 + <emphasis>all of history</emphasis> as a series of branches and 1.246 + merges. Really, what we have here is two ideas that are 1.247 + peripherally related, but which happen to share a name.</para> 1.248 + <itemizedlist> 1.249 + <listitem><para><quote>Big picture</quote> branches represent 1.250 + the sweep of a project's evolution; people give them names, 1.251 + and talk about them in conversation.</para> 1.252 + </listitem> 1.253 + <listitem><para><quote>Little picture</quote> branches are 1.254 + artefacts of the day-to-day activity of developing and 1.255 + merging changes. They expose the narrative of how the code 1.256 + was developed.</para> 1.257 + </listitem></itemizedlist> 1.258 + 1.259 + </sect1> 1.260 + <sect1> 1.261 + <title>Managing big-picture branches in repositories</title> 1.262 + 1.263 + <para>The easiest way to isolate a <quote>big picture</quote> 1.264 + branch in Mercurial is in a dedicated repository. If you have 1.265 + an existing shared repository&emdash;let's call it 1.266 + <literal>myproject</literal>&emdash;that reaches a 1.267 + <quote>1.0</quote> milestone, you can start to prepare for 1.268 + future maintenance releases on top of version 1.0 by tagging the 1.269 + revision from which you prepared the 1.0 release.</para> 1.270 + 1.271 + &interaction.branch-repo.tag; 1.272 + 1.273 + <para>You can then clone a new shared 1.274 + <literal>myproject-1.0.1</literal> repository as of that 1.275 + tag.</para> 1.276 + 1.277 + &interaction.branch-repo.clone; 1.278 + 1.279 + <para>Afterwards, if someone needs to work on a bug fix that ought 1.280 + to go into an upcoming 1.0.1 minor release, they clone the 1.281 + <literal>myproject-1.0.1</literal> repository, make their 1.282 + changes, and push them back.</para> 1.283 + 1.284 + &interaction.branch-repo.bugfix; 1.285 + 1.286 + <para>Meanwhile, development for 1.287 + the next major release can continue, isolated and unabated, in 1.288 + the <literal>myproject</literal> repository.</para> 1.289 + 1.290 + &interaction.branch-repo.new; 1.291 + 1.292 + </sect1> 1.293 + <sect1> 1.294 + <title>Don't repeat yourself: merging across branches</title> 1.295 + 1.296 + <para>In many cases, if you have a bug to fix on a maintenance 1.297 + branch, the chances are good that the bug exists on your 1.298 + project's main branch (and possibly other maintenance branches, 1.299 + too). It's a rare developer who wants to fix the same bug 1.300 + multiple times, so let's look at a few ways that Mercurial can 1.301 + help you to manage these bugfixes without duplicating your 1.302 + work.</para> 1.303 + 1.304 + <para>In the simplest instance, all you need to do is pull changes 1.305 + from your maintenance branch into your local clone of the target 1.306 + branch.</para> 1.307 + 1.308 + &interaction.branch-repo.pull; 1.309 + 1.310 + <para>You'll then need to merge the heads of the two branches, and 1.311 + push back to the main branch.</para> 1.312 + 1.313 + &interaction.branch-repo.merge; 1.314 + 1.315 + </sect1> 1.316 + <sect1> 1.317 + <title>Naming branches within one repository</title> 1.318 + 1.319 + <para>In most instances, isolating branches in repositories is the 1.320 + right approach. Its simplicity makes it easy to understand; and 1.321 + so it's hard to make mistakes. There's a one-to-one 1.322 + relationship between branches you're working in and directories 1.323 + on your system. This lets you use normal (non-Mercurial-aware) 1.324 + tools to work on files within a branch/repository.</para> 1.325 + 1.326 + <para>If you're more in the <quote>power user</quote> category 1.327 + (<emphasis>and</emphasis> your collaborators are too), there is 1.328 + an alternative way of handling branches that you can consider. 1.329 + I've already mentioned the human-level distinction between 1.330 + <quote>small picture</quote> and <quote>big picture</quote> 1.331 + branches. While Mercurial works with multiple <quote>small 1.332 + picture</quote> branches in a repository all the time (for 1.333 + example after you pull changes in, but before you merge them), 1.334 + it can <emphasis>also</emphasis> work with multiple <quote>big 1.335 + picture</quote> branches.</para> 1.336 + 1.337 + <para>The key to working this way is that Mercurial lets you 1.338 + assign a persistent <emphasis>name</emphasis> to a branch. 1.339 + There always exists a branch named <literal>default</literal>. 1.340 + Even before you start naming branches yourself, you can find 1.341 + traces of the <literal>default</literal> branch if you look for 1.342 + them.</para> 1.343 + 1.344 + <para>As an example, when you run the <command role="hg-cmd">hg 1.345 + commit</command> command, and it pops up your editor so that 1.346 + you can enter a commit message, look for a line that contains 1.347 + the text <quote><literal>HG: branch default</literal></quote> at 1.348 + the bottom. This is telling you that your commit will occur on 1.349 + the branch named <literal>default</literal>.</para> 1.350 + 1.351 + <para>To start working with named branches, use the <command 1.352 + role="hg-cmd">hg branches</command> command. This command 1.353 + lists the named branches already present in your repository, 1.354 + telling you which changeset is the tip of each.</para> 1.355 + 1.356 + &interaction.branch-named.branches; 1.357 + 1.358 + <para>Since you haven't created any named branches yet, the only 1.359 + one that exists is <literal>default</literal>.</para> 1.360 + 1.361 + <para>To find out what the <quote>current</quote> branch is, run 1.362 + the <command role="hg-cmd">hg branch</command> command, giving 1.363 + it no arguments. This tells you what branch the parent of the 1.364 + current changeset is on.</para> 1.365 + 1.366 + &interaction.branch-named.branch; 1.367 + 1.368 + <para>To create a new branch, run the <command role="hg-cmd">hg 1.369 + branch</command> command again. This time, give it one 1.370 + argument: the name of the branch you want to create.</para> 1.371 + 1.372 + &interaction.branch-named.create; 1.373 + 1.374 + <para>After you've created a branch, you might wonder what effect 1.375 + the <command role="hg-cmd">hg branch</command> command has had. 1.376 + What do the <command role="hg-cmd">hg status</command> and 1.377 + <command role="hg-cmd">hg tip</command> commands report?</para> 1.378 + 1.379 + &interaction.branch-named.status; 1.380 + 1.381 + <para>Nothing has changed in the 1.382 + working directory, and there's been no new history created. As 1.383 + this suggests, running the <command role="hg-cmd">hg 1.384 + branch</command> command has no permanent effect; it only 1.385 + tells Mercurial what branch name to use the 1.386 + <emphasis>next</emphasis> time you commit a changeset.</para> 1.387 + 1.388 + <para>When you commit a change, Mercurial records the name of the 1.389 + branch on which you committed. Once you've switched from the 1.390 + <literal>default</literal> branch to another and committed, 1.391 + you'll see the name of the new branch show up in the output of 1.392 + <command role="hg-cmd">hg log</command>, <command 1.393 + role="hg-cmd">hg tip</command>, and other commands that 1.394 + display the same kind of output.</para> 1.395 + 1.396 + &interaction.branch-named.commit; 1.397 + 1.398 + <para>The <command role="hg-cmd">hg log</command>-like commands 1.399 + will print the branch name of every changeset that's not on the 1.400 + <literal>default</literal> branch. As a result, if you never 1.401 + use named branches, you'll never see this information.</para> 1.402 + 1.403 + <para>Once you've named a branch and committed a change with that 1.404 + name, every subsequent commit that descends from that change 1.405 + will inherit the same branch name. You can change the name of a 1.406 + branch at any time, using the <command role="hg-cmd">hg 1.407 + branch</command> command.</para> 1.408 + 1.409 + &interaction.branch-named.rebranch; 1.410 + 1.411 + <para>In practice, this is something you won't do very often, as 1.412 + branch names tend to have fairly long lifetimes. (This isn't a 1.413 + rule, just an observation.)</para> 1.414 + 1.415 + </sect1> 1.416 + <sect1> 1.417 + <title>Dealing with multiple named branches in a 1.418 + repository</title> 1.419 + 1.420 + <para>If you have more than one named branch in a repository, 1.421 + Mercurial will remember the branch that your working directory 1.422 + on when you start a command like <command role="hg-cmd">hg 1.423 + update</command> or <command role="hg-cmd">hg pull 1.424 + -u</command>. It will update the working directory to the tip 1.425 + of this branch, no matter what the <quote>repo-wide</quote> tip 1.426 + is. To update to a revision that's on a different named branch, 1.427 + you may need to use the <option role="hg-opt-update">-C</option> 1.428 + option to <command role="hg-cmd">hg update</command>.</para> 1.429 + 1.430 + <para>This behaviour is a little subtle, so let's see it in 1.431 + action. First, let's remind ourselves what branch we're 1.432 + currently on, and what branches are in our repository.</para> 1.433 + 1.434 + &interaction.branch-named.parents; 1.435 + 1.436 + <para>We're on the <literal>bar</literal> branch, but there also 1.437 + exists an older <command role="hg-cmd">hg foo</command> 1.438 + branch.</para> 1.439 + 1.440 + <para>We can <command role="hg-cmd">hg update</command> back and 1.441 + forth between the tips of the <literal>foo</literal> and 1.442 + <literal>bar</literal> branches without needing to use the 1.443 + <option role="hg-opt-update">-C</option> option, because this 1.444 + only involves going backwards and forwards linearly through our 1.445 + change history.</para> 1.446 + 1.447 + &interaction.branch-named.update-switchy; 1.448 + 1.449 + <para>If we go back to the <literal>foo</literal> branch and then 1.450 + run <command role="hg-cmd">hg update</command>, it will keep us 1.451 + on <literal>foo</literal>, not move us to the tip of 1.452 + <literal>bar</literal>.</para> 1.453 + 1.454 + &interaction.branch-named.update-nothing; 1.455 + 1.456 + <para>Committing a new change on the <literal>foo</literal> branch 1.457 + introduces a new head.</para> 1.458 + 1.459 + &interaction.branch-named.foo-commit; 1.460 + 1.461 + </sect1> 1.462 + <sect1> 1.463 + <title>Branch names and merging</title> 1.464 + 1.465 + <para>As you've probably noticed, merges in Mercurial are not 1.466 + symmetrical. Let's say our repository has two heads, 17 and 23. 1.467 + If I <command role="hg-cmd">hg update</command> to 17 and then 1.468 + <command role="hg-cmd">hg merge</command> with 23, Mercurial 1.469 + records 17 as the first parent of the merge, and 23 as the 1.470 + second. Whereas if I <command role="hg-cmd">hg update</command> 1.471 + to 23 and then <command role="hg-cmd">hg merge</command> with 1.472 + 17, it records 23 as the first parent, and 17 as the 1.473 + second.</para> 1.474 + 1.475 + <para>This affects Mercurial's choice of branch name when you 1.476 + merge. After a merge, Mercurial will retain the branch name of 1.477 + the first parent when you commit the result of the merge. If 1.478 + your first parent's branch name is <literal>foo</literal>, and 1.479 + you merge with <literal>bar</literal>, the branch name will 1.480 + still be <literal>foo</literal> after you merge.</para> 1.481 + 1.482 + <para>It's not unusual for a repository to contain multiple heads, 1.483 + each with the same branch name. Let's say I'm working on the 1.484 + <literal>foo</literal> branch, and so are you. We commit 1.485 + different changes; I pull your changes; I now have two heads, 1.486 + each claiming to be on the <literal>foo</literal> branch. The 1.487 + result of a merge will be a single head on the 1.488 + <literal>foo</literal> branch, as you might hope.</para> 1.489 + 1.490 + <para>But if I'm working on the <literal>bar</literal> branch, and 1.491 + I merge work from the <literal>foo</literal> branch, the result 1.492 + will remain on the <literal>bar</literal> branch.</para> 1.493 + 1.494 + &interaction.branch-named.merge; 1.495 + 1.496 + <para>To give a more concrete example, if I'm working on the 1.497 + <literal>bleeding-edge</literal> branch, and I want to bring in 1.498 + the latest fixes from the <literal>stable</literal> branch, 1.499 + Mercurial will choose the <quote>right</quote> 1.500 + (<literal>bleeding-edge</literal>) branch name when I pull and 1.501 + merge from <literal>stable</literal>.</para> 1.502 + 1.503 + </sect1> 1.504 + <sect1> 1.505 + <title>Branch naming is generally useful</title> 1.506 + 1.507 + <para>You shouldn't think of named branches as applicable only to 1.508 + situations where you have multiple long-lived branches 1.509 + cohabiting in a single repository. They're very useful even in 1.510 + the one-branch-per-repository case.</para> 1.511 + 1.512 + <para>In the simplest case, giving a name to each branch gives you 1.513 + a permanent record of which branch a changeset originated on. 1.514 + This gives you more context when you're trying to follow the 1.515 + history of a long-lived branchy project.</para> 1.516 + 1.517 + <para>If you're working with shared repositories, you can set up a 1.518 + <literal role="hook">pretxnchangegroup</literal> hook on each 1.519 + that will block incoming changes that have the 1.520 + <quote>wrong</quote> branch name. This provides a simple, but 1.521 + effective, defence against people accidentally pushing changes 1.522 + from a <quote>bleeding edge</quote> branch to a 1.523 + <quote>stable</quote> branch. Such a hook might look like this 1.524 + inside the shared repo's <filename role="special"> 1.525 + /.hgrc</filename>.</para> 1.526 + <programlisting>[hooks] 1.527 +pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch</programlisting> 1.528 + 1.529 + </sect1> 1.530 +</chapter> 1.531 + 1.532 +<!-- 1.533 +local variables: 1.534 +sgml-parent-document: ("00book.xml" "book" "chapter") 1.535 +end: 1.536 +-->