hgbook: 64393e8da2ff fr/ch08-branch.xml

hgbook

view fr/ch08-branch.xml @ 981:64393e8da2ff

Some errors corrected in fr/ch00-preface.xml

author	Frédéric Bouquet <youshe.jaalon@gmail.com>
date	Tue Sep 08 15:30:26 2009 +0200 (2009-09-08)
parents
children	6f8c48362758

line source

1

3 <chapter>

4 <title>Managing releases and branchy development</title>

5 <para>\label{chap:branch}</para>

7 <para>Mercurial provides several mechanisms for you to manage a project that

8 is making progress on multiple fronts at once. To understand these

9 mechanisms, let's first take a brief look at a fairly normal software

10 project structure.</para>

12 <para>Many software projects issue periodic <quote>major</quote> releases that contain

13 substantial new features. In parallel, they may issue <quote>minor</quote>

14 releases. These are usually identical to the major releases off which

15 they're based, but with a few bugs fixed.</para>

17 <para>In this chapter, we'll start by talking about how to keep records of

18 project milestones such as releases. We'll then continue on to talk

19 about the flow of work between different phases of a project, and how

20 Mercurial can help you to isolate and manage this work.</para>

22 <sect1>

23 <title>Giving a persistent name to a revision</title>

25 <para>Once you decide that you'd like to call a particular revision a

26 <quote>release</quote>, it's a good idea to record the identity of that revision.

27 This will let you reproduce that release at a later date, for whatever

28 purpose you might need at the time (reproducing a bug, porting to a

29 new platform, etc).

30 </para>

32 <para>Mercurial lets you give a permanent name to any revision using the

33 <command role="hg-cmd">hg tag</command> command. Not surprisingly, these names are called

34 <quote>tags</quote>.

35 </para>

37 <para>A tag is nothing more than a <quote>symbolic name</quote> for a revision. Tags

38 exist purely for your convenience, so that you have a handy permanent

39 way to refer to a revision; Mercurial doesn't interpret the tag names

40 you use in any way. Neither does Mercurial place any restrictions on

41 the name of a tag, beyond a few that are necessary to ensure that a

42 tag can be parsed unambiguously. A tag name cannot contain any of the

43 following characters:</para>

44 <itemizedlist>

45 <listitem><para>Colon (ASCII 58, <quote><literal>:</literal></quote>)</para>

46 </listitem>

47 <listitem><para>Carriage return (ASCII 13, <quote><literal>\r</literal></quote>)

48 </para>

49 </listitem>

50 <listitem><para>Newline (ASCII 10, <quote><literal>\n</literal></quote>)

51 </para>

52 </listitem></itemizedlist>

54 <para>You can use the <command role="hg-cmd">hg tags</command> command to display the tags present in

55 your repository. In the output, each tagged revision is identified

56 first by its name, then by revision number, and finally by the unique

57 hash of the revision.

58

59 Notice that <literal>tip</literal> is listed in the output of <command role="hg-cmd">hg tags</command>. The

60 <literal>tip</literal> tag is a special <quote>floating</quote> tag, which always

61 identifies the newest revision in the repository.

62 </para>

64 <para>In the output of the <command role="hg-cmd">hg tags</command> command, tags are listed in reverse

65 order, by revision number. This usually means that recent tags are

66 listed before older tags. It also means that <literal>tip</literal> is always

67 going to be the first tag listed in the output of <command role="hg-cmd">hg tags</command>.

68 </para>

70 <para>When you run <command role="hg-cmd">hg log</command>, if it displays a revision that has tags

71 associated with it, it will print those tags.

72

73 </para>

75 <para>Any time you need to provide a revision ID to a Mercurial command, the

76 command will accept a tag name in its place. Internally, Mercurial

77 will translate your tag name into the corresponding revision ID, then

78 use that.

79

80 </para>

82 <para>There's no limit on the number of tags you can have in a repository,

83 or on the number of tags that a single revision can have. As a

84 practical matter, it's not a great idea to have <quote>too many</quote> (a number

85 which will vary from project to project), simply because tags are

86 supposed to help you to find revisions. If you have lots of tags, the

87 ease of using them to identify revisions diminishes rapidly.

