view en/tour-merge.tex @ 102:ff9dc8bc2a8b

More. Merge. Stuff.

\chapter{A tour of Mercurial: merging work}
\label{chap:tour-merge}

We've now covered cloning a repository, making changes in a
repository, and pulling or pushing changes from one repository into
another.  Our next step is \emph{merging} changes from separate
repositories.

\section{Merging streams of work}

Merging is a fundamental part of working with a distributed revision
control tool.
\begin{itemize}
\item Alice and Bob each have a personal copy of a repository for a
  project they're collaborating on.  Alice fixes a bug in her
  repository; Bob adds a new feature in his.  They want the shared
  repository to contain both the bug fix and the new feature.
\item I frequently work on several different tasks for a single
  project at once, each safely isolated in its own repository.
  Working this way means that I often need to merge one piece of my
  own work with another.
\end{itemize}

Because merging is such a common thing to need to do, Mercurial makes
it easy.  Let's walk through the process.  We'll begin by cloning yet
another repository (see how often they spring up?) and making a change
in it.
\interaction{tour.merge.clone}
We should now have two copies of \filename{hello.c} with different
contents.  The histories of the two repositories have also diverged,
as illustrated in figure~\ref{fig:tour-merge:sep-repos}.
\interaction{tour.merge.cat}

\begin{figure}[ht]
  \centering
  \grafix{tour-merge-sep-repos}
  \caption{Divergent recent histories of the \dirname{my-hello} and
    \dirname{my-new-hello} repositories}
  \label{fig:tour-merge:sep-repos}
\end{figure}

We already know that pulling changes from our \dirname{my-hello}
repository will have no effect on the working directory.
\interaction{tour.merge.pull}
However, the \hgcmd{pull} command says something about ``heads''.  

\subsection{Head changesets}

A head is a change that has no descendants, or children, as they're
also known.  The tip revision is thus a head, because the newest
revision in a repository doesn't have any children, but a repository
can contain more than one head.

\begin{figure}[ht]
  \centering
  \grafix{tour-merge-pull}
  \caption{Repository contents after pulling from \dirname{my-hello} into
    \dirname{my-new-hello}}
  \label{fig:tour-merge:pull}
\end{figure}

In figure~\ref{fig:tour-merge:pull}, you can see the effect of the
pull from \dirname{my-hello} into \dirname{my-new-hello}.  The history
that was already present in \dirname{my-new-hello} is untouched, but a
new revision has been added.  By referring to
figure~\ref{fig:tour-merge:sep-repos}, we can see that the
\emph{changeset ID} remains the same in the new repository, but the
\emph{revision number} has changed.  (This, incidentally, is a fine
example of why it's not safe to use revision numbers when discussing
changesets.)  We can view the heads in a repository using the
\hgcmd{heads} command.
\interaction{tour.merge.heads}

\subsection{Performing the merge}

What happens if we try to use the normal \hgcmd{update} command to
update to the new tip?
\interaction{tour.merge.update}
Mercurial is telling us that the \hgcmd{update} command won't do a
merge; it won't update the working directory when it thinks we might
be wanting to do a merge, unless we force it to do so.  Instead, we
use the \hgcmd{merge} command to merge the two heads.
\interaction{tour.merge.merge}

\begin{figure}[ht]
  \centering
  \grafix{tour-merge-merge}
  \caption{Working directory and repository during merge, and
    following commit}
  \label{fig:tour-merge:merge}
\end{figure}

This updates the working directory so that it contains changes from
\emph{both} heads, which is reflected in both the output of
\hgcmd{parents} and the contents of \filename{hello.c}.
\interaction{tour.merge.parents}

\subsection{Committing the results of the merge}

Whenever we've done a merge, \hgcmd{parents} will display two parents
until we \hgcmd{commit} the results of the merge.
\interaction{tour.merge.commit}
We now have a new tip revision; notice that it has \emph{both} of
our former heads as its parents.  These are the same revisions that
were previously displayed by \hgcmd{parents}.
\interaction{tour.merge.tip}
In figure~\ref{fig:tour-merge:merge}, you can see a representation of
what happens to the working directory during the merge, and how this
affects the repository when the commit happens.  During the merge, the
working directory has two parent changesets, and these become the
parents of the new changeset.

\section{Merging conflicting changes}

Most merges are simple affairs, but sometimes you'll find yourself
merging a change that you made with another, where both modify the
same portions of the same files.  Unless both modifications are
identical, this results in a \emph{conflict}, where you have to decide
how to reconcile the different changes into something coherent.

\section{Using an extension to simplify merging}

The process of merging changes as outlined above is straightforward,
but requires running three commands in sequence.
\begin{codesample2}
  hg pull
  hg merge
  hg commit -m 'Merged remote changes'
\end{codesample2}
In the case of the final commit, you also need to come up with a
commit message, which is almost always going to be a piece of
uninteresting ``boilerplate'' text.

It would be nice to reduce the number of steps needed, if this were
possible.  Indeed, Mercurial is distributed with an extension called
\hgext{fetch} that does just this.

Mercurial provides a flexible extension mechanism that lets people
extend its functionality, while keeping the core of Mercurial small
and easy to deal with.  Some extensions add new commands that you can
use from the command line, while others work ``behind the scenes,''
for example adding capabilities to the server.

The \hgext{fetch} extension adds a new command called, not
surprisingly, \hgcmd{fetch}.  This extension acts as a combination of
\hgcmd{pull}, \hgcmd{update} and \hgcmd{merge}.  It begins by pulling
changes from another repository into the current repository.  If it
finds that the changes added a new head to the repository, it begins a
merge, then commits the result of the merge with an
automatically-generated commit message.  If no new heads were added,
it updates the working directory to the new tip changeset.

Enabling the \hgext{fetch} extension is easy.  Edit your
\sfilename{.hgrc}, and either go to the \rcsection{extensions} section
or create an \rcsection{extensions} section.  Then add a line that
simply reads ``\Verb+fetch +''.
\begin{codesample2}
  [extensions]
  fetch =
\end{codesample2}
(Normally, on the right-hand side of the ``\texttt{=}'' would appear
the location of the extension, but since the \hgext{fetch} extension
is in the standard distribution, Mercurial knows where to search for
it.)

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "00book"
%%% End: