hgbook
changeset 198:615f3c6b30e1
Start to describe branch management.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Mon Apr 16 17:21:38 2007 -0700 (2007-04-16) |
parents | 76697ae503db |
children | 58e3a6c76725 |
files | en/Makefile en/branch.tex en/examples/branch-repo en/examples/branch-repo.bugfix.out en/examples/branch-repo.clone.out en/examples/branch-repo.new.out en/examples/branch-repo.tag.out |
line diff
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