root/branches/2.1/info/ediff-2

This is ../info/ediff, produced by makeinfo version 4.2 from ediff.texi.

INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Ediff: (ediff).       A visual interface for comparing and merging programs.
END-INFO-DIR-ENTRY

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

   Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software
Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being "A GNU Manual",
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled "GNU Free Documentation License" in
the Emacs manual.

   (a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development."

   This document is part of a collection distributed under the GNU Free
Documentation License.  If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.


File: ediff,  Node: Quick Help Customization,  Next: Window and Frame Configuration,  Prev: Hooks,  Up: Customization

Quick Help Customization
========================

   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 `?'.  The control window will then shrink to
just one line and a mode line, displaying a short help message.

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

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


File: ediff,  Node: Window and Frame Configuration,  Next: Selective Browsing,  Prev: Quick Help Customization,  Up: Customization

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 `|' 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 `C-l' (`ediff-recenter'),
`p' (`ediff-previous-difference'), `n' (`ediff-next-difference'), etc.

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

   The upshot 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):

`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
     `Ediff'.  Under X-windows, you can use this name to set up
     preferences in your `~/.Xdefaults', `~/.xrdb', or whatever X
     resource file is in use.  Usually this is preferable to changing
     `ediff-control-frame-parameters' directly.  For instance, you can
     specify in `~/.Xdefaults' the color of the control frame using the
     resource `Ediff*background'.

     In general, any X resource pertaining the control frame can be
     reached via the prefix `Ediff*'.

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

   The following variables can be used to adjust the location produced
by `ediff-make-frame-position' and for related customization.

`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.

`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.

`ediff-control-frame-upward-shift'
     Specifies the number of pixels for the upward shift of the control
     frame.

`ediff-prefer-iconified-control-frame'
     If this variable is `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 `t' and `ediff-prefer-long-help-message' to `nil'
     (*note Quick Help Customization::).  This behavior is useful only
     if icons are allowed to accept keybord input (which depend on the
     window manager and other factors).

   To make more creative changes in the way Ediff sets up windows, you
can rewrite the function `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.  The icon will usually accept all of the Ediff
commands, but will free up valuable real estate on your screen (this may
depend on your window manager, though).

   The following variable controls how windows are set up:

`ediff-window-setup-function'
     The multiframe setup is done by the
     `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 `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 `ediff-toggle-multiframe' using
     the Minibuffer of the Menubar.

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

   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., `Ediff Control Panel<3>'.)


File: ediff,  Node: Selective Browsing,  Next: Highlighting Difference Regions,  Prev: Window and Frame Configuration,  Up: Customization

