root/trunk/man/ediff.texi

\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.
@comment @setfilename ediff
@comment @setfilename ediff.info
@setfilename ../info/ediff

@settitle Ediff User's Manual
@synindex vr cp
@synindex fn cp
@synindex pg cp
@synindex ky cp

@iftex
@finalout
@end iftex
@c      @smallbook
@comment %**end of header (This is for running Texinfo on a region.)

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

Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 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.
@end quotation
@end copying

@dircategory Emacs
@direntry
* Ediff: (ediff).       A visual interface for comparing and merging programs.
@end direntry

@titlepage
@title Ediff User's Manual
@sp 4
@subtitle Ediff version 2.81.1
@sp 1
@subtitle April 2007
@sp 5
@author Michael Kifer
@page

@vskip 0pt plus 1filll
@insertcopying
@end titlepage


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


@menu
* Introduction::                About Ediff.
* Major Entry Points::          How to use Ediff.
* Session Commands::            Ediff commands used within a session.
* 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.
* GNU Free Documentation License:: The license for this documentation.
* 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
(which are called @samp{variants} for our purposes).  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 through
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 variants, 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
format or GNU unified format.  All other patches are treated as 1-file
patches.  Ediff is [hopefully] using the same algorithm as @code{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 of Ediff's
functions are adaptations from Emerge.  Although Ediff subsumes and greatly
extends Emerge, much of the functionality in Ediff is influenced by Emerge.
The architecture and the interface are, of course, drastically different.

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

When Ediff starts up, it displays a small control window, which accepts the
Ediff commands, and two or three windows displaying the files to be compared
or merged. The control window can be in its own small frame or it can be
part of a bigger frame that displays other buffers. In any case, it is
important that the control window be active (i.e., be the one receiving the
keystrokes) when you use Ediff. You can switch to other Emacs buffers at
will and even edit the files currently being compared with Ediff and then
switch back to Ediff at any time by activating the appropriate Emacs windows.

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-backup
@findex ediff-backup
Compare a file with its backup. If there are several numerical backups, use
the latest. If the file is itself a backup, then compare it with its
original.

@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.  The regions can come from the same buffer
and they can even overlap.  You will be asked to specify the buffers that
contain the regions, which you want to compare. For each buffer, you will
also be asked to mark the regions to be compared. Pay attention to the
messages that appear in the minibuffer.

@item ediff-regions-linewise
@findex ediff-regions-linewise
Similar to @code{ediff-windows-linewise}, but compares the regions
line-by-line. See @code{ediff-windows-linewise} for more details.

@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 or multiple files, then compare.  If the patch applies to just
one file, Ediff will invoke a regular comparison session.  If it is a
multi-file patch, then a session group interface will be used and the user
will be able to patch the files selectively.  @xref{Session Groups}, for
more details.

Since the patch might be in a buffer or a file, you will be asked which is
the case. To avoid this extra prompt, you can invoke this command with a
prefix argument.  With an odd prefix argument, Ediff assumes the patch
is in a file; with an even argument, a buffer is assumed.

Note that @code{ediff-patch-file} will actually use the @code{patch}
utility to change the original files on disk.  This is not that
dangerous, since you will always have the original contents of the file
saved in another file that has the extension @file{.orig}.
Furthermore, if the file is under version control, then you can always back
out to one of the previous versions (see the section on Version Control in
the Emacs manual).

@code{ediff-patch-file} is careful about versions control: if the file
to be patched is checked in, then Ediff will offer to check it out, because
failing to do so may result in the loss of the changes when the file is
checked out the next time.

If you don't intend to modify the file via the patch and just want to see
what the patch is all about (and decide later), then
@code{ediff-patch-buffer} might be a better choice.

@item ediff-patch-buffer
@itemx epatch-buffer
@findex ediff-patch-buffer
@findex epatch-buffer
Patch a buffer, then compare.  The buffer being patched and the file visited
by that buffer (if any) is @emph{not} modified.  The result of the patch
appears in some other buffer that has the name ending with @emph{_patched}.

This function would refuse to apply a multifile patch to a buffer.  Use
@code{ediff-patch-file} for that (and when you want the original file to be
modified by the @code{patch} utility).

Since the patch might be in a buffer or a file, you will be asked which is
the case. To avoid this extra prompt, you can invoke this command with a
prefix argument.  With an odd prefix argument, Ediff assumes the patch
is in a file; with an even argument, a buffer is assumed.

@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.
 If a pair of files doesn't have an ancestor in the ancestor-directory, you
 will still be able to merge them without the ancestor.

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

@item ediff-documentation
@findex ediff-documentation
Brings up this manual.

@item ediff-show-registry
@itemx eregistry
Brings up Ediff session registry.  This feature enables you to quickly find
and restart active Ediff sessions.
@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, the user is prompted for all the
necessary information---typically the files or buffers to compare, merge, 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} or @code{diff3} programs
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 @code{diff} program.  The
total number of difference regions and the current difference number are
always displayed in the mode line of the control window.

