hgbook
view en/branch.tex @ 196:4237e45506ee
Add early material describing tags.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Mon Apr 16 16:11:24 2007 -0700 (2007-04-16) |
| parents | b60e2de6dbc3 |
| children | 76697ae503db |
line source
1 \chapter{Managing releases and branchy development}
2 \label{chap:branch}
4 Mercurial provides two ways for you to manage a project that is making
5 progress on multiple fronts at once. To understand these mechanisms,
6 let's first take a look at a fairly normal software project structure.
8 Many software projects issue periodic ``major'' releases that contain
9 substantial new features. In parallel, they may issue ``minor''
10 releases. These are usually identical to the major releases off which
11 they're based, but with a few bugs fixed.
13 \section{Giving a persistent name to a revision}
15 Once you decide that you'd like to call a particular revision a
16 ``release'', it's a good idea to record the identity of that revision.
17 This will let you reproduce that release at a later date, for whatever
18 purpose you might need at the time (reproducing a bug, porting to a
19 new platform, etc).
20 \interaction{tag.init}
22 Mercurial lets you give a permanent name to any revision using the
23 \hgcmd{tag} command. Not surprisingly, these names are called
24 ``tags''.
25 \interaction{tag.tag}
27 A tag is nothing more than a ``symbolic name'' for a revision. Tags
28 exist purely for your convenience, so that you have a handy permanent
29 way to refer to a revision; Mercurial doesn't interpret the tag names
30 you use in any way. Neither does Mercurial place any restrictions on
31 the name of a tag, beyond a few that are necessary to ensure that a
32 tag can be parsed unambiguously. A tag name cannot contain any of the
33 following characters:
34 \begin{itemize}
35 \item Colon (ASCII 58, ``\texttt{:}'')
36 \item Carriage return (ASCII 13, ``\texttt{$\backslash$r}'')
37 \item Newline (ASCII 10, ``\texttt{$\backslash$n}'')
38 \end{itemize}
40 You can use the \hgcmd{tags} command to display the tags present in
41 your repository. In the output, each tagged revision is identified
42 first by its name, then by revision number, and finally by the unique
43 hash of the revision.
44 \interaction{tag.tags}
45 Notice that \texttt{tip} is listed in the output of \hgcmd{tags}. The
46 \texttt{tip} tag is a special ``floating'' tag, which always
47 identifies the newest revision in the repository.
49 In the output of the \hgcmd{tags} command, tags are listed in reverse
50 order, by revision number. This usually means that recent tags are
51 listed before older tags. It also means that \texttt{tip} is always
52 going to be the first tag listed in the output of \hgcmd{tags}.
54 When you run \hgcmd{log}, if it displays a revision that has tags
55 associated with it, it will print those tags.
56 \interaction{tag.log}
58 Any time you need to provide a revision~ID to a Mercurial command, the
59 command will accept a tag name in its place. Internally, Mercurial
60 will translate your tag name into the corresponding revision~ID, then
61 use that.
62 \interaction{tag.log.v1.0}
64 There's no limit on the number of tags you can have in a repository,
65 or on the number of tags that a single revision can have. As a
66 practical matter, it's not a great idea to have ``too many'' (a number
67 which will vary from project to project), simply because tags are
68 supposed to help you to find revisions. If you have lots of tags, the
69 ease of using them to identify revisions diminishes rapidly.
71 For example, if your project has milestones as frequent as every few
72 days, it's perfectly reasonable to tag each one of those. But if you
73 have a continuous build system that makes sure every revision can be
74 built cleanly, you'd be introducing a lot of noise if you were to tag
75 every clean build. Instead, you could tag failed builds (on the
76 assumption that they're rare!), or simply not use tags to track
77 buildability.
79 If you want to remove a tag that you no longer want, use
80 \hgcmdargs{tag}{--remove}.
81 \interaction{tag.remove}
82 You can also modify a tag at any time, so that it identifies a
83 different revision, by simply issuing a new \hgcmd{tag} command.
84 You'll have to use the \hgopt{tag}{-f} option to tell Mercurial that
85 you \emph{really} want to update the tag.
86 \interaction{tag.replace}
87 There will still be a permanent record of the previous identity of the
88 tag, but Mercurial will no longer use it.
90 Mercurial stores tags in a normal revision-controlled file in your
91 repository. If you've created any tags, you'll find them in a file
92 named \sfilename{.hgtags}. When you run the \hgcmd{tag} command,
93 Mercurial modifies this file, then automatically commits the change to
94 it. This means that every time you run \hgcmd{tag}, you'll see a
95 corresponding changeset in the output of \hgcmd{log}.
96 \interaction{tag.tip}
98 \subsection{Handling tag conflicts during a merge}
100 You won't often need to care about the \sfilename{.hgtags} file, but
101 it sometimes makes its presence known during a merge. The format of
102 the file is simple: it consists of a series of lines. Each line
103 starts with a changeset hash, followed by a space, followed by the
104 name of a tag.
106 If you're resolving a conflict in the \sfilename{.hgtags} file during
107 a merge, there's one twist to modifying the \sfilename{.hgtags} file:
108 when Mercurial is parsing the tags in a repository, it \emph{never}
109 reads the working copy of the \sfilename{.hgtags} file. Instead, it
110 reads the \emph{most recently committed} revision of the file.
112 An unfortunate consequence of this design is that you can't actually
113 verify that your merged \sfilename{.hgtags} file is correct until
114 \emph{after} you've committed a change. So if you find yourself
115 resolving a conflict on \sfilename{.hgtags} during a merge, be sure to
116 run \hgcmd{tags} after you commit. If it finds an error in the
117 \sfilename{.hgtags} file, it will report the location of the error,
118 which you can then fix and commit. You should then run \hgcmd{tags}
119 again, just to be sure that your fix is correct.
121 %%% Local Variables:
122 %%% mode: latex
123 %%% TeX-master: "00book"
124 %%% End: