Commit | Line | Data |
---|---|---|
6f585e44 | 1 | @c This is part of the Emacs manual. |
68af8d4f | 2 | @c Copyright (C) 2004-2012 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 | |
68af8d4f | 22 | and @ref{Top,, Ediff, ediff, The Ediff Manual}. |
c5184807 EZ |
23 | |
24 | @menu | |
8838673e GM |
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:: Miscellaneous issues. | |
c5184807 EZ |
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 | |
d07e72d3 GM |
152 | skip over differences in states ``prefer-A'' and ``prefer-B'' |
153 | (@pxref{State of Difference}). Thus you see only differences for | |
154 | which neither version is presumed ``correct.'' The mode line | |
155 | indicates Skip Prefers mode with @samp{S}. This mode is only relevant | |
156 | when there is an ancestor. | |
c5184807 | 157 | |
68af8d4f GM |
158 | @findex emerge-auto-advance |
159 | @findex emerge-skip-prefers | |
160 | Use the command @kbd{s a} (@code{emerge-auto-advance}) to set or clear | |
161 | Auto Advance mode. Use @kbd{s s} (@code{emerge-skip-prefers}) to set or | |
162 | clear Skip Prefers mode. These commands turn on the mode with a | |
163 | positive argument, turn it off with a negative or zero argument, and | |
164 | toggle the mode with no argument. | |
c5184807 EZ |
165 | |
166 | @node State of Difference | |
167 | @subsection State of a Difference | |
168 | ||
169 | In the merge buffer, a difference is marked with lines of @samp{v} and | |
170 | @samp{^} characters. Each difference has one of these seven states: | |
171 | ||
172 | @table @asis | |
173 | @item A | |
174 | The difference is showing the A version. The @kbd{a} command always | |
175 | produces this state; the mode line indicates it with @samp{A}. | |
176 | ||
177 | @item B | |
178 | The difference is showing the B version. The @kbd{b} command always | |
179 | produces this state; the mode line indicates it with @samp{B}. | |
180 | ||
181 | @item default-A | |
182 | @itemx default-B | |
183 | The difference is showing the A or the B state by default, because you | |
184 | haven't made a choice. All differences start in the default-A state | |
185 | (and thus the merge buffer is a copy of the A buffer), except those for | |
186 | which one alternative is ``preferred'' (see below). | |
187 | ||
188 | When you select a difference, its state changes from default-A or | |
189 | default-B to plain A or B. Thus, the selected difference never has | |
190 | state default-A or default-B, and these states are never displayed in | |
191 | the mode line. | |
192 | ||
193 | The command @kbd{d a} chooses default-A as the default state, and @kbd{d | |
194 | b} chooses default-B. This chosen default applies to all differences | |
d07e72d3 | 195 | that you have never selected and for which no alternative is preferred. |
c5184807 EZ |
196 | If you are moving through the merge sequentially, the differences you |
197 | haven't selected are those following the selected one. Thus, while | |
198 | moving sequentially, you can effectively make the A version the default | |
199 | for some sections of the merge buffer and the B version the default for | |
200 | others by using @kbd{d a} and @kbd{d b} between sections. | |
201 | ||
202 | @item prefer-A | |
203 | @itemx prefer-B | |
204 | The difference is showing the A or B state because it is | |
205 | @dfn{preferred}. This means that you haven't made an explicit choice, | |
206 | but one alternative seems likely to be right because the other | |
207 | alternative agrees with the common ancestor. Thus, where the A buffer | |
208 | agrees with the common ancestor, the B version is preferred, because | |
209 | chances are it is the one that was actually changed. | |
210 | ||
211 | These two states are displayed in the mode line as @samp{A*} and @samp{B*}. | |
212 | ||
213 | @item combined | |
214 | The difference is showing a combination of the A and B states, as a | |
215 | result of the @kbd{x c} or @kbd{x C} commands. | |
216 | ||
217 | Once a difference is in this state, the @kbd{a} and @kbd{b} commands | |
218 | don't do anything to it unless you give them a numeric argument. | |
219 | ||
220 | The mode line displays this state as @samp{comb}. | |
221 | @end table | |
222 | ||
223 | @node Merge Commands | |
224 | @subsection Merge Commands | |
225 | ||
226 | Here are the Merge commands for Fast mode; in Edit mode, precede them | |
227 | with @kbd{C-c C-c}: | |
228 | ||
229 | @table @kbd | |
230 | @item p | |
231 | Select the previous difference. | |
232 | ||
233 | @item n | |
234 | Select the next difference. | |
235 | ||
236 | @item a | |
237 | Choose the A version of this difference. | |
238 | ||
239 | @item b | |
240 | Choose the B version of this difference. | |
241 | ||
242 | @item C-u @var{n} j | |
243 | Select difference number @var{n}. | |
244 | ||
245 | @item . | |
d07e72d3 GM |
246 | Select the difference containing point. |
247 | @c [Does not work in the A or B buffer?] | |
248 | @c You can use this command in the merge buffer or in the A or B buffer. | |
c5184807 EZ |
249 | |
250 | @item q | |
251 | Quit---finish the merge. | |
252 | ||
253 | @item C-] | |
254 | Abort---exit merging and do not save the output. | |
255 | ||
256 | @item f | |
257 | Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.) | |
258 | ||
259 | @item e | |
260 | Go into Edit mode. | |
261 | ||
262 | @item l | |
d07e72d3 GM |
263 | Recenter (like @kbd{C-l}) all three windows. With an argument, |
264 | reestablish the default three-window display. | |
c5184807 EZ |
265 | |
266 | @item - | |
267 | Specify part of a prefix numeric argument. | |
268 | ||
269 | @item @var{digit} | |
270 | Also specify part of a prefix numeric argument. | |
271 | ||
272 | @item d a | |
273 | Choose the A version as the default from here down in | |
274 | the merge buffer. | |
275 | ||
276 | @item d b | |
277 | Choose the B version as the default from here down in | |
278 | the merge buffer. | |
279 | ||
280 | @item c a | |
281 | Copy the A version of this difference into the kill ring. | |
282 | ||
283 | @item c b | |
284 | Copy the B version of this difference into the kill ring. | |
285 | ||
286 | @item i a | |
287 | Insert the A version of this difference at point. | |
288 | ||
289 | @item i b | |
290 | Insert the B version of this difference at point. | |
291 | ||
292 | @item m | |
293 | Put point and mark around the difference. | |
294 | ||
295 | @item ^ | |
296 | Scroll all three windows down (like @kbd{M-v}). | |
297 | ||
298 | @item v | |
299 | Scroll all three windows up (like @kbd{C-v}). | |
300 | ||
301 | @item < | |
302 | Scroll all three windows left (like @kbd{C-x <}). | |
303 | ||
304 | @item > | |
305 | Scroll all three windows right (like @kbd{C-x >}). | |
306 | ||
307 | @item | | |
308 | Reset horizontal scroll on all three windows. | |
309 | ||
310 | @item x 1 | |
311 | Shrink the merge window to one line. (Use @kbd{C-u l} to restore it | |
312 | to full size.) | |
313 | ||
314 | @item x c | |
315 | Combine the two versions of this difference (@pxref{Combining in | |
316 | Emerge}). | |
317 | ||
318 | @item x f | |
319 | Show the names of the files/buffers Emerge is operating on, in a Help | |
320 | window. (Use @kbd{C-u l} to restore windows.) | |
321 | ||
322 | @item x j | |
323 | Join this difference with the following one. | |
324 | (@kbd{C-u x j} joins this difference with the previous one.) | |
325 | ||
326 | @item x s | |
327 | Split this difference into two differences. Before you use this | |
328 | command, position point in each of the three buffers at the place where | |
329 | you want to split the difference. | |
330 | ||
331 | @item x t | |
332 | Trim identical lines off the top and bottom of the difference. | |
333 | Such lines occur when the A and B versions are | |
334 | identical but differ from the ancestor version. | |
335 | @end table | |
336 | ||
337 | @node Exiting Emerge | |
338 | @subsection Exiting Emerge | |
339 | ||
340 | The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing | |
341 | the results into the output file if you specified one. It restores the | |
342 | A and B buffers to their proper contents, or kills them if they were | |
343 | created by Emerge and you haven't changed them. It also disables the | |
344 | Emerge commands in the merge buffer, since executing them later could | |
345 | damage the contents of the various buffers. | |
346 | ||
347 | @kbd{C-]} aborts the merge. This means exiting without writing the | |
348 | output file. If you didn't specify an output file, then there is no | |
349 | real difference between aborting and finishing the merge. | |
350 | ||
351 | If the Emerge command was called from another Lisp program, then its | |
352 | return value is @code{t} for successful completion, or @code{nil} if you | |
353 | abort. | |
354 | ||
355 | @node Combining in Emerge | |
356 | @subsection Combining the Two Versions | |
357 | ||
358 | Sometimes you want to keep @emph{both} alternatives for a particular | |
359 | difference. To do this, use @kbd{x c}, which edits the merge buffer | |
360 | like this: | |
361 | ||
362 | @example | |
363 | @group | |
364 | #ifdef NEW | |
c5184807 | 365 | @var{version from B buffer} |
68af8d4f GM |
366 | #else /* not NEW */ |
367 | @var{version from A buffer} | |
c5184807 EZ |
368 | #endif /* not NEW */ |
369 | @end group | |
370 | @end example | |
371 | ||
372 | @noindent | |
373 | @vindex emerge-combine-versions-template | |
374 | While this example shows C preprocessor conditionals delimiting the two | |
375 | alternative versions, you can specify the strings to use by setting | |
376 | the variable @code{emerge-combine-versions-template} to a string of your | |
377 | choice. In the string, @samp{%a} says where to put version A, and | |
378 | @samp{%b} says where to put version B. The default setting, which | |
379 | produces the results shown above, looks like this: | |
380 | ||
381 | @example | |
382 | @group | |
68af8d4f | 383 | "#ifdef NEW\n%b#else /* not NEW */\n%a#endif /* not NEW */\n" |
c5184807 EZ |
384 | @end group |
385 | @end example | |
386 | ||
387 | @node Fine Points of Emerge | |
388 | @subsection Fine Points of Emerge | |
389 | ||
390 | During the merge, you mustn't try to edit the A and B buffers yourself. | |
391 | Emerge modifies them temporarily, but ultimately puts them back the way | |
392 | they were. | |
393 | ||
394 | You can have any number of merges going at once---just don't use any one | |
395 | buffer as input to more than one merge at once, since the temporary | |
396 | changes made in these buffers would get in each other's way. | |
397 | ||
398 | Starting Emerge can take a long time because it needs to compare the | |
399 | files fully. Emacs can't do anything else until @code{diff} finishes. | |
400 | Perhaps in the future someone will change Emerge to do the comparison in | |
401 | the background when the input files are large---then you could keep on | |
402 | doing other things with Emacs until Emerge is ready to accept | |
403 | commands. | |
404 | ||
405 | @vindex emerge-startup-hook | |
406 | After setting up the merge, Emerge runs the hook | |
c4945d6a EZ |
407 | @code{emerge-startup-hook}. |
408 | @iftex | |
409 | @xref{Hooks,,, emacs, the Emacs Manual}. | |
410 | @end iftex | |
411 | @ifnottex | |
412 | @xref{Hooks}. | |
413 | @end ifnottex |