1.1 --- a/en/branch.tex	Mon Apr 16 16:11:24 2007 -0700
     1.2 +++ b/en/branch.tex	Mon Apr 16 16:33:51 2007 -0700
     1.3 @@ -1,15 +1,21 @@
     1.4  \chapter{Managing releases and branchy development}
     1.5  \label{chap:branch}
     1.6  
     1.7 -Mercurial provides two ways for you to manage a project that is making
     1.8 -progress on multiple fronts at once.  To understand these mechanisms,
     1.9 -let's first take a look at a fairly normal software project structure.
    1.10 +Mercurial provides several mechanisms for you to manage a project that
    1.11 +is making progress on multiple fronts at once.  To understand these
    1.12 +mechanisms, let's first take a brief look at a fairly normal software
    1.13 +project structure.
    1.14  
    1.15  Many software projects issue periodic ``major'' releases that contain
    1.16  substantial new features.  In parallel, they may issue ``minor''
    1.17  releases.  These are usually identical to the major releases off which
    1.18  they're based, but with a few bugs fixed.
    1.19  
    1.20 +In this chapter, we'll start by talking about how to keep records of
    1.21 +project milestones such as releases.  We'll then continue on to talk
    1.22 +about the flow of work between different phases of a project, and how
    1.23 +Mercurial can help you to isolate and manage this work.
    1.24 +
    1.25  \section{Giving a persistent name to a revision}
    1.26  
    1.27  Once you decide that you'd like to call a particular revision a
    1.28 @@ -85,7 +91,9 @@
    1.29  you \emph{really} want to update the tag.
    1.30  \interaction{tag.replace}
    1.31  There will still be a permanent record of the previous identity of the
    1.32 -tag, but Mercurial will no longer use it.
    1.33 +tag, but Mercurial will no longer use it.  There's thus no penalty to
    1.34 +tagging the wrong revision; all you have to do is turn around and tag
    1.35 +the correct revision once you discover your error.
    1.36  
    1.37  Mercurial stores tags in a normal revision-controlled file in your
    1.38  repository.  If you've created any tags, you'll find them in a file
    1.39 @@ -118,6 +126,25 @@
    1.40  which you can then fix and commit.  You should then run \hgcmd{tags}
    1.41  again, just to be sure that your fix is correct.
    1.42  
    1.43 +\subsection{When permanent tags are too much}
    1.44 +
    1.45 +Since Mercurial's tags are revision controlled and carried around with
    1.46 +a project's history, everyone you work with will see the tags you
    1.47 +create.  But giving names to revisions has uses beyond simply noting
    1.48 +that revision \texttt{4237e45506ee} is really \texttt{v2.0.2}.  If
    1.49 +you're trying to track down a subtle bug, you might want a tag to
    1.50 +remind you of something like ``Anne saw the symptoms with this
    1.51 +revision''.
    1.52 +
    1.53 +For cases like this, what you might want to use are \emph{local} tags.
    1.54 +You can create a local tag with the \hgopt{tag}{-l} option to the
    1.55 +\hgcmd{tag} command.  This will store the tag in a file called
    1.56 +\sfilename{.hg/localtags}.  Unlike \sfilename{.hgtags},
    1.57 +\sfilename{.hg/localtags} is not revision controlled.  Any tags you
    1.58 +create using \hgopt{tag}{-l} remain strictly local to the repository
    1.59 +you're currently working in.
    1.60 +
    1.61 +
    1.62  %%% Local Variables: 
    1.63  %%% mode: latex
    1.64  %%% TeX-master: "00book"