changeset 202:6f167e644762

Start writing about named branches.
author Bryan O'Sullivan <bos@serpentine.com>
date Fri, 20 Apr 2007 14:02:10 -0700
parents 80fc720338a5
children d7615e15510f
files en/Makefile en/branch.tex en/examples/branch-named
diffstat 3 files changed, 46 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/en/Makefile	Wed Apr 18 15:48:00 2007 -0700
+++ b/en/Makefile	Fri Apr 20 14:02:10 2007 -0700
@@ -56,6 +56,7 @@
 	backout \
 	bisect \
 	branching \
+	branch-named \
 	branch-repo \
 	cmdref \
 	daily.copy \
--- a/en/branch.tex	Wed Apr 18 15:48:00 2007 -0700
+++ b/en/branch.tex	Fri Apr 20 14:02:10 2007 -0700
@@ -224,6 +224,41 @@
 to the main branch.
 \interaction{branch-repo.merge}
 
+\section{Naming branches within one repository}
+
+In most instances, isolating branches in repositories is the right
+approach.  Its simplicity makes it easy to understand; and so it's
+hard to make mistakes.  There's a one-to-one relationship between
+branches you're working in and directories on your system.  This lets
+you use normal (non-Mercurial-aware) tools to work on files within a
+branch/repository.
+
+If you're more in the ``power user'' category (\emph{and} your
+collaborators are too), there is an alternative way of handling
+branches that you can consider.  I've already mentioned the
+human-level distinction between ``small picture'' and ``big picture''
+branches.  While Mercurial works with multiple ``small picture''
+branches in a repository all the time (for example after you pull
+changes in, but before you merge them), it can \emph{also} work with
+multiple ``big picture'' branches.
+
+The key to working this way is that Mercurial lets you assign a
+persistent \emph{name} to a branch.  There always exists a branch
+named \texttt{default}.  Even before you start naming branches
+yourself, you can find traces of the \texttt{default} branch if you
+look for them.
+
+As an example, when you run the \hgcmd{commit} command, and it pops up
+your editor so that you can enter a commit message, look for a line
+that contains the text ``\texttt{HG: branch default}'' at the bottom.
+This is telling you that your commit will occur on the branch named
+\texttt{default}.
+
+To start working with named branches, use the \hgcmd{branches}
+command.  This command lists the named branches already present in
+your repository.
+\interaction{branch-named.branches}
+
 %%% Local Variables: 
 %%% mode: latex
 %%% TeX-master: "00book"
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/en/examples/branch-named	Fri Apr 20 14:02:10 2007 -0700
@@ -0,0 +1,10 @@
+#!/bin/bash
+
+hg init a
+cd a
+echo hello > myfile
+hg commit -A -m 'Initial commit'
+
+#$ name: branches
+
+hg branches