jerojasro@382: \chapter{A tour of Mercurial: merging work} bos@95: \label{chap:tour-merge} bos@94: jerojasro@382: We've now covered cloning a repository, making changes in a jerojasro@382: repository, and pulling or pushing changes from one repository into jerojasro@382: another. Our next step is \emph{merging} changes from separate jerojasro@382: 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@103: merging changes where each modifies the same portions of the same bos@103: files. Unless both modifications are identical, this results in a bos@103: \emph{conflict}, where you have to decide how to reconcile the bos@103: different changes into something coherent. bos@103: bos@103: \begin{figure}[ht] bos@103: \centering bos@103: \grafix{tour-merge-conflict} bos@103: \caption{Conflicting changes to a document} bos@103: \label{fig:tour-merge:conflict} bos@103: \end{figure} bos@103: bos@103: Figure~\ref{fig:tour-merge:conflict} illustrates an instance of two bos@103: conflicting changes to a document. We started with a single version bos@103: of the file; then we made some changes; while someone else made bos@103: different changes to the same text. Our task in resolving the bos@103: conflicting changes is to decide what the file should look like. bos@103: bos@103: Mercurial doesn't have a built-in facility for handling conflicts. bos@103: Instead, it runs an external program called \command{hgmerge}. This bos@103: is a shell script that is bundled with Mercurial; you can change it to bos@103: behave however you please. What it does by default is try to find one bos@103: of several different merging tools that are likely to be installed on bos@103: your system. It first tries a few fully automatic merging tools; if bos@103: these don't succeed (because the resolution process requires human bos@103: guidance) or aren't present, the script tries a few different bos@103: graphical merging tools. bos@103: bos@103: It's also possible to get Mercurial to run another program or script bos@103: instead of \command{hgmerge}, by setting the \envar{HGMERGE} bos@103: environment variable to the name of your preferred program. bos@103: bos@103: \subsection{Using a graphical merge tool} bos@103: bos@103: My preferred graphical merge tool is \command{kdiff3}, which I'll use bos@103: to describe the features that are common to graphical file merging bos@103: tools. You can see a screenshot of \command{kdiff3} in action in bos@103: figure~\ref{fig:tour-merge:kdiff3}. The kind of merge it is bos@103: performing is called a \emph{three-way merge}, because there are three bos@103: different versions of the file of interest to us. The tool thus bos@103: splits the upper portion of the window into three panes: bos@103: \begin{itemize} bos@103: \item At the left is the \emph{base} version of the file, i.e.~the bos@103: most recent version from which the two versions we're trying to bos@103: merge are descended. bos@103: \item In the middle is ``our'' version of the file, with the contents bos@103: that we modified. bos@103: \item On the right is ``their'' version of the file, the one that bos@103: from the changeset that we're trying to merge with. bos@103: \end{itemize} bos@103: In the pane below these is the current \emph{result} of the merge. bos@103: Our task is to replace all of the red text, which indicates unresolved bos@103: conflicts, with some sensible merger of the ``ours'' and ``theirs'' bos@103: versions of the file. bos@103: bos@103: All four of these panes are \emph{locked together}; if we scroll bos@103: vertically or horizontally in any of them, the others are updated to bos@103: display the corresponding sections of their respective files. bos@103: bos@103: \begin{figure}[ht] bos@103: \centering bos@103: \grafix{kdiff3} bos@103: \caption{Using \command{kdiff3} to merge versions of a file} bos@103: \label{fig:tour-merge:kdiff3} bos@103: \end{figure} bos@103: bos@103: For each conflicting portion of the file, we can choose to resolve mrowe@257: the conflict using some combination of text from the base version, bos@103: ours, or theirs. We can also manually edit the merged file at any bos@103: time, in case we need to make further modifications. bos@103: bos@103: There are \emph{many} file merging tools available, too many to cover bos@103: here. They vary in which platforms they are available for, and in bos@103: their particular strengths and weaknesses. Most are tuned for merging bos@103: files containing plain text, while a few are aimed at specialised file bos@103: formats (generally XML). bos@103: bos@103: \subsection{A worked example} bos@103: bos@103: In this example, we will reproduce the file modification history of bos@103: figure~\ref{fig:tour-merge:conflict} above. Let's begin by creating a bos@103: repository with a base version of our document. bos@103: \interaction{tour-merge-conflict.wife} bos@103: We'll clone the repository and make a change to the file. bos@103: \interaction{tour-merge-conflict.cousin} bos@103: And another clone, to simulate someone else making a change to the bos@103: file. (This hints at the idea that it's not all that unusual to merge bos@103: with yourself when you isolate tasks in separate repositories, and bos@103: indeed to find and resolve conflicts while doing so.) bos@103: \interaction{tour-merge-conflict.son} bos@103: Having created two different versions of the file, we'll set up an bos@103: environment suitable for running our merge. bos@103: \interaction{tour-merge-conflict.pull} bos@103: bos@103: In this example, I won't use Mercurial's normal \command{hgmerge} bos@103: program to do the merge, because it would drop my nice automated bos@103: example-running tool into a graphical user interface. Instead, I'll bos@103: set \envar{HGMERGE} to tell Mercurial to use the non-interactive bos@103: \command{merge} command. This is bundled with many Unix-like systems. bos@103: If you're following this example on your computer, don't bother bos@103: setting \envar{HGMERGE}. bos@103: \interaction{tour-merge-conflict.merge} bos@103: Because \command{merge} can't resolve the conflicting changes, it bos@103: leaves \emph{merge markers} inside the file that has conflicts, bos@103: indicating which lines have conflicts, and whether they came from our bos@103: version of the file or theirs. bos@103: bos@103: Mercurial can tell from the way \command{merge} exits that it wasn't bos@103: able to merge successfully, so it tells us what commands we'll need to bos@103: run if we want to redo the merging operation. This could be useful bos@103: if, for example, we were running a graphical merge tool and quit bos@103: because we were confused or realised we had made a mistake. bos@103: bos@103: If automatic or manual merges fail, there's nothing to prevent us from bos@103: ``fixing up'' the affected files ourselves, and committing the results bos@103: of our merge: bos@103: \interaction{tour-merge-conflict.commit} bos@103: bos@224: \section{Simplifying the pull-merge-commit sequence} bos@224: \label{sec:tour-merge:fetch} 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@103: In the case of the final commit, you also need to enter a commit bos@103: message, which is almost always going to be a piece of uninteresting bos@103: ``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: