Ediff

3.1 Quick Help Commands

? ¶

Toggles the Ediff Quick Help window ON and OFF.

G ¶

Prepares a mail buffer for sending a praise or a curse to the Ediff maintainer.

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.

v ¶

Scrolls up buffers A and B (and buffer C where appropriate) in a coordinated fashion.

V ¶

Scrolls the buffers down.

< ¶

Scrolls the buffers to the left simultaneously.

> ¶

Scrolls buffers to the right.

wd ¶

Saves the output from the diff utility, for further reference.

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

wa ¶

Saves buffer A, if it was modified.

wb ¶

Saves buffer B, if it was modified.

wc ¶

Saves buffer C, if it was modified (if you are in a session that compares three files simultaneously).

a ¶

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 rb, which see.

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

b ¶

Works similarly, but copies the current difference region from buffer B to buffer A (in comparison sessions) or the merge buffer (in merge sessions).

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

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

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

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

bc ¶

Copies the difference region from buffer B to buffer C. The command rc undoes this.

ca ¶

Copies the difference region from buffer C to buffer A. The command ra undoes this.

cb ¶

Copies the difference region from buffer C to buffer B. The command rb undoes this.

p ¶

DEL

Makes the previous difference region current.

n ¶

SPC

Makes the next difference region current.

j ¶

-j

Nj

Makes the very first difference region current.

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

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

gb ¶

Makes current the difference region closest to the position of the point in buffer B.

With a prefix argument, behaves like ga, but with respect to buffer B.

gc ¶

In merge sessions: makes current the difference region closest to the point in the merge buffer.

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

With a prefix argument, behaves like ga, but with respect to buffer C.

! ¶

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.

* ¶

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

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.

| ¶

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 m may help some.

@ ¶

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

h ¶

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

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 a or b, Ediff saves the old contents of the region in case you change your mind.)

This command is enabled in merge sessions only.

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: b, ba, ca, which see. This command is enabled in comparison sessions only.

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: a, ab, cb, which see. This command is enabled in comparison sessions only.

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: ac, bc, which see. This command is enabled in 3-file comparison sessions only.

## ¶

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 ## again puts Ediff back in the original state.

#c ¶

Toggle case sensitivity in the diff program. All diffs are recomputed. Case sensitivity is controlled by the variables ediff-ignore-case-option, ediff-ignore-case-option3, and ediff-ignore-case, which are explained elsewhere.

#h ¶

#f

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 j). The above commands, #h and #f, may well save your day!

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

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

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

B ¶

Toggles the read-only property in buffer B. If file B is under version control and is checked in, it is checked out.

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.

~ ¶

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.

i ¶

Displays all kinds of useful data about the current Ediff session.

D ¶

Runs 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 diff output. See Patch and Diff Programs, for details.

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 lose track of them completely... The R command is designed to save these people from the recently discovered Ediff Proficiency Syndrome.)

Typing 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: M-x eregistry. See Registry of Ediff Sessions.

M ¶

Shows the session group buffer that invoked the current Ediff session. See Session Groups, for more information on session groups.

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. See Registry of Ediff Sessions, for details.

q ¶

Terminates this Ediff session. With a prefix argument (e.g.,1q), asks if you also want to delete the buffers of the variants. Modified files and the results of merges are never deleted.

% ¶

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

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.

$$ ¶

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 $$ again undoes this setting.

$* ¶

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 $* 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.

/ ¶

Toggle to display the ancestor file in 3way merges. You can enable permanently this setting customizing the variable ediff-show-ancestor.

