5 Session Groups

Several major entries of Ediff perform comparison and merging on directories. On entering ediff-directories, ediff-directories3, ediff-merge-directories, ediff-merge-directories-with-ancestor, ediff-directory-revisions, ediff-merge-directory-revisions, or 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 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 nil nor 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 necessary.

The variable 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-directories or 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.

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