84237
|
1 @c This is part of the Emacs manual.
|
100974
|
2 @c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
|
84237
|
3 @c See file emacs.texi for copying conditions.
|
|
4 @c
|
|
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
|
|
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}.
|
|
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.
|
|
72 @iftex
|
|
73 @xref{Narrowing,,, emacs, the Emacs Manual}.
|
|
74 @end iftex
|
|
75 @ifnottex
|
|
76 @xref{Narrowing}.
|
|
77 @end ifnottex
|
|
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
|
|
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
|
|
411
|
|
412 @ignore
|
|
413 arch-tag: cda63f09-9c5f-4ea1-adb9-4a820fdfb24e
|
|
414 @end ignore
|