hgbook
diff en/branch.tex @ 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 |
line diff
1.1 --- a/en/branch.tex Mon Apr 16 16:33:51 2007 -0700 1.2 +++ b/en/branch.tex Mon Apr 16 17:21:38 2007 -0700 1.3 @@ -126,6 +126,24 @@ 1.4 which you can then fix and commit. You should then run \hgcmd{tags} 1.5 again, just to be sure that your fix is correct. 1.6 1.7 +\subsection{Tags and cloning} 1.8 + 1.9 +You may have noticed that the \hgcmd{clone} command has a 1.10 +\hgopt{clone}{-r} option that lets you clone an exact copy of 1.11 +repository as of a particular changeset. The new clone will not 1.12 +contain any project history that comes after the revision you 1.13 +specified. This has an interaction with tags that can surprise the 1.14 +unwary. 1.15 + 1.16 +Recall that a tag is stored as a revision to the \sfilename{.hgtags} 1.17 +file, so that when you create a tag, the changeset in which it's 1.18 +recorded necessarily refers to an older changeset. When you run 1.19 +\hgcmdargs{clone}{-r foo} to clone a repository as of tag 1.20 +\texttt{foo}, the new clone \emph{will not contain the history that 1.21 + created the tag} that you used to clone the repository. The result 1.22 +is that you'll get exactly the right subset of the project's history 1.23 +in the new repository, but \emph{not} the tag you might have expected. 1.24 + 1.25 \subsection{When permanent tags are too much} 1.26 1.27 Since Mercurial's tags are revision controlled and carried around with 1.28 @@ -144,6 +162,53 @@ 1.29 create using \hgopt{tag}{-l} remain strictly local to the repository 1.30 you're currently working in. 1.31 1.32 +\section{The flow of changes---big picture vs. little} 1.33 + 1.34 +To return to the outline I sketched at the beginning of a chapter, 1.35 +let's think about a project that has multiple concurrent pieces of 1.36 +work under development at once. 1.37 + 1.38 +There might be a push for a new ``main'' release; a new minor bugfix 1.39 +release to the last main release; and an unexpected ``hot fix'' to an 1.40 +old release that is now in maintenance mode. 1.41 + 1.42 +The usual way people refer to these different concurrent directions of 1.43 +development is as ``branches''. However, we've already seen numerous 1.44 +times that Mercurial treats \emph{all of history} as a series of 1.45 +branches and merges. Really, what we have here is two ideas that are 1.46 +peripherally related, but which happen to share a name. 1.47 +\begin{itemize} 1.48 +\item ``Big picture'' branches represent the sweep of a project's 1.49 + evolution; people give them names, and talk about them in 1.50 + conversation. 1.51 +\item ``Little picture'' branches are artefacts of the day-to-day 1.52 + activity of developing and merging changes. They expose the 1.53 + narrative of how the code was developed. 1.54 +\end{itemize} 1.55 + 1.56 +\section{Managing big-picture branches in repositories} 1.57 + 1.58 +The easiest way to isolate a ``big picture'' branch in Mercurial is in 1.59 +a dedicated repository. If you have an existing shared 1.60 +repository---let's call it \texttt{myproject}---that reaches a ``1.0'' 1.61 +milestone, you can start to prepare for future maintenance releases on 1.62 +top of version~1.0 by tagging the revision from which you prepared 1.63 +the~1.0 release. 1.64 +\interaction{branch-repo.tag} 1.65 +You can then clone a new shared \texttt{myproject-1.0.1} repository as 1.66 +of that tag. 1.67 +\interaction{branch-repo.clone} 1.68 + 1.69 +Afterwards, if someone needs to work on a bug fix that ought to go 1.70 +into an upcoming~1.0.1 minor release, they clone the 1.71 +\texttt{myproject-1.0.1} repository, make their changes, and push them 1.72 +back. 1.73 +\interaction{branch-repo.bugfix} 1.74 +Meanwhile, development for the next major release can continue, 1.75 +isolated and unabated, in the \texttt{myproject} repository. 1.76 +\interaction{branch-repo.new} 1.77 + 1.78 + 1.79 1.80 %%% Local Variables: 1.81 %%% mode: latex