Next: Session Commands, Previous: Introduction, Up: Top

## 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. See 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.

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

         (require 'ediff)

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 `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 such as the VMS version of `diff`.

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