@synindex vr cp
@synindex fn cp
@synindex pg cp
-
-@dircategory Emacs
-@direntry
-* Ediff: (ediff). A visual interface for comparing and merging programs.
-@end direntry
+@synindex ky cp
@iftex
@finalout
@c @smallbook
@comment %**end of header (This is for running Texinfo on a region.)
-@ifinfo
+@copying
This file documents Ediff, a comprehensive visual interface to Unix diff
and patch utilities.
-Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software
+Foundation, Inc.
+@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Documentation License. If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
-@end ifinfo
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Ediff: (ediff). A visual interface for comparing and merging programs.
+@end direntry
-@iftex
@titlepage
@title Ediff User's Manual
@sp 4
-@subtitle Ediff version 2.70
+@subtitle Ediff version 2.76.1
@sp 1
-@subtitle March 1998
+@subtitle January 2002
@sp 5
@author Michael Kifer
@page
@vskip 0pt plus 1filll
-@noindent
-Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover texts being ``A GNU
-Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
-license is included in the section entitled ``GNU Free Documentation
-License'' in the Emacs manual.
-
-(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-this GNU Manual, like GNU software. Copies published by the Free
-Software Foundation raise funds for GNU development.''
-
-This document is part of a collection distributed under the GNU Free
-Documentation License. If you want to distribute this document
-separately from the collection, you can do so by adding a copy of the
-license to the document, as described in section 6 of the license.
+@insertcopying
@end titlepage
-@page
-@end iftex
+
@node Top, Introduction, (dir), (dir)
allow the user to conveniently launch browsing or merging sessions on
groups of files in two (or three) different directories.
-In addition, Ediff can apply a patch to a file and then let you step though
+In addition, Ediff can apply a patch to a file and then let you step through
both files, the patched and the original one, simultaneously,
difference-by-difference. You can even apply a patch right out of a mail
buffer, i.e., patches received by mail don't even have to be saved. Since
@node Major Entry Points, Session Commands, Introduction, Top
@chapter 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:
@item ediff-regions-wordwise
@findex ediff-regions-wordwise
-Compare regions word-by-word.
+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.
@item ediff-regions-linewise
@findex ediff-regions-linewise
-Compare regions line-by-line.
+Similar to @code{ediff-windows-linewise}, but compares the regions
+line-by-line. See @code{ediff-windows-linewise} for more details.
@item ediff-revision
@findex ediff-revision
dangerous, since you will always have the original contents of the file
saved in another file that has the extension @file{.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 Countrol in
-Emacs manual).
+out to one of the previous versions (see the section on Version Control in
+the Emacs manual).
@code{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
monochrome display, they are underlined. @xref{Highlighting Difference
Regions}, for information on how to customize this.
-The functions @code{ediff-windows-wordwise},
+The commands @code{ediff-windows-wordwise},
@code{ediff-windows-linewise}, @code{ediff-regions-wordwise} and
@code{ediff-regions-linewise} do comparison on parts of existing Emacs
-buffers. Since @code{ediff-windows-wordwise} and
+buffers. The commands @code{ediff-windows-wordwise} and
@code{ediff-regions-wordwise} are intended for relatively small segments
-of buffers, comparison is done on the basis of words rather than lines.
-No refinement is necessary in this case. These commands are recommended
-only for relatively small regions (perhaps, up to 100 lines), because
-these functions have a relatively slow startup.
+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 @code{ediff-regions-linewise}. This
command displays differences much like @code{ediff-files} and
@table @kbd
@item ?
+@kindex ?
Toggles the Ediff Quick Help window ON and OFF.
@item G
+@kindex G
Prepares a mail buffer for sending a praise or a curse to the Ediff maintainer.
@item E
+@kindex 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.
@item v
+@kindex v
Scrolls up buffers A and B (and buffer C where appropriate) in a
coordinated fashion.
@item V
+@kindex V
Scrolls the buffers down.
@item <
+@kindex <
Scrolls the buffers to the left simultaneously.
@item >
+@kindex >
Scrolls buffers to the right.
@item wd
+@kindex wd
Saves the output from the diff utility, for further reference.
With prefix argument, saves the plain output from @code{diff} (see
it is available.
@item wa
+@kindex wa
Saves buffer A, if it was modified.
@item wb
+@kindex wb
Saves buffer B, if it was modified.
@item wc
+@kindex wc
Saves buffer C, if it was modified (if you are in a session that
compares three files simultaneously).
@item a
+@kindex a
@emph{In comparison sessions:}
Copies the current difference region (or the region specified as the prefix
to this command) from buffer A to buffer B.
this region in buffer C can be restored via the command @kbd{r}.
@item b
+@kindex b
Works similarly, but copies the current difference region from buffer B to
buffer A (in @emph{comparison sessions}) or the merge buffer (in
@emph{merge sessions}).
@kbd{r} in merge sessions.
@item ab
+@kindex 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 @kbd{rb}.
@item ac
+@kindex 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
@kbd{rc}.
@item ba
+@kindex 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
@kbd{ra}.
@item bc
+@kindex bc
Copies the difference region from buffer B to buffer C.
The command @kbd{rc} undoes this.
@item ca
+@kindex ca
Copies the difference region from buffer C to buffer A.
The command @kbd{ra} undoes this.
@item cb
+@kindex cb
Copies the difference region from buffer C to buffer B.
The command @kbd{rb} undoes this.
@item p
@itemx DEL
+@kindex p
+@kindex DEL
Makes the previous difference region current.
@item n
@itemx SPC
+@kindex n
+@kindex SPC
Makes the next difference region current.
@item j
@itemx -j
@itemx Nj
+@kindex j
Makes the very first difference region current.
@kbd{-j} makes the last region current. Typing a number, N, and then `j'
`j' makes current the region Last - N.
@item ga
+@kindex ga
Makes current the difference region closest to the position of the point in
buffer A.
this case, the variants will be positioned so that each would display this
area (of agreement).
@item gb
+@kindex gb
Makes current the difference region closest to the position of the point in
buffer B.
With a prefix argument, behaves like @kbd{ga}, but with respect to buffer B.
@item gc
+@kindex gc
@emph{In merge sessions:}
makes current the difference region closest to the point in the merge buffer.
With a prefix argument, behaves like @kbd{ga}, but with respect to buffer C.
@item !
+@kindex !
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.
@item *
+@kindex *
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.
no longer current, due to user editing.
@item m
+@kindex 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.
@item |
+@kindex |
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 @kbd{m} may help some.
@item @@
+@kindex @@
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.
@kbd{*}.
@item h
+@kindex 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.
@item r
+@kindex 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 @kbd{a} or @kbd{b}, Ediff saves the old contents of the
This command is enabled in merge sessions only.
@item ra
+@kindex 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:
@kbd{b}, @kbd{ba}, @kbd{ca}, which see. This command is enabled in
comparison sessions only.
@item rb
+@kindex 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:
@kbd{a}, @kbd{ab}, @kbd{cb}, which see. This command is enabled in
comparison sessions only.
@item rc
+@kindex 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:
@kbd{ac}, @kbd{bc}, which see. This command is enabled in 3-file
comparison sessions only.
@item ##
+@kindex ##
Tell Ediff to skip over regions that disagree among themselves only in the
amount of white space and line breaks.
@item #h
@itemx #f
+@kindex #f
+@kindex #h
Ediff works hard to ameliorate the effects of boredom in the workplace...
Quite often differences are due to identical replacements (e.g., the word
over. @xref{Selective Browsing}, for more.
@item A
+@kindex 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).
@item B
+@kindex B
Toggles the read-only property in buffer B.
If file B is under version control and is checked in, it is checked out.
@item C
+@kindex 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.
@item ~
+@kindex ~
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.
@item i
+@kindex i
Displays all kinds of useful data about the current Ediff session.
@item D
+@kindex D
Runs @code{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.
@xref{Patch and Diff Programs}, for details.
@item R
+@kindex 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.
minibuffer: @kbd{M-x eregistry}. @xref{Registry of Ediff Sessions}.
@item M
+@kindex M
Shows the session group buffer that invoked the current Ediff session.
@xref{Session Groups}, for more information on session groups.
@item z
+@kindex 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
The easiest way to resume a suspended Ediff session is through the registry
of active sessions. @xref{Registry of Ediff Sessions}, for details.
@item q
+@kindex q
Terminates this Ediff session. With a prefix argument (e.g.,@kbd{1q}), asks
if you also want to delete the buffers of the variants.
Modified files and the results of merges are never deleted.
@item %
+@kindex %
Toggles narrowing in Ediff buffers. Ediff buffers may be narrowed if you
are comparing only parts of these buffers via the commands
@code{ediff-windows-*} and @code{ediff-regions-*}, which see.
@item C-l
+@kindex 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.
@item $$
+@kindex $$
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
it. Typing @kbd{$$} again undoes this setting.
@item $*
+@kindex $*
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 @kbd{$*} will accomplish
region in buffer A, etc.
@item /
+@kindex /
Displays the ancestor file during merges.
@item &
+@kindex &
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.
corresponding region from buffer B.
@item s
+@kindex 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.
the variable @code{ediff-merge-window-share}, which see.
@item +
+@kindex +
Combines the difference regions from buffers A and B and copies the
result into the merge buffer. @xref{Merging and diff3}, and the
variables @code{ediff-combine-diffs} and @code{ediff-combination-pattern}.
@item =
+@kindex =
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
text is contrary to human nature, Ediff has a special command to help
reduce the risk of developing a cataract.
-The above command compares regions within Ediff buffers. This creates a
-child Ediff session for comparing current Emacs regions in buffers A, B, or
-C as follows:
+In other situations, the currently highlighted region might be big and you
+might want to reconcile of them interactively.
-@emph{If you are comparing 2 files or buffers:}
-Ediff would compare current Emacs regions in buffers A and B.
+All of this can be done with the above command, @kbd{=}, which
+compares regions within Ediff buffers. Typing @kbd{=} creates a
+child Ediff session for comparing regions in buffers A, B, or
+C as follows.
-@emph{If you are comparing 3 files or buffers simultaneously:} Ediff would
-compare the current Emacs regions in the buffers of your choice (you will
-be asked which two of the three buffers to use).
+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.
-@emph{If you are merging files or buffers (with or without ancestor):}
-Ediff would take the current region in the merge buffer and compare
-it to the current region in the buffer of your choice (A or B).
+If you reject the offer, you will be asked to select regions of your choice.
-Highlighting set by the parent Ediff session is removed, to avoid interference
-with highlighting of the child session. When done with the child session, type
-@kbd{C-l} in the parent's control panel to restore the original highlighting.
+@emph{If you are comparing 2 files or buffers:}
+Ediff will ask you to select regions in buffers A and B.
-If you temporarily switch to the parent session, parent highlighting will be
-restored. If you then come back to the child session, you may want to remove
-parent highlighting, so it won't interfere. Typing @kbd{h} may help here.
+@emph{If you are comparing 3 files or buffers simultaneously:} Ediff will
+ask you to choose buffers and then select regions inside those buffers.
+
+@emph{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.
@end table
cases, the change will take place only after you execute one of the Ediff
commands, such as going to the next difference or redisplaying.
+@item ediff-toggle-use-toolbar
+@findex ediff-toggle-use-toolbar
+Available in XEmacs only. The Ediff toolbar provides quick access to some
+of the common Ediff functions. This function toggles the display of the
+toolbar. If invoked from the menubar, the function may take sometimes
+effect only after you execute an Ediff command, such as going to the next
+difference.
+
+@item ediff-use-toolbar-p
+@vindex ediff-use-toolbar-p
+The use of the toolbar can also be specified via the variable
+@code{ediff-use-toolbar-p} (default is @code{t}). This variable can be set
+only in @file{.emacs} --- do @strong{not} change it interactively. Use the
+function @code{ediff-toggle-use-toolbar} instead.
+
@item ediff-revert-buffers-then-recompute-diffs
@findex ediff-revert-buffers-then-recompute-diffs
This command reverts the buffers you are comparing and recomputes their
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 buffer and are conveniently displayed by typing @kbd{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.
+separate @emph{directory difference buffer} and are conveniently displayed
+by typing @kbd{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.
+
+@cindex Directory difference buffer
+Sometimes it is desirable to copy some files from one directory to another
+without exiting Ediff. The @emph{directory difference buffer}, which is
+displayed by typing @kbd{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 @kbd{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 @kbd{+}, for
active sessions, and with @kbd{-}, for finished sessions.
@node Credits, Index, Customization, Top
@chapter Credits
-Ediff was written by Michael Kifer <kifer@@cs.sunysb.edu>. It was inspired
+Ediff was written by Michael Kifer <kifer@@cs.stonybrook.edu>. It was inspired
by emerge.el written by Dale R.@: Worley <drw@@math.mit.edu>. An idea due to
Boris Goldowsky <boris@@cs.rochester.edu> made it possible to highlight
fine differences in Ediff buffers. Alastair Burt <burt@@dfki.uni-kl.de>
toolbar support package for Ediff, and Hrvoje Niksic <hniksic@@xemacs.org>
adapted it to the Emacs customization package.
-Many people provided help with bug reports, patches, and advice.
+Many people provided help with bug reports, feature suggestions, and advice.
Without them, Ediff would not be nearly as useful as it is today.
-Here is a full list of contributors (I hope I didn't miss anyone):
+Here is a hopefully full list of contributors:
@example
Adrian Aichner (aichner@@ecf.teradyne.com),
(jaffe@@chipmunk.cita.utoronto.ca),
David Karr (dkarr@@nmo.gtegsc.com),
Norbert Kiesel (norbert@@i3.informatik.rwth-aachen.de),
-Sam Steingold (sds@@goems.com),
Leigh L Klotz (klotz@@adoc.xerox.com),
Fritz Knabe (Fritz.Knabe@@ecrc.de),
Heinz Knutzen (hk@@informatik.uni-kiel.d400.de),
Andrew Koenig (ark@@research.att.com),
+Hannu Koivisto (azure@@iki.fi),
Ken Laprade (laprade@@dw3f.ess.harris.com),
Will C Lauer (wcl@@cadre.com),
Richard Levitte (levitte@@e.kth.se),
Mike Long (mike.long@@analog.com),
+Dave Love (d.love@@dl.ac.uk),
Martin Maechler (maechler@@stat.math.ethz.ch),
Simon Marshall (simon@@gnu.org),
+Paul C. Meuse (pmeuse@@delcomsys.com),
Richard Mlynarik (mly@@adoc.xerox.com),
Stefan Monnier (monnier@@cs.yale.edu),
Chris Murphy (murphycm@@sun.aston.ac.uk),
Tibor Polgar (tlp00@@spg.amdahl.com),
David Prince (dave0d@@fegs.co.uk),
Paul Raines (raines@@slac.stanford.edu),
+Stefan Reicher (xsteve@@riic.at),
+Charles Rich (rich@@merl.com),
Bill Richter (richter@@math.nwu.edu),
C.S.@: Roberson (roberson@@aur.alcatel.com),
Kevin Rodgers (kevin.rodgers@@ihs.com),
Scott O. Sherman (Scott.Sherman@@mci.com),
Richard Stallman (rms@@gnu.org),
Richard Stanton (stanton@@haas.berkeley.edu),
+Sam Steingold (sds@@goems.com),
Ake Stenhoff (etxaksf@@aom.ericsson.se),
Stig (stig@@hackvan.com),
Peter Stout (Peter_Stout@@cs.cmu.edu),
Chuck Thompson (cthomp@@cs.uiuc.edu),
Ray Tomlinson (tomlinso@@bbn.com),
Raymond Toy (toy@@rtp.ericsson.se),
+Stephen J. Turnbull (stephen@@xemacs.org),
Jan Vroonhof (vroonhof@@math.ethz.ch),
Colin Walters (walters@@cis.ohio-state.edu),
Philippe Waroquiers (philippe.waroquiers@@eurocontrol.be),
HCoop / bpt / emacs.git / blobdiff