\input texinfo                  @c -*-texinfo-*-
@c documentation for Ediff
@c Written by Michael Kifer

@comment %**start of header (This is for running Texinfo on a region.)

@comment Using ediff.info instead of ediff in setfilename breaks DOS.
@setfilename ../info/ediff.info
@comment @setfilename ediff.info

@settitle Ediff User's Manual
@synindex vr cp
@synindex fn cp
@synindex pg cp
@iftex
@finalout
@end iftex
@c      @smallbook
@comment %**end of header (This is for running Texinfo on a region.)

@ifinfo
This file documents Ediff, a comprehensive visual interface to Unix diff
and patch utilities.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission notice
identical to this one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
@end ifinfo

@iftex
@titlepage
@title Ediff User's Manual
@sp 4
@subtitle Ediff version 2.61
@sp 1
@subtitle June 1996
@sp 5
@author Michael Kifer
@page

@vskip 0pt plus 1filll
@noindent
Copyright @copyright{} 1995, 1996 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
@end titlepage
@page
@end iftex

@node Top, Introduction, (dir), (dir)

@menu
* Introduction::                About Ediff.
* Major Entry Points::          How to use Ediff.
* Commands::                    Ediff commands.
* Registry of Ediff Sessions::  Keeping track of multiple Ediff sessions.
* Session Groups::              Comparing and merging directories.
* Remote and Compressed Files::  You may want to know about this.
* Customization::               How to make Ediff work the way YOU want.
* Credits::                     Thanks to those who helped.
* Index::                       
@end menu

@node Introduction, Major Entry Points, Top, Top
@chapter Introduction

@cindex Comparing files and buffers
@cindex Merging files and buffers
@cindex Patching files and buffers
@cindex Finding differences

Ediff provides a convenient way for simultaneous browsing through
the differences between a pair (or a triple) of files or buffers.  The
files being compared, file-A, file-B, and file-C (if applicable) are
shown in separate windows (side by side, one above the another, or in
separate frames), and the differences are highlighted as you step
through them.  You can also copy difference regions from one buffer to
another (and recover old differences if you change your mind).

Another powerful feature is the ability to merge a pair of files into a
third buffer. Merging with an ancestor file is also supported.
Furthermore, Ediff is equipped with directory-level capabilities that
allow the user to conveniently launch browsing or merging sessions on
groups of files in two (or three) different directories.

