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