Commit | Line | Data |
---|---|---|
6f585e44 | 1 | @c This is part of the Emacs manual. |
73b0cd50 | 2 | @c Copyright (C) 2004-2011 |
8838673e | 3 | @c Free Software Foundation, Inc. |
6f585e44 EZ |
4 | @c See file emacs.texi for copying conditions. |
5 | @c | |
c5184807 EZ |
6 | @c This file is included either in emacs-xtra.texi (when producing the |
7 | @c printed version) or in the main Emacs manual (for the on-line version). | |
8 | @node Emerge | |
9 | @section Merging Files with Emerge | |
10 | @cindex Emerge | |
11 | @cindex merging files | |
12 | ||
13 | It's not unusual for programmers to get their signals crossed and | |
14 | modify the same program in two different directions. To recover from | |
15 | this confusion, you need to merge the two versions. Emerge makes this | |
c4945d6a EZ |
16 | easier. For other ways to compare files, see |
17 | @iftex | |
18 | @ref{Comparing Files,,, emacs, the Emacs Manual}, | |
19 | @end iftex | |
20 | @ifnottex | |
21 | @ref{Comparing Files}, | |
22 | @end ifnottex | |
23 | and @ref{Top, Ediff,, ediff, The Ediff Manual}. | |
c5184807 EZ |
24 | |
25 | @menu | |
8838673e GM |
26 | * Overview of Emerge:: How to start Emerge. Basic concepts. |
27 | * Submodes of Emerge:: Fast mode vs. Edit mode. | |
28 | Skip Prefers mode and Auto Advance mode. | |
29 | * State of Difference:: You do the merge by specifying state A or B | |
30 | for each difference. | |
31 | * Merge Commands:: Commands for selecting a difference, | |
32 | changing states of differences, etc. | |
33 | * Exiting Emerge:: What to do when you've finished the merge. | |
34 | * Combining in Emerge:: How to keep both alternatives for a difference. | |
35 | * Fine Points of Emerge:: Miscellaneous issues. | |
c5184807 EZ |
36 | @end menu |
37 | ||
38 | @node Overview of Emerge | |
39 | @subsection Overview of Emerge | |
40 | ||
41 | To start Emerge, run one of these four commands: | |
42 | ||
43 | @table @kbd | |
44 | @item M-x emerge-files | |
45 | @findex emerge-files | |
46 | Merge two specified files. | |
47 | ||
48 | @item M-x emerge-files-with-ancestor | |
49 | @findex emerge-files-with-ancestor | |
50 | Merge two specified files, with reference to a common ancestor. | |
51 | ||
52 | @item M-x emerge-buffers | |
53 | @findex emerge-buffers | |
54 | Merge two buffers. | |
55 | ||
56 | @item M-x emerge-buffers-with-ancestor | |
57 | @findex emerge-buffers-with-ancestor | |
58 | Merge two buffers with reference to a common ancestor in a third | |
59 | buffer. | |
60 | @end table | |
61 | ||
62 | @cindex merge buffer (Emerge) | |
63 | @cindex A and B buffers (Emerge) | |
64 | The Emerge commands compare two files or buffers, and display the | |
65 | comparison in three buffers: one for each input text (the @dfn{A buffer} | |
66 | and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging | |
67 | takes place. The merge buffer shows the full merged text, not just the | |
68 | differences. Wherever the two input texts differ, you can choose which | |
69 | one of them to include in the merge buffer. | |
70 | ||
71 | The Emerge commands that take input from existing buffers use only | |
72 | the accessible portions of those buffers, if they are narrowed. | |
c4945d6a | 73 | @iftex |
c5184807 | 74 | @xref{Narrowing,,, emacs, the Emacs Manual}. |
c4945d6a EZ |
75 | @end iftex |
76 | @ifnottex | |
77 | @xref{Narrowing}. | |
78 | @end ifnottex | |
c5184807 EZ |
79 | |
80 | ||
81 | If a common ancestor version is available, from which the two texts to | |
82 | be merged were both derived, Emerge can use it to guess which | |
83 | alternative is right. Wherever one current version agrees with the | |
84 | ancestor, Emerge presumes that the other current version is a deliberate | |
85 | change which should be kept in the merged version. Use the | |
86 | @samp{with-ancestor} commands if you want to specify a common ancestor | |
87 | text. These commands read three file or buffer names---variant A, | |
88 | variant B, and the common ancestor. | |
89 | ||
90 | After the comparison is done and the buffers are prepared, the | |
91 | interactive merging starts. You control the merging by typing special | |
92 | @dfn{merge commands} in the merge buffer (@pxref{Merge Commands}). | |
93 | For each run of differences between the input texts, you can choose | |
94 | which one of them to keep, or edit them both together. | |
95 | ||
96 | The merge buffer uses a special major mode, Emerge mode, with commands | |
97 | for making these choices. But you can also edit the buffer with | |
98 | ordinary Emacs commands. | |
99 | ||
100 | At any given time, the attention of Emerge is focused on one | |
101 | particular difference, called the @dfn{selected} difference. This | |
102 | difference is marked off in the three buffers like this: | |
103 | ||
104 | @example | |
105 | vvvvvvvvvvvvvvvvvvvv | |
106 | @var{text that differs} | |
107 | ^^^^^^^^^^^^^^^^^^^^ | |
108 | @end example | |
109 | ||
110 | @noindent | |
111 | Emerge numbers all the differences sequentially and the mode | |
112 | line always shows the number of the selected difference. | |
113 | ||
114 | Normally, the merge buffer starts out with the A version of the text. | |
115 | But when the A version of a difference agrees with the common ancestor, | |
116 | then the B version is initially preferred for that difference. | |
117 | ||
118 | Emerge leaves the merged text in the merge buffer when you exit. At | |
119 | that point, you can save it in a file with @kbd{C-x C-w}. If you give a | |
120 | numeric argument to @code{emerge-files} or | |
121 | @code{emerge-files-with-ancestor}, it reads the name of the output file | |
122 | using the minibuffer. (This is the last file name those commands read.) | |
123 | Then exiting from Emerge saves the merged text in the output file. | |
124 | ||
125 | Normally, Emerge commands save the output buffer in its file when you | |
126 | exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not | |
127 | save the output buffer, but you can save it yourself if you wish. | |
128 | ||
129 | @node Submodes of Emerge | |
130 | @subsection Submodes of Emerge | |
131 | ||
132 | You can choose between two modes for giving merge commands: Fast mode | |
133 | and Edit mode. In Fast mode, basic merge commands are single | |
134 | characters, but ordinary Emacs commands are disabled. This is | |
135 | convenient if you use only merge commands. In Edit mode, all merge | |
136 | commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs | |
137 | commands are also available. This allows editing the merge buffer, but | |
138 | slows down Emerge operations. | |
139 | ||
140 | Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to | |
141 | Fast mode. The mode line indicates Edit and Fast modes with @samp{E} | |
142 | and @samp{F}. | |
143 | ||
144 | Emerge has two additional submodes that affect how particular merge | |
145 | commands work: Auto Advance mode and Skip Prefers mode. | |
146 | ||
147 | If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands | |
148 | advance to the next difference. This lets you go through the merge | |
149 | faster as long as you simply choose one of the alternatives from the | |
150 | input. The mode line indicates Auto Advance mode with @samp{A}. | |
151 | ||
152 | If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands | |
d07e72d3 GM |
153 | skip over differences in states ``prefer-A'' and ``prefer-B'' |
154 | (@pxref{State of Difference}). Thus you see only differences for | |
155 | which neither version is presumed ``correct.'' The mode line | |
156 | indicates Skip Prefers mode with @samp{S}. This mode is only relevant | |
157 | when there is an ancestor. | |
c5184807 EZ |
158 | |
159 | @findex emerge-auto-advance-mode | |
160 | @findex emerge-skip-prefers-mode | |
161 | Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or | |
162 | clear Auto Advance mode. Use @kbd{s s} | |
163 | (@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode. | |
d07e72d3 | 164 | These commands turn on the mode with a positive argument, turn it off |
c5184807 EZ |
165 | with a negative or zero argument, and toggle the mode with no argument. |
166 | ||
167 | @node State of Difference | |
168 | @subsection State of a Difference | |
169 | ||
170 | In the merge buffer, a difference is marked with lines of @samp{v} and | |
171 | @samp{^} characters. Each difference has one of these seven states: | |
172 | ||
173 | @table @asis | |
174 | @item A | |
175 | The difference is showing the A version. The @kbd{a} command always | |
176 | produces this state; the mode line indicates it with @samp{A}. | |
177 | ||
178 | @item B | |
179 | The difference is showing the B version. The @kbd{b} command always | |
180 | produces this state; the mode line indicates it with @samp{B}. | |
181 | ||
182 | @item default-A | |
183 | @itemx default-B | |
184 | The difference is showing the A or the B state by default, because you | |
185 | haven't made a choice. All differences start in the default-A state | |
186 | (and thus the merge buffer is a copy of the A buffer), except those for | |
187 | which one alternative is ``preferred'' (see below). | |
188 | ||
189 | When you select a difference, its state changes from default-A or | |
190 | default-B to plain A or B. Thus, the selected difference never has | |
191 | state default-A or default-B, and these states are never displayed in | |
192 | the mode line. | |
193 | ||
194 | The command @kbd{d a} chooses default-A as the default state, and @kbd{d | |
195 | b} chooses default-B. This chosen default applies to all differences | |
d07e72d3 | 196 | that you have never selected and for which no alternative is preferred. |
c5184807 EZ |
197 | If you are moving through the merge sequentially, the differences you |
198 | haven't selected are those following the selected one. Thus, while | |
199 | moving sequentially, you can effectively make the A version the default | |
200 | for some sections of the merge buffer and the B version the default for | |
201 | others by using @kbd{d a} and @kbd{d b} between sections. | |
202 | ||
203 | @item prefer-A | |
204 | @itemx prefer-B | |
205 | The difference is showing the A or B state because it is | |
206 | @dfn{preferred}. This means that you haven't made an explicit choice, | |
207 | but one alternative seems likely to be right because the other | |
208 | alternative agrees with the common ancestor. Thus, where the A buffer | |
209 | agrees with the common ancestor, the B version is preferred, because | |
210 | chances are it is the one that was actually changed. | |
211 | ||
212 | These two states are displayed in the mode line as @samp{A*} and @samp{B*}. | |
213 | ||
214 | @item combined | |
215 | The difference is showing a combination of the A and B states, as a | |
216 | result of the @kbd{x c} or @kbd{x C} commands. | |
217 | ||
218 | Once a difference is in this state, the @kbd{a} and @kbd{b} commands | |
219 | don't do anything to it unless you give them a numeric argument. | |
220 | ||
221 | The mode line displays this state as @samp{comb}. | |
222 | @end table | |
223 | ||
224 | @node Merge Commands | |
225 | @subsection Merge Commands | |
226 | ||
227 | Here are the Merge commands for Fast mode; in Edit mode, precede them | |
228 | with @kbd{C-c C-c}: | |
229 | ||
230 | @table @kbd | |
231 | @item p | |
232 | Select the previous difference. | |
233 | ||
234 | @item n | |
235 | Select the next difference. | |
236 | ||
237 | @item a | |
238 | Choose the A version of this difference. | |
239 | ||
240 | @item b | |
241 | Choose the B version of this difference. | |
242 | ||
243 | @item C-u @var{n} j | |
244 | Select difference number @var{n}. | |
245 | ||
246 | @item . | |
d07e72d3 GM |
247 | Select the difference containing point. |
248 | @c [Does not work in the A or B buffer?] | |
249 | @c You can use this command in the merge buffer or in the A or B buffer. | |
c5184807 EZ |
250 | |
251 | @item q | |
252 | Quit---finish the merge. | |
253 | ||
254 | @item C-] | |
255 | Abort---exit merging and do not save the output. | |
256 | ||
257 | @item f | |
258 | Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.) | |
259 | ||
260 | @item e | |
261 | Go into Edit mode. | |
262 | ||
263 | @item l | |
d07e72d3 GM |
264 | Recenter (like @kbd{C-l}) all three windows. With an argument, |
265 | reestablish the default three-window display. | |
c5184807 EZ |
266 | |
267 | @item - | |
268 | Specify part of a prefix numeric argument. | |
269 | ||
270 | @item @var{digit} | |
271 | Also specify part of a prefix numeric argument. | |
272 | ||
273 | @item d a | |
274 | Choose the A version as the default from here down in | |
275 | the merge buffer. | |
276 | ||
277 | @item d b | |
278 | Choose the B version as the default from here down in | |
279 | the merge buffer. | |
280 | ||
281 | @item c a | |
282 | Copy the A version of this difference into the kill ring. | |
283 | ||
284 | @item c b | |
285 | Copy the B version of this difference into the kill ring. | |
286 | ||
287 | @item i a | |
288 | Insert the A version of this difference at point. | |
289 | ||
290 | @item i b | |
291 | Insert the B version of this difference at point. | |
292 | ||
293 | @item m | |
294 | Put point and mark around the difference. | |
295 | ||
296 | @item ^ | |
297 | Scroll all three windows down (like @kbd{M-v}). | |
298 | ||
299 | @item v | |
300 | Scroll all three windows up (like @kbd{C-v}). | |
301 | ||
302 | @item < | |
303 | Scroll all three windows left (like @kbd{C-x <}). | |
304 | ||
305 | @item > | |
306 | Scroll all three windows right (like @kbd{C-x >}). | |
307 | ||
308 | @item | | |
309 | Reset horizontal scroll on all three windows. | |
310 | ||
311 | @item x 1 | |
312 | Shrink the merge window to one line. (Use @kbd{C-u l} to restore it | |
313 | to full size.) | |
314 | ||
315 | @item x c | |
316 | Combine the two versions of this difference (@pxref{Combining in | |
317 | Emerge}). | |
318 | ||
319 | @item x f | |
320 | Show the names of the files/buffers Emerge is operating on, in a Help | |
321 | window. (Use @kbd{C-u l} to restore windows.) | |
322 | ||
323 | @item x j | |
324 | Join this difference with the following one. | |
325 | (@kbd{C-u x j} joins this difference with the previous one.) | |
326 | ||
327 | @item x s | |
328 | Split this difference into two differences. Before you use this | |
329 | command, position point in each of the three buffers at the place where | |
330 | you want to split the difference. | |
331 | ||
332 | @item x t | |
333 | Trim identical lines off the top and bottom of the difference. | |
334 | Such lines occur when the A and B versions are | |
335 | identical but differ from the ancestor version. | |
336 | @end table | |
337 | ||
338 | @node Exiting Emerge | |
339 | @subsection Exiting Emerge | |
340 | ||
341 | The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing | |
342 | the results into the output file if you specified one. It restores the | |
343 | A and B buffers to their proper contents, or kills them if they were | |
344 | created by Emerge and you haven't changed them. It also disables the | |
345 | Emerge commands in the merge buffer, since executing them later could | |
346 | damage the contents of the various buffers. | |
347 | ||
348 | @kbd{C-]} aborts the merge. This means exiting without writing the | |
349 | output file. If you didn't specify an output file, then there is no | |
350 | real difference between aborting and finishing the merge. | |
351 | ||
352 | If the Emerge command was called from another Lisp program, then its | |
353 | return value is @code{t} for successful completion, or @code{nil} if you | |
354 | abort. | |
355 | ||
356 | @node Combining in Emerge | |
357 | @subsection Combining the Two Versions | |
358 | ||
359 | Sometimes you want to keep @emph{both} alternatives for a particular | |
360 | difference. To do this, use @kbd{x c}, which edits the merge buffer | |
361 | like this: | |
362 | ||
363 | @example | |
364 | @group | |
365 | #ifdef NEW | |
366 | @var{version from A buffer} | |
367 | #else /* not NEW */ | |
368 | @var{version from B buffer} | |
369 | #endif /* not NEW */ | |
370 | @end group | |
371 | @end example | |
372 | ||
373 | @noindent | |
374 | @vindex emerge-combine-versions-template | |
375 | While this example shows C preprocessor conditionals delimiting the two | |
376 | alternative versions, you can specify the strings to use by setting | |
377 | the variable @code{emerge-combine-versions-template} to a string of your | |
378 | choice. In the string, @samp{%a} says where to put version A, and | |
379 | @samp{%b} says where to put version B. The default setting, which | |
380 | produces the results shown above, looks like this: | |
381 | ||
382 | @example | |
383 | @group | |
384 | "#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n" | |
385 | @end group | |
386 | @end example | |
387 | ||
388 | @node Fine Points of Emerge | |
389 | @subsection Fine Points of Emerge | |
390 | ||
391 | During the merge, you mustn't try to edit the A and B buffers yourself. | |
392 | Emerge modifies them temporarily, but ultimately puts them back the way | |
393 | they were. | |
394 | ||
395 | You can have any number of merges going at once---just don't use any one | |
396 | buffer as input to more than one merge at once, since the temporary | |
397 | changes made in these buffers would get in each other's way. | |
398 | ||
399 | Starting Emerge can take a long time because it needs to compare the | |
400 | files fully. Emacs can't do anything else until @code{diff} finishes. | |
401 | Perhaps in the future someone will change Emerge to do the comparison in | |
402 | the background when the input files are large---then you could keep on | |
403 | doing other things with Emacs until Emerge is ready to accept | |
404 | commands. | |
405 | ||
406 | @vindex emerge-startup-hook | |
407 | After setting up the merge, Emerge runs the hook | |
c4945d6a EZ |
408 | @code{emerge-startup-hook}. |
409 | @iftex | |
410 | @xref{Hooks,,, emacs, the Emacs Manual}. | |
411 | @end iftex | |
412 | @ifnottex | |
413 | @xref{Hooks}. | |
414 | @end ifnottex |