Selective Browsing
==================

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

   The commands `#f' and `#h' let you do precisely this.

   Typing `#f' lets you specify regular expressions that match
difference regions you want to focus on.  We shall call these regular
expressions REGEXP-A, REGEXP-B and REGEXP-C.  Ediff will then start
stepping through only those difference regions where the region in
buffer A matches REGEXP-A and/or the region in buffer B matches
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 `\`' and `\'' to tie search to the
beginning or end of the difference regions.

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

   Typing `#f' and `#h' toggles selective browsing on and off.

   Note that selective browsing affects only `ediff-next-difference'
and `ediff-previous-difference', i.e., the commands `n'/<SPC> and
`p'/<DEL>.  `#f' and `#h' do not change the position of the point in
the buffers.  And you can still jump directly (using `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 `ediff-load-hook' which will do the following assignments:

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

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

   You can use the status command, `i', to find out whether selective
browsing is currently in effect.

   The regular expressions you specified are kept in the local variables
`ediff-regexp-focus-A', `ediff-regexp-focus-B', `ediff-regexp-focus-C',
`ediff-regexp-hide-A', `ediff-regexp-hide-B', `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 `.emacs'
using `setq-default'.

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

`ediff-ignore-similar-regions'
     If `t', causes Ediff to skip over "uninteresting" difference
     regions, which are the regions where the variants differ only in
     the amount of the white space and newlines.  This feature can be
     toggled on/off interactively, via the command `##'.

   *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 `@').

   *Reassurance:* If many such uninteresting regions appear in a row,
Ediff may take a long time to skip over them because it has to compute
fine differences of all intermediate regions.  This delay does not
indicate any problem.


File: ediff,  Node: Highlighting Difference Regions,  Next: Narrowing,  Prev: Selective Browsing,  Up: Customization

Highlighting Difference Regions
===============================

   The following variables control the way Ediff highlights difference
regions:

`ediff-before-flag-bol'
`ediff-after-flag-eol'
`ediff-before-flag-mol'
`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.

`ediff-current-diff-face-A'
`ediff-current-diff-face-B'
`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 `.emacs' or in `.Xdefaults'.  The X
     resource for Ediff is `Ediff', _not_ `emacs'.  Please refer to
     Emacs manual for the information on how to set X resources.

`ediff-fine-diff-face-A'
`ediff-fine-diff-face-B'
`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.

`ediff-even-diff-face-A'
`ediff-even-diff-face-B'
`ediff-even-diff-face-C'
`ediff-odd-diff-face-A'
`ediff-odd-diff-face-B'
`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.

`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 `t' to make sure that Ediff uses faces to highlight differences.

`ediff-highlight-all-diffs'
     Indicates whether--on a windowind display--Ediff should highlight
     differences using inserted strings (as on text-only terminals) 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 `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 `ediff-highlight-all-diffs' to `nil'.  Type `h' to restore
     highlighting for 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.

If you want to change the default settings for `ediff-force-faces' and
`ediff-highlight-all-diffs', you must do it *before* Ediff is loaded.

   You can also change the defaults for the faces used to highlight the
difference regions.  There are two ways to do this.  The simplest and
the preferred way is to use the customization widget accessible from the
menubar.  Ediff's customization group is located under "Tools", which in
turn is under "Programming".  The faces that are used to highlight
difference regions are located in the "Highlighting" subgroup of the
Ediff customization group.

   The second, much more arcane, method to change default faces is to
include some Lisp code in `~/.emacs'.  For instance,

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

would use the pre-defined fase `bold-italic' to highlight the current
difference region in buffer A (this face is not a good choice, by the
way).

   If you are unhappy with just _some_ of the aspects of the default
faces, you can modify them when Ediff is being loaded using
`ediff-load-hook'.  For instance:

     (add-hook 'ediff-load-hook
               (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)))

   *Note:* To set Ediff's faces, use only `copy-face' or
`set/make-face-...' as shown above. Emacs' low-level face-manipulation
functions should be avoided.


File: ediff,  Node: Narrowing,  Next: Refinement of Difference Regions,  Prev: Highlighting Difference Regions,  Up: Customization

Narrowing
=========

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

   Calling `ediff-regions-linewise' or `ediff-windows-linewise', or the
corresponding `-wordwise' commands, narrows the variants to the
particular 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 `%' command.

   These two variables control this narrowing behavior:

`ediff-start-narrowed'
     If `t', Ediff narrows the display to the appropriate range when it
     is invoked with an `ediff-regions...' or `ediff-windows...'
     command.  If `nil', these commands do not automatically narrow,
     but you can still toggle narrowing on and off by typing `%'.

