doc/misc/ediff.texi

26 This file documents Ediff, a comprehensive visual interface to Unix diff
32 Permission is granted to copy, distribute and/or modify this document
39 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
73 * Major Entry Points::          How to use Ediff.
77 * Remote and Compressed Files::  You may want to know about this.
78 * Customization::               How to make Ediff work the way YOU want.
79 * Credits::                     Thanks to those who helped.
98 through them.  You can also copy difference regions from one buffer to
101 Another powerful feature is the ability to merge a pair of files into a
105 allow the user to conveniently launch browsing or merging sessions on
108 In addition, Ediff can apply a patch to a file and then let you step through
111 buffer, i.e., patches received by mail don't even have to be saved.  Since
114 @file{file.orig} to @file{file}, thereby undoing any particular patch that
120 patches.  Ediff is [hopefully] using the same algorithm as @code{patch} to
121 determine which files need to be patched.)
137 Ediff commands, and two or three windows displaying the files to be compared
141 keystrokes) when you use Ediff. You can switch to other Emacs buffers at
143 switch back to Ediff at any time by activating the appropriate Emacs windows.
146 be run either from the minibuffer or from the menu bar.  In the menu bar,
147 all Ediff's entry points belong to three submenus of the Tools menu:
186  Compare files common to two directories.
191  Compare files common to three directories.
222 and they can even overlap.  You will be asked to specify the buffers that
223 contain the regions, which you want to compare. For each buffer, you will
224 also be asked to mark the regions to be compared. Pay attention to the
225 messages that appear in the minibuffer.
229 Similar to @code{ediff-windows-linewise}, but compares the regions
242 Patch a file or multiple files, then compare.  If the patch applies to just
245 will be able to patch the files selectively.  @xref{Session Groups}, for
254 utility to change the original files on disk.  This is not that
258 out to one of the previous versions (see the section on Version Control in
262 to be patched is checked in, then Ediff will offer to check it out, because
263 failing to do so may result in the loss of the changes when the file is
266 If you don't intend to modify the file via the patch and just want to see
278 This function would refuse to apply a multifile patch to a buffer.  Use
279 @code{ediff-patch-file} for that (and when you want the original file to be
312  Merge files common to two directories.
319  will still be able to merge them without the ancestor.
335 Brings up Ediff session registry.  This feature enables you to quickly find
340 necessary information---typically the files or buffers to compare, merge, or
341 patch.  Ediff tries to be smart about these prompts.  For instance, in
344 file name will be appended to that directory.  In addition, if the variable
351 to find differences between two files.  They process the @code{diff} output
363 even though the difference may be localized to just a few words or even
364 to the white space or line breaks, Ediff further @emph{refines} the
365 regions to indicate which exact words differ.  If the only difference is
370 Regions}, for information on how to customize this.
385 patch to a file or a buffer and then run Ediff on the appropriate
394 the file visited by the current buffer to one of its checked-in versions.
405 @kbd{?} to shrink the window to just one line.  You can redisplay the help
409 type a number, say 3, and then @kbd{j} (@code{ediff-jump-to-difference}),
410 Ediff moves to the third difference region.  Typing 3 and then @kbd{a}
411 (@code{ediff-diff-to-diff}) copies the 3rd difference region from variant A
412 to variant B@.  Likewise, 4 followed by @kbd{ra} restores the 4th difference
431 * Other Session Commands::          Commands that are not bound to keys.
445 Prepares a mail buffer for sending a praise or a curse to the Ediff maintainer.
463 Scrolls the buffers to the left simultaneously.
466 Scrolls buffers to the right.
493 to this command) from buffer A to buffer B@.
499 to this command) from buffer A to the merge buffer.  The old contents of
504 Works similarly, but copies the current difference region from buffer B to
515 to this command) from buffer A to buffer B@.  This (and the next five)
521 Copies the difference region from buffer A to buffer C@.
526 Copies the difference region from buffer B to buffer A@.
531 Copies the difference region from buffer B to buffer C@.
535 Copies the difference region from buffer C to buffer A@.
539 Copies the difference region from buffer C to buffer B@.
565 Makes current the difference region closest to the position of the point in
577 Makes current the difference region closest to the position of the point in
580 With a prefix argument, behaves like @kbd{ga}, but with respect to buffer B.
584 makes current the difference region closest to the point in the merge buffer.
587 makes current the region closest to the point in buffer C.
589 With a prefix argument, behaves like @kbd{ga}, but with respect to buffer C.
593 Recomputes the difference regions, bringing them up to date.  This is often
594 needed because it is common to do all sorts of editing during Ediff
606 Ediff doesn't do automatic refinement in order to improve response time.
613 no longer current, due to user editing.
624 split is convenient when it is possible to compare files
634 On slow machines, it may be advantageous to turn auto-refinement off.  The
674 Tell Ediff to skip over regions that disagree among themselves only in the
677 Even though such regions will be skipped over, you can still jump to any
695 Ediff works hard to ameliorate the effects of boredom in the workplace...
697 Quite often differences are due to identical replacements (e.g., the word
701 tempted to tell Ediff to skip these regions altogether (you will still be able
702 to jump to them via the command @kbd{j}).  The above commands, @kbd{#h}
705 @kbd{#h} prompts you to specify regular expressions for each
708 also tell Ediff to skip regions where at least one variant matches its
742 to your Mom.
754 track of them completely...  The @kbd{R} command is designed to save these
759 minibuffer: @kbd{M-x eregistry}.  @xref{Registry of Ediff Sessions}.
770 your current activity.  This command tries hard to hide all Ediff-related
773 The easiest way to resume a suspended Ediff session is through the registry
778 if you also want to delete the buffers of the variants.
789 Restores the usual Ediff window setup.  This is the quickest way to resume
795 While merging with an ancestor file, Ediff is determined to reduce user's
797 typing.  If it notices that, say, file A's difference region is identical to
804 You may want to ignore such ``obvious'' merges and concentrate on difference
807 had different ideas on how to do this.
816 convenient to be able to skip the difference regions for which you already
821 identical to its default setting, as originally decided by Ediff.  For
822 instance, if Ediff is merging according to the ``combined'' policy, then the
832 Toggle to display the ancestor file in 3way merges.
838 on a difference region and the other doesn't, Ediff knows what to do: it copies
850 they weren't changed with respect to the original.  For instance, if such a
851 region has the status @samp{default-A} then changing the default action to
857 Causes the merge window shrink to its minimum size, thereby exposing as much
868 restores window C to its original size whenever it makes any other change
870 to another difference does not affect window C's size.
885 edited and then moved to a different place in another file.  In such a case,
886 these two chunks of text are unlikely to belong to the same difference
887 region, so the refinement feature of Ediff will not be able to tell you
889 text is contrary to human nature, Ediff has a special command to help
893 might want to reconcile of them interactively.
900 First, you will be asked whether you want to compare the fine differences
905 If you reject the offer, you will be asked to select regions of your choice.
908 Ediff will ask you to select regions in buffers A and B.
911 ask you to choose buffers and then select regions inside those buffers.
914 Ediff will ask you to choose which buffer (A or B) to compare with the
923 although some of them are not bound to a key.
931 registry is a device that can be used to resume any active Ediff session
932 (which may have been postponed because the user switched to some other
941 is in a separate frame) to the single-frame mode (where all Ediff buffers
943 @code{ediff-window-setup-function} for details on how to make either of
948 commands, such as going to the next difference or redisplaying.
952 Available in XEmacs only.  The Ediff toolbar provides quick access to some
955 effect only after you execute an Ediff command, such as going to the next
968 differences.  It is useful when, after making changes, you decided to
970 compared but want to discard any changes to comparison buffers that were
997 The latter would be the fastest way to bring up the registry
1000 If you are in a habit of running multiple long Ediff sessions and often need to
1001 suspend, resume, or switch between them, it may be a good idea to have the
1008 description of each session, so it is usually easy to identify the right
1009 session to resume.
1011 Other useful commands are bound to @kbd{SPC} (next registry record)
1013 but you don't need to memorize them, since they are listed at the top of
1028 Dired-like buffer that lists files common to the directories involved along
1036 files.  You can come back to the session group buffer associated with a
1041 applicable only to certain types of work.  The relevant commands are always
1042 listed at the top of each session group buffer, so there is no need to
1046 files common to all directories involved.  The differences are kept in a
1048 by typing @kbd{D} to the corresponding session group panel.  Thus, as an
1049 added benefit, Ediff can be used to compare the contents of up to three
1053 Sometimes it is desirable to copy some files from one directory to another
1057 Ediff's Directory B (Ediff will refuse to override existing files), then
1060 Directory A to Directory B.
1065 Sometimes, it is convenient to exclude certain sessions from a group.
1066 Usually this happens when the user doesn't intend to run Ediff of certain
1068 to the session group buffer.  To help alleviate this problem, the user can
1069 type @kbd{h} to mark a session as a candidate for exclusion and @kbd{x} to
1073 though, so the user has to explicitly unmark the sessions of interest).
1080 For group sessions created to merge files, Ediff can store all merges
1081 automatically in a directory.  The user is asked to specify such directory
1083 @code{nil}, nothing is done to the merge buffers---it will be the user's
1084 responsibility to save them.  If the value is @code{t}, the user will be
1085 asked where to save the merge buffers in all merge jobs, even those that do
1094 set on a per-buffer basis.  Therefore, use @code{setq-default} to change
1102 created in response to @code{ediff-directories} or
1104 desired Ediff sessions and then type @kbd{P} to create a
1114 In an @code{ediff-directories} session, it is enough to just mark the
1116 marked sessions must also be active, or else Ediff will refuse to produce a
1118 many ways to create diff output, and it is easier to handle by running
1122 sessions have identical entries, so you won't have to run Ediff on those
1125 Likewise, you can use @kbd{=h} to mark sessions with identical entries
1129 subdirectories to see if they have identical contents (so the user will not
1130 need to descend into those subdirectories manually). These commands ask the
1131 user whether or not to do a recursive descent.
1142 machine, or you can apply a patch to a file on another machine.  Even
1149 Generally, this applies to files that are handled using black magic, such
1162 won't need to change anything.  However, should the need arise, there are
1170 With respect to the latter, please note that the X resource
1174 refer to Emacs manual for the information on how to set Emacs X resources.
1178 * Quick Help Customization::    How to customize Ediff's quick help feature.
1183 * Refinement of Difference Regions::  How to control the refinement process.
1186 * Merging and diff3::           How to customize Ediff in its Merge Mode.
1188                                  You are not likely to do that.
1202 Hook that is run just before Ediff rearranges windows to its liking.
1203 Can be used to save windows configuration.
1208 This hook can be used to alter bindings in Ediff's keymap,
1220 configuration.  These hooks are run each time Ediff rearranges windows to
1229 used to set desired window configurations, delete files Ediff didn't
1230 want to clean up after exiting, etc.
1234 most cases.  You probably won't want to change it, but you might
1235 want to add other hook functions.
1248 place to do various cleanups, such as deleting the variant buffers.
1261 effect of using this function is that you may not be able to compare the
1271 to save the merge buffer according to the value of
1279 They can be used to relocate Ediff control frame when Ediff runs in a
1281 frame).  Be aware that many variables that drive Ediff are local to
1284 @code{ediff-default-suspend-hook} and @code{ediff-default-quit-hook} to
1307 can be used to alter the help message for custom packages that run on
1313 buffer.  This is done before any Ediff window is created.  You can use it to
1323 sessions. Can be used, for example, to save window configuration to restore
1350 typing @kbd{?}.  The control window will then shrink to just one line and a
1355 is set to @code{nil}, meaning that the short message is used.
1356 Set this to @code{t}, if you want Ediff to use the long
1360 If you want to change the appearance of the help message on a per-buffer
1361 basis, you must use @code{ediff-startup-hook} to change the value of
1362 the variable @code{ediff-help-message}, which is local to
1378 If, according to the above criteria, the two buffers fall into the same
1385 dedicated, etc.  Unfortunately, the margin of this book is too narrow to
1390 be achieved by arranging buffers A, B (and C, if applicable) to be seen in
1392 adapting itself to the multi-frame mode.
1394 Ediff uses the following variables to set up its control panel
1402 X-windows, you can use this name to set up preferences in your
1404 use.  Usually this is preferable to changing
1415 setting the variable @code{ediff-control-frame-position-function} to an
1424 The following variables can be used to adjust the location produced by
1453 variable to @code{t} and @code{ediff-prefer-long-help-message} to
1455 only if icons are allowed to accept keyboard input (which depends on the
1463 separate frame offers an important opportunity by allowing you to
1478 under Emacs, you can switch freely between these two setups by executing
1497 particular session is local to the associated control panel buffer.  You
1498 can switch between sessions by suspending one session and then switching
1499 to another control panel.  (Different control panel buffers are
1505 Sometimes it is convenient to be able to step through only some difference
1506 regions, those that match certain regular expressions, and to ignore all
1507 others.  On other occasions, you may want to ignore difference regions that
1508 match some regular expressions, and to look only at the rest.
1513 regions you want to focus on.
1519 depends on how you respond to a question.
1522 Ediff narrows the buffers to those regions.  This means that you can use
1523 the expressions @kbd{\`} and @kbd{\'} to tie search to the beginning or end
1540 directly (using @kbd{j})  to any numbered
1543 Users can supply their own functions to specify how Ediff should do
1554 simply type @key{RET} in response to a prompt.  Typing @key{RET} tells Ediff
1555 to accept the default value, which may not be what you want.  Instead, you
1559 You can use the status command, @kbd{i}, to find out whether
1569 In addition to the ability to ignore regions that match regular
1570 expressions, Ediff can be ordered to start skipping over certain
1577 If @code{t}, causes Ediff to skip over "uninteresting" difference regions,
1583 @strong{Please note:} in order for this feature to work, auto-refining of
1591 Ediff may take a long time to skip over them because it has to compute fine
1598 Finally, Ediff can be told to ignore the case of the letters. This behavior
1603 The variable @code{ediff-ignore-case-option} specifies the option to pass
1604 to the diff program for comparing two files or buffers. For GNU
1606 @code{ediff-ignore-case-option3} specifies the option to pass to the
1607 @code{diff3} program in order to make it case-insensitive. GNU @code{diff3}
1633 These variables hold strings that Ediff uses to mark the beginning and the
1635 cannot display faces.  Ediff uses different flags to highlight regions that
1644 Ediff uses these faces to highlight current differences on devices where
1647 is @samp{Ediff}, @emph{not} @samp{emacs}.  Please refer to Emacs manual for
1648 the information on how to set X resources.
1655 Ediff uses these faces to show the fine differences between the current
1673 So, Ediff uses italics to highlight non-current differences.
1678 use highlighting with faces.  However, if it fails to determine that faces
1679 can be used, the user can set this variable to @code{t} to make sure that
1680 Ediff uses faces to highlight differences.
1689 in the mode where all difference regions are highlighted.  If you prefer to
1691 should set @code{ediff-highlight-all-diffs} to @code{nil}.  Type @kbd{h} to
1694 Ediff lets you switch between the two modes of highlighting.  That is,
1695 you can switch interactively from highlighting using faces to
1702 If you want to change the default settings for @code{ediff-force-faces} and
1706 You can also change the defaults for the faces used to highlight the
1707 difference regions.  There are two ways to do this.  The simplest and the
1708 preferred way is to use the customization widget accessible from the
1710 turn is under "Programming".  The faces that are used to highlight
1714 The second, much more arcane, method to change default faces is to include
1723 would use the pre-defined face @code{bold-italic} to highlight the current
1745 that would widen the buffers, since this command is defined to compare the
1749 the corresponding @samp{-wordwise} commands, narrows the variants to the
1759 If @code{t}, Ediff narrows the display to the appropriate range when it
1774 Ediff has variables to control the way fine differences are
1800 If auto-refining is on, this variable limits the size of the regions to
1816 region into words and then passing the result to
1824 and for the function @code{ediff-forward-word} for an explanation of how to
1846 This section describes variables that specify the programs to be used for
1856 These variables specify the programs to use to produce differences
1864 These variables specify the options to pass to the above utilities.
1866 In @code{ediff-diff-options}, it may be useful to specify options
1873 This variable specifies the coding system to use when reading the output
1874 that the programs @code{diff3} and @code{diff} send to Emacs. The default
1878 @code{raw-text-dos} might work. If not, you will have to experiment with
1882 The program to use to apply patches.  Since there are certain
1884 best way to stay out of trouble is to use a GNU-compatible version.
1885 Otherwise, you may have to tune the values of the variables
1889 Options to pass to @code{ediff-patch-program}.
1894 It is recommended to pass the @option{-f} option to the patch program,
1903 Backup directives to pass to the patch program.
1908 system-dependent.  Therefore, Ediff needs to know the backup extension used
1912 @var{extension}} to specify a backup file name extension.  Other
1914 extension @file{.orig}.  Yet others force you to use
1921 which extension to use.
1928 Because Ediff limits the options you may want to pass to the @code{diff}
1934 even have to be a standard-style @code{diff}!)@: is not used by Ediff.  It is
1936 refer to
1938 differences, you may want to send context differences to a colleague.
1940 @code{ediff-diff-program}, you would have to run @code{diff -c} separately
1941 just to produce the list of differences.  Fortunately,
1948 Specifies the default directory to look for patches.
1963 Merging is done according to the following algorithm.
1972 chooses the region according to the value of the variable
1978 @comment Use @set to avoid triggering merge conflict detectors like CVS.
2015 possible to add or delete region specifiers in this template (although
2016 the only possibly useful such modification seems to be the deletion of
2019 In addition to the state of the difference, Ediff displays the state of the
2022 @code{ediff-default-variant} was set to @code{default-A}) then
2034 In addition to the state of merge and state of difference indicators, while
2038 changes made to the original in variants A and B represent pure insertion
2053 ancestor buffer can be displayed by typing @kbd{/} to the control
2054 window.  (Type @kbd{C-l} to hide it again.)
2061 you copy a difference region from buffer A to buffer C then
2062 @samp{=diff(B)} will change to @samp{diff-A} and the mode line will
2064 region in buffer C is identical to that in buffer A, but originally
2065 buffer C's region came from buffer B@.  This is useful to know because
2070 Ediff never changes the state-of-merge indicator, except in response to
2080 makes no sense to recompute differences using the ancestor file, since
2082 B, but that you may have edited buffer C, and these changes are to be
2085 to tell where the various regions in the merge buffer came from.
2087 In three-way comparison, Ediff tries to disregard regions that consist
2094 only, then a message to this effect will be displayed.
2103 We don't recommend increasing the size of the merge-window to more than
2104 half the frame (i.e., to increase the value of
2105 @code{ediff-merge-window-share}) to more than 0.5, since it would be
2106 hard to see the contents of buffers A and B.
2108 You can temporarily shrink the merge window to just one line by
2109 typing @kbd{s}.  This change is temporary, until Ediff finds a reason to
2120 variable @code{ediff-show-clashes-only} to non-@code{nil}.
2125 commands.  You can still jump directly to any difference region directly
2132 The variable @code{ediff-autostore-merges} controls what happens to the
2134 to the merge buffer---it will be the user's responsibility to save it.
2135 If the value is @code{t}, the user will be asked where to save the buffer
2136 and whether to delete it afterwards.  It the value is neither @code{nil} nor
2147 set in a per-buffer manner.  Therefore, use @code{setq-default} to globally
2152 @code{ediff-autostore-merges}, Ediff attaches a prefix to each file, as
2170 package.  This is the standard Emacs interface to RCS, CVS, and SCCS.
2173 have to tell Ediff which version control package you are using, e.g.,
2179 to version control: @file{rcs.el}, @file{pcl-cvs.el} (recently renamed
2192 Ediff's interface to the above packages allows the user to compare the
2193 versions of the current buffer or to merge them (with or without an
2210 Ediff tries to be intelligent in choosing the mode line buffer
2215 @code{ediff-prepare-buffer-hook} to modify the mode line.
2229 (and file-C, if applicable).  It defaults to the vertical split
2230 (@code{split-window-vertically}, but you can set it to
2232 Ediff also lets you switch from vertical to horizontal split and back
2236 separate frames, it assumes that the user wants them to be so displayed
2237 and stops splitting windows.  Instead, it arranges for each buffer to
2238 be displayed in a separate frame.  You can switch to the one-frame mode
2249 to @code{split-window-horizontally} instead of
2254 The value is a function to be called to widen the frame for displaying
2257 recommended to look into the source of the default function
2269 default directory when it prompts the user for files to compare.  If
2278 behave like the @key{DEL} key, i.e., it will move you back to the previous
2280 window or a text-only terminal, the Backspace key is bound to @kbd{C-h} and is
2285 This variable's value is a function that Ediff uses to toggle
2290 version control, Ediff first tries to check the file out.
2299 be preserved when Ediff quits.  Setting this to @code{nil} causes Ediff to
2300 offer the user a chance to delete these buffers (if they are not modified).
2301 Supplying a prefix argument to the quit command (@code{q}) temporarily
2306 However, Ediff temporarily resets this variable to @code{t} if it is
2308 This is because it is all too easy to lose a day's work otherwise.
2310 prior to starting Ediff, so Ediff just preserves status quo here.
2320 to clean up and delete these version files.
2326 needs to type an Ediff command the focus will be in an appropriate Ediff's
2327 frame.  However, some users prefer to move the mouse by themselves.  The
2328 above variable, if set to @code{maybe}, will prevent Ediff from grabbing
2340 Some users need to customize Ediff in rather sophisticated ways, which
2345 local to the panel by calling make-local-variable from within
2351 @code{ediff-setup} sets the variables in the list to the respective
2352 values, locally in the Ediff control buffer.  This is an easy way to
2362 to functions that return help strings.
2371 not user-definable.  They are local to the Ediff control buffer, so this
2374 local to that buffer.  It is usually used for checking if the current buffer
2410 by emerge.el written by Dale R. Worley <drw@@math.mit.edu>.  An idea due to
2411 Boris Goldowsky <boris@@cs.rochester.edu> made it possible to highlight
2413 ported Ediff to XEmacs, Eric Freudenthal <freudent@@jan.ultra.nyu.edu>
2416 adapted it to the Emacs customization package.