Mercurial > emacs
annotate doc/emacs/emerge-xtra.texi @ 109262:51ddcf320fe4
Untabify doc/emacs/*.texi files.
* abbrevs.texi, basic.texi, buffers.texi, building.texi, calendar.texi:
* custom.texi, dired.texi, display.texi, emacs.texi, emerge-xtra.texi:
* files.texi, fortran-xtra.texi, frames.texi, help.texi, killing.texi:
* maintaining.texi, mark.texi, mini.texi, misc.texi, msdog.texi:
* programs.texi, rmail.texi, screen.texi, search.texi, sending.texi:
* text.texi, trouble.texi, vc1-xtra.texi, xresources.texi:
Untabify Texinfo files.
author | Glenn Morris <rgm@gnu.org> |
---|---|
date | Tue, 22 Jun 2010 19:46:43 -0700 |
parents | 1d1d5d9bd884 |
children | 376148b31b5e |
rev | line source |
---|---|
84237 | 1 @c This is part of the Emacs manual. |
109262
51ddcf320fe4
Untabify doc/emacs/*.texi files.
Glenn Morris <rgm@gnu.org>
parents:
106815
diff
changeset
|
2 @c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010 |
51ddcf320fe4
Untabify doc/emacs/*.texi files.
Glenn Morris <rgm@gnu.org>
parents:
106815
diff
changeset
|
3 @c Free Software Foundation, Inc. |
84237 | 4 @c See file emacs.texi for copying conditions. |
5 @c | |
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 | |
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}. | |
24 | |
25 @menu | |
109262
51ddcf320fe4
Untabify doc/emacs/*.texi files.
Glenn Morris <rgm@gnu.org>
parents:
106815
diff
changeset
|
26 * Overview of Emerge:: How to start Emerge. Basic concepts. |
51ddcf320fe4
Untabify doc/emacs/*.texi files.
Glenn Morris <rgm@gnu.org>
parents:
106815
diff
changeset
|
27 * Submodes of Emerge:: Fast mode vs. Edit mode. |
51ddcf320fe4
Untabify doc/emacs/*.texi files.
Glenn Morris <rgm@gnu.org>
parents:
106815
diff
changeset
|
28 Skip Prefers mode and Auto Advance mode. |
51ddcf320fe4
Untabify doc/emacs/*.texi files.
Glenn Morris <rgm@gnu.org>
parents:
106815
diff
changeset
|
29 * State of Difference:: You do the merge by specifying state A or B |
51ddcf320fe4
Untabify doc/emacs/*.texi files.
Glenn Morris <rgm@gnu.org>
parents:
106815
diff
changeset
|
30 for each difference. |
51ddcf320fe4
Untabify doc/emacs/*.texi files.
Glenn Morris <rgm@gnu.org>
parents:
106815
diff
changeset
|
31 * Merge Commands:: Commands for selecting a difference, |
51ddcf320fe4
Untabify doc/emacs/*.texi files.
Glenn Morris <rgm@gnu.org>
parents:
106815
diff
changeset
|
32 changing states of differences, etc. |
51ddcf320fe4
Untabify doc/emacs/*.texi files.
Glenn Morris <rgm@gnu.org>
parents:
106815
diff
changeset
|
33 * Exiting Emerge:: What to do when you've finished the merge. |
51ddcf320fe4
Untabify doc/emacs/*.texi files.
Glenn Morris <rgm@gnu.org>
parents:
106815
diff
changeset
|
34 * Combining in Emerge:: How to keep both alternatives for a difference. |
51ddcf320fe4
Untabify doc/emacs/*.texi files.
Glenn Morris <rgm@gnu.org>
parents:
106815
diff
changeset
|
35 * Fine Points of Emerge:: Miscellaneous issues. |
84237 | 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. | |
73 @iftex | |
74 @xref{Narrowing,,, emacs, the Emacs Manual}. | |
75 @end iftex | |
76 @ifnottex | |
77 @xref{Narrowing}. | |
78 @end ifnottex | |
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 | |
103701
a7852a825f44
(Emerge): Tweak Misc menu description.
Glenn Morris <rgm@gnu.org>
parents:
100974
diff
changeset
|
153 skip over differences in states ``prefer-A'' and ``prefer-B'' |
a7852a825f44
(Emerge): Tweak Misc menu description.
Glenn Morris <rgm@gnu.org>
parents:
100974
diff
changeset
|
154 (@pxref{State of Difference}). Thus you see only differences for |
a7852a825f44
(Emerge): Tweak Misc menu description.
Glenn Morris <rgm@gnu.org>
parents:
100974
diff
changeset
|
155 which neither version is presumed ``correct.'' The mode line |
a7852a825f44
(Emerge): Tweak Misc menu description.
Glenn Morris <rgm@gnu.org>
parents:
100974
diff
changeset
|
156 indicates Skip Prefers mode with @samp{S}. This mode is only relevant |
a7852a825f44
(Emerge): Tweak Misc menu description.
Glenn Morris <rgm@gnu.org>
parents:
100974
diff
changeset
|
157 when there is an ancestor. |
84237 | 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. | |
103701
a7852a825f44
(Emerge): Tweak Misc menu description.
Glenn Morris <rgm@gnu.org>
parents:
100974
diff
changeset
|
164 These commands turn on the mode with a positive argument, turn it off |
84237 | 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 | |
103701
a7852a825f44
(Emerge): Tweak Misc menu description.
Glenn Morris <rgm@gnu.org>
parents:
100974
diff
changeset
|
196 that you have never selected and for which no alternative is preferred. |
84237 | 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 . | |
103701
a7852a825f44
(Emerge): Tweak Misc menu description.
Glenn Morris <rgm@gnu.org>
parents:
100974
diff
changeset
|
247 Select the difference containing point. |
a7852a825f44
(Emerge): Tweak Misc menu description.
Glenn Morris <rgm@gnu.org>
parents:
100974
diff
changeset
|
248 @c [Does not work in the A or B buffer?] |
a7852a825f44
(Emerge): Tweak Misc menu description.
Glenn Morris <rgm@gnu.org>
parents:
100974
diff
changeset
|
249 @c You can use this command in the merge buffer or in the A or B buffer. |
84237 | 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 | |
103701
a7852a825f44
(Emerge): Tweak Misc menu description.
Glenn Morris <rgm@gnu.org>
parents:
100974
diff
changeset
|
264 Recenter (like @kbd{C-l}) all three windows. With an argument, |
a7852a825f44
(Emerge): Tweak Misc menu description.
Glenn Morris <rgm@gnu.org>
parents:
100974
diff
changeset
|
265 reestablish the default three-window display. |
84237 | 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 | |
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 | |
415 | |
416 @ignore | |
417 arch-tag: cda63f09-9c5f-4ea1-adb9-4a820fdfb24e | |
418 @end ignore |