`ediff-quit-widened'
     Controls whether on quitting Ediff should restore the accessible
     range that existed before the current invocation.


File: ediff,  Node: Refinement of Difference Regions,  Next: Patch and Diff Programs,  Prev: Narrowing,  Up: Customization

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.

`ediff-auto-refine'
     This variable controls whether fine differences within regions are
     highlighted automatically ("auto-refining").  The default is yes
     (`on').

     On a slow machine, automatic refinement may be painful.  In that
     case, you can turn auto-refining on or off interactively by typing
     `@'.  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 `*' computes and displays fine differences for the current
     difference region, regardless of whether auto-refining is turned
     on.

`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 `*'.

`ediff-forward-word-function'
     This variable controls how fine differences are computed.  The
     value must be a Lisp function that determines how the current
     difference region should be split into words.

     Fine differences are computed by first splitting the current
     difference region into words and then passing the result to
     `ediff-diff-program'.  For the default forward word function
     (which is `ediff-forward-word'), a word is a string consisting of
     letters, `-', or `_'; 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:
     `ediff-word-1', ..., `ediff-word-4'.  See the on-line
     documentation for these variables and for the function
     `ediff-forward-word' for an explanation of how to modify these
     variables.

   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 `*' with a negative
prefix argument.  This unhighlights fine differences for the current
region.

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


File: ediff,  Node: Patch and Diff Programs,  Next: Merging and diff3,  Prev: Refinement of Difference Regions,  Up: Customization

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):

`ediff-diff-program'
`ediff-diff3-program'
     These variables specify the programs to use to produce differences
     and do patching.

`ediff-diff-options'
`ediff-diff3-options'
     These variables specify the options to pass to the above utilities.

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

`ediff-coding-system-for-read'
     This variable specifies the coding system to use when reading the
     output that the programs `diff3' and `diff' send to Emacs. The
     default is `raw-text', and this should work fine on GNU, Unix, and
     in most cases under Windows NT/95/98/2000.  There are `diff'
     programs for which the default option doesn't work under Windows.
     In such cases, `raw-text-dos' might work. If not, you will have to
     experiment with other coding systems or use GNU diff.

`ediff-patch-program'
     The program to use to apply patches.  Since there are certain
     incompatibilities between the different versions of the patch
     program, the best way to stay out of trouble is to use a
     GNU-compatible version.  Otherwise, you may have to tune the
     values of the variables `ediff-patch-options',
     `ediff-backup-specs', and `ediff-backup-extension' as described
     below.

`ediff-patch-options'
     Options to pass to `ediff-patch-program'.

     Note: the `-b' and `-z' options should be specified in
     `ediff-backup-specs', not in `ediff-patch-options'.

     It is recommended to pass the `-f' option to the patch program, so
     it won't ask questions.  However, some implementations don't
     accept this option, in which case the default value of this
     variable should be changed.

`ediff-backup-extension'
     Backup extension used by the patch program.  Must be specified,
     even if `ediff-backup-specs' is given.

`ediff-backup-specs'
     Backup directives to pass to the patch program.  Ediff requires
     that the old version of the file (before applying the patch) is
     saved in a file named `the-patch-file.extension'.  Usually
     `extension' is `.orig', but this can be changed by the user, and
     may also be system-dependent.  Therefore, Ediff needs to know the
     backup extension used by the patch program.

     Some versions of the patch program let the user specify `-b
     backup-extension'.  Other versions only permit `-b', which
     (usually) assumes the extension `.orig'.  Yet others force you to
     use `-z<backup-extension>'.

     Note that both `ediff-backup-extension' and `ediff-backup-specs'
     must be properly set.  If your patch program takes the option
     `-b', but not `-b extension', the variable
     `ediff-backup-extension' must still be set so Ediff will know
     which extension to use.

`ediff-custom-diff-program'
`ediff-custom-diff-options'
     Because Ediff limits the options you may want to pass to the `diff'
     program, it partially makes up for this drawback by letting you
     save the output from `diff' in your preferred format, which is
     specified via the above two variables.

     The output generated by `ediff-custom-diff-program' (which doesn't
     even have to be a standard-style `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 `-c' option in
     `ediff-diff-program', you would have to run `diff -c' separately
     just to produce the list of differences.  Fortunately,
     `ediff-custom-diff-program' and `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 `D'.

`ediff-patch-default-directory'
     Specifies the default directory to look for patches.

*Warning:* Ediff does not support the output format of VMS `diff'.
Instead, make sure you are using some implementation of POSIX `diff',
such as `gnudiff'.


File: ediff,  Node: Merging and diff3,  Next: Support for Version Control,  Prev: Patch and Diff Programs,  Up: Customization

Merging and diff3
=================

   Ediff supports three-way comparison via the functions `ediff-files3'
and `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 `[=diff(C)]' and the mode line of buffer
C will display `[=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.

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

     <<<<<<< variant A
     the difference region from buffer A
     >>>>>>> variant B
     the difference region from buffer B
     ####### Ancestor
     the difference region from the ancestor buffer, if available
     ======= end

   The above is the default template for the combined region. The user
can customize this template using the variable
`ediff-combination-pattern'.

   The variable `ediff-combination-pattern' specifies the template that
determines how the combined merged region looks like.  The template is
represented as a list of the form `(STRING1 Symbol1 STRING2 Symbol2
STRING3 Symbol3 STRING4)'. The symbols here must be atoms of the form
`A', `B', or `Ancestor'. They determine the order in which the
corresponding difference regions (from buffers A, B, and the ancestor
buffer) are displayed in the merged region of buffer C.  The strings in
the template determine the text that separates the aforesaid regions.
The default template is

     ("<<<<<<< variant A" A ">>>>>>> variant B" B
        "####### Ancestor" Ancestor "======= end")

(this is one long line) and the corresponding combined region is shown
above. The order in which the regions are shown (and the separator
strings) can be changed by changing the above template. It is even
possible to add or delete region specifiers in this template (although
the only possibly useful such modification seems to be the deletion of
the ancestor).

   In addition to the state of the difference, 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 `ediff-default-variant' was set to `default-A') then `[=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 `[=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 `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 the state of merge and state of difference
indicators, 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 _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 _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
`/' to the control window.  (Type `C-l' to hide it again.)

   Note that the state-of-difference indicators `=diff(A)' and
`=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 `=diff(B) prefer(B)' and you
copy a difference region from buffer A to buffer C then `=diff(B)' will
change to `diff-A' and the mode line will display `=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 `r'.

   Ediff never changes the state-of-merge indicator, except in response
to the `!' 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, `a', `b', `r', `+'.

   The `!' 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 `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.

   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 `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
`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 `s'.  This change is temporary, until Ediff finds a reason to
redraw the screen.  Typing `s' again restores the original window size.

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

   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 `ediff-show-clashes-only' to non-`nil'.

   You can toggle this feature interactively by typing `$$'.

   Note that this variable affects only the show next/previous
difference commands.  You can still jump directly to any difference
region directly using the command `j' (with a prefix argument
specifying the difference number).

   The variable `ediff-autostore-merges' controls what happens to the
merge buffer when Ediff quits.  If the value is `nil', nothing is done
to the merge buffer--it will be the user's responsibility to save it.
If the value is `t', the user will be asked where to save the buffer
and whether to delete it afterwards.  It the value is neither `nil' nor
`t', the merge buffer is saved _only_ if this merge session was invoked
from a group of related Ediff session, such as those that result from
`ediff-merge-directories', `ediff-merge-directory-revisions', etc.
*Note Session Groups::.  This behavior is implemented in the function
`ediff-maybe-save-and-delete-merge', which is a hook in
`ediff-quit-merge-hook'.  The user can supply a different hook, if
necessary.

   The variable `ediff-autostore-merges' is buffer-local, so it can be
set in a per-buffer manner.  Therefore, use `setq-default' to globally
change this variable.

   When merge buffers are saved automatically as directed by
