Mercurial > hg > xemacs-beta

comparison man/emerge.txt @ 0:376386a54a3c r19-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r19-14
author cvs
date Mon, 13 Aug 2007 08:45:50 +0200
parents
children ac2d302a0011
comparison
equal deleted inserted replaced
-1:000000000000 0:376386a54a3c
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
673 on the files files listed."
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.