88 </para>

90 <para>For example, if your project has milestones as frequent as every few

91 days, it's perfectly reasonable to tag each one of those. But if you

92 have a continuous build system that makes sure every revision can be

93 built cleanly, you'd be introducing a lot of noise if you were to tag

94 every clean build. Instead, you could tag failed builds (on the

95 assumption that they're rare!), or simply not use tags to track

96 buildability.

97 </para>

99 <para>If you want to remove a tag that you no longer want, use

100 <command role="hg-cmd">hg tag --remove</command>.

101

102 You can also modify a tag at any time, so that it identifies a

103 different revision, by simply issuing a new <command role="hg-cmd">hg tag</command> command.

104 You'll have to use the <option role="hg-opt-tag">-f</option> option to tell Mercurial that

105 you <emphasis>really</emphasis> want to update the tag.

106

107 There will still be a permanent record of the previous identity of the

108 tag, but Mercurial will no longer use it. There's thus no penalty to

109 tagging the wrong revision; all you have to do is turn around and tag

110 the correct revision once you discover your error.

111 </para>

112

113 <para>Mercurial stores tags in a normal revision-controlled file in your

114 repository. If you've created any tags, you'll find them in a file

115 named <filename role="special">.hgtags</filename>. When you run the <command role="hg-cmd">hg tag</command> command,

116 Mercurial modifies this file, then automatically commits the change to

117 it. This means that every time you run <command role="hg-cmd">hg tag</command>, you'll see a

118 corresponding changeset in the output of <command role="hg-cmd">hg log</command>.

119

120 </para>

121

122 <sect2>

123 <title>Handling tag conflicts during a merge</title>

124

125 <para>You won't often need to care about the <filename role="special">.hgtags</filename> file, but

126 it sometimes makes its presence known during a merge. The format of

127 the file is simple: it consists of a series of lines. Each line

128 starts with a changeset hash, followed by a space, followed by the

129 name of a tag.

130 </para>

131

132 <para>If you're resolving a conflict in the <filename role="special">.hgtags</filename> file during

133 a merge, there's one twist to modifying the <filename role="special">.hgtags</filename> file:

134 when Mercurial is parsing the tags in a repository, it <emphasis>never</emphasis>

135 reads the working copy of the <filename role="special">.hgtags</filename> file. Instead, it

136 reads the <emphasis>most recently committed</emphasis> revision of the file.

137 </para>

138

139 <para>An unfortunate consequence of this design is that you can't actually

140 verify that your merged <filename role="special">.hgtags</filename> file is correct until

141 <emphasis>after</emphasis> you've committed a change. So if you find yourself

142 resolving a conflict on <filename role="special">.hgtags</filename> during a merge, be sure to

143 run <command role="hg-cmd">hg tags</command> after you commit. If it finds an error in the

144 <filename role="special">.hgtags</filename> file, it will report the location of the error,

145 which you can then fix and commit. You should then run <command role="hg-cmd">hg tags</command>

146 again, just to be sure that your fix is correct.

147 </para>

148

149 </sect2>

150 <sect2>

151 <title>Tags and cloning</title>

152

153 <para>You may have noticed that the <command role="hg-cmd">hg clone</command> command has a

154 <option role="hg-opt-clone">-r</option> option that lets you clone an exact copy of the

155 repository as of a particular changeset. The new clone will not

156 contain any project history that comes after the revision you

157 specified. This has an interaction with tags that can surprise the

158 unwary.

159 </para>

160

161 <para>Recall that a tag is stored as a revision to the <filename role="special">.hgtags</filename>

162 file, so that when you create a tag, the changeset in which it's

163 recorded necessarily refers to an older changeset. When you run

164 <command role="hg-cmd">hg clone -r foo</command> to clone a repository as of tag

165 <literal>foo</literal>, the new clone \emph{will not contain the history that

166 created the tag} that you used to clone the repository. The result

167 is that you'll get exactly the right subset of the project's history

168 in the new repository, but <emphasis>not</emphasis> the tag you might have expected.

169 </para>

170

171 </sect2>

172 <sect2>

173 <title>When permanent tags are too much</title>

174

175 <para>Since Mercurial's tags are revision controlled and carried around with

176 a project's history, everyone you work with will see the tags you

177 create. But giving names to revisions has uses beyond simply noting

178 that revision <literal>4237e45506ee</literal> is really <literal>v2.0.2</literal>. If

179 you're trying to track down a subtle bug, you might want a tag to

180 remind you of something like <quote>Anne saw the symptoms with this

181 revision</quote>.

182 </para>

183

184 <para>For cases like this, what you might want to use are <emphasis>local</emphasis> tags.

185 You can create a local tag with the <option role="hg-opt-tag">-l</option> option to the

186 <command role="hg-cmd">hg tag</command> command. This will store the tag in a file called

187 <filename role="special">.hg/localtags</filename>. Unlike <filename role="special">.hgtags</filename>,

188 <filename role="special">.hg/localtags</filename> is not revision controlled. Any tags you

189 create using <option role="hg-opt-tag">-l</option> remain strictly local to the repository

190 you're currently working in.

191 </para>

192

193 </sect2>

194 </sect1>

195 <sect1>

196 <title>The flow of changes&emdash;big picture vs. little</title>

197

198 <para>To return to the outline I sketched at the beginning of a chapter,

199 let's think about a project that has multiple concurrent pieces of

200 work under development at once.

201 </para>

202

203 <para>There might be a push for a new <quote>main</quote> release; a new minor bugfix

204 release to the last main release; and an unexpected <quote>hot fix</quote> to an

205 old release that is now in maintenance mode.

206 </para>

207

208 <para>The usual way people refer to these different concurrent directions of

209 development is as <quote>branches</quote>. However, we've already seen numerous

210 times that Mercurial treats <emphasis>all of history</emphasis> as a series of

211 branches and merges. Really, what we have here is two ideas that are

212 peripherally related, but which happen to share a name.

213 </para>

214 <itemizedlist>

215 <listitem><para><quote>Big picture</quote> branches represent the sweep of a project's

216 evolution; people give them names, and talk about them in

217 conversation.

218 </para>

219 </listitem>

220 <listitem><para><quote>Little picture</quote> branches are artefacts of the day-to-day

221 activity of developing and merging changes. They expose the

222 narrative of how the code was developed.

223 </para>

224 </listitem></itemizedlist>

225

226 </sect1>

227 <sect1>

228 <title>Managing big-picture branches in repositories</title>

229

230 <para>The easiest way to isolate a <quote>big picture</quote> branch in Mercurial is in

231 a dedicated repository. If you have an existing shared

232 repository&emdash;let's call it <literal>myproject</literal>&emdash;that reaches a <quote>1.0</quote>

233 milestone, you can start to prepare for future maintenance releases on

234 top of version 1.0 by tagging the revision from which you prepared

235 the 1.0 release.

236

237 You can then clone a new shared <literal>myproject-1.0.1</literal> repository as

238 of that tag.

239

240 </para>

241

242 <para>Afterwards, if someone needs to work on a bug fix that ought to go

243 into an upcoming 1.0.1 minor release, they clone the

244 <literal>myproject-1.0.1</literal> repository, make their changes, and push them

245 back.

246

247 Meanwhile, development for the next major release can continue,

248 isolated and unabated, in the <literal>myproject</literal> repository.

249

250 </para>

251

252 </sect1>

253 <sect1>

254 <title>Don't repeat yourself: merging across branches</title>

255

256 <para>In many cases, if you have a bug to fix on a maintenance branch, the

257 chances are good that the bug exists on your project's main branch

258 (and possibly other maintenance branches, too). It's a rare developer

259 who wants to fix the same bug multiple times, so let's look at a few

260 ways that Mercurial can help you to manage these bugfixes without

261 duplicating your work.

262 </para>

263

264 <para>In the simplest instance, all you need to do is pull changes from your

265 maintenance branch into your local clone of the target branch.

266

267 You'll then need to merge the heads of the two branches, and push back

268 to the main branch.

269

270 </para>

271

272 </sect1>

273 <sect1>

274 <title>Naming branches within one repository</title>

275

276 <para>In most instances, isolating branches in repositories is the right

277 approach. Its simplicity makes it easy to understand; and so it's

278 hard to make mistakes. There's a one-to-one relationship between

279 branches you're working in and directories on your system. This lets

280 you use normal (non-Mercurial-aware) tools to work on files within a

281 branch/repository.

282 </para>

283

284 <para>If you're more in the <quote>power user</quote> category (<emphasis>and</emphasis> your

285 collaborators are too), there is an alternative way of handling

