
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@99: contents.  The histories of the two repositories have also diverged,
bos@99: as illustrated in figure~\ref{fig:tour-merge:sep-repos}.
bos@94: \interaction{tour.merge.cat}
bos@94: 
bos@99: \begin{figure}[ht]
bos@99:   \centering
bos@99:   \grafix{tour-merge-sep-repos}
bos@99:   \caption{Divergent recent histories of the \dirname{my-hello} and
bos@99:     \dirname{my-new-hello} repositories}
bos@99:   \label{fig:tour-merge:sep-repos}
bos@99: \end{figure}
bos@99: 
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@102: \subsection{Head changesets}
bos@102: 
bos@99: A head is a change that has no descendants, or children, as they're
bos@99: also known.  The tip revision is thus a head, because the newest
bos@99: revision in a repository doesn't have any children, but a repository
bos@99: can contain more than one head.
bos@99: 
bos@99: \begin{figure}[ht]
bos@99:   \centering
bos@99:   \grafix{tour-merge-pull}
bos@99:   \caption{Repository contents after pulling from \dirname{my-hello} into
bos@99:     \dirname{my-new-hello}}
bos@99:   \label{fig:tour-merge:pull}
bos@99: \end{figure}
bos@99: 
bos@99: In figure~\ref{fig:tour-merge:pull}, you can see the effect of the
bos@99: pull from \dirname{my-hello} into \dirname{my-new-hello}.  The history
bos@99: that was already present in \dirname{my-new-hello} is untouched, but a
bos@99: new revision has been added.  By referring to
bos@99: figure~\ref{fig:tour-merge:sep-repos}, we can see that the
bos@99: \emph{changeset ID} remains the same in the new repository, but the
bos@99: \emph{revision number} has changed.  (This, incidentally, is a fine
bos@99: example of why it's not safe to use revision numbers when discussing
bos@99: changesets.)  We can view the heads in a repository using the
bos@99: \hgcmd{heads} command.
bos@94: \interaction{tour.merge.heads}
bos@102: 
bos@102: \subsection{Performing the merge}
bos@102: 
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@100: merge; it won't update the working directory when it thinks we might
bos@100: be wanting to do a merge, unless we force it to do so.  Instead, we
bos@100: use the \hgcmd{merge} command to merge the two heads.
bos@94: \interaction{tour.merge.merge}
bos@100: 
bos@100: \begin{figure}[ht]
bos@100:   \centering
bos@100:   \grafix{tour-merge-merge}
bos@100:   \caption{Working directory and repository during merge, and
bos@100:     following commit}
bos@100:   \label{fig:tour-merge:merge}
bos@100: \end{figure}
bos@100: 
bos@94: This updates the working directory so that it contains changes from
bos@100: \emph{both} heads, which is reflected in both the output of
bos@100: \hgcmd{parents} and the contents of \filename{hello.c}.
bos@94: \interaction{tour.merge.parents}
bos@102: 
bos@102: \subsection{Committing the results of the merge}
bos@102: 
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@101: In figure~\ref{fig:tour-merge:merge}, you can see a representation of
bos@101: what happens to the working directory during the merge, and how this
bos@101: affects the repository when the commit happens.  During the merge, the
bos@101: working directory has two parent changesets, and these become the
bos@101: parents of the new changeset.
bos@94: 
bos@102: \section{Merging conflicting changes}
bos@102: 
bos@102: Most merges are simple affairs, but sometimes you'll find yourself
bos@102: merging a change that you made with another, where both modify the
bos@102: same portions of the same files.  Unless both modifications are
bos@102: identical, this results in a \emph{conflict}, where you have to decide
bos@102: how to reconcile the different changes into something coherent.
bos@102: 
bos@102: \section{Using an extension to simplify merging}
bos@102: 
bos@102: The process of merging changes as outlined above is straightforward,
bos@102: but requires running three commands in sequence.
bos@102: \begin{codesample2}
bos@102:   hg pull
bos@102:   hg merge
bos@102:   hg commit -m 'Merged remote changes'
bos@102: \end{codesample2}
bos@102: In the case of the final commit, you also need to come up with a
bos@102: commit message, which is almost always going to be a piece of
bos@102: uninteresting ``boilerplate'' text.
bos@102: 
bos@102: It would be nice to reduce the number of steps needed, if this were
bos@102: possible.  Indeed, Mercurial is distributed with an extension called
bos@102: \hgext{fetch} that does just this.
bos@102: 
bos@102: Mercurial provides a flexible extension mechanism that lets people
bos@102: extend its functionality, while keeping the core of Mercurial small
bos@102: and easy to deal with.  Some extensions add new commands that you can
bos@102: use from the command line, while others work ``behind the scenes,''
bos@102: for example adding capabilities to the server.
bos@102: 
bos@102: The \hgext{fetch} extension adds a new command called, not
bos@102: surprisingly, \hgcmd{fetch}.  This extension acts as a combination of
bos@102: \hgcmd{pull}, \hgcmd{update} and \hgcmd{merge}.  It begins by pulling
bos@102: changes from another repository into the current repository.  If it
bos@102: finds that the changes added a new head to the repository, it begins a
bos@102: merge, then commits the result of the merge with an
bos@102: automatically-generated commit message.  If no new heads were added,
bos@102: it updates the working directory to the new tip changeset.
bos@102: 
bos@102: Enabling the \hgext{fetch} extension is easy.  Edit your
bos@102: \sfilename{.hgrc}, and either go to the \rcsection{extensions} section
bos@102: or create an \rcsection{extensions} section.  Then add a line that
bos@102: simply reads ``\Verb+fetch +''.
bos@102: \begin{codesample2}
bos@102:   [extensions]
bos@102:   fetch =
bos@102: \end{codesample2}
bos@102: (Normally, on the right-hand side of the ``\texttt{=}'' would appear
bos@102: the location of the extension, but since the \hgext{fetch} extension
bos@102: is in the standard distribution, Mercurial knows where to search for
bos@102: it.)
bos@102: 
bos@84: %%% Local Variables: 
bos@84: %%% mode: latex
bos@84: %%% TeX-master: "00book"
bos@84: %%% End: 




