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