hgbook

annotate es/tour-merge.tex @ 381:7ca1186c422f

find changesets by author, revision, files, or words in the commit message
testing push
author Javier Rojas <jerojasro@devnull.li>
date Wed Oct 29 23:47:29 2008 -0500 (2008-10-29)
parents 7e52f0cc4516
children 772b30049b80
rev   line source
jerojasro@381 1 \chapter{Una gira de Mercurial: fusionar trabajo}
jerojasro@336 2 \label{chap:tour-merge}
jerojasro@336 3
jerojasro@381 4 Hasta ahora hemos cubierto cómo clonar un repositorio
jerojasro@336 5 We've now covered cloning a repository, making changes in a
jerojasro@336 6 repository, and pulling or pushing changes from one repository into
jerojasro@336 7 another. Our next step is \emph{merging} changes from separate
jerojasro@336 8 repositories.
jerojasro@336 9
jerojasro@336 10 \section{Merging streams of work}
jerojasro@336 11
jerojasro@336 12 Merging is a fundamental part of working with a distributed revision
jerojasro@336 13 control tool.
jerojasro@336 14 \begin{itemize}
jerojasro@336 15 \item Alice and Bob each have a personal copy of a repository for a
jerojasro@336 16 project they're collaborating on. Alice fixes a bug in her
jerojasro@336 17 repository; Bob adds a new feature in his. They want the shared
jerojasro@336 18 repository to contain both the bug fix and the new feature.
jerojasro@336 19 \item I frequently work on several different tasks for a single
jerojasro@336 20 project at once, each safely isolated in its own repository.
jerojasro@336 21 Working this way means that I often need to merge one piece of my
jerojasro@336 22 own work with another.
jerojasro@336 23 \end{itemize}
jerojasro@336 24
jerojasro@336 25 Because merging is such a common thing to need to do, Mercurial makes
jerojasro@336 26 it easy. Let's walk through the process. We'll begin by cloning yet
jerojasro@336 27 another repository (see how often they spring up?) and making a change
jerojasro@336 28 in it.
jerojasro@336 29 \interaction{tour.merge.clone}
jerojasro@336 30 We should now have two copies of \filename{hello.c} with different
jerojasro@336 31 contents. The histories of the two repositories have also diverged,
jerojasro@336 32 as illustrated in figure~\ref{fig:tour-merge:sep-repos}.
jerojasro@336 33 \interaction{tour.merge.cat}
jerojasro@336 34
jerojasro@336 35 \begin{figure}[ht]
jerojasro@336 36 \centering
jerojasro@336 37 \grafix{tour-merge-sep-repos}
jerojasro@336 38 \caption{Divergent recent histories of the \dirname{my-hello} and
jerojasro@336 39 \dirname{my-new-hello} repositories}
jerojasro@336 40 \label{fig:tour-merge:sep-repos}
jerojasro@336 41 \end{figure}
jerojasro@336 42
jerojasro@336 43 We already know that pulling changes from our \dirname{my-hello}
jerojasro@336 44 repository will have no effect on the working directory.
jerojasro@336 45 \interaction{tour.merge.pull}
jerojasro@336 46 However, the \hgcmd{pull} command says something about ``heads''.
jerojasro@336 47
jerojasro@336 48 \subsection{Head changesets}
jerojasro@336 49
jerojasro@336 50 A head is a change that has no descendants, or children, as they're
jerojasro@336 51 also known. The tip revision is thus a head, because the newest
jerojasro@336 52 revision in a repository doesn't have any children, but a repository
jerojasro@336 53 can contain more than one head.
jerojasro@336 54
jerojasro@336 55 \begin{figure}[ht]
jerojasro@336 56 \centering
jerojasro@336 57 \grafix{tour-merge-pull}
jerojasro@336 58 \caption{Repository contents after pulling from \dirname{my-hello} into
jerojasro@336 59 \dirname{my-new-hello}}
jerojasro@336 60 \label{fig:tour-merge:pull}
jerojasro@336 61 \end{figure}
jerojasro@336 62
jerojasro@336 63 In figure~\ref{fig:tour-merge:pull}, you can see the effect of the
jerojasro@336 64 pull from \dirname{my-hello} into \dirname{my-new-hello}. The history
jerojasro@336 65 that was already present in \dirname{my-new-hello} is untouched, but a
jerojasro@336 66 new revision has been added. By referring to
jerojasro@336 67 figure~\ref{fig:tour-merge:sep-repos}, we can see that the
jerojasro@336 68 \emph{changeset ID} remains the same in the new repository, but the
jerojasro@336 69 \emph{revision number} has changed. (This, incidentally, is a fine
jerojasro@336 70 example of why it's not safe to use revision numbers when discussing
jerojasro@336 71 changesets.) We can view the heads in a repository using the
jerojasro@336 72 \hgcmd{heads} command.
jerojasro@336 73 \interaction{tour.merge.heads}
jerojasro@336 74
jerojasro@336 75 \subsection{Performing the merge}
jerojasro@336 76
jerojasro@336 77 What happens if we try to use the normal \hgcmd{update} command to
jerojasro@336 78 update to the new tip?
jerojasro@336 79 \interaction{tour.merge.update}
jerojasro@336 80 Mercurial is telling us that the \hgcmd{update} command won't do a
jerojasro@336 81 merge; it won't update the working directory when it thinks we might
jerojasro@336 82 be wanting to do a merge, unless we force it to do so. Instead, we
jerojasro@336 83 use the \hgcmd{merge} command to merge the two heads.
jerojasro@336 84 \interaction{tour.merge.merge}
jerojasro@336 85
jerojasro@336 86 \begin{figure}[ht]
jerojasro@336 87 \centering
jerojasro@336 88 \grafix{tour-merge-merge}
jerojasro@336 89 \caption{Working directory and repository during merge, and
jerojasro@336 90 following commit}
jerojasro@336 91 \label{fig:tour-merge:merge}
jerojasro@336 92 \end{figure}
jerojasro@336 93
jerojasro@336 94 This updates the working directory so that it contains changes from
jerojasro@336 95 \emph{both} heads, which is reflected in both the output of
jerojasro@336 96 \hgcmd{parents} and the contents of \filename{hello.c}.
jerojasro@336 97 \interaction{tour.merge.parents}
jerojasro@336 98
jerojasro@336 99 \subsection{Committing the results of the merge}
jerojasro@336 100
jerojasro@336 101 Whenever we've done a merge, \hgcmd{parents} will display two parents
jerojasro@336 102 until we \hgcmd{commit} the results of the merge.
jerojasro@336 103 \interaction{tour.merge.commit}
jerojasro@336 104 We now have a new tip revision; notice that it has \emph{both} of
jerojasro@336 105 our former heads as its parents. These are the same revisions that
jerojasro@336 106 were previously displayed by \hgcmd{parents}.
jerojasro@336 107 \interaction{tour.merge.tip}
jerojasro@336 108 In figure~\ref{fig:tour-merge:merge}, you can see a representation of
jerojasro@336 109 what happens to the working directory during the merge, and how this
jerojasro@336 110 affects the repository when the commit happens. During the merge, the
jerojasro@336 111 working directory has two parent changesets, and these become the
jerojasro@336 112 parents of the new changeset.
jerojasro@336 113
jerojasro@336 114 \section{Merging conflicting changes}
jerojasro@336 115
jerojasro@336 116 Most merges are simple affairs, but sometimes you'll find yourself
jerojasro@336 117 merging changes where each modifies the same portions of the same
jerojasro@336 118 files. Unless both modifications are identical, this results in a
jerojasro@336 119 \emph{conflict}, where you have to decide how to reconcile the
jerojasro@336 120 different changes into something coherent.
jerojasro@336 121
jerojasro@336 122 \begin{figure}[ht]
jerojasro@336 123 \centering
jerojasro@336 124 \grafix{tour-merge-conflict}
jerojasro@336 125 \caption{Conflicting changes to a document}
jerojasro@336 126 \label{fig:tour-merge:conflict}
jerojasro@336 127 \end{figure}
jerojasro@336 128
jerojasro@336 129 Figure~\ref{fig:tour-merge:conflict} illustrates an instance of two
jerojasro@336 130 conflicting changes to a document. We started with a single version
jerojasro@336 131 of the file; then we made some changes; while someone else made
jerojasro@336 132 different changes to the same text. Our task in resolving the
jerojasro@336 133 conflicting changes is to decide what the file should look like.
jerojasro@336 134
jerojasro@336 135 Mercurial doesn't have a built-in facility for handling conflicts.
jerojasro@336 136 Instead, it runs an external program called \command{hgmerge}. This
jerojasro@336 137 is a shell script that is bundled with Mercurial; you can change it to
jerojasro@336 138 behave however you please. What it does by default is try to find one
jerojasro@336 139 of several different merging tools that are likely to be installed on
jerojasro@336 140 your system. It first tries a few fully automatic merging tools; if
jerojasro@336 141 these don't succeed (because the resolution process requires human
jerojasro@336 142 guidance) or aren't present, the script tries a few different
jerojasro@336 143 graphical merging tools.
jerojasro@336 144
jerojasro@336 145 It's also possible to get Mercurial to run another program or script
jerojasro@336 146 instead of \command{hgmerge}, by setting the \envar{HGMERGE}
jerojasro@336 147 environment variable to the name of your preferred program.
jerojasro@336 148
jerojasro@336 149 \subsection{Using a graphical merge tool}
jerojasro@336 150
jerojasro@336 151 My preferred graphical merge tool is \command{kdiff3}, which I'll use
jerojasro@336 152 to describe the features that are common to graphical file merging
jerojasro@336 153 tools. You can see a screenshot of \command{kdiff3} in action in
jerojasro@336 154 figure~\ref{fig:tour-merge:kdiff3}. The kind of merge it is
jerojasro@336 155 performing is called a \emph{three-way merge}, because there are three
jerojasro@336 156 different versions of the file of interest to us. The tool thus
jerojasro@336 157 splits the upper portion of the window into three panes:
jerojasro@336 158 \begin{itemize}
jerojasro@336 159 \item At the left is the \emph{base} version of the file, i.e.~the
jerojasro@336 160 most recent version from which the two versions we're trying to
jerojasro@336 161 merge are descended.
jerojasro@336 162 \item In the middle is ``our'' version of the file, with the contents
jerojasro@336 163 that we modified.
jerojasro@336 164 \item On the right is ``their'' version of the file, the one that
jerojasro@336 165 from the changeset that we're trying to merge with.
jerojasro@336 166 \end{itemize}
jerojasro@336 167 In the pane below these is the current \emph{result} of the merge.
jerojasro@336 168 Our task is to replace all of the red text, which indicates unresolved
jerojasro@336 169 conflicts, with some sensible merger of the ``ours'' and ``theirs''
jerojasro@336 170 versions of the file.
jerojasro@336 171
jerojasro@336 172 All four of these panes are \emph{locked together}; if we scroll
jerojasro@336 173 vertically or horizontally in any of them, the others are updated to
jerojasro@336 174 display the corresponding sections of their respective files.
jerojasro@336 175
jerojasro@336 176 \begin{figure}[ht]
jerojasro@336 177 \centering
jerojasro@336 178 \grafix{kdiff3}
jerojasro@336 179 \caption{Using \command{kdiff3} to merge versions of a file}
jerojasro@336 180 \label{fig:tour-merge:kdiff3}
jerojasro@336 181 \end{figure}
jerojasro@336 182
jerojasro@336 183 For each conflicting portion of the file, we can choose to resolve
jerojasro@336 184 the conflict using some combination of text from the base version,
jerojasro@336 185 ours, or theirs. We can also manually edit the merged file at any
jerojasro@336 186 time, in case we need to make further modifications.
jerojasro@336 187
jerojasro@336 188 There are \emph{many} file merging tools available, too many to cover
jerojasro@336 189 here. They vary in which platforms they are available for, and in
jerojasro@336 190 their particular strengths and weaknesses. Most are tuned for merging
jerojasro@336 191 files containing plain text, while a few are aimed at specialised file
jerojasro@336 192 formats (generally XML).
jerojasro@336 193
jerojasro@336 194 \subsection{A worked example}
jerojasro@336 195
jerojasro@336 196 In this example, we will reproduce the file modification history of
jerojasro@336 197 figure~\ref{fig:tour-merge:conflict} above. Let's begin by creating a
jerojasro@336 198 repository with a base version of our document.
jerojasro@336 199 \interaction{tour-merge-conflict.wife}
jerojasro@336 200 We'll clone the repository and make a change to the file.
jerojasro@336 201 \interaction{tour-merge-conflict.cousin}
jerojasro@336 202 And another clone, to simulate someone else making a change to the
jerojasro@336 203 file. (This hints at the idea that it's not all that unusual to merge
jerojasro@336 204 with yourself when you isolate tasks in separate repositories, and
jerojasro@336 205 indeed to find and resolve conflicts while doing so.)
jerojasro@336 206 \interaction{tour-merge-conflict.son}
jerojasro@336 207 Having created two different versions of the file, we'll set up an
jerojasro@336 208 environment suitable for running our merge.
jerojasro@336 209 \interaction{tour-merge-conflict.pull}
jerojasro@336 210
jerojasro@336 211 In this example, I won't use Mercurial's normal \command{hgmerge}
jerojasro@336 212 program to do the merge, because it would drop my nice automated
jerojasro@336 213 example-running tool into a graphical user interface. Instead, I'll
jerojasro@336 214 set \envar{HGMERGE} to tell Mercurial to use the non-interactive
jerojasro@336 215 \command{merge} command. This is bundled with many Unix-like systems.
jerojasro@336 216 If you're following this example on your computer, don't bother
jerojasro@336 217 setting \envar{HGMERGE}.
jerojasro@336 218 \interaction{tour-merge-conflict.merge}
jerojasro@336 219 Because \command{merge} can't resolve the conflicting changes, it
jerojasro@336 220 leaves \emph{merge markers} inside the file that has conflicts,
jerojasro@336 221 indicating which lines have conflicts, and whether they came from our
jerojasro@336 222 version of the file or theirs.
jerojasro@336 223
jerojasro@336 224 Mercurial can tell from the way \command{merge} exits that it wasn't
jerojasro@336 225 able to merge successfully, so it tells us what commands we'll need to
jerojasro@336 226 run if we want to redo the merging operation. This could be useful
jerojasro@336 227 if, for example, we were running a graphical merge tool and quit
jerojasro@336 228 because we were confused or realised we had made a mistake.
jerojasro@336 229
jerojasro@336 230 If automatic or manual merges fail, there's nothing to prevent us from
jerojasro@336 231 ``fixing up'' the affected files ourselves, and committing the results
jerojasro@336 232 of our merge:
jerojasro@336 233 \interaction{tour-merge-conflict.commit}
jerojasro@336 234
jerojasro@336 235 \section{Simplifying the pull-merge-commit sequence}
jerojasro@336 236 \label{sec:tour-merge:fetch}
jerojasro@336 237
jerojasro@336 238 The process of merging changes as outlined above is straightforward,
jerojasro@336 239 but requires running three commands in sequence.
jerojasro@336 240 \begin{codesample2}
jerojasro@336 241 hg pull
jerojasro@336 242 hg merge
jerojasro@336 243 hg commit -m 'Merged remote changes'
jerojasro@336 244 \end{codesample2}
jerojasro@336 245 In the case of the final commit, you also need to enter a commit
jerojasro@336 246 message, which is almost always going to be a piece of uninteresting
jerojasro@336 247 ``boilerplate'' text.
jerojasro@336 248
jerojasro@336 249 It would be nice to reduce the number of steps needed, if this were
jerojasro@336 250 possible. Indeed, Mercurial is distributed with an extension called
jerojasro@336 251 \hgext{fetch} that does just this.
jerojasro@336 252
jerojasro@336 253 Mercurial provides a flexible extension mechanism that lets people
jerojasro@336 254 extend its functionality, while keeping the core of Mercurial small
jerojasro@336 255 and easy to deal with. Some extensions add new commands that you can
jerojasro@336 256 use from the command line, while others work ``behind the scenes,''
jerojasro@336 257 for example adding capabilities to the server.
jerojasro@336 258
jerojasro@336 259 The \hgext{fetch} extension adds a new command called, not
jerojasro@336 260 surprisingly, \hgcmd{fetch}. This extension acts as a combination of
jerojasro@336 261 \hgcmd{pull}, \hgcmd{update} and \hgcmd{merge}. It begins by pulling
jerojasro@336 262 changes from another repository into the current repository. If it
jerojasro@336 263 finds that the changes added a new head to the repository, it begins a
jerojasro@336 264 merge, then commits the result of the merge with an
jerojasro@336 265 automatically-generated commit message. If no new heads were added,
jerojasro@336 266 it updates the working directory to the new tip changeset.
jerojasro@336 267
jerojasro@336 268 Enabling the \hgext{fetch} extension is easy. Edit your
jerojasro@336 269 \sfilename{.hgrc}, and either go to the \rcsection{extensions} section
jerojasro@336 270 or create an \rcsection{extensions} section. Then add a line that
jerojasro@336 271 simply reads ``\Verb+fetch +''.
jerojasro@336 272 \begin{codesample2}
jerojasro@336 273 [extensions]
jerojasro@336 274 fetch =
jerojasro@336 275 \end{codesample2}
jerojasro@336 276 (Normally, on the right-hand side of the ``\texttt{=}'' would appear
jerojasro@336 277 the location of the extension, but since the \hgext{fetch} extension
jerojasro@336 278 is in the standard distribution, Mercurial knows where to search for
jerojasro@336 279 it.)
jerojasro@336 280
jerojasro@336 281 %%% Local Variables:
jerojasro@336 282 %%% mode: latex
jerojasro@336 283 %%% TeX-master: "00book"
jerojasro@336 284 %%% End: