]> Ediff User's Manual This file documents Ediff, a comprehensive visual interface to Unix diffand patch utilities.Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being “A GNU Manual”, and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License” in the Emacs manual. (a) The FSF's Back-Cover Text is: “You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.” This document is part of a collection distributed under the GNU Free Documentation License. If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license. Introduction Comparing files and buffers Merging files and buffers Patching files and buffers Finding differences Ediff provides a convenient way for simultaneous browsing through the differences between a pair (or a triple) of files or buffers (which are called ‘variants’ for our purposes). The files being compared, file-A, file-B, and file-C (if applicable) are shown in separate windows (side by side, one above the another, or in separate frames), and the differences are highlighted as you step through them. You can also copy difference regions from one buffer to another (and recover old differences if you change your mind). Another powerful feature is the ability to merge a pair of files into a third buffer. Merging with an ancestor file is also supported. Furthermore, Ediff is equipped with directory-level capabilities that allow the user to conveniently launch browsing or merging sessions on groups of files in two (or three) different directories. In addition, Ediff can apply a patch to a file and then let you step through both files, the patched and the original one, simultaneously, difference-by-difference. You can even apply a patch right out of a mail buffer, i.e., patches received by mail don't even have to be saved. Since Ediff lets you copy differences between variants, you can, in effect, apply patches selectively (i.e., you can copy a difference region from file.orig to file, thereby undoing any particular patch that you 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 context format or GNU unified format. All other patches are treated as 1-file patches. Ediff is [hopefully] using the same algorithm as patch to determine which files need to be patched.) Ediff is aware of version control, which lets you compare files with their older versions. Ediff also works with remote and compressed files, automatically ftp'ing them over and uncompressing them. See , for details. This package builds upon ideas borrowed from Emerge, and several of Ediff's functions are adaptations from Emerge. Although Ediff subsumes and greatly extends Emerge, much of the functionality in Ediff is influenced by Emerge. The architecture and the interface are, of course, drastically different. Major Entry Points When Ediff starts up, it displays a small control window, which accepts the Ediff commands, and two or three windows displaying the files to be compared or merged. The control window can be in its own small frame or it can be part of a bigger frame that displays other buffers. In any case, it is important that the control window be active (i.e., be the one receiving the keystrokes) when you use Ediff. You can switch to other Emacs buffers at will and even edit the files currently being compared with Ediff and then switch back to Ediff at any time by activating the appropriate Emacs windows. Ediff can be invoked interactively using the following functions, which can be run either from the minibuffer or from the menu bar. In the menu bar, all Ediff's entry points belong to three submenus of the Tools menu: Compare, Merge, and Apply Patch. ediff-filesediff ediff-files ediffCompare two files. ediff-backup ediff-backupCompare a file with its backup. If there are several numerical backups, usethe latest. If the file is itself a backup, then compare it with itsoriginal. ediff-buffers ediff-buffersCompare two buffers. ediff-files3ediff3 ediff-files3 ediff3Compare three files. ediff-buffers3 ediff-buffers3Compare three buffers. edirsediff-directories edirs ediff-directories Compare files common to two directories. edirs3ediff-directories3 edirs3 ediff-directories3 Compare files common to three directories. edir-revisionsediff-directory-revisions ediff-directory-revisions edir-revisions Compare versions of files in a given directory. Ediff selects only thefiles that are under version control. edir-merge-revisionsediff-merge-directory-revisions edir-merge-revisions ediff-merge-directory-revisions Merge versions of files in a given directory. Ediff selects only thefiles that are under version control. edir-merge-revisions-with-ancestorediff-merge-directory-revisions-with-ancestor edir-merge-revisions-with-ancestor 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. ediff-windows-wordwise ediff-windows-wordwiseCompare windows word-by-word. ediff-windows-linewise ediff-windows-linewiseCompare windows line-by-line. ediff-regions-wordwise ediff-regions-wordwiseCompare regions word-by-word. The regions can come from the same bufferand they can even overlap. You will be asked to specify the buffers thatcontain the regions, which you want to compare. For each buffer, you willalso be asked to mark the regions to be compared. Pay attention to themessages that appear in the minibuffer. ediff-regions-linewise ediff-regions-linewiseSimilar to ediff-windows-linewise, but compares the regionsline-by-line. See ediff-windows-linewise for more details. ediff-revision ediff-revision Compare versions of the current buffer, if the buffer is visiting a file under version control. ediff-patch-fileepatch ediff-patch-file 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. See , 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 ediff-patch-file will actually use the patchutility 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 .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 Control inthe Emacs manual).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), thenediff-patch-buffer might be a better choice. ediff-patch-bufferepatch-buffer ediff-patch-buffer epatch-bufferPatch a buffer, then compare. The buffer being patched and the file visitedby that buffer (if any) is not modified. The result of the patchappears in some other buffer that has the name ending with _patched.This function would refuse to apply a multifile patch to a buffer. Useediff-patch-file for that (and when you want the original file to bemodified by the 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. ediff-merge-filesediff-merge ediff-merge-files ediff-mergeMerge two files. ediff-merge-files-with-ancestorediff-merge-with-ancestor ediff-merge-files-with-ancestor ediff-merge-with-ancestorLike ediff-merge, but with a third ancestor file. ediff-merge-buffers ediff-merge-buffersMerge two buffers. ediff-merge-buffers-with-ancestor ediff-merge-buffers-with-ancestorSame but with ancestor. edirs-mergeediff-merge-directories edirs-merge ediff-merge-directories Merge files common to two directories. edirs-merge-with-ancestorediff-merge-directories-with-ancestor edirs-merge-with-ancestor 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. ediff-merge-revisions ediff-merge-revisionsMerge two versions of the file visited by the current buffer. ediff-merge-revisions-with-ancestor ediff-merge-revisions-with-ancestorSame but with ancestor. ediff-documentation ediff-documentationBrings up this manual. ediff-show-registryeregistry Brings up Ediff session registry. This feature enables you to quickly findand restart active Ediff sessions. If you want Ediff to be loaded from the very beginning of your Emacs session, you should put this line in your ~/.emacs file: (require 'ediff) Otherwise, Ediff will be loaded automatically when you use one of the above functions, either directly or through the menus. When the above functions are invoked, the user is prompted for all the necessary information—typically the files or buffers to compare, merge, or patch. Ediff tries to be smart about these prompts. For instance, in comparing/merging files, it will offer the visible buffers as defaults. In prompting for files, if the user enters a directory, the previously input file name will be appended to that directory. In addition, if the variable ediff-use-last-dir is not nil, Ediff will offer previously entered directories as defaults (which will be maintained separately for each type of file, A, B, or C). ediff-use-last-dir All the above functions use the POSIX diff or diff3 programs to find differences between two files. They process the diff output and display it in a convenient form. At present, Ediff understands only the plain output from diff. Options such as ‘-c’ are not supported, nor is the format produced by incompatible file comparison programs such as the VMS version of diff. The functions ediff-files, ediff-buffers, ediff-files3, ediff-buffers3 first display the coarse, line-based difference regions, as reported by the diff program. The total number of difference regions and the current difference number are always displayed in the mode line of the control window. Since diff may report fairly large chunks of text as being different, even though the difference may be localized to just a few words or even to the white space or line breaks, Ediff further refines the regions to indicate which exact words differ. If the only difference is in the white space and line breaks, Ediff says so. On a color display, fine differences are highlighted with color; on a monochrome display, they are underlined. See , for information on how to customize this. The commands ediff-windows-wordwise, ediff-windows-linewise, ediff-regions-wordwise and ediff-regions-linewise do comparison on parts of existing Emacs buffers. The commands ediff-windows-wordwise and ediff-regions-wordwise are intended for relatively small segments of buffers (e.g., up to 100 lines, depending on the speed of your machine), as they perform comparison on the basis of words rather than lines. (Word-wise comparison of large chunks of text can be slow.) To compare large regions, use ediff-regions-linewise. This command displays differences much like ediff-files and ediff-buffers. The functions ediff-patch-file and ediff-patch-buffer apply a patch to a file or a buffer and then run Ediff on the appropriate files/buffers, displaying the difference regions. The entry points ediff-directories, ediff-merge-directories, etc., provide a convenient interface for comparing and merging files in different directories. The user is presented with Dired-like interface from which one can run a group of related Ediff sessions. For files under version control, ediff-revision lets you compare the 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 ediff-directory-revisions, ediff-merge-directory-revisions, etc., let you run a group of related Ediff sessions by taking a directory and comparing (or merging) versions of files in that directory. Session Commands All Ediff commands are displayed in a Quick Help window, unless you type ? to shrink the window to just one line. You can redisplay the help window by typing ? again. The Quick Help commands are detailed below. Many Ediff commands take numeric prefix arguments. For instance, if you type a number, say 3, and then j (ediff-jump-to-difference), Ediff moves to the third difference region. Typing 3 and then a (ediff-diff-to-diff) copies the 3d difference region from variant A to variant B. Likewise, 4 followed by ra restores the 4th difference region in buffer A (if it was previously written over via the command a). Some commands take negative prefix arguments as well. For instance, typing - and then j will make the last difference region current. Typing -2 then j makes the penultimate difference region current, etc. Without the prefix argument, all commands operate on the currently selected difference region. You can make any difference region current using the various commands explained below. For some commands, the actual value of the prefix argument is immaterial. However, if supplied, the prefix argument may modify the command (see ga, gb, and gc). Quick Help Commands ? ?Toggles the Ediff Quick Help window ON and OFF. G GPrepares a mail buffer for sending a praise or a curse to the Ediff maintainer. E 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. v vScrolls up buffers A and B (and buffer C where appropriate) in acoordinated fashion. V VScrolls the buffers down. < <Scrolls the buffers to the left simultaneously. > >Scrolls buffers to the right. wd wdSaves the output from the diff utility, for further reference.With prefix argument, saves the plain output from diff (seeediff-diff-program and ediff-diff-options). Without theargument, it saves customized diff output (seeediff-custom-diff-program and ediff-custom-diff-options), ifit is available. wa waSaves buffer A, if it was modified. wb wbSaves buffer B, if it was modified. wc wcSaves buffer C, if it was modified (if you are in a session thatcompares three files simultaneously). a aIn 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 rb, which see.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 r. b bWorks similarly, but copies the current difference region from buffer B tobuffer A (in comparison sessions) or the merge buffer (inmerge sessions).Ediff saves the old contents of the difference region copied over; it canbe reinstated via the command ra in comparison sessions andr in merge sessions. ab 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 rb. ac acCopies the difference region from buffer A to buffer C.The old region in buffer C is saved and can be restored via the commandrc. ba baCopies the difference region from buffer B to buffer A.The old region in buffer A is saved and can be restored via the commandra. bc bcCopies the difference region from buffer B to buffer C.The command rc undoes this. ca caCopies the difference region from buffer C to buffer A.The command ra undoes this. cb cbCopies the difference region from buffer C to buffer B.The command rb undoes this. pDEL p DELMakes the previous difference region current. nSPC n SPCMakes the next difference region current. j-jNj jMakes the very first difference region current.-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. ga 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). gb gbMakes current the difference region closest to the position of the point inbuffer B.With a prefix argument, behaves like ga, but with respect to buffer B. gc gcIn merge sessions:makes current the difference region closest to the point in the merge buffer.In 3-file comparison sessions:makes current the region closest to the point in buffer C.With a prefix argument, behaves like ga, but with respect to buffer C. ! !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. * *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 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 * 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. m 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. | |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 m may help some. @ @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*. h 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. r 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 a or b, Ediff saves the old contents of theregion in case you change your mind.)This command is enabled in merge sessions only. ra raRestores the old contents of the current difference region in buffer A,which was previously saved when the user invoked one of these commands:b, ba, ca, which see. This command is enabled incomparison sessions only. rb rbRestores the old contents of the current difference region in buffer B,which was previously saved when the user invoked one of these commands:a, ab, cb, which see. This command is enabled incomparison sessions only. rc rcRestores the old contents of the current difference region in buffer C,which was previously saved when the user invoked one of these commands:ac, bc, which see. This command is enabled in 3-filecomparison sessions only. ## ##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 ##again puts Ediff back in the original state. #c #c ediff-ignore-case-option ediff-ignore-case-option3 ediff-ignore-caseToggle case sensitivity in the diff program. All diffs are recomputed.Case sensitivity is controlled by the variablesediff-ignore-case-option, ediff-ignore-case-option3,and ediff-ignore-case, which are explained elsewhere. #h#f #f #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 j). The above commands, #hand #f, may well save your day!#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.)#f does dual job: it focuses on regions that match the correspondingregular expressions. All other regions will be skippedover. See , for more. A 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). B BToggles the read-only property in buffer B.If file B is under version control and is checked in, it is checked out. C 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. ~ ~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. i iDisplays all kinds of useful data about the current Ediff session. D DRuns 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 diff output.See , for details. R 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 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: M-x eregistry. See . M MShows the session group buffer that invoked the current Ediff session.See , for more information on session groups. z 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. See , for details. q qTerminates this Ediff session. With a prefix argument (e.g.,1q), asksif you also want to delete the buffers of the variants.Modified files and the results of merges are never deleted. % %Toggles narrowing in Ediff buffers. Ediff buffers may be narrowed if youare comparing only parts of these buffers via the commandsediff-windows-* and ediff-regions-*, which see. C-l 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. $$ $$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 $$ again undoes this setting. $* $*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 $* 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. / /Displays the ancestor file during merges. & &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 ‘default-A’ (choose the region from bufferA), ‘default-B’ (choose the region from buffer B), or ‘combined’(combine the regions from the two buffers).See , for further details.The command & also affects the regions in the merge buffers that have‘default-A’, ‘default-B’, or ‘combined’ status, providedthey weren't changed with respect to the original. For instance, if such aregion has the status ‘default-A’ then changing the default action to‘default-B’ will also replace this merge-buffer's region with thecorresponding region from buffer B. s 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., 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, -s shrinks the windowby about 1 line and -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 (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 ediff-merge-window-share, which see. + +Combines the difference regions from buffers A and B and copies theresult into the merge buffer. See , and thevariables ediff-combine-diffs and ediff-combination-pattern. = =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.In other situations, the currently highlighted region might be big and youmight want to reconcile of them interactively.All of this can be done with the above command, =, whichcompares regions within Ediff buffers. Typing = creates achild Ediff session for comparing regions in buffers A, B, orC as follows.First, you will be asked whether you want to compare the fine differencesbetween the currently highlighted buffers on a word-by-word basis. If youaccept, a child Ediff session will start using the currently highlightedregions. Ediff will let you step over the differences word-wise.If you reject the offer, you will be asked to select regions of your choice.If you are comparing 2 files or buffers:Ediff will ask you to select regions in buffers A and B.If you are comparing 3 files or buffers simultaneously: Ediff willask you to choose buffers and then select regions inside those buffers.If you are merging files or buffers (with or without ancestor):Ediff will ask you to choose which buffer (A or B) to compare with themerge buffer and then select regions in those buffers. Other Session Commands The following commands can be invoked from within any Ediff session, although some of them are not bound to a key. eregistryediff-show-registry eregistry 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 functioneregistry is an alias for ediff-show-registry.See , for more information on this registry. ediff-toggle-multiframe 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. Seeediff-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. ediff-toggle-use-toolbar ediff-toggle-use-toolbarAvailable in XEmacs only. The Ediff toolbar provides quick access to someof the common Ediff functions. This function toggles the display of thetoolbar. If invoked from the menubar, the function may take sometimeseffect only after you execute an Ediff command, such as going to the nextdifference. ediff-use-toolbar-p ediff-use-toolbar-pThe use of the toolbar can also be specified via the variableediff-use-toolbar-p (default is t). This variable can be setonly in .emacs — do not change it interactively. Use thefunction ediff-toggle-use-toolbar instead. ediff-revert-buffers-then-recompute-diffs 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. ediff-profile 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 ediff-profile togglesprofiling of ediff commands. Registry of Ediff Sessions Ediff maintains a registry of all its invocations that are still active. This feature is very convenient for switching among active Ediff sessions or for quickly restarting a suspended Ediff session. The focal point of this activity is a buffer called *Ediff Registry*. You can display this buffer by typing R in any Ediff Control Buffer or Session Group Buffer (see ), or by typing M-x eregistry into the Minibuffer. The latter would be the fastest way to bring up the registry buffer if no control or group buffer is displayed in any of the visible Emacs windows. If you are in a habit of running multiple long Ediff sessions and often need to suspend, resume, or switch between them, it may be a good idea to have the registry buffer permanently displayed in a separate, dedicated window. The registry buffer has several convenient key bindings. For instance, clicking mouse button 2 or typing RET or v over any session record resumes that session. Session records in the registry buffer provide a fairly complete description of each session, so it is usually easy to identify the right session to resume. Other useful commands are bound to SPC (next registry record) and 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 of the registry buffer. Session Groups Several major entries of Ediff perform comparison and merging on directories. On entering ediff-directories, ediff-directories3, ediff-merge-directories, ediff-merge-directories-with-ancestor, ediff-directory-revisions, ediff-merge-directory-revisions, or ediff-merge-directory-revisions-with-ancestor, the user is presented with a Dired-like buffer that lists files common to the directories involved along with their sizes. (The list of common files can be further filtered through a regular expression, which the user is prompted for.) We call this buffer Session Group Panel because all Ediff sessions associated with the listed files will have this buffer as a common focal point. Clicking button 2 or typing RET or v over a record describing files invokes Ediff in the appropriate mode on these files. You can come back to the session group buffer associated with a particular invocation of Ediff by typing M in Ediff control buffer of that invocation. Many commands are available in the session group buffer; some are applicable only to certain types of work. The relevant commands are always listed at the top of each session group buffer, so there is no need to memorize them. In directory comparison or merging, a session group panel displays only the files common to all directories involved. The differences are kept in a separate directory difference buffer and are conveniently displayed by typing D to the corresponding session group panel. Thus, as an added benefit, Ediff can be used to compare the contents of up to three directories. Directory difference buffer Sometimes it is desirable to copy some files from one directory to another without exiting Ediff. The directory difference buffer, which is displayed by typing D as discussed above, can be used for this purpose. If a file is, say, in Ediff's Directory A, but is missing in Ediff's Directory B (Ediff will refuse to override existing files), then typing C or clicking mouse button 2 over that file (which must be displayed in directory difference buffer) will copy that file from Directory A to Directory B. Session records in session group panels are also marked with +, for active sessions, and with -, for finished sessions. Sometimes, it is convenient to exclude certain sessions from a group. Usually this happens when the user doesn't intend to run Ediff of certain files in the group, and the corresponding session records just add clutter to the session group buffer. To help alleviate this problem, the user can type h to mark a session as a candidate for exclusion and x to actually hide the marked sessions. There actions are reversible: with a prefix argument, h unmarks the session under the cursor, and x brings the hidden sessions into the view (x doesn't unmark them, though, so the user has to explicitly unmark the sessions of interest). Group sessions also understand the command m, which marks sessions for future operations (other than hiding) on a group of sessions. At present, the only such group-level operation is the creation of a multi-file patch. ediff-autostore-merges For group sessions created to merge files, Ediff can store all merges automatically in a directory. The user is asked to specify such directory if the value of ediff-autostore-merges is non-nil. If the value is nil, nothing is done to the merge buffers—it will be the user's responsibility to save them. If the value is t, the user will be asked where to save the merge buffers in all merge jobs, even those that do not originate from a session group. It the value is neither nil nor t, the merge buffer is saved only if this merge session was invoked from a session group. This behavior is implemented in the function ediff-maybe-save-and-delete-merge, which is a hook in ediff-quit-merge-hook. The user can supply a different hook, if necessary. The variable ediff-autostore-merges is buffer-local, so it can be set on a per-buffer basis. Therefore, use setq-default to change this variable globally. Multi-file patches A multi-file patch is a concatenated output of several runs of the Unix diff command (some versions of diff let you create a multi-file patch in just one run). Ediff facilitates creation of multi-file patches as follows. If you are in a session group buffer created in response to ediff-directories or ediff-directory-revisions, you can mark (by typing m) the desired Ediff sessions and then type P to create a multi-file patch of those marked sessions. Ediff will then display a buffer containing the patch. The patch is generated by invoking diff on all marked individual sessions (represented by files) and session groups (represented by directories). Ediff will also recursively descend into any unmarked session group and will search for marked sessions there. In this way, you can create multi-file patches that span file subtrees that grow out of any given directory. In an ediff-directories session, it is enough to just mark the requisite sessions. In ediff-directory-revisions revisions, the marked sessions must also be active, or else Ediff will refuse to produce a multi-file patch. This is because, in the latter-style sessions, there are many ways to create diff output, and it is easier to handle by running Ediff on the inactive sessions. Last, but not least, by typing ==, you can quickly find out which sessions have identical entries, so you won't have to run Ediff on those sessions. This, however, works only on local, uncompressed files. For compressed or remote files, this command won't report anything. Likewise, you can use =h to mark sessions with identical entries for hiding or, with =m, for further operations. The comparison operations ==, =h, and =m can recurse into subdirectories to see if they have identical contents (so the user will not need to descend into those subdirectories manually). These commands ask the user whether or not to do a recursive descent. Remote and Compressed Files Ediff works with remote, compressed, and encrypted files. Ediff supports ange-ftp.el, jka-compr.el, uncompress.el and crypt++.el, but it may work with other similar packages as well. This means that you can compare files residing on another machine, or you can apply a patch to a file on another machine. Even the patch itself can be a remote file! When patching compressed or remote files, Ediff does not rename the source file (unlike what the patch utility would usually do). Instead, the source file retains its name and the result of applying the patch is placed in a temporary file that has the suffix _patched attached. Generally, this applies to files that are handled using black magic, such as special file handlers (ange-ftp and some compression and encryption packages also use this method). Regular files are treated by the patch utility in the usual manner, i.e., the original is renamed into source-name.orig and the result of the patch is placed into the file source-name (_orig is used on systems like VMS, DOS, etc.) Customization Ediff has a rather self-explanatory interface, and in most cases you won't need to change anything. However, should the need arise, there are extensive facilities for changing the default behavior. Most of the customization can be done by setting various variables in the .emacs file. Some customization (mostly window-related customization and faces) can be done by putting appropriate lines in .Xdefaults, .xrdb, or whatever X resource file is in use. With respect to the latter, please note that the X resource for Ediff customization is `Ediff', not `emacs'. See , See , for further details. Please also refer to Emacs manual for the information on how to set Emacs X resources. Hooks The bulk of customization can be done via the following hooks: ediff-load-hook ediff-load-hookThis hook can be used to change defaults after Ediff is loaded. ediff-before-setup-hook ediff-before-setup-hookHook that is run just before Ediff rearranges windows to its liking.Can be used to save windows configuration. ediff-keymap-setup-hook ediff-keymap-setup-hook ediff-mode-mapThis hook can be used to alter bindings in Ediff's keymap,ediff-mode-map. These hooks arerun right after the default bindings are set but beforeediff-load-hook. The regular user needs not be concerned with thishook—it is provided for implementors of other Emacs packages built on topof Ediff. ediff-before-setup-windows-hookediff-after-setup-windows-hook ediff-before-setup-windows-hook 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. ediff-suspend-hookediff-quit-hook ediff-suspend-hook 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, ediff-quit-hook holds one hook function,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 ediff-cleanup-mess startin ediff-control-buffer; they should also leaveediff-control-buffer as the current buffer when they finish.Hooks that are executed after ediff-cleanup-mess should expectthe current buffer be either buffer A or buffer B.ediff-cleanup-mess doesn't kill the buffers being compared ormerged (see ediff-cleanup-hook, below). ediff-cleanup-hook ediff-cleanup-hookThis hook is run just before ediff-quit-hook. This is a goodplace to do various cleanups, such as deleting the variant buffers.Ediff provides a function, ediff-janitor, as one such possiblehook, which you can add to ediff-cleanup-hook withadd-hooks. 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. ediff-quit-merge-hook ediff-quit-merge-hook ediff-autostore-merges ediff-maybe-save-and-delete-mergeThis hook is called when Ediff quits a merge job. By default, the value isediff-maybe-save-and-delete-merge, which is a function that attemptsto save the merge buffer according to the value ofediff-autostore-merges, as described later. ediff-before-setup-control-frame-hookediff-after-setup-control-frame-hook ediff-before-setup-control-frame-hook 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 (ediff-control-buffer), which requiresspecial care in writing these hooks. Take a look atediff-default-suspend-hook and ediff-default-quit-hook tosee what's involved. ediff-startup-hook ediff-startup-hookThis hook is run at the end of Ediff startup. ediff-select-hook ediff-select-hookThis hook is run after Ediff selects the next difference region. ediff-unselect-hook ediff-unselect-hookThis hook is run after Ediff unselects the current difference region. ediff-prepare-buffer-hook ediff-prepare-buffer-hookThis hook is run for each Ediff buffer (A, B, C) right after the bufferis arranged. ediff-display-help-hook 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. ediff-mode-hook 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. ediff-registry-setup-hook ediff-registry-setup-hookHooks run after setting up the registry for all active Ediff session.See , for details. ediff-before-session-group-setup-hook 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. ediff-after-session-group-setup-hook ediff-after-session-group-setup-hookHooks run after setting up a control panel for a group of related Ediffsessions. See , for details. ediff-quit-session-group-hook ediff-quit-session-group-hookHooks run just before exiting a session group. ediff-meta-buffer-keymap-setup-hook ediff-meta-buffer-keymap-setup-hook ediff-meta-buffer-mapHooks run just after setting up the ediff-meta-buffer-map — themap that controls key bindings in the meta buffer. Sinceediff-meta-buffer-map is a local variable, you can set differentbindings for different kinds of meta buffers. Quick Help Customization ediff-use-long-help-message ediff-control-buffer ediff-startup-hook ediff-help-message Ediff provides quick help using its control panel window. Since this window takes a fair share of the screen real estate, you can toggle it off by typing ?. The control window will then shrink to just one line and a mode line, displaying a short help message. The variable ediff-use-long-help-message tells Ediff whether you use the short message or the long one. By default, it is set to nil, meaning that the short message is used. Set this to t, if you want Ediff to use the long message by default. This property can always be changed interactively, by typing ? into Ediff Control Buffer. If you want to change the appearance of the help message on a per-buffer basis, you must use ediff-startup-hook to change the value of the variable ediff-help-message, which is local to ediff-control-buffer. Window and Frame Configuration On a non-windowing display, Ediff sets things up in one frame, splitting it between a small control window and the windows for buffers A, B, and C. The split between these windows can be horizontal or vertical, which can be changed interactively by typing | while the cursor is in the control window. On a window display, Ediff sets up a dedicated frame for Ediff Control Panel and then it chooses windows as follows: If one of the buffers is invisible, it is displayed in the currently selected frame. If a 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 same frame, then so be it—the frame will be shared by the two. The same algorithm works when you type C-l (ediff-recenter), p (ediff-previous-difference), n (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 to present the details of this remarkable algorithm. The upshot of all this is that you can compare buffers in one frame or in different frames. The former is done by default, while the latter can be achieved by arranging buffers A, B (and C, if applicable) to be seen in different frames. Ediff respects these arrangements, automatically adapting 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): ediff-control-frame-parameters 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 ‘Ediff’. UnderX-windows, you can use this name to set up preferences in your~/.Xdefaults, ~/.xrdb, or whatever X resource file is inuse. Usually this is preferable to changingediff-control-frame-parameters directly. For instance, you canspecify in ~/.Xdefaults the color of the control frameusing the resource ‘Ediff*background’.In general, any X resource pertaining the control frame can be reachedvia the prefix Ediff*. ediff-control-frame-position-function ediff-control-frame-position-functionThe preferred way of specifying the position of the control frame is bysetting the variable ediff-control-frame-position-function to anappropriate function.The default value of this variable isediff-make-frame-position. This function places the control frame inthe vicinity of the North-East corner of the frame displaying buffer A. ediff-make-frame-position The following variables can be used to adjust the location produced by ediff-make-frame-position and for related customization. ediff-narrow-control-frame-leftward-shift 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. ediff-wide-control-frame-rightward-shift 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. ediff-control-frame-upward-shift ediff-control-frame-upward-shiftSpecifies the number of pixels for the upward shiftof the control frame. ediff-prefer-iconified-control-frame ediff-prefer-iconified-control-frameIf this variable is 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 t and ediff-prefer-long-help-message tonil (see ). This behavior is usefulonly if icons are allowed to accept keyboard input (which depends on thewindow manager and other factors). ediff-setup-windows To make more creative changes in the way Ediff sets up windows, you can rewrite the function ediff-setup-windows. However, we believe that detaching Ediff Control Panel from the rest and making it into a separate frame offers an important opportunity by allowing you to iconify that frame. The icon will usually accept all of the Ediff commands, but will free up valuable real estate on your screen (this may depend on your window manager, though). The following variable controls how windows are set up: ediff-window-setup-function ediff-window-setup-functionThe multiframe setup is done by theediff-setup-windows-multiframe function, which is the default onwindowing displays. The plain setup, one where all windows are alwaysin one frame, is done by 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 ediff-toggle-multiframe using the Minibuffer of theMenubar. ediff-setup-windows-multiframe ediff-setup-windows-plain ediff-toggle-multiframeIf you don't like any of these setups, write your own function. See thedocumentation for ediff-window-setup-function for the basicguidelines. However, writing window setups is not easy, so you shouldfirst take a close look at ediff-setup-windows-plain andediff-setup-windows-multiframe. You can run multiple Ediff sessions at once, by invoking Ediff several times without exiting previous Ediff sessions. Different sessions may even operate on the same pair of files. Each session has its own Ediff Control Panel and all the regarding a particular session is local to the associated control panel buffer. You can switch between sessions by suspending one session and then switching to another control panel. (Different control panel buffers are distinguished by a numerical suffix, e.g., ‘Ediff Control Panel<3>’.) Selective Browsing Sometimes it is convenient to be able to step through only some difference regions, those that match certain regular expressions, and to ignore all others. On other occasions, you may want to ignore difference regions that match some regular expressions, and to look only at the rest. The commands #f and #h let you do precisely this. Typing #f lets you specify regular expressions that match difference regions you want to focus on. We shall call these regular expressions regexp-A, regexp-B and regexp-C. Ediff will then start stepping through only those difference regions where the region in buffer A matches regexp-A and/or the region in buffer B matches regexp-B, etc. Whether `and' or `or' will be used depends 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 use the expressions \` and \' to tie search to the beginning or end of the difference regions. On the other hand, typing #h lets you specify (hide) uninteresting regions. That is, if a difference region in buffer A matches regexp-A, the corresponding region in buffer B matches regexp-B and (if applicable) buffer C's region matches regexp-C, then the region will be ignored by the commands n/SPC (ediff-next-difference) and p/DEL (ediff-previous-difference) commands. Typing #f and #h toggles selective browsing on and off. Note that selective browsing affects only ediff-next-difference and ediff-previous-difference, i.e., the commands n/SPC and p/DEL. #f and #h do not change the position of the point in the buffers. And you can still jump directly (using j) to any numbered difference. Users can supply their own functions to specify how Ediff should do selective browsing. To change the default Ediff function, add a function to ediff-load-hook which will do the following assignments: (setq ediff-hide-regexp-matches-function 'your-hide-function) (setq ediff-focus-on-regexp-matches-function 'your-focus-function) Useful hint: To specify a regexp that matches everything, don't simply type RET in response to a prompt. Typing RET tells Ediff to accept the default value, which may not be what you want. Instead, you should enter something like ^ or $. These match every line. You can use the status command, i, to find out whether selective browsing is currently in effect. The regular expressions you specified are kept in the local variables ediff-regexp-focus-A, ediff-regexp-focus-B, ediff-regexp-focus-C, ediff-regexp-hide-A, ediff-regexp-hide-B, ediff-regexp-hide-C. Their default value is the empty string (i.e., nothing is hidden or focused on). To change the default, set these variables in .emacs using setq-default. In addition to the ability to ignore regions that match regular expressions, Ediff can be ordered to start skipping over certain “uninteresting” difference regions. This is controlled by the following variable: ediff-ignore-similar-regions ediff-ignore-similar-regionsIf 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 ##. Please note: in order for this feature to work, auto-refining of difference regions must be on, since otherwise Ediff won't know if there are fine differences between regions. On devices where Emacs can display faces, auto-refining is a default, but it is not turned on by default on text-only terminals. In that case, you must explicitly turn auto-refining on (such as, by typing @). 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 fine differences of all intermediate regions. This delay does not indicate any problem. ediff-ignore-case-option ediff-ignore-case-option3 ediff-ignore-case Finally, Ediff can be told to ignore the case of the letters. This behavior can be toggled with #c and it is controlled with three variables: ediff-ignore-case-option, ediff-ignore-case-option3, and ediff-ignore-case. The variable ediff-ignore-case-option specifies the option to pass to the diff program for comparing two files or buffers. For GNU diff, this option is "-i". The variable ediff-ignore-case-option3 specifies the option to pass to the diff3 program in order to make it case-insensitive. GNU diff3 does not have such an option, so when merging or comparing three files with this program, ignoring the letter case is not supported. The variable ediff-ignore-case controls whether Ediff starts out by ignoring letter case or not. It can be set in .emacs using setq-default. When case sensitivity is toggled, all difference regions are recomputed. Highlighting Difference Regions The following variables control the way Ediff highlights difference regions: ediff-before-flag-bolediff-after-flag-eolediff-before-flag-molediff-after-flag-mol ediff-before-flag-bol ediff-after-flag-eol ediff-before-flag-mol 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. ediff-current-diff-face-Aediff-current-diff-face-Bediff-current-diff-face-C ediff-current-diff-face-A ediff-current-diff-face-B 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 .emacs or in .Xdefaults. The X resource for Ediffis ‘Ediff’, not ‘emacs’. Please refer to Emacs manual forthe information on how to set X resources. ediff-fine-diff-face-Aediff-fine-diff-face-Bediff-fine-diff-face-C ediff-fine-diff-face-A ediff-fine-diff-face-B ediff-fine-diff-face-CEdiff uses these faces to show the fine differences between the currentdifferences regions in buffers A, B, and C, respectively. ediff-even-diff-face-Aediff-even-diff-face-Bediff-even-diff-face-Cediff-odd-diff-face-Aediff-odd-diff-face-Bediff-odd-diff-face-C ediff-even-diff-face-A ediff-even-diff-face-B ediff-even-diff-face-C ediff-odd-diff-face-A ediff-odd-diff-face-B 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. ediff-force-faces 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 t to make sure thatEdiff uses faces to highlight differences. ediff-highlight-all-diffs ediff-highlight-all-diffsIndicates whether—on a windowing 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 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 ediff-highlight-all-diffs to nil. Type 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. If you want to change the default settings for ediff-force-faces and ediff-highlight-all-diffs, you must do it before Ediff is loaded. You can also change the defaults for the faces used to highlight the difference regions. There are two ways to do this. The simplest and the preferred way is to use the customization widget accessible from the menubar. Ediff's customization group is located under "Tools", which in turn is under "Programming". The faces that are used to highlight difference regions are located in the "Highlighting" subgroup of the Ediff customization group. The second, much more arcane, method to change default faces is to include some Lisp code in ~/.emacs. For instance, (setq ediff-current-diff-face-A (copy-face 'bold-italic 'ediff-current-diff-face-A)) would use the pre-defined face bold-italic to highlight the current difference region in buffer A (this face is not a good choice, by the way). If you are unhappy with just some of the aspects of the default faces, you can modify them when Ediff is being loaded using ediff-load-hook. For instance: (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))) Please note: to set Ediff's faces, use only copy-face or set/make-face-… as shown above. Emacs' low-level face-manipulation functions should be avoided. Narrowing If buffers being compared are narrowed at the time of invocation of Ediff, ediff-buffers will preserve the narrowing range. However, if ediff-files is invoked on the files visited by these buffers, that would widen the buffers, since this command is defined to compare the entire files. Calling ediff-regions-linewise or ediff-windows-linewise, or the corresponding ‘-wordwise’ commands, narrows the variants to the particular regions being compared. The original accessible ranges are restored when you quit Ediff. During the command, you can toggle this narrowing on and off with the % command. These two variables control this narrowing behavior: ediff-start-narrowed ediff-start-narrowedIf t, Ediff narrows the display to the appropriate range when itis invoked with an ‘ediff-regions…’ or‘ediff-windows…’ command. If nil, these commands donot automatically narrow, but you can still toggle narrowing on and offby typing %. ediff-quit-widened ediff-quit-widenedControls whether on quitting Ediff should restore the accessible rangethat existed before the current invocation. Refinement of Difference Regions Ediff has variables to control the way fine differences are highlighted. This feature gives you control over the process of refinement. Note that refinement ignores spaces, tabs, and newlines. ediff-auto-refine ediff-auto-refineThis variable controls whether fine differences within regions arehighlighted automatically (“auto-refining”). The default is yes(‘on’).On a slow machine, automatic refinement may be painful. In that case,you can turn auto-refining on or off interactively by typing@. 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 * computes and displays fine differences for the currentdifference region, regardless of whether auto-refining is turned on. ediff-auto-refine-limit 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 *. ediff-forward-word-function 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. ediff-diff-program ediff-forward-word-function ediff-forward-wordFine differences are computed by first splitting the current differenceregion into words and then passing the result toediff-diff-program. For the default forward word function (which isediff-forward-word), a word is a string consisting of letters,‘-’, or ‘_’; 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: ediff-word-1,..., ediff-word-4. See the on-line documentation for these variablesand for the function ediff-forward-word for an explanation of how tomodify these variables. ediff-word-1 ediff-word-2 ediff-word-3 ediff-word-4 Sometimes, when a region has too many differences between the variants, highlighting of fine differences is inconvenient, especially on color displays. If that is the case, type * with a negative prefix argument. This unhighlights fine differences for the current region. To unhighlight fine differences in all difference regions, use the command @. Repeated typing of this key cycles through three different states: auto-refining, no-auto-refining, and no-highlighting of fine differences. Patch and Diff Programs This section describes variables that specify the programs to be used for applying patches and for computing the main difference regions (not the fine difference regions): ediff-diff-programediff-diff3-program ediff-patch-program ediff-diff-program ediff-diff3-programThese variables specify the programs to use to produce differencesand do patching. ediff-diff-optionsediff-diff3-options ediff-patch-options ediff-diff-options ediff-diff3-optionsThese variables specify the options to pass to the above utilities.In ediff-diff-options, it may be useful to specify optionssuch as ‘-w’ that ignore certain kinds of changes. However,Ediff does not let you use the option ‘-c’, as it doesn't recognize thisformat yet. ediff-coding-system-for-read ediff-coding-system-for-readThis variable specifies the coding system to use when reading the outputthat the programs diff3 and diff send to Emacs. The defaultis raw-text, and this should work fine in Unix and in mostcases under Windows NT/95/98/2000. There are diff programsfor which the default option doesn't work under Windows. In such cases,raw-text-dos might work. If not, you will have to experiment withother coding systems or use GNU diff. ediff-patch-program The 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 variablesediff-patch-options, ediff-backup-specs, andediff-backup-extension as described below. ediff-patch-options Options to pass to ediff-patch-program.Note: the `-b' and `-z' options should be specified in`ediff-backup-specs', not in 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. ediff-backup-extension Backup extension used by the patch program. Must be specified, even ifediff-backup-specs is given. ediff-backup-specs Backup 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 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. ediff-custom-diff-programediff-custom-diff-options ediff-custom-diff-program ediff-custom-diff-options ediff-save-bufferBecause Ediff limits the options you may want to pass to the diffprogram, it partially makes up for this drawback by letting you save theoutput from diff in your preferred format, which is specified viathe above two variables.The output generated by ediff-custom-diff-program (which doesn'teven have to be a standard-style 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 ‘-c’ option inediff-diff-program, you would have to run diff -c separatelyjust to produce the list of differences. Fortunately,ediff-custom-diff-program and ediff-custom-diff-optionseliminate this nuisance by keeping a copy of a difference list in thedesired format in a buffer that can be displayed via the command D. ediff-patch-default-directory ediff-patch-default-directorySpecifies the default directory to look for patches. Warning: Ediff does not support the output format of VMS diff. Instead, make sure you are using some implementation of POSIX diff, such as gnudiff. Merging and diff3 Ediff supports three-way comparison via the functions ediff-files3 and ediff-buffers3. The interface is the same as for two-way comparison. In three-way comparison and merging, Ediff reports if any two difference regions are identical. For instance, if the current region in buffer A is the same as the region in buffer C, then the mode line of buffer A will display ‘[=diff(C)]’ and the mode line of buffer C will display ‘[=diff(A)]’. Merging is done according to the following algorithm. If a difference region in one of the buffers, say B, differs from the ancestor file 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 from the ancestor and B's doesn't, A's region is used. ediff-default-variant If both regions in buffers A and B differ from the ancestor file, Ediff chooses the region according to the value of the variable ediff-default-variant. If its value is default-A then A's region is chosen. If it is default-B then B's region is chosen. If it is combined then the region in buffer C will look like this: <<<<<<< variant A the difference region from buffer A >>>>>>> variant B the difference region from buffer B ####### Ancestor the difference region from the ancestor buffer, if available ======= end The above is the default template for the combined region. The user can customize this template using the variable ediff-combination-pattern. ediff-combination-pattern The variable ediff-combination-pattern specifies the template that determines how the combined merged region looks like. The template is represented as a list of the form (STRING1 Symbol1 STRING2 Symbol2 STRING3 Symbol3 STRING4). The symbols here must be atoms of the form A, B, or Ancestor. They determine the order in which the corresponding difference regions (from buffers A, B, and the ancestor buffer) are displayed in the merged region of buffer C. The strings in the template determine the text that separates the aforesaid regions. The default template is ("<<<<<<< variant A" A ">>>>>>> variant B" B "####### Ancestor" Ancestor "======= end") (this is one long line) and the corresponding combined region is shown above. The order in which the regions are shown (and the separator strings) can be changed by changing the above template. It is even possible to add or delete region specifiers in this template (although the only possibly useful such modification seems to be the deletion of the ancestor). In addition to the state of the difference, Ediff displays the state of the merge for each region. If a difference came from buffer A by default (because both regions A and B were different from the ancestor and ediff-default-variant was set to default-A) then ‘[=diff(A) default-A]’ is displayed in the mode line. If the difference in buffer C came, say, from buffer B because the difference region in that buffer differs from the ancestor, but the region in buffer A does not (if merging with an ancestor) then ‘[=diff(B) prefer-B]’ is displayed. The indicators default-A/B and prefer-A/B are inspired by Emerge and have the same meaning. Another indicator of the state of merge is ‘combined’. It appears with any difference region in buffer C that was obtained by combining the difference regions in buffers A and B as explained above. In addition to the state of merge and state of difference indicators, while merging with an ancestor file or buffer, Ediff informs the user when the current difference region in the (normally invisible) ancestor buffer is empty via the AncestorEmpty indicator. This helps determine if the changes made to the original in variants A and B represent pure insertion or deletion of text: if the mode line shows AncestorEmpty and the corresponding region in buffers A or B is not empty, this means that new text was inserted. If this indicator is not present and the difference regions in buffers A or B are non-empty, this means that text was modified. Otherwise, the original text was deleted. Although the ancestor buffer is normally invisible, Ediff maintains difference regions there and advances the current difference region accordingly. All highlighting of difference regions is provided in the ancestor buffer, except for the fine differences. Therefore, if desired, the user can put the ancestor buffer in a separate frame and watch it there. 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 all buffers, including the ancestor buffer, would be visible. However, the ancestor buffer can be displayed by typing / to the control window. (Type C-l to hide it again.) Note that the state-of-difference indicators ‘=diff(A)’ and ‘=diff(B)’ above are not redundant, even in the presence of a state-of-merge indicator. In fact, the two serve different purposes. For instance, if the mode line displays ‘=diff(B) prefer(B)’ and you copy a difference region from buffer A to buffer C then ‘=diff(B)’ will change to ‘diff-A’ and the mode line will display ‘=diff(A) prefer-B’. This indicates that the difference region in buffer C is identical to that in buffer A, but originally buffer C's region came from buffer B. This is useful to know because you can recover the original difference region in buffer C by typing r. Ediff never changes the state-of-merge indicator, except in response to the ! command (see below), in which case the indicator is lost. On the other hand, the state-of-difference indicator is changed automatically by the copying/recovery commands, a, b, r, +. The ! command loses the information about origins of the regions in the merge buffer (default-A, prefer-B, or combined). This is because recomputing differences in this case means running diff3 on buffers A, B, and the merge buffer, not on the ancestor buffer. (It makes no sense to recompute differences using the ancestor file, since in the merging mode Ediff assumes that you have not edited buffers A and B, but that you may have edited buffer C, and these changes are to be preserved.) Since some difference regions may disappear as a result of editing buffer C and others may arise, there is generally no simple way to tell where the various regions in the merge buffer came from. In three-way comparison, Ediff tries to disregard regions that consist entirely of white space. For instance, if, say, the current region in buffer A consists of the white space only (or if it is empty), Ediff will not take it into account for the purpose of computing fine differences. The result is that Ediff can provide a better visual information regarding the actual fine differences in the non-white regions in buffers B and C. Moreover, if the regions in buffers B and C differ in the white space only, then a message to this effect will be displayed. ediff-merge-window-share In the merge mode, the share of the split between window C (the window displaying the merge-buffer) and the windows displaying buffers A and B is controlled by the variable ediff-merge-window-share. Its default value is 0.5. To make the merge-buffer window smaller, reduce this amount. We don't recommend increasing the size of the merge-window to more than half the frame (i.e., to increase the value of ediff-merge-window-share) to more than 0.5, since it would be hard to see the contents of buffers A and B. You can temporarily shrink the merge window to just one line by typing s. This change is temporary, until Ediff finds a reason to redraw the screen. Typing s again restores the original window size. With a positive prefix argument, the s command will make the merge window slightly taller. This change is persistent. With `-' or with a negative prefix argument, the command s makes the merge window slightly shorter. This change also persistent. ediff-show-clashes-only Ediff lets you automatically ignore the regions where only one of the buffers A and B disagrees with the ancestor. To do this, set the variable ediff-show-clashes-only to non-nil. You can toggle this feature interactively by typing $$. Note that this variable affects only the show next/previous difference commands. You can still jump directly to any difference region directly using the command j (with a prefix argument specifying the difference number). ediff-autostore-merges ediff-quit-merge-hook ediff-maybe-save-and-delete-merge The variable ediff-autostore-merges controls what happens to the merge buffer when Ediff quits. If the value is nil, nothing is done to the merge buffer—it will be the user's responsibility to save it. If the value is t, the user will be asked where to save the buffer and whether to delete it afterwards. It the value is neither nil nor t, the merge buffer is saved only if this merge session was invoked from a group of related Ediff session, such as those that result from ediff-merge-directories, ediff-merge-directory-revisions, etc. See . This behavior is implemented in the function ediff-maybe-save-and-delete-merge, which is a hook in ediff-quit-merge-hook. The user can supply a different hook, if necessary. The variable ediff-autostore-merges is buffer-local, so it can be set in a per-buffer manner. Therefore, use setq-default to globally change this variable. ediff-merge-filename-prefix When merge buffers are saved automatically as directed by ediff-autostore-merges, Ediff attaches a prefix to each file, as specified by the variable ediff-merge-filename-prefix. The default is merge_, but this can be changed by the user. Support for Version Control Ediff supports version control and lets you compare versions of files visited by Emacs buffers via the function ediff-revision. This feature is controlled by the following variables: ediff-version-control-package ediff-version-control-packageA symbol. The default is ‘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., (setq ediff-version-control-package 'rcs) Apart from the standard vc.el, Ediff supports three other interfacesto version control: rcs.el, pcl-cvs.el (recently renamedpcvs.el), and generic-sc.el. The package rcs.el is writtenby Sebastian Kremer <sk@thp.Uni-Koeln.DE> and is available as ftp.cs.buffalo.edu:pub/Emacs/rcs.tar.Z ftp.uni-koeln.de:/pub/gnu/emacs/rcs.tar.Z vc.el rcs.el pcl-cvs.el generic-sc.el Ediff's interface to the above packages allows the user to compare the versions of the current buffer or to merge them (with or without an ancestor-version). These operations can also be performed on directories containing files under version control. In case of pcl-cvs.el, Ediff can also be invoked via the function run-ediff-from-cvs-buffer—see the documentation string for this function. Customizing the Mode Line When Ediff is running, the mode line of ‘Ediff Control Panel’ buffer shows the current difference number and the total number of difference regions in the two files. The mode line of the buffers being compared displays the type of the buffer (‘A:’, ‘B:’, or ‘C:’) and (usually) the file name. Ediff tries to be intelligent in choosing the mode line buffer identification. In particular, it works well with the uniquify.el and mode-line.el packages (which improve on the default way in which Emacs displays buffer identification). If you don't like the way Ediff changes the mode line, you can use ediff-prepare-buffer-hook to modify the mode line. ediff-prepare-buffer-hook uniquify.el mode-line.el Miscellaneous Here are a few other variables for customizing Ediff: ediff-split-window-function 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(split-window-vertically, but you can set it tosplit-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~. ediff-merge-split-window-function ediff-merge-split-window-functionControls how windows aresplit between buffers A and B in the merge mode.This variable is like ediff-split-window-function, but it defaultsto split-window-horizontally instead ofsplit-window-vertically. ediff-make-wide-display-function 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 forediff-make-wide-display-function for details. It is alsorecommended to look into the source of the default functionediff-make-wide-display.You can toggle wide/regular display by typing 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. ediff-use-last-dir ediff-use-last-dirControls the way Ediff presents thedefault directory when it prompts the user for files to compare. Ifnil,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. ediff-no-emacs-help-in-control-buffer ediff-no-emacs-help-in-control-bufferIf t, makes C-hbehave like the 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 C-h and ispositioned more conveniently than the DEL key. ediff-toggle-read-only-function 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. ediff-make-buffers-readonly-at-startup nil ediff-make-buffers-readonly-at-startupIf t, all variant buffers are made read-only at Ediff startup. ediff-keep-variants ediff-keep-variantsThe default is t, meaning that the buffers being compared or merged willbe preserved when Ediff quits. Setting this to 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 (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 t if it isinvoked via one of the "buffer" jobs, such as 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 ediff-cleanup-hook, one can make Ediff delete the variantsunconditionally (e.g., by making ediff-janitor into one of these hooks). ediff-keep-tmp-versions ediff-keep-tmp-versionsDefault is nil. If t, the versions of the files beingcompared or merged using operations such as ediff-revision orediff-merge-revisions are not deleted on exit. The normal action isto clean up and delete these version files. ediff-grab-mouse ediff-grab-mouseDefault is 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 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 isnil, then mouse is entirely user's responsibility.Try different settings and see which one is for you. Notes on Heavy-duty Customization Some users need to customize Ediff in rather sophisticated ways, which requires 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 are usually accessible from within Ediff Control Panel, so one can make them local to the panel by calling make-local-variable from within ediff-startup-hook. Second, the function ediff-setup accepts an optional sixth argument which has the form ((var-name-1 . val-1) (var-name-2 . val-2) …). The function ediff-setup sets the variables in the list to the respective values, locally in the Ediff control buffer. This is an easy way to throw in custom variables (which usually should be buffer-local) that can then be tested in various hooks. Make sure the variable ediff-job-name and ediff-word-mode are set properly in this case, as some things in Ediff depend on this. Finally, if you want custom-tailored help messages, you can set the variables ediff-brief-help-message-function and ediff-long-help-message-function to functions that return help strings. ediff-startup-hook ediff-setup ediff-job-name ediff-word-mode ediff-brief-help-message-function ediff-long-help-message-function When customizing Ediff, some other variables are useful, although they are not user-definable. They are local to the Ediff control buffer, so this buffer must be current when you access these variables. The control buffer is accessible via the variable ediff-control-buffer, which is also local to that buffer. It is usually used for checking if the current buffer is also the control buffer. Other variables of interest are: ediff-buffer-A The first of the data buffers being compared. ediff-buffer-B The second of the data buffers being compared. ediff-buffer-C In 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. ediff-window-A The window displaying buffer A. If buffer A is not visible, this variableis nil or it may be a dead window. ediff-window-B The window displaying buffer B. ediff-window-C The window displaying buffer C, if any. ediff-control-frame A dedicated frame displaying the control buffer, if it exists. It isnon-nil only if Ediff uses the multiframe display, i.e., whenthe control buffer is in its own frame. Credits Ediff was written by Michael Kifer <kifer@cs.stonybrook.edu>. It was inspired by emerge.el written by Dale R. Worley <drw@math.mit.edu>. An idea due to Boris Goldowsky <boris@cs.rochester.edu> made it possible to highlight fine differences in Ediff buffers. Alastair Burt <burt@dfki.uni-kl.de> ported Ediff to XEmacs, Eric Freudenthal <freudent@jan.ultra.nyu.edu> made it work with VC, Marc Paquette <marcpa@cam.org> wrote the toolbar support package for Ediff, and Hrvoje Niksic <hniksic@xemacs.org> adapted it to the Emacs customization package. Many people provided help with bug reports, feature suggestions, and advice. Without them, Ediff would not be nearly as useful as it is today. Here is a hopefully full list of contributors: Adrian Aichner (aichner@ecf.teradyne.com), Drew Adams (drew.adams@oracle.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), Felix Heinrich Gatzemeier (felix.g@tzemeier.info), 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), Marcus Harnisch (marcus_harnisch@mint-tech.com), Steven E. Harris (seh@panix.com), Aaron S. Hawley (Aaron.Hawley@uvm.edu), 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), Steffen Kilb (skilb@gmx.net), Leigh L Klotz (klotz@adoc.xerox.com), Fritz Knabe (Fritz.Knabe@ecrc.de), Heinz Knutzen (hk@informatik.uni-kiel.d400.de), Andrew Koenig (ark@research.att.com), Hannu Koivisto (azure@iki.fi), Ken Laprade (laprade@dw3f.ess.harris.com), Will C Lauer (wcl@cadre.com), Richard Levitte (levitte@e.kth.se), Mike Long (mike.long@analog.com), Dave Love (d.love@dl.ac.uk), Martin Maechler (maechler@stat.math.ethz.ch), Simon Marshall (simon@gnu.org), Paul C. Meuse (pmeuse@delcomsys.com), Richard Mlynarik (mly@adoc.xerox.com), Stefan Monnier (monnier@cs.yale.edu), Chris Murphy (murphycm@sun.aston.ac.uk), Erik Naggum (erik@naggum.no), Eyvind Ness (Eyvind.Ness@hrp.no), Ray Nickson (nickson@cs.uq.oz.au), Dan Nicolaescu (dann@ics.uci.edu), 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), Stefan Reicher (xsteve@riic.at), Charles Rich (rich@merl.com), Bill Richter (richter@math.nwu.edu), C.S. Roberson (roberson@aur.alcatel.com), Kevin Rodgers (kevin.rodgers@ihs.com), 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), Sam Steingold (sds@goems.com), Ake Stenhoff (etxaksf@aom.ericsson.se), Stig (stig@hackvan.com), Peter Stout (Peter_Stout@cs.cmu.edu), Chuck Thompson (cthomp@cs.uiuc.edu), Ray Tomlinson (tomlinso@bbn.com), Raymond Toy (toy@rtp.ericsson.se), Stephen J. Turnbull (stephen@xemacs.org), Jan Vroonhof (vroonhof@math.ethz.ch), Colin Walters (walters@cis.ohio-state.edu), Philippe Waroquiers (philippe.waroquiers@eurocontrol.be), 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) GNU Free Documentation License
Version 1.2, November 2002
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. PREAMBLEThe purpose of this License is to make a manual, textbook, or otherfunctional and useful document “free” in the sense of freedom: toassure everyone the effective freedom to copy and redistribute it,with or without modifying it, either commercially or noncommercially.Secondarily, this License preserves for the author and publisher a wayto get credit for their work, while not being considered responsiblefor modifications made by others.This License is a kind of “copyleft,” which means that derivativeworks of the document must themselves be free in the same sense. Itcomplements the GNU General Public License, which is a copyleftlicense designed for free software.We have designed this License in order to use it for manuals for freesoftware, because free software needs free documentation: a freeprogram should come with manuals providing the same freedoms that thesoftware does. But this License is not limited to software manuals;it can be used for any textual work, regardless of subject matter orwhether it is published as a printed book. We recommend this Licenseprincipally for works whose purpose is instruction or reference. APPLICABILITY AND DEFINITIONSThis License applies to any manual or other work, in any medium, thatcontains a notice placed by the copyright holder saying it can bedistributed under the terms of this License. Such a notice grants aworld-wide, royalty-free license, unlimited in duration, to use thatwork under the conditions stated herein. The “Document,” below,refers to any such manual or work. Any member of the public is alicensee, and is addressed as “you.” You accept the license if youcopy, modify or distribute the work in a way requiring permissionunder copyright law.A “Modified Version” of the Document means any work containing theDocument or a portion of it, either copied verbatim, or withmodifications and/or translated into another language.A “Secondary Section” is a named appendix or a front-matter section ofthe Document that deals exclusively with the relationship of thepublishers or authors of the Document to the Document's overall subject(or to related matters) and contains nothing that could fall directlywithin that overall subject. (Thus, if the Document is in part atextbook of mathematics, a Secondary Section may not explain anymathematics.) The relationship could be a matter of historicalconnection with the subject or with related matters, or of legal,commercial, philosophical, ethical or political position regardingthem.The “Invariant Sections” are certain Secondary Sections whose titlesare designated, as being those of Invariant Sections, in the noticethat says that the Document is released under this License. If asection does not fit the above definition of Secondary then it is notallowed to be designated as Invariant. The Document may contain zeroInvariant Sections. If the Document does not identify any InvariantSections then there are none.The “Cover Texts” are certain short passages of text that are listed,as Front-Cover Texts or Back-Cover Texts, in the notice that says thatthe Document is released under this License. A Front-Cover Text maybe at most 5 words, and a Back-Cover Text may be at most 25 words.A “Transparent” copy of the Document means a machine-readable copy,represented in a format whose specification is available to thegeneral public, that is suitable for revising the documentstraightforwardly with generic text editors or (for images composed ofpixels) generic paint programs or (for drawings) some widely availabledrawing editor, and that is suitable for input to text formatters orfor automatic translation to a variety of formats suitable for inputto text formatters. A copy made in an otherwise Transparent fileformat whose markup, or absence of markup, has been arranged to thwartor discourage subsequent modification by readers is not Transparent.An image format is not Transparent if used for any substantial amountof text. A copy that is not “Transparent” is called “Opaque.”Examples of suitable formats for Transparent copies include plainASCII without markup, Texinfo input format, LaTeX input format, SGMLor XML using a publicly available DTD, and standard-conforming simpleHTML, PostScript or PDF designed for human modification. Examples oftransparent image formats include PNG, XCF and JPG. Opaque formatsinclude proprietary formats that can be read and edited only byproprietary word processors, SGML or XML for which the DTD and/orprocessing tools are not generally available, and themachine-generated HTML, PostScript or PDF produced by some wordprocessors for output purposes only.The “Title Page” means, for a printed book, the title page itself,plus such following pages as are needed to hold, legibly, the materialthis License requires to appear in the title page. For works informats which do not have any title page as such, “Title Page” meansthe text near the most prominent appearance of the work's title,preceding the beginning of the body of the text.A section “Entitled XYZ” means a named subunit of the Document whosetitle either is precisely XYZ or contains XYZ in parentheses followingtext that translates XYZ in another language. (Here XYZ stands for aspecific section name mentioned below, such as “Acknowledgements,”“Dedications,” “Endorsements,” or “History.”) To “Preserve the Title”of such a section when you modify the Document means that it remains asection “Entitled XYZ” according to this definition.The Document may include Warranty Disclaimers next to the notice whichstates that this License applies to the Document. These WarrantyDisclaimers are considered to be included by reference in thisLicense, but only as regards disclaiming warranties: any otherimplication that these Warranty Disclaimers may have is void and hasno effect on the meaning of this License. VERBATIM COPYINGYou may copy and distribute the Document in any medium, eithercommercially or noncommercially, provided that this License, thecopyright notices, and the license notice saying this License appliesto the Document are reproduced in all copies, and that you add no otherconditions whatsoever to those of this License. You may not usetechnical measures to obstruct or control the reading or furthercopying of the copies you make or distribute. However, you may acceptcompensation in exchange for copies. If you distribute a large enoughnumber of copies you must also follow the conditions in section 3.You may also lend copies, under the same conditions stated above, andyou may publicly display copies. COPYING IN QUANTITYIf you publish printed copies (or copies in media that commonly haveprinted covers) of the Document, numbering more than 100, and theDocument's license notice requires Cover Texts, you must enclose thecopies in covers that carry, clearly and legibly, all these CoverTexts: Front-Cover Texts on the front cover, and Back-Cover Texts onthe back cover. Both covers must also clearly and legibly identifyyou as the publisher of these copies. The front cover must presentthe full title with all words of the title equally prominent andvisible. You may add other material on the covers in addition.Copying with changes limited to the covers, as long as they preservethe title of the Document and satisfy these conditions, can be treatedas verbatim copying in other respects.If the required texts for either cover are too voluminous to fitlegibly, you should put the first ones listed (as many as fitreasonably) on the actual cover, and continue the rest onto adjacentpages.If you publish or distribute Opaque copies of the Document numberingmore than 100, you must either include a machine-readable Transparentcopy along with each Opaque copy, or state in or with each Opaque copya computer-network location from which the general network-usingpublic has access to download using public-standard network protocolsa complete Transparent copy of the Document, free of added material.If you use the latter option, you must take reasonably prudent steps,when you begin distribution of Opaque copies in quantity, to ensurethat this Transparent copy will remain thus accessible at the statedlocation until at least one year after the last time you distribute anOpaque copy (directly or through your agents or retailers) of thatedition to the public.It is requested, but not required, that you contact the authors of theDocument well before redistributing any large number of copies, to givethem a chance to provide you with an updated version of the Document. MODIFICATIONSYou may copy and distribute a Modified Version of the Document underthe conditions of sections 2 and 3 above, provided that you releasethe Modified Version under precisely this License, with the ModifiedVersion filling the role of the Document, thus licensing distributionand modification of the Modified Version to whoever possesses a copyof it. In addition, you must do these things in the Modified Version:A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.C. State on the Title page the name of the publisher of the Modified Version, as the publisher.D. Preserve all the copyright notices of the Document.E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.H. Include an unaltered copy of this License.I. Preserve the section Entitled “History,” Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.K. For any section Entitled “Acknowledgements” or “Dedications,” Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.M. Delete any section Entitled “Endorsements.” Such a section may not be included in the Modified Version.N. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.O. Preserve any Warranty Disclaimers.If the Modified Version includes new front-matter sections orappendices that qualify as Secondary Sections and contain no materialcopied from the Document, you may at your option designate some or allof these sections as invariant. To do this, add their titles to thelist of Invariant Sections in the Modified Version's license notice.These titles must be distinct from any other section titles.You may add a section Entitled “Endorsements,” provided it containsnothing but endorsements of your Modified Version by variousparties–for example, statements of peer review or that the text hasbeen approved by an organization as the authoritative definition of astandard.You may add a passage of up to five words as a Front-Cover Text, and apassage of up to 25 words as a Back-Cover Text, to the end of the listof Cover Texts in the Modified Version. Only one passage ofFront-Cover Text and one of Back-Cover Text may be added by (orthrough arrangements made by) any one entity. If the Document alreadyincludes a cover text for the same cover, previously added by you orby arrangement made by the same entity you are acting on behalf of,you may not add another; but you may replace the old one, on explicitpermission from the previous publisher that added the old one.The author(s) and publisher(s) of the Document do not by this Licensegive permission to use their names for publicity for or to assert orimply endorsement of any Modified Version. COMBINING DOCUMENTSYou may combine the Document with other documents released under thisLicense, under the terms defined in section 4 above for modifiedversions, provided that you include in the combination all of theInvariant Sections of all of the original documents, unmodified, andlist them all as Invariant Sections of your combined work in itslicense notice, and that you preserve all their Warranty Disclaimers.The combined work need only contain one copy of this License, andmultiple identical Invariant Sections may be replaced with a singlecopy. If there are multiple Invariant Sections with the same name butdifferent contents, make the title of each such section unique byadding at the end of it, in parentheses, the name of the originalauthor or publisher of that section if known, or else a unique number.Make the same adjustment to the section titles in the list ofInvariant Sections in the license notice of the combined work.In the combination, you must combine any sections Entitled “History”in the various original documents, forming one section Entitled“History”; likewise combine any sections Entitled “Acknowledgements,”and any sections Entitled “Dedications.” You must delete all sectionsEntitled “Endorsements.” COLLECTIONS OF DOCUMENTSYou may make a collection consisting of the Document and other documentsreleased under this License, and replace the individual copies of thisLicense in the various documents with a single copy that is included inthe collection, provided that you follow the rules of this License forverbatim copying of each of the documents in all other respects.You may extract a single document from such a collection, and distributeit individually under this License, provided you insert a copy of thisLicense into the extracted document, and follow this License in allother respects regarding verbatim copying of that document. AGGREGATION WITH INDEPENDENT WORKSA compilation of the Document or its derivatives with other separateand independent documents or works, in or on a volume of a storage ordistribution medium, is called an “aggregate” if the copyrightresulting from the compilation is not used to limit the legal rightsof the compilation's users beyond what the individual works permit.When the Document is included in an aggregate, this License does notapply to the other works in the aggregate which are not themselvesderivative works of the Document.If the Cover Text requirement of section 3 is applicable to thesecopies of the Document, then if the Document is less than one half ofthe entire aggregate, the Document's Cover Texts may be placed oncovers that bracket the Document within the aggregate, or theelectronic equivalent of covers if the Document is in electronic form.Otherwise they must appear on printed covers that bracket the wholeaggregate. TRANSLATIONTranslation is considered a kind of modification, so you maydistribute translations of the Document under the terms of section 4.Replacing Invariant Sections with translations requires specialpermission from their copyright holders, but you may includetranslations of some or all Invariant Sections in addition to theoriginal versions of these Invariant Sections. You may include atranslation of this License, and all the license notices in theDocument, and any Warranty Disclaimers, provided that you also includethe original English version of this License and the original versionsof those notices and disclaimers. In case of a disagreement betweenthe translation and the original version of this License or a noticeor disclaimer, the original version will prevail.If a section in the Document is Entitled “Acknowledgements,”“Dedications,” or “History,” the requirement (section 4) to Preserveits Title (section 1) will typically require changing the actualtitle. TERMINATIONYou may not copy, modify, sublicense, or distribute the Document exceptas expressly provided for under this License. Any other attempt tocopy, modify, sublicense or distribute the Document is void, and willautomatically terminate your rights under this License. However,parties who have received copies, or rights, from you under thisLicense will not have their licenses terminated so long as suchparties remain in full compliance. FUTURE REVISIONS OF THIS LICENSEThe Free Software Foundation may publish new, revised versionsof the GNU Free Documentation License from time to time. Such newversions will be similar in spirit to the present version, but maydiffer in detail to address new problems or concerns. Seehttp://www.gnu.org/copyleft/.Each version of the License is given a distinguishing version number.If the Document specifies that a particular numbered version of thisLicense “or any later version” applies to it, you have the option offollowing the terms and conditions either of that specified version orof any later version that has been published (not as a draft) by theFree Software Foundation. If the Document does not specify a versionnumber of this License, you may choose any version ever published (notas a draft) by the Free Software Foundation. ADDENDUM: How to use this License for your documents To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: Copyright (C) year your name. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License.'' If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this: with the Invariant Sections being list their titles, with the Front-Cover Texts being list, and with the Back-Cover Texts being list. If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software. xreflabel="Index" id="Index"> Index !, see ##, see #c, see #f, see #h, see $$, see $*, see %, see &, see *, see +, see /, see <, see =, see >, see ?, see @, see A A, see a, see ab, see ac, see B B, see b, see ba, see bc, see C C, see C-l, see ca, see cb, see Comparing files and buffers, see D D, see DEL, see Directory difference buffer, see E E, see ediff, see ediff-after-flag-eol, see ediff-after-flag-mol, see ediff-after-session-group-setup-hook, see ediff-after-setup-control-frame-hook, see ediff-after-setup-windows-hook, see ediff-auto-refine, see ediff-auto-refine-limit, see ediff-autostore-merges, see ediff-autostore-merges, see ediff-autostore-merges, see ediff-backup, see ediff-before-flag-bol, see ediff-before-flag-mol, see ediff-before-session-group-setup-hook, see ediff-before-setup-control-frame-hook, see ediff-before-setup-hook, see ediff-before-setup-windows-hook, see ediff-brief-help-message-function, see ediff-buffers, see ediff-buffers3, see ediff-cleanup-hook, see ediff-coding-system-for-read, see ediff-combination-pattern, see ediff-control-buffer, see ediff-control-frame-parameters, see ediff-control-frame-position-function, see ediff-control-frame-upward-shift, see ediff-current-diff-face-A, see ediff-current-diff-face-B, see ediff-current-diff-face-C, see ediff-custom-diff-options, see ediff-custom-diff-program, see ediff-default-variant, see ediff-diff-options, see ediff-diff-program, see ediff-diff-program, see ediff-diff3-options, see ediff-diff3-program, see ediff-directories, see ediff-directories3, see ediff-directory-revisions, see ediff-display-help-hook, see ediff-documentation, see ediff-even-diff-face-A, see ediff-even-diff-face-B, see ediff-even-diff-face-C, see ediff-files, see ediff-files3, see ediff-fine-diff-face-A, see ediff-fine-diff-face-B, see ediff-fine-diff-face-C, see ediff-force-faces, see ediff-forward-word, see ediff-forward-word-function, see ediff-grab-mouse, see ediff-help-message, see ediff-highlight-all-diffs, see ediff-ignore-case, see ediff-ignore-case, see ediff-ignore-case-option, see ediff-ignore-case-option, see ediff-ignore-case-option3, see ediff-ignore-case-option3, see ediff-ignore-similar-regions, see ediff-janitor, see ediff-job-name, see ediff-keep-tmp-versions, see ediff-keep-variants, see ediff-keymap-setup-hook, see ediff-load-hook, see ediff-long-help-message-function, see ediff-make-buffers-readonly-at-startup, see ediff-make-frame-position, see ediff-make-wide-display-function, see ediff-maybe-save-and-delete-merge, see ediff-maybe-save-and-delete-merge, see ediff-merge, see ediff-merge-buffers, see ediff-merge-buffers-with-ancestor, see ediff-merge-directories, see ediff-merge-directories-with-ancestor, see ediff-merge-directory-revisions, see ediff-merge-directory-revisions-with-ancestor, see ediff-merge-filename-prefix, see ediff-merge-files, see ediff-merge-files-with-ancestor, see ediff-merge-revisions, see ediff-merge-revisions-with-ancestor, see ediff-merge-split-window-function, see ediff-merge-window-share, see ediff-merge-with-ancestor, see ediff-meta-buffer-keymap-setup-hook, see ediff-meta-buffer-map, see ediff-mode-hook, see ediff-mode-map, see ediff-narrow-control-frame-leftward-shift, see ediff-no-emacs-help-in-control-buffer, see ediff-odd-diff-face-A, see ediff-odd-diff-face-B, see ediff-odd-diff-face-C, see ediff-patch-buffer, see ediff-patch-default-directory, see ediff-patch-file, see ediff-patch-options, see ediff-patch-program, see ediff-prefer-iconified-control-frame, see ediff-prepare-buffer-hook, see ediff-prepare-buffer-hook, see ediff-profile, see ediff-quit-hook, see ediff-quit-merge-hook, see ediff-quit-merge-hook, see ediff-quit-session-group-hook, see ediff-quit-widened, see ediff-regions-linewise, see ediff-regions-wordwise, see ediff-registry-setup-hook, see ediff-revert-buffers-then-recompute-diffs, see ediff-revision, see ediff-save-buffer, see ediff-select-hook, see ediff-setup, see ediff-setup-windows, see ediff-setup-windows-multiframe, see ediff-setup-windows-plain, see ediff-show-clashes-only, see ediff-show-registry, see ediff-split-window-function, see ediff-start-narrowed, see ediff-startup-hook, see ediff-startup-hook, see ediff-startup-hook, see ediff-suspend-hook, see ediff-toggle-multiframe, see ediff-toggle-multiframe, see ediff-toggle-read-only-function, see ediff-toggle-use-toolbar, see ediff-unselect-hook, see ediff-use-last-dir, see ediff-use-last-dir, see ediff-use-long-help-message, see ediff-use-toolbar-p, see ediff-version-control-package, see ediff-wide-control-frame-rightward-shift, see ediff-window-setup-function, see ediff-windows-linewise, see ediff-windows-wordwise, see ediff-word-1, see ediff-word-2, see ediff-word-3, see ediff-word-4, see ediff-word-mode, see ediff3, see edir-merge-revisions, see edir-merge-revisions-with-ancestor, see edir-revisions, see edirs, see edirs-merge, see edirs-merge-with-ancestor, see edirs3, see epatch, see epatch-buffer, see eregistry, see F Finding differences, see G G, see ga, see gb, see gc, see generic-sc.el, see H h, see I i, see J j, see M M, see m, see Merging files and buffers, see mode-line.el, see Multi-file patches, see N n, see P p, see Patching files and buffers, see pcl-cvs.el, see Q q, see R R, see r, see ra, see rb, see rc, see rcs.el, see S s, see SPC, see uniquify.el, see V V, see v, see vc.el, see W wa, see wb, see wc, see wd, see Z z, see |, see ~, see