ediff: Major Entry Points
2 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.
‘ediff-files’
‘ediff’
Compare two files.
‘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.
‘ediff-current-file’
Compare the buffer with its file on disk. This function can be
used as a safe version of ‘revert-buffer’.
‘ediff-buffers’
Compare two buffers.
‘ediff-files3’
‘ediff3’
Compare three files.
‘ediff-buffers3’
Compare three buffers.
‘edirs’
‘ediff-directories’
Compare files common to two directories.
‘edirs3’
‘ediff-directories3’
Compare files common to three directories.
‘edir-revisions’
‘ediff-directory-revisions’
Compare versions of files in a given directory. Ediff selects only
the files that are under version control.
‘edir-merge-revisions’
‘ediff-merge-directory-revisions’
Merge versions of files in a given directory. Ediff selects only
the files that are under version control.
‘edir-merge-revisions-with-ancestor’
‘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.
‘ediff-windows-wordwise’
Compare windows word-by-word.
‘ediff-windows-linewise’
Compare windows line-by-line.
‘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.
‘ediff-regions-linewise’
Similar to ‘ediff-windows-linewise’, but compares the regions
line-by-line. See ‘ediff-windows-linewise’ for more details.
‘ediff-revision’
Compare versions of the current buffer, if the buffer is visiting a
file under version control.
‘ediff-patch-file’
‘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.
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 ‘ediff-patch-file’ will actually use the ‘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 ‘.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).
‘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
‘ediff-patch-buffer’ might be a better choice.
‘ediff-patch-buffer’
‘epatch-buffer’
Patch a buffer, then compare. The buffer being patched and the
file visited by that buffer (if any) is _not_ modified. The result
of the patch appears in some other buffer that has the name ending
with __patched_.
This function would refuse to apply a multifile patch to a buffer.
Use ‘ediff-patch-file’ for that (and when you want the original
file to be modified by the ‘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.
‘ediff-merge-files’
‘ediff-merge’
Merge two files.
‘ediff-merge-files-with-ancestor’
‘ediff-merge-with-ancestor’
Like ‘ediff-merge’, but with a third ancestor file.
‘ediff-merge-buffers’
Merge two buffers.
‘ediff-merge-buffers-with-ancestor’
Same but with ancestor.
‘edirs-merge’
‘ediff-merge-directories’
Merge files common to two directories.
‘edirs-merge-with-ancestor’
‘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.
‘ediff-merge-revisions’
Merge two versions of the file visited by the current buffer.
‘ediff-merge-revisions-with-ancestor’
Same but with ancestor.
‘ediff-documentation’
Brings up this manual.
‘ediff-show-registry’
‘eregistry’
Brings up Ediff session registry. This feature enables you to
quickly find and restart active Ediff sessions.
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 ‘ediff-use-last-dir’ is not ‘nil’, Ediff will
offer previously entered directories as defaults (which will be
maintained separately for each type of file, A, B, or C).
All the above functions use the POSIX ‘diff’ or ‘diff3’ programs to
find differences between two files. They process the ‘diff’ output and
display it in a convenient form. At present, Ediff understands only the
plain output from diff. Options such as ‘-c’ are not supported, nor is
the format produced by incompatible file comparison programs.
The functions ‘ediff-files’, ‘ediff-buffers’, ‘ediff-files3’,
‘ediff-buffers3’ first display the coarse, line-based difference
regions, as reported by the ‘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 ‘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 _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. Highlighting Difference
Regions, for information on how to customize this.
The commands ‘ediff-windows-wordwise’, ‘ediff-windows-linewise’,
‘ediff-regions-wordwise’ and ‘ediff-regions-linewise’ do comparison on
parts of existing Emacs buffers. The commands ‘ediff-windows-wordwise’
and ‘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 ‘ediff-regions-linewise’. This command
displays differences much like ‘ediff-files’ and ‘ediff-buffers’.
The functions ‘ediff-patch-file’ and ‘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 ‘ediff-directories’, ‘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, ‘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 ‘ediff-directory-revisions’,
‘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.
Info Catalog
ediff: Introduction
ediff: Top
ediff: Session Commands