286 branches that you can consider. I've already mentioned the

287 human-level distinction between <quote>small picture</quote> and <quote>big picture</quote>

288 branches. While Mercurial works with multiple <quote>small picture</quote>

289 branches in a repository all the time (for example after you pull

290 changes in, but before you merge them), it can <emphasis>also</emphasis> work with

291 multiple <quote>big picture</quote> branches.

292 </para>

293

294 <para>The key to working this way is that Mercurial lets you assign a

295 persistent <emphasis>name</emphasis> to a branch. There always exists a branch

296 named <literal>default</literal>. Even before you start naming branches

297 yourself, you can find traces of the <literal>default</literal> branch if you

298 look for them.

299 </para>

300

301 <para>As an example, when you run the <command role="hg-cmd">hg commit</command> command, and it pops up

302 your editor so that you can enter a commit message, look for a line

303 that contains the text <quote><literal>HG: branch default</literal></quote> at the bottom.

304 This is telling you that your commit will occur on the branch named

305 <literal>default</literal>.

306 </para>

307

308 <para>To start working with named branches, use the <command role="hg-cmd">hg branches</command>

309 command. This command lists the named branches already present in

310 your repository, telling you which changeset is the tip of each.

311

312 Since you haven't created any named branches yet, the only one that

313 exists is <literal>default</literal>.

