1.1 --- a/es/tour-merge.tex	Sat Oct 18 07:48:21 2008 -0500
     1.2 +++ b/es/tour-merge.tex	Thu Oct 23 03:13:35 2008 -0500
     1.3 @@ -0,0 +1,283 @@
     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.  The histories of the two repositories have also diverged,
    1.34 +as illustrated in figure~\ref{fig:tour-merge:sep-repos}.
    1.35 +\interaction{tour.merge.cat}
    1.36 +
    1.37 +\begin{figure}[ht]
    1.38 +  \centering
    1.39 +  \grafix{tour-merge-sep-repos}
    1.40 +  \caption{Divergent recent histories of the \dirname{my-hello} and
    1.41 +    \dirname{my-new-hello} repositories}
    1.42 +  \label{fig:tour-merge:sep-repos}
    1.43 +\end{figure}
    1.44 +
    1.45 +We already know that pulling changes from our \dirname{my-hello}
    1.46 +repository will have no effect on the working directory.
    1.47 +\interaction{tour.merge.pull}
    1.48 +However, the \hgcmd{pull} command says something about ``heads''.  
    1.49 +
    1.50 +\subsection{Head changesets}
    1.51 +
    1.52 +A head is a change that has no descendants, or children, as they're
    1.53 +also known.  The tip revision is thus a head, because the newest
    1.54 +revision in a repository doesn't have any children, but a repository
    1.55 +can contain more than one head.
    1.56 +
    1.57 +\begin{figure}[ht]
    1.58 +  \centering
    1.59 +  \grafix{tour-merge-pull}
    1.60 +  \caption{Repository contents after pulling from \dirname{my-hello} into
    1.61 +    \dirname{my-new-hello}}
    1.62 +  \label{fig:tour-merge:pull}
    1.63 +\end{figure}
    1.64 +
    1.65 +In figure~\ref{fig:tour-merge:pull}, you can see the effect of the
    1.66 +pull from \dirname{my-hello} into \dirname{my-new-hello}.  The history
    1.67 +that was already present in \dirname{my-new-hello} is untouched, but a
    1.68 +new revision has been added.  By referring to
    1.69 +figure~\ref{fig:tour-merge:sep-repos}, we can see that the
    1.70 +\emph{changeset ID} remains the same in the new repository, but the
    1.71 +\emph{revision number} has changed.  (This, incidentally, is a fine
    1.72 +example of why it's not safe to use revision numbers when discussing
    1.73 +changesets.)  We can view the heads in a repository using the
    1.74 +\hgcmd{heads} command.
    1.75 +\interaction{tour.merge.heads}
    1.76 +
    1.77 +\subsection{Performing the merge}
    1.78 +
    1.79 +What happens if we try to use the normal \hgcmd{update} command to
    1.80 +update to the new tip?
    1.81 +\interaction{tour.merge.update}
    1.82 +Mercurial is telling us that the \hgcmd{update} command won't do a
    1.83 +merge; it won't update the working directory when it thinks we might
    1.84 +be wanting to do a merge, unless we force it to do so.  Instead, we
    1.85 +use the \hgcmd{merge} command to merge the two heads.
    1.86 +\interaction{tour.merge.merge}
    1.87 +
    1.88 +\begin{figure}[ht]
    1.89 +  \centering
    1.90 +  \grafix{tour-merge-merge}
    1.91 +  \caption{Working directory and repository during merge, and
    1.92 +    following commit}
    1.93 +  \label{fig:tour-merge:merge}
    1.94 +\end{figure}
    1.95 +
    1.96 +This updates the working directory so that it contains changes from
    1.97 +\emph{both} heads, which is reflected in both the output of
    1.98 +\hgcmd{parents} and the contents of \filename{hello.c}.
    1.99 +\interaction{tour.merge.parents}
   1.100 +
   1.101 +\subsection{Committing the results of the merge}
   1.102 +
   1.103 +Whenever we've done a merge, \hgcmd{parents} will display two parents
   1.104 +until we \hgcmd{commit} the results of the merge.
   1.105 +\interaction{tour.merge.commit}
   1.106 +We now have a new tip revision; notice that it has \emph{both} of
   1.107 +our former heads as its parents.  These are the same revisions that
   1.108 +were previously displayed by \hgcmd{parents}.
   1.109 +\interaction{tour.merge.tip}
   1.110 +In figure~\ref{fig:tour-merge:merge}, you can see a representation of
   1.111 +what happens to the working directory during the merge, and how this
   1.112 +affects the repository when the commit happens.  During the merge, the
   1.113 +working directory has two parent changesets, and these become the
   1.114 +parents of the new changeset.
   1.115 +
   1.116 +\section{Merging conflicting changes}
   1.117 +
   1.118 +Most merges are simple affairs, but sometimes you'll find yourself
   1.119 +merging changes where each modifies the same portions of the same
   1.120 +files.  Unless both modifications are identical, this results in a
   1.121 +\emph{conflict}, where you have to decide how to reconcile the
   1.122 +different changes into something coherent.
   1.123 +
   1.124 +\begin{figure}[ht]
   1.125 +  \centering
   1.126 +  \grafix{tour-merge-conflict}
   1.127 +  \caption{Conflicting changes to a document}
   1.128 +  \label{fig:tour-merge:conflict}
   1.129 +\end{figure}
   1.130 +
   1.131 +Figure~\ref{fig:tour-merge:conflict} illustrates an instance of two
   1.132 +conflicting changes to a document.  We started with a single version
   1.133 +of the file; then we made some changes; while someone else made
   1.134 +different changes to the same text.  Our task in resolving the
   1.135 +conflicting changes is to decide what the file should look like.
   1.136 +
   1.137 +Mercurial doesn't have a built-in facility for handling conflicts.
   1.138 +Instead, it runs an external program called \command{hgmerge}.  This
   1.139 +is a shell script that is bundled with Mercurial; you can change it to
   1.140 +behave however you please.  What it does by default is try to find one
   1.141 +of several different merging tools that are likely to be installed on
   1.142 +your system.  It first tries a few fully automatic merging tools; if
   1.143 +these don't succeed (because the resolution process requires human
   1.144 +guidance) or aren't present, the script tries a few different
   1.145 +graphical merging tools.
   1.146 +
   1.147 +It's also possible to get Mercurial to run another program or script
   1.148 +instead of \command{hgmerge}, by setting the \envar{HGMERGE}
   1.149 +environment variable to the name of your preferred program.
   1.150 +
   1.151 +\subsection{Using a graphical merge tool}
   1.152 +
   1.153 +My preferred graphical merge tool is \command{kdiff3}, which I'll use
   1.154 +to describe the features that are common to graphical file merging
   1.155 +tools.  You can see a screenshot of \command{kdiff3} in action in
   1.156 +figure~\ref{fig:tour-merge:kdiff3}.  The kind of merge it is
   1.157 +performing is called a \emph{three-way merge}, because there are three
   1.158 +different versions of the file of interest to us.  The tool thus
   1.159 +splits the upper portion of the window into three panes:
   1.160 +\begin{itemize}
   1.161 +\item At the left is the \emph{base} version of the file, i.e.~the
   1.162 +  most recent version from which the two versions we're trying to
   1.163 +  merge are descended.
   1.164 +\item In the middle is ``our'' version of the file, with the contents
   1.165 +  that we modified.
   1.166 +\item On the right is ``their'' version of the file, the one that
   1.167 +  from the changeset that we're trying to merge with.
   1.168 +\end{itemize}
   1.169 +In the pane below these is the current \emph{result} of the merge.
   1.170 +Our task is to replace all of the red text, which indicates unresolved
   1.171 +conflicts, with some sensible merger of the ``ours'' and ``theirs''
   1.172 +versions of the file.
   1.173 +
   1.174 +All four of these panes are \emph{locked together}; if we scroll
   1.175 +vertically or horizontally in any of them, the others are updated to
   1.176 +display the corresponding sections of their respective files.
   1.177 +
   1.178 +\begin{figure}[ht]
   1.179 +  \centering
   1.180 +  \grafix{kdiff3}
   1.181 +  \caption{Using \command{kdiff3} to merge versions of a file}
   1.182 +  \label{fig:tour-merge:kdiff3}
   1.183 +\end{figure}
   1.184 +
   1.185 +For each conflicting portion of the file, we can choose to resolve
   1.186 +the conflict using some combination of text from the base version,
   1.187 +ours, or theirs.  We can also manually edit the merged file at any
   1.188 +time, in case we need to make further modifications.
   1.189 +
   1.190 +There are \emph{many} file merging tools available, too many to cover
   1.191 +here.  They vary in which platforms they are available for, and in
   1.192 +their particular strengths and weaknesses.  Most are tuned for merging
   1.193 +files containing plain text, while a few are aimed at specialised file
   1.194 +formats (generally XML).
   1.195 +
   1.196 +\subsection{A worked example}
   1.197 +
   1.198 +In this example, we will reproduce the file modification history of
   1.199 +figure~\ref{fig:tour-merge:conflict} above.  Let's begin by creating a
   1.200 +repository with a base version of our document.
   1.201 +\interaction{tour-merge-conflict.wife}
   1.202 +We'll clone the repository and make a change to the file.
   1.203 +\interaction{tour-merge-conflict.cousin}
   1.204 +And another clone, to simulate someone else making a change to the
   1.205 +file.  (This hints at the idea that it's not all that unusual to merge
   1.206 +with yourself when you isolate tasks in separate repositories, and
   1.207 +indeed to find and resolve conflicts while doing so.)
   1.208 +\interaction{tour-merge-conflict.son}
   1.209 +Having created two different versions of the file, we'll set up an
   1.210 +environment suitable for running our merge.
   1.211 +\interaction{tour-merge-conflict.pull}
   1.212 +
   1.213 +In this example, I won't use Mercurial's normal \command{hgmerge}
   1.214 +program to do the merge, because it would drop my nice automated
   1.215 +example-running tool into a graphical user interface.  Instead, I'll
   1.216 +set \envar{HGMERGE} to tell Mercurial to use the non-interactive
   1.217 +\command{merge} command.  This is bundled with many Unix-like systems.
   1.218 +If you're following this example on your computer, don't bother
   1.219 +setting \envar{HGMERGE}.
   1.220 +\interaction{tour-merge-conflict.merge}
   1.221 +Because \command{merge} can't resolve the conflicting changes, it
   1.222 +leaves \emph{merge markers} inside the file that has conflicts,
   1.223 +indicating which lines have conflicts, and whether they came from our
   1.224 +version of the file or theirs.
   1.225 +
   1.226 +Mercurial can tell from the way \command{merge} exits that it wasn't
   1.227 +able to merge successfully, so it tells us what commands we'll need to
   1.228 +run if we want to redo the merging operation.  This could be useful
   1.229 +if, for example, we were running a graphical merge tool and quit
   1.230 +because we were confused or realised we had made a mistake.
   1.231 +
   1.232 +If automatic or manual merges fail, there's nothing to prevent us from
   1.233 +``fixing up'' the affected files ourselves, and committing the results
   1.234 +of our merge:
   1.235 +\interaction{tour-merge-conflict.commit}
   1.236 +
   1.237 +\section{Simplifying the pull-merge-commit sequence}
   1.238 +\label{sec:tour-merge:fetch}
   1.239 +
   1.240 +The process of merging changes as outlined above is straightforward,
   1.241 +but requires running three commands in sequence.
   1.242 +\begin{codesample2}
   1.243 +  hg pull
   1.244 +  hg merge
   1.245 +  hg commit -m 'Merged remote changes'
   1.246 +\end{codesample2}
   1.247 +In the case of the final commit, you also need to enter a commit
   1.248 +message, which is almost always going to be a piece of uninteresting
   1.249 +``boilerplate'' text.
   1.250 +
   1.251 +It would be nice to reduce the number of steps needed, if this were
   1.252 +possible.  Indeed, Mercurial is distributed with an extension called
   1.253 +\hgext{fetch} that does just this.
   1.254 +
   1.255 +Mercurial provides a flexible extension mechanism that lets people
   1.256 +extend its functionality, while keeping the core of Mercurial small
   1.257 +and easy to deal with.  Some extensions add new commands that you can
   1.258 +use from the command line, while others work ``behind the scenes,''
   1.259 +for example adding capabilities to the server.
   1.260 +
   1.261 +The \hgext{fetch} extension adds a new command called, not
   1.262 +surprisingly, \hgcmd{fetch}.  This extension acts as a combination of
   1.263 +\hgcmd{pull}, \hgcmd{update} and \hgcmd{merge}.  It begins by pulling
   1.264 +changes from another repository into the current repository.  If it
   1.265 +finds that the changes added a new head to the repository, it begins a
   1.266 +merge, then commits the result of the merge with an
   1.267 +automatically-generated commit message.  If no new heads were added,
   1.268 +it updates the working directory to the new tip changeset.
   1.269 +
   1.270 +Enabling the \hgext{fetch} extension is easy.  Edit your
   1.271 +\sfilename{.hgrc}, and either go to the \rcsection{extensions} section
   1.272 +or create an \rcsection{extensions} section.  Then add a line that
   1.273 +simply reads ``\Verb+fetch +''.
   1.274 +\begin{codesample2}
   1.275 +  [extensions]
   1.276 +  fetch =
   1.277 +\end{codesample2}
   1.278 +(Normally, on the right-hand side of the ``\texttt{=}'' would appear
   1.279 +the location of the extension, but since the \hgext{fetch} extension
   1.280 +is in the standard distribution, Mercurial knows where to search for
   1.281 +it.)
   1.282 +
   1.283 +%%% Local Variables: 
   1.284 +%%% mode: latex
   1.285 +%%% TeX-master: "00book"
   1.286 +%%% End: