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