* viper-ex.el (ex-token-list,ex-cmd-execute): Revamped, courtesy
[bpt/emacs.git] / man / ediff.texi
CommitLineData
6bf7aab6
DL
1\input texinfo @c -*-texinfo-*-
2@c documentation for Ediff
3@c Written by Michael Kifer
4
5@comment %**start of header (This is for running Texinfo on a region.)
6
7@comment Using ediff.info instead of ediff in setfilename breaks DOS.
8@comment @setfilename ediff
9@comment @setfilename ediff.info
10@setfilename ../info/ediff
11
12@settitle Ediff User's Manual
13@synindex vr cp
14@synindex fn cp
15@synindex pg cp
4960e757 16@synindex ky cp
6bf7aab6 17
d8a13805 18@dircategory Emacs
6bf7aab6
DL
19@direntry
20* Ediff: (ediff). A visual interface for comparing and merging programs.
21@end direntry
22
23@iftex
24@finalout
25@end iftex
26@c @smallbook
27@comment %**end of header (This is for running Texinfo on a region.)
28
29@ifinfo
30This file documents Ediff, a comprehensive visual interface to Unix diff
31and patch utilities.
32
b409f09b
GM
33Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
34
35Permission is granted to copy, distribute and/or modify this document
36under the terms of the GNU Free Documentation License, Version 1.1 or
37any later version published by the Free Software Foundation; with no
38Invariant Sections, with the Front-Cover texts being ``A GNU
39Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
40license is included in the section entitled ``GNU Free Documentation
41License'' in the Emacs manual.
42
43(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
44this GNU Manual, like GNU software. Copies published by the Free
45Software Foundation raise funds for GNU development.''
46
47This document is part of a collection distributed under the GNU Free
48Documentation License. If you want to distribute this document
49separately from the collection, you can do so by adding a copy of the
50license to the document, as described in section 6 of the license.
6bf7aab6
DL
51@end ifinfo
52
53@iftex
54@titlepage
55@title Ediff User's Manual
56@sp 4
57@subtitle Ediff version 2.70
58@sp 1
59@subtitle March 1998
60@sp 5
61@author Michael Kifer
62@page
63
64@vskip 0pt plus 1filll
65@noindent
b409f09b
GM
66Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
67
68Permission is granted to copy, distribute and/or modify this document
69under the terms of the GNU Free Documentation License, Version 1.1 or
70any later version published by the Free Software Foundation; with no
71Invariant Sections, with the Front-Cover texts being ``A GNU
72Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
73license is included in the section entitled ``GNU Free Documentation
74License'' in the Emacs manual.
75
76(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
77this GNU Manual, like GNU software. Copies published by the Free
78Software Foundation raise funds for GNU development.''
79
80This document is part of a collection distributed under the GNU Free
81Documentation License. If you want to distribute this document
82separately from the collection, you can do so by adding a copy of the
83license to the document, as described in section 6 of the license.
6bf7aab6
DL
84@end titlepage
85@page
86@end iftex
87
88@node Top, Introduction, (dir), (dir)
89
90
91@menu
92* Introduction:: About Ediff.
93* Major Entry Points:: How to use Ediff.
94* Session Commands:: Ediff commands used within a session.
95* Registry of Ediff Sessions:: Keeping track of multiple Ediff sessions.
96* Session Groups:: Comparing and merging directories.
97* Remote and Compressed Files:: You may want to know about this.
98* Customization:: How to make Ediff work the way YOU want.
99* Credits:: Thanks to those who helped.
100* Index::
101@end menu
102
103@node Introduction, Major Entry Points, Top, Top
104@chapter Introduction
105
106@cindex Comparing files and buffers
107@cindex Merging files and buffers
108@cindex Patching files and buffers
109@cindex Finding differences
110
111Ediff provides a convenient way for simultaneous browsing through
112the differences between a pair (or a triple) of files or buffers
113(which are called @samp{variants} for our purposes). The
114files being compared, file-A, file-B, and file-C (if applicable) are
115shown in separate windows (side by side, one above the another, or in
116separate frames), and the differences are highlighted as you step
117through them. You can also copy difference regions from one buffer to
118another (and recover old differences if you change your mind).
119
120Another powerful feature is the ability to merge a pair of files into a
121third buffer. Merging with an ancestor file is also supported.
122Furthermore, Ediff is equipped with directory-level capabilities that
123allow the user to conveniently launch browsing or merging sessions on
124groups of files in two (or three) different directories.
125
126In addition, Ediff can apply a patch to a file and then let you step though
127both files, the patched and the original one, simultaneously,
128difference-by-difference. You can even apply a patch right out of a mail
129buffer, i.e., patches received by mail don't even have to be saved. Since
130Ediff lets you copy differences between variants, you can, in effect, apply
131patches selectively (i.e., you can copy a difference region from
132@file{file.orig} to @file{file}, thereby undoing any particular patch that
133you don't like).
134
135Ediff even understands multi-file patches and can apply them interactively!
136(Ediff can recognize multi-file patches only if they are in the context
137format or GNU unified format. All other patches are treated as 1-file
d63f8c1a 138patches. Ediff is [hopefully] using the same algorithm as @code{patch} to
6bf7aab6
DL
139determine which files need to be patched.)
140
141Ediff is aware of version control, which lets you compare
142files with their older versions. Ediff also works with remote and
143compressed files, automatically ftp'ing them over and uncompressing them.
144@xref{Remote and Compressed Files}, for details.
145
146This package builds upon ideas borrowed from Emerge, and several of Ediff's
147functions are adaptations from Emerge. Although Ediff subsumes and greatly
148extends Emerge, much of the functionality in Ediff is influenced by Emerge.
149The architecture and the interface are, of course, drastically different.
150
151@node Major Entry Points, Session Commands, Introduction, Top
152@chapter Major Entry Points
153
4960e757
MK
154When Ediff starts up, it displays a small control window, which accepts the
155Ediff commands and two or three windows displaying the files to be compared
156or merged. The control window can be in its own small frame or it can be
157part of a bigger frame that displays other buffers. In any case, it is
158important that the control window be active (i.e., be the one receiving the
159keystrokes) when you use Ediff. You can switch to other Emacs buffers at
160will and even edit the files currently being compared with Ediff and then
161switch back to Ediff at any time by activating the appropriate Emacs windows.
162
6bf7aab6
DL
163Ediff can be invoked interactively using the following functions, which can
164be run either from the minibuffer or from the menu bar. In the menu bar,
165all Ediff's entry points belong to three submenus of the Tools menu:
166Compare, Merge, and Apply Patch.
167
168@table @code
169@item ediff-files
170@itemx ediff
171@findex ediff-files
172@findex ediff
173Compare two files.
174
175@item ediff-buffers
176@findex ediff-buffers
177Compare two buffers.
178
179@item ediff-files3
180@itemx ediff3
181@findex ediff-files3
182@findex ediff3
183Compare three files.
184
185@item ediff-buffers3
186@findex ediff-buffers3
187Compare three buffers.
188
189@item edirs
190@itemx ediff-directories
191@findex edirs
192@findex ediff-directories
193 Compare files common to two directories.
194@item edirs3
195@itemx ediff-directories3
196@findex edirs3
197@findex ediff-directories3
198 Compare files common to three directories.
199@item edir-revisions
200@itemx ediff-directory-revisions
201@findex ediff-directory-revisions
202@findex edir-revisions
203 Compare versions of files in a given directory. Ediff selects only the
204files that are under version control.
205@item edir-merge-revisions
206@itemx ediff-merge-directory-revisions
207@findex edir-merge-revisions
208@findex ediff-merge-directory-revisions
209 Merge versions of files in a given directory. Ediff selects only the
210files that are under version control.
211@item edir-merge-revisions-with-ancestor
212@itemx ediff-merge-directory-revisions-with-ancestor
213@findex edir-merge-revisions-with-ancestor
214@findex ediff-merge-directory-revisions-with-ancestor
215 Merge versions of files in a given directory using other versions as
216ancestors. Ediff selects only the files that are under version control.
217
218@item ediff-windows-wordwise
219@findex ediff-windows-wordwise
220Compare windows word-by-word.
221
222@item ediff-windows-linewise
223@findex ediff-windows-linewise
224Compare windows line-by-line.
225
226@item ediff-regions-wordwise
227@findex ediff-regions-wordwise
228Compare regions word-by-word.
229
230@item ediff-regions-linewise
231@findex ediff-regions-linewise
232Compare regions line-by-line.
233
234@item ediff-revision
235@findex ediff-revision
236 Compare versions of the current buffer, if the buffer is visiting
237 a file under version control.
238
239@item ediff-patch-file
240@itemx epatch
241@findex ediff-patch-file
242@findex epatch
243
244Patch a file or multiple files, then compare. If the patch applies to just
245one file, Ediff will invoke a regular comparison session. If it is a
246multi-file patch, then a session group interface will be used and the user
247will be able to patch the files selectively. @xref{Session Groups}, for
248more details.
249
3af0304a
MK
250Since the patch might be in a buffer or a file, you will be asked which is
251the case. To avoid this extra prompt, you can invoke this command with a
252prefix argument. With an odd prefix argument, Ediff assumes the patch
253is in a file; with an even argument, a buffer is assumed.
254
d63f8c1a 255Note that @code{ediff-patch-file} will actually use the @code{patch}
f918ef63 256utility to change the original files on disk. This is not that
6bf7aab6
DL
257dangerous, since you will always have the original contents of the file
258saved in another file that has the extension @file{.orig}.
259Furthermore, if the file is under version control, then you can always back
260out to one of the previous versions (see the section on Version Countrol in
261Emacs manual).
262
263@code{ediff-patch-file} is careful about versions control: if the file
264to be patched is checked in, then Ediff will offer to check it out, because
265failing to do so may result in the loss of the changes when the file is
266checked out the next time.
267
268If you don't intend to modify the file via the patch and just want to see
269what the patch is all about (and decide later), then
270@code{ediff-patch-buffer} might be a better choice.
271
272@item ediff-patch-buffer
273@itemx epatch-buffer
274@findex ediff-patch-buffer
275@findex epatch-buffer
276Patch a buffer, then compare. The buffer being patched and the file visited
277by that buffer (if any) is @emph{not} modified. The result of the patch
278appears in some other buffer that has the name ending with @emph{_patched}.
279
280This function would refuse to apply a multifile patch to a buffer. Use
281@code{ediff-patch-file} for that (and when you want the original file to be
d63f8c1a 282modified by the @code{patch} utility).
6bf7aab6 283
3af0304a
MK
284Since the patch might be in a buffer or a file, you will be asked which is
285the case. To avoid this extra prompt, you can invoke this command with a
286prefix argument. With an odd prefix argument, Ediff assumes the patch
287is in a file; with an even argument, a buffer is assumed.
288
6bf7aab6
DL
289@item ediff-merge-files
290@itemx ediff-merge
291@findex ediff-merge-files
292@findex ediff-merge
293Merge two files.
294
295@item ediff-merge-files-with-ancestor
296@itemx ediff-merge-with-ancestor
297@findex ediff-merge-files-with-ancestor
298@findex ediff-merge-with-ancestor
299Like @code{ediff-merge}, but with a third ancestor file.
300
301@item ediff-merge-buffers
302@findex ediff-merge-buffers
303Merge two buffers.
304
305@item ediff-merge-buffers-with-ancestor
306@findex ediff-merge-buffers-with-ancestor
307Same but with ancestor.
308
309
310@item edirs-merge
311@itemx ediff-merge-directories
312@findex edirs-merge
313@findex ediff-merge-directories
314 Merge files common to two directories.
315@item edirs-merge-with-ancestor
316@itemx ediff-merge-directories-with-ancestor
317@findex edirs-merge-with-ancestor
318@findex ediff-merge-directories-with-ancestor
319 Same but using files in a third directory as ancestors.
320 If a pair of files doesn't have an ancestor in the ancestor-directory, you
321 will still be able to merge them without the ancestor.
322
323@item ediff-merge-revisions
324@findex ediff-merge-revisions
325Merge two versions of the file visited by the current buffer.
326
327@item ediff-merge-revisions-with-ancestor
328@findex ediff-merge-revisions-with-ancestor
329Same but with ancestor.
330
331@item ediff-documentation
332@findex ediff-documentation
333Brings up this manual.
334
335@item ediff-show-registry
336@itemx eregistry
337Brings up Ediff session registry. This feature enables you to quickly find
338and restart active Ediff sessions.
339@end table
340
341@noindent
342If you want Ediff to be loaded from the very beginning of your Emacs
343session, you should put this line in your @file{~/.emacs} file:
344
345@example
346(require 'ediff)
347@end example
348
349@noindent
350Otherwise, Ediff will be loaded automatically when you use one of the
351above functions, either directly or through the menus.
352
353When the above functions are invoked, the user is prompted for all the
354necessary information---typically the files or buffers to compare, merge, or
355patch. Ediff tries to be smart about these prompts. For instance, in
356comparing/merging files, it will offer the visible buffers as defaults. In
357prompting for files, if the user enters a directory, the previously input
358file name will be appended to that directory. In addition, if the variable
359@code{ediff-use-last-dir} is not @code{nil}, Ediff will offer
360previously entered directories as defaults (which will be maintained
361separately for each type of file, A, B, or C).
362@vindex @code{ediff-use-last-dir}
363
364All the above functions use the POSIX @code{diff} or @code{diff3} programs
365to find differences between two files. They process the @code{diff} output
366and display it in a convenient form. At present, Ediff understands only
367the plain output from diff. Options such as @samp{-c} are not supported,
368nor is the format produced by incompatible file comparison programs such as
369the VMS version of @code{diff}.
370
371The functions @code{ediff-files}, @code{ediff-buffers},
372@code{ediff-files3}, @code{ediff-buffers3} first display the coarse,
d63f8c1a 373line-based difference regions, as reported by the @code{diff} program. The
6bf7aab6
DL
374total number of difference regions and the current difference number are
375always displayed in the mode line of the control window.
376
377Since @code{diff} may report fairly large chunks of text as being different,
378even though the difference may be localized to just a few words or even
379to the white space or line breaks, Ediff further @emph{refines} the
380regions to indicate which exact words differ. If the only difference is
381in the white space and line breaks, Ediff says so.
382
383On a color display, fine differences are highlighted with color; on a
384monochrome display, they are underlined. @xref{Highlighting Difference
385Regions}, for information on how to customize this.
386
387The functions @code{ediff-windows-wordwise},
388@code{ediff-windows-linewise}, @code{ediff-regions-wordwise} and
389@code{ediff-regions-linewise} do comparison on parts of existing Emacs
390buffers. Since @code{ediff-windows-wordwise} and
391@code{ediff-regions-wordwise} are intended for relatively small segments
392of buffers, comparison is done on the basis of words rather than lines.
393No refinement is necessary in this case. These commands are recommended
394only for relatively small regions (perhaps, up to 100 lines), because
395these functions have a relatively slow startup.
396
397To compare large regions, use @code{ediff-regions-linewise}. This
398command displays differences much like @code{ediff-files} and
399@code{ediff-buffers}.
400
401The functions @code{ediff-patch-file} and @code{ediff-patch-buffer} apply a
402patch to a file or a buffer and then run Ediff on the appropriate
403files/buffers, displaying the difference regions.
404
405The entry points @code{ediff-directories}, @code{ediff-merge-directories},
406etc., provide a convenient interface for comparing and merging files in
407different directories. The user is presented with Dired-like interface from
408which one can run a group of related Ediff sessions.
409
410For files under version control, @code{ediff-revision} lets you compare
411the file visited by the current buffer to one of its checked-in versions.
412You can also compare two checked-in versions of the visited file.
413Moreover, the functions @code{ediff-directory-revisions},
414@code{ediff-merge-directory-revisions}, etc., let you run a group of
415related Ediff sessions by taking a directory and comparing (or merging)
416versions of files in that directory.
417
418@node Session Commands, Registry of Ediff Sessions, Major Entry Points, Top
419@chapter Session Commands
420
421All Ediff commands are displayed in a Quick Help window, unless you type
422@kbd{?} to shrink the window to just one line. You can redisplay the help
423window by typing @kbd{?} again. The Quick Help commands are detailed below.
424
425Many Ediff commands take numeric prefix arguments. For instance, if you
426type a number, say 3, and then @kbd{j} (@code{ediff-jump-to-difference}),
427Ediff moves to the third difference region. Typing 3 and then @kbd{a}
428(@code{ediff-diff-to-diff}) copies the 3d difference region from variant A
429to variant B. Likewise, 4 followed by @kbd{ra} restores the 4th difference
430region in buffer A (if it was previously written over via the command
431@kbd{a}).
432
433Some commands take negative prefix arguments as well. For instance, typing
434@kbd{-} and then @kbd{j} will make the last difference region
435current. Typing @kbd{-2} then @kbd{j} makes the penultimate difference
436region current, etc.
437
438Without the prefix argument, all commands operate on the currently
439selected difference region. You can make any difference region
440current using the various commands explained below.
441
442For some commands, the actual value of the prefix argument is
443immaterial. However, if supplied, the prefix argument may modify the
444command (see @kbd{ga}, @kbd{gb}, and @kbd{gc}).
445
446@menu
447* Quick Help Commands:: Frequently used commands.
448* Other Session Commands:: Commands that are not bound to keys.
449@end menu
450
451@node Quick Help Commands,Other Session Commands,,Session Commands
452@section Quick Help Commands
453
454@table @kbd
455@item ?
4960e757 456@kindex ?
6bf7aab6
DL
457Toggles the Ediff Quick Help window ON and OFF.
458@item G
4960e757 459@kindex G
6bf7aab6
DL
460Prepares a mail buffer for sending a praise or a curse to the Ediff maintainer.
461
462@item E
4960e757 463@kindex E
6bf7aab6
DL
464Brings up the top node of this manual, where you can find further
465information on the various Ediff functions and advanced issues, such as
466customization, session groups, etc.
467
468@item v
4960e757 469@kindex v
6bf7aab6
DL
470Scrolls up buffers A and B (and buffer C where appropriate) in a
471coordinated fashion.
472@item V
4960e757 473@kindex V
6bf7aab6
DL
474Scrolls the buffers down.
475
476@item <
4960e757 477@kindex <
6bf7aab6
DL
478Scrolls the buffers to the left simultaneously.
479@item >
4960e757 480@kindex >
6bf7aab6
DL
481Scrolls buffers to the right.
482
483@item wd
4960e757 484@kindex wd
6bf7aab6
DL
485Saves the output from the diff utility, for further reference.
486
d63f8c1a 487With prefix argument, saves the plain output from @code{diff} (see
6bf7aab6 488@code{ediff-diff-program} and @code{ediff-diff-options}). Without the
d63f8c1a 489argument, it saves customized @code{diff} output (see
6bf7aab6
DL
490@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options}), if
491it is available.
492
493@item wa
4960e757 494@kindex wa
6bf7aab6
DL
495Saves buffer A, if it was modified.
496@item wb
4960e757 497@kindex wb
6bf7aab6
DL
498Saves buffer B, if it was modified.
499@item wc
4960e757 500@kindex wc
6bf7aab6
DL
501Saves buffer C, if it was modified (if you are in a session that
502compares three files simultaneously).
503
504@item a
4960e757 505@kindex a
6bf7aab6
DL
506@emph{In comparison sessions:}
507Copies the current difference region (or the region specified as the prefix
508to this command) from buffer A to buffer B.
509Ediff saves the old contents of buffer B's region; it can
510be restored via the command @kbd{rb}, which see.
511
512@emph{In merge sessions:}
513Copies the current difference region (or the region specified as the prefix
514to this command) from buffer A to the merge buffer. The old contents of
515this region in buffer C can be restored via the command @kbd{r}.
516
517@item b
4960e757 518@kindex b
6bf7aab6
DL
519Works similarly, but copies the current difference region from buffer B to
520buffer A (in @emph{comparison sessions}) or the merge buffer (in
521@emph{merge sessions}).
522
523Ediff saves the old contents of the difference region copied over; it can
524be reinstated via the command @kbd{ra} in comparison sessions and
525@kbd{r} in merge sessions.
526
527@item ab
4960e757 528@kindex ab
6bf7aab6
DL
529Copies the current difference region (or the region specified as the prefix
530to this command) from buffer A to buffer B. This (and the next five)
531command is enabled only in sessions that compare three files
532simultaneously. The old region in buffer B is saved and can be restored
533via the command @kbd{rb}.
534@item ac
4960e757 535@kindex ac
6bf7aab6
DL
536Copies the difference region from buffer A to buffer C.
537The old region in buffer C is saved and can be restored via the command
538@kbd{rc}.
539@item ba
4960e757 540@kindex ba
6bf7aab6
DL
541Copies the difference region from buffer B to buffer A.
542The old region in buffer A is saved and can be restored via the command
543@kbd{ra}.
544@item bc
4960e757 545@kindex bc
6bf7aab6
DL
546Copies the difference region from buffer B to buffer C.
547The command @kbd{rc} undoes this.
548@item ca
4960e757 549@kindex ca
6bf7aab6
DL
550Copies the difference region from buffer C to buffer A.
551The command @kbd{ra} undoes this.
552@item cb
4960e757 553@kindex cb
6bf7aab6
DL
554Copies the difference region from buffer C to buffer B.
555The command @kbd{rb} undoes this.
556
557@item p
558@itemx DEL
4960e757
MK
559@kindex p
560@kindex DEL
6bf7aab6
DL
561Makes the previous difference region current.
562@item n
563@itemx SPC
4960e757
MK
564@kindex n
565@kindex SPC
6bf7aab6
DL
566Makes the next difference region current.
567
568@item j
569@itemx -j
570@itemx Nj
4960e757 571@kindex j
6bf7aab6
DL
572Makes the very first difference region current.
573
574@kbd{-j} makes the last region current. Typing a number, N, and then `j'
575makes the difference region N current. Typing -N (a negative number) then
576`j' makes current the region Last - N.
577
578@item ga
4960e757 579@kindex ga
6bf7aab6
DL
580Makes current the difference region closest to the position of the point in
581buffer A.
582
583However, with a prefix argument, Ediff would position all variants
584around the area indicated by the current point in buffer A: if
585the point is inside a difference region, then the variants will be
586positioned at this difference region. If the point is not in any difference
587region, then it is in an area where all variants agree with each other. In
588this case, the variants will be positioned so that each would display this
589area (of agreement).
590@item gb
4960e757 591@kindex gb
6bf7aab6
DL
592Makes current the difference region closest to the position of the point in
593buffer B.
594
595With a prefix argument, behaves like @kbd{ga}, but with respect to buffer B.
596@item gc
4960e757 597@kindex gc
6bf7aab6
DL
598@emph{In merge sessions:}
599makes current the difference region closest to the point in the merge buffer.
600
601@emph{In 3-file comparison sessions:}
602makes current the region closest to the point in buffer C.
603
604With a prefix argument, behaves like @kbd{ga}, but with respect to buffer C.
605
606@item !
4960e757 607@kindex !
6bf7aab6
DL
608Recomputes the difference regions, bringing them up to date. This is often
609needed because it is common to do all sorts of editing during Ediff
610sessions, so after a while, the highlighted difference regions may no
611longer reflect the actual differences among the buffers.
612
613@item *
4960e757 614@kindex *
6bf7aab6
DL
615Forces refinement of the current difference region, which highlights the exact
616words of disagreement among the buffers. With a negative prefix argument,
617unhighlights the current region.
618
619Forceful refinement may be needed if Ediff encounters a difference region
620that is larger than @code{ediff-auto-refine-limit}. In this situation,
621Ediff doesn't do automatic refinement in order to improve response time.
622(Ediff doesn't auto-refine on dumb terminals as well, but @kbd{*} still
623works there. However, the only useful piece of information it can tell you
624is whether or not the difference regions disagree only in the amount of
625white space.)
626
627This command is also useful when the highlighted fine differences are
628no longer current, due to user editing.
629
630@item m
4960e757 631@kindex m
6bf7aab6
DL
632Displays the current Ediff session in a frame as wide as the physical
633display. This is useful when comparing files side-by-side. Typing `m' again
634restores the original size of the frame.
635
636@item |
4960e757 637@kindex |
6bf7aab6
DL
638Toggles the horizontal/vertical split of the Ediff display. Horizontal
639split is convenient when it is possible to compare files
640side-by-side. If the frame in which files are displayed is too narrow
641and lines are cut off, typing @kbd{m} may help some.
642
643@item @@
4960e757 644@kindex @@
6bf7aab6
DL
645Toggles auto-refinement of difference regions (i.e., automatic highlighting
646of the exact words that differ among the variants). Auto-refinement is
647turned off on devices where Emacs doesn't support highlighting.
648
649On slow machines, it may be advantageous to turn auto-refinement off. The
650user can always forcefully refine specific difference regions by typing
651@kbd{*}.
652
653@item h
4960e757 654@kindex h
6bf7aab6
DL
655Cycles between full highlighting, the mode where fine differences are not
656highlighted (but computed), and the mode where highlighting is done with
657ASCII strings. The latter is not really recommended, unless on a dumb TTY.
658
659@item r
4960e757 660@kindex r
6bf7aab6
DL
661Restores the old contents of the region in the merge buffer.
662(If you copied a difference region from buffer A or B into the merge buffer
663using the commands @kbd{a} or @kbd{b}, Ediff saves the old contents of the
664region in case you change your mind.)
665
666This command is enabled in merge sessions only.
667
668@item ra
4960e757 669@kindex ra
6bf7aab6
DL
670Restores the old contents of the current difference region in buffer A,
671which was previously saved when the user invoked one of these commands:
672@kbd{b}, @kbd{ba}, @kbd{ca}, which see. This command is enabled in
673comparison sessions only.
674@item rb
4960e757 675@kindex rb
6bf7aab6
DL
676Restores the old contents of the current difference region in buffer B,
677which was previously saved when the user invoked one of these commands:
678@kbd{a}, @kbd{ab}, @kbd{cb}, which see. This command is enabled in
679comparison sessions only.
680@item rc
4960e757 681@kindex rc
6bf7aab6
DL
682Restores the old contents of the current difference region in buffer C,
683which was previously saved when the user invoked one of these commands:
684@kbd{ac}, @kbd{bc}, which see. This command is enabled in 3-file
685comparison sessions only.
686
687@item ##
4960e757 688@kindex ##
6bf7aab6
DL
689Tell Ediff to skip over regions that disagree among themselves only in the
690amount of white space and line breaks.
691
692Even though such regions will be skipped over, you can still jump to any
693one of them by typing the region number and then `j'. Typing @kbd{##}
694again puts Ediff back in the original state.
695
696@item #h
697@itemx #f
4960e757
MK
698@kindex #f
699@kindex #h
6bf7aab6
DL
700Ediff works hard to ameliorate the effects of boredom in the workplace...
701
702Quite often differences are due to identical replacements (e.g., the word
703`foo' is replaced with the word `bar' everywhere). If the number of regions
704with such boring differences exceeds your tolerance threshold, you may be
705tempted to tell Ediff to skip these regions altogether (you will still be able
706to jump to them via the command @kbd{j}). The above commands, @kbd{#h}
707and @kbd{#f}, may well save your day!
708
709@kbd{#h} prompts you to specify regular expressions for each
710variant. Difference regions where each variant's region matches the
711corresponding regular expression will be skipped from then on. (You can
712also tell Ediff to skip regions where at least one variant matches its
713regular expression.)
714
715@kbd{#f} does dual job: it focuses on regions that match the corresponding
716regular expressions. All other regions will be skipped
717over. @xref{Selective Browsing}, for more.
718
719@item A
4960e757 720@kindex A
6bf7aab6
DL
721Toggles the read-only property in buffer A.
722If file A is under version control and is checked in, it is checked out
723(with your permission).
724@item B
4960e757 725@kindex B
6bf7aab6
DL
726Toggles the read-only property in buffer B.
727If file B is under version control and is checked in, it is checked out.
728@item C
4960e757 729@kindex C
6bf7aab6
DL
730Toggles the read-only property in buffer C (in 3-file comparison sessions).
731If file C is under version control and is checked in, it is checked out.
732
733@item ~
4960e757 734@kindex ~
6bf7aab6
DL
735Swaps the windows where buffers A and B are displayed. If you are comparing
736three buffers at once, then this command would rotate the windows among
737buffers A, B, and C.
738
739@item i
4960e757 740@kindex i
6bf7aab6
DL
741Displays all kinds of useful data about the current Ediff session.
742@item D
4960e757 743@kindex D
6bf7aab6
DL
744Runs @code{ediff-custom-diff-program} on the variants and displays the
745buffer containing the output. This is useful when you must send the output
746to your Mom.
747
d63f8c1a 748With a prefix argument, displays the plain @code{diff} output.
6bf7aab6
DL
749@xref{Patch and Diff Programs}, for details.
750
751@item R
4960e757 752@kindex R
6bf7aab6
DL
753Displays a list of currently active Ediff sessions---the Ediff Registry.
754You can then restart any of these sessions by either clicking on a session
755record or by putting the cursor over it and then typing the return key.
756
757(Some poor souls leave so many active Ediff sessions around that they loose
758track of them completely... The `R' command is designed to save these
759people from the recently discovered Ediff Proficiency Syndrome.)
760
761Typing @kbd{R} brings up Ediff Registry only if it is typed into an Ediff
762Control Panel. If you don't have a control panel handy, type this in the
763minibuffer: @kbd{M-x eregistry}. @xref{Registry of Ediff Sessions}.
764
765@item M
4960e757 766@kindex M
6bf7aab6
DL
767Shows the session group buffer that invoked the current Ediff session.
768@xref{Session Groups}, for more information on session groups.
769
770@item z
4960e757 771@kindex z
6bf7aab6
DL
772Suspends the current Ediff session. (If you develop a condition known as
773Repetitive Ediff Injury---a serious but curable illness---you must change
774your current activity. This command tries hard to hide all Ediff-related
775buffers.)
776
777The easiest way to resume a suspended Ediff session is through the registry
778of active sessions. @xref{Registry of Ediff Sessions}, for details.
779@item q
4960e757 780@kindex q
6bf7aab6
DL
781Terminates this Ediff session. With a prefix argument (e.g.,@kbd{1q}), asks
782if you also want to delete the buffers of the variants.
783Modified files and the results of merges are never deleted.
784
785@item %
4960e757 786@kindex %
6bf7aab6
DL
787Toggles narrowing in Ediff buffers. Ediff buffers may be narrowed if you
788are comparing only parts of these buffers via the commands
789@code{ediff-windows-*} and @code{ediff-regions-*}, which see.
790
791@item C-l
4960e757 792@kindex C-l
6bf7aab6
DL
793Restores the usual Ediff window setup. This is the quickest way to resume
794an Ediff session, but it works only if the control panel of that session is
795visible.
796
3af0304a 797@item $$
4960e757 798@kindex $$
6bf7aab6
DL
799While merging with an ancestor file, Ediff is determined to reduce user's
800wear and tear by saving him and her much of unproductive, repetitive
801typing. If it notices that, say, file A's difference region is identical to
802the same difference region in the ancestor file, then the merge buffer will
803automatically get the difference region taken from buffer B. The rationale
804is that this difference region in buffer A is as old as that in the
805ancestor buffer, so the contents of that region in buffer B represents real
806change.
807
808You may want to ignore such `obvious' merges and concentrate on difference
809regions where both files `clash' with the ancestor, since this means that
810two different people have been changing this region independently and they
811had different ideas on how to do this.
812
813The above command does this for you by skipping the regions where only one
814of the variants clashes with the ancestor but the other variant agrees with
3af0304a
MK
815it. Typing @kbd{$$} again undoes this setting.
816
817@item $*
4960e757 818@kindex $*
3af0304a
MK
819When merging files with large number of differences, it is sometimes
820convenient to be able to skip the difference regions for which you already
821decided which variant is most appropriate. Typing @kbd{$*} will accomplish
822precisely this.
823
824To be more precise, this toggles the check for whether the current merge is
825identical to its default setting, as originally decided by Ediff. For
826instance, if Ediff is merging according to the `combined' policy, then the
827merge region is skipped over if it is different from the combination of the
828regions in buffers A and B. (Warning: swapping buffers A and B will confuse
829things in this respect). If the merge region is marked as `prefer-A' then
830this region will be skipped if it differs from the current difference
831region in buffer A, etc.
6bf7aab6
DL
832
833@item /
4960e757 834@kindex /
6bf7aab6
DL
835Displays the ancestor file during merges.
836@item &
4960e757 837@kindex &
6bf7aab6
DL
838In some situations, such as when one of the files agrees with the ancestor file
839on a difference region and the other doesn't, Ediff knows what to do: it copies
840the current difference region from the second buffer into the merge buffer.
841
842In other cases, the right course of action is not that clearcut, and Ediff
843would use a default action. The above command changes the default action.
844The default action can be @samp{default-A} (choose the region from buffer
845A), @samp{default-B} (choose the region from buffer B), or @samp{combined}
846(combine the regions from the two buffers).
847@xref{Merging and diff3}, for further details.
848
849The command @kbd{&} also affects the regions in the merge buffers that have
850@samp{default-A}, @samp{default-B}, or @samp{combined} status, provided
851they weren't changed with respect to the original. For instance, if such a
852region has the status @samp{default-A} then changing the default action to
853@samp{default-B} will also replace this merge-buffer's region with the
854corresponding region from buffer B.
855
856@item s
4960e757 857@kindex s
6bf7aab6
DL
858Causes the merge window shrink to its minimum size, thereby exposing as much
859of the variant buffers as possible. Typing `s' again restores
860the original size of that window.
861
862With a positive prefix argument, this command enlarges the merge window.
863E.g., @kbd{4s} increases the size of the window by about 4 lines, if
864possible. With a negative numeric argument, the size of the merge window
865shrinks by that many lines, if possible. Thus, @kbd{-s} shrinks the window
866by about 1 line and @kbd{-3s} by about 3 lines.
867
868This command is intended only for temporary viewing; therefore, Ediff
869restores window C to its original size whenever it makes any other change
870in the window configuration. However, redisplaying (@kbd{C-l}) or jumping
871to another difference does not affect window C's size.
872
873The split between the merge window and the variant windows is controlled by
874the variable @code{ediff-merge-window-share}, which see.
875
876@item +
4960e757 877@kindex +
6bf7aab6
DL
878Combines the difference regions from buffers A and B and copies the
879result into the merge buffer. @xref{Merging and diff3}, and the
880variables @code{ediff-combine-diffs} and @code{ediff-combination-pattern}.
881
882
883@item =
4960e757 884@kindex =
6bf7aab6
DL
885You may run into situations when a large chunk of text in one file has been
886edited and then moved to a different place in another file. In such a case,
887these two chunks of text are unlikely to belong to the same difference
888region, so the refinement feature of Ediff will not be able to tell you
889what exactly differs inside these chunks. Since eyeballing large pieces of
890text is contrary to human nature, Ediff has a special command to help
891reduce the risk of developing a cataract.
892
893The above command compares regions within Ediff buffers. This creates a
894child Ediff session for comparing current Emacs regions in buffers A, B, or
895C as follows:
896
897@emph{If you are comparing 2 files or buffers:}
898Ediff would compare current Emacs regions in buffers A and B.
899
900@emph{If you are comparing 3 files or buffers simultaneously:} Ediff would
901compare the current Emacs regions in the buffers of your choice (you will
902be asked which two of the three buffers to use).
903
904@emph{If you are merging files or buffers (with or without ancestor):}
905Ediff would take the current region in the merge buffer and compare
906it to the current region in the buffer of your choice (A or B).
907
4960e757
MK
908@emph{Note: In all these cases you must first switch to the appropriate
909Emacs buffers and manually set the regions that you want to compare.}
910
6bf7aab6
DL
911Highlighting set by the parent Ediff session is removed, to avoid interference
912with highlighting of the child session. When done with the child session, type
913@kbd{C-l} in the parent's control panel to restore the original highlighting.
914
915If you temporarily switch to the parent session, parent highlighting will be
916restored. If you then come back to the child session, you may want to remove
917parent highlighting, so it won't interfere. Typing @kbd{h} may help here.
918
919@end table
920
921@node Other Session Commands,,Quick Help Commands,Session Commands
922@section Other Session Commands
923
924The following commands can be invoked from within any Ediff session,
925although some of them are not bound to a key.
926
927@table @code
928@item eregistry
929@itemx ediff-show-registry
930@findex eregistry
931@findex ediff-show-registry
932This command brings up the registry of active Ediff sessions. Ediff
933registry is a device that can be used to resume any active Ediff session
934(which may have been postponed because the user switched to some other
935activity). This command is also useful for switching between multiple
936active Ediff sessions that are run at the same time. The function
937@code{eregistry} is an alias for @code{ediff-show-registry}.
938@xref{Registry of Ediff Sessions}, for more information on this registry.
939
940@item ediff-toggle-multiframe
941@findex ediff-toggle-multiframe
942Changes the display from the multi-frame mode (where the quick help window
943is in a separate frame) to the single-frame mode (where all Ediff buffers
944share the same frame), and vice versa. See
945@code{ediff-window-setup-function} for details on how to make either of
946these modes the default one.
947
948This function can also be invoked from the Menubar. However, in some
949cases, the change will take place only after you execute one of the Ediff
950commands, such as going to the next difference or redisplaying.
951
952@item ediff-revert-buffers-then-recompute-diffs
953@findex ediff-revert-buffers-then-recompute-diffs
954This command reverts the buffers you are comparing and recomputes their
955differences. It is useful when, after making changes, you decided to
956make a fresh start, or if at some point you changed the files being
957compared but want to discard any changes to comparison buffers that were
958done since then.
959
960This command normally asks for confirmation before reverting files.
961With a prefix argument, it reverts files without asking.
962
963
964@item ediff-profile
965@findex ediff-profile
966Ediff has an admittedly primitive (but useful) facility for profiling
967Ediff's commands. It is meant for Ediff maintenance---specifically, for
968making it run faster. The function @code{ediff-profile} toggles
969profiling of ediff commands.
970@end table
971
972@node Registry of Ediff Sessions, Session Groups, Session Commands, Top
973@chapter Registry of Ediff Sessions
974
975Ediff maintains a registry of all its invocations that are
976still @emph{active}. This feature is very convenient for switching among
977active Ediff sessions or for quickly restarting a suspended Ediff session.
978
979The focal point of this activity is a buffer
980called @emph{*Ediff Registry*}. You can display this buffer by typing
981@kbd{R} in any Ediff Control Buffer or Session Group Buffer
982(@pxref{Session Groups}), or by typing
983@kbd{M-x eregistry} into the Minibuffer.
984The latter would be the fastest way to bring up the registry
985buffer if no control or group buffer is displayed in any of the visible
986Emacs windows.
987If you are in a habit of running multiple long Ediff sessions and often need to
988suspend, resume, or switch between them, it may be a good idea to have the
989registry buffer permanently displayed in a separate, dedicated window.
990
991The registry buffer has several convenient key bindings.
992For instance, clicking mouse button 2 or typing
993@kbd{RET} or @kbd{v} over any session record resumes that session.
994Session records in the registry buffer provide a fairly complete
995description of each session, so it is usually easy to identify the right
996session to resume.
997
998Other useful commands are bound to @kbd{SPC} (next registry record)
999and @kbd{DEL} (previous registry record). There are other commands as well,
1000but you don't need to memorize them, since they are listed at the top of
1001the registry buffer.
1002
1003@node Session Groups, Remote and Compressed Files, Registry of Ediff Sessions, Top
1004@chapter Session Groups
1005
1006Several major entries of Ediff perform comparison and merging on
1007directories. On entering @code{ediff-directories},
1008@code{ediff-directories3},
1009@code{ediff-merge-directories},
1010@code{ediff-merge-directories-with-ancestor},
1011@code{ediff-directory-revisions},
1012@code{ediff-merge-directory-revisions}, or
1013@code{ediff-merge-directory-revisions-with-ancestor},
1014the user is presented with a
1015Dired-like buffer that lists files common to the directories involved along
1016with their sizes. (The list of common files can be further filtered through
1017a regular expression, which the user is prompted for.) We call this buffer
1018@emph{Session Group Panel} because all Ediff sessions associated with the
1019listed files will have this buffer as a common focal point.
1020
1021Clicking button 2 or typing @kbd{RET} or @kbd{v} over a
1022record describing files invokes Ediff in the appropriate mode on these
1023files. You can come back to the session group buffer associated with a
1024particular invocation of Ediff by typing @kbd{M} in Ediff control buffer of
1025that invocation.
1026
1027Many commands are available in the session group buffer; some are
1028applicable only to certain types of work. The relevant commands are always
1029listed at the top of each session group buffer, so there is no need to
1030memorize them.
1031
1032In directory comparison or merging, a session group panel displays only the
1033files common to all directories involved. The differences are kept in a
1034separate buffer and are conveniently displayed by typing @kbd{D} to the
1035corresponding session group panel. Thus, as an added benefit, Ediff can be
1036used to compare the contents of up to three directories.
1037
1038Session records in session group panels are also marked with @kbd{+}, for
1039active sessions, and with @kbd{-}, for finished sessions.
1040
1041Sometimes, it is convenient to exclude certain sessions from a group.
1042Usually this happens when the user doesn't intend to run Ediff of certain
1043files in the group, and the corresponding session records just add clutter
1044to the session group buffer. To help alleviate this problem, the user can
1045type @kbd{h} to mark a session as a candidate for exclusion and @kbd{x} to
1046actually hide the marked sessions. There actions are reversible: with a
1047prefix argument, @kbd{h} unmarks the session under the cursor, and @kbd{x}
1048brings the hidden sessions into the view (@kbd{x} doesn't unmark them,
1049though, so the user has to explicitly unmark the sessions of interest).
1050
1051Group sessions also understand the command @kbd{m}, which marks sessions
1052for future operations (other than hiding) on a group of sessions. At present,
1053the only such group-level operation is the creation of a multi-file patch.
1054
1055@vindex ediff-autostore-merges
1056For group sessions created to merge files, Ediff can store all merges
1057automatically in a directory. The user is asked to specify such directory
1058if the value of @code{ediff-autostore-merges} is non-nil. If the value is
1059@code{nil}, nothing is done to the merge buffers---it will be the user's
1060responsibility to save them. If the value is @code{t}, the user will be
1061asked where to save the merge buffers in all merge jobs, even those that do
1062not originate from a session group. It the value is neither @code{nil} nor
1063@code{t}, the merge buffer is saved @emph{only} if this merge session was
1064invoked from a session group. This behavior is implemented in the function
1065@code{ediff-maybe-save-and-delete-merge}, which is a hook in
1066@code{ediff-quit-merge-hook}. The user can supply a different hook, if
1067necessary.
1068
1069The variable @code{ediff-autostore-merges} is buffer-local, so it can be
6de3983f
MK
1070set on a per-buffer basis. Therefore, use @code{setq-default} to change
1071this variable globally.
6bf7aab6
DL
1072
1073@cindex Multi-file patches
1074A multi-file patch is a concatenated output of several runs of the Unix
d63f8c1a 1075@code{diff} command (some versions of @code{diff} let you create a
6bf7aab6
DL
1076multi-file patch in just one run). Ediff facilitates creation of
1077multi-file patches as follows. If you are in a session group buffer
1078created in response to @code{ediff-directories} or
1079@code{ediff-directory-revisions}, you can mark (by typing @kbd{m}) the
1080desired Ediff sessions and then type @kbd{P} to create a
1081multi-file patch of those marked sessions.
1082Ediff will then display a buffer containing the patch.
d63f8c1a 1083The patch is generated by invoking @code{diff} on all marked individual
6bf7aab6
DL
1084sessions (represented by files) and session groups (represented by
1085directories). Ediff will also recursively descend into any @emph{unmarked}
1086session group and will search for marked sessions there. In this way, you
1087can create multi-file patches that span file subtrees that grow out of
1088any given directory.
1089
1090In an @code{ediff-directories} session, it is enough to just mark the
1091requisite sessions. In @code{ediff-directory-revisions} revisions, the
1092marked sessions must also be active, or else Ediff will refuse to produce a
1093multi-file patch. This is because, in the latter-style sessions, there are
1094many ways to create diff output, and it is easier to handle by running
1095Ediff on the inactive sessions.
1096
1097Last, but not least, by typing @kbd{=}, you can quickly find out which
1098sessions have identical files, so you won't have to run Ediff on those
1099sessions. This, however, works only on local, uncompressed files.
1100For compressed or remote files, this command won't report anything.
1101
1102
1103@node Remote and Compressed Files, Customization, Session Groups, Top
1104@chapter Remote and Compressed Files
1105
1106Ediff works with remote, compressed, and encrypted files. Ediff
1107supports @file{ange-ftp.el}, @file{jka-compr.el}, @file{uncompress.el}
1108and @file{crypt++.el}, but it may work with other similar packages as
1109well. This means that you can compare files residing on another
1110machine, or you can apply a patch to a file on another machine. Even
1111the patch itself can be a remote file!
1112
1113When patching compressed or remote files, Ediff does not rename the source
1114file (unlike what the @code{patch} utility would usually do). Instead, the
1115source file retains its name and the result of applying the patch is placed
1116in a temporary file that has the suffix @file{_patched} attached.
1117Generally, this applies to files that are handled using black magic, such
1118as special file handlers (ange-ftp and some compression and encryption
1119packages also use this method).
1120
1121Regular files are treated by the @code{patch} utility in the usual manner,
1122i.e., the original is renamed into @file{source-name.orig} and the result
1123of the patch is placed into the file source-name (@file{_orig} is used
1124on systems like VMS, DOS, etc.)
1125
1126@node Customization, Credits, Remote and Compressed Files, Top
1127@chapter Customization
1128
1129Ediff has a rather self-explanatory interface, and in most cases you
1130won't need to change anything. However, should the need arise, there are
1131extensive facilities for changing the default behavior.
1132
1133Most of the customization can be done by setting various variables in the
1134@file{.emacs} file. Some customization (mostly window-related
1135customization and faces) can be done by putting appropriate lines in
1136@file{.Xdefaults}, @file{.xrdb}, or whatever X resource file is in use.
1137
1138With respect to the latter, please note that the X resource
1139for Ediff customization is `Ediff', @emph{not} `emacs'.
1140@xref{Window and Frame Configuration},
1141@xref{Highlighting Difference Regions}, for further details. Please also
1142refer to Emacs manual for the information on how to set Emacs X resources.
1143
1144@menu
1145* Hooks:: Customization via the hooks.
1146* Quick Help Customization:: How to customize Ediff's quick help feature.
1147* Window and Frame Configuration:: Controlling the way Ediff displays things.
1148* Selective Browsing:: Advanced browsing through difference regions.
1149* Highlighting Difference Regions:: Controlling highlighting.
1150* Narrowing:: Comparing regions, windows, etc.
1151* Refinement of Difference Regions:: How to control the refinement process.
1152* Patch and Diff Programs:: Changing the utilities that compute differences
1153 and apply patches.
1154* Merging and diff3:: How to customize Ediff in its Merge Mode.
1155* Support for Version Control:: Changing the version control package.
1156 You are not likely to do that.
1157* Customizing the Mode Line:: Changing the look of the mode line in Ediff.
1158* Miscellaneous:: Other customization.
1159* Notes on Heavy-duty Customization:: Customization for the gurus.
1160@end menu
1161
1162@node Hooks, Quick Help Customization, Customization, Customization
1163@section Hooks
1164
1165The bulk of customization can be done via the following hooks:
1166
1167@table @code
1168@item ediff-load-hook
1169@vindex ediff-load-hook
1170This hook can be used to change defaults after Ediff is loaded.
1171
657f9cb8
MK
1172@item ediff-before-setup-hook
1173@vindex ediff-before-setup-hook
1174Hook that is run just before Ediff rearranges windows to its liking.
1175Can be used to save windows configuration.
1176
6bf7aab6
DL
1177@item ediff-keymap-setup-hook
1178@vindex ediff-keymap-setup-hook
1179@vindex ediff-mode-map
1180This hook can be used to alter bindings in Ediff's keymap,
1181@code{ediff-mode-map}. These hooks are
1182run right after the default bindings are set but before
1183@code{ediff-load-hook}. The regular user needs not be concerned with this
1184hook---it is provided for implementors of other Emacs packages built on top
1185of Ediff.
1186
1187@item ediff-before-setup-windows-hook
1188@itemx ediff-after-setup-windows-hook
1189@vindex ediff-before-setup-windows-hook
1190@vindex ediff-after-setup-windows-hook
1191These two hooks are called before and after Ediff sets up its window
657f9cb8
MK
1192configuration. These hooks are run each time Ediff rearranges windows to
1193its liking. This happens whenever it detects that the user changed the
1194windows setup.
6bf7aab6
DL
1195
1196@item ediff-suspend-hook
1197@itemx ediff-quit-hook
1198@vindex ediff-suspend-hook
1199@vindex ediff-quit-hook
1200These two hooks are run when you suspend or quit Ediff. They can be
1201used to set desired window configurations, delete files Ediff didn't
1202want to clean up after exiting, etc.
1203
1204By default, @code{ediff-quit-hook} holds one hook function,
1205@code{ediff-cleanup-mess}, which cleans after Ediff, as appropriate in
1206most cases. You probably won't want to change it, but you might
1207want to add other hook functions.
1208
1209Keep in mind that hooks executing before @code{ediff-cleanup-mess} start
1210in @code{ediff-control-buffer;} they should also leave
1211@code{ediff-control-buffer} as the current buffer when they finish.
1212Hooks that are executed after @code{ediff-cleanup-mess} should expect
1213the current buffer be either buffer A or buffer B.
1214@code{ediff-cleanup-mess} doesn't kill the buffers being compared or
1215merged (see @code{ediff-cleanup-hook}, below).
1216
1217@item ediff-cleanup-hook
1218@vindex ediff-cleanup-hook
1219This hook is run just before @code{ediff-quit-hook}. This is a good
1220place to do various cleanups, such as deleting the variant buffers.
1221Ediff provides a function, @code{ediff-janitor}, as one such possible
1222hook, which you can add to @code{ediff-cleanup-hook} with
1223@code{add-hooks}.
1224
1225@findex ediff-janitor
1226This function kills buffers A, B, and, possibly, C, if these buffers aren't
1227modified. In merge jobs, buffer C is never deleted. However, the side
1228effect of using this function is that you may not be able to compare the
1229same buffer in two separate Ediff sessions: quitting one of them will
1230delete this buffer in another session as well.
1231
1232@item ediff-quit-merge-hook
1233@vindex ediff-quit-merge-hook
1234@vindex ediff-autostore-merges
1235@findex ediff-maybe-save-and-delete-merge
1236This hook is called when Ediff quits a merge job. By default, the value is
1237@code{ediff-maybe-save-and-delete-merge}, which is a function that attempts
1238to save the merge buffer according to the value of
1239@code{ediff-autostore-merges}, as described later.
1240
1241@item ediff-before-setup-control-frame-hook
1242@itemx ediff-after-setup-control-frame-hook
1243@vindex ediff-before-setup-control-frame-hook
1244@vindex ediff-after-setup-control-frame-hook
1245These two hooks run before and after Ediff sets up the control frame.
1246They can be used to relocate Ediff control frame when Ediff runs in a
1247multiframe mode (i.e., when the control buffer is in its own dedicated
1248frame). Be aware that many variables that drive Ediff are local to
1249Ediff Control Panel (@code{ediff-control-buffer}), which requires
1250special care in writing these hooks. Take a look at
1251@code{ediff-default-suspend-hook} and @code{ediff-default-quit-hook} to
1252see what's involved.
1253
1254@item ediff-startup-hook
1255@vindex ediff-startup-hook
1256This hook is run at the end of Ediff startup.
1257
1258@item ediff-select-hook
1259@vindex ediff-select-hook
1260This hook is run after Ediff selects the next difference region.
1261
1262@item ediff-unselect-hook
1263@vindex ediff-unselect-hook
1264This hook is run after Ediff unselects the current difference region.
1265
1266@item ediff-prepare-buffer-hook
1267@vindex ediff-prepare-buffer-hook
1268This hook is run for each Ediff buffer (A, B, C) right after the buffer
1269is arranged.
1270
1271@item ediff-display-help-hook
1272@vindex ediff-display-help-hook
1273Ediff runs this hook each time after setting up the help message. It
1274can be used to alter the help message for custom packages that run on
1275top of Ediff.
1276
1277@item ediff-mode-hook
1278@vindex ediff-mode-hook
1279This hook is run just after Ediff mode is set up in the control
1280buffer. This is done before any Ediff window is created. You can use it to
1281set local variables that alter the look of the display.
1282
1283@item ediff-registry-setup-hook
1284@vindex ediff-registry-setup-hook
1285Hooks run after setting up the registry for all active Ediff session.
1286@xref{Session Groups}, for details.
657f9cb8
MK
1287@item ediff-before-session-group-setup-hook
1288@vindex ediff-before-session-group-setup-hook
1289Hooks run before setting up a control panel for a group of related Ediff
1290sessions. Can be used, for example, to save window configuration to restore
1291later.
1292@item ediff-after-session-group-setup-hook
1293@vindex ediff-after-session-group-setup-hook
6bf7aab6
DL
1294Hooks run after setting up a control panel for a group of related Ediff
1295sessions. @xref{Session Groups}, for details.
1296@item ediff-quit-session-group-hook
1297@vindex ediff-quit-session-group-hook
1298Hooks run just before exiting a session group.
1299@item ediff-meta-buffer-keymap-setup-hook
1300@vindex ediff-meta-buffer-keymap-setup-hook
1301@vindex ediff-meta-buffer-map
1302Hooks run just after setting up the @code{ediff-meta-buffer-map} --- the
1303map that controls key bindings in the meta buffer. Since
1304@code{ediff-meta-buffer-map} is a local variable, you can set different
1305bindings for different kinds of meta buffers.
1306@end table
1307
1308@node Quick Help Customization, Window and Frame Configuration, Hooks, Customization
1309@section Quick Help Customization
1310@vindex ediff-use-long-help-message
1311@vindex ediff-control-buffer
1312@vindex ediff-startup-hook
1313@vindex ediff-help-message
1314
1315Ediff provides quick help using its control panel window. Since this window
1316takes a fair share of the screen real estate, you can toggle it off by
1317typing @kbd{?}. The control window will then shrink to just one line and a
1318mode line, displaying a short help message.
1319
1320The variable @code{ediff-use-long-help-message} tells Ediff whether
1321you use the short message or the long one. By default, it
1322is set to @code{nil}, meaning that the short message is used.
1323Set this to @code{t}, if you want Ediff to use the long
1324message by default. This property can always be changed interactively, by
1325typing @kbd{?} into Ediff Control Buffer.
1326
1327If you want to change the appearance of the help message on a per-buffer
1328basis, you must use @code{ediff-startup-hook} to change the value of
1329the variable @code{ediff-help-message}, which is local to
1330@code{ediff-control-buffer}.
1331
1332@node Window and Frame Configuration, Selective Browsing, Quick Help Customization, Customization
1333@section Window and Frame Configuration
1334
1335On a non-windowing display, Ediff sets things up in one frame, splitting
1336it between a small control window and the windows for buffers A, B, and C.
1337The split between these windows can be horizontal or
1338vertical, which can be changed interactively by typing @kbd{|} while the
1339cursor is in the control window.
1340
1341On a window display, Ediff sets up a dedicated frame for Ediff Control
1342Panel and then it chooses windows as follows: If one of the buffers
1343is invisible, it is displayed in the currently selected frame. If
1344a buffer is visible, it is displayed in the frame where it is visible.
1345If, according to the above criteria, the two buffers fall into the same
1346frame, then so be it---the frame will be shared by the two. The same
1347algorithm works when you type @kbd{C-l} (@code{ediff-recenter}), @kbd{p}
1348(@code{ediff-previous-difference}), @kbd{n}
1349(@code{ediff-next-difference}), etc.
1350
1351The above behavior also depends on whether the current frame is splittable,
1352dedicated, etc. Unfortunately, the margin of this book is too narrow to
1353present the details of this remarkable algorithm.
1354
1355The upshot of all this is that you can compare buffers in one frame or
1356in different frames. The former is done by default, while the latter can
1357be achieved by arranging buffers A, B (and C, if applicable) to be seen in
1358different frames. Ediff respects these arrangements, automatically
1359adapting itself to the multi-frame mode.
1360
1361Ediff uses the following variables to set up its control panel
1362(a.k.a.@: control buffer, a.k.a.@: quick help window):
1363
1364@table @code
1365@item ediff-control-frame-parameters
1366@vindex ediff-control-frame-parameters
1367You can change or augment this variable including the font, color,
1368etc. The X resource name of Ediff Control Panel frames is @samp{Ediff}. Under
1369X-windows, you can use this name to set up preferences in your
1370@file{~/.Xdefaults}, @file{~/.xrdb}, or whatever X resource file is in
1371use. Usually this is preferable to changing
1372@code{ediff-control-frame-parameters} directly. For instance, you can
1373specify in @file{~/.Xdefaults} the color of the control frame
1374using the resource @samp{Ediff*background}.
1375
1376In general, any X resource pertaining the control frame can be reached
1377via the prefix @code{Ediff*}.
1378
1379@item ediff-control-frame-position-function
1380@vindex ediff-control-frame-position-function
1381The preferred way of specifying the position of the control frame is by
1382setting the variable @code{ediff-control-frame-position-function} to an
1383appropriate function.
1384The default value of this variable is
1385@code{ediff-make-frame-position}. This function places the control frame in
1386the vicinity of the North-East corner of the frame displaying buffer A.
1387
1388@findex ediff-make-frame-position
1389@end table
1390
1391The following variables can be used to adjust the location produced by
1392@code{ediff-make-frame-position} and for related customization.
1393
1394@table @code
1395@item ediff-narrow-control-frame-leftward-shift
1396@vindex ediff-narrow-control-frame-leftward-shift
1397Specifies the number of characters for shifting
1398the control frame from the rightmost edge of frame A when the control
1399frame is displayed as a small window.
1400
1401@item ediff-wide-control-frame-rightward-shift
1402@vindex ediff-wide-control-frame-rightward-shift
1403Specifies the rightward shift of the control frame
1404from the left edge of frame A when the control frame shows the full
1405menu of options.
1406
1407@item ediff-control-frame-upward-shift
1408@vindex ediff-control-frame-upward-shift
1409Specifies the number of pixels for the upward shift
1410of the control frame.
1411
1412@item ediff-prefer-iconified-control-frame
1413@vindex ediff-prefer-iconified-control-frame
1414If this variable is @code{t}, the control frame becomes iconified
1415automatically when you toggle the quick help message off. This saves
1416valuable real estate on the screen. Toggling help back will deiconify
1417the control frame.
1418
1419To start Ediff with an iconified Control Panel, you should set this
1420variable to @code{t} and @code{ediff-prefer-long-help-message} to
1421@code{nil} (@pxref{Quick Help Customization}). This behavior is useful
3af0304a
MK
1422only if icons are allowed to accept keybord input (which depend on the
1423window manager and other factors).
6bf7aab6
DL
1424@end table
1425
1426@findex ediff-setup-windows
1427To make more creative changes in the way Ediff sets up windows, you can
1428rewrite the function @code{ediff-setup-windows}. However, we believe
1429that detaching Ediff Control Panel from the rest and making it into a
1430separate frame offers an important opportunity by allowing you to
1431iconify that frame. The icon will usually accept all of the Ediff
1432commands, but will free up valuable real estate on your screen (this may
1433depend on your window manager, though).
1434
1435The following variable controls how windows are set up:
1436
1437@table @code
1438@item ediff-window-setup-function
1439@vindex ediff-window-setup-function
1440The multiframe setup is done by the
1441@code{ediff-setup-windows-multiframe} function, which is the default on
1442windowing displays. The plain setup, one where all windows are always
1443in one frame, is done by @code{ediff-setup-windows-plain}, which is the
1444default on a non-windowing display (or in an xterm window). In fact,
1445under Emacs, you can switch freely between these two setups by executing
1446the command @code{ediff-toggle-multiframe} using the Minibuffer of the
1447Menubar.
1448@findex ediff-setup-windows-multiframe
1449@findex ediff-setup-windows-plain
1450@findex ediff-toggle-multiframe
1451
1452If you don't like any of these setups, write your own function. See the
1453documentation for @code{ediff-window-setup-function} for the basic
1454guidelines. However, writing window setups is not easy, so you should
1455first take a close look at @code{ediff-setup-windows-plain} and
1456@code{ediff-setup-windows-multiframe}.
1457@end table
1458
1459You can run multiple Ediff sessions at once, by invoking Ediff several
1460times without exiting previous Ediff sessions. Different sessions
1461may even operate on the same pair of files.
1462
1463Each session has its own Ediff Control Panel and all the regarding a
1464particular session is local to the associated control panel buffer. You
1465can switch between sessions by suspending one session and then switching
1466to another control panel. (Different control panel buffers are
1467distinguished by a numerical suffix, e.g., @samp{Ediff Control Panel<3>}.)
1468
1469@node Selective Browsing, Highlighting Difference Regions, Window and Frame Configuration, Customization
1470@section Selective Browsing
1471
1472Sometimes it is convenient to be able to step through only some difference
1473regions, those that match certain regular expressions, and to ignore all
1474others. On other occasions, you may want to ignore difference regions that
1475match some regular expressions, and to look only at the rest.
1476
1477The commands @kbd{#f} and @kbd{#h} let you do precisely this.
1478
1479Typing @kbd{#f} lets you specify regular expressions that match difference
1480regions you want to focus on.
1481We shall call these regular expressions @var{regexp-A}, @var{regexp-B} and
1482@var{regexp-C}.
1483Ediff will then start stepping through only those difference regions
1484where the region in buffer A matches @var{regexp-A} and/or the region in
1485buffer B matches @var{regexp-B}, etc. Whether `and' or `or' will be used
1486depends on how you respond to a question.
1487
1488When scanning difference regions for the aforesaid regular expressions,
1489Ediff narrows the buffers to those regions. This means that you can use
1490the expressions @kbd{\`} and @kbd{\'} to tie search to the beginning or end
1491of the difference regions.
1492
1493On the other hand, typing @kbd{#h} lets you specify (hide) uninteresting
1494regions. That is, if a difference region in buffer A matches
1495@var{regexp-A}, the corresponding region in buffer B matches @var{regexp-B}
1496and (if applicable) buffer C's region matches @var{regexp-C}, then the
1497region will be ignored by the commands @kbd{n}/@key{SPC}
1498(@code{ediff-next-difference}) and @kbd{p}/@key{DEL}
1499(@code{ediff-previous-difference}) commands.
1500
1501Typing @kbd{#f} and @kbd{#h} toggles selective browsing on and off.
1502
1503Note that selective browsing affects only @code{ediff-next-difference}
1504and @code{ediff-previous-difference}, i.e., the commands
1505@kbd{n}/@key{SPC} and @kbd{p}/@key{DEL}. @kbd{#f} and @kbd{#h} do not
1506change the position of the point in the buffers. And you can still jump
1507directly (using @kbd{j}) to any numbered
1508difference.
1509
1510Users can supply their own functions to specify how Ediff should do
1511selective browsing. To change the default Ediff function, add a function to
1512@code{ediff-load-hook} which will do the following assignments:
1513
1514@example
1515(setq ediff-hide-regexp-matches-function 'your-hide-function)
1516(setq ediff-focus-on-regexp-matches-function 'your-focus-function)
1517@end example
1518
1519@strong{Useful hint}: To specify a regexp that matches everything, don't
1520simply type @key{RET} in response to a prompt. Typing @key{RET} tells Ediff
1521to accept the default value, which may not be what you want. Instead, you
1522should enter something like @key{^} or @key{$}. These match every
1523line.
1524
1525You can use the status command, @kbd{i}, to find out whether
1526selective browsing is currently in effect.
1527
1528The regular expressions you specified are kept in the local variables
1529@code{ediff-regexp-focus-A}, @code{ediff-regexp-focus-B},
1530@code{ediff-regexp-focus-C}, @code{ediff-regexp-hide-A},
1531@code{ediff-regexp-hide-B}, @code{ediff-regexp-hide-C}. Their default value
1532is the empty string (i.e., nothing is hidden or focused on). To change the
1533default, set these variables in @file{.emacs} using @code{setq-default}.
1534
1535In addition to the ability to ignore regions that match regular
1536expressions, Ediff can be ordered to start skipping over certain
1537``uninteresting'' difference regions. This is controlled by the following
1538variable:
1539
1540@table @code
1541@item ediff-ignore-similar-regions
1542@vindex ediff-ignore-similar-regions
1543If @code{t}, causes Ediff to skip over "uninteresting" difference regions,
1544which are the regions where the variants differ only in the amount of the
1545white space and newlines. This feature can be toggled on/off interactively,
1546via the command @kbd{##}.
1547@end table
1548
1549@strong{Note:} In order for this feature to work, auto-refining of
1550difference regions must be on, since otherwise Ediff won't know if there
1551are fine differences between regions. On devices where Emacs can display
1552faces, auto-refining is a default, but it is not turned on by default on
1553text-only terminals. In that case, you must explicitly turn auto-refining
1554on (such as, by typing @kbd{@@}).
1555
1556@strong{Reassurance:} If many such uninteresting regions appear in a row,
1557Ediff may take a long time to skip over them because it has to compute fine
1558differences of all intermediate regions. This delay does not indicate any
1559problem.
1560
1561@node Highlighting Difference Regions, Narrowing, Selective Browsing, Customization
1562@section Highlighting Difference Regions
1563
1564The following variables control the way Ediff highlights difference
1565regions:
1566
1567@table @code
1568@item ediff-before-flag-bol
1569@itemx ediff-after-flag-eol
1570@itemx ediff-before-flag-mol
1571@itemx ediff-after-flag-mol
1572@vindex ediff-before-flag-bol
1573@vindex ediff-after-flag-eol
1574@vindex ediff-before-flag-mol
1575@vindex ediff-after-flag-mol
1576These variables hold strings that Ediff uses to mark the beginning and the
1577end of the differences found in files A, B, and C on devices where Emacs
1578cannot display faces. Ediff uses different flags to highlight regions that
1579begin/end at the beginning/end of a line or in a middle of a line.
1580
1581@item ediff-current-diff-face-A
1582@itemx ediff-current-diff-face-B
1583@itemx ediff-current-diff-face-C
1584@vindex ediff-current-diff-face-A
1585@vindex ediff-current-diff-face-B
1586@vindex ediff-current-diff-face-C
1587Ediff uses these faces to highlight current differences on devices where
1588Emacs can display faces. These and subsequently described faces can be set
1589either in @file{.emacs} or in @file{.Xdefaults}. The X resource for Ediff
1590is @samp{Ediff}, @emph{not} @samp{emacs}. Please refer to Emacs manual for
1591the information on how to set X resources.
1592@item ediff-fine-diff-face-A
1593@itemx ediff-fine-diff-face-B
1594@itemx ediff-fine-diff-face-C
1595@vindex ediff-fine-diff-face-A
1596@vindex ediff-fine-diff-face-B
1597@vindex ediff-fine-diff-face-C
1598Ediff uses these faces to show the fine differences between the current
1599differences regions in buffers A, B, and C, respectively.
1600
1601@item ediff-even-diff-face-A
1602@itemx ediff-even-diff-face-B
1603@itemx ediff-even-diff-face-C
1604@itemx ediff-odd-diff-face-A
1605@itemx ediff-odd-diff-face-B
1606@itemx ediff-odd-diff-face-C
1607@vindex ediff-even-diff-face-A
1608@vindex ediff-even-diff-face-B
1609@vindex ediff-even-diff-face-C
1610@vindex ediff-odd-diff-face-A
1611@vindex ediff-odd-diff-face-B
1612@vindex ediff-odd-diff-face-C
1613Non-current difference regions are displayed using these alternating
1614faces. The odd and the even faces are actually identical on monochrome
1615displays, because without colors options are limited.
1616So, Ediff uses italics to highlight non-current differences.
1617
1618@item ediff-force-faces
1619@vindex ediff-force-faces
1620Ediff generally can detect when Emacs is running on a device where it can
1621use highlighting with faces. However, if it fails to determine that faces
1622can be used, the user can set this variable to @code{t} to make sure that
1623Ediff uses faces to highlight differences.
1624
1625@item ediff-highlight-all-diffs
1626@vindex ediff-highlight-all-diffs
1627Indicates whether---on a windowind display---Ediff should highlight
1628differences using inserted strings (as on text-only terminals) or using
1629colors and highlighting. Normally, Ediff highlights all differences, but
1630the selected difference is highlighted more visibly. One can cycle through
1631various modes of highlighting by typing @kbd{h}. By default, Ediff starts
1632in the mode where all difference regions are highlighted. If you prefer to
1633start in the mode where unselected differences are not highlighted, you
1634should set @code{ediff-highlight-all-diffs} to @code{nil}. Type @kbd{h} to
1635restore highlighting for all differences.
1636
1637Ediff lets you switch between the two modes of highlighting. That is,
1638you can switch interactively from highlighting using faces to
1639highlighting using string flags, and back. Of course, switching has
1640effect only under a windowing system. On a text-only terminal or in an
1641xterm window, the only available option is highlighting with strings.
1642@end table
1643
1644@noindent
1645If you want to change the default settings for @code{ediff-force-faces} and
1646@code{ediff-highlight-all-diffs}, you must do it @strong{before} Ediff is
1647loaded.
1648
1649You can also change the defaults for the faces used to highlight the
1650difference regions. There are two ways to do this. The simplest and the
1651preferred way is to use the customization widget accessible from the
1652menubar. Ediff's customization group is located under "Tools", which in
1653turn is under "Programming". The faces that are used to highlight
1654difference regions are located in the "Highlighting" subgroup of the Ediff
1655customization group.
1656
1657The second, much more arcane, method to change default faces is to include
1658some Lisp code in @file{~/.emacs}. For instance,
1659
1660@example
1661(setq ediff-current-diff-face-A
1662 (copy-face 'bold-italic 'ediff-current-diff-face-A))
1663@end example
1664
1665@noindent
1666would use the pre-defined fase @code{bold-italic} to highlight the current
1667difference region in buffer A (this face is not a good choice, by the way).
1668
1669If you are unhappy with just @emph{some} of the aspects of the default
1670faces, you can modify them when Ediff is being loaded using
1671@code{ediff-load-hook}. For instance:
1672
1673@smallexample
1674(add-hook 'ediff-load-hook
bed44076
SM
1675 (lambda ()
1676 (set-face-foreground
1677 ediff-current-diff-face-B "blue")
1678 (set-face-background
1679 ediff-current-diff-face-B "red")
1680 (make-face-italic
1681 ediff-current-diff-face-B)))
6bf7aab6
DL
1682@end smallexample
1683
3af0304a
MK
1684@strong{Note:} To set Ediff's faces, use only @code{copy-face} or
1685@code{set/make-face-@dots{}} as shown above. Emacs' low-level
1686face-manipulation functions should be avoided.
6bf7aab6
DL
1687
1688@node Narrowing, Refinement of Difference Regions, Highlighting Difference Regions, Customization
1689@section Narrowing
1690
1691If buffers being compared are narrowed at the time of invocation of
1692Ediff, @code{ediff-buffers} will preserve the narrowing range. However,
1693if @code{ediff-files} is invoked on the files visited by these buffers,
1694that would widen the buffers, since this command is defined to compare the
1695entire files.
1696
1697Calling @code{ediff-regions-linewise} or @code{ediff-windows-linewise}, or
1698the corresponding @samp{-wordwise} commands, narrows the variants to the
1699particular regions being compared. The original accessible ranges are
1700restored when you quit Ediff. During the command, you can toggle this
1701narrowing on and off with the @kbd{%} command.
1702
1703These two variables control this narrowing behavior:
1704
1705@table @code
1706@item ediff-start-narrowed
1707@vindex ediff-start-narrowed
1708If @code{t}, Ediff narrows the display to the appropriate range when it
1709is invoked with an @samp{ediff-regions@dots{}} or
1710@samp{ediff-windows@dots{}} command. If @code{nil}, these commands do
1711not automatically narrow, but you can still toggle narrowing on and off
1712by typing @kbd{%}.
1713
1714@item ediff-quit-widened
1715@vindex ediff-quit-widened
1716Controls whether on quitting Ediff should restore the accessible range
1717that existed before the current invocation.
1718@end table
1719
1720@node Refinement of Difference Regions, Patch and Diff Programs, Narrowing, Customization
1721@section Refinement of Difference Regions
1722
1723Ediff has variables to control the way fine differences are
1724highlighted. This feature gives you control over the process of refinement.
1725Note that refinement ignores spaces, tabs, and newlines.
1726
1727@table @code
1728@item ediff-auto-refine
1729@vindex ediff-auto-refine
1730This variable controls whether fine differences within regions are
1731highlighted automatically (``auto-refining''). The default is yes
1732(@samp{on}).
1733
1734On a slow machine, automatic refinement may be painful. In that case,
1735you can turn auto-refining on or off interactively by typing
1736@kbd{@@}. You can also turn off display of refining that has
1737already been done.
1738
1739When auto-refining is off, fine differences are shown only for regions
1740for which these differences have been computed and saved before. If
1741auto-refining and display of refining are both turned off, fine
1742differences are not shown at all.
1743
1744Typing @kbd{*} computes and displays fine differences for the current
1745difference region, regardless of whether auto-refining is turned on.
1746
1747@item ediff-auto-refine-limit
1748@vindex ediff-auto-refine-limit
1749If auto-refining is on, this variable limits the size of the regions to
1750be auto-refined. This guards against the possible slowdown that may be
1751caused by extraordinary large difference regions.
1752
1753You can always refine the current region by typing @kbd{*}.
1754
1755@item ediff-forward-word-function
1756@vindex ediff-forward-word-function
1757This variable controls how fine differences are computed. The
1758value must be a Lisp function that determines how the current difference
1759region should be split into words.
1760
1761@vindex ediff-diff-program
1762@vindex ediff-forward-word-function
1763@findex ediff-forward-word
1764Fine differences are computed by first splitting the current difference
1765region into words and then passing the result to
1766@code{ediff-diff-program}. For the default forward word function (which is
1767@code{ediff-forward-word}), a word is a string consisting of letters,
1768@samp{-}, or @samp{_}; a string of punctuation symbols; a string of digits,
1769or a string consisting of symbols that are neither space, nor a letter.
1770
1771This default behavior is controlled by four variables: @code{ediff-word-1},
1772..., @code{ediff-word-4}. See the on-line documentation for these variables
1773and for the function @code{ediff-forward-word} for an explanation of how to
1774modify these variables.
1775@vindex ediff-word-1
1776@vindex ediff-word-2
1777@vindex ediff-word-3
1778@vindex ediff-word-4
1779@end table
1780
1781Sometimes, when a region has too many differences between the variants,
1782highlighting of fine differences is inconvenient, especially on
1783color displays. If that is the case, type @kbd{*} with a negative
1784prefix argument. This unhighlights fine differences for the current
1785region.
1786
1787To unhighlight fine differences in all difference regions, use the
1788command @kbd{@@}. Repeated typing of this key cycles through three
1789different states: auto-refining, no-auto-refining, and no-highlighting
1790of fine differences.
1791
1792@node Patch and Diff Programs, Merging and diff3, Refinement of Difference Regions, Customization
1793@section Patch and Diff Programs
1794
1795This section describes variables that specify the programs to be used for
1796applying patches and for computing the main difference regions (not the
1797fine difference regions):
1798
1799@table @code
1800@item ediff-diff-program
1801@itemx ediff-diff3-program
1802@vindex ediff-patch-program
1803@vindex ediff-diff-program
1804@vindex ediff-diff3-program
1805These variables specify the programs to use to produce differences
1806and do patching.
1807
1808@item ediff-diff-options
1809@itemx ediff-diff3-options
1810@vindex ediff-patch-options
1811@vindex ediff-diff-options
1812@vindex ediff-diff3-options
1813These variables specify the options to pass to the above utilities.
1814
1815In @code{ediff-diff-options}, it may be useful to specify options
1816such as @samp{-w} that ignore certain kinds of changes. However,
1817Ediff does not let you use the option @samp{-c}, as it doesn't recognize this
1818format yet.
1819
513bea45 1820@item ediff-coding-system-for-read
513bea45
MK
1821@vindex ediff-coding-system-for-read
1822This variable specifies the coding system to use when reading the output
1823that the programs @code{diff3} and @code{diff} send to Emacs. The default
1824is @code{raw-text}, and this should work fine in Unix and in most
1825cases under Windows NT/95/98/2000. There are @code{diff} programs
1826for which the default option doesn't work under Windows. In such cases,
1827@code{raw-text-dos} might work. If not, you will have to experiment with
1828other coding systems or use GNU diff.
1829
6bf7aab6
DL
1830@item ediff-patch-program
1831The program to use to apply patches. Since there are certain
1832incompatibilities between the different versions of the patch program, the
1833best way to stay out of trouble is to use a GNU-compatible version.
1834Otherwise, you may have to tune the values of the variables
1835@code{ediff-patch-options}, @code{ediff-backup-specs}, and
1836@code{ediff-backup-extension} as described below.
1837@item ediff-patch-options
1838Options to pass to @code{ediff-patch-program}.
1839
1840Note: the `-b' and `-z' options should be specified in
1841`ediff-backup-specs', not in @code{ediff-patch-options}.
1842
1843It is recommended to pass the `-f' option to the patch program, so it won't
1844ask questions. However, some implementations don't accept this option, in
1845which case the default value of this variable should be changed.
1846
1847@item ediff-backup-extension
1848Backup extension used by the patch program. Must be specified, even if
1849@code{ediff-backup-specs} is given.
1850@item ediff-backup-specs
1851Backup directives to pass to the patch program.
1852Ediff requires that the old version of the file (before applying the patch)
1853is saved in a file named @file{the-patch-file.extension}. Usually
1854`extension' is `.orig', but this can be changed by the user, and may also be
1855system-dependent. Therefore, Ediff needs to know the backup extension used
1856by the patch program.
1857
1858Some versions of the patch program let the user specify `-b backup-extension'.
1859Other versions only permit `-b', which (usually) assumes the extension `.orig'.
1860Yet others force you to use `-z<backup-extension>'.
1861
1862Note that both `ediff-backup-extension' and `ediff-backup-specs' must be
1863properly set. If your patch program takes the option `-b', but not
1864`-b extension', the variable `ediff-backup-extension' must still
1865be set so Ediff will know which extension to use.
1866
1867@item ediff-custom-diff-program
1868@itemx ediff-custom-diff-options
1869@vindex ediff-custom-diff-program
1870@vindex ediff-custom-diff-options
1871@findex ediff-save-buffer
1872Because Ediff limits the options you may want to pass to the @code{diff}
1873program, it partially makes up for this drawback by letting you save the
1874output from @code{diff} in your preferred format, which is specified via
1875the above two variables.
1876
1877The output generated by @code{ediff-custom-diff-program} (which doesn't
d63f8c1a 1878even have to be a standard-style @code{diff}!)@: is not used by Ediff. It is
6bf7aab6
DL
1879provided exclusively so that you can
1880refer to
1881it later, send it over email, etc. For instance, after reviewing the
1882differences, you may want to send context differences to a colleague.
1883Since Ediff ignores the @samp{-c} option in
1884@code{ediff-diff-program}, you would have to run @code{diff -c} separately
1885just to produce the list of differences. Fortunately,
1886@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options}
1887eliminate this nuisance by keeping a copy of a difference list in the
1888desired format in a buffer that can be displayed via the command @kbd{D}.
1889
1890@item ediff-patch-default-directory
1891@vindex ediff-patch-default-directory
1892Specifies the default directory to look for patches.
1893
1894@end table
1895
1896@noindent
1897@strong{Warning:} Ediff does not support the output format of VMS
1898@code{diff}. Instead, make sure you are using some implementation of POSIX
1899@code{diff}, such as @code{gnudiff}.
1900
1901@node Merging and diff3, Support for Version Control, Patch and Diff Programs, Customization
1902@section Merging and diff3
1903
1904Ediff supports three-way comparison via the functions @code{ediff-files3} and
1905@code{ediff-buffers3}. The interface is the same as for two-way comparison.
1906In three-way comparison and merging, Ediff reports if any two difference
1907regions are identical. For instance, if the current region in buffer A
1908is the same as the region in buffer C, then the mode line of buffer A will
1909display @samp{[=diff(C)]} and the mode line of buffer C will display
1910@samp{[=diff(A)]}.
1911
1912Merging is done according to the following algorithm.
1913
1914If a difference region in one of the buffers, say B, differs from the ancestor
1915file while the region in the other buffer, A, doesn't, then the merge buffer,
1916C, gets B's region. Similarly when buffer A's region differs from
1917the ancestor and B's doesn't, A's region is used.
1918
1919@vindex ediff-default-variant
1920If both regions in buffers A and B differ from the ancestor file, Ediff
1921chooses the region according to the value of the variable
1922@code{ediff-default-variant}. If its value is @code{default-A} then A's
1923region is chosen. If it is @code{default-B} then B's region is chosen.
1924If it is @code{combined} then the region in buffer C will look like
1925this:
1926
778a536a
MK
1927@comment Use @set to avoid triggering merge conflict detectors like CVS.
1928@set seven-left <<<<<<<
1929@set seven-right >>>>>>>
6bf7aab6 1930@example
778a536a 1931@value{seven-left} variant A
b844f697 1932the difference region from buffer A
778a536a 1933@value{seven-right} variant B
b844f697
MK
1934the difference region from buffer B
1935####### Ancestor
1936the difference region from the ancestor buffer, if available
1937======= end
6bf7aab6
DL
1938@end example
1939
b844f697
MK
1940The above is the default template for the combined region. The user can
1941customize this template using the variable
1942@code{ediff-combination-pattern}.
1943
6bf7aab6 1944@vindex ediff-combination-pattern
b844f697
MK
1945The variable @code{ediff-combination-pattern} specifies the template that
1946determines how the combined merged region looks like. The template is
1947represented as a list of the form @code{(STRING1 Symbol1 STRING2 Symbol2
1948STRING3 Symbol3 STRING4)}. The symbols here must be atoms of the form
1949@code{A}, @code{B}, or @code{Ancestor}. They determine the order in which
1950the corresponding difference regions (from buffers A, B, and the ancestor
1951buffer) are displayed in the merged region of buffer C. The strings in the
1952template determine the text that separates the aforesaid regions. The
1953default template is
1954
a010164d
EZ
1955@smallexample
1956("@value{seven-left} variant A" A "@value{seven-right} variant B" B
1957 "####### Ancestor" Ancestor "======= end")
1958@end smallexample
b844f697 1959
a010164d
EZ
1960@noindent
1961(this is one long line) and the corresponding combined region is shown
1962above. The order in which the regions are shown (and the separator
1963strings) can be changed by changing the above template. It is even
1964possible to add or delete region specifiers in this template (although
1965the only possibly useful such modification seems to be the deletion of
1966the ancestor).
6bf7aab6
DL
1967
1968In addition to the state of the difference, Ediff displays the state of the
1969merge for each region. If a difference came from buffer A by default
1970(because both regions A and B were different from the ancestor and
1971@code{ediff-default-variant} was set to @code{default-A}) then
1972@samp{[=diff(A) default-A]} is displayed in the mode line. If the
1973difference in buffer C came, say, from buffer B because the difference
1974region in that buffer differs from the ancestor, but the region in buffer A
1975does not (if merging with an ancestor) then @samp{[=diff(B) prefer-B]} is
1976displayed. The indicators default-A/B and prefer-A/B are inspired by
1977Emerge and have the same meaning.
1978
1979Another indicator of the state of merge is @samp{combined}. It appears
1980with any difference region in buffer C that was obtained by combining
1981the difference regions in buffers A and B as explained above.
1982
1983In addition to the state of merge and state of difference indicators, while
1984merging with an ancestor file or buffer, Ediff informs the user when the
1985current difference region in the (normally invisible) ancestor buffer is
1986empty via the @emph{AncestorEmpty} indicator. This helps determine if the
1987changes made to the original in variants A and B represent pure insertion
1988or deletion of text: if the mode line shows @emph{AncestorEmpty} and the
1989corresponding region in buffers A or B is not empty, this means that new
1990text was inserted. If this indicator is not present and the difference
1991regions in buffers A or B are non-empty, this means that text was
1992modified. Otherwise, the original text was deleted.
1993
1994Although the ancestor buffer is normally invisible, Ediff maintains
1995difference regions there and advances the current difference region
1996accordingly. All highlighting of difference regions is provided in the
1997ancestor buffer, except for the fine differences. Therefore, if desired, the
1998user can put the ancestor buffer in a separate frame and watch it
1999there. However, on a TTY, only one frame can be visible at any given time,
2000and Ediff doesn't support any single-frame window configuration where all
2001buffers, including the ancestor buffer, would be visible. However, the
2002ancestor buffer can be displayed by typing @kbd{/} to the control
2003window. (Type @kbd{C-l} to hide it again.)
2004
2005Note that the state-of-difference indicators @samp{=diff(A)} and
2006@samp{=diff(B)} above are not redundant, even in the presence of a
2007state-of-merge indicator. In fact, the two serve different purposes.
2008
2009For instance, if the mode line displays @samp{=diff(B) prefer(B)} and
2010you copy a difference region from buffer A to buffer C then
2011@samp{=diff(B)} will change to @samp{diff-A} and the mode line will
2012display @samp{=diff(A) prefer-B}. This indicates that the difference
2013region in buffer C is identical to that in buffer A, but originally
2014buffer C's region came from buffer B. This is useful to know because
2015you can recover the original difference region in buffer C by typing
2016@kbd{r}.
2017
2018
2019Ediff never changes the state-of-merge indicator, except in response to
2020the @kbd{!} command (see below), in which case the indicator is lost.
2021On the other hand, the state-of-difference indicator is changed
2022automatically by the copying/recovery commands, @kbd{a}, @kbd{b}, @kbd{r},
2023@kbd{+}.
2024
2025The @kbd{!} command loses the information about origins of the regions
2026in the merge buffer (default-A, prefer-B, or combined). This is because
2027recomputing differences in this case means running @code{diff3} on
2028buffers A, B, and the merge buffer, not on the ancestor buffer. (It
2029makes no sense to recompute differences using the ancestor file, since
2030in the merging mode Ediff assumes that you have not edited buffers A and
2031B, but that you may have edited buffer C, and these changes are to be
2032preserved.) Since some difference regions may disappear as a result of
2033editing buffer C and others may arise, there is generally no simple way
2034to tell where the various regions in the merge buffer came from.
2035
2036In three-way comparison, Ediff tries to disregard regions that consist
2037entirely of white space. For instance, if, say, the current region in
2038buffer A consists of the white space only (or if it is empty), Ediff will
2039not take it into account for the purpose of computing fine differences. The
2040result is that Ediff can provide a better visual information regarding the
2041actual fine differences in the non-white regions in buffers B and
2042C. Moreover, if the regions in buffers B and C differ in the white space
2043only, then a message to this effect will be displayed.
2044
2045@vindex ediff-merge-window-share
2046In the merge mode, the share of the split between window C (the window
2047displaying the merge-buffer) and the windows displaying buffers A and B
2048is controlled by the variable @code{ediff-merge-window-share}. Its
2049default value is 0.5. To make the merge-buffer window smaller, reduce
2050this amount.
2051
2052We don't recommend increasing the size of the merge-window to more than
2053half the frame (i.e., to increase the value of
2054@code{ediff-merge-window-share}) to more than 0.5, since it would be
2055hard to see the contents of buffers A and B.
2056
2057You can temporarily shrink the merge window to just one line by
2058typing @kbd{s}. This change is temporary, until Ediff finds a reason to
2059redraw the screen. Typing @kbd{s} again restores the original window size.
2060
2061With a positive prefix argument, the @kbd{s} command will make the merge
2062window slightly taller. This change is persistent. With `@kbd{-}' or
2063with a negative prefix argument, the command @kbd{s} makes the merge
2064window slightly shorter. This change also persistent.
2065
2066@vindex ediff-show-clashes-only
2067Ediff lets you automatically ignore the regions where only one of the
2068buffers A and B disagrees with the ancestor. To do this, set the
2069variable @code{ediff-show-clashes-only} to non-@code{nil}.
2070
3af0304a 2071You can toggle this feature interactively by typing @kbd{$$}.
6bf7aab6
DL
2072
2073Note that this variable affects only the show next/previous difference
2074commands. You can still jump directly to any difference region directly
2075using the command @kbd{j} (with a prefix argument specifying the difference
2076number).
2077
2078@vindex ediff-autostore-merges
2079@vindex ediff-quit-merge-hook
2080@findex ediff-maybe-save-and-delete-merge
2081The variable @code{ediff-autostore-merges} controls what happens to the
2082merge buffer when Ediff quits. If the value is @code{nil}, nothing is done
2083to the merge buffer---it will be the user's responsibility to save it.
2084If the value is @code{t}, the user will be asked where to save the buffer
2085and whether to delete it afterwards. It the value is neither @code{nil} nor
2086@code{t}, the merge buffer is saved @emph{only} if this merge session was
2087invoked from a group of related Ediff session, such as those that result
2088from @code{ediff-merge-directories},
2089@code{ediff-merge-directory-revisions}, etc.
2090@xref{Session Groups}. This behavior is implemented in the function
2091@code{ediff-maybe-save-and-delete-merge}, which is a hook in
2092@code{ediff-quit-merge-hook}. The user can supply a different hook, if
2093necessary.
2094
2095The variable @code{ediff-autostore-merges} is buffer-local, so it can be
2096set in a per-buffer manner. Therefore, use @code{setq-default} to globally
2097change this variable.
2098
6de3983f
MK
2099@vindex ediff-merge-filename-prefix
2100When merge buffers are saved automatically as directed by
2101@code{ediff-autostore-merges}, Ediff attaches a prefix to each file, as
2102specified by the variable @code{ediff-merge-filename-prefix}. The default
2103is @code{merge_}, but this can be changed by the user.
2104
6bf7aab6
DL
2105@node Support for Version Control, Customizing the Mode Line, Merging and diff3, Customization
2106@section Support for Version Control
2107
2108
2109Ediff supports version control and lets you compare versions of files
2110visited by Emacs buffers via the function @code{ediff-revision}. This
2111feature is controlled by the following variables:
2112
2113@table @code
2114@item ediff-version-control-package
2115@vindex ediff-version-control-package
2116A symbol. The default is @samp{vc}.
2117
2118If you are like most Emacs users, Ediff will use VC as the version control
2119package. This is the standard Emacs interface to RCS, CVS, and SCCS.
2120
2121However, if your needs are better served by other interfaces, you will
2122have to tell Ediff which version control package you are using, e.g.,
2123@example
2124(setq ediff-version-control-package 'rcs)
2125@end example
2126
2127Apart from the standard @file{vc.el}, Ediff supports three other interfaces
657f9cb8
MK
2128to version control: @file{rcs.el}, @file{pcl-cvs.el} (recently renamed
2129pcvs.el), and @file{generic-sc.el}. The package @file{rcs.el} is written
2130by Sebastian Kremer <sk@@thp.Uni-Koeln.DE> and is available as
6bf7aab6
DL
2131@example
2132@file{ftp.cs.buffalo.edu:pub/Emacs/rcs.tar.Z}
2133@file{ftp.uni-koeln.de:/pub/gnu/emacs/rcs.tar.Z}
2134@end example
2135@pindex @file{vc.el}
2136@pindex @file{rcs.el}
2137@pindex @file{pcl-cvs.el}
2138@pindex @file{generic-sc.el}
2139@end table
2140
2141Ediff's interface to the above packages allows the user to compare the
2142versions of the current buffer or to merge them (with or without an
2143ancestor-version). These operations can also be performed on directories
2144containing files under version control.
2145
2146In case of @file{pcl-cvs.el}, Ediff can also be invoked via the function
2147@code{run-ediff-from-cvs-buffer}---see the documentation string for this
2148function.
2149
2150@node Customizing the Mode Line, Miscellaneous, Support for Version Control, Customization
2151@section Customizing the Mode Line
2152
2153When Ediff is running, the mode line of @samp{Ediff Control Panel}
2154buffer shows the current difference number and the total number of
2155difference regions in the two files.
2156
2157The mode line of the buffers being compared displays the type of the
2158buffer (@samp{A:}, @samp{B:}, or @samp{C:}) and (usually) the file name.
2159Ediff tries to be intelligent in choosing the mode line buffer
2160identification. In particular, it works well with the
2161@file{uniquify.el} and @file{mode-line.el} packages (which improve on
2162the default way in which Emacs displays buffer identification). If you
2163don't like the way Ediff changes the mode line, you can use
2164@code{ediff-prepare-buffer-hook} to modify the mode line.
2165@vindex ediff-prepare-buffer-hook
2166@pindex @file{uniquify.el}
2167@pindex @file{mode-line.el}
2168
2169@node Miscellaneous, Notes on Heavy-duty Customization, Customizing the Mode Line, Customization
2170@section Miscellaneous
2171
2172Here are a few other variables for customizing Ediff:
2173
2174@table @code
2175@item ediff-split-window-function
2176@vindex ediff-split-window-function
2177Controls the way you want the window be split between file-A and file-B
2178(and file-C, if applicable). It defaults to the vertical split
2179(@code{split-window-vertically}, but you can set it to
2180@code{split-window-horizontally}, if you so wish.
2181Ediff also lets you switch from vertical to horizontal split and back
2182interactively.
2183
2184Note that if Ediff detects that all the buffers it compares are displayed in
2185separate frames, it assumes that the user wants them to be so displayed
2186and stops splitting windows. Instead, it arranges for each buffer to
2187be displayed in a separate frame. You can switch to the one-frame mode
2188by hiding one of the buffers A/B/C.
2189
2190You can also swap the windows where buffers are displayed by typing
2191@kbd{~}.
2192
2193@item ediff-merge-split-window-function
2194@vindex ediff-merge-split-window-function
2195Controls how windows are
2196split between buffers A and B in the merge mode.
2197This variable is like @code{ediff-split-window-function}, but it defaults
2198to @code{split-window-horizontally} instead of
2199@code{split-window-vertically}.
2200
2201@item ediff-make-wide-display-function
2202@vindex ediff-make-wide-display-function
2203The value is a function to be called to widen the frame for displaying
2204the Ediff buffers. See the on-line documentation for
2205@code{ediff-make-wide-display-function} for details. It is also
2206recommended to look into the source of the default function
2207@code{ediff-make-wide-display}.
2208
2209You can toggle wide/regular display by typing @kbd{m}. In the wide
2210display mode, buffers A, B (and C, when applicable) are displayed in a
2211single frame that is as wide as the entire workstation screen. This is
2212useful when files are compared side-by-side. By default, the display is
2213widened without changing its height.
2214
2215@item ediff-use-last-dir
2216@vindex ediff-use-last-dir
2217Controls the way Ediff presents the
2218default directory when it prompts the user for files to compare. If
2219@code{nil},
2220Ediff uses the default directory of the current buffer when it
2221prompts the user for file names. Otherwise, it will use the
2222directories it had previously used for files A, B, or C, respectively.
2223
2224@item ediff-no-emacs-help-in-control-buffer
2225@vindex ediff-no-emacs-help-in-control-buffer
2226If @code{t}, makes @kbd{C-h}
2227behave like the @key{DEL} key, i.e., it will move you back to the previous
2228difference rather than invoking help. This is useful when, in an xterm
2229window or a text-only terminal, the Backspace key is bound to @kbd{C-h} and is
2230positioned more conveniently than the @key{DEL} key.
2231
2232@item ediff-toggle-read-only-function
2233@vindex ediff-toggle-read-only-function
2234This variable's value is a function that Ediff uses to toggle
2235the read-only property in its buffers.
2236
2237The default function that Ediff uses simply toggles the read-only property,
2238unless the file is under version control. For a checked-in file under
2239version control, Ediff first tries to check the file out.
2240
2241@item ediff-make-buffers-readonly-at-startup nil
2242@vindex ediff-make-buffers-readonly-at-startup
2243If t, all variant buffers are made read-only at Ediff startup.
2244
2245@item ediff-keep-variants
2246@vindex @code{ediff-keep-variants}
2247The default is @code{t}, meaning that the buffers being compared or merged will
2248be preserved when Ediff quits. Setting this to @code{nil} causes Ediff to
2249offer the user a chance to delete these buffers (if they are not modified).
2250Supplying a prefix argument to the quit command (@code{q}) temporarily
2251reverses the meaning of this variable. This is convenient when the user
2252prefers one of the behaviors most of the time, but occasionally needs the
2253other behavior.
2254
2255However, Ediff temporarily resets this variable to @code{t} if it is
2256invoked via one of the "buffer" jobs, such as @code{ediff-buffers}.
2257This is because it is all too easy to loose day's work otherwise.
2258Besides, in a "buffer" job, the variant buffers have already been loaded
2259prior to starting Ediff, so Ediff just preserves status quo here.
2260
2261Using @code{ediff-cleanup-hook}, one can make Ediff delete the variants
2262unconditionally (e.g., by making @code{ediff-janitor} into one of these hooks).
2263@item ediff-grab-mouse
2264@vindex @code{ediff-grab-mouse}
2265Default is @code{t}. Normally, Ediff grabs mouse and puts it in its
2266control frame. This is useful since the user can be sure that when he
2267needs to type an Ediff command the focus will be in an appropriate Ediff's
2268frame. However, some users prefer to move the mouse by themselves. The
2269above variable, if set to @code{maybe}, will prevent Ediff from grabbing
2270the mouse in many situations, usually after commands that may take more
2271time than usual. In other situation, Ediff will continue grabbing the mouse
2272and putting it where it believes is appropriate. If the value is
2273@code{nil}, then mouse is entirely user's responsibility.
2274Try different settings and see which one is for you.
2275@end table
2276
2277
2278@node Notes on Heavy-duty Customization, , Miscellaneous, Customization
2279@section Notes on Heavy-duty Customization
2280
2281Some users need to customize Ediff in rather sophisticated ways, which
2282requires different defaults for different kinds of files (e.g., SGML,
2283etc.). Ediff supports this kind of customization in several ways. First,
2284most customization variables are buffer-local. Those that aren't are
2285usually accessible from within Ediff Control Panel, so one can make them
2286local to the panel by calling make-local-variable from within
2287@code{ediff-startup-hook}.
2288
2289Second, the function @code{ediff-setup} accepts an optional sixth
2290argument which has the form @code{((@var{var-name-1} .@: @var{val-1})
2291(@var{var-name-2} .@: @var{val-2}) @dots{})}. The function
2292@code{ediff-setup} sets the variables in the list to the respective
2293values, locally in the Ediff control buffer. This is an easy way to
2294throw in custom variables (which usually should be buffer-local) that
2295can then be tested in various hooks.
2296
2297Make sure the variable @code{ediff-job-name} and @code{ediff-word-mode} are set
2298properly in this case, as some things in Ediff depend on this.
2299
2300Finally, if you want custom-tailored help messages, you can set the
2301variables @code{ediff-brief-help-message-function} and
2302@code{ediff-long-help-message-function}
2303to functions that return help strings.
2304@vindex ediff-startup-hook
2305@findex ediff-setup
2306@vindex ediff-job-name
2307@vindex ediff-word-mode
2308@vindex ediff-brief-help-message-function
2309@vindex ediff-long-help-message-function
2310
2311When customizing Ediff, some other variables are useful, although they are
2312not user-definable. They are local to the Ediff control buffer, so this
2313buffer must be current when you access these variables. The control buffer
2314is accessible via the variable @code{ediff-control-buffer}, which is also
2315local to that buffer. It is usually used for checking if the current buffer
2316is also the control buffer.
2317
2318Other variables of interest are:
2319@table @code
2320@item ediff-buffer-A
2321The first of the data buffers being compared.
2322
2323@item ediff-buffer-B
2324The second of the data buffers being compared.
2325
2326@item ediff-buffer-C
2327In three-way comparisons, this is the third buffer being compared.
2328In merging, this is the merge buffer.
2329In two-way comparison, this variable is nil.
2330
2331@item ediff-window-A
2332The window displaying buffer A. If buffer A is not visible, this variable
2333is nil or it may be a dead window.
2334
2335@item ediff-window-B
2336The window displaying buffer B.
2337
2338@item ediff-window-C
2339The window displaying buffer C, if any.
2340
2341@item ediff-control-frame
2342A dedicated frame displaying the control buffer, if it exists.
2343It is non-nil only if Ediff uses the multiframe display, i.e., when the
2344control buffer is in its own frame.
2345@end table
2346
2347@node Credits, Index, Customization, Top
2348@chapter Credits
2349
2350Ediff was written by Michael Kifer <kifer@@cs.sunysb.edu>. It was inspired
2351by emerge.el written by Dale R.@: Worley <drw@@math.mit.edu>. An idea due to
2352Boris Goldowsky <boris@@cs.rochester.edu> made it possible to highlight
2353fine differences in Ediff buffers. Alastair Burt <burt@@dfki.uni-kl.de>
2354ported Ediff to XEmacs, Eric Freudenthal <freudent@@jan.ultra.nyu.edu>
2355made it work with VC, Marc Paquette <marcpa@@cam.org> wrote the
778a536a 2356toolbar support package for Ediff, and Hrvoje Niksic <hniksic@@xemacs.org>
6bf7aab6
DL
2357adapted it to the Emacs customization package.
2358
2359Many people provided help with bug reports, patches, and advice.
2360Without them, Ediff would not be nearly as useful as it is today.
2361Here is a full list of contributors (I hope I didn't miss anyone):
2362
2363@example
3af0304a 2364Adrian Aichner (aichner@@ecf.teradyne.com),
6bf7aab6
DL
2365Steve Baur (steve@@xemacs.org),
2366Neal Becker (neal@@ctd.comsat.com),
2367E.@: Jay Berkenbilt (ejb@@ql.org),
2368Alastair Burt (burt@@dfki.uni-kl.de),
2369Paul Bibilo (peb@@delcam.co.uk),
2370Kevin Broadey (KevinB@@bartley.demon.co.uk),
2371Harald Boegeholz (hwb@@machnix.mathematik.uni-stuttgart.de),
2372Bradley A.@: Bosch (brad@@lachman.com),
2373Michael D.@: Carney (carney@@ltx-tr.com),
2374Jin S.@: Choi (jin@@atype.com),
2375Scott Cummings (cummings@@adc.com),
2376Albert Dvornik (bert@@mit.edu),
2377Eric Eide (eeide@@asylum.cs.utah.edu),
2378Paul Eggert (eggert@@twinsun.com),
3af0304a 2379Urban Engberg (ue@@cci.dk),
6bf7aab6
DL
2380Kevin Esler (esler@@ch.hp.com),
2381Robert Estes (estes@@ece.ucdavis.edu),
2382Jay Finger (jayf@@microsoft.com),
2383Xavier Fornari (xavier@@europe.cma.fr),
2384Eric Freudenthal (freudent@@jan.ultra.nyu.edu),
2385Job Ganzevoort (Job.Ganzevoort@@cwi.nl),
2386Boris Goldowsky (boris@@cs.rochester.edu),
2387Allan Gottlieb (gottlieb@@allan.ultra.nyu.edu),
3af0304a 2388Aaron Gross (aaron@@bfr.co.il),
6bf7aab6
DL
2389Thorbjoern Hansen (thorbjoern.hansen@@mchp.siemens.de),
2390Xiaoli Huang (hxl@@epic.com),
3af0304a 2391Andreas Jaeger (aj@@suse.de),
6bf7aab6
DL
2392Lars Magne Ingebrigtsen (larsi@@ifi.uio.no),
2393Larry Gouge (larry@@itginc.com),
2394Karl Heuer (kwzh@@gnu.org),
2395(irvine@@lks.csi.com),
2396(jaffe@@chipmunk.cita.utoronto.ca),
2397David Karr (dkarr@@nmo.gtegsc.com),
2398Norbert Kiesel (norbert@@i3.informatik.rwth-aachen.de),
3af0304a 2399Sam Steingold (sds@@goems.com),
6bf7aab6
DL
2400Leigh L Klotz (klotz@@adoc.xerox.com),
2401Fritz Knabe (Fritz.Knabe@@ecrc.de),
2402Heinz Knutzen (hk@@informatik.uni-kiel.d400.de),
2403Andrew Koenig (ark@@research.att.com),
4960e757 2404Hannu Koivisto (azure@@iki.fi),
6bf7aab6
DL
2405Ken Laprade (laprade@@dw3f.ess.harris.com),
2406Will C Lauer (wcl@@cadre.com),
2407Richard Levitte (levitte@@e.kth.se),
2408Mike Long (mike.long@@analog.com),
2409Martin Maechler (maechler@@stat.math.ethz.ch),
2410Simon Marshall (simon@@gnu.org),
4960e757 2411Paul C. Meuse (pmeuse@@delcomsys.com),
6bf7aab6 2412Richard Mlynarik (mly@@adoc.xerox.com),
657f9cb8 2413Stefan Monnier (monnier@@cs.yale.edu),
6bf7aab6
DL
2414Chris Murphy (murphycm@@sun.aston.ac.uk),
2415Erik Naggum (erik@@naggum.no),
2416Eyvind Ness (Eyvind.Ness@@hrp.no),
2417Ray Nickson (nickson@@cs.uq.oz.au),
2418David Petchey (petchey_david@@jpmorgan.com),
2419Benjamin Pierce (benjamin.pierce@@cl.cam.ac.uk),
3af0304a 2420Francois Pinard (pinard@@iro.umontreal.ca),
6bf7aab6
DL
2421Tibor Polgar (tlp00@@spg.amdahl.com),
2422David Prince (dave0d@@fegs.co.uk),
2423Paul Raines (raines@@slac.stanford.edu),
2424Bill Richter (richter@@math.nwu.edu),
2425C.S.@: Roberson (roberson@@aur.alcatel.com),
2426Kevin Rodgers (kevin.rodgers@@ihs.com),
2427Sandy Rutherford (sandy@@ibm550.sissa.it),
2428Heribert Schuetz (schuetz@@ecrc.de),
2429Andy Scott (ascott@@pcocd2.intel.com),
2430Axel Seibert (axel@@tumbolia.ppp.informatik.uni-muenchen.de),
2550055a
MK
2431Vin Shelton (acs@@xemacs.org),
2432Scott O. Sherman (Scott.Sherman@@mci.com),
6bf7aab6
DL
2433Richard Stallman (rms@@gnu.org),
2434Richard Stanton (stanton@@haas.berkeley.edu),
2435Ake Stenhoff (etxaksf@@aom.ericsson.se),
2436Stig (stig@@hackvan.com),
2437Peter Stout (Peter_Stout@@cs.cmu.edu),
2438Chuck Thompson (cthomp@@cs.uiuc.edu),
2439Ray Tomlinson (tomlinso@@bbn.com),
2440Raymond Toy (toy@@rtp.ericsson.se),
2441Jan Vroonhof (vroonhof@@math.ethz.ch),
2550055a 2442Colin Walters (walters@@cis.ohio-state.edu),
6bf7aab6
DL
2443Philippe Waroquiers (philippe.waroquiers@@eurocontrol.be),
2444Klaus Weber (gizmo@@zork.north.de),
778a536a 2445Ben Wing (ben@@xemacs.org),
657f9cb8 2446Tom Wurgler (twurgler@@goodyear.com),
2550055a 2447Steve Youngs (youngs@@xemacs.org),
6bf7aab6
DL
2448Ilya Zakharevich (ilya@@math.ohio-state.edu),
2449Eli Zaretskii (eliz@@is.elta.co.il)
2450@end example
2451
2452@node Index, , Credits, Top
2453@unnumbered Index
2454@printindex cp
2455
56f7c94a 2456@setchapternewpage odd
6bf7aab6
DL
2457@contents
2458@bye