1.1 --- a/en/Makefile	Mon Apr 16 16:33:51 2007 -0700
     1.2 +++ b/en/Makefile	Mon Apr 16 17:21:38 2007 -0700
     1.3 @@ -56,6 +56,7 @@
     1.4  	backout \
     1.5  	bisect \
     1.6  	branching \
     1.7 +	branch-repo \
     1.8  	cmdref \
     1.9  	daily.copy \
    1.10  	daily.files \

     2.1 --- a/en/branch.tex	Mon Apr 16 16:33:51 2007 -0700
     2.2 +++ b/en/branch.tex	Mon Apr 16 17:21:38 2007 -0700
     2.3 @@ -126,6 +126,24 @@
     2.4  which you can then fix and commit.  You should then run \hgcmd{tags}
     2.5  again, just to be sure that your fix is correct.
     2.6  
     2.7 +\subsection{Tags and cloning}
     2.8 +
     2.9 +You may have noticed that the \hgcmd{clone} command has a
    2.10 +\hgopt{clone}{-r} option that lets you clone an exact copy of
    2.11 +repository as of a particular changeset.  The new clone will not
    2.12 +contain any project history that comes after the revision you
    2.13 +specified.  This has an interaction with tags that can surprise the
    2.14 +unwary.
    2.15 +
    2.16 +Recall that a tag is stored as a revision to the \sfilename{.hgtags}
    2.17 +file, so that when you create a tag, the changeset in which it's
    2.18 +recorded necessarily refers to an older changeset.  When you run
    2.19 +\hgcmdargs{clone}{-r foo} to clone a repository as of tag
    2.20 +\texttt{foo}, the new clone \emph{will not contain the history that
    2.21 +  created the tag} that you used to clone the repository.  The result
    2.22 +is that you'll get exactly the right subset of the project's history
    2.23 +in the new repository, but \emph{not} the tag you might have expected.
    2.24 +
    2.25  \subsection{When permanent tags are too much}
    2.26  
    2.27  Since Mercurial's tags are revision controlled and carried around with
    2.28 @@ -144,6 +162,53 @@
    2.29  create using \hgopt{tag}{-l} remain strictly local to the repository
    2.30  you're currently working in.
    2.31  
    2.32 +\section{The flow of changes---big picture vs. little}
    2.33 +
    2.34 +To return to the outline I sketched at the beginning of a chapter,
    2.35 +let's think about a project that has multiple concurrent pieces of
    2.36 +work under development at once.
    2.37 +
    2.38 +There might be a push for a new ``main'' release; a new minor bugfix
    2.39 +release to the last main release; and an unexpected ``hot fix'' to an
    2.40 +old release that is now in maintenance mode.
    2.41 +
    2.42 +The usual way people refer to these different concurrent directions of
    2.43 +development is as ``branches''.  However, we've already seen numerous
    2.44 +times that Mercurial treats \emph{all of history} as a series of
    2.45 +branches and merges.  Really, what we have here is two ideas that are
    2.46 +peripherally related, but which happen to share a name.
    2.47 +\begin{itemize}
    2.48 +\item ``Big picture'' branches represent the sweep of a project's
    2.49 +  evolution; people give them names, and talk about them in
    2.50 +  conversation.
    2.51 +\item ``Little picture'' branches are artefacts of the day-to-day
    2.52 +  activity of developing and merging changes.  They expose the
    2.53 +  narrative of how the code was developed.
    2.54 +\end{itemize}
    2.55 +
    2.56 +\section{Managing big-picture branches in repositories}
    2.57 +
    2.58 +The easiest way to isolate a ``big picture'' branch in Mercurial is in
    2.59 +a dedicated repository.  If you have an existing shared
    2.60 +repository---let's call it \texttt{myproject}---that reaches a ``1.0''
    2.61 +milestone, you can start to prepare for future maintenance releases on
    2.62 +top of version~1.0 by tagging the revision from which you prepared
    2.63 +the~1.0 release.
    2.64 +\interaction{branch-repo.tag}
    2.65 +You can then clone a new shared \texttt{myproject-1.0.1} repository as
    2.66 +of that tag.
    2.67 +\interaction{branch-repo.clone}
    2.68 +
    2.69 +Afterwards, if someone needs to work on a bug fix that ought to go
    2.70 +into an upcoming~1.0.1 minor release, they clone the
    2.71 +\texttt{myproject-1.0.1} repository, make their changes, and push them
    2.72 +back.
    2.73 +\interaction{branch-repo.bugfix}
    2.74 +Meanwhile, development for the next major release can continue,
    2.75 +isolated and unabated, in the \texttt{myproject} repository.
    2.76 +\interaction{branch-repo.new}
    2.77 +
    2.78 +
    2.79  
    2.80  %%% Local Variables: 
    2.81  %%% mode: latex

     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/en/examples/branch-repo	Mon Apr 16 17:21:38 2007 -0700
     3.3 @@ -0,0 +1,35 @@
     3.4 +#!/bin/bash
     3.5 +
     3.6 +hg init myproject
     3.7 +cd myproject
     3.8 +echo hello > myfile
     3.9 +hg commit -A -m 'Initial commit'
    3.10 +cd ..
    3.11 +
    3.12 +#$ name: tag
    3.13 +
    3.14 +cd myproject
    3.15 +hg tag v1.0
    3.16 +
    3.17 +#$ name: clone
    3.18 +
    3.19 +cd ..
    3.20 +hg clone myproject myproject-1.0.1
    3.21 +
    3.22 +#$ name: bugfix
    3.23 +
    3.24 +hg clone myproject-1.0.1 my-1.0.1-bugfix
    3.25 +cd my-1.0.1-bugfix
    3.26 +echo 'I fixed a bug using only echo!' >> myfile
    3.27 +hg commit -m 'Important fix for 1.0.1'
    3.28 +#$ ignore: /tmp/branch-repo.*
    3.29 +hg push
    3.30 +
    3.31 +#$ name: new
    3.32 +
    3.33 +cd ..
    3.34 +hg clone myproject my-feature
    3.35 +cd my-feature
    3.36 +echo "I'm adding a new feature with my mind!" > mynewfile
    3.37 +hg commit -A -m 'New feature'
    3.38 +

     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/en/examples/branch-repo.bugfix.out	Mon Apr 16 17:21:38 2007 -0700
     4.3 @@ -0,0 +1,12 @@
     4.4 +$ \textbf{hg clone myproject-1.0.1 my-1.0.1-bugfix}
     4.5 +2 files updated, 0 files merged, 0 files removed, 0 files unresolved
     4.6 +$ \textbf{cd my-1.0.1-bugfix}
     4.7 +$ \textbf{echo 'I fixed a bug using only echo!' >> myfile}
     4.8 +$ \textbf{hg commit -m 'Important fix for 1.0.1'}
     4.9 +$ \textbf{hg push}
    4.10 +pushing to /tmp/branch-repo4rF-PL/myproject-1.0.1
    4.11 +searching for changes
    4.12 +adding changesets
    4.13 +adding manifests
    4.14 +adding file changes
    4.15 +added 1 changesets with 1 changes to 1 files

     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/en/examples/branch-repo.clone.out	Mon Apr 16 17:21:38 2007 -0700
     5.3 @@ -0,0 +1,3 @@
     5.4 +$ \textbf{cd ..}
     5.5 +$ \textbf{hg clone myproject myproject-1.0.1}
     5.6 +2 files updated, 0 files merged, 0 files removed, 0 files unresolved

     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/en/examples/branch-repo.new.out	Mon Apr 16 17:21:38 2007 -0700
     6.3 @@ -0,0 +1,8 @@
     6.4 +$ \textbf{cd ..}
     6.5 +$ \textbf{hg clone myproject my-feature}
     6.6 +2 files updated, 0 files merged, 0 files removed, 0 files unresolved
     6.7 +$ \textbf{cd my-feature}
     6.8 +$ \textbf{echo "I'm adding a new feature with my mind!" > mynewfile}
     6.9 +bash: !": event not found
    6.10 +$ \textbf{hg commit -A -m 'New feature'}
    6.11 +nothing changed

     7.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.2 +++ b/en/examples/branch-repo.tag.out	Mon Apr 16 17:21:38 2007 -0700
     7.3 @@ -0,0 +1,2 @@
     7.4 +$ \textbf{cd myproject}
     7.5 +$ \textbf{hg tag v1.0}