
bos@95: \chapter{A tour of Mercurial: merging work}
bos@95: \label{chap:tour-merge}
bos@94: 
bos@94: We've now covered cloning a repository, making changes in a
bos@94: repository, and pulling or pushing changes from one repository into
bos@94: another.  Our next step is \emph{merging} changes from separate
bos@94: repositories.
bos@94: 
bos@95: \section{Merging streams of work}
bos@95: 
bos@94: Merging is a fundamental part of working with a distributed revision
bos@94: control tool.
bos@94: \begin{itemize}
bos@94: \item Alice and Bob each have a personal copy of a repository for a
bos@94:   project they're collaborating on.  Alice fixes a bug in her
bos@94:   repository; Bob adds a new feature in his.  They want the shared
bos@94:   repository to contain both the bug fix and the new feature.
bos@94: \item I frequently work on several different tasks for a single
bos@94:   project at once, each safely isolated in its own repository.
bos@94:   Working this way means that I often need to merge one piece of my
bos@94:   own work with another.
bos@94: \end{itemize}
bos@94: 
bos@94: Because merging is such a common thing to need to do, Mercurial makes
bos@94: it easy.  Let's walk through the process.  We'll begin by cloning yet
bos@94: another repository (see how often they spring up?) and making a change
bos@94: in it.
bos@94: \interaction{tour.merge.clone}
bos@94: We should now have two copies of \filename{hello.c} with different
bos@94: contents.
bos@94: \interaction{tour.merge.cat}
bos@94: 
bos@94: We already know that pulling changes from our \dirname{my-hello}
bos@94: repository will have no effect on the working directory.
bos@94: \interaction{tour.merge.pull}
bos@94: However, the \hgcmd{pull} command says something about ``heads''.  
bos@94: 
bos@94: A head is a change that has no descendants.  The tip revision is thus
bos@94: a head, but a repository can contain more than one head.  We can view
bos@94: them using the \hgcmd{heads} command.
bos@94: \interaction{tour.merge.heads}
bos@94: What happens if we try to use the normal \hgcmd{update} command to
bos@94: update to the new tip?
bos@94: \interaction{tour.merge.update}
bos@94: Mercurial is telling us that the \hgcmd{update} command won't do a
bos@94: merge.  Instead, we use the \hgcmd{merge} command to merge the two
bos@94: heads.
bos@94: \interaction{tour.merge.merge}
bos@94: This updates the working directory so that it contains changes from
bos@94: both heads, which is reflected in both the output of \hgcmd{parents}
bos@94: and the contents of \filename{hello.c}.
bos@94: \interaction{tour.merge.parents}
bos@94: Whenever we've done a merge, \hgcmd{parents} will display two parents
bos@94: until we \hgcmd{commit} the results of the merge.
bos@94: \interaction{tour.merge.commit}
bos@94: We now have a new tip revision; notice that it has \emph{both} of
bos@94: our former heads as its parents.  These are the same revisions that
bos@94: were previously displayed by \hgcmd{parents}.
bos@94: \interaction{tour.merge.tip}
bos@94: 
bos@84: %%% Local Variables: 
bos@84: %%% mode: latex
bos@84: %%% TeX-master: "00book"
bos@84: %%% End: 




