\input texinfo @c -*-texinfo-*-@c documentation for Ediff@c Written by Michael Kifer@comment %**start of header (This is for running Texinfo on a region.)@comment Using ediff.info instead of ediff in setfilename breaks DOS.@comment @setfilename ediff@comment @setfilename ediff.info@setfilename ../info/ediff@settitle Ediff User's Manual@synindex vr cp@synindex fn cp@synindex pg cp@synindex ky cp@dircategory Emacs@direntry* Ediff: (ediff). A visual interface for comparing and merging programs.@end direntry@iftex@finalout@end iftex@c @smallbook@comment %**end of header (This is for running Texinfo on a region.)@ifinfoThis file documents Ediff, a comprehensive visual interface to diffand patch utilities.Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.Permission is granted to copy, distribute and/or modify this documentunder the terms of the GNU Free Documentation License, Version 1.1 orany later version published by the Free Software Foundation; with noInvariant Sections, with the Front-Cover texts being ``A GNUManual'', and with the Back-Cover Texts as in (a) below. A copy of thelicense is included in the section entitled ``GNU Free DocumentationLicense'' in the Emacs manual.(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modifythis GNU Manual, like GNU software. Copies published by the FreeSoftware Foundation raise funds for GNU development.''This document is part of a collection distributed under the GNU FreeDocumentation License. If you want to distribute this documentseparately from the collection, you can do so by adding a copy of thelicense to the document, as described in section 6 of the license.@end ifinfo@iftex@titlepage@title Ediff User's Manual@sp 4@subtitle Ediff version 2.70@sp 1@subtitle March 1998@sp 5@author Michael Kifer@page@vskip 0pt plus 1filll@noindentCopyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.Permission is granted to copy, distribute and/or modify this documentunder the terms of the GNU Free Documentation License, Version 1.1 orany later version published by the Free Software Foundation; with noInvariant Sections, with the Front-Cover texts being ``A GNUManual'', and with the Back-Cover Texts as in (a) below. A copy of thelicense is included in the section entitled ``GNU Free DocumentationLicense'' in the Emacs manual.(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modifythis GNU Manual, like GNU software. Copies published by the FreeSoftware Foundation raise funds for GNU development.''This document is part of a collection distributed under the GNU FreeDocumentation License. If you want to distribute this documentseparately from the collection, you can do so by adding a copy of thelicense to the document, as described in section 6 of the license.@end titlepage@page@end iftex@node Top, Introduction, (dir), (dir)@menu* Introduction:: About Ediff.* Major Entry Points:: How to use Ediff.* Session Commands:: Ediff commands used within a session.* Registry of Ediff Sessions:: Keeping track of multiple Ediff sessions.* Session Groups:: Comparing and merging directories.* Remote and Compressed Files:: You may want to know about this.* Customization:: How to make Ediff work the way YOU want.* Credits:: Thanks to those who helped.* Index::@end menu@node Introduction, Major Entry Points, Top, Top@chapter Introduction@cindex Comparing files and buffers@cindex Merging files and buffers@cindex Patching files and buffers@cindex Finding differencesEdiff provides a convenient way for simultaneous browsing throughthe differences between a pair (or a triple) of files or buffers(which are called @samp{variants} for our purposes). Thefiles being compared, file-A, file-B, and file-C (if applicable) areshown in separate windows (side by side, one above the another, or inseparate frames), and the differences are highlighted as you stepthrough them. You can also copy difference regions from one buffer toanother (and recover old differences if you change your mind).Another powerful feature is the ability to merge a pair of files into athird buffer. Merging with an ancestor file is also supported.Furthermore, Ediff is equipped with directory-level capabilities thatallow the user to conveniently launch browsing or merging sessions ongroups of files in two (or three) different directories.In addition, Ediff can apply a patch to a file and then let you step thoughboth files, the patched and the original one, simultaneously,difference-by-difference. You can even apply a patch right out of a mailbuffer, i.e., patches received by mail don't even have to be saved. SinceEdiff lets you copy differences between variants, you can, in effect, applypatches selectively (i.e., you can copy a difference region from@file{file.orig} to @file{file}, thereby undoing any particular patch thatyou don't like).Ediff even understands multi-file patches and can apply them interactively!(Ediff can recognize multi-file patches only if they are in the contextformat or GNU unified format. All other patches are treated as 1-filepatches. Ediff is [hopefully] using the same algorithm as @code{patch} todetermine which files need to be patched.)Ediff is aware of version control, which lets you comparefiles with their older versions. Ediff also works with remote andcompressed files, automatically ftp'ing them over and uncompressing them.@xref{Remote and Compressed Files}, for details.This package builds upon ideas borrowed from Emerge, and several of Ediff'sfunctions are adaptations from Emerge. Although Ediff subsumes and greatlyextends Emerge, much of the functionality in Ediff is influenced by Emerge.The architecture and the interface are, of course, drastically different.@node Major Entry Points, Session Commands, Introduction, Top@chapter Major Entry PointsWhen Ediff starts up, it displays a small control window, which accepts theEdiff commands and two or three windows displaying the files to be comparedor merged. The control window can be in its own small frame or it can bepart of a bigger frame that displays other buffers. In any case, it isimportant that the control window be active (i.e., be the one receiving thekeystrokes) when you use Ediff. You can switch to other Emacs buffers atwill and even edit the files currently being compared with Ediff and thenswitch back to Ediff at any time by activating the appropriate Emacs windows.Ediff can be invoked interactively using the following functions, which canbe 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:Compare, Merge, and Apply Patch.@table @code@item ediff-files@itemx ediff@findex ediff-files@findex ediffCompare two files.@item ediff-buffers@findex ediff-buffersCompare two buffers.@item ediff-files3@itemx ediff3@findex ediff-files3@findex ediff3Compare three files.@item ediff-buffers3@findex ediff-buffers3Compare three buffers.@item edirs@itemx ediff-directories@findex edirs@findex ediff-directories Compare files common to two directories.@item edirs3@itemx ediff-directories3@findex edirs3@findex ediff-directories3 Compare files common to three directories.@item edir-revisions@itemx ediff-directory-revisions@findex ediff-directory-revisions@findex edir-revisions Compare versions of files in a given directory. Ediff selects only thefiles that are under version control.@item edir-merge-revisions@itemx ediff-merge-directory-revisions@findex edir-merge-revisions@findex ediff-merge-directory-revisions Merge versions of files in a given directory. Ediff selects only thefiles that are under version control.@item edir-merge-revisions-with-ancestor@itemx ediff-merge-directory-revisions-with-ancestor@findex edir-merge-revisions-with-ancestor@findex ediff-merge-directory-revisions-with-ancestor Merge versions of files in a given directory using other versions asancestors. Ediff selects only the files that are under version control.@item ediff-windows-wordwise@findex ediff-windows-wordwiseCompare windows word-by-word.@item ediff-windows-linewise@findex ediff-windows-linewiseCompare windows line-by-line.@item ediff-regions-wordwise@findex ediff-regions-wordwiseCompare regions word-by-word.@item ediff-regions-linewise@findex ediff-regions-linewiseCompare regions line-by-line.@item ediff-revision@findex ediff-revision Compare versions of the current buffer, if the buffer is visiting a file under version control.@item ediff-patch-file@itemx epatch@findex ediff-patch-file@findex epatchPatch a file or multiple files, then compare. If the patch applies to justone file, Ediff will invoke a regular comparison session. If it is amulti-file patch, then a session group interface will be used and the userwill be able to patch the files selectively. @xref{Session Groups}, formore details.Since the patch might be in a buffer or a file, you will be asked which isthe case. To avoid this extra prompt, you can invoke this command with aprefix argument. With an odd prefix argument, Ediff assumes the patchis in a file; with an even argument, a buffer is assumed.Note that @code{ediff-patch-file} will actually use the @code{patch}utility to change the original files on disk. This is not thatdangerous, since you will always have the original contents of the filesaved in another file that has the extension @file{.orig}.Furthermore, if the file is under version control, then you can always backout to one of the previous versions (see the section on Version Countrol inEmacs manual).@code{ediff-patch-file} is careful about versions control: if the fileto be patched is checked in, then Ediff will offer to check it out, becausefailing to do so may result in the loss of the changes when the file ischecked out the next time.If you don't intend to modify the file via the patch and just want to seewhat the patch is all about (and decide later), then@code{ediff-patch-buffer} might be a better choice.@item ediff-patch-buffer@itemx epatch-buffer@findex ediff-patch-buffer@findex epatch-bufferPatch a buffer, then compare. The buffer being patched and the file visitedby that buffer (if any) is @emph{not} modified. The result of the patchappears in some other buffer that has the name ending with @emph{_patched}.This function would refuse to apply a multifile patch to a buffer. Use@code{ediff-patch-file} for that (and when you want the original file to bemodified by the @code{patch} utility).Since the patch might be in a buffer or a file, you will be asked which isthe case. To avoid this extra prompt, you can invoke this command with aprefix argument. With an odd prefix argument, Ediff assumes the patchis in a file; with an even argument, a buffer is assumed.@item ediff-merge-files@itemx ediff-merge@findex ediff-merge-files@findex ediff-mergeMerge two files.@item ediff-merge-files-with-ancestor@itemx ediff-merge-with-ancestor@findex ediff-merge-files-with-ancestor@findex ediff-merge-with-ancestorLike @code{ediff-merge}, but with a third ancestor file.@item ediff-merge-buffers@findex ediff-merge-buffersMerge two buffers.@item ediff-merge-buffers-with-ancestor@findex ediff-merge-buffers-with-ancestorSame but with ancestor.@item edirs-merge@itemx ediff-merge-directories@findex edirs-merge@findex ediff-merge-directories Merge files common to two directories.@item edirs-merge-with-ancestor@itemx ediff-merge-directories-with-ancestor@findex edirs-merge-with-ancestor@findex ediff-merge-directories-with-ancestor Same but using files in a third directory as ancestors. If a pair of files doesn't have an ancestor in the ancestor-directory, you will still be able to merge them without the ancestor.@item ediff-merge-revisions@findex ediff-merge-revisionsMerge two versions of the file visited by the current buffer.@item ediff-merge-revisions-with-ancestor@findex ediff-merge-revisions-with-ancestorSame but with ancestor.@item ediff-documentation@findex ediff-documentationBrings up this manual.@item ediff-show-registry@itemx eregistryBrings up Ediff session registry. This feature enables you to quickly findand restart active Ediff sessions.@end table@noindentIf you want Ediff to be loaded from the very beginning of your Emacssession, you should put this line in your @file{~/.emacs} file:@example(require 'ediff)@end example@noindentOtherwise, Ediff will be loaded automatically when you use one of theabove functions, either directly or through the menus.When the above functions are invoked, the user is prompted for all thenecessary information---typically the files or buffers to compare, merge, orpatch. Ediff tries to be smart about these prompts. For instance, incomparing/merging files, it will offer the visible buffers as defaults. Inprompting for files, if the user enters a directory, the previously inputfile name will be appended to that directory. In addition, if the variable@code{ediff-use-last-dir} is not @code{nil}, Ediff will offerpreviously entered directories as defaults (which will be maintainedseparately for each type of file, A, B, or C).@vindex @code{ediff-use-last-dir}All the above functions use the POSIX @code{diff} or @code{diff3} programsto find differences between two files. They process the @code{diff} outputand display it in a convenient form. At present, Ediff understands onlythe plain output from diff. Options such as @samp{-c} are not supported,nor is the format produced by incompatible file comparison programs such asthe VMS version of @code{diff}.The functions @code{ediff-files}, @code{ediff-buffers},@code{ediff-files3}, @code{ediff-buffers3} first display the coarse,line-based difference regions, as reported by the @code{diff} program. Thetotal number of difference regions and the current difference number arealways displayed in the mode line of the control window.Since @code{diff} may report fairly large chunks of text as being different,even though the difference may be localized to just a few words or evento the white space or line breaks, Ediff further @emph{refines} theregions to indicate which exact words differ. If the only difference isin the white space and line breaks, Ediff says so.On a color display, fine differences are highlighted with color; on amonochrome display, they are underlined. @xref{Highlighting DifferenceRegions}, for information on how to customize this.The functions @code{ediff-windows-wordwise},@code{ediff-windows-linewise}, @code{ediff-regions-wordwise} and@code{ediff-regions-linewise} do comparison on parts of existing Emacsbuffers. Since @code{ediff-windows-wordwise} and@code{ediff-regions-wordwise} are intended for relatively small segmentsof buffers, comparison is done on the basis of words rather than lines.No refinement is necessary in this case. These commands are recommendedonly for relatively small regions (perhaps, up to 100 lines), becausethese functions have a relatively slow startup.To compare large regions, use @code{ediff-regions-linewise}. Thiscommand displays differences much like @code{ediff-files} and@code{ediff-buffers}.The functions @code{ediff-patch-file} and @code{ediff-patch-buffer} apply apatch to a file or a buffer and then run Ediff on the appropriatefiles/buffers, displaying the difference regions.The entry points @code{ediff-directories}, @code{ediff-merge-directories},etc., provide a convenient interface for comparing and merging files indifferent directories. The user is presented with Dired-like interface fromwhich one can run a group of related Ediff sessions.For files under version control, @code{ediff-revision} lets you comparethe file visited by the current buffer to one of its checked-in versions.You can also compare two checked-in versions of the visited file.Moreover, the functions @code{ediff-directory-revisions},@code{ediff-merge-directory-revisions}, etc., let you run a group ofrelated Ediff sessions by taking a directory and comparing (or merging)versions of files in that directory.@node Session Commands, Registry of Ediff Sessions, Major Entry Points, Top@chapter Session CommandsAll Ediff commands are displayed in a Quick Help window, unless you type@kbd{?} to shrink the window to just one line. You can redisplay the helpwindow by typing @kbd{?} again. The Quick Help commands are detailed below.Many Ediff commands take numeric prefix arguments. For instance, if youtype a number, say 3, and then @kbd{j} (@code{ediff-jump-to-difference}),Ediff moves to the third difference region. Typing 3 and then @kbd{a}(@code{ediff-diff-to-diff}) copies the 3d difference region from variant Ato variant B. Likewise, 4 followed by @kbd{ra} restores the 4th differenceregion in buffer A (if it was previously written over via the command@kbd{a}).Some commands take negative prefix arguments as well. For instance, typing@kbd{-} and then @kbd{j} will make the last difference regioncurrent. Typing @kbd{-2} then @kbd{j} makes the penultimate differenceregion current, etc.Without the prefix argument, all commands operate on the currentlyselected difference region. You can make any difference regioncurrent using the various commands explained below.For some commands, the actual value of the prefix argument isimmaterial. However, if supplied, the prefix argument may modify thecommand (see @kbd{ga}, @kbd{gb}, and @kbd{gc}).@menu* Quick Help Commands:: Frequently used commands.* Other Session Commands:: Commands that are not bound to keys.@end menu@node Quick Help Commands,Other Session Commands,,Session Commands@section Quick Help Commands@table @kbd@item ?@kindex ?Toggles the Ediff Quick Help window ON and OFF.@item G@kindex GPrepares a mail buffer for sending a praise or a curse to the Ediff maintainer.@item E@kindex EBrings up the top node of this manual, where you can find furtherinformation on the various Ediff functions and advanced issues, such ascustomization, session groups, etc.@item v@kindex vScrolls up buffers A and B (and buffer C where appropriate) in acoordinated fashion.@item V@kindex VScrolls the buffers down.@item <@kindex <Scrolls the buffers to the left simultaneously.@item >@kindex >Scrolls buffers to the right.@item wd@kindex wdSaves the output from the diff utility, for further reference.With prefix argument, saves the plain output from @code{diff} (see@code{ediff-diff-program} and @code{ediff-diff-options}). Without theargument, it saves customized @code{diff} output (see@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options}), ifit is available.@item wa@kindex waSaves buffer A, if it was modified.@item wb@kindex wbSaves buffer B, if it was modified.@item wc@kindex wcSaves buffer C, if it was modified (if you are in a session thatcompares three files simultaneously).@item a@kindex a@emph{In comparison sessions:}Copies the current difference region (or the region specified as the prefixto this command) from buffer A to buffer B.Ediff saves the old contents of buffer B's region; it canbe restored via the command @kbd{rb}, which see.@emph{In merge sessions:}Copies the current difference region (or the region specified as the prefixto this command) from buffer A to the merge buffer. The old contents ofthis region in buffer C can be restored via the command @kbd{r}.@item b@kindex bWorks similarly, but copies the current difference region from buffer B tobuffer A (in @emph{comparison sessions}) or the merge buffer (in@emph{merge sessions}).Ediff saves the old contents of the difference region copied over; it canbe reinstated via the command @kbd{ra} in comparison sessions and@kbd{r} in merge sessions.@item ab@kindex abCopies the current difference region (or the region specified as the prefixto this command) from buffer A to buffer B. This (and the next five)command is enabled only in sessions that compare three filessimultaneously. The old region in buffer B is saved and can be restoredvia the command @kbd{rb}.@item ac@kindex acCopies 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 baCopies 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 bcCopies the difference region from buffer B to buffer C.The command @kbd{rc} undoes this.@item ca@kindex caCopies the difference region from buffer C to buffer A.The command @kbd{ra} undoes this.@item cb@kindex cbCopies the difference region from buffer C to buffer B.The command @kbd{rb} undoes this.@item p@itemx DEL@kindex p@kindex DELMakes the previous difference region current.@item n@itemx SPC@kindex n@kindex SPCMakes the next difference region current.@item j@itemx -j@itemx Nj@kindex jMakes the very first difference region current.@kbd{-j} makes the last region current. Typing a number, N, and then `j'makes the difference region N current. Typing -N (a negative number) then`j' makes current the region Last - N.@item ga@kindex gaMakes current the difference region closest to the position of the point inbuffer A.However, with a prefix argument, Ediff would position all variantsaround the area indicated by the current point in buffer A: ifthe point is inside a difference region, then the variants will bepositioned at this difference region. If the point is not in any differenceregion, then it is in an area where all variants agree with each other. Inthis case, the variants will be positioned so that each would display thisarea (of agreement).@item gb@kindex gbMakes current the difference region closest to the position of the point inbuffer 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.@emph{In 3-file comparison sessions:}makes current the region closest to the point in buffer C.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 oftenneeded because it is common to do all sorts of editing during Ediffsessions, so after a while, the highlighted difference regions may nolonger reflect the actual differences among the buffers.@item *@kindex *Forces refinement of the current difference region, which highlights the exactwords of disagreement among the buffers. With a negative prefix argument,unhighlights the current region.Forceful refinement may be needed if Ediff encounters a difference regionthat is larger than @code{ediff-auto-refine-limit}. In this situation,Ediff doesn't do automatic refinement in order to improve response time.(Ediff doesn't auto-refine on dumb terminals as well, but @kbd{*} stillworks there. However, the only useful piece of information it can tell youis whether or not the difference regions disagree only in the amount ofwhite space.)This command is also useful when the highlighted fine differences areno longer current, due to user editing.@item m@kindex mDisplays the current Ediff session in a frame as wide as the physicaldisplay. This is useful when comparing files side-by-side. Typing `m' againrestores the original size of the frame.@item |@kindex |Toggles the horizontal/vertical split of the Ediff display. Horizontalsplit is convenient when it is possible to compare filesside-by-side. If the frame in which files are displayed is too narrowand lines are cut off, typing @kbd{m} may help some.@item @@@kindex @@Toggles auto-refinement of difference regions (i.e., automatic highlightingof the exact words that differ among the variants). Auto-refinement isturned off on devices where Emacs doesn't support highlighting.On slow machines, it may be advantageous to turn auto-refinement off. Theuser can always forcefully refine specific difference regions by typing@kbd{*}.@item h@kindex hCycles between full highlighting, the mode where fine differences are nothighlighted (but computed), and the mode where highlighting is done withASCII strings. The latter is not really recommended, unless on a dumb TTY.@item r@kindex rRestores the old contents of the region in the merge buffer.(If you copied a difference region from buffer A or B into the merge bufferusing the commands @kbd{a} or @kbd{b}, Ediff saves the old contents of theregion in case you change your mind.)This command is enabled in merge sessions only.@item ra@kindex raRestores 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 incomparison sessions only.@item rb@kindex rbRestores 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 incomparison sessions only.@item rc@kindex rcRestores 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-filecomparison sessions only.@item ##@kindex ##Tell Ediff to skip over regions that disagree among themselves only in theamount of white space and line breaks.Even though such regions will be skipped over, you can still jump to anyone of them by typing the region number and then `j'. Typing @kbd{##}again puts Ediff back in the original state.@item #h@itemx #f@kindex #f@kindex #hEdiff works hard to ameliorate the effects of boredom in the workplace...Quite often differences are due to identical replacements (e.g., the word`foo' is replaced with the word `bar' everywhere). If the number of regionswith such boring differences exceeds your tolerance threshold, you may betempted to tell Ediff to skip these regions altogether (you will still be ableto jump to them via the command @kbd{j}). The above commands, @kbd{#h}and @kbd{#f}, may well save your day!@kbd{#h} prompts you to specify regular expressions for eachvariant. Difference regions where each variant's region matches thecorresponding regular expression will be skipped from then on. (You canalso tell Ediff to skip regions where at least one variant matches itsregular expression.)@kbd{#f} does dual job: it focuses on regions that match the correspondingregular expressions. All other regions will be skippedover. @xref{Selective Browsing}, for more.@item A@kindex AToggles 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 BToggles 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 CToggles 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 comparingthree buffers at once, then this command would rotate the windows amongbuffers A, B, and C.@item i@kindex iDisplays all kinds of useful data about the current Ediff session.@item D@kindex DRuns @code{ediff-custom-diff-program} on the variants and displays thebuffer containing the output. This is useful when you must send the outputto your Mom.With a prefix argument, displays the plain @code{diff} output.@xref{Patch and Diff Programs}, for details.@item R@kindex RDisplays a list of currently active Ediff sessions---the Ediff Registry.You can then restart any of these sessions by either clicking on a sessionrecord or by putting the cursor over it and then typing the return key.(Some poor souls leave so many active Ediff sessions around that they loosetrack of them completely... The `R' command is designed to save thesepeople from the recently discovered Ediff Proficiency Syndrome.)Typing @kbd{R} brings up Ediff Registry only if it is typed into an EdiffControl Panel. If you don't have a control panel handy, type this in theminibuffer: @kbd{M-x eregistry}. @xref{Registry of Ediff Sessions}.@item M@kindex MShows the session group buffer that invoked the current Ediff session.@xref{Session Groups}, for more information on session groups.@item z@kindex zSuspends the current Ediff session. (If you develop a condition known asRepetitive Ediff Injury---a serious but curable illness---you must changeyour current activity. This command tries hard to hide all Ediff-relatedbuffers.)The easiest way to resume a suspended Ediff session is through the registryof active sessions. @xref{Registry of Ediff Sessions}, for details.@item q@kindex qTerminates this Ediff session. With a prefix argument (e.g.,@kbd{1q}), asksif 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 youare comparing only parts of these buffers via the commands@code{ediff-windows-*} and @code{ediff-regions-*}, which see.@item C-l@kindex C-lRestores the usual Ediff window setup. This is the quickest way to resumean Ediff session, but it works only if the control panel of that session isvisible.@item $$@kindex $$While merging with an ancestor file, Ediff is determined to reduce user'swear and tear by saving him and her much of unproductive, repetitivetyping. If it notices that, say, file A's difference region is identical tothe same difference region in the ancestor file, then the merge buffer willautomatically get the difference region taken from buffer B. The rationaleis that this difference region in buffer A is as old as that in theancestor buffer, so the contents of that region in buffer B represents realchange.You may want to ignore such `obvious' merges and concentrate on differenceregions where both files `clash' with the ancestor, since this means thattwo different people have been changing this region independently and theyhad different ideas on how to do this.The above command does this for you by skipping the regions where only oneof the variants clashes with the ancestor but the other variant agrees withit. Typing @kbd{$$} again undoes this setting.@item $*@kindex $*When merging files with large number of differences, it is sometimesconvenient to be able to skip the difference regions for which you alreadydecided which variant is most appropriate. Typing @kbd{$*} will accomplishprecisely this.To be more precise, this toggles the check for whether the current merge isidentical to its default setting, as originally decided by Ediff. Forinstance, if Ediff is merging according to the `combined' policy, then themerge region is skipped over if it is different from the combination of theregions in buffers A and B. (Warning: swapping buffers A and B will confusethings in this respect). If the merge region is marked as `prefer-A' thenthis region will be skipped if it differs from the current differenceregion 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 fileon a difference region and the other doesn't, Ediff knows what to do: it copiesthe current difference region from the second buffer into the merge buffer.In other cases, the right course of action is not that clearcut, and Ediffwould use a default action. The above command changes the default action.The default action can be @samp{default-A} (choose the region from bufferA), @samp{default-B} (choose the region from buffer B), or @samp{combined}(combine the regions from the two buffers).@xref{Merging and diff3}, for further details.The command @kbd{&} also affects the regions in the merge buffers that have@samp{default-A}, @samp{default-B}, or @samp{combined} status, providedthey weren't changed with respect to the original. For instance, if such aregion has the status @samp{default-A} then changing the default action to@samp{default-B} will also replace this merge-buffer's region with thecorresponding region from buffer B.@item s@kindex sCauses the merge window shrink to its minimum size, thereby exposing as muchof the variant buffers as possible. Typing `s' again restoresthe original size of that window.With a positive prefix argument, this command enlarges the merge window.E.g., @kbd{4s} increases the size of the window by about 4 lines, ifpossible. With a negative numeric argument, the size of the merge windowshrinks by that many lines, if possible. Thus, @kbd{-s} shrinks the windowby about 1 line and @kbd{-3s} by about 3 lines.This command is intended only for temporary viewing; therefore, Ediffrestores window C to its original size whenever it makes any other changein the window configuration. However, redisplaying (@kbd{C-l}) or jumpingto another difference does not affect window C's size.The split between the merge window and the variant windows is controlled bythe variable @code{ediff-merge-window-share}, which see.@item +@kindex +Combines the difference regions from buffers A and B and copies theresult into the merge buffer. @xref{Merging and diff3}, and thevariables @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 beenedited 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 differenceregion, so the refinement feature of Ediff will not be able to tell youwhat exactly differs inside these chunks. Since eyeballing large pieces oftext is contrary to human nature, Ediff has a special command to helpreduce the risk of developing a cataract.The above command compares regions within Ediff buffers. This creates achild Ediff session for comparing current Emacs regions in buffers A, B, orC as follows:@emph{If you are comparing 2 files or buffers:}Ediff would compare current Emacs regions in buffers A and B.@emph{If you are comparing 3 files or buffers simultaneously:} Ediff wouldcompare the current Emacs regions in the buffers of your choice (you willbe asked which two of the three buffers to use).@emph{If you are merging files or buffers (with or without ancestor):}Ediff would take the current region in the merge buffer and compareit to the current region in the buffer of your choice (A or B).@emph{Note: In all these cases you must first switch to the appropriateEmacs buffers and manually set the regions that you want to compare.}Highlighting set by the parent Ediff session is removed, to avoid interferencewith 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.If you temporarily switch to the parent session, parent highlighting will berestored. If you then come back to the child session, you may want to removeparent highlighting, so it won't interfere. Typing @kbd{h} may help here.@end table@node Other Session Commands,,Quick Help Commands,Session Commands@section Other Session CommandsThe following commands can be invoked from within any Ediff session,although some of them are not bound to a key.@table @code@item eregistry@itemx ediff-show-registry@findex eregistry@findex ediff-show-registryThis command brings up the registry of active Ediff sessions. Ediffregistry is a device that can be used to resume any active Ediff session(which may have been postponed because the user switched to some otheractivity). This command is also useful for switching between multipleactive Ediff sessions that are run at the same time. The function@code{eregistry} is an alias for @code{ediff-show-registry}.@xref{Registry of Ediff Sessions}, for more information on this registry.@item ediff-toggle-multiframe@findex ediff-toggle-multiframeChanges the display from the multi-frame mode (where the quick help windowis in a separate frame) to the single-frame mode (where all Ediff buffersshare the same frame), and vice versa. See@code{ediff-window-setup-function} for details on how to make either ofthese modes the default one.This function can also be invoked from the Menubar. However, in somecases, the change will take place only after you execute one of the Ediffcommands, such as going to the next difference or redisplaying.@item ediff-revert-buffers-then-recompute-diffs@findex ediff-revert-buffers-then-recompute-diffsThis command reverts the buffers you are comparing and recomputes theirdifferences. It is useful when, after making changes, you decided tomake a fresh start, or if at some point you changed the files beingcompared but want to discard any changes to comparison buffers that weredone since then.This command normally asks for confirmation before reverting files.With a prefix argument, it reverts files without asking.@item ediff-profile@findex ediff-profileEdiff has an admittedly primitive (but useful) facility for profilingEdiff's commands. It is meant for Ediff maintenance---specifically, formaking it run faster. The function @code{ediff-profile} togglesprofiling of ediff commands.@end table@node Registry of Ediff Sessions, Session Groups, Session Commands, Top@chapter Registry of Ediff SessionsEdiff maintains a registry of all its invocations that arestill @emph{active}. This feature is very convenient for switching amongactive Ediff sessions or for quickly restarting a suspended Ediff session.The focal point of this activity is a buffercalled @emph{*Ediff Registry*}. You can display this buffer by typing@kbd{R} in any Ediff Control Buffer or Session Group Buffer(@pxref{Session Groups}), or by typing@kbd{M-x eregistry} into the Minibuffer.The latter would be the fastest way to bring up the registrybuffer if no control or group buffer is displayed in any of the visibleEmacs windows.If you are in a habit of running multiple long Ediff sessions and often need tosuspend, resume, or switch between them, it may be a good idea to have theregistry buffer permanently displayed in a separate, dedicated window.The registry buffer has several convenient key bindings.For instance, clicking mouse button 2 or typing@kbd{RET} or @kbd{v} over any session record resumes that session.Session records in the registry buffer provide a fairly completedescription of each session, so it is usually easy to identify the rightsession to resume.Other useful commands are bound to @kbd{SPC} (next registry record)and @kbd{DEL} (previous registry record). There are other commands as well,but you don't need to memorize them, since they are listed at the top ofthe registry buffer.@node Session Groups, Remote and Compressed Files, Registry of Ediff Sessions, Top@chapter Session GroupsSeveral major entries of Ediff perform comparison and merging ondirectories. On entering @code{ediff-directories},@code{ediff-directories3},@code{ediff-merge-directories},@code{ediff-merge-directories-with-ancestor},@code{ediff-directory-revisions},@code{ediff-merge-directory-revisions}, or@code{ediff-merge-directory-revisions-with-ancestor},the user is presented with aDired-like buffer that lists files common to the directories involved alongwith their sizes. (The list of common files can be further filtered througha regular expression, which the user is prompted for.) We call this buffer@emph{Session Group Panel} because all Ediff sessions associated with thelisted files will have this buffer as a common focal point.Clicking button 2 or typing @kbd{RET} or @kbd{v} over arecord describing files invokes Ediff in the appropriate mode on thesefiles. You can come back to the session group buffer associated with aparticular invocation of Ediff by typing @kbd{M} in Ediff control buffer ofthat invocation.Many commands are available in the session group buffer; some areapplicable only to certain types of work. The relevant commands are alwayslisted at the top of each session group buffer, so there is no need tomemorize them.In directory comparison or merging, a session group panel displays only thefiles common to all directories involved. The differences are kept in aseparate buffer and are conveniently displayed by typing @kbd{D} to thecorresponding session group panel. Thus, as an added benefit, Ediff can beused to compare the contents of up to three directories.Session records in session group panels are also marked with @kbd{+}, foractive sessions, and with @kbd{-}, 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 certainfiles in the group, and the corresponding session records just add clutterto the session group buffer. To help alleviate this problem, the user cantype @kbd{h} to mark a session as a candidate for exclusion and @kbd{x} toactually hide the marked sessions. There actions are reversible: with aprefix argument, @kbd{h} unmarks the session under the cursor, and @kbd{x}brings the hidden sessions into the view (@kbd{x} doesn't unmark them,though, so the user has to explicitly unmark the sessions of interest).Group sessions also understand the command @kbd{m}, which marks sessionsfor 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.@vindex ediff-autostore-mergesFor group sessions created to merge files, Ediff can store all mergesautomatically in a directory. The user is asked to specify such directoryif the value of @code{ediff-autostore-merges} is non-nil. If the value is@code{nil}, nothing is done to the merge buffers---it will be the user'sresponsibility to save them. If the value is @code{t}, the user will beasked where to save the merge buffers in all merge jobs, even those that donot originate from a session group. It the value is neither @code{nil} nor@code{t}, the merge buffer is saved @emph{only} if this merge session wasinvoked from a session group. This behavior is implemented in the function@code{ediff-maybe-save-and-delete-merge}, which is a hook in@code{ediff-quit-merge-hook}. The user can supply a different hook, ifnecessary.The variable @code{ediff-autostore-merges} is buffer-local, so it can beset on a per-buffer basis. Therefore, use @code{setq-default} to changethis variable globally.@cindex Multi-file patchesA multi-file patch is a concatenated output of several runs of the@code{diff} command (some versions of @code{diff} let you create amulti-file patch in just one run). Ediff facilitates creation ofmulti-file patches as follows. If you are in a session group buffercreated in response to @code{ediff-directories} or@code{ediff-directory-revisions}, you can mark (by typing @kbd{m}) thedesired Ediff sessions and then type @kbd{P} to create amulti-file patch of those marked sessions.Ediff will then display a buffer containing the patch.The patch is generated by invoking @code{diff} on all marked individualsessions (represented by files) and session groups (represented bydirectories). Ediff will also recursively descend into any @emph{unmarked}session group and will search for marked sessions there. In this way, youcan create multi-file patches that span file subtrees that grow out ofany given directory.In an @code{ediff-directories} session, it is enough to just mark therequisite sessions. In @code{ediff-directory-revisions} revisions, themarked sessions must also be active, or else Ediff will refuse to produce amulti-file patch. This is because, in the latter-style sessions, there aremany ways to create diff output, and it is easier to handle by runningEdiff on the inactive sessions.Last, but not least, by typing @kbd{=}, you can quickly find out whichsessions have identical files, so you won't have to run Ediff on thosesessions. This, however, works only on local, uncompressed files.For compressed or remote files, this command won't report anything.@node Remote and Compressed Files, Customization, Session Groups, Top@chapter Remote and Compressed FilesEdiff works with remote, compressed, and encrypted files. Ediffsupports @file{ange-ftp.el}, @file{jka-compr.el}, @file{uncompress.el}and @file{crypt++.el}, but it may work with other similar packages aswell. This means that you can compare files residing on anothermachine, or you can apply a patch to a file on another machine. Eventhe patch itself can be a remote file!When patching compressed or remote files, Ediff does not rename the sourcefile (unlike what the @code{patch} utility would usually do). Instead, thesource file retains its name and the result of applying the patch is placedin a temporary file that has the suffix @file{_patched} attached.Generally, this applies to files that are handled using black magic, suchas special file handlers (ange-ftp and some compression and encryptionpackages also use this method).Regular files are treated by the @code{patch} utility in the usual manner,i.e., the original is renamed into @file{source-name.orig} and the resultof the patch is placed into the file source-name (@file{_orig} is usedon systems like VMS, DOS, etc.)@node Customization, Credits, Remote and Compressed Files, Top@chapter CustomizationEdiff has a rather self-explanatory interface, and in most cases youwon't need to change anything. However, should the need arise, there areextensive facilities for changing the default behavior.Most of the customization can be done by setting various variables in the@file{.emacs} file. Some customization (mostly window-relatedcustomization and faces) can be done by putting appropriate lines in@file{.Xdefaults}, @file{.xrdb}, or whatever X resource file is in use.With respect to the latter, please note that the X resourcefor Ediff customization is `Ediff', @emph{not} `emacs'.@xref{Window and Frame Configuration},@xref{Highlighting Difference Regions}, for further details. Please alsorefer to Emacs manual for the information on how to set Emacs X resources.@menu* Hooks:: Customization via the hooks.* Quick Help Customization:: How to customize Ediff's quick help feature.* Window and Frame Configuration:: Controlling the way Ediff displays things.* Selective Browsing:: Advanced browsing through difference regions.* Highlighting Difference Regions:: Controlling highlighting.* Narrowing:: Comparing regions, windows, etc.* Refinement of Difference Regions:: How to control the refinement process.* Patch and Diff Programs:: Changing the utilities that compute differences and apply patches.* Merging and diff3:: How to customize Ediff in its Merge Mode.* Support for Version Control:: Changing the version control package. You are not likely to do that.* Customizing the Mode Line:: Changing the look of the mode line in Ediff.* Miscellaneous:: Other customization.* Notes on Heavy-duty Customization:: Customization for the gurus.@end menu@node Hooks, Quick Help Customization, Customization, Customization@section HooksThe bulk of customization can be done via the following hooks:@table @code@item ediff-load-hook@vindex ediff-load-hookThis hook can be used to change defaults after Ediff is loaded.@item ediff-before-setup-hook@vindex ediff-before-setup-hookHook that is run just before Ediff rearranges windows to its liking.Can be used to save windows configuration.@item ediff-keymap-setup-hook@vindex ediff-keymap-setup-hook@vindex ediff-mode-mapThis hook can be used to alter bindings in Ediff's keymap,@code{ediff-mode-map}. These hooks arerun right after the default bindings are set but before@code{ediff-load-hook}. The regular user needs not be concerned with thishook---it is provided for implementors of other Emacs packages built on topof Ediff.@item ediff-before-setup-windows-hook@itemx ediff-after-setup-windows-hook@vindex ediff-before-setup-windows-hook@vindex ediff-after-setup-windows-hookThese two hooks are called before and after Ediff sets up its windowconfiguration. These hooks are run each time Ediff rearranges windows toits liking. This happens whenever it detects that the user changed thewindows setup.@item ediff-suspend-hook@itemx ediff-quit-hook@vindex ediff-suspend-hook@vindex ediff-quit-hookThese two hooks are run when you suspend or quit Ediff. They can beused to set desired window configurations, delete files Ediff didn'twant to clean up after exiting, etc.By default, @code{ediff-quit-hook} holds one hook function,@code{ediff-cleanup-mess}, which cleans after Ediff, as appropriate inmost cases. You probably won't want to change it, but you mightwant to add other hook functions.Keep in mind that hooks executing before @code{ediff-cleanup-mess} startin @code{ediff-control-buffer;} they should also leave@code{ediff-control-buffer} as the current buffer when they finish.Hooks that are executed after @code{ediff-cleanup-mess} should expectthe current buffer be either buffer A or buffer B.@code{ediff-cleanup-mess} doesn't kill the buffers being compared ormerged (see @code{ediff-cleanup-hook}, below).@item ediff-cleanup-hook@vindex ediff-cleanup-hookThis hook is run just before @code{ediff-quit-hook}. This is a goodplace to do various cleanups, such as deleting the variant buffers.Ediff provides a function, @code{ediff-janitor}, as one such possiblehook, which you can add to @code{ediff-cleanup-hook} with@code{add-hooks}.@findex ediff-janitorThis function kills buffers A, B, and, possibly, C, if these buffers aren'tmodified. In merge jobs, buffer C is never deleted. However, the sideeffect of using this function is that you may not be able to compare thesame buffer in two separate Ediff sessions: quitting one of them willdelete this buffer in another session as well.@item ediff-quit-merge-hook@vindex ediff-quit-merge-hook@vindex ediff-autostore-merges@findex ediff-maybe-save-and-delete-mergeThis hook is called when Ediff quits a merge job. By default, the value is@code{ediff-maybe-save-and-delete-merge}, which is a function that attemptsto save the merge buffer according to the value of@code{ediff-autostore-merges}, as described later.@item ediff-before-setup-control-frame-hook@itemx ediff-after-setup-control-frame-hook@vindex ediff-before-setup-control-frame-hook@vindex ediff-after-setup-control-frame-hookThese two hooks run before and after Ediff sets up the control frame.They can be used to relocate Ediff control frame when Ediff runs in amultiframe mode (i.e., when the control buffer is in its own dedicatedframe). Be aware that many variables that drive Ediff are local toEdiff Control Panel (@code{ediff-control-buffer}), which requiresspecial care in writing these hooks. Take a look at@code{ediff-default-suspend-hook} and @code{ediff-default-quit-hook} tosee what's involved.@item ediff-startup-hook@vindex ediff-startup-hookThis hook is run at the end of Ediff startup.@item ediff-select-hook@vindex ediff-select-hookThis hook is run after Ediff selects the next difference region.@item ediff-unselect-hook@vindex ediff-unselect-hookThis hook is run after Ediff unselects the current difference region.@item ediff-prepare-buffer-hook@vindex ediff-prepare-buffer-hookThis hook is run for each Ediff buffer (A, B, C) right after the bufferis arranged.@item ediff-display-help-hook@vindex ediff-display-help-hookEdiff runs this hook each time after setting up the help message. Itcan be used to alter the help message for custom packages that run ontop of Ediff.@item ediff-mode-hook@vindex ediff-mode-hookThis hook is run just after Ediff mode is set up in the controlbuffer. This is done before any Ediff window is created. You can use it toset local variables that alter the look of the display.@item ediff-registry-setup-hook@vindex ediff-registry-setup-hookHooks run after setting up the registry for all active Ediff session.@xref{Session Groups}, for details.@item ediff-before-session-group-setup-hook@vindex ediff-before-session-group-setup-hookHooks run before setting up a control panel for a group of related Ediffsessions. Can be used, for example, to save window configuration to restorelater.@item ediff-after-session-group-setup-hook@vindex ediff-after-session-group-setup-hookHooks run after setting up a control panel for a group of related Ediffsessions. @xref{Session Groups}, for details.@item ediff-quit-session-group-hook@vindex ediff-quit-session-group-hookHooks run just before exiting a session group.@item ediff-meta-buffer-keymap-setup-hook@vindex ediff-meta-buffer-keymap-setup-hook@vindex ediff-meta-buffer-mapHooks run just after setting up the @code{ediff-meta-buffer-map} --- themap that controls key bindings in the meta buffer. Since@code{ediff-meta-buffer-map} is a local variable, you can set differentbindings for different kinds of meta buffers.@end table@node Quick Help Customization, Window and Frame Configuration, Hooks, Customization@section Quick Help Customization@vindex ediff-use-long-help-message@vindex ediff-control-buffer@vindex ediff-startup-hook@vindex ediff-help-messageEdiff provides quick help using its control panel window. Since this windowtakes a fair share of the screen real estate, you can toggle it off bytyping @kbd{?}. The control window will then shrink to just one line and amode line, displaying a short help message.The variable @code{ediff-use-long-help-message} tells Ediff whetheryou use the short message or the long one. By default, itis set to @code{nil}, meaning that the short message is used.Set this to @code{t}, if you want Ediff to use the longmessage by default. This property can always be changed interactively, bytyping @kbd{?} into Ediff Control Buffer.If you want to change the appearance of the help message on a per-bufferbasis, you must use @code{ediff-startup-hook} to change the value ofthe variable @code{ediff-help-message}, which is local to@code{ediff-control-buffer}.@node Window and Frame Configuration, Selective Browsing, Quick Help Customization, Customization@section Window and Frame ConfigurationOn a non-windowing display, Ediff sets things up in one frame, splittingit between a small control window and the windows for buffers A, B, and C.The split between these windows can be horizontal orvertical, which can be changed interactively by typing @kbd{|} while thecursor is in the control window.On a window display, Ediff sets up a dedicated frame for Ediff ControlPanel and then it chooses windows as follows: If one of the buffersis invisible, it is displayed in the currently selected frame. Ifa buffer is visible, it is displayed in the frame where it is visible.If, according to the above criteria, the two buffers fall into the sameframe, then so be it---the frame will be shared by the two. The samealgorithm works when you type @kbd{C-l} (@code{ediff-recenter}), @kbd{p}(@code{ediff-previous-difference}), @kbd{n}(@code{ediff-next-difference}), etc.The above behavior also depends on whether the current frame is splittable,dedicated, etc. Unfortunately, the margin of this book is too narrow topresent the details of this remarkable algorithm.The upshot of all this is that you can compare buffers in one frame orin different frames. The former is done by default, while the latter canbe achieved by arranging buffers A, B (and C, if applicable) to be seen indifferent frames. Ediff respects these arrangements, automaticallyadapting itself to the multi-frame mode.Ediff uses the following variables to set up its control panel(a.k.a.@: control buffer, a.k.a.@: quick help window):@table @code@item ediff-control-frame-parameters@vindex ediff-control-frame-parametersYou can change or augment this variable including the font, color,etc. The X resource name of Ediff Control Panel frames is @samp{Ediff}. UnderX-windows, you can use this name to set up preferences in your@file{~/.Xdefaults}, @file{~/.xrdb}, or whatever X resource file is inuse. Usually this is preferable to changing@code{ediff-control-frame-parameters} directly. For instance, you canspecify in @file{~/.Xdefaults} the color of the control frameusing the resource @samp{Ediff*background}.In general, any X resource pertaining the control frame can be reachedvia the prefix @code{Ediff*}.@item ediff-control-frame-position-function@vindex ediff-control-frame-position-functionThe preferred way of specifying the position of the control frame is bysetting the variable @code{ediff-control-frame-position-function} to anappropriate function.The default value of this variable is@code{ediff-make-frame-position}. This function places the control frame inthe vicinity of the North-East corner of the frame displaying buffer A.@findex ediff-make-frame-position@end tableThe following variables can be used to adjust the location produced by@code{ediff-make-frame-position} and for related customization.@table @code@item ediff-narrow-control-frame-leftward-shift@vindex ediff-narrow-control-frame-leftward-shiftSpecifies the number of characters for shiftingthe control frame from the rightmost edge of frame A when the controlframe is displayed as a small window.@item ediff-wide-control-frame-rightward-shift@vindex ediff-wide-control-frame-rightward-shiftSpecifies the rightward shift of the control framefrom the left edge of frame A when the control frame shows the fullmenu of options.@item ediff-control-frame-upward-shift@vindex ediff-control-frame-upward-shiftSpecifies the number of pixels for the upward shiftof the control frame.@item ediff-prefer-iconified-control-frame@vindex ediff-prefer-iconified-control-frameIf this variable is @code{t}, the control frame becomes iconifiedautomatically when you toggle the quick help message off. This savesvaluable real estate on the screen. Toggling help back will deiconifythe control frame.To start Ediff with an iconified Control Panel, you should set thisvariable to @code{t} and @code{ediff-prefer-long-help-message} to@code{nil} (@pxref{Quick Help Customization}). This behavior is usefulonly if icons are allowed to accept keybord input (which depend on thewindow manager and other factors).@end table@findex ediff-setup-windowsTo make more creative changes in the way Ediff sets up windows, you canrewrite the function @code{ediff-setup-windows}. However, we believethat detaching Ediff Control Panel from the rest and making it into aseparate frame offers an important opportunity by allowing you toiconify that frame. The icon will usually accept all of the Ediffcommands, but will free up valuable real estate on your screen (this maydepend on your window manager, though).The following variable controls how windows are set up:@table @code@item ediff-window-setup-function@vindex ediff-window-setup-functionThe multiframe setup is done by the@code{ediff-setup-windows-multiframe} function, which is the default onwindowing displays. The plain setup, one where all windows are alwaysin one frame, is done by @code{ediff-setup-windows-plain}, which is thedefault on a non-windowing display (or in an xterm window). In fact,under Emacs, you can switch freely between these two setups by executingthe command @code{ediff-toggle-multiframe} using the Minibuffer of theMenubar.@findex ediff-setup-windows-multiframe@findex ediff-setup-windows-plain@findex ediff-toggle-multiframeIf you don't like any of these setups, write your own function. See thedocumentation for @code{ediff-window-setup-function} for the basicguidelines. However, writing window setups is not easy, so you shouldfirst take a close look at @code{ediff-setup-windows-plain} and@code{ediff-setup-windows-multiframe}.@end tableYou can run multiple Ediff sessions at once, by invoking Ediff severaltimes without exiting previous Ediff sessions. Different sessionsmay even operate on the same pair of files.Each session has its own Ediff Control Panel and all the regarding aparticular session is local to the associated control panel buffer. Youcan switch between sessions by suspending one session and then switchingto another control panel. (Different control panel buffers aredistinguished by a numerical suffix, e.g., @samp{Ediff Control Panel<3>}.)@node Selective Browsing, Highlighting Difference Regions, Window and Frame Configuration, Customization@section Selective BrowsingSometimes it is convenient to be able to step through only some differenceregions, those that match certain regular expressions, and to ignore allothers. On other occasions, you may want to ignore difference regions thatmatch some regular expressions, and to look only at the rest.The commands @kbd{#f} and @kbd{#h} let you do precisely this.Typing @kbd{#f} lets you specify regular expressions that match differenceregions you want to focus on.We shall call these regular expressions @var{regexp-A}, @var{regexp-B} and@var{regexp-C}.Ediff will then start stepping through only those difference regionswhere the region in buffer A matches @var{regexp-A} and/or the region inbuffer B matches @var{regexp-B}, etc. Whether `and' or `or' will be useddepends on how you respond to a question.When scanning difference regions for the aforesaid regular expressions,Ediff narrows the buffers to those regions. This means that you can usethe expressions @kbd{\`} and @kbd{\'} to tie search to the beginning or endof the difference regions.On the other hand, typing @kbd{#h} lets you specify (hide) uninterestingregions. That is, if a difference region in buffer A matches@var{regexp-A}, the corresponding region in buffer B matches @var{regexp-B}and (if applicable) buffer C's region matches @var{regexp-C}, then theregion will be ignored by the commands @kbd{n}/@key{SPC}(@code{ediff-next-difference}) and @kbd{p}/@key{DEL}(@code{ediff-previous-difference}) commands.Typing @kbd{#f} and @kbd{#h} toggles selective browsing on and off.Note that selective browsing affects only @code{ediff-next-difference}and @code{ediff-previous-difference}, i.e., the commands@kbd{n}/@key{SPC} and @kbd{p}/@key{DEL}. @kbd{#f} and @kbd{#h} do notchange the position of the point in the buffers. And you can still jumpdirectly (using @kbd{j}) to any numbereddifference.Users can supply their own functions to specify how Ediff should doselective browsing. To change the default Ediff function, add a function to@code{ediff-load-hook} which will do the following assignments:@example(setq ediff-hide-regexp-matches-function 'your-hide-function)(setq ediff-focus-on-regexp-matches-function 'your-focus-function)@end example@strong{Useful hint}: To specify a regexp that matches everything, don'tsimply type @key{RET} in response to a prompt. Typing @key{RET} tells Ediffto accept the default value, which may not be what you want. Instead, youshould enter something like @key{^} or @key{$}. These match everyline.You can use the status command, @kbd{i}, to find out whetherselective browsing is currently in effect.The regular expressions you specified are kept in the local variables@code{ediff-regexp-focus-A}, @code{ediff-regexp-focus-B},@code{ediff-regexp-focus-C}, @code{ediff-regexp-hide-A},@code{ediff-regexp-hide-B}, @code{ediff-regexp-hide-C}. Their default valueis the empty string (i.e., nothing is hidden or focused on). To change thedefault, set these variables in @file{.emacs} using @code{setq-default}.In addition to the ability to ignore regions that match regularexpressions, Ediff can be ordered to start skipping over certain``uninteresting'' difference regions. This is controlled by the followingvariable:@table @code@item ediff-ignore-similar-regions@vindex ediff-ignore-similar-regionsIf @code{t}, causes Ediff to skip over "uninteresting" difference regions,which are the regions where the variants differ only in the amount of thewhite space and newlines. This feature can be toggled on/off interactively,via the command @kbd{##}.@end table@strong{Note:} In order for this feature to work, auto-refining ofdifference regions must be on, since otherwise Ediff won't know if thereare fine differences between regions. On devices where Emacs can displayfaces, auto-refining is a default, but it is not turned on by default ontext-only terminals. In that case, you must explicitly turn auto-refiningon (such as, by typing @kbd{@@}).@strong{Reassurance:} If many such uninteresting regions appear in a row,Ediff may take a long time to skip over them because it has to compute finedifferences of all intermediate regions. This delay does not indicate anyproblem.@node Highlighting Difference Regions, Narrowing, Selective Browsing, Customization@section Highlighting Difference RegionsThe following variables control the way Ediff highlights differenceregions:@table @code@item ediff-before-flag-bol@itemx ediff-after-flag-eol@itemx ediff-before-flag-mol@itemx ediff-after-flag-mol@vindex ediff-before-flag-bol@vindex ediff-after-flag-eol@vindex ediff-before-flag-mol@vindex ediff-after-flag-molThese variables hold strings that Ediff uses to mark the beginning and theend of the differences found in files A, B, and C on devices where Emacscannot display faces. Ediff uses different flags to highlight regions thatbegin/end at the beginning/end of a line or in a middle of a line.@item ediff-current-diff-face-A@itemx ediff-current-diff-face-B@itemx ediff-current-diff-face-C@vindex ediff-current-diff-face-A@vindex ediff-current-diff-face-B@vindex ediff-current-diff-face-CEdiff uses these faces to highlight current differences on devices whereEmacs can display faces. These and subsequently described faces can be seteither in @file{.emacs} or in @file{.Xdefaults}. The X resource for Ediffis @samp{Ediff}, @emph{not} @samp{emacs}. Please refer to Emacs manual forthe information on how to set X resources.@item ediff-fine-diff-face-A@itemx ediff-fine-diff-face-B@itemx ediff-fine-diff-face-C@vindex ediff-fine-diff-face-A@vindex ediff-fine-diff-face-B@vindex ediff-fine-diff-face-CEdiff uses these faces to show the fine differences between the currentdifferences regions in buffers A, B, and C, respectively.@item ediff-even-diff-face-A@itemx ediff-even-diff-face-B@itemx ediff-even-diff-face-C@itemx ediff-odd-diff-face-A@itemx ediff-odd-diff-face-B@itemx ediff-odd-diff-face-C@vindex ediff-even-diff-face-A@vindex ediff-even-diff-face-B@vindex ediff-even-diff-face-C@vindex ediff-odd-diff-face-A@vindex ediff-odd-diff-face-B@vindex ediff-odd-diff-face-CNon-current difference regions are displayed using these alternatingfaces. The odd and the even faces are actually identical on monochromedisplays, because without colors options are limited.So, Ediff uses italics to highlight non-current differences.@item ediff-force-faces@vindex ediff-force-facesEdiff generally can detect when Emacs is running on a device where it canuse highlighting with faces. However, if it fails to determine that facescan be used, the user can set this variable to @code{t} to make sure thatEdiff uses faces to highlight differences.@item ediff-highlight-all-diffs@vindex ediff-highlight-all-diffsIndicates whether---on a windowind display---Ediff should highlightdifferences using inserted strings (as on text-only terminals) or usingcolors and highlighting. Normally, Ediff highlights all differences, butthe selected difference is highlighted more visibly. One can cycle throughvarious modes of highlighting by typing @kbd{h}. By default, Ediff startsin the mode where all difference regions are highlighted. If you prefer tostart in the mode where unselected differences are not highlighted, youshould set @code{ediff-highlight-all-diffs} to @code{nil}. Type @kbd{h} torestore highlighting for all differences.Ediff lets you switch between the two modes of highlighting. That is,you can switch interactively from highlighting using faces tohighlighting using string flags, and back. Of course, switching haseffect only under a windowing system. On a text-only terminal or in anxterm window, the only available option is highlighting with strings.@end table@noindentIf you want to change the default settings for @code{ediff-force-faces} and@code{ediff-highlight-all-diffs}, you must do it @strong{before} Ediff isloaded.You can also change the defaults for the faces used to highlight thedifference regions. There are two ways to do this. The simplest and thepreferred way is to use the customization widget accessible from themenubar. Ediff's customization group is located under "Tools", which inturn is under "Programming". The faces that are used to highlightdifference regions are located in the "Highlighting" subgroup of the Ediffcustomization group.The second, much more arcane, method to change default faces is to includesome Lisp code in @file{~/.emacs}. For instance,@example(setq ediff-current-diff-face-A (copy-face 'bold-italic 'ediff-current-diff-face-A))@end example@noindentwould use the pre-defined fase @code{bold-italic} to highlight the currentdifference region in buffer A (this face is not a good choice, by the way).If you are unhappy with just @emph{some} of the aspects of the defaultfaces, you can modify them when Ediff is being loaded using@code{ediff-load-hook}. For instance:@smallexample(add-hook 'ediff-load-hook (lambda () (set-face-foreground ediff-current-diff-face-B "blue") (set-face-background ediff-current-diff-face-B "red") (make-face-italic ediff-current-diff-face-B)))@end smallexample@strong{Note:} To set Ediff's faces, use only @code{copy-face} or@code{set/make-face-@dots{}} as shown above. Emacs' low-levelface-manipulation functions should be avoided.@node Narrowing, Refinement of Difference Regions, Highlighting Difference Regions, Customization@section NarrowingIf buffers being compared are narrowed at the time of invocation ofEdiff, @code{ediff-buffers} will preserve the narrowing range. However,if @code{ediff-files} is invoked on the files visited by these buffers,that would widen the buffers, since this command is defined to compare theentire files.Calling @code{ediff-regions-linewise} or @code{ediff-windows-linewise}, orthe corresponding @samp{-wordwise} commands, narrows the variants to theparticular regions being compared. The original accessible ranges arerestored when you quit Ediff. During the command, you can toggle thisnarrowing on and off with the @kbd{%} command.These two variables control this narrowing behavior:@table @code@item ediff-start-narrowed@vindex ediff-start-narrowedIf @code{t}, Ediff narrows the display to the appropriate range when itis invoked with an @samp{ediff-regions@dots{}} or@samp{ediff-windows@dots{}} command. If @code{nil}, these commands donot automatically narrow, but you can still toggle narrowing on and offby typing @kbd{%}.@item ediff-quit-widened@vindex ediff-quit-widenedControls whether on quitting Ediff should restore the accessible rangethat existed before the current invocation.@end table@node Refinement of Difference Regions, Patch and Diff Programs, Narrowing, Customization@section Refinement of Difference RegionsEdiff has variables to control the way fine differences arehighlighted. This feature gives you control over the process of refinement.Note that refinement ignores spaces, tabs, and newlines.@table @code@item ediff-auto-refine@vindex ediff-auto-refineThis variable controls whether fine differences within regions arehighlighted automatically (``auto-refining''). The default is yes(@samp{on}).On a slow machine, automatic refinement may be painful. In that case,you can turn auto-refining on or off interactively by typing@kbd{@@}. You can also turn off display of refining that hasalready been done.When auto-refining is off, fine differences are shown only for regionsfor which these differences have been computed and saved before. Ifauto-refining and display of refining are both turned off, finedifferences are not shown at all.Typing @kbd{*} computes and displays fine differences for the currentdifference region, regardless of whether auto-refining is turned on.@item ediff-auto-refine-limit@vindex ediff-auto-refine-limitIf auto-refining is on, this variable limits the size of the regions tobe auto-refined. This guards against the possible slowdown that may becaused by extraordinary large difference regions.You can always refine the current region by typing @kbd{*}.@item ediff-forward-word-function@vindex ediff-forward-word-functionThis variable controls how fine differences are computed. Thevalue must be a Lisp function that determines how the current differenceregion should be split into words.@vindex ediff-diff-program@vindex ediff-forward-word-function@findex ediff-forward-wordFine differences are computed by first splitting the current differenceregion into words and then passing the result to@code{ediff-diff-program}. For the default forward word function (which is@code{ediff-forward-word}), a word is a string consisting of letters,@samp{-}, or @samp{_}; a string of punctuation symbols; a string of digits,or a string consisting of symbols that are neither space, nor a letter.This default behavior is controlled by four variables: @code{ediff-word-1},..., @code{ediff-word-4}. See the on-line documentation for these variablesand for the function @code{ediff-forward-word} for an explanation of how tomodify these variables.@vindex ediff-word-1@vindex ediff-word-2@vindex ediff-word-3@vindex ediff-word-4@end tableSometimes, when a region has too many differences between the variants,highlighting of fine differences is inconvenient, especially oncolor displays. If that is the case, type @kbd{*} with a negativeprefix argument. This unhighlights fine differences for the currentregion.To unhighlight fine differences in all difference regions, use thecommand @kbd{@@}. Repeated typing of this key cycles through threedifferent states: auto-refining, no-auto-refining, and no-highlightingof fine differences.@node Patch and Diff Programs, Merging and diff3, Refinement of Difference Regions, Customization@section Patch and Diff ProgramsThis section describes variables that specify the programs to be used forapplying patches and for computing the main difference regions (not thefine difference regions):@table @code@item ediff-diff-program@itemx ediff-diff3-program@vindex ediff-patch-program@vindex ediff-diff-program@vindex ediff-diff3-programThese variables specify the programs to use to produce differencesand do patching.@item ediff-diff-options@itemx ediff-diff3-options@vindex ediff-patch-options@vindex ediff-diff-options@vindex ediff-diff3-optionsThese variables specify the options to pass to the above utilities.In @code{ediff-diff-options}, it may be useful to specify optionssuch as @samp{-w} that ignore certain kinds of changes. However,Ediff does not let you use the option @samp{-c}, as it doesn't recognize thisformat yet.@item ediff-coding-system-for-read@vindex ediff-coding-system-for-readThis variable specifies the coding system to use when reading the outputthat the programs @code{diff3} and @code{diff} send to Emacs. The defaultis @code{raw-text}, and this should work fine on GNU, Unix, and in mostcases under Windows NT/95/98/2000. There are @code{diff} programsfor which the default option doesn't work under Windows. In such cases,@code{raw-text-dos} might work. If not, you will have to experiment withother coding systems or use GNU diff.@item ediff-patch-programThe program to use to apply patches. Since there are certainincompatibilities between the different versions of the patch program, thebest way to stay out of trouble is to use a GNU-compatible version.Otherwise, you may have to tune the values of the variables@code{ediff-patch-options}, @code{ediff-backup-specs}, and@code{ediff-backup-extension} as described below.@item ediff-patch-optionsOptions to pass to @code{ediff-patch-program}.Note: the `-b' and `-z' options should be specified in`ediff-backup-specs', not in @code{ediff-patch-options}.It is recommended to pass the `-f' option to the patch program, so it won'task questions. However, some implementations don't accept this option, inwhich case the default value of this variable should be changed.@item ediff-backup-extensionBackup extension used by the patch program. Must be specified, even if@code{ediff-backup-specs} is given.@item ediff-backup-specsBackup directives to pass to the patch program.Ediff requires that the old version of the file (before applying the patch)is saved in a file named @file{the-patch-file.extension}. Usually`extension' is `.orig', but this can be changed by the user, and may also besystem-dependent. Therefore, Ediff needs to know the backup extension usedby the patch program.Some versions of the patch program let the user specify `-b backup-extension'.Other versions only permit `-b', which (usually) assumes the extension `.orig'.Yet others force you to use `-z<backup-extension>'.Note that both `ediff-backup-extension' and `ediff-backup-specs' must beproperly set. If your patch program takes the option `-b', but not`-b extension', the variable `ediff-backup-extension' must stillbe set so Ediff will know which extension to use.@item ediff-custom-diff-program@itemx ediff-custom-diff-options@vindex ediff-custom-diff-program@vindex ediff-custom-diff-options@findex ediff-save-bufferBecause Ediff limits the options you may want to pass to the @code{diff}program, it partially makes up for this drawback by letting you save theoutput from @code{diff} in your preferred format, which is specified viathe above two variables.The output generated by @code{ediff-custom-diff-program} (which doesn'teven have to be a standard-style @code{diff}!)@: is not used by Ediff. It isprovided exclusively so that you canrefer toit later, send it over email, etc. For instance, after reviewing thedifferences, you may want to send context differences to a colleague.Since Ediff ignores the @samp{-c} option in@code{ediff-diff-program}, you would have to run @code{diff -c} separatelyjust to produce the list of differences. Fortunately,@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options}eliminate this nuisance by keeping a copy of a difference list in thedesired format in a buffer that can be displayed via the command @kbd{D}.@item ediff-patch-default-directory@vindex ediff-patch-default-directorySpecifies the default directory to look for patches.@end table@noindent@strong{Warning:} Ediff does not support the output format of VMS@code{diff}. Instead, make sure you are using some implementation of POSIX@code{diff}, such as @code{gnudiff}.@node Merging and diff3, Support for Version Control, Patch and Diff Programs, Customization@section Merging and diff3Ediff supports three-way comparison via the functions @code{ediff-files3} and@code{ediff-buffers3}. The interface is the same as for two-way comparison.In three-way comparison and merging, Ediff reports if any two differenceregions are identical. For instance, if the current region in buffer Ais the same as the region in buffer C, then the mode line of buffer A willdisplay @samp{[=diff(C)]} and the mode line of buffer C will display@samp{[=diff(A)]}.Merging is done according to the following algorithm.If a difference region in one of the buffers, say B, differs from the ancestorfile while the region in the other buffer, A, doesn't, then the merge buffer,C, gets B's region. Similarly when buffer A's region differs fromthe ancestor and B's doesn't, A's region is used.@vindex ediff-default-variantIf both regions in buffers A and B differ from the ancestor file, Ediffchooses the region according to the value of the variable@code{ediff-default-variant}. If its value is @code{default-A} then A'sregion is chosen. If it is @code{default-B} then B's region is chosen.If it is @code{combined} then the region in buffer C will look likethis:@comment Use @set to avoid triggering merge conflict detectors like CVS.@set seven-left <<<<<<<@set seven-right >>>>>>>@example@value{seven-left} variant Athe difference region from buffer A@value{seven-right} variant Bthe difference region from buffer B####### Ancestorthe difference region from the ancestor buffer, if available======= end@end exampleThe above is the default template for the combined region. The user cancustomize this template using the variable@code{ediff-combination-pattern}.@vindex ediff-combination-patternThe variable @code{ediff-combination-pattern} specifies the template thatdetermines how the combined merged region looks like. The template isrepresented as a list of the form @code{(STRING1 Symbol1 STRING2 Symbol2STRING3 Symbol3 STRING4)}. The symbols here must be atoms of the form@code{A}, @code{B}, or @code{Ancestor}. They determine the order in whichthe corresponding difference regions (from buffers A, B, and the ancestorbuffer) are displayed in the merged region of buffer C. The strings in thetemplate determine the text that separates the aforesaid regions. Thedefault template is@smallexample("@value{seven-left} variant A" A "@value{seven-right} variant B" B "####### Ancestor" Ancestor "======= end")@end smallexample@noindent(this is one long line) and the corresponding combined region is shownabove. The order in which the regions are shown (and the separatorstrings) can be changed by changing the above template. It is evenpossible to add or delete region specifiers in this template (althoughthe only possibly useful such modification seems to be the deletion ofthe ancestor).In addition to the state of the difference, Ediff displays the state of themerge for each region. If a difference came from buffer A by default(because both regions A and B were different from the ancestor and@code{ediff-default-variant} was set to @code{default-A}) then@samp{[=diff(A) default-A]} is displayed in the mode line. If thedifference in buffer C came, say, from buffer B because the differenceregion in that buffer differs from the ancestor, but the region in buffer Adoes not (if merging with an ancestor) then @samp{[=diff(B) prefer-B]} isdisplayed. The indicators default-A/B and prefer-A/B are inspired byEmerge and have the same meaning.Another indicator of the state of merge is @samp{combined}. It appearswith any difference region in buffer C that was obtained by combiningthe difference regions in buffers A and B as explained above.In addition to the state of merge and state of difference indicators, whilemerging with an ancestor file or buffer, Ediff informs the user when thecurrent difference region in the (normally invisible) ancestor buffer isempty via the @emph{AncestorEmpty} indicator. This helps determine if thechanges made to the original in variants A and B represent pure insertionor deletion of text: if the mode line shows @emph{AncestorEmpty} and thecorresponding region in buffers A or B is not empty, this means that newtext was inserted. If this indicator is not present and the differenceregions in buffers A or B are non-empty, this means that text wasmodified. Otherwise, the original text was deleted.Although the ancestor buffer is normally invisible, Ediff maintainsdifference regions there and advances the current difference regionaccordingly. All highlighting of difference regions is provided in theancestor buffer, except for the fine differences. Therefore, if desired, theuser can put the ancestor buffer in a separate frame and watch itthere. However, on a TTY, only one frame can be visible at any given time,and Ediff doesn't support any single-frame window configuration where allbuffers, including the ancestor buffer, would be visible. However, theancestor buffer can be displayed by typing @kbd{/} to the controlwindow. (Type @kbd{C-l} to hide it again.)Note that the state-of-difference indicators @samp{=diff(A)} and@samp{=diff(B)} above are not redundant, even in the presence of astate-of-merge indicator. In fact, the two serve different purposes.For instance, if the mode line displays @samp{=diff(B) prefer(B)} andyou copy a difference region from buffer A to buffer C then@samp{=diff(B)} will change to @samp{diff-A} and the mode line willdisplay @samp{=diff(A) prefer-B}. This indicates that the differenceregion in buffer C is identical to that in buffer A, but originallybuffer C's region came from buffer B. This is useful to know becauseyou can recover the original difference region in buffer C by typing@kbd{r}.Ediff never changes the state-of-merge indicator, except in response tothe @kbd{!} command (see below), in which case the indicator is lost.On the other hand, the state-of-difference indicator is changedautomatically by the copying/recovery commands, @kbd{a}, @kbd{b}, @kbd{r},@kbd{+}.The @kbd{!} command loses the information about origins of the regionsin the merge buffer (default-A, prefer-B, or combined). This is becauserecomputing differences in this case means running @code{diff3} onbuffers A, B, and the merge buffer, not on the ancestor buffer. (Itmakes no sense to recompute differences using the ancestor file, sincein the merging mode Ediff assumes that you have not edited buffers A andB, but that you may have edited buffer C, and these changes are to bepreserved.) Since some difference regions may disappear as a result ofediting buffer C and others may arise, there is generally no simple wayto tell where the various regions in the merge buffer came from.In three-way comparison, Ediff tries to disregard regions that consistentirely of white space. For instance, if, say, the current region inbuffer A consists of the white space only (or if it is empty), Ediff willnot take it into account for the purpose of computing fine differences. Theresult is that Ediff can provide a better visual information regarding theactual fine differences in the non-white regions in buffers B andC. Moreover, if the regions in buffers B and C differ in the white spaceonly, then a message to this effect will be displayed.@vindex ediff-merge-window-shareIn the merge mode, the share of the split between window C (the windowdisplaying the merge-buffer) and the windows displaying buffers A and Bis controlled by the variable @code{ediff-merge-window-share}. Itsdefault value is 0.5. To make the merge-buffer window smaller, reducethis amount.We don't recommend increasing the size of the merge-window to more thanhalf the frame (i.e., to increase the value of@code{ediff-merge-window-share}) to more than 0.5, since it would behard to see the contents of buffers A and B.You can temporarily shrink the merge window to just one line bytyping @kbd{s}. This change is temporary, until Ediff finds a reason toredraw the screen. Typing @kbd{s} again restores the original window size.With a positive prefix argument, the @kbd{s} command will make the mergewindow slightly taller. This change is persistent. With `@kbd{-}' orwith a negative prefix argument, the command @kbd{s} makes the mergewindow slightly shorter. This change also persistent.@vindex ediff-show-clashes-onlyEdiff lets you automatically ignore the regions where only one of thebuffers A and B disagrees with the ancestor. To do this, set thevariable @code{ediff-show-clashes-only} to non-@code{nil}.You can toggle this feature interactively by typing @kbd{$$}.Note that this variable affects only the show next/previous differencecommands. You can still jump directly to any difference region directlyusing the command @kbd{j} (with a prefix argument specifying the differencenumber).@vindex ediff-autostore-merges@vindex ediff-quit-merge-hook@findex ediff-maybe-save-and-delete-mergeThe variable @code{ediff-autostore-merges} controls what happens to themerge buffer when Ediff quits. If the value is @code{nil}, nothing is doneto the merge buffer---it will be the user's responsibility to save it.If the value is @code{t}, the user will be asked where to save the bufferand whether to delete it afterwards. It the value is neither @code{nil} nor@code{t}, the merge buffer is saved @emph{only} if this merge session wasinvoked from a group of related Ediff session, such as those that resultfrom @code{ediff-merge-directories},@code{ediff-merge-directory-revisions}, etc.@xref{Session Groups}. This behavior is implemented in the function@code{ediff-maybe-save-and-delete-merge}, which is a hook in@code{ediff-quit-merge-hook}. The user can supply a different hook, ifnecessary.The variable @code{ediff-autostore-merges} is buffer-local, so it can beset in a per-buffer manner. Therefore, use @code{setq-default} to globallychange this variable.@vindex ediff-merge-filename-prefixWhen merge buffers are saved automatically as directed by@code{ediff-autostore-merges}, Ediff attaches a prefix to each file, asspecified by the variable @code{ediff-merge-filename-prefix}. The defaultis @code{merge_}, but this can be changed by the user.@node Support for Version Control, Customizing the Mode Line, Merging and diff3, Customization@section Support for Version ControlEdiff supports version control and lets you compare versions of filesvisited by Emacs buffers via the function @code{ediff-revision}. Thisfeature is controlled by the following variables:@table @code@item ediff-version-control-package@vindex ediff-version-control-packageA symbol. The default is @samp{vc}.If you are like most Emacs users, Ediff will use VC as the version controlpackage. This is the standard Emacs interface to RCS, CVS, and SCCS.However, if your needs are better served by other interfaces, you willhave to tell Ediff which version control package you are using, e.g.,@example(setq ediff-version-control-package 'rcs)@end exampleApart from the standard @file{vc.el}, Ediff supports three other interfacesto version control: @file{rcs.el}, @file{pcl-cvs.el} (recently renamedpcvs.el), and @file{generic-sc.el}. The package @file{rcs.el} is writtenby Sebastian Kremer <sk@@thp.Uni-Koeln.DE> and is available as@example@file{ftp.cs.buffalo.edu:pub/Emacs/rcs.tar.Z}@file{ftp.uni-koeln.de:/pub/gnu/emacs/rcs.tar.Z}@end example@pindex @file{vc.el}@pindex @file{rcs.el}@pindex @file{pcl-cvs.el}@pindex @file{generic-sc.el}@end tableEdiff's interface to the above packages allows the user to compare theversions of the current buffer or to merge them (with or without anancestor-version). These operations can also be performed on directoriescontaining files under version control.In case of @file{pcl-cvs.el}, Ediff can also be invoked via the function@code{run-ediff-from-cvs-buffer}---see the documentation string for thisfunction.@node Customizing the Mode Line, Miscellaneous, Support for Version Control, Customization@section Customizing the Mode LineWhen Ediff is running, the mode line of @samp{Ediff Control Panel}buffer shows the current difference number and the total number ofdifference regions in the two files.The mode line of the buffers being compared displays the type of thebuffer (@samp{A:}, @samp{B:}, or @samp{C:}) and (usually) the file name.Ediff tries to be intelligent in choosing the mode line bufferidentification. In particular, it works well with the@file{uniquify.el} and @file{mode-line.el} packages (which improve onthe default way in which Emacs displays buffer identification). If youdon't like the way Ediff changes the mode line, you can use@code{ediff-prepare-buffer-hook} to modify the mode line.@vindex ediff-prepare-buffer-hook@pindex @file{uniquify.el}@pindex @file{mode-line.el}@node Miscellaneous, Notes on Heavy-duty Customization, Customizing the Mode Line, Customization@section MiscellaneousHere are a few other variables for customizing Ediff:@table @code@item ediff-split-window-function@vindex ediff-split-window-functionControls the way you want the window be split between file-A and file-B(and file-C, if applicable). It defaults to the vertical split(@code{split-window-vertically}, but you can set it to@code{split-window-horizontally}, if you so wish.Ediff also lets you switch from vertical to horizontal split and backinteractively.Note that if Ediff detects that all the buffers it compares are displayed inseparate frames, it assumes that the user wants them to be so displayedand stops splitting windows. Instead, it arranges for each buffer tobe displayed in a separate frame. You can switch to the one-frame modeby hiding one of the buffers A/B/C.You can also swap the windows where buffers are displayed by typing@kbd{~}.@item ediff-merge-split-window-function@vindex ediff-merge-split-window-functionControls how windows aresplit between buffers A and B in the merge mode.This variable is like @code{ediff-split-window-function}, but it defaultsto @code{split-window-horizontally} instead of@code{split-window-vertically}.@item ediff-make-wide-display-function@vindex ediff-make-wide-display-functionThe value is a function to be called to widen the frame for displayingthe Ediff buffers. See the on-line documentation for@code{ediff-make-wide-display-function} for details. It is alsorecommended to look into the source of the default function@code{ediff-make-wide-display}.You can toggle wide/regular display by typing @kbd{m}. In the widedisplay mode, buffers A, B (and C, when applicable) are displayed in asingle frame that is as wide as the entire workstation screen. This isuseful when files are compared side-by-side. By default, the display iswidened without changing its height.@item ediff-use-last-dir@vindex ediff-use-last-dirControls the way Ediff presents thedefault directory when it prompts the user for files to compare. If@code{nil},Ediff uses the default directory of the current buffer when itprompts the user for file names. Otherwise, it will use thedirectories it had previously used for files A, B, or C, respectively.@item ediff-no-emacs-help-in-control-buffer@vindex ediff-no-emacs-help-in-control-bufferIf @code{t}, makes @kbd{C-h}behave like the @key{DEL} key, i.e., it will move you back to the previousdifference rather than invoking help. This is useful when, in an xtermwindow or a text-only terminal, the Backspace key is bound to @kbd{C-h} and ispositioned more conveniently than the @key{DEL} key.@item ediff-toggle-read-only-function@vindex ediff-toggle-read-only-functionThis variable's value is a function that Ediff uses to togglethe read-only property in its buffers.The default function that Ediff uses simply toggles the read-only property,unless the file is under version control. For a checked-in file underversion control, Ediff first tries to check the file out.@item ediff-make-buffers-readonly-at-startup nil@vindex ediff-make-buffers-readonly-at-startupIf t, all variant buffers are made read-only at Ediff startup.@item ediff-keep-variants@vindex @code{ediff-keep-variants}The default is @code{t}, meaning that the buffers being compared or merged willbe preserved when Ediff quits. Setting this to @code{nil} causes Ediff tooffer the user a chance to delete these buffers (if they are not modified).Supplying a prefix argument to the quit command (@code{q}) temporarilyreverses the meaning of this variable. This is convenient when the userprefers one of the behaviors most of the time, but occasionally needs theother behavior.However, Ediff temporarily resets this variable to @code{t} if it isinvoked via one of the "buffer" jobs, such as @code{ediff-buffers}.This is because it is all too easy to loose day's work otherwise.Besides, in a "buffer" job, the variant buffers have already been loadedprior to starting Ediff, so Ediff just preserves status quo here.Using @code{ediff-cleanup-hook}, one can make Ediff delete the variantsunconditionally (e.g., by making @code{ediff-janitor} into one of these hooks).@item ediff-grab-mouse@vindex @code{ediff-grab-mouse}Default is @code{t}. Normally, Ediff grabs mouse and puts it in itscontrol frame. This is useful since the user can be sure that when heneeds to type an Ediff command the focus will be in an appropriate Ediff'sframe. However, some users prefer to move the mouse by themselves. Theabove variable, if set to @code{maybe}, will prevent Ediff from grabbingthe mouse in many situations, usually after commands that may take moretime than usual. In other situation, Ediff will continue grabbing the mouseand putting it where it believes is appropriate. If the value is@code{nil}, then mouse is entirely user's responsibility.Try different settings and see which one is for you.@end table@node Notes on Heavy-duty Customization, , Miscellaneous, Customization@section Notes on Heavy-duty CustomizationSome users need to customize Ediff in rather sophisticated ways, whichrequires different defaults for different kinds of files (e.g., SGML,etc.). Ediff supports this kind of customization in several ways. First,most customization variables are buffer-local. Those that aren't areusually accessible from within Ediff Control Panel, so one can make themlocal to the panel by calling make-local-variable from within@code{ediff-startup-hook}.Second, the function @code{ediff-setup} accepts an optional sixthargument which has the form @code{((@var{var-name-1} .@: @var{val-1})(@var{var-name-2} .@: @var{val-2}) @dots{})}. The function@code{ediff-setup} sets the variables in the list to the respectivevalues, locally in the Ediff control buffer. This is an easy way tothrow in custom variables (which usually should be buffer-local) thatcan then be tested in various hooks.Make sure the variable @code{ediff-job-name} and @code{ediff-word-mode} are setproperly in this case, as some things in Ediff depend on this.Finally, if you want custom-tailored help messages, you can set thevariables @code{ediff-brief-help-message-function} and@code{ediff-long-help-message-function}to functions that return help strings.@vindex ediff-startup-hook@findex ediff-setup@vindex ediff-job-name@vindex ediff-word-mode@vindex ediff-brief-help-message-function@vindex ediff-long-help-message-functionWhen customizing Ediff, some other variables are useful, although they arenot user-definable. They are local to the Ediff control buffer, so thisbuffer must be current when you access these variables. The control bufferis accessible via the variable @code{ediff-control-buffer}, which is alsolocal to that buffer. It is usually used for checking if the current bufferis also the control buffer.Other variables of interest are:@table @code@item ediff-buffer-AThe first of the data buffers being compared.@item ediff-buffer-BThe second of the data buffers being compared.@item ediff-buffer-CIn three-way comparisons, this is the third buffer being compared.In merging, this is the merge buffer.In two-way comparison, this variable is nil.@item ediff-window-AThe window displaying buffer A. If buffer A is not visible, this variableis nil or it may be a dead window.@item ediff-window-BThe window displaying buffer B.@item ediff-window-CThe window displaying buffer C, if any.@item ediff-control-frameA dedicated frame displaying the control buffer, if it exists.It is non-nil only if Ediff uses the multiframe display, i.e., when thecontrol buffer is in its own frame.@end table@node Credits, Index, Customization, Top@chapter CreditsEdiff was written by Michael Kifer <kifer@@cs.sunysb.edu>. It was inspiredby emerge.el written by Dale R.@: Worley <drw@@math.mit.edu>. An idea due toBoris Goldowsky <boris@@cs.rochester.edu> made it possible to highlightfine differences in Ediff buffers. Alastair Burt <burt@@dfki.uni-kl.de>ported Ediff to XEmacs, Eric Freudenthal <freudent@@jan.ultra.nyu.edu>made it work with VC, Marc Paquette <marcpa@@cam.org> wrote thetoolbar 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.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):@exampleAdrian Aichner (aichner@@ecf.teradyne.com),Steve Baur (steve@@xemacs.org),Neal Becker (neal@@ctd.comsat.com),E.@: Jay Berkenbilt (ejb@@ql.org),Alastair Burt (burt@@dfki.uni-kl.de),Paul Bibilo (peb@@delcam.co.uk),Kevin Broadey (KevinB@@bartley.demon.co.uk),Harald Boegeholz (hwb@@machnix.mathematik.uni-stuttgart.de),Bradley A.@: Bosch (brad@@lachman.com),Michael D.@: Carney (carney@@ltx-tr.com),Jin S.@: Choi (jin@@atype.com),Scott Cummings (cummings@@adc.com),Albert Dvornik (bert@@mit.edu),Eric Eide (eeide@@asylum.cs.utah.edu),Paul Eggert (eggert@@twinsun.com),Urban Engberg (ue@@cci.dk),Kevin Esler (esler@@ch.hp.com),Robert Estes (estes@@ece.ucdavis.edu),Jay Finger (jayf@@microsoft.com),Xavier Fornari (xavier@@europe.cma.fr),Eric Freudenthal (freudent@@jan.ultra.nyu.edu),Job Ganzevoort (Job.Ganzevoort@@cwi.nl),Boris Goldowsky (boris@@cs.rochester.edu),Allan Gottlieb (gottlieb@@allan.ultra.nyu.edu),Aaron Gross (aaron@@bfr.co.il),Thorbjoern Hansen (thorbjoern.hansen@@mchp.siemens.de),Xiaoli Huang (hxl@@epic.com),Andreas Jaeger (aj@@suse.de),Lars Magne Ingebrigtsen (larsi@@ifi.uio.no),Larry Gouge (larry@@itginc.com),Karl Heuer (kwzh@@gnu.org),(irvine@@lks.csi.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),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),Erik Naggum (erik@@naggum.no),Eyvind Ness (Eyvind.Ness@@hrp.no),Ray Nickson (nickson@@cs.uq.oz.au),David Petchey (petchey_david@@jpmorgan.com),Benjamin Pierce (benjamin.pierce@@cl.cam.ac.uk),Francois Pinard (pinard@@iro.umontreal.ca),Tibor Polgar (tlp00@@spg.amdahl.com),David Prince (dave0d@@fegs.co.uk),Paul Raines (raines@@slac.stanford.edu),Bill Richter (richter@@math.nwu.edu),C.S.@: Roberson (roberson@@aur.alcatel.com),Kevin Rodgers (kevin.rodgers@@ihs.com),Sandy Rutherford (sandy@@ibm550.sissa.it),Heribert Schuetz (schuetz@@ecrc.de),Andy Scott (ascott@@pcocd2.intel.com),Axel Seibert (axel@@tumbolia.ppp.informatik.uni-muenchen.de),Vin Shelton (acs@@xemacs.org),Scott O. Sherman (Scott.Sherman@@mci.com),Richard Stallman (rms@@gnu.org),Richard Stanton (stanton@@haas.berkeley.edu),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),Jan Vroonhof (vroonhof@@math.ethz.ch),Colin Walters (walters@@cis.ohio-state.edu),Philippe Waroquiers (philippe.waroquiers@@eurocontrol.be),Klaus Weber (gizmo@@zork.north.de),Ben Wing (ben@@xemacs.org),Tom Wurgler (twurgler@@goodyear.com),Steve Youngs (youngs@@xemacs.org),Ilya Zakharevich (ilya@@math.ohio-state.edu),Eli Zaretskii (eliz@@is.elta.co.il)@end example@node Index, , Credits, Top@unnumbered Index@printindex cp@setchapternewpage odd@contents@bye