changeset 198:615f3c6b30e1

Start to describe branch management.

--- a/en/Makefile	Mon Apr 16 16:33:51 2007 -0700
+++ b/en/Makefile	Mon Apr 16 17:21:38 2007 -0700
@@ -56,6 +56,7 @@
 	backout \
 	bisect \
 	branching \
+	branch-repo \
 	cmdref \
 	daily.copy \
 	daily.files \

--- a/en/branch.tex	Mon Apr 16 16:33:51 2007 -0700
+++ b/en/branch.tex	Mon Apr 16 17:21:38 2007 -0700
@@ -126,6 +126,24 @@
 which you can then fix and commit.  You should then run \hgcmd{tags}
 again, just to be sure that your fix is correct.
 
+\subsection{Tags and cloning}
+
+You may have noticed that the \hgcmd{clone} command has a
+\hgopt{clone}{-r} option that lets you clone an exact copy of
+repository as of a particular changeset.  The new clone will not
+contain any project history that comes after the revision you
+specified.  This has an interaction with tags that can surprise the
+unwary.
+
+Recall that a tag is stored as a revision to the \sfilename{.hgtags}
+file, so that when you create a tag, the changeset in which it's
+recorded necessarily refers to an older changeset.  When you run
+\hgcmdargs{clone}{-r foo} to clone a repository as of tag
+\texttt{foo}, the new clone \emph{will not contain the history that
+  created the tag} that you used to clone the repository.  The result
+is that you'll get exactly the right subset of the project's history
+in the new repository, but \emph{not} the tag you might have expected.
+
 \subsection{When permanent tags are too much}
 
 Since Mercurial's tags are revision controlled and carried around with
@@ -144,6 +162,53 @@
 create using \hgopt{tag}{-l} remain strictly local to the repository
 you're currently working in.
 
+\section{The flow of changes---big picture vs. little}
+
+To return to the outline I sketched at the beginning of a chapter,
+let's think about a project that has multiple concurrent pieces of
+work under development at once.
+
+There might be a push for a new ``main'' release; a new minor bugfix
+release to the last main release; and an unexpected ``hot fix'' to an
+old release that is now in maintenance mode.
+
+The usual way people refer to these different concurrent directions of
+development is as ``branches''.  However, we've already seen numerous
+times that Mercurial treats \emph{all of history} as a series of
+branches and merges.  Really, what we have here is two ideas that are
+peripherally related, but which happen to share a name.
+\begin{itemize}
+\item ``Big picture'' branches represent the sweep of a project's
+  evolution; people give them names, and talk about them in
+  conversation.
+\item ``Little picture'' branches are artefacts of the day-to-day
+  activity of developing and merging changes.  They expose the
+  narrative of how the code was developed.
+\end{itemize}
+
+\section{Managing big-picture branches in repositories}
+
+The easiest way to isolate a ``big picture'' branch in Mercurial is in
+a dedicated repository.  If you have an existing shared
+repository---let's call it \texttt{myproject}---that reaches a ``1.0''
+milestone, you can start to prepare for future maintenance releases on
+top of version~1.0 by tagging the revision from which you prepared
+the~1.0 release.
+\interaction{branch-repo.tag}
+You can then clone a new shared \texttt{myproject-1.0.1} repository as
+of that tag.
+\interaction{branch-repo.clone}
+
+Afterwards, if someone needs to work on a bug fix that ought to go
+into an upcoming~1.0.1 minor release, they clone the
+\texttt{myproject-1.0.1} repository, make their changes, and push them
+back.
+\interaction{branch-repo.bugfix}
+Meanwhile, development for the next major release can continue,
+isolated and unabated, in the \texttt{myproject} repository.
+\interaction{branch-repo.new}
+
+
 
 %%% Local Variables: 
 %%% mode: latex

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/en/examples/branch-repo	Mon Apr 16 17:21:38 2007 -0700
@@ -0,0 +1,35 @@
+#!/bin/bash
+
+hg init myproject
+cd myproject
+echo hello > myfile
+hg commit -A -m 'Initial commit'
+cd ..
+
+#$ name: tag
+
+cd myproject
+hg tag v1.0
+
+#$ name: clone
+
+cd ..
+hg clone myproject myproject-1.0.1
+
+#$ name: bugfix
+
+hg clone myproject-1.0.1 my-1.0.1-bugfix
+cd my-1.0.1-bugfix
+echo 'I fixed a bug using only echo!' >> myfile
+hg commit -m 'Important fix for 1.0.1'
+#$ ignore: /tmp/branch-repo.*
+hg push
+
+#$ name: new
+
+cd ..
+hg clone myproject my-feature
+cd my-feature
+echo "I'm adding a new feature with my mind!" > mynewfile
+hg commit -A -m 'New feature'
+

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

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

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

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