1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/en/tour-merge.tex	Fri Oct 13 14:00:06 2006 -0700
     1.3 @@ -0,0 +1,64 @@
     1.4 +\chapter{A tour of Mercurial: merging work}
     1.5 +\label{chap:tour-merge}
     1.6 +
     1.7 +We've now covered cloning a repository, making changes in a
     1.8 +repository, and pulling or pushing changes from one repository into
     1.9 +another.  Our next step is \emph{merging} changes from separate
    1.10 +repositories.
    1.11 +
    1.12 +\section{Merging streams of work}
    1.13 +
    1.14 +Merging is a fundamental part of working with a distributed revision
    1.15 +control tool.
    1.16 +\begin{itemize}
    1.17 +\item Alice and Bob each have a personal copy of a repository for a
    1.18 +  project they're collaborating on.  Alice fixes a bug in her
    1.19 +  repository; Bob adds a new feature in his.  They want the shared
    1.20 +  repository to contain both the bug fix and the new feature.
    1.21 +\item I frequently work on several different tasks for a single
    1.22 +  project at once, each safely isolated in its own repository.
    1.23 +  Working this way means that I often need to merge one piece of my
    1.24 +  own work with another.
    1.25 +\end{itemize}
    1.26 +
    1.27 +Because merging is such a common thing to need to do, Mercurial makes
    1.28 +it easy.  Let's walk through the process.  We'll begin by cloning yet
    1.29 +another repository (see how often they spring up?) and making a change
    1.30 +in it.
    1.31 +\interaction{tour.merge.clone}
    1.32 +We should now have two copies of \filename{hello.c} with different
    1.33 +contents.
    1.34 +\interaction{tour.merge.cat}
    1.35 +
    1.36 +We already know that pulling changes from our \dirname{my-hello}
    1.37 +repository will have no effect on the working directory.
    1.38 +\interaction{tour.merge.pull}
    1.39 +However, the \hgcmd{pull} command says something about ``heads''.  
    1.40 +
    1.41 +A head is a change that has no descendants.  The tip revision is thus
    1.42 +a head, but a repository can contain more than one head.  We can view
    1.43 +them using the \hgcmd{heads} command.
    1.44 +\interaction{tour.merge.heads}
    1.45 +What happens if we try to use the normal \hgcmd{update} command to
    1.46 +update to the new tip?
    1.47 +\interaction{tour.merge.update}
    1.48 +Mercurial is telling us that the \hgcmd{update} command won't do a
    1.49 +merge.  Instead, we use the \hgcmd{merge} command to merge the two
    1.50 +heads.
    1.51 +\interaction{tour.merge.merge}
    1.52 +This updates the working directory so that it contains changes from
    1.53 +both heads, which is reflected in both the output of \hgcmd{parents}
    1.54 +and the contents of \filename{hello.c}.
    1.55 +\interaction{tour.merge.parents}
    1.56 +Whenever we've done a merge, \hgcmd{parents} will display two parents
    1.57 +until we \hgcmd{commit} the results of the merge.
    1.58 +\interaction{tour.merge.commit}
    1.59 +We now have a new tip revision; notice that it has \emph{both} of
    1.60 +our former heads as its parents.  These are the same revisions that
    1.61 +were previously displayed by \hgcmd{parents}.
    1.62 +\interaction{tour.merge.tip}
    1.63 +
    1.64 +%%% Local Variables: 
    1.65 +%%% mode: latex
    1.66 +%%% TeX-master: "00book"
    1.67 +%%% End: