Source

XEmacs / man / emerge.txt

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
This is the documentation for version 5 of "emerge.el", an Emacs
package that allows you to combine two versions of a file by
selecting, for each place where they differ, which version of the
difference you prefer.  It is similar to Sun's "filemerge".

Written by Dale R. Worley <drw@math.mit.edu>.

WARRANTY DISCLAIMER

This software was created by Dale R. Worley and is
distributed free of charge.  It is placed in the public domain and
permission is granted to anyone to use, duplicate, modify and redistribute
it provided that this notice is attached.

Dale R. Worley provides absolutely NO WARRANTY OF ANY KIND
with respect to this software.  The entire risk as to the quality and
performance of this software is with the user.  IN NO EVENT WILL DALE
R. WORLEY BE LIABLE TO ANYONE FOR ANY DAMAGES ARISING OUT THE
USE OF THIS SOFTWARE, INCLUDING, WITHOUT LIMITATION, DAMAGES RESULTING FROM
LOST DATA OR LOST PROFITS, OR FOR ANY SPECIAL, INCIDENTAL OR CONSEQUENTIAL
DAMAGES.

;; LCD Archive Entry:
;; emerge|Dale R. Worley|drw@math.mit.edu
;; |File merge documentation
;; |92-12-11|version 5 gamma|~/packages/emerge.doc.Z

- Changes from version 4 to version 5

Put in improved disclaimer of copyright and warranty.

Document autoload for emerge-execute-line.

Changes to support use with Ange-FTP.

Allow filenames containing shell metacharacters to be handled unscathed.

Certain internal problems were fixed so that bugs in "x s", "x j", and
"x t" were eliminated.

Non-existent and non-readable file names are rejected, even if Emerge
is called non-interactively.

Add code to process the local-variables list in newly created merge
buffers.

Add changes made by David Gudeman to allow the default directory for
arguments to the emerge-files commands to be the directory of the
argument of that type to the last emerge-files command.  See "Default
directories" below.

Add emerge-process-line command to allow semi-automatic batching of
merges.

Add David Gudeman's facility for merging RCS revisions of a file.

Add a few hooks to make customization easier.

Still no Epoch support in this version, though.  Talk to Dan Pierson
<pierson@xenna.encore.com> or check epoch-emerge-patch.el in the Emacs
Lisp Directory if you want Epoch support.

And the document still isn't in TeXinfo format.

- Changes from version 3 to version 4

More configuration variables are marked as user options.

Code is included for an improved version of make-auto-save-file-name
which eliminates many problems with the default version.  See the
documentation of emerge-make-auto-save-file-name to see how to
activate it.

Emerge now works with Gnu diff3, which can produce the groups of lines
from the various files in the order 1, 2, 3 or 1, 3, 2.

Add "x f" command to show what files or buffers are being operated on.

The merge buffer now starts read-only, which being in fast mode it
should be.

When merging buffers, Emerge writes their contents into temporary
files in the directory $TMPDIR (if it is defined), or /tmp by default.

Add "x j" command to join two differences.

Add "x s" command to split a difference into two differences.

Add emerge-version variable and function to report the version of Emerge
being run.

Add "x t" command to trim unchanged lines off top and bottom of
difference region.

Add "x d", "x a", and "x b" commands to locate the differences at or
near a given location in one of the buffers.

Emerge no longer tries to copy the minor modes from the A buffer to
the merge buffer, only the major mode.

The programs executed to find the differences between versions of the file
are no longer controlled by emerge-diff/diff3-command, but rather by:
  emerge-diff-program	      
    Variable: *Name of the program which compares two files.
  emerge-diff3-program	      
    Variable: *Name of the program which compares an ancestor file
    (first argument) and two variant files (second and third arguments).
  emerge-diff-options	      
    Variable: *Options to be passed to emerge-diff/diff3-program.

The names of the files are expanded (see expand-file-name) before being
passed to emerge-diff/diff3-program, so diff need not invoked under a shell
that understands '~', for instance.

If the diff/diff3 program reports errors, the user is notified and the
errors are displayed.

The command "0j" can be used to suppress the flags from showing in the
buffers.

A discussion of the effect of the merge flags on indentation of code
has been added to the documentation.

If kill-fix.el is loaded, Emerge control variables now have their
'preserved' property set, so setting the major mode in the merge
buffer doesn't destroy Emerge's state.

Add "x c", "x C", and "x x" commands to allow the A and B versions to be
combined into #ifdef - #endif forms.

Replaced calls of "ding" to calls of "error" where appropriate.

Add "x m" command to allow major mode of merge buffer to be changed.

Add "x 1" command to shrink the merge window to one line.

Add emerge-startup-hooks to allow customization.

Fixed a bug that is activated when a remote merge request is made when
the minibuffer window is selected.

- Changes from version 2 to version 3

The directory into which temporary files are written is now controlled
by a user option (emerge-temp-file-prefix).

The A and B versions of the difference can be loaded into the kill
ring with the "c a" and "c b" commands.

The A and B versions of the difference can be inserted into the merge
buffer with the "i a" and "i b" commands.

The difference region of the merge buffer can be surrounded by the
point and mark with the "m" command.

The three windows can be scrolled together with the "^", "v", "<",
">", and "|" commands.

The "s s" and "s a" commands report the state of the option in the
echo area.  Similarly, the "f" and "e" commands report what they do in
the echo area.

The "q" command has been revamped, and its behavior is now controlled
by the manner in which Emerge is started.  In particular, if you wish
to write the merge buffer into a file upon exiting, invoke
emerge-files[-with-ancestor] with a prefix argument, and it will
prompt you for the file name.  Then exiting will write the merge
buffer to the file, unless "q" is given a prefix argument.

The "i a" and "i b" commands now work in fast mode.

The modifications that Emerge makes to save-buffer and write-file are
described.

Emerge now handles merging narrowed buffers correctly.

Emerge now isn't fooled when the buffer visiting a file is not the
same as the file on disk.

- Starting

To start Emerge, you must run one of four commands:

	emerge-files
	emerge-files-with-ancestor
	emerge-buffers
	emerge-buffers-with-ancestor

The "files" versions prompt you for two file names (the "A" and "B"
files), the "buffers" versions prompt you for two buffer names (the
"A" and "B" buffers).  Emerge then runs a "diff" of the two entities
(emerge-buffers writes the buffers into temporary files for input to
diff) and digests the output to form a list of the differences between
the two files.  Then three buffers are set up: two containing the
entities (emerge-files does a find-file (C-x C-f) on the files to get
them into buffers), and one, the "merge buffer", which contains the
working copy of the merged file that you are constructing.  The three
buffers are put up in a nice three-window display, showing the A and B
buffers in the upper half and the merge buffer in the lower half.

The versions of the command that say "with-ancestor" ask for a third
name, that of an entity which is a common ancestor from which the
versions being merged were derived.  These commands use "diff3" to
compare all three versions.  If one version of a difference agrees
with the ancestor, then it is presumed that the other version is the
"correct" version, and is said to be "preferred".

(Note that if you use emerge-files, Emerge attempts to make sure that
file on disk and the file in the buffer are the same.  If the file on
disk has been changed, Emerge offers to revert the buffer.  If the
buffer has been modified, Emerge offers to save the buffer.  If the
user declines the offer, or if the file on disk and the buffer have
both been modified, Emerge aborts with an error message.  Emerge is
careful to widen the buffers containing the files if they have been
narrowed.  If you use emerge-buffers, the buffers are not widened --
only the visible portion is used.)

During the merge, the A and B buffers are read-only, so you don't
damage them.  (This is because the A and B versions of the differences
are extracted from these buffers.)  When you quit the merge, the
read-only/read-write status and modified flag on the A and B buffers
are restored.  In addition, auto-saving of the A and B buffers is
suppressed during the merge.  This is because Emerge modifies the A
and B buffers to point out the text of the differences, and it would
be useless to save these changes.  (Just before suppressing
auto-saving, Emerge forces an auto-save.)

If you give a prefix argument to emerge-files or
emerge-files-with-ancestor, it prompts you for another file name,
which is the file into which the merged file is to be written when you
exit Emerge.  The output file name defaults to the A file name.  If
you successfully quit Emerge, the merge buffer will be written to the
output file, and the buffers for the A, B, and ancestor buffers will
be deleted (if they exist and are not modified).  If you abort Emerge,
the merge buffer will not be written and the buffers will not be
deleted.

You can have any number of merges going at once -- just don't use any
one buffer as input to more than one merge at once, since that will
cause the read-only/modified/auto-save status save-and-restore to
screw up.

Beware that when Emerge starts up, it does a diff or diff3 of the
files, which can take many minutes for long files with many
differences.  Emacs can't do anything else until diff finishes.

If diff or diff3 produces error messages, Emerge will beep and display
the error messages instead of the merge buffer.  There will be a
message in the echo area giving the name of the merge buffer.  Note
that this is really just an informational message -- you still have
switch to the merge buffer and abort the merge to restore the
conditions before you ran Emerge.  (Emerge considers any output line
that does not match the regexp emerge-diff/diff3-ok-lines to be an
error message.)

After the merge has been set up, Emerge runs the hooks in
emerge-startup-hooks.

The major mode of the merge buffer is set from the major mode of the A
file or buffer.  You should not use the major-mode-setting commands
(like c-mode or lisp-mode) to alter the major mode of the merge
buffer, since they damage the state information of the merge.
(Emerge's information is maintained as local variables of the merge
buffer.)  You can use the "x m" command to change the major mode of
the merge buffer safely.

- Default directories

If the variable emerge-default-last-directories is not set, the
default directory for all filename arguments to the emerge-files
commands is the default directory of the current buffer, like any
other Emacs command.  This can be inconvenient if you are merging
files in two different directories, since you cannot arrange for the
default directories for all of the various arguments to be the
directories you want.

The default directories for filename arguments can be changed by
setting the variable emerge-default-last-directories.  When it is set,
the default directory for each filename argument is the directory of
the previous argument of that type.  Thus, when merging files in two
directories, the full filenames need only be entered for the first
emerge-files command; the arugments to later emerge-files commands
will default to the same directories as the first one.

In this mode of operation, when the default directory for a filename
argument is not the same as the directory of the file given as the A
file, the argument acquires a default filename which is the filename
of the A file appended to the default directory for the argument.
This simplifies the usual case when several sets of files with
corresponding names in different directories are being merged.

- Merging

Once you have started the merge, you manipulate the merge buffer with
special commands issued in the merge buffer.  You may also edit the
buffer with ordinary Emacs commands.  Emerge keeps track of each
difference between the A and B buffers and the corresponding section
of the merge buffer.  Initially, all differences show the A version,
except those for which B is preferred (because A agrees with the
ancestor), which show the B version.  Emerge always has its attention
focused on one particular difference, which is marked off in the three
buffers by "vvvvvvvvvvvvvvvvvvvv" above and "^^^^^^^^^^^^^^^^^^^^"
below.  The number of the difference is shown in the mode line.  If
you are positioned before the first difference (that's where you
start) or after the last difference, it displays as "diff 0 of nnn" or
"diff nnn+1 of nnn".

A merge buffer can be in two modes: "fast" mode and "edit" mode.  In
fast mode, emerge commands are single characters, and ordinary Emacs
commands are disabled.  This makes Emerge operations fast, but
prevents you from doing more than selecing the A or the B version of
differences.  In edit mode, all emerge commands must be prefixed with
C-c, and all (non-conflicting) Emacs commands are available.  This
allows editing the merge buffer, but slows down Emerge operations.
Edit and fast modes are indicated by "F" and "E" in the minor modes in
the mode line.