Since @code{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 commands @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.  The commands @code{ediff-windows-wordwise} and
@code{ediff-regions-wordwise} are intended for relatively small segments
of buffers (e.g., up to 100 lines, depending on the speed of your machine),
as they perform comparison on the basis of words rather than lines.
(Word-wise comparison of large chunks of text can be slow.)

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 the appropriate
files/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-revision} 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 Session Commands, Registry of Ediff Sessions, Major Entry Points, Top
@chapter Session 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.  The Quick Help commands are detailed below.

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 variant A
to variant B.  Likewise, 4 followed by @kbd{ra} restores the 4th difference
region in buffer A (if it was previously written over via the command
@kbd{a}).

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

Without the prefix argument, all commands operate on the currently
selected difference region.  You can make any difference region
current using the various commands explained below.

For some commands, the actual value of the prefix argument is
immaterial.  However, if supplied, the prefix argument may modify the
command (see @kbd{ga}, @kbd{gb}, and @kbd{gc}).

@menu
* Quick Help Commands::             Frequently used commands.
* Other Session Commands::          Commands that are not bound to keys.
@end menu

@node Quick Help Commands,Other Session Commands,,Session Commands
@section Quick Help Commands

@table @kbd
@item ?
@kindex ?
Toggles the Ediff Quick Help window ON and OFF.
@item G
@kindex G
Prepares a mail buffer for sending a praise or a curse to the Ediff maintainer.

@item E
@kindex E
Brings up the top node of this manual, where you can find further
information on the various Ediff functions and advanced issues, such as
customization, session groups, etc.

@item v
@kindex v
Scrolls up buffers A and B (and buffer C where appropriate) in a
coordinated fashion.
@item V
@kindex V
Scrolls the buffers down.

@item <
@kindex <
Scrolls the buffers to the left simultaneously.
@item >
@kindex >
Scrolls buffers to the right.

@item wd
@kindex wd
Saves the output from the diff utility, for further reference.

With prefix argument, saves the plain output from @code{diff} (see
@code{ediff-diff-program} and @code{ediff-diff-options}).  Without the
argument, it saves customized @code{diff} output (see
@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options}), if
it is available.

@item wa
@kindex wa
Saves buffer A, if it was modified.
@item wb
@kindex wb
Saves buffer B, if it was modified.
@item wc
@kindex wc
Saves buffer C, if it was modified (if you are in a session that
compares three files simultaneously).

@item a
@kindex a
@emph{In comparison sessions:}
Copies the current difference region (or the region specified as the prefix
to this command) from buffer A to buffer B.
Ediff saves the old contents of buffer B's region; it can
be restored via the command @kbd{rb}, which see.

@emph{In merge sessions:}
Copies the current difference region (or the region specified as the prefix
to this command) from buffer A to the merge buffer.  The old contents of
this region in buffer C can be restored via the command @kbd{r}.

@item b
@kindex b
Works similarly, but copies the current difference region from buffer B to
buffer A (in @emph{comparison sessions}) or the merge buffer (in
@emph{merge sessions}).

Ediff saves the old contents of the difference region copied over; it can
be reinstated via the command @kbd{ra} in comparison sessions and
@kbd{r} in merge sessions.

@item ab
@kindex ab
Copies the current difference region (or the region specified as the prefix
to this command) from buffer A to buffer B.  This (and the next five)
command is enabled only in sessions that compare three files
simultaneously.  The old region in buffer B is saved and can be restored
via the command @kbd{rb}.
@item ac
@kindex ac
Copies the difference region from buffer A to buffer C.
The old region in buffer C is saved and can be restored via the command
@kbd{rc}.
@item ba
@kindex ba
Copies the difference region from buffer B to buffer A.
The old region in buffer A is saved and can be restored via the command
@kbd{ra}.
@item bc
@kindex bc
Copies the difference region from buffer B to buffer C.
The command @kbd{rc} undoes this.
@item ca
@kindex ca
Copies the difference region from buffer C to buffer A.
The command @kbd{ra} undoes this.
@item cb
@kindex cb
Copies the difference region from buffer C to buffer B.
The command @kbd{rb} undoes this.

