1 @c This is part of the Emacs manual.
2 @c Copyright (C) 2004, 2005, 2006 Free Software Foundation, Inc.
3 @c See file emacs.texi for copying conditions.
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).
8 @section Merging Files with Emerge
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 @ref{Comparing Files,,,
16 emacs, the Emacs Manual} and @ref{Top, Ediff,, ediff, The Ediff
20 * Overview of Emerge:: How to start Emerge. Basic concepts.
21 * Submodes of Emerge:: Fast mode vs. Edit mode.
22 Skip Prefers mode and Auto Advance mode.
23 * State of Difference:: You do the merge by specifying state A or B
25 * Merge Commands:: Commands for selecting a difference,
26 changing states of differences, etc.
27 * Exiting Emerge:: What to do when you've finished the merge.
28 * Combining in Emerge:: How to keep both alternatives for a difference.
29 * Fine Points of Emerge:: Misc.
32 @node Overview of Emerge
33 @subsection Overview of Emerge
35 To start Emerge, run one of these four commands:
38 @item M-x emerge-files
40 Merge two specified files.
42 @item M-x emerge-files-with-ancestor
43 @findex emerge-files-with-ancestor
44 Merge two specified files, with reference to a common ancestor.
46 @item M-x emerge-buffers
47 @findex emerge-buffers
50 @item M-x emerge-buffers-with-ancestor
51 @findex emerge-buffers-with-ancestor
52 Merge two buffers with reference to a common ancestor in a third
56 @cindex merge buffer (Emerge)
57 @cindex A and B buffers (Emerge)
58 The Emerge commands compare two files or buffers, and display the
59 comparison in three buffers: one for each input text (the @dfn{A buffer}
60 and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging
61 takes place. The merge buffer shows the full merged text, not just the
62 differences. Wherever the two input texts differ, you can choose which
63 one of them to include in the merge buffer.
65 The Emerge commands that take input from existing buffers use only
66 the accessible portions of those buffers, if they are narrowed.
67 @xref{Narrowing,,, emacs, the Emacs Manual}.
70 If a common ancestor version is available, from which the two texts to
71 be merged were both derived, Emerge can use it to guess which
72 alternative is right. Wherever one current version agrees with the
73 ancestor, Emerge presumes that the other current version is a deliberate
74 change which should be kept in the merged version. Use the
75 @samp{with-ancestor} commands if you want to specify a common ancestor
76 text. These commands read three file or buffer names---variant A,
77 variant B, and the common ancestor.
79 After the comparison is done and the buffers are prepared, the
80 interactive merging starts. You control the merging by typing special
81 @dfn{merge commands} in the merge buffer (@pxref{Merge Commands}).
82 For each run of differences between the input texts, you can choose
83 which one of them to keep, or edit them both together.
85 The merge buffer uses a special major mode, Emerge mode, with commands
86 for making these choices. But you can also edit the buffer with
87 ordinary Emacs commands.
89 At any given time, the attention of Emerge is focused on one
90 particular difference, called the @dfn{selected} difference. This
91 difference is marked off in the three buffers like this:
95 @var{text that differs}
100 Emerge numbers all the differences sequentially and the mode
101 line always shows the number of the selected difference.
103 Normally, the merge buffer starts out with the A version of the text.
104 But when the A version of a difference agrees with the common ancestor,
105 then the B version is initially preferred for that difference.
107 Emerge leaves the merged text in the merge buffer when you exit. At
108 that point, you can save it in a file with @kbd{C-x C-w}. If you give a
109 numeric argument to @code{emerge-files} or
110 @code{emerge-files-with-ancestor}, it reads the name of the output file
111 using the minibuffer. (This is the last file name those commands read.)
112 Then exiting from Emerge saves the merged text in the output file.
114 Normally, Emerge commands save the output buffer in its file when you
115 exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not
116 save the output buffer, but you can save it yourself if you wish.
118 @node Submodes of Emerge
119 @subsection Submodes of Emerge
121 You can choose between two modes for giving merge commands: Fast mode
122 and Edit mode. In Fast mode, basic merge commands are single
123 characters, but ordinary Emacs commands are disabled. This is
124 convenient if you use only merge commands. In Edit mode, all merge
125 commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs
126 commands are also available. This allows editing the merge buffer, but
127 slows down Emerge operations.
129 Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to
130 Fast mode. The mode line indicates Edit and Fast modes with @samp{E}
133 Emerge has two additional submodes that affect how particular merge
134 commands work: Auto Advance mode and Skip Prefers mode.
136 If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands
137 advance to the next difference. This lets you go through the merge
138 faster as long as you simply choose one of the alternatives from the
139 input. The mode line indicates Auto Advance mode with @samp{A}.
141 If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands
142 skip over differences in states prefer-A and prefer-B (@pxref{State of
143 Difference}). Thus you see only differences for which neither version
144 is presumed ``correct.'' The mode line indicates Skip Prefers mode with
147 @findex emerge-auto-advance-mode
148 @findex emerge-skip-prefers-mode
149 Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or
150 clear Auto Advance mode. Use @kbd{s s}
151 (@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode.
152 These commands turn on the mode with a positive argument, turns it off
153 with a negative or zero argument, and toggle the mode with no argument.
155 @node State of Difference
156 @subsection State of a Difference
158 In the merge buffer, a difference is marked with lines of @samp{v} and
159 @samp{^} characters. Each difference has one of these seven states:
163 The difference is showing the A version. The @kbd{a} command always
164 produces this state; the mode line indicates it with @samp{A}.
167 The difference is showing the B version. The @kbd{b} command always
168 produces this state; the mode line indicates it with @samp{B}.
172 The difference is showing the A or the B state by default, because you
173 haven't made a choice. All differences start in the default-A state
174 (and thus the merge buffer is a copy of the A buffer), except those for
175 which one alternative is ``preferred'' (see below).
177 When you select a difference, its state changes from default-A or
178 default-B to plain A or B. Thus, the selected difference never has
179 state default-A or default-B, and these states are never displayed in
182 The command @kbd{d a} chooses default-A as the default state, and @kbd{d
183 b} chooses default-B. This chosen default applies to all differences
184 which you haven't ever selected and for which no alternative is preferred.
185 If you are moving through the merge sequentially, the differences you
186 haven't selected are those following the selected one. Thus, while
187 moving sequentially, you can effectively make the A version the default
188 for some sections of the merge buffer and the B version the default for
189 others by using @kbd{d a} and @kbd{d b} between sections.
193 The difference is showing the A or B state because it is
194 @dfn{preferred}. This means that you haven't made an explicit choice,
195 but one alternative seems likely to be right because the other
196 alternative agrees with the common ancestor. Thus, where the A buffer
197 agrees with the common ancestor, the B version is preferred, because
198 chances are it is the one that was actually changed.
200 These two states are displayed in the mode line as @samp{A*} and @samp{B*}.
203 The difference is showing a combination of the A and B states, as a
204 result of the @kbd{x c} or @kbd{x C} commands.
206 Once a difference is in this state, the @kbd{a} and @kbd{b} commands
207 don't do anything to it unless you give them a numeric argument.
209 The mode line displays this state as @samp{comb}.
213 @subsection Merge Commands
215 Here are the Merge commands for Fast mode; in Edit mode, precede them
220 Select the previous difference.
223 Select the next difference.
226 Choose the A version of this difference.
229 Choose the B version of this difference.
232 Select difference number @var{n}.
235 Select the difference containing point. You can use this command in the
236 merge buffer or in the A or B buffer.
239 Quit---finish the merge.
242 Abort---exit merging and do not save the output.
245 Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.)
251 Recenter (like @kbd{C-l}) all three windows.
254 Specify part of a prefix numeric argument.
257 Also specify part of a prefix numeric argument.
260 Choose the A version as the default from here down in
264 Choose the B version as the default from here down in
268 Copy the A version of this difference into the kill ring.
271 Copy the B version of this difference into the kill ring.
274 Insert the A version of this difference at point.
277 Insert the B version of this difference at point.
280 Put point and mark around the difference.
283 Scroll all three windows down (like @kbd{M-v}).
286 Scroll all three windows up (like @kbd{C-v}).
289 Scroll all three windows left (like @kbd{C-x <}).
292 Scroll all three windows right (like @kbd{C-x >}).
295 Reset horizontal scroll on all three windows.
298 Shrink the merge window to one line. (Use @kbd{C-u l} to restore it
302 Combine the two versions of this difference (@pxref{Combining in
306 Show the names of the files/buffers Emerge is operating on, in a Help
307 window. (Use @kbd{C-u l} to restore windows.)
310 Join this difference with the following one.
311 (@kbd{C-u x j} joins this difference with the previous one.)
314 Split this difference into two differences. Before you use this
315 command, position point in each of the three buffers at the place where
316 you want to split the difference.
319 Trim identical lines off the top and bottom of the difference.
320 Such lines occur when the A and B versions are
321 identical but differ from the ancestor version.
325 @subsection Exiting Emerge
327 The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing
328 the results into the output file if you specified one. It restores the
329 A and B buffers to their proper contents, or kills them if they were
330 created by Emerge and you haven't changed them. It also disables the
331 Emerge commands in the merge buffer, since executing them later could
332 damage the contents of the various buffers.
334 @kbd{C-]} aborts the merge. This means exiting without writing the
335 output file. If you didn't specify an output file, then there is no
336 real difference between aborting and finishing the merge.
338 If the Emerge command was called from another Lisp program, then its
339 return value is @code{t} for successful completion, or @code{nil} if you
342 @node Combining in Emerge
343 @subsection Combining the Two Versions
345 Sometimes you want to keep @emph{both} alternatives for a particular
346 difference. To do this, use @kbd{x c}, which edits the merge buffer
352 @var{version from A buffer}
354 @var{version from B buffer}
360 @vindex emerge-combine-versions-template
361 While this example shows C preprocessor conditionals delimiting the two
362 alternative versions, you can specify the strings to use by setting
363 the variable @code{emerge-combine-versions-template} to a string of your
364 choice. In the string, @samp{%a} says where to put version A, and
365 @samp{%b} says where to put version B. The default setting, which
366 produces the results shown above, looks like this:
370 "#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"
374 @node Fine Points of Emerge
375 @subsection Fine Points of Emerge
377 During the merge, you mustn't try to edit the A and B buffers yourself.
378 Emerge modifies them temporarily, but ultimately puts them back the way
381 You can have any number of merges going at once---just don't use any one
382 buffer as input to more than one merge at once, since the temporary
383 changes made in these buffers would get in each other's way.
385 Starting Emerge can take a long time because it needs to compare the
386 files fully. Emacs can't do anything else until @code{diff} finishes.
387 Perhaps in the future someone will change Emerge to do the comparison in
388 the background when the input files are large---then you could keep on
389 doing other things with Emacs until Emerge is ready to accept
392 @vindex emerge-startup-hook
393 After setting up the merge, Emerge runs the hook
394 @code{emerge-startup-hook}. @xref{Hooks,,, emacs, the Emacs Manual}.
397 arch-tag: cda63f09-9c5f-4ea1-adb9-4a820fdfb24e