The Emerge commands are:

	p	go to the previous difference
	n	go to the next difference
	a	select the A version of this difference
	b	select the B version of this difference
	j	go to a particular difference (prefix argument
		specifies which difference) (0j suppresses display of
		the flags)
	q	quit - finish the merge*
	f	go into fast mode
	e	go into edit mode
	s a	set/clear auto-advance mode*
	s s	set/clear skip-prefers mode*
	l	recenter (C-l) all three windows*
	- and 0 through 9
		prefix numeric arguments
	d a	select the A version as the default from here down in
		the merge buffer*
	d b	select the B version as the default from here down in
		the merge buffer*
	c a	copy the A version of the difference into the kill
		ring
	c b	copy the B version of the difference into the kill
		ring
	i a	insert the A version of the difference at the point
	i b	insert the B version of the difference at the point
	m	put the point and mark around the difference region
	^	scroll-down (like M-v) the three windows*
	v	scroll-up (like C-v) the three windows*
	<	scroll-left (like C-x <) the three windows*
	>	scroll-right (like C-x >) the three windows*
	|	reset horizontal scroll on the three windows*
	x 1	shrink the merge window to one line (use C-u l to restore it
		to full size)
	x a	find the difference containing a location in the A buffer*
	x b	find the difference containing a location in the B buffer*
	x c	combine the two versions of this difference*
	x C	combine the two versions of this difference, using a
		register's value as the template*
	x d	find the difference containing a location in the merge buffer*
	x f	show the files/buffers Emerge is operating on in Help window
		(use C-u l to restore windows)
	x j	join this difference with the following one
		(C-u x j joins this difference with the previous one)
	x l	show line numbers of points in A, B, and merge buffers
	x m	change major mode of merge buffer*
	x s	split this difference into two differences
		(first position the point in all three buffers to the places
		to split the difference)
	x t	trim identical lines off top and bottom of difference
		(such lines occur when the A and B versions are
		identical but differ from the ancestor version)
	x x	set the template for the x c command*

* - more details on these commands are given below

The variable emerge-version gives the version number of Emerge.  The
emerge-version function displays emerge-version (when called
interactively) or returns it (when called from a program).

- Differences and their states

A difference can have one of seven states:

A:  the difference is showing the A version.

B:  the difference is showing the B version.

default-A and default-B: the difference is showing the A or B state,
but has never been selected by the user.  All differences start in the
default-A state (and thus the merge buffer is a copy of the A buffer),
except those for which one buffer or another is preferred.  When the
user selects the difference, it changes to the A or B state.

prefer-A and prefer-B: the difference is showing the A or B state.  In
addition, the other buffer (that is, for prefer-A, the B buffer; for
prefer-B, the A buffer) agrees with the ancestor buffer.  Thus,
presumably, the displayed version is the correct one.  The "a" and "b"
commands override these states, and turn them into the A and B states.

combined: the difference is showing a combination of the A and B
states that was constructed by the "x c" or "x C" commands.  Since
this state is neither the A or B states, the "a" and "b" commands
won't alter the difference unless they are given a prefix argument.

The state of the currently selected difference is shown in the mode
line of the merge window:

	state		display

	A		A
	B		B
	prefer-A	A*
	prefer-B	B*
	combined	comb

- Select default commands (d a and d b)

The "d a" and "d b" commands change all default-A's to default-B's (or
vice-versa) from the selected difference on down to the end of the
file to default-A or default-B, respectively.  But remember, any
difference that you have ever selected isn't in the default-A or
default-B state, so it will never be affected by "d a" or "d b".  This
leads to the unexpected result that "d a" or "d b" never affects the
difference selected at the moment, but prevents differences that you
have already looked at from changing unexpectedly.

If you work your way down from the top of the file, using "d a" and
"d b" at judicious points, you can effectivly make the A version the
default for some sections of the merge buffer and the B version the
default for others.