@item p
@itemx DEL
@kindex p
@kindex DEL
Makes the previous difference region current.
@item n
@itemx SPC
@kindex n
@kindex SPC
Makes the next difference region current.

@item j
@itemx -j
@itemx Nj
@kindex j
Makes the very first difference region current.

@kbd{-j} makes the last region current.  Typing a number, N, and then `j'
makes the difference region N current.  Typing -N (a negative number) then
`j' makes current the region Last - N.

@item ga
@kindex ga
Makes current the difference region closest to the position of the point in
buffer A.

However, with a prefix argument, Ediff would position all variants
around the area indicated by the current point in buffer A: if
the point is inside a difference region, then the variants will be
positioned at this difference region.  If the point is not in any difference
region, then it is in an area where all variants agree with each other.  In
this case, the variants will be positioned so that each would display this
area (of agreement).
@item gb
@kindex gb
Makes current the difference region closest to the position of the point in
buffer B.

With a prefix argument, behaves like @kbd{ga}, but with respect to buffer B.
@item gc
@kindex gc
@emph{In merge sessions:}
makes current the difference region closest to the point in the merge buffer.

@emph{In 3-file comparison sessions:}
makes current the region closest to the point in buffer C.

With a prefix argument, behaves like @kbd{ga}, but with respect to buffer C.

@item !
@kindex !
Recomputes the difference regions, bringing them up to date.  This is often
needed because it is common to do all sorts of editing during Ediff
sessions, so after a while, the highlighted difference regions may no
longer reflect the actual differences among the buffers.

@item *
@kindex *
Forces refinement of the current difference region, which highlights the exact
words of disagreement among the buffers.  With a negative prefix argument,
unhighlights the current region.

Forceful refinement may be needed if Ediff encounters a difference region
that is larger than @code{ediff-auto-refine-limit}.  In this situation,
Ediff doesn't do automatic refinement in order to improve response time.
(Ediff doesn't auto-refine on dumb terminals as well, but @kbd{*} still
works there.  However, the only useful piece of information it can tell you
is whether or not the difference regions disagree only in the amount of
white space.)

This command is also useful when the highlighted fine differences are
no longer current, due to user editing.

@item m
@kindex m
Displays the current Ediff session in a frame as wide as the physical
display.  This is useful when comparing files side-by-side.  Typing `m' again
restores the original size of the frame.

@item |
@kindex |
Toggles the horizontal/vertical split of the Ediff display.  Horizontal
split is convenient when it is possible to compare files
side-by-side.  If the frame in which files are displayed is too narrow
and lines are cut off, typing @kbd{m} may help some.

@item @@
@kindex @@
Toggles auto-refinement of difference regions (i.e., automatic highlighting
of the exact words that differ among the variants).  Auto-refinement is
turned off on devices where Emacs doesn't support highlighting.

On slow machines, it may be advantageous to turn auto-refinement off.  The
user can always forcefully refine specific difference regions by typing
@kbd{*}.

@item h
@kindex h
Cycles between full highlighting, the mode where fine differences are not
highlighted (but computed), and the mode where highlighting is done with
@acronym{ASCII} strings.  The latter is not really recommended, unless on a dumb TTY.

@item r
@kindex r
Restores the old contents of the region in the merge buffer.
(If you copied a difference region from buffer A or B into the merge buffer
using the commands @kbd{a} or @kbd{b}, Ediff saves the old contents of the
region in case you change your mind.)

This command is enabled in merge sessions only.

@item ra
@kindex ra
Restores the old contents of the current difference region in buffer A,
which was previously saved when the user invoked one of these commands:
@kbd{b}, @kbd{ba}, @kbd{ca}, which see.  This command is enabled in
comparison sessions only.
@item rb
@kindex rb
Restores the old contents of the current difference region in buffer B,
which was previously saved when the user invoked one of these commands:
@kbd{a}, @kbd{ab}, @kbd{cb}, which see.  This command is enabled in
comparison sessions only.
@item rc
@kindex rc
Restores the old contents of the current difference region in buffer C,
which was previously saved when the user invoked one of these commands:
@kbd{ac}, @kbd{bc}, which see.  This command is enabled in 3-file
comparison sessions only.

@item ##
@kindex ##
Tell Ediff to skip over regions that disagree among themselves only in the
amount of white space and line breaks.

Even though such regions will be skipped over, you can still jump to any
one of them by typing the region number and then `j'.  Typing @kbd{##}
again puts Ediff back in the original state.