`ediff-autostore-merges', Ediff attaches a prefix to each file, as
specified by the variable `ediff-merge-filename-prefix'. The default is
`merge_', but this can be changed by the user.


File: ediff,  Node: Support for Version Control,  Next: Customizing the Mode Line,  Prev: Merging and diff3,  Up: Customization

Support for Version Control
===========================

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

`ediff-version-control-package'
     A symbol.  The default is `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.,
          (setq ediff-version-control-package 'rcs)

     Apart from the standard `vc.el', Ediff supports three other
     interfaces to version control: `rcs.el', `pcl-cvs.el' (recently
     renamed pcvs.el), and `generic-sc.el'.  The package `rcs.el' is
     written by Sebastian Kremer <sk@thp.Uni-Koeln.DE> and is available
     as
          `ftp.cs.buffalo.edu:pub/Emacs/rcs.tar.Z'
          `ftp.uni-koeln.de:/pub/gnu/emacs/rcs.tar.Z'

   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 `pcl-cvs.el', Ediff can also be invoked via the function
`run-ediff-from-cvs-buffer'--see the documentation string for this
function.


File: ediff,  Node: Customizing the Mode Line,  Next: Miscellaneous,  Prev: Support for Version Control,  Up: Customization

Customizing the Mode Line
=========================

   When Ediff is running, the mode line of `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 (`A:', `B:', or `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 `uniquify.el' and `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 `ediff-prepare-buffer-hook' to modify the mode
line.


File: ediff,  Node: Miscellaneous,  Next: Notes on Heavy-duty Customization,  Prev: Customizing the Mode Line,  Up: Customization

Miscellaneous
=============

   Here are a few other variables for customizing Ediff:

`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 (`split-window-vertically', but you can set it to
     `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
     `~'.

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

`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
     `ediff-make-wide-display-function' for details.  It is also
     recommended to look into the source of the default function
     `ediff-make-wide-display'.

     You can toggle wide/regular display by typing `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.

`ediff-use-last-dir'
     Controls the way Ediff presents the default directory when it
     prompts the user for files to compare.  If `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.