Giving the "d a" or "d b" command a prefix argument causes it to change
differences from the current point down that are in the B state (for d
a) or A state (for "d b") as well.  (Thus, the selected difference may
be changed also.)  Differences for which there is a preference will
not be affected.  (Selecting a difference won't erase its preference.)

- Exiting (q)

The quit command finishes the merge session by restoring the state of
the A and B buffers and removing the markers around the currently
selected difference.  It also disables the Emerge commands in the
merge buffer, since executing them later could damage the contents of
the various buffers.

The action of "q" depends on how Emerge was started and whether "q"
was given a prefix argument.  If there was no prefix argument, it is
considered a "successful" finish.  If there was a prefix argument, it
is considered an "unsuccessful" finish.  In either case, you are asked
to cofirm the exit, and the confirmation message tells which sort of
exit you are confirming.

If Emerge was started by some other process, success/failure is
reported to the caller.

If Emerge was started with emerge-files or emerge-files-with-ancestor,
if a prefix argument was given to that command, then you specified a
file into which the merge is to be written.  A successful exit writes
the merge into the output file and then kills the A, B, and ancestor
buffers (so they aren't lying around to confuse you, since they
probably all have similar names).

- Auto-advance mode (s a)

If auto-advance mode is set, the "a" and "b" commands perform an "n"
(select next difference) afterward.  When auto-advance mode is set,
it is indicated by "A" in the minor modes in the mode line.
"s a" with a positive argument sets auto-advance, with a non-positive
argument clears it, and with no argument toggles it.

- Skip-prefers mode (s s)

If skip-prefers mode is set, the "n" and "p" commands skip over
differences with states prefer-A and prefer-B.  Thus you will only see
differences for which one version isn't presumed "correct".  When
skip-prefers mode is set, it is indicated by "S" in the minor modes in
the mode line.  "s s" with a positive argument sets auto-advance, with
a non-positive argument clears it, and with no argument toggles it.

- Recenter (l)

The Emerge "l" command causes the selected difference to be brought
into view in the three windows, or at least, whichever of the three
merge buffers are visible at the moment.  If a prefix argument is
given, then the original three-window display is set up before the
difference texts are shown.

- Scrolling the text (^, v, <, >, and |)

Emerge has several commands which scroll all three windows by the same
amount, thus allowing you to easily compare the versions of the text.
The commands are "^" (scroll-up), "v" (scroll-down), "<"
(scroll-left), ">" (scroll-right), and "|" (reset horizontal
scrolling).  (Remember that Emacs names scrolling commands by the
motion of the text with respect to the window, so C-v is called
"scroll-up".)

If these commands (except "|") are given an argument, that is the
number of lines or characters by which the windows are scrolled.
Otherwise, the amount of motion is computed based on the dimensions of
the merge buffer window -- the height of the merge buffer window
(minus next-screen-context-lines), or half the width of the merge
buffer window.  (The A and B version windows are assumed to be as high
as the merge window, but half as wide.)  If the argument is just `C-u
-', then the scrolling is half the default amount.

- Finding the difference at or near a location (x d, x a, and x b)

The "x d" command selects the difference containing the current point
in the merge buffer.  If there is no difference containing the point,
an error is given.  An argument can be given to the command to change
this behavior: if the argument is positive (e.g., C-u), the next
following difference is selected; if the argument is negative (e.g.,
C-u -), the previous difference is selected.

The "x a" and "x b" commands select the difference containing the
current point in the A and B buffers, respectively.  Otherwise, they
act like the "x d" command.  Note that although the point used in the
commands is not the merge buffer point, the commands can only be
issued in the merge buffer, because it is the only buffer with the
Emerge keymap.

- Combining the two versions (x c, x C, and x x)

Sometimes one wants to combine the two versions of a difference.  For
instance, when merging two versions of a program, one wants to make
something like this:

	#ifdef NEW
		...new version of code...
	#else /* NEW */
		...old version of code...
	#endif /* NEW */

The "x c" command will make such a combined version.  (Note that any
combined version is not the same as either the A or B versions, and so
the "a" and "b" commands will refuse to alter it unless they are given
a prefix argument.)  The combination is made under control of a
template, which is a character string with the following
interpolations:

	%a	the A version of the difference
	%b	the B version of the difference
	%%	the character '%'

Thus, the template used above is 

	#ifdef NEW\n%b#else /* NEW */\n%a#endif /* NEW */\n

(using \n here to represent newlines).  The template is stored in the
variable emerge-combine-versions-template, and its initial value is
the one given above.  The template can be set (from the current
region) by the "x x" command.  (Be careful to get the newlines in the
template in the right places!)  ("x x" was chosen by analogy with "C-x
x".)  ("x x" is only available in the merge buffer, of course.
Elsewhere, M-x emerge-set-combine-versions-template can be used.)  If
"x x" is given a prefix argument, emerge-combine-versions-template is
localized in the merge buffer before its value is set, so the "x x"
command's effect (and the effect of any later "x x" command in the
merge buffer) is only on the merge buffer.

The "x C" command is like "x c", but it prompts for a character
which is the register whose value is to be used as the template.
This allows one to use multiple templates conveniently.

- Changing the major mode of the edit buffer (x m)

The "x m" command prompts for the name of a major-mode-setting command
(such as "c-mode" or "emacs-lisp-mode") and executes it.  Ordinarily,
major-mode-setting commands change the mode line and local keymap, so
the "x m" command then resets the Emerge mode line and the fast or
edit mode local keymap, as appropriate.

If you have already changed the major mode of the merge buffer and
lost the Emerge keymap, you can use M-x emerge-set-merge-mode to
execute this command.

Beware that "x m" accepts any command name, not just
major-mode-setting commands.

In order to use "x m", the kill-fix.el package of improvements to the
kill-all-local-variables function must be installed.  It can be
obtained from the Emacs Lisp archives by anonymous FTP from file
/pub/gnu/emacs/elisp-archive/as-is/kill-fix.el.Z on
archive.cis.ohio-state.edu.

- Writing the merge buffer manually

Emerge places a wrapper (emerge-query-and-call) on the key bindings of
save-buffer (usually "C-x C-s") and write-file (usually "C-x C-w"), in
order to protect the user from writing out the merge before it is
finished.  Emerge-query-and-call asks the user if he is sure he wants
to write out the incomplete merge.  If he answers yes, the buffer is
written out.  The flags are suppressed while the write is being done.
As a result of this, the displayed portions of the buffers are
recentered (equivalent to "l").

- Running Emerge standalone

If you invoke emacs with the following arguments, you can execute
Emerge as a standalone program:

	emacs -l emerge -f emerge-files-command file-a file-b file-out

	emacs -l emerge -f emerge-files-with-ancestor-command
		file-a file-b file-ancestor file-out

When the user gives the "q" (quit) command, Emerge will write out the
merge buffer in file-out and terminate Emacs.  If a prefix argument is
given, Emacs will terminate with an unsuccessful return code (1), if
not, it will terminate with a successful return code (0).

- Invoking Emerge remotely

If you use the Emacs client/server code that supports remote
execution, then you can invoke Emerge remotely by executing one of the
Lisp calls:

	(emerge-files-remote "file A" "file B" "output file")

	(emerge-files-with-ancestor-remote "file A" "file B"
		"ancestor file" "output file")

Returning a successful/unsuccessful return code is not yet supported
by the Emacs client/server code.

Beware that in systems of networked workstations, even though all user
directories are shared between all the workstations, the /tmp
directory on each workstation is not shared, so writing files into
/tmp and then remotely invoking Emerge is not likely to work.

- Effect of merge flags on indenting code

The presence of the flags confuses the indentation code of C and
Emacs-Lisp modes.  Starting the flag strings
(emerge-{before,after}-flag) with '#' (for C) or ';' (for Lisp)
prevents the indentation code from noticing the flags.  Remember to
change the flag strings before loading Emerge, or to execute
emerge-new-flags after changing them.  But never change the flag
strings while a merge is being performed.

- Autoloading

The following autoloads will make all top-level Emerge files
autoloading.  Make sure that "emerge" is in a directory on load-path.

(autoload 'emerge-files "emerge"
	  "Run Emerge on two files."
	  t)
(autoload 'emerge-files-with-ancestor "emerge"
	  "Run Emerge on two files, giving another file as the ancestor."
	  t)
(autoload 'emerge-buffers "emerge"
	  "Run Emerge on two buffers."
	  t)
(autoload 'emerge-buffers-with-ancestor "emerge"
	  "Run Emerge on two buffers, giving another buffer as the ancestor."
	  t)
(autoload 'emerge-files-command "emerge")
(autoload 'emerge-files-with-ancestor-command "emerge")
(autoload 'emerge-files-remote "emerge")
(autoload 'emerge-files-with-ancestor-remote "emerge")
(autoload 'emerge-revisions "emerge"
	  "Emerge two RCS revisions of a file."
	  t)
(autoload 'emerge-revisions-with-ancestor
	  "Emerge two RCS revisions of a file, giving another revision as
the ancestor."
	  t)

(autoload 'emerge-execute-line "emerge"
  "Process the current line.  Based on entries found, call emerge correctly
on the files listed."
	t)

- Use with Ange-FTP

The Ange-FTP package allows Emacs to access files using FTP much as if
they are local files.  However, diff/diff3 cannot access non-local
files, and so Emerge needs to provide additional support if non-local
files are being used.  Emerge uses the function emerge-remote-file-p
to test a file name to see whether that file name can be given
directly to diff/diff3.  If not, Emerge saves the file contents into a
temporary file, and gives the temporary file name to diff/diff3.  The
temporary file is deleted after diff/diff3 is done running.

The function emerge-remote-file-p by default causes temporary files to
be generated only for files read using Ange-FTP (which are
distinguished via the variable ange-ftp-path-format).  If Ange-FTP is
not loaded, it causes no temporary files to be generated.  The
function emerge-remote-file-p can be modified for customization.

- Filenames containing shell metacharacters

Emerge handles filenames containing shell metacharacters by quoting
them with \ before passing them to the shell.  This is normally not a
problem, except that Emacs auto-save files begin with #, which is
normally used to start comments.  Which characters are considered
metacharacters is governed by the variable emerge-metachars, whose
default value is suitable when the shell is sh, csh, or compatible
shells.

- Local variables lists

Normally, Emerge ignores any local-variables list that is created in
the merge buffer.  However, sometimes it may be useful to have a
local-variables list processed.  This can be done manually by
executing the function "(hack-local-variables)".  If the variable
emerge-process-local-variables is true, when Emerge is started it
will process any local variables list in the newly-created merge
buffer.  (If the merge has an ancestor, the selecting of default
versions of differences is done before the local variables list is
processed.)

- Semi-automatic batching of merges

If you have a large number of merges to execute, the function
emerge-execute-line can reduce the amount of work.  To use it, create
a buffer containing lines that describe the merges to be done.  Each
line describes a single merge by means of fields of the form:

	A=file1
	B=file2
	ancestor=file3
	output=file4

The fields are seperated by whitespace, and the filenames given should
be absolute, not relative.  The buffer's contents can be generated by
a program and read in as a file, or they can be generated by an Emacs
function.  (See the sample function emerge-merge-directories, which
produces specifications to merge the entire contents of two
directories, possibly with an ancestor directory and an output
directory.)

If you position the cursor on one line of the buffer and execute
emerge-execute-line, the information on that line will be read and an
appropriate merge will be started.  When the merge is finished (or
aborted), the original buffer will be displayed again, with the cursor
at the beginning of the next line, ready for the next invocation of
emerge-execute-line.  In this way, it is easy to start a sequence of
merges that are described by a buffer of specifications.

To perform a two-way merge, provide an "A" and a "B" field.  To
perform a merge with an ancestor file, provide "A", "B", and
"ancestor" fields.  In either case, if an "output" field is provided,
the results of a successful merge will be written into the designated
file, just as if a prefix argument had been given to the Emerge
command.

In addition, emerge-process-line attempts to handle situations where
one of the "A" or "B" fields are missing, showing that one version or
another of the file does not exist.  (In all cases, files that are
specified in the "A", "B", or "ancestor" fields must exist.
Non-existent files are specified by omitting the appropriate field.)
The principles governing these cases are: (1) If no "output" file is
specified, it is an error.  (2) If an "output" file is specified, then
the "A" or "B" file (whichever is present) is copied into the output
file.  (3) If an "ancestor" file is given, it is assumed that the file
in question has been deleted in one or another of the versions, and so
should be deleted from the "merged" version of the files.  Case (3) is
sufficiently dangerous that it is only activated if the variable
emerge-execute-line-deletions is set; otherwise case (3) will be
handled as case (2), that is, the one existing version will be copied
to the output file.

In all cases, the goal is to simplify the usual case of "merging two
directories that contain two versions of a system of software".

- Merging RCS versions of a file

You can merge RCS versions of a file using the commands
emerge-revisions and emerge-revisions-with-ancestor.  For both
commands, all of the input files are RCS versions of one base file,
which are checked out automatically.  If you provide a prefix
argument, upon successful completion the merged file is checked in.

- Use with Lucid Emacs

Under Lucid Emacs, Emerge highlights the selected difference rather
that bordering it with character flags.  This is probably more
natural, but it has the problem that insertions made at the very ends
of the difference may go either inside or outside of the difference,
at Emacs' discretion.  The Lucid features should be disablable by
setting emerge-lucid-p to nil, but that variable is also used to
activate workarounds to bugs in Lucid Emacs, so the user shouldn't
change its value.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.