In addition, Ediff can apply a patch to a file and then let you step though
both files, the patched and the original one, simultaneously,
difference-by-difference.  You can even apply a patch right out of a mail
buffer, i.e., patches received by mail don't even have to be saved.  Since
Ediff lets you copy differences between buffers, you can, in effect, apply
patches selectively (i.e., you can copy a difference region from
@file{file_orig} to @file{file}, thereby undoing any particular patch that
you don't like).

Ediff even understands multi-file patches and can apply them interactively!
(Ediff can recognize multi-file patches only if they are in the context or
GNU unified format. All other patches are treated as 1-file patches. Ediff
is [hopefully] using the same algorithm as patch to determine which
files need to be patched.)

Ediff is aware of version control, which lets you compare
files with their older versions. Ediff also works with remote and
compressed files, automatically ftp'ing them over and uncompressing them.
@xref{Remote and Compressed Files}, for details.

This package builds upon ideas borrowed from Emerge and
several Ediff's functions are adaptations from Emerge.
Although Ediff subsumes Emerge,
much of the functionality of Ediff is influenced by Emerge.
The architecture and the interface are, of course, drastically different.

@node Major Entry Points, Commands, Introduction, Top
@chapter Major Entry Points

Ediff can be invoked interactively using the following functions, which can
be run either from the minibuffer or from the menu bar. In the menu bar,
all Ediff's entry points belong to three submenus of the Tools menu:
Compare, Merge, and Apply Patch.

@table @code
@item ediff-files
@itemx ediff
@findex ediff-files
@findex ediff
Compare two files.

@item ediff-buffers
@findex ediff-buffers
Compare two buffers.

@item ediff-files3
@itemx ediff3
@findex ediff-files3
@findex ediff3
Compare three files.

@item ediff-buffers3
@findex ediff-buffers3
Compare three buffers.

@item edirs
@itemx ediff-directories
@findex edirs
@findex ediff-directories
 Compare files common to two directories.
@item edirs3
@itemx ediff-directories3
@findex edirs3
@findex ediff-directories3
 Compare files common to three directories.
@item edir-revisions
@itemx ediff-directory-revisions
@findex ediff-directory-revisions
@findex edir-revisions
 Compare versions of files in a given directory. Ediff selects only the
files that are under version control.
@item edir-merge-revisions
@itemx ediff-merge-directory-revisions
@findex edir-merge-revisions
@findex ediff-merge-directory-revisions
 Merge versions of files in a given directory. Ediff selects only the
files that are under version control.
@item edir-merge-revisions-with-ancestor
@itemx ediff-merge-directory-revisions-with-ancestor
@findex edir-merge-revisions-with-ancestor
@findex ediff-merge-directory-revisions-with-ancestor
 Merge versions of files in a given directory using other versions as
ancestors. Ediff selects only the files that are under version control.

@item ediff-windows-wordwise
@findex ediff-windows-wordwise
Compare windows word-by-word.

@item ediff-windows-linewise
@findex ediff-windows-linewise
Compare windows line-by-line.

@item ediff-regions-wordwise
@findex ediff-regions-wordwise
Compare regions word-by-word.

@item ediff-regions-linewise
@findex ediff-regions-linewise
Compare regions line-by-line.

@item ediff-revision
@findex ediff-revision
 Compare versions of the current buffer, if the buffer is visiting
 a file under version control. 

@item ediff-patch-file
@itemx epatch
@findex ediff-patch-file
@findex epatch
 Patch a file, then compare.
@item ediff-patch-buffer
@itemx epatch-buffer
@findex ediff-patch-buffer
Patch a buffer, then compare.

@item ediff-merge-files
@itemx ediff-merge
@findex ediff-merge-files
@findex ediff-merge
Merge two files.

@item ediff-merge-files-with-ancestor
@itemx ediff-merge-with-ancestor
@findex ediff-merge-files-with-ancestor
@findex ediff-merge-with-ancestor
Like @code{ediff-merge}, but with a third ancestor file.

@item ediff-merge-buffers
@findex ediff-merge-buffers
Merge two buffers.

@item ediff-merge-buffers-with-ancestor
@findex ediff-merge-buffers-with-ancestor
Same but with ancestor.


@item edirs-merge
@itemx ediff-merge-directories
@findex edirs-merge
@findex ediff-merge-directories
 Merge files common to two directories.
@item edirs-merge-with-ancestor
@itemx ediff-merge-directories-with-ancestor
@findex edirs-merge-with-ancestor
@findex ediff-merge-directories-with-ancestor
 Same but using files in a third directory as ancestors.

@item ediff-merge-revisions
@findex ediff-merge-revisions
Merge two versions of the file visited by the current buffer.

@item ediff-merge-revisions-with-ancestor
@findex ediff-merge-revisions-with-ancestor
Same but with ancestor.
@end table

@noindent
If you want Ediff to be loaded from the very beginning of your Emacs
session, you should put this line in your @file{~/.emacs} file:

@example
(require 'ediff)
@end example

@noindent
Otherwise, Ediff will be loaded automatically when you use one of the
above functions, either directly or through the menus.

When the above functions are invoked, they prompt the user for the
information they need---typically the files or buffers to compare or
patch. Ediff tries to be smart about these prompts. For instance, in
comparing/merging files, it will offer the visible buffers as defaults.  In
prompting for files, if the user enters a directory, the previously input
file name will be appended to that directory. In addition, if the variable
@code{ediff-use-last-dir} is not @code{nil}, Ediff will offer 
previously entered directories as defaults (which will be maintained
separately for each type of file, A, B, or C).
@vindex @code{ediff-use-last-dir}

All the above functions use the POSIX @code{diff} program to find
differences between two files.  They process the @code{diff} output and
display it in a convenient form.  At present, Ediff understands only the
plain output from diff.  Options such as @samp{-c} are not supported,
nor is the format produced by incompatible file comparison programs such
as the VMS version of @code{diff}.

The functions @code{ediff-files}, @code{ediff-buffers},
@code{ediff-files3}, @code{ediff-buffers3} first display the coarse,
line-based difference regions, as reported by the @file{diff} program.
Since diff may report fairly large chunks of text as being different,
even though the difference may be localized to just a few words or even
to the white space or line breaks, Ediff further @emph{refines} the
regions to indicate which exact words differ.  If the only difference is
in the white space and line breaks, Ediff says so.

On a color display, fine differences are highlighted with color; on a
monochrome display, they are underlined.  @xref{Highlighting Difference
Regions}, for information on how to customize this.

The functions @code{ediff-windows-wordwise},
@code{ediff-windows-linewise}, @code{ediff-regions-wordwise} and
@code{ediff-regions-linewise} do comparison on parts of existing Emacs
buffers.  Since @code{ediff-windows-wordwise} and
@code{ediff-regions-wordwise} are intended for relatively small segments
of buffers, comparison is done on the basis of words rather than lines.
No refinement is necessary in this case.  These commands are recommended
only for relatively small regions (perhaps, up to 100 lines), because
these functions have a relatively slow startup.

To compare large regions, use @code{ediff-regions-linewise}.  This
command displays differences much like @code{ediff-files} and
@code{ediff-buffers}.

The functions @code{ediff-patch-file} and @code{ediff-patch-buffer} apply a
patch to a file or a buffer and then run Ediff on these buffers, displaying
the difference regions. 

The entry points @code{ediff-directories}, @code{ediff-merge-directories},
etc., provide a convenient interface for comparing and merging files in
different directories. The user is presented with Dired-like interface from
which one can run a group of related Ediff sessions.

For files under version control, @code{ediff-revisions} lets you compare
the file visited by the current buffer to one of its checked-in versions.
You can also compare two checked-in versions of the visited file.
Moreover, the functions @code{ediff-directory-revisions},
@code{ediff-merge-directory-revisions}, etc., let you run a group of
related Ediff sessions by taking a directory and comparing (or merging)
versions of files in that directory.

@node Commands, Registry of Ediff Sessions, Major Entry Points, Top
@chapter Commands

All Ediff commands are displayed in a quick
help window, unless you type @kbd{?} to shrink the window to just one line.
You can redisplay the help window by typing @kbd{?} again.
In this section
we comment only on the features that cannot be readily deduced from the
quick help window.
You can always type @kbd{E} in the control window to display this manual.

Many Ediff commands take numeric prefix arguments.  For instance, if you
type a number, say 3, and then @kbd{j} (@code{ediff-jump-to-difference}), Ediff
moves to the third difference region.   Typing 3 and then @kbd{a}
(@code{ediff-diff-to-diff}) copies the 3d difference region from buffer
A to buffer B.  Typing @kbd{b} does copying in the opposite
direction.  (In 3-way comparison mode, the commands for copying are
@kbd{ab}, @kbd{ba}, @kbd{ca}, etc.)
Likewise, 4 followed by @kbd{ra}
restores the 4th difference region in buffer A (if it was previously
saved as a result of copying from, say, buffer B to A).

Some commands take negative prefix arguments as well.
For instance, typing @kbd{-} and then @kbd{j} will take Ediff to the last
difference. Typing @kbd{-2} then @kbd{j} takes Ediff to the penultimate
difference region, etc.

Without the prefix argument, all commands operate on the current
selected difference region.  You can select any difference region
as the current one using other Ediff commands.

For some commands, the value of the prefix argument is immaterial. However,
if supplied, the prefix argument modifies the command.  For instance,
normally the commands @kbd{ga}/@kbd{gb}/@kbd{gc}
(@code{ediff-jump-to-difference-at-point}) causes Ediff to jump to the
difference region that is closest to the point in a specified buffer (the
buffer, A, B, or C, is specified by the last character of the command,
i.e., for @code{gb}, the specified buffer is B).
However, with a prefix argument, Ediff would position all these
buffers around the area indicated by the current point in the specified
buffer: if the point is inside a difference region, then the buffers will
be positioned at this difference region. If the point is not in any
difference region, then it is in an area where all buffers agree with each
other. In this case, all buffers will be positioned so that they would
display this area.

The total number of differences and the current difference number are
always displayed in the mode line of the control window. 

If, after making changes to buffers A, B, or C, you decide to save them, it
is best to use @code{ediff-save-buffer}, which is bound to @kbd{wa},
@kbd{wb}, and @kbd{wc} (@kbd{wa} will save buffer A, @kbd{wb} saves buffer
B, etc.).

Typing @kbd{wd} saves the output from the @code{diff} utility to a file, so
you can later refer to it. With prefix argument, this command saves the
plain output from @file{diff} (see @code{ediff-diff-program} and
@code{ediff-diff-options}). Without the argument, it saves customized
@file{diff} output (see @code{ediff-custom-diff-program} and
@code{ediff-custom-diff-options}), if it is available.

Instead of saving it, @file{diff} output can be @emph{displayed} using the
command @kbd{D}. Without the prefix argument, it displays the customized
@file{diff} output of the session.  With the prefix argument, it displays
the plain @file{diff} output If either of the @file{diff} outputs is
unavailable (because it wasn't generated or the user killed the respective
buffer), then Ediff will try to display the other @file{diff} output.  If
none is available, a warning is issued.

The command @kbd{z} suspends the current ediff session. It hides the
control buffer and the variants. The easiest way to resume a suspended
Ediff session is through the registry of active sessions.
@xref{Registry of Ediff Sessions}, for details.

The command @kbd{q} quits the current Ediff session. With a prefix
argument, it will ask the user whether to delete the variant
buffers. 

The command @kbd{s} is used only for merging.  It shrinks window C (the
merge window) to its minimal size, thereby exposing as much of buffers A
and B as possible.  This command is intended only for temporary viewing;
therefore, Ediff restores window C to its original size whenever it
makes any other change in the window configuration.  Typing @kbd{s}
again also restores the original size of window C.  However, recentering and
jumping to a difference does not affect window C's size.

With a positive prefix argument, the command @kbd{s} makes the merge
window, window C, slightly taller. With @kbd{-} or a negative prefix
argument, @kbd{s} makes window C slightly shorter.

Another command used only for merging is @kbd{+}.  Its effect is to
combine the current difference regions of buffers A and B and put the
combination into the merge buffer. @xref{Merging and diff3}, specifically,
the variables @code{ediff-combine-diffs} and
@code{ediff-combination-pattern}.

In merge mode, Ediff uses a default variant (one of the two files being
merged) when it cannot decide which of the difference regions (that of
buffer A or buffer B) should be copied into the merge buffer.  You might
decide to use the other variant instead.  To facilitate this, Ediff has
a command, bound to @kbd{&}, which selects another default variant for
the current difference and subsequent differences.  You can specify as
the new default any of @samp{default-A}, @samp{default-B}, or
@samp{combined}.  @xref{Merging and diff3}, for details.

Such repeated merging affects only difference regions that have
default-A/B status, and only if they were not changed with respect to
their originals.

Some commands are not bound to any key:

@table @code
@item eregistry
@itemx ediff-show-registry
@findex eregistry
@findex ediff-show-registry
This command brings up the registry of active Ediff sessions.  Ediff
registry is a useful device that can be used for resuming Ediff sessions
when the user switched to some other work before finishing a comparison or
merging job.  It is also useful for switching between multiple active Ediff
sessions that are run at the same time. The function @code{eregistry} is an
alias for @code{ediff-show-registry}.
@item ediff-toggle-multiframe
@findex ediff-toggle-multiframe
Changes the display from the multi-frame mode (where the quick help window
is in a separate frame) to the single-frame mode (where all Ediff buffers
share the same frame), and vice versa.
@item ediff-revert-buffers-then-recompute-diffs
@findex ediff-revert-buffers-then-recompute-diffs
This command reverts the buffers you are comparing and recomputes their
differences.  It is useful when, after making changes, you decided to
make a fresh start, or if at some point you changed the files being
compared but want to discard any changes to comparison buffers that were
done since then.

This command normally asks for confirmation before reverting files.
With a prefix argument, it reverts files without asking.


@item ediff-profile
@findex ediff-profile
Ediff has an admittedly primitive (but useful) facility for profiling
Ediff's commands.  It is meant for Ediff maintenance---specifically, for
making it run faster.  The function @code{ediff-profile} toggles
profiling of ediff commands.
@end table

@node Registry of Ediff Sessions, Session Groups, Commands, Top
@chapter Registry of Ediff Sessions

Ediff maintains a registry of all its invocations that are
still @emph{active}. This feature is very convenient for switching among
active Ediff sessions or for quickly restarting a suspended Ediff session.

The focal point of this activity is a buffer
called @emph{*Ediff Registry*}. You can display this buffer by typing
@kbd{R} in any Ediff Control Buffer or Session Group Buffer
(@pxref{Session Groups}), or by typing
@kbd{M-x eregistry} into the Minibuffer.
The latter would be the fastest way to bring up the registry
buffer if no control or group buffer is displayed in any of the visible
Emacs windows.
If you are in a habit of running multiple long Ediff sessions and often need to
suspend, resume, or switch between them, it may be a good idea to have the
registry buffer permanently displayed in a separate, dedicated window.

The registry buffer has several convenient key bindings.
For instance, clicking mouse button 2 or typing
@kbd{RET} or @kbd{v} over any session record resumes that session.
Session records in the registry buffer provide a fairly complete
description of each session, so it is usually easy to identify the right
session to resume.

Other useful commands are bound to @kbd{SPC} (next registry record)
and @kbd{DEL} (previous registry record). There are other commands as well,
but you don't need to memorize them, since they are listed at the top of
the registry buffer.

@node Session Groups, Remote and Compressed Files, Registry of Ediff Sessions, Top
@chapter Session Groups

Several major entries of Ediff perform comparison and merging on
directories.  On entering @code{ediff-directories},
@code{ediff-directories3},
@code{ediff-merge-directories},
@code{ediff-merge-directories-with-ancestor},
@code{ediff-directory-revisions},
@code{ediff-merge-directory-revisions}, or
@code{ediff-merge-directory-revisions-with-ancestor},
the user is presented with a
Dired-like buffer that lists files common to the directories involved along
with their sizes. (The list of common files can be further filtered through
a regular expression, which the user is prompted for.) We call this buffer
@emph{Session Group Panel} because all Ediff sessions associated with the
listed files will have this buffer as a common focal point.

Clicking button 2 or typing @kbd{RET} or @kbd{v} over a
record describing files invokes Ediff in the appropriate mode on these
files. You can come back to the session group buffer associated with a
particular invocation of Ediff by typing @kbd{M} in Ediff control buffer of
that invocation.

Many commands are available in the session group buffer; some are
applicable only for certain types of work. The relevant commands are always
listed at the top of each session group buffer, so there is no need to
memorize them.

In directory comparison or merging, a session group panel displays only the
files common to all directories involved. The differences are kept in a
separate buffer and are conveniently displayed by typing @kbd{D} to the
corresponding session group panel. Thus, as an added benefit, Ediff can be
used to compare the contents of up to three directories.

Session records in session group panels are also marked with @kbd{+}, for
active sessions, and with @kbd{-}, for finished sessions.  

Sometimes, it is convenient to exclude certain session records from a group.
Usually this happens when the user doesn't intend to run Ediff of certain
files in the group, and the corresponding session records just add clutter
to the session group buffer. To help alleviate this problem, the user can
type @kbd{h} to mark a session as a candidate for exclusion and @kbd{x} to
actually hide the marked sessions. There actions are reversible: with a
prefix argument, @kbd{h} unmarks the session under the cursor, and @kbd{x}
brings the hidden sessions into the view (@kbd{x} doesn't unmark them,
though, so the user has to explicitly unmark the sessions of interest).

Group sessions also understand the command @kbd{m}, which marks sessions
for future operations (other than hiding) on a group of sessions. At present,
the only such group-level operation is the creation of a multi-file patch.

@cindex Multi-file patches
A multi-file patch is a concatenated output of several runs of the Unix
@file{diff} command (some versions of @file{diff} let you create a
multi-file patch in just one run).  In a session group buffer created in
response to @code{ediff-directories} or @code{ediff-directory-revisions},
the user can type @kbd{P} to create a multi-file patch of marked sessions
(which must be marked using the @kbd{m} command).  Ediff then will display
a buffer containing the patch.  In an @code{ediff-directories} session, it
is enough to just mark the requisite sessions. In
@code{ediff-directory-revisions} revisions, the marked sessions must also
be active, or else Ediff will refuse to produce a multi-file patch. This is
because, in the latter-style sessions, there are many ways to create diff
output, and it is easier to handle by running Ediff on the inactive
sessions.


@node Remote and Compressed Files, Customization, Session Groups, Top
@chapter Remote and Compressed Files

Ediff works with remote, compressed, and encrypted files.  Ediff
supports @file{ange-ftp.el}, @file{jka-compr.el}, @file{uncompress.el}
and @file{crypt++.el}, but it may work with other similar packages as
well.  This means that you can compare files residing on another
machine, or you can apply a patch to a file on another machine.  Even
the patch itself can be a remote file!

When patching compressed or remote files, Ediff does not rename the source
file (unlike what the @code{patch} utility would usually do).  Instead, the
source file retains its name and the result of applying the patch is placed
in a temporary file that has the suffix @file{_patched} attached.
Generally, this applies to files that are handled using black magic, such
as special file handlers (ange-ftp and some compression and encryption
packages all use this method).

Regular files are treated by the @code{patch} utility in the usual manner,
i.e., the original is renamed into @file{source-name.orig} and the result
of the patch is placed into the file source-name. (Ediff @file{_orig}
on systems like VMS, DOS, etc.)

@node Customization, Credits, Remote and Compressed Files, Top
@chapter Customization

Ediff has a rather self-explanatory interface, and in most cases you
won't need to change anything.  However, should the need arise, there are
extensive facilities to change the default behavior.

Most of the customization can be done by setting various variables in the
@file{.emacs} file. Some customization (mostly window-related
customization and faces) can be done by putting appropriate lines in
@file{.Xdefaults}, @file{.xrdb}, or whatever X resource file is in use.

With respect to the latter, please note that the X resource
for Ediff customization is `Ediff', @emph{not} `emacs'.
@xref{Window and Frame Configuration},
@xref{Highlighting Difference Regions}, for further details. Please also
refer to Emacs manual for the information on how to set Emacs X resources.

@menu
* Hooks::                       Customization via the hooks.
* Quick Help::                  How to customize Ediff's quick help feature.
* Window and Frame Configuration::  Controlling the way Ediff displays things.
* Selective Browsing::          Advanced browsing through difference regions.
* Highlighting Difference Regions::  Controlling highlighting.
* Narrowing::                   Comparing regions, windows, etc.
* Refinement of Difference Regions::  How to control the refinement process.
* Patch and Diff Programs::     Changing the utilities that compute differences
                                and apply patches.
* Merging and diff3::           How to customize Ediff in its Merge Mode.
* Support for Version Control::  Changing the version control package.
                                 You are not likely to do that.
* Customizing the Mode Line::   Changing the look of the mode line in Ediff.
* Miscellaneous::               Other customization.
* Notes on Heavy-duty Customization::  Customization for the gurus.
@end menu

@node Hooks, Quick Help, Customization, Customization
@section Hooks

The bulk of customization can be done via the following hooks:

@table @code
@item ediff-load-hook
@vindex ediff-load-hook
This hook can be used to change defaults after Ediff is loaded.

@item ediff-keymap-setup-hook
@vindex ediff-keymap-setup-hook
This hook can be used to alter bindings in Ediff's keymap. These hooks are
run right after the default bindings are set but before
@code{ediff-load-hook}.  The regular user needs not be concerned with this
hook---it is provided for implementors of other Emacs packages built on top
of Ediff.

@item ediff-before-setup-windows-hook
@itemx ediff-after-setup-windows-hook
@vindex ediff-before-setup-windows-hook
@vindex ediff-after-setup-windows-hook
These two hooks are called before and after Ediff sets up its window
configuration.  Can be used to save the configuration that existed
before Ediff starts or for whatever other purposes.

@item ediff-suspend-hook
@itemx ediff-quit-hook
@vindex ediff-suspend-hook
@vindex ediff-quit-hook
These two hooks are run when you suspend or quit Ediff.  They can be
used to set desired window configurations, delete files Ediff didn't
want to clean up after exiting, etc.

By default, @code{ediff-quit-hook} holds one hook function,
@code{ediff-cleanup-mess}, which cleans after Ediff, as appropriate in
most cases.  You probably won't want to change it, but you might
want to add other hook functions.

Keep in mind that hooks executing before @code{ediff-cleanup-mess} start
in @code{ediff-control-buffer;} they should also leave
@code{ediff-control-buffer} as the current buffer when they finish.
Hooks that are executed after @code{ediff-cleanup-mess} should expect
the current buffer be either buffer A or buffer B.
@code{ediff-cleanup-mess} doesn't kill the buffers being compared or
merged (see @code{ediff-cleanup-hook}, below).

@item ediff-cleanup-hook
@vindex ediff-cleanup-hook
This hook is run just before @code{ediff-quit-hook}.  This is a good
place to do various cleanups, such as deleting the variant buffers.
Ediff provides a function, @code{ediff-janitor}, as one such possible
hook, which you can add to @code{ediff-cleanup-hook} with
@code{add-hooks}.

@findex ediff-janitor
This function kills buffers A, B, and, possibly, C, if these buffers aren't
modified. In merge jobs, buffer C is never deleted.  However, the side
effect of using this function is that you may not be able to compare the
same buffer in two separate Ediff sessions: quitting one of them will
delete this buffer in another session as well.

@item ediff-before-setup-control-frame-hook
@itemx ediff-after-setup-control-frame-hook
@vindex ediff-before-setup-control-frame-hook
@vindex ediff-after-setup-control-frame-hook
These two hooks run before and after Ediff sets up the control frame.
They can be used to relocate Ediff control frame when Ediff runs in a
multiframe mode (i.e., when the control buffer is in its own dedicated
frame).  Be aware that many variables that drive Ediff are local to
Ediff Control Panel (@code{ediff-control-buffer}), which requires
special care in writing these hooks.  Take a look at
@code{ediff-default-suspend-hook} and @code{ediff-default-quit-hook} to
see what's involved.

@item ediff-startup-hook
@vindex ediff-startup-hook
This hook is run at the end of Ediff startup.

@item ediff-select-hook
@vindex ediff-select-hook
This hook is run after Ediff selects the next difference region.

@item ediff-unselect-hook
@vindex ediff-unselect-hook
This hook is run after Ediff unselects the current difference region.

@item ediff-prepare-buffer-hook
@vindex ediff-prepare-buffer-hook
This hook is run for each Ediff buffer (A, B, C) right after the buffer
is arranged.

@item ediff-display-help-hook
@vindex ediff-display-help-hook
Ediff runs this hook each time after setting up the help message.  It
can be used to alter the help message for custom packages that run on
top of Ediff.

@item ediff-mode-hook
@vindex ediff-mode-hook
This hook is run just after Ediff mode is set up in the control
buffer. This is done before any Ediff window is created. You can use it to
set local variables that alter the look of the display.

@item ediff-registry-setup-hook
@vindex ediff-registry-setup-hook
Hooks run after setting up the registry for all active Ediff session.
@xref{Session Groups}, for details.
@item ediff-session-group-setup-hook
@vindex ediff-session-group-setup-hook
Hooks run after setting up a control panel for a group of related Ediff
sessions. @xref{Session Groups}, for details.
@end table

@node Quick Help, Window and Frame Configuration, Hooks, Customization
@section Quick Help
@vindex ediff-use-long-help-message
@vindex ediff-control-buffer
@vindex ediff-startup-hook
@vindex ediff-help-message

Ediff provides quick help using its control panel window. Since this window
takes a fair share of the screen real estate, you can toggle it off by
typing @kbd{?}.  The control window will then shrink to just one line and a
mode line, displaying a short help message.

The variable @code{ediff-use-long-help-message} tells Ediff whether
you use the short message or the long one.  By default, it
is set to @code{nil}, meaning that the short message is used.
Set this to @code{t}, if you want Ediff to use the long
message by default. This property can always be changed interactively, by
typing @kbd{?} into Ediff Control Buffer.

If you want to change the appearance of the help message on a per-buffer
basis, you must use @code{ediff-startup-hook} to change the value of
the variable @code{ediff-help-message}, which is local to
@code{ediff-control-buffer}.

@node Window and Frame Configuration, Selective Browsing, Quick Help, Customization
@section Window and Frame Configuration

On a non-windowing display, Ediff sets things up in one frame, splitting
it between a small control window and the windows for buffers A, B, and C.
The split between these windows can be horizontal or
vertical, which can be changed interactively by typing @kbd{|} while the
cursor is in the control window.

On a window display, Ediff sets up a dedicated frame for Ediff Control
Panel and then it chooses windows as follows: If one of the buffers
is invisible, it is displayed in the currently selected frame.  If
a buffer is visible, it is displayed in the frame where it is visible.
If, according to the above criteria, the two buffers fall into the same
frame, then so be it---the frame will be shared by the two.  The same
algorithm works when you type @kbd{C-l} (@code{ediff-recenter}), @kbd{p}
(@code{ediff-previous-difference}), @kbd{n}
(@code{ediff-next-difference}), etc.

The above behavior also depends on whether the current frame is splittable,
dedicated, etc. Unfortunately, the margin is too small to present this
remarkable algorithm.

The bottom line of all this is that you can compare buffers in one frame or
in different frames.  The former is done by default, while the latter can
be achieved by arranging buffers A, B (and C, if applicable) to be seen in
different frames.  Ediff respects these arrangements, automatically
adapting itself to the multi-frame mode.

Ediff uses the following variables to set up its control panel
(a.k.a. control buffer, a.k.a. quick help window):

@table @code
@item ediff-control-frame-parameters
@vindex ediff-control-frame-parameters
You can change or augment this variable including the font, color,
etc.  The X resource name of Ediff Control Panel frames is @samp{Ediff}.  Under
X-windows, you can use this name to set up preferences in your
@file{~/.Xdefaults}, @file{~/.xrdb}, or whatever X resource file is in
use. Usually this is preferable to changing
@code{ediff-control-frame-parameters} directly.  For instance, you can
specify in @file{~/.Xdefaults} the color of the control frame
using the resource @samp{Ediff*background}.

In general, any X resource pertaining the control frame can be reached
via the prefix @code{Ediff*}.

@item ediff-control-frame-position-function
@vindex ediff-control-frame-position-function
The preferred way of specifying the position of the control frame is by
setting the variable @code{ediff-control-frame-position-function} to an
appropriate function.
The default value of this variable is
@code{ediff-make-frame-position}. This function places the control frame in
the vicinity of the North-East corner of the frame displaying buffer A.

@findex ediff-make-frame-position
@end table

The following variables can be used to adjust the location produced by
@code{ediff-make-frame-position} and for related customization.

@table @code
@item ediff-narrow-control-frame-leftward-shift
@vindex ediff-narrow-control-frame-leftward-shift
Specifies the number of characters for shifting
the control frame from the rightmost edge of frame A when the control
frame is displayed as a small window. 

@item ediff-wide-control-frame-rightward-shift
@vindex ediff-wide-control-frame-rightward-shift
Specifies the rightward shift of the control frame
from the left edge of frame A when the control frame shows the full
menu of options.

@item ediff-control-frame-upward-shift
@vindex ediff-control-frame-upward-shift
Specifies the number of pixels for the upward shift
of the control frame.

@item ediff-prefer-iconified-control-frame
@vindex ediff-prefer-iconified-control-frame
If this variable is @code{t}, the control frame becomes iconified
automatically when you toggle the quick help message off.  This saves
valuable real estate on the screen.  Toggling help back will deiconify
the control frame.

To start Ediff with an iconified Control Panel, you should set this
variable to @code{t} and @code{ediff-prefer-long-help-message} to
@code{nil} (@pxref{Quick Help}).  This behavior is useful only if the
window manager is TWM or a derivative. Also, this doesn't work under
XEmacs, since this editor ignores input from icons.
@end table

@findex ediff-setup-windows
To make more creative changes in the way Ediff sets up windows, you can
rewrite the function @code{ediff-setup-windows}.  However, we believe
that detaching Ediff Control Panel from the rest and making it into a
separate frame offers an important opportunity by allowing you to
iconify that frame.  Under Emacs, the icon will usually accept all of
the Ediff commands, but will free up valuable real estate on your screen
(this may depend on the window manager, though).  Iconifying won't do
any good under XEmacs since XEmacs icons are not sensitive to keyboard
input.  The saving grace is that, even if not iconified, the control
frame is very small, smaller than some icons, so it does not take much
space in any case.

The following variable controls how windows are set up:

@table @code
@item ediff-window-setup-function
@vindex ediff-window-setup-function
The multiframe setup is done by the
@code{ediff-setup-windows-multiframe} function, which is the default on
windowing displays.  The plain setup, one where all windows are always
in one frame, is done by @code{ediff-setup-windows-plain}, which is the
default on a non-windowing display (or in an xterm window).  In fact,
under Emacs, you can switch freely between these two setups by executing
the command @code{ediff-toggle-multiframe} using the Minibuffer.
@findex ediff-setup-windows-multiframe
@findex ediff-setup-windows-plain
@findex ediff-toggle-multiframe

If you don't like any of these setups, write your own function.  See the
documentation for @code{ediff-window-setup-function} for the basic
guidelines.  However, writing window setups is not easy, so you should
first take a close look at @code{ediff-setup-windows-plain} and
@code{ediff-setup-windows-multiframe}.
@end table

You can run multiple Ediff sessions at once, by invoking Ediff several
times without exiting previous Ediff sessions.  Different sessions
may even operate on the same pair of files.

Each session has its own Ediff Control Panel and all the regarding a
particular session is local to the associated control panel buffer.  You
can switch between sessions by suspending one session and then switching
to another control panel.  (Different control panel buffers are
distinguished by a numerical suffix, e.g., @samp{Ediff Control Panel<3>}.)

@node Selective Browsing, Highlighting Difference Regions, Window and Frame Configuration, Customization
@section Selective Browsing

Sometimes it is convenient to be able to step through only some difference
regions, those that satisfy certain regular expressions, and to ignore all
others.  On other occasions, you may want to ignore difference regions that
satisfy some regular expressions, and to look only at the rest.

The commands @kbd{#f} and @kbd{#h} let you do precisely this.

Typing @kbd{#f} lets you specify regular expressions that match difference
regions you want to focus on.
We shall call these regular expressions @var{regexp-A}, @var{regexp-B} and
@var{regexp-C}.
Ediff will then start stepping through only those difference regions
where the region in buffer A matches @var{regexp-A} and/or the region in
buffer B matches @var{regexp-B}, etc.  Whether `and' or `or' will be used
depends on how you respond to a question.

When scanning difference regions for the aforesaid regular expressions,
Ediff narrows the buffers to those regions. This means that you can use
the expressions @kbd{\`} and @kbd{\'} to tie search to the beginning or end
of the difference regions.

On the other hand, typing @kbd{#h} lets you specify (hide) uninteresting
regions. That is, if a difference region in buffer A matches
@var{regexp-A}, the corresponding region in buffer B matches @var{regexp-B}
and (if applicable) buffer-C's region matches @var{regexp-C}, then the
region will be ignored by the commands @kbd{n}/@key{SPC}
(@code{ediff-next-difference}) and @kbd{p}/@key{DEL}
(@code{ediff-previous-difference}) commands.

Typing @kbd{#f} and @kbd{#h} toggles selective browsing on and off.

Note that selective browsing affects only @code{ediff-next-difference}
and @code{ediff-previous-difference}, i.e., the commands
@kbd{n}/@key{SPC} and @kbd{p}/@key{DEL}.  @kbd{#f} and @kbd{#h} do not
change the position of the point in the buffers.  And you can still jump
directly (using @kbd{j})  to any numbered
difference.

Users can supply their own functions to specify how Ediff should do
selective browsing. To change the default Ediff function, add a function to
@code{ediff-load-hook} which will do the following assignments:

@example
(setq ediff-hide-regexp-matches-function 'your-hide-function) 
(setq ediff-focus-on-regexp-matches-function 'your-focus-function)
@end example

@strong{Useful hint}: To specify a regexp that matches everything, don't
simply type @key{RET} in response to a prompt. Typing @key{RET} tells Ediff
to accept the default value, which may not be what you want. Instead, you
should enter something like @key{^} or @key{$}. These match every
line.

You can use the status command, @kbd{i}, to find out whether
selective browsing is currently in use.

The regular expressions you specified are kept in the local variables
@code{ediff-regexp-focus-A}, @code{ediff-regexp-focus-B},
@code{ediff-regexp-focus-C}, @code{ediff-regexp-hide-A},
@code{ediff-regexp-hide-B}, @code{ediff-regexp-hide-C}. Their default value
is the empty string (i.e., nothing is hidden or focused on).  To change the
default, set these variables in @file{.emacs} using @code{setq-default}.

In addition to the ability to ignore regions that match regular
expressions, Ediff can be ordered to start skipping over certain
``inessential'' regions.  This is controlled by the following variable:

@table @code
@item ediff-ignore-similar-regions
@vindex ediff-ignore-similar-regions
If @code{t}, causes Ediff to skip over difference regions
that deemed inessential, i.e., where the only differences are those
in the white space and newlines.
@end table

@strong{Note:} In order for this feature to work, auto-refining of
difference regions must be on, since otherwise Ediff won't know if there
are fine differences between regions.  On devices where Emacs can display
faces, auto-refining is a default, but it is not turned on by default on
text-only terminals.  In that case, you must explicitly turn auto-refining
on (such as, by typing @kbd{@@}).

@strong{Reassurance:} If many inessential regions appear in a row, Ediff may
take a long time to jump to the next region because it has to compute
fine differences of all intermediate regions.  This delay does not
indicate any problem.

@node Highlighting Difference Regions, Narrowing, Selective Browsing, Customization
@section Highlighting Difference Regions

The following variables control the way Ediff highlights difference
regions:

@table @code
@item ediff-before-flag-bol
@itemx ediff-after-flag-eol
@itemx ediff-before-flag-mol
@itemx ediff-after-flag-mol
@vindex ediff-before-flag-bol
@vindex ediff-after-flag-eol
@vindex ediff-before-flag-mol
@vindex ediff-after-flag-mol
These variables hold strings that Ediff uses to mark the beginning and the
end of the differences found in files A, B, and C on devices where Emacs
cannot display faces. Ediff uses different flags to highlight regions that
begin/end at the beginning/end of a line or in a middle of a line.

@item ediff-current-diff-face-A
@itemx ediff-current-diff-face-B
@itemx ediff-current-diff-face-C
@vindex ediff-current-diff-face-A
@vindex ediff-current-diff-face-B
@vindex ediff-current-diff-face-C
Ediff uses these faces to highlight current differences on devices where
Emacs can display faces.  These and subsequently described faces can be set
either in @file{.emacs} or in @file{.Xdefaults}. The X resource for Ediff
is @samp{Ediff}, @emph{not} @samp{emacs}. Please refer to Emacs manual for
the information on how to set X resources.
@item ediff-fine-diff-face-A
@itemx ediff-fine-diff-face-B
@itemx ediff-fine-diff-face-C
@vindex ediff-fine-diff-face-A
@vindex ediff-fine-diff-face-B
@vindex ediff-fine-diff-face-C
Ediff uses these faces to show the fine differences between the current
differences regions in buffers A, B, and C, respectively.

@item ediff-even-diff-face-A
@itemx ediff-even-diff-face-B
@itemx ediff-even-diff-face-C
@itemx ediff-odd-diff-face-A
@itemx ediff-odd-diff-face-B
@itemx ediff-odd-diff-face-C
@vindex ediff-even-diff-face-A
@vindex ediff-even-diff-face-B
@vindex ediff-even-diff-face-C
@vindex ediff-odd-diff-face-A
@vindex ediff-odd-diff-face-B
@vindex ediff-odd-diff-face-C
Non-current difference regions are displayed using these alternating
faces. The odd and the even faces are actually identical on monochrome
displays, because without colors options are limited.
So, Ediff uses italics to highlight non-current differences.

@item ediff-force-faces
@vindex ediff-force-faces
Ediff generally can detect when Emacs is running on a device where it can
use highlighting with faces. However, if it fails to determine that faces
can be used, the user can set this variable to @code{t} to make sure that
Ediff uses faces to highlight differences.

@item ediff-highlight-all-diffs
@vindex ediff-highlight-all-diffs
Indicates whether---on a window system---Ediff should highlight differences
using inserted strings (as on a text-only terminal) or using colors and
highlighting.  Normally, Ediff highlights all differences, but the
selected difference is highlighted more visibly.  One can cycle through
various modes of highlighting by typing @kbd{h}.  By default, Ediff
starts in the mode where all difference regions are highlighted.  If you
prefer to start in the mode where unselected differences are not
highlighted, you should set @code{ediff-highlight-all-diffs} to
@code{nil}.  Type @kbd{h} to restore highlighting of all differences.

Ediff lets you switch between the two modes of highlighting.  That is,
you can switch interactively from highlighting using faces to
highlighting using string flags, and back.  Of course, switching has
effect only under a windowing system.  On a text-only terminal or in an
xterm window, the only available option is highlighting with strings.
@end table

@noindent
If you want to change the above variables, you must do it
@strong{before} Ediff is loaded. 

There are two ways to change the default setting
for highlighting faces: either change the variables, as shown here,

@example
(setq ediff-current-diff-face-A 'bold-italic)
@end example

@noindent
or here,

@example
(setq ediff-current-diff-face-A
(copy-face 'bold-italic 'ediff-current-diff-face-A))
@end example

@noindent
or modify the defaults selectively:

@smallexample
(add-hook 'ediff-load-hook
          (function (lambda () 
                      (set-face-foreground
                        ediff-current-diff-face-B "blue")
                      (set-face-background
                        ediff-current-diff-face-B "red")
                      (make-face-italic
                        ediff-current-diff-face-B))))
@end smallexample

You may also want to take a look at how the above faces are defined in the
source code of Ediff. 

@strong{Note:} it is not recommended to use @code{internal-get-face} (or
@code{get-face} in XEmacs) when defining Ediff's faces, since this may
cause problems when there are several frames with different font sizes.
Instead, use @code{copy-face} or @code{set/make-face-@dots{}} as shown
above.

@node Narrowing, Refinement of Difference Regions, Highlighting Difference Regions, Customization
@section Narrowing

If buffers being compared are narrowed at the time of invocation of
Ediff, @code{ediff-buffers} will preserve the narrowing range.  However,
if @code{ediff-files} is invoked on the files visited by these buffers,
that widens the buffers, since this command is defined to compare the
entire files.

Calling @code{ediff-regions-linewise} or @code{ediff-windows-linewise},
or the corresponding @samp{-wordwise} commands, narrows the buffers
being compared (corresponding to the regions being compared).  The
original accessible ranges are restored when you quit Ediff.
During the command, you can toggle this narrowing on and off
with the @kbd{%} command.

These two variables control this narrowing behavior:

@table @code
@item ediff-start-narrowed
@vindex ediff-start-narrowed
If @code{t}, Ediff narrows the display to the appropriate range when it
is invoked with an @samp{ediff-regions@dots{}} or
@samp{ediff-windows@dots{}} command.  If @code{nil}, these commands do
not automatically narrow, but you can still toggle narrowing on and off
by typing @kbd{%}.

@item ediff-quit-widened
@vindex ediff-quit-widened
Controls whether on quitting Ediff should restore the accessible range
that existed before the current invocation.
@end table

@node Refinement of Difference Regions, Patch and Diff Programs, Narrowing, Customization
@section Refinement of Difference Regions

Ediff has variables to control the way fine differences are
highlighted.  This feature gives you control over the process of refinement.
Note that refinement ignores spaces, tabs, and newlines.

@table @code
@item ediff-auto-refine
@vindex ediff-auto-refine
This variable controls whether fine differences within regions are
highlighted automatically (``auto-refining'').  The default is yes
(@samp{on}).

On a slow machine, automatic refinement may be painful.  In that case,
you can turn auto-refining on or off interactively by typing
@kbd{@@}.  You can also turn off display of refining that has
already been done.

When auto-refining is off, fine differences are shown only for regions
for which these differences have been computed and saved before.  If
auto-refining and display of refining are both turned off, fine
differences are not shown at all.

Typing @kbd{*} computes and displays fine differences for the current
difference region, regardless of whether auto-refining is turned on.

@item ediff-auto-refine-limit
@vindex ediff-auto-refine-limit
If auto-refining is on, this variable limits the size of the regions to
be auto-refined.  This guards against the possible slowdown that may be
caused by extraordinary large difference regions.

You can always refine the current region by typing @kbd{*}.

@item ediff-forward-word-function
@vindex ediff-forward-word-function
This variable gives control over how fine differences are computed.  The
value must be a Lisp function that determines how the current difference
region should be split into words.

@vindex ediff-diff-program
@vindex ediff-forward-word-function
@findex ediff-forward-word
Fine differences are computed by first splitting the current difference
region into words and then passing this along to
@code{ediff-diff-program}. For the default
@code{ediff-forward-word-function} (which is @code{ediff-forward-word}), a
word is a string consisting of letters, @samp{-}, or @samp{_}; a string of
punctuation symbols; a string of digits, or a string consisting of symbols
that are neither space, nor a letter.

This default behavior is controlled by four variables: @code{ediff-word-1},
..., @code{ediff-word-4}. See the on-line documentation for these variables
and for the function @code{ediff-forward-word} for an explanation of how to
modify these variables.
@vindex ediff-word-1
@vindex ediff-word-2
@vindex ediff-word-3
@vindex ediff-word-4
@end table

Sometimes, when a region has too many differences between the variants,
highlighting of fine differences is inconvenient, especially on
color displays.  If that is the case, type @kbd{*} with a negative
prefix argument.  This unhighlights fine differences for the current
region.

To unhighlight fine differences in all difference regions, use the
command @kbd{@@}.  Repeated typing of this key cycles through three
different states: auto-refining, no-auto-refining, and no-highlighting
of fine differences.

@node Patch and Diff Programs, Merging and diff3, Refinement of Difference Regions, Customization
@section Patch and Diff Programs

This section describes variables that specify the programs to be used for
applying patches and for computing the main difference regions (not the
fine difference regions):

@table @code
@item ediff-patch-program
@itemx ediff-diff-program
@itemx ediff-diff3-program
@vindex ediff-patch-program
@vindex ediff-diff-program
@vindex ediff-diff3-program
These variables specify the programs to use to produce differences
and do patching.

@item ediff-patch-options
@itemx ediff-diff-options
@itemx ediff-diff3-options
@vindex ediff-patch-options
@vindex ediff-diff-options
@vindex ediff-diff3-options
These variables specify the options to pass to the above utilities.

In @code{ediff-diff-options}, it may be useful to specify options
such as @samp{-w} that ignore certain kinds of changes.  However,
Ediff does not let you use the option @samp{-c}, as it doesn't recognize this
format yet.


@item ediff-custom-diff-program
@itemx ediff-custom-diff-options
@vindex ediff-custom-diff-program
@vindex ediff-custom-diff-options
@findex ediff-save-buffer
Because Ediff limits the options you may want to pass to the @code{diff}
program, it partially makes up for this drawback by letting you save the
output from @code{diff} in your preferred format, which is specified via
the above two variables.

The output generated by @code{ediff-custom-diff-program} (which doesn't
even have to be a standard-style @file{diff}!) is not used by Ediff. It is
provided exclusively so that you can
refer to
it later, send it over email, etc.  For instance, after reviewing the
differences, you may want to send context differences to a colleague.
Since Ediff ignores the @samp{-c} option in
@code{ediff-diff-program}, you would have to run @code{diff -c} separately
just to produce the list of differences. Fortunately,
@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options}
eliminate this nuisance by keeping a copy of a difference list in the
desired format in a buffer that can be displayed via the command @kbd{D}.

@item ediff-patch-default-directory
@vindex ediff-patch-default-directory
Specifies the default directory to look for patches.

@end table

@noindent
@strong{Warning:} Ediff does not support the output format of VMS
@code{diff}.  Instead, make sure to use some implementation of POSIX
@code{diff}, such as @code{gnudiff}.

@node Merging and diff3, Support for Version Control, Patch and Diff Programs, Customization
@section Merging and diff3

Ediff supports three-way comparison via the functions @code{ediff-files3} and
@code{ediff-buffers3}.  The interface is the same as for two-way comparison.
In three-way comparison and merging, Ediff reports if any two difference
regions are identical.  For instance, if the current region in buffer A
is the same as the region in buffer C, then the mode line of buffer A will
display @samp{[=diff(C)]} and the mode line of buffer C will display
@samp{[=diff(A)]}. 

Merging is done according to the following algorithm.

If a difference region in one of the buffers, say B, differs from the ancestor
file while the region in the other buffer, A, doesn't, then the merge buffer,
C, gets B's region.  Similarly when buffer A's region differs from
the ancestor and B's doesn't, A's region is used.

@vindex ediff-default-variant
If both regions in buffers A and B differ from the ancestor file, Ediff
chooses the region according to the value of the variable
@code{ediff-default-variant}.  If its value is @code{default-A} then A's
region is chosen.  If it is @code{default-B} then B's region is chosen.
If it is @code{combined} then the region in buffer C will look like
this:

@example
#ifdef NEW  /* variant A */
difference region from buffer A
#else  /* variant B */
difference region from buffer B
#endif  /* NEW */
@end example

@vindex ediff-combination-pattern
The actual strings that separate the regions copied from buffer A and B
are controlled by the variable @code{ediff-combination-pattern}.  Its
value should be a list of three strings.  The first is inserted before
the difference region of buffer A; the second string goes between the
regions; the third goes after region B, as shown in the above example.

In addition to the state of the difference, during merging Ediff
displays the state of the merge for each region. If a difference came
from buffer A by default (because both regions A and B were different
from the ancestor and @code{ediff-default-variant} was set to @code{default-A})
then @samp{[=diff(A) default-A]} is displayed in the mode line.  If the
difference in buffer C came, say, from buffer B because the difference region
in that buffer differs from the ancestor, but the region in buffer A
does not (if merging with an ancestor) then @samp{[=diff(B) prefer-B]} is
displayed.  The indicators default-A/B and prefer-A/B are inspired by
Emerge and have the same meaning. 

Another indicator of the state of merge is @samp{combined}.  It appears
with any difference region in buffer C that was obtained by combining
the difference regions in buffers A and B as explained above.

In addition to state of merge and difference indicator, while merging with an
ancestor file or buffer, Ediff informs the user when the current difference
region in the (normally invisible) ancestor buffer is empty via the
@emph{AncestorEmpty} indicator. This helps determine if the changes
made to the original in variants A and B represent pure insertion or
deletion of text: if the mode line shows @emph{AncestorEmpty} and the
corresponding region in buffers A or B is not empty, this means that new
text was inserted. If this indicator is not present and the difference
regions in buffers A or B are non-empty, this means that text was
modified. Otherwise, the original text was deleted.

Although the ancestor buffer is normally invisible, Ediff maintains
difference regions there and advances the current difference region
accordingly. All highlighting of difference regions is provided in the
ancestor buffer, except for the fine differences.  Therefore, if desired, the
user can put the ancestor buffer in a separate frame and watch it
there. However, on a TTY, only one frame can be visible at any given time,
and Ediff doesn't support any single-frame window configuration where all
buffers, including the ancestor buffer, would be visible. However, the
ancestor buffer can be displayed by typing @kbd{/} to the control
window. (Type @kbd{C-l} to hide it again.)

Note that the state-of-difference indicators @samp{=diff(A)} and
@samp{=diff(B)} above are not redundant, even in the presence of a
state-of-merge indicator.  In fact, the two serve different purposes.

For instance, if the mode line displays @samp{=diff(B) prefer(B)} and
you copy a difference region from buffer A to buffer C then
@samp{=diff(B)} will change to @samp{diff-A} and the mode line will
display @samp{=diff(A) prefer-B}.  This indicates that the difference
region in buffer C is identical to that in buffer A, but originally
buffer C's region came from buffer B.  This is useful to know because
you can recover the original difference region in buffer C by typing
@kbd{r}.


Ediff never changes the state-of-merge indicator, except in response to
the @kbd{!} command (see below), in which case the indicator is lost.
On the other hand, the state-of-difference indicator is changed
automatically by the copying/recovery commands, @kbd{a}, @kbd{b}, @kbd{r},
@kbd{+}. 

The @kbd{!} command loses the information about origins of the regions
in the merge buffer (default-A, prefer-B, or combined).  This is because
recomputing differences in this case means running @code{diff3} on
buffers A, B, and the merge buffer, not on the ancestor buffer.  (It
makes no sense to recompute differences using the ancestor file, since
in the merging mode Ediff assumes that you have not edited buffers A and
B, but that you may have edited buffer C, and these changes are to be
preserved.)  Since some difference regions may disappear as a result of
editing buffer C and others may arise, there is generally no simple way
to tell where the various regions in the merge buffer came from.

In three-way comparison, Ediff tries to disregard regions that consist
entirely of white space.  For instance, if, say, the current region in
buffer A consists of the white space only (or if it is empty), Ediff will
not take it into account for the purpose of computing fine differences. The
result is that Ediff can provide a better visual information regarding the
actual fine differences in the non-white regions in buffers B and
C. Moreover, if the regions in buffers B and C differ in the white space
only, then a message to this effect will be displayed.

@vindex ediff-merge-window-share
In the merge mode, the share of the split between window C (the window
displaying the merge-buffer) and the windows displaying buffers A and B
is controlled by the variable @code{ediff-merge-window-share}.  Its
default value is 0.5.  To make the merge-buffer window smaller, reduce
this amount.

We don't recommend increasing the size of the merge-window to more than
half the frame (i.e., to increase the value of
@code{ediff-merge-window-share}) to more than 0.5, since it would be
hard to see the contents of buffers A and B.

You can temporarily shrink the merge window to just one line by
typing @kbd{s}.  This change is temporary, until Ediff finds a reason to
redraw the screen.  Typing @kbd{s} again restores the original window size.

With a positive prefix argument, the @kbd{s} command will make the merge
window slightly taller.  This change is persistent.  With `@kbd{-}' or
with a negative prefix argument, the command @kbd{s} makes the merge
window slightly shorter.  This change also persistent.

@vindex ediff-show-clashes-only
Ediff lets you automatically ignore the regions where only one of the
buffers A and B disagrees with the ancestor.  To do this, set the
variable @code{ediff-show-clashes-only} to non-@code{nil}.

You can toggle this feature interactively by typing @kbd{$}.

Note that this variable controls only how Ediff chooses the
next/previous difference to show.  You can still jump directly to any
difference using the command @kbd{j} (with a prefix argument specifying
the difference number).

@node Support for Version Control, Customizing the Mode Line, Merging and diff3, Customization
@section Support for Version Control


Ediff supports version control and lets you compare versions of files
visited by Emacs buffers via the function @code{ediff-revision}. This
feature is controlled by the following variables:

@table @code
@item ediff-version-control-package
@vindex ediff-version-control-package
A symbol. The default is @samp{vc}.

If you are like most Emacs users, Ediff will use VC as the version control
package. This is the standard Emacs interface to RCS, CVS, and SCCS.

However, if your needs are better served by other interfaces, you will
have to tell Ediff which version control package you are using, e.g.,
@example
(setq ediff-version-control-package 'rcs)
@end example

Apart from the standard @file{vc.el}, Ediff supports three other interfaces
to version control:
@file{rcs.el}, @file{pcl-cvs.el}, and @file{generic-sc.el}. 
The package @file{rcs.el} is written by Sebastian Kremer
<sk@@thp.Uni-Koeln.DE> and is available as
@example
@file{ftp.cs.buffalo.edu:pub/Emacs/rcs.tar.Z}
@file{ftp.uni-koeln.de:/pub/gnu/emacs/rcs.tar.Z}
@end example
The packages @file{pcl-cvs.el} and @file{generic-sc.el} are found in XEmacs
distribution.
@pindex @file{vc.el}
@pindex @file{rcs.el}
@pindex @file{pcl-cvs.el}
@pindex @file{generic-sc.el}
@end table

Ediff's interface to the above packages allows the user to compare the
versions of the current buffer or to merge them (with or without an
ancestor-version). These operations can also be performed on directories
containing files under version control.

In case of @file{pcl-cvs.el}, Ediff can also be invoked via the function
@code{run-ediff-from-cvs-buffer}---see the documentation string for this
function.

@node Customizing the Mode Line, Miscellaneous, Support for Version Control, Customization
@section Customizing the Mode Line

When Ediff is running, the mode line of @samp{Ediff Control Panel}
buffer shows the current difference number and the total number of
difference regions in the two files.

The mode line of the buffers being compared displays the type of the
buffer (@samp{A:}, @samp{B:}, or @samp{C:}) and (usually) the file name.
Ediff tries to be intelligent in choosing the mode line buffer
identification.  In particular, it works well with the
@file{uniquify.el} and @file{mode-line.el} packages (which improve on
the default way in which Emacs displays buffer identification).  If you
don't like the way Ediff changes the mode line, you can use
@code{ediff-prepare-buffer-hook} to modify the mode line.
@vindex ediff-prepare-buffer-hook
@pindex @file{uniquify.el}
@pindex @file{mode-line.el}

@node Miscellaneous, Notes on Heavy-duty Customization, Customizing the Mode Line, Customization
@section Miscellaneous

Here are a few other variables for customizing Ediff:

@table @code
@item ediff-split-window-function
@vindex ediff-split-window-function
Controls the way you want the window be split between file-A and file-B
(and file-C, if applicable).  It defaults to the vertical split
(@code{split-window-vertically}, but you can set it to
@code{split-window-horizontally}, if you so wish.
Ediff also lets you switch from vertical to horizontal split and back
interactively.

Note that if Ediff detects that all the buffers it compares are displayed in
separate frames, it assumes that the user wants them to be so displayed
and stops splitting windows.  Instead, it arranges for each buffer to
be displayed in a separate frame. You can switch to the one-frame mode
by hiding one of the buffers A/B/C.

You can also swap the windows where buffers are displayed by typing
@kbd{~}.

@item ediff-merge-split-window-function
@vindex ediff-merge-split-window-function
Controls how windows are
split between buffers A and B in the merge mode.
This variable is like @code{ediff-split-window-function}, but it defaults
to @code{split-window-horizontally} instead of
@code{split-window-vertically}.

@item ediff-make-wide-display-function
@vindex ediff-make-wide-display-function
The value is a function to be called to widen the frame for displaying
the Ediff buffers.  See the on-line documentation for
@code{ediff-make-wide-display-function} for details.  It is also
recommended to look into the source of the default function
@code{ediff-make-wide-display}.

You can toggle wide/regular display by typing @kbd{m}.  In the wide
display mode, buffers A, B (and C, when applicable) are displayed in a
single frame that is as wide as the entire workstation screen.  This is
useful when files are compared side-by-side.  By default, the display is
widened without changing its height.

@item ediff-use-last-dir
@vindex ediff-use-last-dir
Controls the way Ediff presents the
default directory when it prompts the user for files to compare.  If
@code{nil},
Ediff uses the default directory of the current buffer when it
prompts the user for file names.  Otherwise, it will use the
directories it had previously used for files A, B, or C, respectively.

@item ediff-no-emacs-help-in-control-buffer
@vindex ediff-no-emacs-help-in-control-buffer
If @code{t}, makes @kbd{C-h}
behave like the @key{DEL} key, i.e., it will move you back to the previous
difference rather than invoking help.  This is useful when, in an xterm
window or a text-only terminal, the Backspace key is bound to @kbd{C-h} and is
positioned more conveniently than the @key{DEL} key.

@item ediff-toggle-read-only-function
@vindex ediff-toggle-read-only-function
This variable's value is a function that Ediff uses to toggle
the read-only property in its buffers.

The default function that Ediff uses simply toggles the read-only property,
unless the file is under version control.  For a checked-in file under
version control, Ediff first tries to check the file out.

@item ediff-keep-variants
@vindex @code{ediff-keep-variants}
The default is @code{t}, meaning that the buffers being compared or merged will
be preserved when Ediff quits. Setting this to @code{nil} causes Ediff to
offer the user a chance to delete these buffers (if they are not modified).
Supplying a prefix argument to the quit command (@code{q}) temporarily
reverses the meaning of this variable. This is convenient when the user
prefers one of the behaviors most of the time, but occasionally needs the
other behavior.

However, Ediff temporarily resets this variable to @code{t} if it is
invoked via one of the "buffer" jobs, such as @code{ediff-buffers}.
This is because it is all too easy to loose day's work otherwise.
Besides, in a "buffer" job, the variant buffers have already been loaded
prior to starting Ediff, so Ediff just preserves status quo here.

Using @code{ediff-cleanup-hook}, one can make Ediff delete the variants
unconditionally (e.g., by making @code{ediff-janitor} into one of these hooks).
@item ediff-grab-mouse
@vindex @code{ediff-grab-mouse}
Default is @code{t}.  Normally, Ediff grabs mouse and puts it in its
control frame.  This is useful since the user can be sure that when he
needs to type an Ediff command the focus will be in an appropriate Ediff's
frame.  However, some users prefer to move the mouse by themselves.  The
above variable, if set to @code{maybe}, will prevent Ediff from grabbing
the mouse in many situations, usually after commands that may take more
time than usual. In other situation, Ediff will continue grabbing the mouse
and putting it where it believes is appropriate.  If the value is
@code{nil}, then mouse is entirely user's responsibility.
Try different settings and see which one is for you.
@end table


@node Notes on Heavy-duty Customization, , Miscellaneous, Customization
@section Notes on Heavy-duty Customization

Some users need to customize Ediff in rather sophisticated ways, which
requires different defaults for different kinds of files (e.g., SGML,
etc.).  Ediff supports this kind of customization in several ways.  First,
most customization variables are buffer-local. Those that aren't are
usually accessible from within Ediff Control Panel, so one can make them
local to the panel by calling make-local-variable from within
@code{ediff-startup-hook}. 

Second, the function @code{ediff-setup} accepts an optional sixth
argument which has the form @code{((@var{var-name-1} . @var{val-1})
(@var{var-name-2} . @var{val-2}) @dots{})}.  The function
@code{ediff-setup} sets the variables in the list to the respective
values, locally in the Ediff control buffer.  This is an easy way to
throw in custom variables (which usually should be buffer-local) that
can then be tested in various hooks.

Make sure the variable @code{ediff-job-name} and @code{ediff-word-mode} are set
properly in this case, as some things in Ediff depend on this.

Finally, if you want custom-tailored help messages, you can set the
variables @code{ediff-brief-help-message-function} and
@code{ediff-long-help-message-function}
to functions that return help strings.
@vindex ediff-startup-hook
@findex ediff-setup
@vindex ediff-job-name
@vindex ediff-word-mode
@vindex ediff-brief-help-message-function
@vindex ediff-long-help-message-function

When customizing Ediff, some other variables are useful, although they are
not user-definable. They are local to the Ediff control buffer, so this
buffer must be current when you access these variables. The control buffer
is accessible via the variable @code{ediff-control-buffer}, which is also
local to that buffer. It is usually used for checking if the current buffer
is also the control buffer.

Other variables of interest are:
@table @code
@item ediff-buffer-A
The first of the data buffers being compared.

@item ediff-buffer-B
The second of the data buffers being compared.

@item ediff-buffer-C
In three-way comparisons, this is the third buffer being compared.
In merging, this is the merge buffer.
In two-way comparison, this variable is nil.

@item ediff-window-A
The window displaying buffer A. If buffer A is not visible, this variable
is nil or it may be a dead window.

@item ediff-window-B
The window displaying buffer B.

@item ediff-window-C
The window displaying buffer C, if any.

@item ediff-control-frame
A dedicated frame displaying the control buffer, if it exists.
It is non-nil only if Ediff uses the multiframe display, i.e., when the
control buffer is in its own frame.
@end table

@node Credits, Index, Customization, Top
@chapter Credits

Ediff was written by Michael Kifer <kifer@@cs.sunysb.edu>. It was inspired
by emerge.el written by Dale R. Worley <drw@@math.mit.edu>.  An idea due to
Boris Goldowsky <boris@@cs.rochester.edu> made it possible to highlight
fine differences in Ediff buffers. Alastair Burt <burt@@dfki.uni-kl.de>
ported Ediff to XEmacs, and Eric Freudenthal <freudent@@jan.ultra.nyu.edu>
made it work with VC.

Many people provided help with bug reports, patches, and advice.
Without them, Ediff would not be nearly as useful as it is today.
Here is a full list of contributors (I hope I didn't miss anyone):

@example
Neal Becker (neal@@ctd.comsat.com),
Alastair Burt (burt@@dfki.uni-kl.de), Paul Bibilo (peb@@delcam.co.uk),
Kevin Broadey (KevinB@@bartley.demon.co.uk),
Harald Boegeholz (hwb@@machnix.mathematik.uni-stuttgart.de),
Bradley A. Bosch (brad@@lachman.com),
Michael D. Carney  (carney@@ltx-tr.com),
Jin S. Choi (jin@@atype.com),
Albert Dvornik (bert@@mit.edu),
Eric Eide (eeide@@asylum.cs.utah.edu),
Kevin Esler (esler@@ch.hp.com), Robert Estes (estes@@ece.ucdavis.edu), 
Xavier Fornari (xavier@@europe.cma.fr),
Eric Freudenthal (freudent@@jan.ultra.nyu.edu),
Job Ganzevoort (Job.Ganzevoort@@cwi.nl),
Boris Goldowsky (boris@@cs.rochester.edu),
Allan Gottlieb (gottlieb@@allan.ultra.nyu.edu), Xiaoli Huang (hxl@@epic.com),
Larry Gouge (larry@@itginc.com), Karl Heuer (kwzh@@gnu.ai.mit.edu),
(irvine@@lks.csi.com), (jaffe@@chipmunk.cita.utoronto.ca),
David Karr (dkarr@@nmo.gtegsc.com),
Norbert Kiesel (norbert@@i3.informatik.rwth-aachen.de),
Leigh L Klotz (klotz@@adoc.xerox.com), Fritz Knabe (Fritz.Knabe@@ecrc.de),
Heinz Knutzen (hk@@informatik.uni-kiel.d400.de),
Andrew Koenig (ark@@research.att.com),
Ken Laprade (laprade@@dw3f.ess.harris.com), Will C Lauer (wcl@@cadre.com),
Richard Levitte (levitte@@e.kth.se), Mike Long (mike.long@@analog.com),
Martin Maechler (maechler@@stat.math.ethz.ch),
Simon Marshall (Simon.Marshall@@mail.esrin.esa.it),
Richard Mlynarik (mly@@adoc.xerox.com),
Chris Murphy (murphycm@@sun.aston.ac.uk),
Erik Naggum (erik@@naggum.no),
Eyvind Ness (Eyvind.Ness@@hrp.no), Ray Nickson (nickson@@cs.uq.oz.au), 
David Petchey (petchey_david@@jpmorgan.com),
Benjamin Pierce (benjamin.pierce@@cl.cam.ac.uk),
Tibor Polgar (tlp00@@spg.amdahl.com),
David Prince (dave0d@@fegs.co.uk),
Paul Raines (raines@@slac.stanford.edu), 
C.S. Roberson (roberson@@aur.alcatel.com),
Kevin Rodgers (kevin.rodgers@@ihs.com),
Sandy Rutherford (sandy@@ibm550.sissa.it),
Heribert Schuetz (schuetz@@ecrc.de), Andy Scott (ascott@@pcocd2.intel.com),
Axel Seibert (axel@@tumbolia.ppp.informatik.uni-muenchen.de),
Richard Stallman (rms@@gnu.ai.mit.edu), 
Richard Stanton (stanton@@haas.berkeley.edu), 
Ake Stenhoff (etxaksf@@aom.ericsson.se), Stig (stig@@hackvan.com),
Peter Stout (Peter_Stout@@cs.cmu.edu), Chuck Thompson (cthomp@@cs.uiuc.edu),
Ray Tomlinson (tomlinso@@bbn.com),
Raymond Toy (toy@@rtp.ericsson.se),
Ben Wing (wing@@666.com),
Ilya Zakharevich (ilya@@math.ohio-state.edu),
Eli Zaretskii (eliz@@is.elta.co.il)
@end example

@node Index, , Credits, Top
@unnumbered Index
@printindex cp

@contents
@bye