314 </para>

315

316 <para>To find out what the <quote>current</quote> branch is, run the <command role="hg-cmd">hg branch</command>

317 command, giving it no arguments. This tells you what branch the

318 parent of the current changeset is on.

319

320 </para>

321

322 <para>To create a new branch, run the <command role="hg-cmd">hg branch</command> command again. This

323 time, give it one argument: the name of the branch you want to create.

324

325 </para>

326

327 <para>After you've created a branch, you might wonder what effect the

328 <command role="hg-cmd">hg branch</command> command has had. What do the <command role="hg-cmd">hg status</command> and

329 <command role="hg-cmd">hg tip</command> commands report?

330

331 Nothing has changed in the working directory, and there's been no new

332 history created. As this suggests, running the <command role="hg-cmd">hg branch</command> command

333 has no permanent effect; it only tells Mercurial what branch name to

334 use the <emphasis>next</emphasis> time you commit a changeset.

335 </para>

336

337 <para>When you commit a change, Mercurial records the name of the branch on

338 which you committed. Once you've switched from the <literal>default</literal>

339 branch to another and committed, you'll see the name of the new branch

340 show up in the output of <command role="hg-cmd">hg log</command>, <command role="hg-cmd">hg tip</command>, and other commands

341 that display the same kind of output.

342

343 The <command role="hg-cmd">hg log</command>-like commands will print the branch name of every

344 changeset that's not on the <literal>default</literal> branch. As a result, if

345 you never use named branches, you'll never see this information.

346 </para>

347

348 <para>Once you've named a branch and committed a change with that name,

349 every subsequent commit that descends from that change will inherit

350 the same branch name. You can change the name of a branch at any

351 time, using the <command role="hg-cmd">hg branch</command> command.

352

353 In practice, this is something you won't do very often, as branch

354 names tend to have fairly long lifetimes. (This isn't a rule, just an

355 observation.)

356 </para>

357

358 </sect1>

359 <sect1>

360 <title>Dealing with multiple named branches in a repository</title>

361

362 <para>If you have more than one named branch in a repository, Mercurial will

363 remember the branch that your working directory on when you start a

364 command like <command role="hg-cmd">hg update</command> or <command role="hg-cmd">hg pull -u</command>. It will update

365 the working directory to the tip of this branch, no matter what the

366 <quote>repo-wide</quote> tip is. To update to a revision that's on a different

367 named branch, you may need to use the <option role="hg-opt-update">-C</option> option to

368 <command role="hg-cmd">hg update</command>.

369 </para>

370

