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