*** empty log message ***
[emacs.git] / man / emerge-xtra.texi
blobe78f17e59d6fdadee3cab51ccd32f1102cec1b2b
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
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
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}.
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
37 @node Overview of Emerge
38 @subsection Overview of Emerge
40   To start Emerge, run one of these four commands:
42 @table @kbd
43 @item M-x emerge-files
44 @findex emerge-files
45 Merge two specified files.
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.
51 @item M-x emerge-buffers
52 @findex emerge-buffers
53 Merge two buffers.
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
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.
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
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.
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.
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.
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:
103 @example
104 vvvvvvvvvvvvvvvvvvvv
105 @var{text that differs}
106 ^^^^^^^^^^^^^^^^^^^^
107 @end example
109 @noindent
110 Emerge numbers all the differences sequentially and the mode
111 line always shows the number of the selected difference.
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.
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.
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.
128 @node Submodes of Emerge
129 @subsection Submodes of Emerge
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.
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}.
143   Emerge has two additional submodes that affect how particular merge
144 commands work: Auto Advance mode and Skip Prefers mode.
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}.
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}.
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.
165 @node State of Difference
166 @subsection State of a Difference
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:
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}.
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}.
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).
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.
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.
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.
210 These two states are displayed in the mode line as @samp{A*} and @samp{B*}.
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.
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.
219 The mode line displays this state as @samp{comb}.
220 @end table
222 @node Merge Commands
223 @subsection Merge Commands
225   Here are the Merge commands for Fast mode; in Edit mode, precede them
226 with @kbd{C-c C-c}:
228 @table @kbd
229 @item p
230 Select the previous difference.
232 @item n
233 Select the next difference.
235 @item a
236 Choose the A version of this difference.
238 @item b
239 Choose the B version of this difference.
241 @item C-u @var{n} j
242 Select difference number @var{n}.
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.
248 @item q
249 Quit---finish the merge.
251 @item C-]
252 Abort---exit merging and do not save the output.
254 @item f
255 Go into Fast mode.  (In Edit mode, this is actually @kbd{C-c C-c f}.)
257 @item e
258 Go into Edit mode.
260 @item l
261 Recenter (like @kbd{C-l}) all three windows.
263 @item -
264 Specify part of a prefix numeric argument.
266 @item @var{digit}
267 Also specify part of a prefix numeric argument.
269 @item d a
270 Choose the A version as the default from here down in
271 the merge buffer.
273 @item d b
274 Choose the B version as the default from here down in
275 the merge buffer.
277 @item c a
278 Copy the A version of this difference into the kill ring.
280 @item c b
281 Copy the B version of this difference into the kill ring.
283 @item i a
284 Insert the A version of this difference at point.
286 @item i b
287 Insert the B version of this difference at point.
289 @item m
290 Put point and mark around the difference.
292 @item ^
293 Scroll all three windows down (like @kbd{M-v}).
295 @item v
296 Scroll all three windows up (like @kbd{C-v}).
298 @item <
299 Scroll all three windows left (like @kbd{C-x <}).
301 @item >
302 Scroll all three windows right (like @kbd{C-x >}).
304 @item |
305 Reset horizontal scroll on all three windows.
307 @item x 1
308 Shrink the merge window to one line.  (Use @kbd{C-u l} to restore it
309 to full size.)
311 @item x c
312 Combine the two versions of this difference (@pxref{Combining in
313 Emerge}).
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.)
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.)
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.
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
334 @node Exiting Emerge
335 @subsection Exiting Emerge
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.
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.
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.
352 @node Combining in Emerge
353 @subsection Combining the Two Versions
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:
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
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:
378 @example
379 @group
380 "#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"
381 @end group
382 @end example
384 @node Fine Points of Emerge
385 @subsection Fine Points of Emerge
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.
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.
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.
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
412 @ignore
413    arch-tag: cda63f09-9c5f-4ea1-adb9-4a820fdfb24e
414 @end ignore