`ediff-no-emacs-help-in-control-buffer'
     If `t', makes `C-h' behave like the <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 `C-h' and is positioned more
     conveniently than the <DEL> key.

`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.

`ediff-make-buffers-readonly-at-startup nil'
     If t, all variant buffers are made read-only at Ediff startup.

`ediff-keep-variants'
     The default is `t', meaning that the buffers being compared or
     merged will be preserved when Ediff quits.  Setting this to `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 (`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 `t' if it is
     invoked via one of the "buffer" jobs, such as `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 `ediff-cleanup-hook', one can make Ediff delete the variants
     unconditionally (e.g., by making `ediff-janitor' into one of these
     hooks).

`ediff-grab-mouse'
     Default is `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 `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 `nil', then
     mouse is entirely user's responsibility.  Try different settings
     and see which one is for you.


File: ediff,  Node: Notes on Heavy-duty Customization,  Prev: Miscellaneous,  Up: Customization

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 `ediff-startup-hook'.

   Second, the function `ediff-setup' accepts an optional sixth
argument which has the form `((VAR-NAME-1 . VAL-1) (VAR-NAME-2 . VAL-2)
...)'.  The function `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 `ediff-job-name' and `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 `ediff-brief-help-message-function' and
`ediff-long-help-message-function' to functions that return help
strings.

   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
`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:
`ediff-buffer-A'
     The first of the data buffers being compared.

`ediff-buffer-B'
     The second of the data buffers being compared.

`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.

`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.

`ediff-window-B'
     The window displaying buffer B.

`ediff-window-C'
     The window displaying buffer C, if any.

`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.


File: ediff,  Node: Credits,  Next: Index,  Prev: Customization,  Up: Top

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, Eric Freudenthal
<freudent@jan.ultra.nyu.edu> made it work with VC, Marc Paquette
<marcpa@cam.org> wrote the toolbar support package for Ediff, and
Hrvoje Niksic <hniksic@xemacs.org> adapted it to the Emacs
customization package.

   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):

     Adrian Aichner (aichner@ecf.teradyne.com),
     Steve Baur (steve@xemacs.org),
     Neal Becker (neal@ctd.comsat.com),
     E. Jay Berkenbilt (ejb@ql.org),
     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),
     Scott Cummings (cummings@adc.com),
     Albert Dvornik (bert@mit.edu),
     Eric Eide (eeide@asylum.cs.utah.edu),
     Paul Eggert (eggert@twinsun.com),
     Urban Engberg (ue@cci.dk),
     Kevin Esler (esler@ch.hp.com),
     Robert Estes (estes@ece.ucdavis.edu),
     Jay Finger (jayf@microsoft.com),
     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),
     Aaron Gross (aaron@bfr.co.il),
     Thorbjoern Hansen (thorbjoern.hansen@mchp.siemens.de),
     Xiaoli Huang (hxl@epic.com),
     Andreas Jaeger (aj@suse.de),
     Lars Magne Ingebrigtsen (larsi@ifi.uio.no),
     Larry Gouge (larry@itginc.com),
     Karl Heuer (kwzh@gnu.org),
     (irvine@lks.csi.com),
     (jaffe@chipmunk.cita.utoronto.ca),
     David Karr (dkarr@nmo.gtegsc.com),
     Norbert Kiesel (norbert@i3.informatik.rwth-aachen.de),
     Sam Steingold (sds@goems.com),
     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),
     Hannu Koivisto (azure@iki.fi),
     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@gnu.org),
     Paul C. Meuse (pmeuse@delcomsys.com),
     Richard Mlynarik (mly@adoc.xerox.com),
     Stefan Monnier (monnier@cs.yale.edu),
     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),
     Francois Pinard (pinard@iro.umontreal.ca),
     Tibor Polgar (tlp00@spg.amdahl.com),
     David Prince (dave0d@fegs.co.uk),
     Paul Raines (raines@slac.stanford.edu),
     Bill Richter (richter@math.nwu.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),
     Vin Shelton (acs@xemacs.org),
     Scott O. Sherman (Scott.Sherman@mci.com),
     Richard Stallman (rms@gnu.org),
     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),
     Jan Vroonhof (vroonhof@math.ethz.ch),
     Colin Walters (walters@cis.ohio-state.edu),
     Philippe Waroquiers (philippe.waroquiers@eurocontrol.be),
     Klaus Weber (gizmo@zork.north.de),