& ¶

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 ‘default-A’ (choose the region from buffer A), ‘default-B’ (choose the region from buffer B), or ‘combined’ (combine the regions from the two buffers). See Merging and diff3, for further details.

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

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., 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, -s shrinks the window by about 1 line and -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 (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 ediff-merge-window-share, which see.

+ ¶

Combines the difference regions from buffers A and B and copies the result into the merge buffer. See Merging and diff3, and the variables ediff-combine-diffs and ediff-combination-pattern.

= ¶

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, =, which compares regions within Ediff buffers. Typing = 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.

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

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

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.

3.2 Other Session Commands

The following commands can be invoked from within any Ediff session, although some of them are not bound to a key.

eregistry ¶

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 eregistry is an alias for ediff-show-registry. See Registry of Ediff Sessions, for more information on this registry.

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

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.

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 ediff-profile toggles profiling of ediff commands.

7.1 Hooks

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

ediff-before-setup-hook ¶

Hook that is run just before Ediff rearranges windows to its liking. Can be used to save windows configuration.

ediff-keymap-setup-hook ¶

This hook can be used to alter bindings in Ediff’s keymap, ediff-mode-map. These hooks are run right after the default bindings are set. The regular user needs not be concerned with this hook—it is provided for implementers of other Emacs packages built on top of Ediff.

ediff-before-setup-windows-hook ¶

ediff-after-setup-windows-hook

These two hooks are called before and after Ediff sets up its window configuration. These hooks are run each time Ediff rearranges windows to its liking. This happens whenever it detects that the user changed the windows setup.

ediff-suspend-hook ¶

ediff-quit-hook

These two hooks are run when you suspend or quit Ediff. They can be used to set desired window configurations, delete files Ediff didn’t want to clean up after exiting, etc.

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

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

ediff-cleanup-hook ¶

This hook is run just before ediff-quit-hook. This is a good place to do various cleanups, such as deleting the variant buffers. Ediff provides a helper function, ediff-janitor, that you can invoke from a private hook function. For example:

(defun my-ediff-janitor ()
  (ediff-janitor nil nil))
(add-hook 'ediff-cleanup-hook #'my-ediff-janitor)

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

ediff-quit-merge-hook ¶

This hook is called when Ediff quits a merge job. By default, the value is ediff-maybe-save-and-delete-merge, which is a function that attempts to save the merge buffer according to the value of ediff-autostore-merges, as described later.

ediff-before-setup-control-frame-hook ¶

ediff-after-setup-control-frame-hook

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

ediff-startup-hook ¶

This hook is run at the end of Ediff startup.

ediff-select-hook ¶

This hook is run after Ediff selects the next difference region.

ediff-unselect-hook ¶

This hook is run after Ediff unselects the current difference region.

ediff-prepare-buffer-hook ¶

This hook is run for each Ediff buffer (A, B, C) right after the buffer is arranged.

ediff-display-help-hook ¶

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

ediff-mode-hook ¶

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

ediff-registry-setup-hook ¶

Hooks run after setting up the registry for all active Ediff session. See Session Groups, for details.

ediff-before-session-group-setup-hook ¶

Hooks run before setting up a control panel for a group of related Ediff sessions. Can be used, for example, to save window configuration to restore later.

ediff-after-session-group-setup-hook ¶

Hooks run after setting up a control panel for a group of related Ediff sessions. See Session Groups, for details.

ediff-quit-session-group-hook ¶

Hooks run just before exiting a session group.

ediff-meta-buffer-keymap-setup-hook ¶

Hooks run just after setting up the ediff-meta-buffer-map, the map that controls key bindings in the meta buffer. Since ediff-meta-buffer-map is a local variable, you can set different bindings for different kinds of meta buffers.

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

7.3 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 (see Quick Help Customization). This behavior is useful only if icons are allowed to accept keyboard input (which depends 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>’.)

7.4 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, use something like the following:

(with-eval-after-load 'ediff
  (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 ##.

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

Finally, Ediff can be told to ignore the case of the letters. This behavior can be toggled with #c and it is controlled with three variables: ediff-ignore-case-option, ediff-ignore-case-option3, and ediff-ignore-case.

The variable ediff-ignore-case-option specifies the option to pass to the diff program for comparing two files or buffers. For GNU diff, this option is "-i". The variable ediff-ignore-case-option3 specifies the option to pass to the diff3 program in order to make it case-insensitive. GNU diff3 does not have such an option, so when merging or comparing three files with this program, ignoring the letter case is not supported.

The variable ediff-ignore-case controls whether Ediff starts out by ignoring letter case or not. It can be set in .emacs using setq-default.

When case sensitivity is toggled, all difference regions are recomputed.

7.5 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 windowing 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 face 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 with-eval-after-load. For instance:

(with-eval-after-load 'ediff
  (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))

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

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

7.8 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 in 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 extension to specify a backup file name extension. Other versions only permit -b, which (usually) assumes the extension .orig. Yet others force you to use -zextension.

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.

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

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

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

7.12 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 lose a 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-keep-tmp-versions ¶

Default is nil. If t, the versions of the files being compared or merged using operations such as ediff-revision or ediff-merge-revisions are not deleted on exit. The normal action is to clean up and delete these version files.

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.

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