@item #c
@kindex #c
@vindex ediff-ignore-case-option
@vindex ediff-ignore-case-option3
@vindex ediff-ignore-case
Toggle case sensitivity in the diff program. All diffs are recomputed.
Case sensitivity is controlled by the variables
@code{ediff-ignore-case-option}, @code{ediff-ignore-case-option3},
and @code{ediff-ignore-case}, which are explained elsewhere.

@item #h
@itemx #f
@kindex #f
@kindex #h
Ediff works hard to ameliorate the effects of boredom in the workplace...

Quite often differences are due to identical replacements (e.g., the word
`foo' is replaced with the word `bar' everywhere).  If the number of regions
with such boring differences exceeds your tolerance threshold, you may be
tempted to tell Ediff to skip these regions altogether (you will still be able
to jump to them via the command @kbd{j}).  The above commands, @kbd{#h}
and @kbd{#f}, may well save your day!

@kbd{#h} prompts you to specify regular expressions for each
variant.  Difference regions where each variant's region matches the
corresponding regular expression will be skipped from then on.  (You can
also tell Ediff to skip regions where at least one variant matches its
regular expression.)

@kbd{#f} does dual job: it focuses on regions that match the corresponding
regular expressions.  All other regions will be skipped
over.  @xref{Selective Browsing}, for more.

@item A
@kindex A
Toggles the read-only property in buffer A.
If file A is under version control and is checked in, it is checked out
(with your permission).
@item B
@kindex B
Toggles the read-only property in buffer B.
If file B is under version control and is checked in, it is checked out.
@item C
@kindex C
Toggles the read-only property in buffer C (in 3-file comparison sessions).
If file C is under version control and is checked in, it is checked out.

@item ~
@kindex ~
Swaps the windows where buffers A and B are displayed.  If you are comparing
three buffers at once, then this command would rotate the windows among
buffers A, B, and C.

@item i
@kindex i
Displays all kinds of useful data about the current Ediff session.
@item D
@kindex D
Runs @code{ediff-custom-diff-program} on the variants and displays the
buffer containing the output.  This is useful when you must send the output
to your Mom.

With a prefix argument, displays the plain @code{diff} output.
@xref{Patch and Diff Programs}, for details.

@item R
@kindex R
Displays a list of currently active Ediff sessions---the Ediff Registry.
You can then restart any of these sessions by either clicking on a session
record or by putting the cursor over it and then typing the return key.

(Some poor souls leave so many active Ediff sessions around that they loose
track of them completely...  The `R' command is designed to save these
people from the recently discovered Ediff Proficiency Syndrome.)

Typing @kbd{R} brings up Ediff Registry only if it is typed into an Ediff
Control Panel.  If you don't have a control panel handy, type this in the
minibuffer: @kbd{M-x eregistry}.  @xref{Registry of Ediff Sessions}.

@item M
@kindex M
Shows the session group buffer that invoked the current Ediff session.
@xref{Session Groups}, for more information on session groups.

@item z
@kindex z
Suspends the current Ediff session.  (If you develop a condition known as
Repetitive Ediff Injury---a serious but curable illness---you must change
your current activity.  This command tries hard to hide all Ediff-related
buffers.)

The easiest way to resume a suspended Ediff session is through the registry
of active sessions.  @xref{Registry of Ediff Sessions}, for details.
@item q
@kindex q
Terminates this Ediff session.  With a prefix argument (e.g.,@kbd{1q}), asks
if you also want to delete the buffers of the variants.
Modified files and the results of merges are never deleted.

@item %
@kindex %
Toggles narrowing in Ediff buffers.  Ediff buffers may be narrowed if you
are comparing only parts of these buffers via the commands
@code{ediff-windows-*} and @code{ediff-regions-*}, which see.

@item C-l
@kindex C-l
Restores the usual Ediff window setup.  This is the quickest way to resume
an Ediff session, but it works only if the control panel of that session is
visible.

@item $$
@kindex $$
While merging with an ancestor file, Ediff is determined to reduce user's
wear and tear by saving him and her much of unproductive, repetitive
typing.  If it notices that, say, file A's difference region is identical to
the same difference region in the ancestor file, then the merge buffer will
automatically get the difference region taken from buffer B.  The rationale
is that this difference region in buffer A is as old as that in the
ancestor buffer, so the contents of that region in buffer B represents real
change.

You may want to ignore such `obvious' merges and concentrate on difference
regions where both files `clash' with the ancestor, since this means that
two different people have been changing this region independently and they
had different ideas on how to do this.

The above command does this for you by skipping the regions where only one
of the variants clashes with the ancestor but the other variant agrees with
it.  Typing @kbd{$$} again undoes this setting.

@item $*
@kindex $*
When merging files with large number of differences, it is sometimes
convenient to be able to skip the difference regions for which you already
decided which variant is most appropriate. Typing @kbd{$*} will accomplish
precisely this.

To be more precise, this toggles the check for whether the current merge is
identical to its default setting, as originally decided by Ediff.  For
instance, if Ediff is merging according to the `combined' policy, then the
merge region is skipped over if it is different from the combination of the
regions in buffers A and B.  (Warning: swapping buffers A and B will confuse
things in this respect.)  If the merge region is marked as `prefer-A' then
this region will be skipped if it differs from the current difference
region in buffer A, etc.

@item /
@kindex /
Displays the ancestor file during merges.
@item &
@kindex &
In some situations, such as when one of the files agrees with the ancestor file
on a difference region and the other doesn't, Ediff knows what to do: it copies
the current difference region from the second buffer into the merge buffer.

In other cases, the right course of action is not that clearcut, and Ediff
would use a default action.  The above command changes the default action.
The default action can be @samp{default-A} (choose the region from buffer
A), @samp{default-B} (choose the region from buffer B), or @samp{combined}
(combine the regions from the two buffers).
@xref{Merging and diff3}, for further details.

The command @kbd{&} also affects the regions in the merge buffers that have
@samp{default-A}, @samp{default-B}, or @samp{combined} status, provided
they weren't changed with respect to the original.  For instance, if such a
region has the status @samp{default-A} then changing the default action to
@samp{default-B} will also replace this merge-buffer's region with the
corresponding region from buffer B.

@item s
@kindex s
Causes the merge window shrink to its minimum size, thereby exposing as much
of the variant buffers as possible.  Typing `s' again restores
the original size of that window.

With a positive prefix argument, this command enlarges the merge window.
E.g., @kbd{4s} increases the size of the window by about 4 lines, if
possible.  With a negative numeric argument, the size of the merge window
shrinks by that many lines, if possible.  Thus, @kbd{-s} shrinks the window
by about 1 line and @kbd{-3s} by about 3 lines.

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.  However, redisplaying (@kbd{C-l}) or jumping
to another difference does not affect window C's size.

The split between the merge window and the variant windows is controlled by
the variable @code{ediff-merge-window-share}, which see.

@item +
@kindex +
Combines the difference regions from buffers A and B and copies the
result into the merge buffer.  @xref{Merging and diff3}, and the
variables @code{ediff-combine-diffs} and @code{ediff-combination-pattern}.


@item =
@kindex =
You may run into situations when a large chunk of text in one file has been
edited and then moved to a different place in another file.  In such a case,
these two chunks of text are unlikely to belong to the same difference
region, so the refinement feature of Ediff will not be able to tell you
what exactly differs inside these chunks.  Since eyeballing large pieces of
text is contrary to human nature, Ediff has a special command to help
reduce the risk of developing a cataract.

In other situations, the currently highlighted region might be big and you
might want to reconcile of them interactively.

All of this can be done with the above command, @kbd{=}, which
compares regions within Ediff buffers.  Typing @kbd{=} creates a
child Ediff session for comparing regions in buffers A, B, or
C as follows.

First, you will be asked whether you want to compare the fine differences
between the currently highlighted buffers on a word-by-word basis. If you
accept, a child Ediff session will start using the currently highlighted
regions. Ediff will let you step over the differences word-wise.

If you reject the offer, you will be asked to select regions of your choice.

@emph{If you are comparing 2 files or buffers:}
Ediff will ask you to select regions in buffers A and B.

@emph{If you are comparing 3 files or buffers simultaneously:} Ediff will
ask you to choose buffers and then select regions inside those buffers.

@emph{If you are merging files or buffers (with or without ancestor):}
Ediff will ask you to choose which buffer (A or B) to compare with the
merge buffer and then select regions in those buffers.

@end table

@node Other Session Commands,,Quick Help Commands,Session Commands
@section Other Session Commands

The following commands can be invoked from within any Ediff session,
although some of them are not bound to a 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 device that can be used to resume any active Ediff session
(which may have been postponed because the user switched to some other
activity).  This command 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}.
@xref{Registry of Ediff Sessions}, for more information on this 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.  See
@code{ediff-window-setup-function} for details on how to make either of
these modes the default one.

This function can also be invoked from the Menubar.  However, in some
cases, the change will take place only after you execute one of the Ediff
commands, such as going to the next difference or redisplaying.

@item ediff-toggle-use-toolbar
@findex ediff-toggle-use-toolbar
Available in XEmacs only.  The Ediff toolbar provides quick access to some
of the common Ediff functions.  This function toggles the display of the
toolbar.  If invoked from the menubar, the function may take sometimes
effect only after you execute an Ediff command, such as going to the next
difference.

@item ediff-use-toolbar-p
@vindex ediff-use-toolbar-p
The use of the toolbar can also be specified via the variable
@code{ediff-use-toolbar-p} (default is @code{t}).  This variable can be set
only in @file{.emacs} --- do @strong{not} change it interactively.  Use the
function @code{ediff-toggle-use-toolbar} instead.

@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, Session 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 to 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 @emph{directory difference 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.

@cindex Directory difference buffer
Sometimes it is desirable to copy some files from one directory to another
without exiting Ediff. The @emph{directory difference buffer}, which is
displayed by typing @kbd{D} as discussed above, can be used for this
purpose. If a file is, say, in Ediff's Directory A, but is missing in
Ediff's Directory B (Ediff will refuse to override existing files), then
typing @kbd{C} or clicking mouse button 2 over that file (which must be
displayed in directory difference buffer) will copy that file from
Directory A to Directory B.

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

@vindex ediff-autostore-merges
For group sessions created to merge files, Ediff can store all merges
automatically in a directory.  The user is asked to specify such directory
if the value of @code{ediff-autostore-merges} is non-@code{nil}.  If the value is
@code{nil}, nothing is done to the merge buffers---it will be the user's
responsibility to save them.  If the value is @code{t}, the user will be
asked where to save the merge buffers in all merge jobs, even those that do
not originate from a session group.  It the value is neither @code{nil} nor
@code{t}, the merge buffer is saved @emph{only} if this merge session was
invoked from a session group.  This behavior is implemented in the function
@code{ediff-maybe-save-and-delete-merge}, which is a hook in
@code{ediff-quit-merge-hook}.  The user can supply a different hook, if
necessary.

The variable @code{ediff-autostore-merges} is buffer-local, so it can be
set on a per-buffer basis.  Therefore, use @code{setq-default} to change
this variable globally.

@cindex Multi-file patches
A multi-file patch is a concatenated output of several runs of the Unix
@code{diff} command (some versions of @code{diff} let you create a
multi-file patch in just one run).  Ediff facilitates creation of
multi-file patches as follows.  If you are in a session group buffer
created in response to @code{ediff-directories} or
@code{ediff-directory-revisions}, you can mark (by typing @kbd{m}) the
desired Ediff sessions and then type @kbd{P} to create a
multi-file patch of those marked sessions.
Ediff will then display a buffer containing the patch.
The patch is generated by invoking @code{diff} on all marked individual
sessions (represented by files) and session groups (represented by
directories).  Ediff will also recursively descend into any @emph{unmarked}
session group and will search for marked sessions there.  In this way, you
can create multi-file patches that span file subtrees that grow out of
any given directory.

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.

Last, but not least, by typing @kbd{==}, you can quickly find out which
sessions have identical entries, so you won't have to run Ediff on those
sessions.  This, however, works only on local, uncompressed files.
For compressed or remote files, this command won't report anything.
Likewise, you can use @kbd{=h} to mark sessions with identical entries
for hiding or, with @kbd{=m}, for further operations.

The comparison operations @kbd{==}, @kbd{=h}, and @kbd{=m} can recurse into
subdirectories to see if they have identical contents (so the user will not
need to descend into those subdirectories manually). These commands ask the
user whether or not to do a recursive descent.



@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 also 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 (@file{_orig} is used
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 for changing 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 Customization::    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::&nb