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