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