|
0
|
1
|
|
|
2 This is the documentation for version 5 of "emerge.el", an Emacs
|
|
|
3 package that allows you to combine two versions of a file by
|
|
|
4 selecting, for each place where they differ, which version of the
|
|
|
5 difference you prefer. It is similar to Sun's "filemerge".
|
|
|
6
|
|
|
7 Written by Dale R. Worley <drw@math.mit.edu>.
|
|
|
8
|
|
|
9 WARRANTY DISCLAIMER
|
|
|
10
|
|
|
11 This software was created by Dale R. Worley and is
|
|
|
12 distributed free of charge. It is placed in the public domain and
|
|
|
13 permission is granted to anyone to use, duplicate, modify and redistribute
|
|
|
14 it provided that this notice is attached.
|
|
|
15
|
|
|
16 Dale R. Worley provides absolutely NO WARRANTY OF ANY KIND
|
|
|
17 with respect to this software. The entire risk as to the quality and
|
|
|
18 performance of this software is with the user. IN NO EVENT WILL DALE
|
|
|
19 R. WORLEY BE LIABLE TO ANYONE FOR ANY DAMAGES ARISING OUT THE
|
|
|
20 USE OF THIS SOFTWARE, INCLUDING, WITHOUT LIMITATION, DAMAGES RESULTING FROM
|
|
|
21 LOST DATA OR LOST PROFITS, OR FOR ANY SPECIAL, INCIDENTAL OR CONSEQUENTIAL
|
|
|
22 DAMAGES.
|
|
|
23
|
|
|
24 ;; LCD Archive Entry:
|
|
|
25 ;; emerge|Dale R. Worley|drw@math.mit.edu
|
|
|
26 ;; |File merge documentation
|
|
|
27 ;; |92-12-11|version 5 gamma|~/packages/emerge.doc.Z
|
|
|
28
|
|
|
29 - Changes from version 4 to version 5
|
|
|
30
|
|
|
31 Put in improved disclaimer of copyright and warranty.
|
|
|
32
|
|
|
33 Document autoload for emerge-execute-line.
|
|
|
34
|
|
|
35 Changes to support use with Ange-FTP.
|
|
|
36
|
|
|
37 Allow filenames containing shell metacharacters to be handled unscathed.
|
|
|
38
|
|
|
39 Certain internal problems were fixed so that bugs in "x s", "x j", and
|
|
|
40 "x t" were eliminated.
|
|
|
41
|
|
|
42 Non-existent and non-readable file names are rejected, even if Emerge
|
|
|
43 is called non-interactively.
|
|
|
44
|
|
|
45 Add code to process the local-variables list in newly created merge
|
|
|
46 buffers.
|
|
|
47
|
|
|
48 Add changes made by David Gudeman to allow the default directory for
|
|
|
49 arguments to the emerge-files commands to be the directory of the
|
|
|
50 argument of that type to the last emerge-files command. See "Default
|
|
|
51 directories" below.
|
|
|
52
|
|
|
53 Add emerge-process-line command to allow semi-automatic batching of
|
|
|
54 merges.
|
|
|
55
|
|
|
56 Add David Gudeman's facility for merging RCS revisions of a file.
|
|
|
57
|
|
|
58 Add a few hooks to make customization easier.
|
|
|
59
|
|
|
60 Still no Epoch support in this version, though. Talk to Dan Pierson
|
|
|
61 <pierson@xenna.encore.com> or check epoch-emerge-patch.el in the Emacs
|
|
|
62 Lisp Directory if you want Epoch support.
|
|
|
63
|
|
|
64 And the document still isn't in TeXinfo format.
|
|
|
65
|
|
|
66 - Changes from version 3 to version 4
|
|
|
67
|
|
|
68 More configuration variables are marked as user options.
|
|
|
69
|
|
|
70 Code is included for an improved version of make-auto-save-file-name
|
|
|
71 which eliminates many problems with the default version. See the
|
|
|
72 documentation of emerge-make-auto-save-file-name to see how to
|
|
|
73 activate it.
|
|
|
74
|
|
|
75 Emerge now works with Gnu diff3, which can produce the groups of lines
|
|
|
76 from the various files in the order 1, 2, 3 or 1, 3, 2.
|
|
|
77
|
|
|
78 Add "x f" command to show what files or buffers are being operated on.
|
|
|
79
|
|
|
80 The merge buffer now starts read-only, which being in fast mode it
|
|
|
81 should be.
|
|
|
82
|
|
|
83 When merging buffers, Emerge writes their contents into temporary
|
|
|
84 files in the directory $TMPDIR (if it is defined), or /tmp by default.
|
|
|
85
|
|
|
86 Add "x j" command to join two differences.
|
|
|
87
|
|
|
88 Add "x s" command to split a difference into two differences.
|
|
|
89
|
|
|
90 Add emerge-version variable and function to report the version of Emerge
|
|
|
91 being run.
|
|
|
92
|
|
|
93 Add "x t" command to trim unchanged lines off top and bottom of
|
|
|
94 difference region.
|
|
|
95
|
|
|
96 Add "x d", "x a", and "x b" commands to locate the differences at or
|
|
|
97 near a given location in one of the buffers.
|
|
|
98
|
|
|
99 Emerge no longer tries to copy the minor modes from the A buffer to
|
|
|
100 the merge buffer, only the major mode.
|
|
|
101
|
|
|
102 The programs executed to find the differences between versions of the file
|
|
|
103 are no longer controlled by emerge-diff/diff3-command, but rather by:
|
|
|
104 emerge-diff-program
|
|
|
105 Variable: *Name of the program which compares two files.
|
|
|
106 emerge-diff3-program
|
|
|
107 Variable: *Name of the program which compares an ancestor file
|
|
|
108 (first argument) and two variant files (second and third arguments).
|
|
|
109 emerge-diff-options
|
|
|
110 Variable: *Options to be passed to emerge-diff/diff3-program.
|
|
|
111
|
|
|
112 The names of the files are expanded (see expand-file-name) before being
|
|
|
113 passed to emerge-diff/diff3-program, so diff need not invoked under a shell
|
|
|
114 that understands '~', for instance.
|
|
|
115
|
|
|
116 If the diff/diff3 program reports errors, the user is notified and the
|
|
|
117 errors are displayed.
|
|
|
118
|
|
|
119 The command "0j" can be used to suppress the flags from showing in the
|
|
|
120 buffers.
|
|
|
121
|
|
|
122 A discussion of the effect of the merge flags on indentation of code
|
|
|
123 has been added to the documentation.
|
|
|
124
|
|
|
125 If kill-fix.el is loaded, Emerge control variables now have their
|
|
|
126 'preserved' property set, so setting the major mode in the merge
|
|
|
127 buffer doesn't destroy Emerge's state.
|
|
|
128
|
|
|
129 Add "x c", "x C", and "x x" commands to allow the A and B versions to be
|
|
|
130 combined into #ifdef - #endif forms.
|
|
|
131
|
|
|
132 Replaced calls of "ding" to calls of "error" where appropriate.
|
|
|
133
|
|
|
134 Add "x m" command to allow major mode of merge buffer to be changed.
|
|
|
135
|
|
|
136 Add "x 1" command to shrink the merge window to one line.
|
|
|
137
|
|
|
138 Add emerge-startup-hooks to allow customization.
|
|
|
139
|
|
|
140 Fixed a bug that is activated when a remote merge request is made when
|
|
|
141 the minibuffer window is selected.
|
|
|
142
|
|
|
143 - Changes from version 2 to version 3
|
|
|
144
|
|
|
145 The directory into which temporary files are written is now controlled
|
|
|
146 by a user option (emerge-temp-file-prefix).
|
|
|
147
|
|
|
148 The A and B versions of the difference can be loaded into the kill
|
|
|
149 ring with the "c a" and "c b" commands.
|
|
|
150
|
|
|
151 The A and B versions of the difference can be inserted into the merge
|
|
|
152 buffer with the "i a" and "i b" commands.
|
|
|
153
|
|
|
154 The difference region of the merge buffer can be surrounded by the
|
|
|
155 point and mark with the "m" command.
|
|
|
156
|
|
|
157 The three windows can be scrolled together with the "^", "v", "<",
|
|
|
158 ">", and "|" commands.
|
|
|
159
|
|
|
160 The "s s" and "s a" commands report the state of the option in the
|
|
|
161 echo area. Similarly, the "f" and "e" commands report what they do in
|
|
|
162 the echo area.
|
|
|
163
|
|
|
164 The "q" command has been revamped, and its behavior is now controlled
|
|
|
165 by the manner in which Emerge is started. In particular, if you wish
|
|
|
166 to write the merge buffer into a file upon exiting, invoke
|
|
|
167 emerge-files[-with-ancestor] with a prefix argument, and it will
|
|
|
168 prompt you for the file name. Then exiting will write the merge
|
|
|
169 buffer to the file, unless "q" is given a prefix argument.
|
|
|
170
|
|
|
171 The "i a" and "i b" commands now work in fast mode.
|
|
|
172
|
|
|
173 The modifications that Emerge makes to save-buffer and write-file are
|
|
|
174 described.
|
|
|
175
|
|
|
176 Emerge now handles merging narrowed buffers correctly.
|
|
|
177
|
|
|
178 Emerge now isn't fooled when the buffer visiting a file is not the
|
|
|
179 same as the file on disk.
|
|
|
180
|
|
|
181 - Starting
|
|
|
182
|
|
|
183 To start Emerge, you must run one of four commands:
|
|
|
184
|
|
|
185 emerge-files
|
|
|
186 emerge-files-with-ancestor
|
|
|
187 emerge-buffers
|
|
|
188 emerge-buffers-with-ancestor
|
|
|
189
|
|
|
190 The "files" versions prompt you for two file names (the "A" and "B"
|
|
|
191 files), the "buffers" versions prompt you for two buffer names (the
|
|
|
192 "A" and "B" buffers). Emerge then runs a "diff" of the two entities
|
|
|
193 (emerge-buffers writes the buffers into temporary files for input to
|
|
|
194 diff) and digests the output to form a list of the differences between
|
|
|
195 the two files. Then three buffers are set up: two containing the
|
|
|
196 entities (emerge-files does a find-file (C-x C-f) on the files to get
|
|
|
197 them into buffers), and one, the "merge buffer", which contains the
|
|
|
198 working copy of the merged file that you are constructing. The three
|
|
|
199 buffers are put up in a nice three-window display, showing the A and B
|
|
|
200 buffers in the upper half and the merge buffer in the lower half.
|
|
|
201
|
|
|
202 The versions of the command that say "with-ancestor" ask for a third
|
|
|
203 name, that of an entity which is a common ancestor from which the
|
|
|
204 versions being merged were derived. These commands use "diff3" to
|
|
|
205 compare all three versions. If one version of a difference agrees
|
|
|
206 with the ancestor, then it is presumed that the other version is the
|
|
|
207 "correct" version, and is said to be "preferred".
|
|
|
208
|
|
|
209 (Note that if you use emerge-files, Emerge attempts to make sure that
|
|
|
210 file on disk and the file in the buffer are the same. If the file on
|
|
|
211 disk has been changed, Emerge offers to revert the buffer. If the
|
|
|
212 buffer has been modified, Emerge offers to save the buffer. If the
|
|
|
213 user declines the offer, or if the file on disk and the buffer have
|
|
|
214 both been modified, Emerge aborts with an error message. Emerge is
|
|
|
215 careful to widen the buffers containing the files if they have been
|
|
|
216 narrowed. If you use emerge-buffers, the buffers are not widened --
|
|
|
217 only the visible portion is used.)
|
|
|
218
|
|
|
219 During the merge, the A and B buffers are read-only, so you don't
|
|
|
220 damage them. (This is because the A and B versions of the differences
|
|
|
221 are extracted from these buffers.) When you quit the merge, the
|
|
|
222 read-only/read-write status and modified flag on the A and B buffers
|
|
|
223 are restored. In addition, auto-saving of the A and B buffers is
|
|
|
224 suppressed during the merge. This is because Emerge modifies the A
|
|
|
225 and B buffers to point out the text of the differences, and it would
|
|
|
226 be useless to save these changes. (Just before suppressing
|
|
|
227 auto-saving, Emerge forces an auto-save.)
|
|
|
228
|
|
|
229 If you give a prefix argument to emerge-files or
|
|
|
230 emerge-files-with-ancestor, it prompts you for another file name,
|
|
|
231 which is the file into which the merged file is to be written when you
|
|
|
232 exit Emerge. The output file name defaults to the A file name. If
|
|
|
233 you successfully quit Emerge, the merge buffer will be written to the
|
|
|
234 output file, and the buffers for the A, B, and ancestor buffers will
|
|
|
235 be deleted (if they exist and are not modified). If you abort Emerge,
|
|
|
236 the merge buffer will not be written and the buffers will not be
|
|
|
237 deleted.
|
|
|
238
|
|
|
239 You can have any number of merges going at once -- just don't use any
|
|
|
240 one buffer as input to more than one merge at once, since that will
|
|
|
241 cause the read-only/modified/auto-save status save-and-restore to
|
|
|
242 screw up.
|
|
|
243
|
|
|
244 Beware that when Emerge starts up, it does a diff or diff3 of the
|
|
|
245 files, which can take many minutes for long files with many
|
|
|
246 differences. Emacs can't do anything else until diff finishes.
|
|
|
247
|
|
|
248 If diff or diff3 produces error messages, Emerge will beep and display
|
|
|
249 the error messages instead of the merge buffer. There will be a
|
|
|
250 message in the echo area giving the name of the merge buffer. Note
|
|
|
251 that this is really just an informational message -- you still have
|
|
|
252 switch to the merge buffer and abort the merge to restore the
|
|
|
253 conditions before you ran Emerge. (Emerge considers any output line
|
|
|
254 that does not match the regexp emerge-diff/diff3-ok-lines to be an
|
|
|
255 error message.)
|
|
|
256
|
|
|
257 After the merge has been set up, Emerge runs the hooks in
|
|
|
258 emerge-startup-hooks.
|
|
|
259
|
|
|
260 The major mode of the merge buffer is set from the major mode of the A
|
|
|
261 file or buffer. You should not use the major-mode-setting commands
|
|
|
262 (like c-mode or lisp-mode) to alter the major mode of the merge
|
|
|
263 buffer, since they damage the state information of the merge.
|
|
|
264 (Emerge's information is maintained as local variables of the merge
|
|
|
265 buffer.) You can use the "x m" command to change the major mode of
|
|
|
266 the merge buffer safely.
|
|
|
267
|
|
|
268 - Default directories
|
|
|
269
|
|
|
270 If the variable emerge-default-last-directories is not set, the
|
|
|
271 default directory for all filename arguments to the emerge-files
|
|
|
272 commands is the default directory of the current buffer, like any
|
|
|
273 other Emacs command. This can be inconvenient if you are merging
|
|
|
274 files in two different directories, since you cannot arrange for the
|
|
|
275 default directories for all of the various arguments to be the
|
|
|
276 directories you want.
|
|
|
277
|
|
|
278 The default directories for filename arguments can be changed by
|
|
|
279 setting the variable emerge-default-last-directories. When it is set,
|
|
|
280 the default directory for each filename argument is the directory of
|
|
|
281 the previous argument of that type. Thus, when merging files in two
|
|
|
282 directories, the full filenames need only be entered for the first
|
|
|
283 emerge-files command; the arugments to later emerge-files commands
|
|
|
284 will default to the same directories as the first one.
|
|
|
285
|
|
|
286 In this mode of operation, when the default directory for a filename
|
|
|
287 argument is not the same as the directory of the file given as the A
|
|
|
288 file, the argument acquires a default filename which is the filename
|
|
|
289 of the A file appended to the default directory for the argument.
|
|
|
290 This simplifies the usual case when several sets of files with
|
|
|
291 corresponding names in different directories are being merged.
|
|
|
292
|
|
|
293 - Merging
|
|
|
294
|
|
|
295 Once you have started the merge, you manipulate the merge buffer with
|
|
|
296 special commands issued in the merge buffer. You may also edit the
|
|
|
297 buffer with ordinary Emacs commands. Emerge keeps track of each
|
|
|
298 difference between the A and B buffers and the corresponding section
|
|
|
299 of the merge buffer. Initially, all differences show the A version,
|
|
|
300 except those for which B is preferred (because A agrees with the
|
|
|
301 ancestor), which show the B version. Emerge always has its attention
|
|
|
302 focused on one particular difference, which is marked off in the three
|
|
|
303 buffers by "vvvvvvvvvvvvvvvvvvvv" above and "^^^^^^^^^^^^^^^^^^^^"
|
|
|
304 below. The number of the difference is shown in the mode line. If
|
|
|
305 you are positioned before the first difference (that's where you
|
|
|
306 start) or after the last difference, it displays as "diff 0 of nnn" or
|
|
|
307 "diff nnn+1 of nnn".
|
|
|
308
|
|
|
309 A merge buffer can be in two modes: "fast" mode and "edit" mode. In
|
|
|
310 fast mode, emerge commands are single characters, and ordinary Emacs
|
|
|
311 commands are disabled. This makes Emerge operations fast, but
|
|
|
312 prevents you from doing more than selecing the A or the B version of
|
|
|
313 differences. In edit mode, all emerge commands must be prefixed with
|
|
|
314 C-c, and all (non-conflicting) Emacs commands are available. This
|
|
|
315 allows editing the merge buffer, but slows down Emerge operations.
|
|
|
316 Edit and fast modes are indicated by "F" and "E" in the minor modes in
|
|
|
317 the mode line.
|
|
|
318
|
|
|
319 The Emerge commands are:
|
|
|
320
|
|
|
321 p go to the previous difference
|
|
|
322 n go to the next difference
|
|
|
323 a select the A version of this difference
|
|
|
324 b select the B version of this difference
|
|
|
325 j go to a particular difference (prefix argument
|
|
|
326 specifies which difference) (0j suppresses display of
|
|
|
327 the flags)
|
|
|
328 q quit - finish the merge*
|
|
|
329 f go into fast mode
|
|
|
330 e go into edit mode
|
|
|
331 s a set/clear auto-advance mode*
|
|
|
332 s s set/clear skip-prefers mode*
|
|
|
333 l recenter (C-l) all three windows*
|
|
|
334 - and 0 through 9
|
|
|
335 prefix numeric arguments
|
|
|
336 d a select the A version as the default from here down in
|
|
|
337 the merge buffer*
|
|
|
338 d b select the B version as the default from here down in
|
|
|
339 the merge buffer*
|
|
|
340 c a copy the A version of the difference into the kill
|
|
|
341 ring
|
|
|
342 c b copy the B version of the difference into the kill
|
|
|
343 ring
|
|
|
344 i a insert the A version of the difference at the point
|
|
|
345 i b insert the B version of the difference at the point
|
|
|
346 m put the point and mark around the difference region
|
|
|
347 ^ scroll-down (like M-v) the three windows*
|
|
|
348 v scroll-up (like C-v) the three windows*
|
|
|
349 < scroll-left (like C-x <) the three windows*
|
|
|
350 > scroll-right (like C-x >) the three windows*
|
|
|
351 | reset horizontal scroll on the three windows*
|
|
|
352 x 1 shrink the merge window to one line (use C-u l to restore it
|
|
|
353 to full size)
|
|
|
354 x a find the difference containing a location in the A buffer*
|
|
|
355 x b find the difference containing a location in the B buffer*
|
|
|
356 x c combine the two versions of this difference*
|
|
|
357 x C combine the two versions of this difference, using a
|
|
|
358 register's value as the template*
|
|
|
359 x d find the difference containing a location in the merge buffer*
|
|
|
360 x f show the files/buffers Emerge is operating on in Help window
|
|
|
361 (use C-u l to restore windows)
|
|
|
362 x j join this difference with the following one
|
|
|
363 (C-u x j joins this difference with the previous one)
|
|
|
364 x l show line numbers of points in A, B, and merge buffers
|
|
|
365 x m change major mode of merge buffer*
|
|
|
366 x s split this difference into two differences
|
|
|
367 (first position the point in all three buffers to the places
|
|
|
368 to split the difference)
|
|
|
369 x t trim identical lines off top and bottom of difference
|
|
|
370 (such lines occur when the A and B versions are
|
|
|
371 identical but differ from the ancestor version)
|
|
|
372 x x set the template for the x c command*
|
|
|
373
|
|
|
374 * - more details on these commands are given below
|
|
|
375
|
|
|
376 The variable emerge-version gives the version number of Emerge. The
|
|
|
377 emerge-version function displays emerge-version (when called
|
|
|
378 interactively) or returns it (when called from a program).
|
|
|
379
|
|
|
380 - Differences and their states
|
|
|
381
|
|
|
382 A difference can have one of seven states:
|
|
|
383
|
|
|
384 A: the difference is showing the A version.
|
|
|
385
|
|
|
386 B: the difference is showing the B version.
|
|
|
387
|
|
|
388 default-A and default-B: the difference is showing the A or B state,
|
|
|
389 but has never been selected by the user. All differences start in the
|
|
|
390 default-A state (and thus the merge buffer is a copy of the A buffer),
|
|
|
391 except those for which one buffer or another is preferred. When the
|
|
|
392 user selects the difference, it changes to the A or B state.
|
|
|
393
|
|
|
394 prefer-A and prefer-B: the difference is showing the A or B state. In
|
|
|
395 addition, the other buffer (that is, for prefer-A, the B buffer; for
|
|
|
396 prefer-B, the A buffer) agrees with the ancestor buffer. Thus,
|
|
|
397 presumably, the displayed version is the correct one. The "a" and "b"
|
|
|
398 commands override these states, and turn them into the A and B states.
|
|
|
399
|
|
|
400 combined: the difference is showing a combination of the A and B
|
|
|
401 states that was constructed by the "x c" or "x C" commands. Since
|
|
|
402 this state is neither the A or B states, the "a" and "b" commands
|
|
|
403 won't alter the difference unless they are given a prefix argument.
|
|
|
404
|
|
|
405 The state of the currently selected difference is shown in the mode
|
|
|
406 line of the merge window:
|
|
|
407
|
|
|
408 state display
|
|
|
409
|
|
|
410 A A
|
|
|
411 B B
|
|
|
412 prefer-A A*
|
|
|
413 prefer-B B*
|
|
|
414 combined comb
|
|
|
415
|
|
|
416 - Select default commands (d a and d b)
|
|
|
417
|
|
|
418 The "d a" and "d b" commands change all default-A's to default-B's (or
|
|
|
419 vice-versa) from the selected difference on down to the end of the
|
|
|
420 file to default-A or default-B, respectively. But remember, any
|
|
|
421 difference that you have ever selected isn't in the default-A or
|
|
|
422 default-B state, so it will never be affected by "d a" or "d b". This
|
|
|
423 leads to the unexpected result that "d a" or "d b" never affects the
|
|
|
424 difference selected at the moment, but prevents differences that you
|
|
|
425 have already looked at from changing unexpectedly.
|
|
|
426
|
|
|
427 If you work your way down from the top of the file, using "d a" and
|
|
|
428 "d b" at judicious points, you can effectivly make the A version the
|
|
|
429 default for some sections of the merge buffer and the B version the
|
|
|
430 default for others.
|
|
|
431
|
|
|
432 Giving the "d a" or "d b" command a prefix argument causes it to change
|
|
|
433 differences from the current point down that are in the B state (for d
|
|
|
434 a) or A state (for "d b") as well. (Thus, the selected difference may
|
|
|
435 be changed also.) Differences for which there is a preference will
|
|
|
436 not be affected. (Selecting a difference won't erase its preference.)
|
|
|
437
|
|
|
438 - Exiting (q)
|
|
|
439
|
|
|
440 The quit command finishes the merge session by restoring the state of
|
|
|
441 the A and B buffers and removing the markers around the currently
|
|
|
442 selected difference. It also disables the Emerge commands in the
|
|
|
443 merge buffer, since executing them later could damage the contents of
|
|
|
444 the various buffers.
|
|
|
445
|
|
|
446 The action of "q" depends on how Emerge was started and whether "q"
|
|
|
447 was given a prefix argument. If there was no prefix argument, it is
|
|
|
448 considered a "successful" finish. If there was a prefix argument, it
|
|
|
449 is considered an "unsuccessful" finish. In either case, you are asked
|
|
|
450 to cofirm the exit, and the confirmation message tells which sort of
|
|
|
451 exit you are confirming.
|
|
|
452
|
|
|
453 If Emerge was started by some other process, success/failure is
|
|
|
454 reported to the caller.
|
|
|
455
|
|
|
456 If Emerge was started with emerge-files or emerge-files-with-ancestor,
|
|
|
457 if a prefix argument was given to that command, then you specified a
|
|
|
458 file into which the merge is to be written. A successful exit writes
|
|
|
459 the merge into the output file and then kills the A, B, and ancestor
|
|
|
460 buffers (so they aren't lying around to confuse you, since they
|
|
|
461 probably all have similar names).
|
|
|
462
|
|
|
463 - Auto-advance mode (s a)
|
|
|
464
|
|
|
465 If auto-advance mode is set, the "a" and "b" commands perform an "n"
|
|
|
466 (select next difference) afterward. When auto-advance mode is set,
|
|
|
467 it is indicated by "A" in the minor modes in the mode line.
|
|
|
468 "s a" with a positive argument sets auto-advance, with a non-positive
|
|
|
469 argument clears it, and with no argument toggles it.
|
|
|
470
|
|
|
471 - Skip-prefers mode (s s)
|
|
|
472
|
|
|
473 If skip-prefers mode is set, the "n" and "p" commands skip over
|
|
|
474 differences with states prefer-A and prefer-B. Thus you will only see
|
|
|
475 differences for which one version isn't presumed "correct". When
|
|
|
476 skip-prefers mode is set, it is indicated by "S" in the minor modes in
|
|
|
477 the mode line. "s s" with a positive argument sets auto-advance, with
|
|
|
478 a non-positive argument clears it, and with no argument toggles it.
|
|
|
479
|
|
|
480 - Recenter (l)
|
|
|
481
|
|
|
482 The Emerge "l" command causes the selected difference to be brought
|
|
|
483 into view in the three windows, or at least, whichever of the three
|
|
|
484 merge buffers are visible at the moment. If a prefix argument is
|
|
|
485 given, then the original three-window display is set up before the
|
|
|
486 difference texts are shown.
|
|
|
487
|
|
|
488 - Scrolling the text (^, v, <, >, and |)
|
|
|
489
|
|
|
490 Emerge has several commands which scroll all three windows by the same
|
|
|
491 amount, thus allowing you to easily compare the versions of the text.
|
|
|
492 The commands are "^" (scroll-up), "v" (scroll-down), "<"
|
|
|
493 (scroll-left), ">" (scroll-right), and "|" (reset horizontal
|
|
|
494 scrolling). (Remember that Emacs names scrolling commands by the
|
|
|
495 motion of the text with respect to the window, so C-v is called
|
|
|
496 "scroll-up".)
|
|
|
497
|
|
|
498 If these commands (except "|") are given an argument, that is the
|
|
|
499 number of lines or characters by which the windows are scrolled.
|
|
|
500 Otherwise, the amount of motion is computed based on the dimensions of
|
|
|
501 the merge buffer window -- the height of the merge buffer window
|
|
|
502 (minus next-screen-context-lines), or half the width of the merge
|
|
|
503 buffer window. (The A and B version windows are assumed to be as high
|
|
|
504 as the merge window, but half as wide.) If the argument is just `C-u
|
|
|
505 -', then the scrolling is half the default amount.
|
|
|
506
|
|
|
507 - Finding the difference at or near a location (x d, x a, and x b)
|
|
|
508
|
|
|
509 The "x d" command selects the difference containing the current point
|
|
|
510 in the merge buffer. If there is no difference containing the point,
|
|
|
511 an error is given. An argument can be given to the command to change
|
|
|
512 this behavior: if the argument is positive (e.g., C-u), the next
|
|
|
513 following difference is selected; if the argument is negative (e.g.,
|
|
|
514 C-u -), the previous difference is selected.
|
|
|
515
|
|
|
516 The "x a" and "x b" commands select the difference containing the
|
|
|
517 current point in the A and B buffers, respectively. Otherwise, they
|
|
|
518 act like the "x d" command. Note that although the point used in the
|
|
|
519 commands is not the merge buffer point, the commands can only be
|
|
|
520 issued in the merge buffer, because it is the only buffer with the
|
|
|
521 Emerge keymap.
|
|
|
522
|
|
|
523 - Combining the two versions (x c, x C, and x x)
|
|
|
524
|
|
|
525 Sometimes one wants to combine the two versions of a difference. For
|
|
|
526 instance, when merging two versions of a program, one wants to make
|
|
|
527 something like this:
|
|
|
528
|
|
|
529 #ifdef NEW
|
|
|
530 ...new version of code...
|
|
|
531 #else /* NEW */
|
|
|
532 ...old version of code...
|
|
|
533 #endif /* NEW */
|
|
|
534
|
|
|
535 The "x c" command will make such a combined version. (Note that any
|
|
|
536 combined version is not the same as either the A or B versions, and so
|
|
|
537 the "a" and "b" commands will refuse to alter it unless they are given
|
|
|
538 a prefix argument.) The combination is made under control of a
|
|
|
539 template, which is a character string with the following
|
|
|
540 interpolations:
|
|
|
541
|
|
|
542 %a the A version of the difference
|
|
|
543 %b the B version of the difference
|
|
|
544 %% the character '%'
|
|
|
545
|
|
|
546 Thus, the template used above is
|
|
|
547
|
|
|
548 #ifdef NEW\n%b#else /* NEW */\n%a#endif /* NEW */\n
|
|
|
549
|
|
|
550 (using \n here to represent newlines). The template is stored in the
|
|
|
551 variable emerge-combine-versions-template, and its initial value is
|
|
|
552 the one given above. The template can be set (from the current
|
|
|
553 region) by the "x x" command. (Be careful to get the newlines in the
|
|
|
554 template in the right places!) ("x x" was chosen by analogy with "C-x
|
|
|
555 x".) ("x x" is only available in the merge buffer, of course.
|
|
|
556 Elsewhere, M-x emerge-set-combine-versions-template can be used.) If
|
|
|
557 "x x" is given a prefix argument, emerge-combine-versions-template is
|
|
|
558 localized in the merge buffer before its value is set, so the "x x"
|
|
|
559 command's effect (and the effect of any later "x x" command in the
|
|
|
560 merge buffer) is only on the merge buffer.
|
|
|
561
|
|
|
562 The "x C" command is like "x c", but it prompts for a character
|
|
|
563 which is the register whose value is to be used as the template.
|
|
|
564 This allows one to use multiple templates conveniently.
|
|
|
565
|
|
|
566 - Changing the major mode of the edit buffer (x m)
|
|
|
567
|
|
|
568 The "x m" command prompts for the name of a major-mode-setting command
|
|
|
569 (such as "c-mode" or "emacs-lisp-mode") and executes it. Ordinarily,
|
|
|
570 major-mode-setting commands change the mode line and local keymap, so
|
|
|
571 the "x m" command then resets the Emerge mode line and the fast or
|
|
|
572 edit mode local keymap, as appropriate.
|
|
|
573
|
|
|
574 If you have already changed the major mode of the merge buffer and
|
|
|
575 lost the Emerge keymap, you can use M-x emerge-set-merge-mode to
|
|
|
576 execute this command.
|
|
|
577
|
|
|
578 Beware that "x m" accepts any command name, not just
|
|
|
579 major-mode-setting commands.
|
|
|
580
|
|
|
581 In order to use "x m", the kill-fix.el package of improvements to the
|
|
|
582 kill-all-local-variables function must be installed. It can be
|
|
|
583 obtained from the Emacs Lisp archives by anonymous FTP from file
|
|
|
584 /pub/gnu/emacs/elisp-archive/as-is/kill-fix.el.Z on
|
|
|
585 archive.cis.ohio-state.edu.
|
|
|
586
|
|
|
587 - Writing the merge buffer manually
|
|
|
588
|
|
|
589 Emerge places a wrapper (emerge-query-and-call) on the key bindings of
|
|
|
590 save-buffer (usually "C-x C-s") and write-file (usually "C-x C-w"), in
|
|
|
591 order to protect the user from writing out the merge before it is
|
|
|
592 finished. Emerge-query-and-call asks the user if he is sure he wants
|
|
|
593 to write out the incomplete merge. If he answers yes, the buffer is
|
|
|
594 written out. The flags are suppressed while the write is being done.
|
|
|
595 As a result of this, the displayed portions of the buffers are
|
|
|
596 recentered (equivalent to "l").
|
|
|
597
|
|
|
598 - Running Emerge standalone
|
|
|
599
|
|
|
600 If you invoke emacs with the following arguments, you can execute
|
|
|
601 Emerge as a standalone program:
|
|
|
602
|
|
|
603 emacs -l emerge -f emerge-files-command file-a file-b file-out
|
|
|
604
|
|
|
605 emacs -l emerge -f emerge-files-with-ancestor-command
|
|
|
606 file-a file-b file-ancestor file-out
|
|
|
607
|
|
|
608 When the user gives the "q" (quit) command, Emerge will write out the
|
|
|
609 merge buffer in file-out and terminate Emacs. If a prefix argument is
|
|
|
610 given, Emacs will terminate with an unsuccessful return code (1), if
|
|
|
611 not, it will terminate with a successful return code (0).
|
|
|
612
|
|
|
613 - Invoking Emerge remotely
|
|
|
614
|
|
|
615 If you use the Emacs client/server code that supports remote
|
|
|
616 execution, then you can invoke Emerge remotely by executing one of the
|
|
|
617 Lisp calls:
|
|
|
618
|
|
|
619 (emerge-files-remote "file A" "file B" "output file")
|
|
|
620
|
|
|
621 (emerge-files-with-ancestor-remote "file A" "file B"
|
|
|
622 "ancestor file" "output file")
|
|
|
623
|
|
|
624 Returning a successful/unsuccessful return code is not yet supported
|
|
|
625 by the Emacs client/server code.
|
|
|
626
|
|
|
627 Beware that in systems of networked workstations, even though all user
|
|
|
628 directories are shared between all the workstations, the /tmp
|
|
|
629 directory on each workstation is not shared, so writing files into
|
|
|
630 /tmp and then remotely invoking Emerge is not likely to work.
|
|
|
631
|
|
|
632 - Effect of merge flags on indenting code
|
|
|
633
|
|
|
634 The presence of the flags confuses the indentation code of C and
|
|
|
635 Emacs-Lisp modes. Starting the flag strings
|
|
|
636 (emerge-{before,after}-flag) with '#' (for C) or ';' (for Lisp)
|
|
|
637 prevents the indentation code from noticing the flags. Remember to
|
|
|
638 change the flag strings before loading Emerge, or to execute
|
|
|
639 emerge-new-flags after changing them. But never change the flag
|
|
|
640 strings while a merge is being performed.
|
|
|
641
|
|
|
642 - Autoloading
|
|
|
643
|
|
|
644 The following autoloads will make all top-level Emerge files
|
|
|
645 autoloading. Make sure that "emerge" is in a directory on load-path.
|
|
|
646
|
|
|
647 (autoload 'emerge-files "emerge"
|
|
|
648 "Run Emerge on two files."
|
|
|
649 t)
|
|
|
650 (autoload 'emerge-files-with-ancestor "emerge"
|
|
|
651 "Run Emerge on two files, giving another file as the ancestor."
|
|
|
652 t)
|
|
|
653 (autoload 'emerge-buffers "emerge"
|
|
|
654 "Run Emerge on two buffers."
|
|
|
655 t)
|
|
|
656 (autoload 'emerge-buffers-with-ancestor "emerge"
|
|
|
657 "Run Emerge on two buffers, giving another buffer as the ancestor."
|
|
|
658 t)
|
|
|
659 (autoload 'emerge-files-command "emerge")
|
|
|
660 (autoload 'emerge-files-with-ancestor-command "emerge")
|
|
|
661 (autoload 'emerge-files-remote "emerge")
|
|
|
662 (autoload 'emerge-files-with-ancestor-remote "emerge")
|
|
|
663 (autoload 'emerge-revisions "emerge"
|
|
|
664 "Emerge two RCS revisions of a file."
|
|
|
665 t)
|
|
|
666 (autoload 'emerge-revisions-with-ancestor
|
|
|
667 "Emerge two RCS revisions of a file, giving another revision as
|
|
|
668 the ancestor."
|
|
|
669 t)
|
|
|
670
|
|
|
671 (autoload 'emerge-execute-line "emerge"
|
|
|
672 "Process the current line. Based on entries found, call emerge correctly
|
|
2
|
673 on the files listed."
|
|
0
|
674 t)
|
|
|
675
|
|
|
676 - Use with Ange-FTP
|
|
|
677
|
|
|
678 The Ange-FTP package allows Emacs to access files using FTP much as if
|
|
|
679 they are local files. However, diff/diff3 cannot access non-local
|
|
|
680 files, and so Emerge needs to provide additional support if non-local
|
|
|
681 files are being used. Emerge uses the function emerge-remote-file-p
|
|
|
682 to test a file name to see whether that file name can be given
|
|
|
683 directly to diff/diff3. If not, Emerge saves the file contents into a
|
|
|
684 temporary file, and gives the temporary file name to diff/diff3. The
|
|
|
685 temporary file is deleted after diff/diff3 is done running.
|
|
|
686
|
|
|
687 The function emerge-remote-file-p by default causes temporary files to
|
|
|
688 be generated only for files read using Ange-FTP (which are
|
|
|
689 distinguished via the variable ange-ftp-path-format). If Ange-FTP is
|
|
|
690 not loaded, it causes no temporary files to be generated. The
|
|
|
691 function emerge-remote-file-p can be modified for customization.
|
|
|
692
|
|
|
693 - Filenames containing shell metacharacters
|
|
|
694
|
|
|
695 Emerge handles filenames containing shell metacharacters by quoting
|
|
|
696 them with \ before passing them to the shell. This is normally not a
|
|
|
697 problem, except that Emacs auto-save files begin with #, which is
|
|
|
698 normally used to start comments. Which characters are considered
|
|
|
699 metacharacters is governed by the variable emerge-metachars, whose
|
|
|
700 default value is suitable when the shell is sh, csh, or compatible
|
|
|
701 shells.
|
|
|
702
|
|
|
703 - Local variables lists
|
|
|
704
|
|
|
705 Normally, Emerge ignores any local-variables list that is created in
|
|
|
706 the merge buffer. However, sometimes it may be useful to have a
|
|
|
707 local-variables list processed. This can be done manually by
|
|
|
708 executing the function "(hack-local-variables)". If the variable
|
|
|
709 emerge-process-local-variables is true, when Emerge is started it
|
|
|
710 will process any local variables list in the newly-created merge
|
|
|
711 buffer. (If the merge has an ancestor, the selecting of default
|
|
|
712 versions of differences is done before the local variables list is
|
|
|
713 processed.)
|
|
|
714
|
|
|
715 - Semi-automatic batching of merges
|
|
|
716
|
|
|
717 If you have a large number of merges to execute, the function
|
|
|
718 emerge-execute-line can reduce the amount of work. To use it, create
|
|
|
719 a buffer containing lines that describe the merges to be done. Each
|
|
|
720 line describes a single merge by means of fields of the form:
|
|
|
721
|
|
|
722 A=file1
|
|
|
723 B=file2
|
|
|
724 ancestor=file3
|
|
|
725 output=file4
|
|
|
726
|
|
|
727 The fields are seperated by whitespace, and the filenames given should
|
|
|
728 be absolute, not relative. The buffer's contents can be generated by
|
|
|
729 a program and read in as a file, or they can be generated by an Emacs
|
|
|
730 function. (See the sample function emerge-merge-directories, which
|
|
|
731 produces specifications to merge the entire contents of two
|
|
|
732 directories, possibly with an ancestor directory and an output
|
|
|
733 directory.)
|
|
|
734
|
|
|
735 If you position the cursor on one line of the buffer and execute
|
|
|
736 emerge-execute-line, the information on that line will be read and an
|
|
|
737 appropriate merge will be started. When the merge is finished (or
|
|
|
738 aborted), the original buffer will be displayed again, with the cursor
|
|
|
739 at the beginning of the next line, ready for the next invocation of
|
|
|
740 emerge-execute-line. In this way, it is easy to start a sequence of
|
|
|
741 merges that are described by a buffer of specifications.
|
|
|
742
|
|
|
743 To perform a two-way merge, provide an "A" and a "B" field. To
|
|
|
744 perform a merge with an ancestor file, provide "A", "B", and
|
|
|
745 "ancestor" fields. In either case, if an "output" field is provided,
|
|
|
746 the results of a successful merge will be written into the designated
|
|
|
747 file, just as if a prefix argument had been given to the Emerge
|
|
|
748 command.
|
|
|
749
|
|
|
750 In addition, emerge-process-line attempts to handle situations where
|
|
|
751 one of the "A" or "B" fields are missing, showing that one version or
|
|
|
752 another of the file does not exist. (In all cases, files that are
|
|
|
753 specified in the "A", "B", or "ancestor" fields must exist.
|
|
|
754 Non-existent files are specified by omitting the appropriate field.)
|
|
|
755 The principles governing these cases are: (1) If no "output" file is
|
|
|
756 specified, it is an error. (2) If an "output" file is specified, then
|
|
|
757 the "A" or "B" file (whichever is present) is copied into the output
|
|
|
758 file. (3) If an "ancestor" file is given, it is assumed that the file
|
|
|
759 in question has been deleted in one or another of the versions, and so
|
|
|
760 should be deleted from the "merged" version of the files. Case (3) is
|
|
|
761 sufficiently dangerous that it is only activated if the variable
|
|
|
762 emerge-execute-line-deletions is set; otherwise case (3) will be
|
|
|
763 handled as case (2), that is, the one existing version will be copied
|
|
|
764 to the output file.
|
|
|
765
|
|
|
766 In all cases, the goal is to simplify the usual case of "merging two
|
|
|
767 directories that contain two versions of a system of software".
|
|
|
768
|
|
|
769 - Merging RCS versions of a file
|
|
|
770
|
|
|
771 You can merge RCS versions of a file using the commands
|
|
|
772 emerge-revisions and emerge-revisions-with-ancestor. For both
|
|
|
773 commands, all of the input files are RCS versions of one base file,
|
|
|
774 which are checked out automatically. If you provide a prefix
|
|
|
775 argument, upon successful completion the merged file is checked in.
|
|
|
776
|
|
|
777 - Use with Lucid Emacs
|
|
|
778
|
|
|
779 Under Lucid Emacs, Emerge highlights the selected difference rather
|
|
|
780 that bordering it with character flags. This is probably more
|
|
|
781 natural, but it has the problem that insertions made at the very ends
|
|
|
782 of the difference may go either inside or outside of the difference,
|
|
|
783 at Emacs' discretion. The Lucid features should be disablable by
|
|
|
784 setting emerge-lucid-p to nil, but that variable is also used to
|
|
|
785 activate workarounds to bugs in Lucid Emacs, so the user shouldn't
|
|
|
786 change its value.
|
