Several major entries of Ediff perform comparison and merging on
directories. On entering
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
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 RET or 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 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 directory difference buffer and are conveniently displayed by typing 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.
Sometimes it is desirable to copy some files from one directory to another without exiting Ediff. The directory difference buffer, which is displayed by typing 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 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 +, for active sessions, and with -, 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 h to mark a session as a candidate for exclusion and x to actually hide the marked sessions. There actions are reversible: with a prefix argument, h unmarks the session under the cursor, and x brings the hidden sessions into the view (x doesn't unmark them, though, so the user has to explicitly unmark the sessions of interest).
Group sessions also understand the command 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.
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
ediff-autostore-merges is non-
nil. If the value is
nil, nothing is done to the merge buffers—it will be the user's
responsibility to save them. If the value is
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
t, the merge buffer is saved only if this merge session was
invoked from a session group. 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
ediff-autostore-merges is buffer-local, so it can be
set on a per-buffer basis. Therefore, use
setq-default to change
this variable globally.
A multi-file patch is a concatenated output of several runs of the Unix
diff command (some versions of
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
ediff-directory-revisions, you can mark (by typing m) the
desired Ediff sessions and then type 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
diff on all marked individual
sessions (represented by files) and session groups (represented by
directories). Ediff will also recursively descend into any 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.
ediff-directories session, it is enough to just mark the
requisite sessions. In
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 ==, 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 =h to mark sessions with identical entries for hiding or, with =m, for further operations.
The comparison operations ==, =h, and =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.