ediff: Session Groups
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.