371 <para>This behaviour is a little subtle, so let's see it in action. First,

372 let's remind ourselves what branch we're currently on, and what

373 branches are in our repository.

374

375 We're on the <literal>bar</literal> branch, but there also exists an older

376 <command role="hg-cmd">hg foo</command> branch.

377 </para>

378

379 <para>We can <command role="hg-cmd">hg update</command> back and forth between the tips of the

380 <literal>foo</literal> and <literal>bar</literal> branches without needing to use the

381 <option role="hg-opt-update">-C</option> option, because this only involves going backwards

382 and forwards linearly through our change history.

383

384 </para>

385

386 <para>If we go back to the <literal>foo</literal> branch and then run <command role="hg-cmd">hg update</command>,

387 it will keep us on <literal>foo</literal>, not move us to the tip of

388 <literal>bar</literal>.

389

390 </para>

391

392 <para>Committing a new change on the <literal>foo</literal> branch introduces a new

393 head.

394

395 </para>

396

397 </sect1>

398 <sect1>

399 <title>Branch names and merging</title>

400

401 <para>As you've probably noticed, merges in Mercurial are not symmetrical.

402 Let's say our repository has two heads, 17 and 23. If I

403 <command role="hg-cmd">hg update</command> to 17 and then <command role="hg-cmd">hg merge</command> with 23, Mercurial records

404 17 as the first parent of the merge, and 23 as the second. Whereas if

405 I <command role="hg-cmd">hg update</command> to 23 and then <command role="hg-cmd">hg merge</command> with 17, it records 23

406 as the first parent, and 17 as the second.

407 </para>

408

409 <para>This affects Mercurial's choice of branch name when you merge. After

410 a merge, Mercurial will retain the branch name of the first parent

411 when you commit the result of the merge. If your first parent's

412 branch name is <literal>foo</literal>, and you merge with <literal>bar</literal>, the

413 branch name will still be <literal>foo</literal> after you merge.

414 </para>

415

416 <para>It's not unusual for a repository to contain multiple heads, each with

417 the same branch name. Let's say I'm working on the <literal>foo</literal>

418 branch, and so are you. We commit different changes; I pull your

419 changes; I now have two heads, each claiming to be on the <literal>foo</literal>

420 branch. The result of a merge will be a single head on the

421 <literal>foo</literal> branch, as you might hope.

422 </para>

423

424 <para>But if I'm working on the <literal>bar</literal> branch, and I merge work from

425 the <literal>foo</literal> branch, the result will remain on the <literal>bar</literal>

426 branch.

427

428 </para>

429

430 <para>To give a more concrete example, if I'm working on the

431 <literal>bleeding-edge</literal> branch, and I want to bring in the latest fixes

432 from the <literal>stable</literal> branch, Mercurial will choose the <quote>right</quote>

433 (<literal>bleeding-edge</literal>) branch name when I pull and merge from

434 <literal>stable</literal>.

435 </para>

436

437 </sect1>

438 <sect1>

439 <title>Branch naming is generally useful</title>

440

441 <para>You shouldn't think of named branches as applicable only to situations

442 where you have multiple long-lived branches cohabiting in a single

443 repository. They're very useful even in the one-branch-per-repository

444 case.

445 </para>

446

447 <para>In the simplest case, giving a name to each branch gives you a

448 permanent record of which branch a changeset originated on. This

449 gives you more context when you're trying to follow the history of a

450 long-lived branchy project.

451 </para>

452

453 <para>If you're working with shared repositories, you can set up a

454 <literal role="hook">pretxnchangegroup</literal> hook on each that will block incoming changes

455 that have the <quote>wrong</quote> branch name. This provides a simple, but

456 effective, defence against people accidentally pushing changes from a

457 <quote>bleeding edge</quote> branch to a <quote>stable</quote> branch. Such a hook might

458 look like this inside the shared repo's <filename role="special"> /.hgrc</filename>.

459 </para>

460 <programlisting>

461 <para> [hooks]

462 pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch

463 </para>

464 </programlisting>

465

466 </sect1>

467 </chapter>

468

469 <!--

470 local variables:

471 sgml-parent-document: ("00book.xml" "book" "chapter")

472 end:

473 -->