hgbook
view en/branch.tex @ 202:6f167e644762
Start writing about named branches.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Fri Apr 20 14:02:10 2007 -0700 (2007-04-20) |
| parents | 58e3a6c76725 |
| children | d7615e15510f |
line source
1 \chapter{Managing releases and branchy development}
2 \label{chap:branch}
4 Mercurial provides several mechanisms for you to manage a project that
5 is making progress on multiple fronts at once. To understand these
6 mechanisms, let's first take a brief look at a fairly normal software
7 project structure.
9 Many software projects issue periodic ``major'' releases that contain
10 substantial new features. In parallel, they may issue ``minor''
11 releases. These are usually identical to the major releases off which
12 they're based, but with a few bugs fixed.
14 In this chapter, we'll start by talking about how to keep records of
15 project milestones such as releases. We'll then continue on to talk
16 about the flow of work between different phases of a project, and how
17 Mercurial can help you to isolate and manage this work.
19 \section{Giving a persistent name to a revision}
21 Once you decide that you'd like to call a particular revision a
22 ``release'', it's a good idea to record the identity of that revision.
23 This will let you reproduce that release at a later date, for whatever
24 purpose you might need at the time (reproducing a bug, porting to a
25 new platform, etc).
26 \interaction{tag.init}
28 Mercurial lets you give a permanent name to any revision using the
29 \hgcmd{tag} command. Not surprisingly, these names are called
30 ``tags''.
31 \interaction{tag.tag}
33 A tag is nothing more than a ``symbolic name'' for a revision. Tags
34 exist purely for your convenience, so that you have a handy permanent
35 way to refer to a revision; Mercurial doesn't interpret the tag names
36 you use in any way. Neither does Mercurial place any restrictions on
37 the name of a tag, beyond a few that are necessary to ensure that a
38 tag can be parsed unambiguously. A tag name cannot contain any of the
39 following characters:
40 \begin{itemize}
41 \item Colon (ASCII 58, ``\texttt{:}'')
42 \item Carriage return (ASCII 13, ``\texttt{$\backslash$r}'')
43 \item Newline (ASCII 10, ``\texttt{$\backslash$n}'')
44 \end{itemize}
46 You can use the \hgcmd{tags} command to display the tags present in
47 your repository. In the output, each tagged revision is identified
48 first by its name, then by revision number, and finally by the unique
49 hash of the revision.
50 \interaction{tag.tags}
51 Notice that \texttt{tip} is listed in the output of \hgcmd{tags}. The
52 \texttt{tip} tag is a special ``floating'' tag, which always
53 identifies the newest revision in the repository.
55 In the output of the \hgcmd{tags} command, tags are listed in reverse
56 order, by revision number. This usually means that recent tags are
57 listed before older tags. It also means that \texttt{tip} is always
58 going to be the first tag listed in the output of \hgcmd{tags}.
60 When you run \hgcmd{log}, if it displays a revision that has tags
61 associated with it, it will print those tags.
62 \interaction{tag.log}
64 Any time you need to provide a revision~ID to a Mercurial command, the
65 command will accept a tag name in its place. Internally, Mercurial
66 will translate your tag name into the corresponding revision~ID, then
67 use that.
68 \interaction{tag.log.v1.0}
70 There's no limit on the number of tags you can have in a repository,
71 or on the number of tags that a single revision can have. As a
72 practical matter, it's not a great idea to have ``too many'' (a number
73 which will vary from project to project), simply because tags are
74 supposed to help you to find revisions. If you have lots of tags, the
75 ease of using them to identify revisions diminishes rapidly.
77 For example, if your project has milestones as frequent as every few
78 days, it's perfectly reasonable to tag each one of those. But if you
79 have a continuous build system that makes sure every revision can be
80 built cleanly, you'd be introducing a lot of noise if you were to tag
81 every clean build. Instead, you could tag failed builds (on the
82 assumption that they're rare!), or simply not use tags to track
83 buildability.
85 If you want to remove a tag that you no longer want, use
86 \hgcmdargs{tag}{--remove}.
87 \interaction{tag.remove}
88 You can also modify a tag at any time, so that it identifies a
89 different revision, by simply issuing a new \hgcmd{tag} command.
90 You'll have to use the \hgopt{tag}{-f} option to tell Mercurial that
91 you \emph{really} want to update the tag.
92 \interaction{tag.replace}
93 There will still be a permanent record of the previous identity of the
94 tag, but Mercurial will no longer use it. There's thus no penalty to
95 tagging the wrong revision; all you have to do is turn around and tag
96 the correct revision once you discover your error.
98 Mercurial stores tags in a normal revision-controlled file in your
99 repository. If you've created any tags, you'll find them in a file
100 named \sfilename{.hgtags}. When you run the \hgcmd{tag} command,
101 Mercurial modifies this file, then automatically commits the change to
102 it. This means that every time you run \hgcmd{tag}, you'll see a
103 corresponding changeset in the output of \hgcmd{log}.
104 \interaction{tag.tip}
106 \subsection{Handling tag conflicts during a merge}
108 You won't often need to care about the \sfilename{.hgtags} file, but
109 it sometimes makes its presence known during a merge. The format of
110 the file is simple: it consists of a series of lines. Each line
111 starts with a changeset hash, followed by a space, followed by the
112 name of a tag.
114 If you're resolving a conflict in the \sfilename{.hgtags} file during
115 a merge, there's one twist to modifying the \sfilename{.hgtags} file:
116 when Mercurial is parsing the tags in a repository, it \emph{never}
117 reads the working copy of the \sfilename{.hgtags} file. Instead, it
118 reads the \emph{most recently committed} revision of the file.
120 An unfortunate consequence of this design is that you can't actually
121 verify that your merged \sfilename{.hgtags} file is correct until
122 \emph{after} you've committed a change. So if you find yourself
123 resolving a conflict on \sfilename{.hgtags} during a merge, be sure to
124 run \hgcmd{tags} after you commit. If it finds an error in the
125 \sfilename{.hgtags} file, it will report the location of the error,
126 which you can then fix and commit. You should then run \hgcmd{tags}
127 again, just to be sure that your fix is correct.
129 \subsection{Tags and cloning}
131 You may have noticed that the \hgcmd{clone} command has a
132 \hgopt{clone}{-r} option that lets you clone an exact copy of
133 repository as of a particular changeset. The new clone will not
134 contain any project history that comes after the revision you
135 specified. This has an interaction with tags that can surprise the
136 unwary.
138 Recall that a tag is stored as a revision to the \sfilename{.hgtags}
139 file, so that when you create a tag, the changeset in which it's
140 recorded necessarily refers to an older changeset. When you run
141 \hgcmdargs{clone}{-r foo} to clone a repository as of tag
142 \texttt{foo}, the new clone \emph{will not contain the history that
143 created the tag} that you used to clone the repository. The result
144 is that you'll get exactly the right subset of the project's history
145 in the new repository, but \emph{not} the tag you might have expected.
147 \subsection{When permanent tags are too much}
149 Since Mercurial's tags are revision controlled and carried around with
150 a project's history, everyone you work with will see the tags you
151 create. But giving names to revisions has uses beyond simply noting
152 that revision \texttt{4237e45506ee} is really \texttt{v2.0.2}. If
153 you're trying to track down a subtle bug, you might want a tag to
154 remind you of something like ``Anne saw the symptoms with this
155 revision''.
157 For cases like this, what you might want to use are \emph{local} tags.
158 You can create a local tag with the \hgopt{tag}{-l} option to the
159 \hgcmd{tag} command. This will store the tag in a file called
160 \sfilename{.hg/localtags}. Unlike \sfilename{.hgtags},
161 \sfilename{.hg/localtags} is not revision controlled. Any tags you
162 create using \hgopt{tag}{-l} remain strictly local to the repository
163 you're currently working in.
165 \section{The flow of changes---big picture vs. little}
167 To return to the outline I sketched at the beginning of a chapter,
168 let's think about a project that has multiple concurrent pieces of
169 work under development at once.
171 There might be a push for a new ``main'' release; a new minor bugfix
172 release to the last main release; and an unexpected ``hot fix'' to an
173 old release that is now in maintenance mode.
175 The usual way people refer to these different concurrent directions of
176 development is as ``branches''. However, we've already seen numerous
177 times that Mercurial treats \emph{all of history} as a series of
178 branches and merges. Really, what we have here is two ideas that are
179 peripherally related, but which happen to share a name.
180 \begin{itemize}
181 \item ``Big picture'' branches represent the sweep of a project's
182 evolution; people give them names, and talk about them in
183 conversation.
184 \item ``Little picture'' branches are artefacts of the day-to-day
185 activity of developing and merging changes. They expose the
186 narrative of how the code was developed.
187 \end{itemize}
189 \section{Managing big-picture branches in repositories}
191 The easiest way to isolate a ``big picture'' branch in Mercurial is in
192 a dedicated repository. If you have an existing shared
193 repository---let's call it \texttt{myproject}---that reaches a ``1.0''
194 milestone, you can start to prepare for future maintenance releases on
195 top of version~1.0 by tagging the revision from which you prepared
196 the~1.0 release.
197 \interaction{branch-repo.tag}
198 You can then clone a new shared \texttt{myproject-1.0.1} repository as
199 of that tag.
200 \interaction{branch-repo.clone}
202 Afterwards, if someone needs to work on a bug fix that ought to go
203 into an upcoming~1.0.1 minor release, they clone the
204 \texttt{myproject-1.0.1} repository, make their changes, and push them
205 back.
206 \interaction{branch-repo.bugfix}
207 Meanwhile, development for the next major release can continue,
208 isolated and unabated, in the \texttt{myproject} repository.
209 \interaction{branch-repo.new}
211 \section{Don't repeat yourself: merging across branches}
213 In many cases, if you have a bug to fix on a maintenance branch, the
214 chances are good that the bug exists on your project's main branch
215 (and possibly other maintenance branches, too). It's a rare developer
216 who wants to fix the same bug multiple times, so let's look at a few
217 ways that Mercurial can help you to manage these bugfixes without
218 duplicating your work.
220 In the simplest instance, all you need to do is pull changes from your
221 maintenance branch into your local clone of the target branch.
222 \interaction{branch-repo.pull}
223 You'll then need to merge the heads of the two branches, and push back
224 to the main branch.
225 \interaction{branch-repo.merge}
227 \section{Naming branches within one repository}
229 In most instances, isolating branches in repositories is the right
230 approach. Its simplicity makes it easy to understand; and so it's
231 hard to make mistakes. There's a one-to-one relationship between
232 branches you're working in and directories on your system. This lets
233 you use normal (non-Mercurial-aware) tools to work on files within a
234 branch/repository.
236 If you're more in the ``power user'' category (\emph{and} your
237 collaborators are too), there is an alternative way of handling
238 branches that you can consider. I've already mentioned the
239 human-level distinction between ``small picture'' and ``big picture''
240 branches. While Mercurial works with multiple ``small picture''
241 branches in a repository all the time (for example after you pull
242 changes in, but before you merge them), it can \emph{also} work with
243 multiple ``big picture'' branches.
245 The key to working this way is that Mercurial lets you assign a
246 persistent \emph{name} to a branch. There always exists a branch
247 named \texttt{default}. Even before you start naming branches
248 yourself, you can find traces of the \texttt{default} branch if you
249 look for them.
251 As an example, when you run the \hgcmd{commit} command, and it pops up
252 your editor so that you can enter a commit message, look for a line
253 that contains the text ``\texttt{HG: branch default}'' at the bottom.
254 This is telling you that your commit will occur on the branch named
255 \texttt{default}.
257 To start working with named branches, use the \hgcmd{branches}
258 command. This command lists the named branches already present in
259 your repository.
260 \interaction{branch-named.branches}
262 %%% Local Variables:
263 %%% mode: latex
264 %%% TeX-master: "00book"
265 %%% End: