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