changeset 197:76697ae503db

Local branches.

--- a/en/branch.tex	Mon Apr 16 16:11:24 2007 -0700
+++ b/en/branch.tex	Mon Apr 16 16:33:51 2007 -0700
@@ -1,15 +1,21 @@
 \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.
+Mercurial provides several mechanisms for you to manage a project that
+is making progress on multiple fronts at once.  To understand these
+mechanisms, let's first take a brief 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.
 
+In this chapter, we'll start by talking about how to keep records of
+project milestones such as releases.  We'll then continue on to talk
+about the flow of work between different phases of a project, and how
+Mercurial can help you to isolate and manage this work.
+
 \section{Giving a persistent name to a revision}
 
 Once you decide that you'd like to call a particular revision a
@@ -85,7 +91,9 @@
 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.
+tag, but Mercurial will no longer use it.  There's thus no penalty to
+tagging the wrong revision; all you have to do is turn around and tag
+the correct revision once you discover your error.
 
 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
@@ -118,6 +126,25 @@
 which you can then fix and commit.  You should then run \hgcmd{tags}
 again, just to be sure that your fix is correct.
 
+\subsection{When permanent tags are too much}
+
+Since Mercurial's tags are revision controlled and carried around with
+a project's history, everyone you work with will see the tags you
+create.  But giving names to revisions has uses beyond simply noting
+that revision \texttt{4237e45506ee} is really \texttt{v2.0.2}.  If
+you're trying to track down a subtle bug, you might want a tag to
+remind you of something like ``Anne saw the symptoms with this
+revision''.
+
+For cases like this, what you might want to use are \emph{local} tags.
+You can create a local tag with the \hgopt{tag}{-l} option to the
+\hgcmd{tag} command.  This will store the tag in a file called
+\sfilename{.hg/localtags}.  Unlike \sfilename{.hgtags},
+\sfilename{.hg/localtags} is not revision controlled.  Any tags you
+create using \hgopt{tag}{-l} remain strictly local to the repository
+you're currently working in.
+
+
 %%% Local Variables: 
 %%% mode: latex
 %%% TeX-master: "00book"