(Fprocess_send_eof): Abort if fail to open null device.
[emacs.git] / man / ediff.texi
blob3179447fd9a4e5db23bc06cd474c49bfb43d535c
1 \input texinfo                  @c -*-texinfo-*-
2 @c documentation for Ediff
3 @c Written by Michael Kifer
5 @comment %**start of header (This is for running Texinfo on a region.)
7 @comment Using ediff.info instead of ediff in setfilename breaks DOS.
8 @comment @setfilename ediff
9 @comment @setfilename ediff.info
10 @setfilename ../info/ediff
12 @settitle Ediff User's Manual
13 @synindex vr cp
14 @synindex fn cp
15 @synindex pg cp
16 @synindex ky cp
18 @iftex
19 @finalout
20 @end iftex
21 @c      @smallbook
22 @comment %**end of header (This is for running Texinfo on a region.)
24 @copying
25 This file documents Ediff, a comprehensive visual interface to Unix diff
26 and patch utilities.
28 Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
29 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
31 @quotation
32 Permission is granted to copy, distribute and/or modify this document
33 under the terms of the GNU Free Documentation License, Version 1.2 or
34 any later version published by the Free Software Foundation; with no
35 Invariant Sections, with the Front-Cover texts being ``A GNU
36 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
37 license is included in the section entitled ``GNU Free Documentation
38 License'' in the Emacs manual.
40 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
41 this GNU Manual, like GNU software.  Copies published by the Free
42 Software Foundation raise funds for GNU development.''
44 This document is part of a collection distributed under the GNU Free
45 Documentation License.  If you want to distribute this document
46 separately from the collection, you can do so by adding a copy of the
47 license to the document, as described in section 6 of the license.
48 @end quotation
49 @end copying
51 @dircategory Emacs
52 @direntry
53 * Ediff: (ediff).       A visual interface for comparing and merging programs.
54 @end direntry
56 @titlepage
57 @title Ediff User's Manual
58 @sp 4
59 @subtitle Ediff version 2.76.1
60 @sp 1
61 @subtitle January 2002
62 @sp 5
63 @author Michael Kifer
64 @page
66 @vskip 0pt plus 1filll
67 @insertcopying
68 @end titlepage
71 @node Top, Introduction, (dir), (dir)
74 @menu
75 * Introduction::                About Ediff.
76 * Major Entry Points::          How to use Ediff.
77 * Session Commands::            Ediff commands used within a session.
78 * Registry of Ediff Sessions::  Keeping track of multiple Ediff sessions.
79 * Session Groups::              Comparing and merging directories.
80 * Remote and Compressed Files::  You may want to know about this.
81 * Customization::               How to make Ediff work the way YOU want.
82 * Credits::                     Thanks to those who helped.
83 * Index::
84 @end menu
86 @node Introduction, Major Entry Points, Top, Top
87 @chapter Introduction
89 @cindex Comparing files and buffers
90 @cindex Merging files and buffers
91 @cindex Patching files and buffers
92 @cindex Finding differences
94 Ediff provides a convenient way for simultaneous browsing through
95 the differences between a pair (or a triple) of files or buffers
96 (which are called @samp{variants} for our purposes).  The
97 files being compared, file-A, file-B, and file-C (if applicable) are
98 shown in separate windows (side by side, one above the another, or in
99 separate frames), and the differences are highlighted as you step
100 through them.  You can also copy difference regions from one buffer to
101 another (and recover old differences if you change your mind).
103 Another powerful feature is the ability to merge a pair of files into a
104 third buffer.  Merging with an ancestor file is also supported.
105 Furthermore, Ediff is equipped with directory-level capabilities that
106 allow the user to conveniently launch browsing or merging sessions on
107 groups of files in two (or three) different directories.
109 In addition, Ediff can apply a patch to a file and then let you step through
110 both files, the patched and the original one, simultaneously,
111 difference-by-difference.  You can even apply a patch right out of a mail
112 buffer, i.e., patches received by mail don't even have to be saved.  Since
113 Ediff lets you copy differences between variants, you can, in effect, apply
114 patches selectively (i.e., you can copy a difference region from
115 @file{file.orig} to @file{file}, thereby undoing any particular patch that
116 you don't like).
118 Ediff even understands multi-file patches and can apply them interactively!
119 (Ediff can recognize multi-file patches only if they are in the context
120 format or GNU unified format.  All other patches are treated as 1-file
121 patches.  Ediff is [hopefully] using the same algorithm as @code{patch} to
122 determine which files need to be patched.)
124 Ediff is aware of version control, which lets you compare
125 files with their older versions.  Ediff also works with remote and
126 compressed files, automatically ftp'ing them over and uncompressing them.
127 @xref{Remote and Compressed Files}, for details.
129 This package builds upon ideas borrowed from Emerge, and several of Ediff's
130 functions are adaptations from Emerge.  Although Ediff subsumes and greatly
131 extends Emerge, much of the functionality in Ediff is influenced by Emerge.
132 The architecture and the interface are, of course, drastically different.
134 @node Major Entry Points, Session Commands, Introduction, Top
135 @chapter Major Entry Points
137 When Ediff starts up, it displays a small control window, which accepts the
138 Ediff commands and two or three windows displaying the files to be compared
139 or merged. The control window can be in its own small frame or it can be
140 part of a bigger frame that displays other buffers. In any case, it is
141 important that the control window be active (i.e., be the one receiving the
142 keystrokes) when you use Ediff. You can switch to other Emacs buffers at
143 will and even edit the files currently being compared with Ediff and then
144 switch back to Ediff at any time by activating the appropriate Emacs windows.
146 Ediff can be invoked interactively using the following functions, which can
147 be run either from the minibuffer or from the menu bar.  In the menu bar,
148 all Ediff's entry points belong to three submenus of the Tools menu:
149 Compare, Merge, and Apply Patch.
151 @table @code
152 @item ediff-files
153 @itemx ediff
154 @findex ediff-files
155 @findex ediff
156 Compare two files.
158 @item ediff-backup
159 @findex ediff-backup
160 Compare a file with its backup. If there are several numerical backups, use
161 the latest. If the file is itself a backup, then compare it with its
162 original.
164 @item ediff-buffers
165 @findex ediff-buffers
166 Compare two buffers.
168 @item ediff-files3
169 @itemx ediff3
170 @findex ediff-files3
171 @findex ediff3
172 Compare three files.
174 @item ediff-buffers3
175 @findex ediff-buffers3
176 Compare three buffers.
178 @item edirs
179 @itemx ediff-directories
180 @findex edirs
181 @findex ediff-directories
182  Compare files common to two directories.
183 @item edirs3
184 @itemx ediff-directories3
185 @findex edirs3
186 @findex ediff-directories3
187  Compare files common to three directories.
188 @item edir-revisions
189 @itemx ediff-directory-revisions
190 @findex ediff-directory-revisions
191 @findex edir-revisions
192  Compare versions of files in a given directory.  Ediff selects only the
193 files that are under version control.
194 @item edir-merge-revisions
195 @itemx ediff-merge-directory-revisions
196 @findex edir-merge-revisions
197 @findex ediff-merge-directory-revisions
198  Merge versions of files in a given directory.  Ediff selects only the
199 files that are under version control.
200 @item edir-merge-revisions-with-ancestor
201 @itemx ediff-merge-directory-revisions-with-ancestor
202 @findex edir-merge-revisions-with-ancestor
203 @findex ediff-merge-directory-revisions-with-ancestor
204  Merge versions of files in a given directory using other versions as
205 ancestors.  Ediff selects only the files that are under version control.
207 @item ediff-windows-wordwise
208 @findex ediff-windows-wordwise
209 Compare windows word-by-word.
211 @item ediff-windows-linewise
212 @findex ediff-windows-linewise
213 Compare windows line-by-line.
215 @item ediff-regions-wordwise
216 @findex ediff-regions-wordwise
217 Compare regions word-by-word.  The regions can come from the same buffer
218 and they can even overlap.  You will be asked to specify the buffers that
219 contain the regions, which you want to compare. For each buffer, you will
220 also be asked to mark the regions to be compared. Pay attention to the
221 messages that appear in the minibuffer.
223 @item ediff-regions-linewise
224 @findex ediff-regions-linewise
225 Similar to @code{ediff-windows-linewise}, but compares the regions
226 line-by-line. See @code{ediff-windows-linewise} for more details.
228 @item ediff-revision
229 @findex ediff-revision
230  Compare versions of the current buffer, if the buffer is visiting
231  a file under version control.
233 @item ediff-patch-file
234 @itemx epatch
235 @findex ediff-patch-file
236 @findex epatch
238 Patch a file or multiple files, then compare.  If the patch applies to just
239 one file, Ediff will invoke a regular comparison session.  If it is a
240 multi-file patch, then a session group interface will be used and the user
241 will be able to patch the files selectively.  @xref{Session Groups}, for
242 more details.
244 Since the patch might be in a buffer or a file, you will be asked which is
245 the case. To avoid this extra prompt, you can invoke this command with a
246 prefix argument.  With an odd prefix argument, Ediff assumes the patch
247 is in a file; with an even argument, a buffer is assumed.
249 Note that @code{ediff-patch-file} will actually use the @code{patch}
250 utility to change the original files on disk.  This is not that
251 dangerous, since you will always have the original contents of the file
252 saved in another file that has the extension @file{.orig}.
253 Furthermore, if the file is under version control, then you can always back
254 out to one of the previous versions (see the section on Version Control in
255 the Emacs manual).
257 @code{ediff-patch-file} is careful about versions control: if the file
258 to be patched is checked in, then Ediff will offer to check it out, because
259 failing to do so may result in the loss of the changes when the file is
260 checked out the next time.
262 If you don't intend to modify the file via the patch and just want to see
263 what the patch is all about (and decide later), then
264 @code{ediff-patch-buffer} might be a better choice.
266 @item ediff-patch-buffer
267 @itemx epatch-buffer
268 @findex ediff-patch-buffer
269 @findex epatch-buffer
270 Patch a buffer, then compare.  The buffer being patched and the file visited
271 by that buffer (if any) is @emph{not} modified.  The result of the patch
272 appears in some other buffer that has the name ending with @emph{_patched}.
274 This function would refuse to apply a multifile patch to a buffer.  Use
275 @code{ediff-patch-file} for that (and when you want the original file to be
276 modified by the @code{patch} utility).
278 Since the patch might be in a buffer or a file, you will be asked which is
279 the case. To avoid this extra prompt, you can invoke this command with a
280 prefix argument.  With an odd prefix argument, Ediff assumes the patch
281 is in a file; with an even argument, a buffer is assumed.
283 @item ediff-merge-files
284 @itemx ediff-merge
285 @findex ediff-merge-files
286 @findex ediff-merge
287 Merge two files.
289 @item ediff-merge-files-with-ancestor
290 @itemx ediff-merge-with-ancestor
291 @findex ediff-merge-files-with-ancestor
292 @findex ediff-merge-with-ancestor
293 Like @code{ediff-merge}, but with a third ancestor file.
295 @item ediff-merge-buffers
296 @findex ediff-merge-buffers
297 Merge two buffers.
299 @item ediff-merge-buffers-with-ancestor
300 @findex ediff-merge-buffers-with-ancestor
301 Same but with ancestor.
304 @item edirs-merge
305 @itemx ediff-merge-directories
306 @findex edirs-merge
307 @findex ediff-merge-directories
308  Merge files common to two directories.
309 @item edirs-merge-with-ancestor
310 @itemx ediff-merge-directories-with-ancestor
311 @findex edirs-merge-with-ancestor
312 @findex ediff-merge-directories-with-ancestor
313  Same but using files in a third directory as ancestors.
314  If a pair of files doesn't have an ancestor in the ancestor-directory, you
315  will still be able to merge them without the ancestor.
317 @item ediff-merge-revisions
318 @findex ediff-merge-revisions
319 Merge two versions of the file visited by the current buffer.
321 @item ediff-merge-revisions-with-ancestor
322 @findex ediff-merge-revisions-with-ancestor
323 Same but with ancestor.
325 @item ediff-documentation
326 @findex ediff-documentation
327 Brings up this manual.
329 @item ediff-show-registry
330 @itemx eregistry
331 Brings up Ediff session registry.  This feature enables you to quickly find
332 and restart active Ediff sessions.
333 @end table
335 @noindent
336 If you want Ediff to be loaded from the very beginning of your Emacs
337 session, you should put this line in your @file{~/.emacs} file:
339 @example
340 (require 'ediff)
341 @end example
343 @noindent
344 Otherwise, Ediff will be loaded automatically when you use one of the
345 above functions, either directly or through the menus.
347 When the above functions are invoked, the user is prompted for all the
348 necessary information---typically the files or buffers to compare, merge, or
349 patch.  Ediff tries to be smart about these prompts.  For instance, in
350 comparing/merging files, it will offer the visible buffers as defaults.  In
351 prompting for files, if the user enters a directory, the previously input
352 file name will be appended to that directory.  In addition, if the variable
353 @code{ediff-use-last-dir} is not @code{nil}, Ediff will offer
354 previously entered directories as defaults (which will be maintained
355 separately for each type of file, A, B, or C).
356 @vindex @code{ediff-use-last-dir}
358 All the above functions use the POSIX @code{diff} or @code{diff3} programs
359 to find differences between two files.  They process the @code{diff} output
360 and display it in a convenient form.  At present, Ediff understands only
361 the plain output from diff.  Options such as @samp{-c} are not supported,
362 nor is the format produced by incompatible file comparison programs such as
363 the VMS version of @code{diff}.
365 The functions @code{ediff-files}, @code{ediff-buffers},
366 @code{ediff-files3}, @code{ediff-buffers3} first display the coarse,
367 line-based difference regions, as reported by the @code{diff} program.  The
368 total number of difference regions and the current difference number are
369 always displayed in the mode line of the control window.
371 Since @code{diff} may report fairly large chunks of text as being different,
372 even though the difference may be localized to just a few words or even
373 to the white space or line breaks, Ediff further @emph{refines} the
374 regions to indicate which exact words differ.  If the only difference is
375 in the white space and line breaks, Ediff says so.
377 On a color display, fine differences are highlighted with color; on a
378 monochrome display, they are underlined.  @xref{Highlighting Difference
379 Regions}, for information on how to customize this.
381 The commands @code{ediff-windows-wordwise},
382 @code{ediff-windows-linewise}, @code{ediff-regions-wordwise} and
383 @code{ediff-regions-linewise} do comparison on parts of existing Emacs
384 buffers.  The commands @code{ediff-windows-wordwise} and
385 @code{ediff-regions-wordwise} are intended for relatively small segments
386 of buffers (e.g., up to 100 lines, depending on the speed of your machine),
387 as they perform comparison on the basis of words rather than lines.
388 (Word-wise comparison of large chunks of text can be slow.)
390 To compare large regions, use @code{ediff-regions-linewise}.  This
391 command displays differences much like @code{ediff-files} and
392 @code{ediff-buffers}.
394 The functions @code{ediff-patch-file} and @code{ediff-patch-buffer} apply a
395 patch to a file or a buffer and then run Ediff on the appropriate
396 files/buffers, displaying the difference regions.
398 The entry points @code{ediff-directories}, @code{ediff-merge-directories},
399 etc., provide a convenient interface for comparing and merging files in
400 different directories.  The user is presented with Dired-like interface from
401 which one can run a group of related Ediff sessions.
403 For files under version control, @code{ediff-revision} lets you compare
404 the file visited by the current buffer to one of its checked-in versions.
405 You can also compare two checked-in versions of the visited file.
406 Moreover, the functions @code{ediff-directory-revisions},
407 @code{ediff-merge-directory-revisions}, etc., let you run a group of
408 related Ediff sessions by taking a directory and comparing (or merging)
409 versions of files in that directory.
411 @node Session Commands, Registry of Ediff Sessions, Major Entry Points, Top
412 @chapter Session Commands
414 All Ediff commands are displayed in a Quick Help window, unless you type
415 @kbd{?} to shrink the window to just one line.  You can redisplay the help
416 window by typing @kbd{?} again.  The Quick Help commands are detailed below.
418 Many Ediff commands take numeric prefix arguments.  For instance, if you
419 type a number, say 3, and then @kbd{j} (@code{ediff-jump-to-difference}),
420 Ediff moves to the third difference region.  Typing 3 and then @kbd{a}
421 (@code{ediff-diff-to-diff}) copies the 3d difference region from variant A
422 to variant B.  Likewise, 4 followed by @kbd{ra} restores the 4th difference
423 region in buffer A (if it was previously written over via the command
424 @kbd{a}).
426 Some commands take negative prefix arguments as well.  For instance, typing
427 @kbd{-} and then @kbd{j} will make the last difference region
428 current.  Typing @kbd{-2} then @kbd{j} makes the penultimate difference
429 region current, etc.
431 Without the prefix argument, all commands operate on the currently
432 selected difference region.  You can make any difference region
433 current using the various commands explained below.
435 For some commands, the actual value of the prefix argument is
436 immaterial.  However, if supplied, the prefix argument may modify the
437 command (see @kbd{ga}, @kbd{gb}, and @kbd{gc}).
439 @menu
440 * Quick Help Commands::             Frequently used commands.
441 * Other Session Commands::          Commands that are not bound to keys.
442 @end menu
444 @node Quick Help Commands,Other Session Commands,,Session Commands
445 @section Quick Help Commands
447 @table @kbd
448 @item ?
449 @kindex ?
450 Toggles the Ediff Quick Help window ON and OFF.
451 @item G
452 @kindex G
453 Prepares a mail buffer for sending a praise or a curse to the Ediff maintainer.
455 @item E
456 @kindex E
457 Brings up the top node of this manual, where you can find further
458 information on the various Ediff functions and advanced issues, such as
459 customization, session groups, etc.
461 @item v
462 @kindex v
463 Scrolls up buffers A and B (and buffer C where appropriate) in a
464 coordinated fashion.
465 @item V
466 @kindex V
467 Scrolls the buffers down.
469 @item <
470 @kindex <
471 Scrolls the buffers to the left simultaneously.
472 @item >
473 @kindex >
474 Scrolls buffers to the right.
476 @item wd
477 @kindex wd
478 Saves the output from the diff utility, for further reference.
480 With prefix argument, saves the plain output from @code{diff} (see
481 @code{ediff-diff-program} and @code{ediff-diff-options}).  Without the
482 argument, it saves customized @code{diff} output (see
483 @code{ediff-custom-diff-program} and @code{ediff-custom-diff-options}), if
484 it is available.
486 @item wa
487 @kindex wa
488 Saves buffer A, if it was modified.
489 @item wb
490 @kindex wb
491 Saves buffer B, if it was modified.
492 @item wc
493 @kindex wc
494 Saves buffer C, if it was modified (if you are in a session that
495 compares three files simultaneously).
497 @item a
498 @kindex a
499 @emph{In comparison sessions:}
500 Copies the current difference region (or the region specified as the prefix
501 to this command) from buffer A to buffer B.
502 Ediff saves the old contents of buffer B's region; it can
503 be restored via the command @kbd{rb}, which see.
505 @emph{In merge sessions:}
506 Copies the current difference region (or the region specified as the prefix
507 to this command) from buffer A to the merge buffer.  The old contents of
508 this region in buffer C can be restored via the command @kbd{r}.
510 @item b
511 @kindex b
512 Works similarly, but copies the current difference region from buffer B to
513 buffer A (in @emph{comparison sessions}) or the merge buffer (in
514 @emph{merge sessions}).
516 Ediff saves the old contents of the difference region copied over; it can
517 be reinstated via the command @kbd{ra} in comparison sessions and
518 @kbd{r} in merge sessions.
520 @item ab
521 @kindex ab
522 Copies the current difference region (or the region specified as the prefix
523 to this command) from buffer A to buffer B.  This (and the next five)
524 command is enabled only in sessions that compare three files
525 simultaneously.  The old region in buffer B is saved and can be restored
526 via the command @kbd{rb}.
527 @item ac
528 @kindex ac
529 Copies the difference region from buffer A to buffer C.
530 The old region in buffer C is saved and can be restored via the command
531 @kbd{rc}.
532 @item ba
533 @kindex ba
534 Copies the difference region from buffer B to buffer A.
535 The old region in buffer A is saved and can be restored via the command
536 @kbd{ra}.
537 @item bc
538 @kindex bc
539 Copies the difference region from buffer B to buffer C.
540 The command @kbd{rc} undoes this.
541 @item ca
542 @kindex ca
543 Copies the difference region from buffer C to buffer A.
544 The command @kbd{ra} undoes this.
545 @item cb
546 @kindex cb
547 Copies the difference region from buffer C to buffer B.
548 The command @kbd{rb} undoes this.
550 @item p
551 @itemx DEL
552 @kindex p
553 @kindex DEL
554 Makes the previous difference region current.
555 @item n
556 @itemx SPC
557 @kindex n
558 @kindex SPC
559 Makes the next difference region current.
561 @item j
562 @itemx -j
563 @itemx Nj
564 @kindex j
565 Makes the very first difference region current.
567 @kbd{-j} makes the last region current.  Typing a number, N, and then `j'
568 makes the difference region N current.  Typing -N (a negative number) then
569 `j' makes current the region Last - N.
571 @item ga
572 @kindex ga
573 Makes current the difference region closest to the position of the point in
574 buffer A.
576 However, with a prefix argument, Ediff would position all variants
577 around the area indicated by the current point in buffer A: if
578 the point is inside a difference region, then the variants will be
579 positioned at this difference region.  If the point is not in any difference
580 region, then it is in an area where all variants agree with each other.  In
581 this case, the variants will be positioned so that each would display this
582 area (of agreement).
583 @item gb
584 @kindex gb
585 Makes current the difference region closest to the position of the point in
586 buffer B.
588 With a prefix argument, behaves like @kbd{ga}, but with respect to buffer B.
589 @item gc
590 @kindex gc
591 @emph{In merge sessions:}
592 makes current the difference region closest to the point in the merge buffer.
594 @emph{In 3-file comparison sessions:}
595 makes current the region closest to the point in buffer C.
597 With a prefix argument, behaves like @kbd{ga}, but with respect to buffer C.
599 @item !
600 @kindex !
601 Recomputes the difference regions, bringing them up to date.  This is often
602 needed because it is common to do all sorts of editing during Ediff
603 sessions, so after a while, the highlighted difference regions may no
604 longer reflect the actual differences among the buffers.
606 @item *
607 @kindex *
608 Forces refinement of the current difference region, which highlights the exact
609 words of disagreement among the buffers.  With a negative prefix argument,
610 unhighlights the current region.
612 Forceful refinement may be needed if Ediff encounters a difference region
613 that is larger than @code{ediff-auto-refine-limit}.  In this situation,
614 Ediff doesn't do automatic refinement in order to improve response time.
615 (Ediff doesn't auto-refine on dumb terminals as well, but @kbd{*} still
616 works there.  However, the only useful piece of information it can tell you
617 is whether or not the difference regions disagree only in the amount of
618 white space.)
620 This command is also useful when the highlighted fine differences are
621 no longer current, due to user editing.
623 @item m
624 @kindex m
625 Displays the current Ediff session in a frame as wide as the physical
626 display.  This is useful when comparing files side-by-side.  Typing `m' again
627 restores the original size of the frame.
629 @item |
630 @kindex |
631 Toggles the horizontal/vertical split of the Ediff display.  Horizontal
632 split is convenient when it is possible to compare files
633 side-by-side.  If the frame in which files are displayed is too narrow
634 and lines are cut off, typing @kbd{m} may help some.
636 @item @@
637 @kindex @@
638 Toggles auto-refinement of difference regions (i.e., automatic highlighting
639 of the exact words that differ among the variants).  Auto-refinement is
640 turned off on devices where Emacs doesn't support highlighting.
642 On slow machines, it may be advantageous to turn auto-refinement off.  The
643 user can always forcefully refine specific difference regions by typing
644 @kbd{*}.
646 @item h
647 @kindex h
648 Cycles between full highlighting, the mode where fine differences are not
649 highlighted (but computed), and the mode where highlighting is done with
650 @acronym{ASCII} strings.  The latter is not really recommended, unless on a dumb TTY.
652 @item r
653 @kindex r
654 Restores the old contents of the region in the merge buffer.
655 (If you copied a difference region from buffer A or B into the merge buffer
656 using the commands @kbd{a} or @kbd{b}, Ediff saves the old contents of the
657 region in case you change your mind.)
659 This command is enabled in merge sessions only.
661 @item ra
662 @kindex ra
663 Restores the old contents of the current difference region in buffer A,
664 which was previously saved when the user invoked one of these commands:
665 @kbd{b}, @kbd{ba}, @kbd{ca}, which see.  This command is enabled in
666 comparison sessions only.
667 @item rb
668 @kindex rb
669 Restores the old contents of the current difference region in buffer B,
670 which was previously saved when the user invoked one of these commands:
671 @kbd{a}, @kbd{ab}, @kbd{cb}, which see.  This command is enabled in
672 comparison sessions only.
673 @item rc
674 @kindex rc
675 Restores the old contents of the current difference region in buffer C,
676 which was previously saved when the user invoked one of these commands:
677 @kbd{ac}, @kbd{bc}, which see.  This command is enabled in 3-file
678 comparison sessions only.
680 @item ##
681 @kindex ##
682 Tell Ediff to skip over regions that disagree among themselves only in the
683 amount of white space and line breaks.
685 Even though such regions will be skipped over, you can still jump to any
686 one of them by typing the region number and then `j'.  Typing @kbd{##}
687 again puts Ediff back in the original state.
689 @item #c
690 @kindex #c
691 @vindex ediff-ignore-case-option
692 @vindex ediff-ignore-case-option3
693 @vindex ediff-ignore-case
694 Toggle case sensitivity in the diff program. All diffs are recomputed.
695 Case sensitivity is controlled by the variables
696 @code{ediff-ignore-case-option}, @code{ediff-ignore-case-option3},
697 and @code{ediff-ignore-case}, which are explained elsewhere.
699 @item #h
700 @itemx #f
701 @kindex #f
702 @kindex #h
703 Ediff works hard to ameliorate the effects of boredom in the workplace...
705 Quite often differences are due to identical replacements (e.g., the word
706 `foo' is replaced with the word `bar' everywhere).  If the number of regions
707 with such boring differences exceeds your tolerance threshold, you may be
708 tempted to tell Ediff to skip these regions altogether (you will still be able
709 to jump to them via the command @kbd{j}).  The above commands, @kbd{#h}
710 and @kbd{#f}, may well save your day!
712 @kbd{#h} prompts you to specify regular expressions for each
713 variant.  Difference regions where each variant's region matches the
714 corresponding regular expression will be skipped from then on.  (You can
715 also tell Ediff to skip regions where at least one variant matches its
716 regular expression.)
718 @kbd{#f} does dual job: it focuses on regions that match the corresponding
719 regular expressions.  All other regions will be skipped
720 over.  @xref{Selective Browsing}, for more.
722 @item A
723 @kindex A
724 Toggles the read-only property in buffer A.
725 If file A is under version control and is checked in, it is checked out
726 (with your permission).
727 @item B
728 @kindex B
729 Toggles the read-only property in buffer B.
730 If file B is under version control and is checked in, it is checked out.
731 @item C
732 @kindex C
733 Toggles the read-only property in buffer C (in 3-file comparison sessions).
734 If file C is under version control and is checked in, it is checked out.
736 @item ~
737 @kindex ~
738 Swaps the windows where buffers A and B are displayed.  If you are comparing
739 three buffers at once, then this command would rotate the windows among
740 buffers A, B, and C.
742 @item i
743 @kindex i
744 Displays all kinds of useful data about the current Ediff session.
745 @item D
746 @kindex D
747 Runs @code{ediff-custom-diff-program} on the variants and displays the
748 buffer containing the output.  This is useful when you must send the output
749 to your Mom.
751 With a prefix argument, displays the plain @code{diff} output.
752 @xref{Patch and Diff Programs}, for details.
754 @item R
755 @kindex R
756 Displays a list of currently active Ediff sessions---the Ediff Registry.
757 You can then restart any of these sessions by either clicking on a session
758 record or by putting the cursor over it and then typing the return key.
760 (Some poor souls leave so many active Ediff sessions around that they loose
761 track of them completely...  The `R' command is designed to save these
762 people from the recently discovered Ediff Proficiency Syndrome.)
764 Typing @kbd{R} brings up Ediff Registry only if it is typed into an Ediff
765 Control Panel.  If you don't have a control panel handy, type this in the
766 minibuffer: @kbd{M-x eregistry}.  @xref{Registry of Ediff Sessions}.
768 @item M
769 @kindex M
770 Shows the session group buffer that invoked the current Ediff session.
771 @xref{Session Groups}, for more information on session groups.
773 @item z
774 @kindex z
775 Suspends the current Ediff session.  (If you develop a condition known as
776 Repetitive Ediff Injury---a serious but curable illness---you must change
777 your current activity.  This command tries hard to hide all Ediff-related
778 buffers.)
780 The easiest way to resume a suspended Ediff session is through the registry
781 of active sessions.  @xref{Registry of Ediff Sessions}, for details.
782 @item q
783 @kindex q
784 Terminates this Ediff session.  With a prefix argument (e.g.,@kbd{1q}), asks
785 if you also want to delete the buffers of the variants.
786 Modified files and the results of merges are never deleted.
788 @item %
789 @kindex %
790 Toggles narrowing in Ediff buffers.  Ediff buffers may be narrowed if you
791 are comparing only parts of these buffers via the commands
792 @code{ediff-windows-*} and @code{ediff-regions-*}, which see.
794 @item C-l
795 @kindex C-l
796 Restores the usual Ediff window setup.  This is the quickest way to resume
797 an Ediff session, but it works only if the control panel of that session is
798 visible.
800 @item $$
801 @kindex $$
802 While merging with an ancestor file, Ediff is determined to reduce user's
803 wear and tear by saving him and her much of unproductive, repetitive
804 typing.  If it notices that, say, file A's difference region is identical to
805 the same difference region in the ancestor file, then the merge buffer will
806 automatically get the difference region taken from buffer B.  The rationale
807 is that this difference region in buffer A is as old as that in the
808 ancestor buffer, so the contents of that region in buffer B represents real
809 change.
811 You may want to ignore such `obvious' merges and concentrate on difference
812 regions where both files `clash' with the ancestor, since this means that
813 two different people have been changing this region independently and they
814 had different ideas on how to do this.
816 The above command does this for you by skipping the regions where only one
817 of the variants clashes with the ancestor but the other variant agrees with
818 it.  Typing @kbd{$$} again undoes this setting.
820 @item $*
821 @kindex $*
822 When merging files with large number of differences, it is sometimes
823 convenient to be able to skip the difference regions for which you already
824 decided which variant is most appropriate. Typing @kbd{$*} will accomplish
825 precisely this.
827 To be more precise, this toggles the check for whether the current merge is
828 identical to its default setting, as originally decided by Ediff.  For
829 instance, if Ediff is merging according to the `combined' policy, then the
830 merge region is skipped over if it is different from the combination of the
831 regions in buffers A and B.  (Warning: swapping buffers A and B will confuse
832 things in this respect).  If the merge region is marked as `prefer-A' then
833 this region will be skipped if it differs from the current difference
834 region in buffer A, etc.
836 @item /
837 @kindex /
838 Displays the ancestor file during merges.
839 @item &
840 @kindex &
841 In some situations, such as when one of the files agrees with the ancestor file
842 on a difference region and the other doesn't, Ediff knows what to do: it copies
843 the current difference region from the second buffer into the merge buffer.
845 In other cases, the right course of action is not that clearcut, and Ediff
846 would use a default action.  The above command changes the default action.
847 The default action can be @samp{default-A} (choose the region from buffer
848 A), @samp{default-B} (choose the region from buffer B), or @samp{combined}
849 (combine the regions from the two buffers).
850 @xref{Merging and diff3}, for further details.
852 The command @kbd{&} also affects the regions in the merge buffers that have
853 @samp{default-A}, @samp{default-B}, or @samp{combined} status, provided
854 they weren't changed with respect to the original.  For instance, if such a
855 region has the status @samp{default-A} then changing the default action to
856 @samp{default-B} will also replace this merge-buffer's region with the
857 corresponding region from buffer B.
859 @item s
860 @kindex s
861 Causes the merge window shrink to its minimum size, thereby exposing as much
862 of the variant buffers as possible.  Typing `s' again restores
863 the original size of that window.
865 With a positive prefix argument, this command enlarges the merge window.
866 E.g., @kbd{4s} increases the size of the window by about 4 lines, if
867 possible.  With a negative numeric argument, the size of the merge window
868 shrinks by that many lines, if possible.  Thus, @kbd{-s} shrinks the window
869 by about 1 line and @kbd{-3s} by about 3 lines.
871 This command is intended only for temporary viewing; therefore, Ediff
872 restores window C to its original size whenever it makes any other change
873 in the window configuration.  However, redisplaying (@kbd{C-l}) or jumping
874 to another difference does not affect window C's size.
876 The split between the merge window and the variant windows is controlled by
877 the variable @code{ediff-merge-window-share}, which see.
879 @item +
880 @kindex +
881 Combines the difference regions from buffers A and B and copies the
882 result into the merge buffer.  @xref{Merging and diff3}, and the
883 variables @code{ediff-combine-diffs} and @code{ediff-combination-pattern}.
886 @item =
887 @kindex =
888 You may run into situations when a large chunk of text in one file has been
889 edited and then moved to a different place in another file.  In such a case,
890 these two chunks of text are unlikely to belong to the same difference
891 region, so the refinement feature of Ediff will not be able to tell you
892 what exactly differs inside these chunks.  Since eyeballing large pieces of
893 text is contrary to human nature, Ediff has a special command to help
894 reduce the risk of developing a cataract.
896 In other situations, the currently highlighted region might be big and you
897 might want to reconcile of them interactively.
899 All of this can be done with the above command, @kbd{=}, which
900 compares regions within Ediff buffers.  Typing @kbd{=} creates a
901 child Ediff session for comparing regions in buffers A, B, or
902 C as follows.
904 First, you will be asked whether you want to compare the fine differences
905 between the currently highlighted buffers on a word-by-word basis. If you
906 accept, a child Ediff session will start using the currently highlighted
907 regions. Ediff will let you step over the differences word-wise.
909 If you reject the offer, you will be asked to select regions of your choice.
911 @emph{If you are comparing 2 files or buffers:}
912 Ediff will ask you to select regions in buffers A and B.
914 @emph{If you are comparing 3 files or buffers simultaneously:} Ediff will
915 ask you to choose buffers and then select regions inside those buffers.
917 @emph{If you are merging files or buffers (with or without ancestor):}
918 Ediff will ask you to choose which buffer (A or B) to compare with the
919 merge buffer and then select regions in those buffers.
921 @end table
923 @node Other Session Commands,,Quick Help Commands,Session Commands
924 @section Other Session Commands
926 The following commands can be invoked from within any Ediff session,
927 although some of them are not bound to a key.
929 @table @code
930 @item eregistry
931 @itemx ediff-show-registry
932 @findex eregistry
933 @findex ediff-show-registry
934 This command brings up the registry of active Ediff sessions.  Ediff
935 registry is a device that can be used to resume any active Ediff session
936 (which may have been postponed because the user switched to some other
937 activity).  This command is also useful for switching between multiple
938 active Ediff sessions that are run at the same time.  The function
939 @code{eregistry} is an alias for @code{ediff-show-registry}.
940 @xref{Registry of Ediff Sessions}, for more information on this registry.
942 @item ediff-toggle-multiframe
943 @findex ediff-toggle-multiframe
944 Changes the display from the multi-frame mode (where the quick help window
945 is in a separate frame) to the single-frame mode (where all Ediff buffers
946 share the same frame), and vice versa.  See
947 @code{ediff-window-setup-function} for details on how to make either of
948 these modes the default one.
950 This function can also be invoked from the Menubar.  However, in some
951 cases, the change will take place only after you execute one of the Ediff
952 commands, such as going to the next difference or redisplaying.
954 @item ediff-toggle-use-toolbar
955 @findex ediff-toggle-use-toolbar
956 Available in XEmacs only.  The Ediff toolbar provides quick access to some
957 of the common Ediff functions.  This function toggles the display of the
958 toolbar.  If invoked from the menubar, the function may take sometimes
959 effect only after you execute an Ediff command, such as going to the next
960 difference.
962 @item ediff-use-toolbar-p
963 @vindex ediff-use-toolbar-p
964 The use of the toolbar can also be specified via the variable
965 @code{ediff-use-toolbar-p} (default is @code{t}).  This variable can be set
966 only in @file{.emacs} --- do @strong{not} change it interactively.  Use the
967 function @code{ediff-toggle-use-toolbar} instead.
969 @item ediff-revert-buffers-then-recompute-diffs
970 @findex ediff-revert-buffers-then-recompute-diffs
971 This command reverts the buffers you are comparing and recomputes their
972 differences.  It is useful when, after making changes, you decided to
973 make a fresh start, or if at some point you changed the files being
974 compared but want to discard any changes to comparison buffers that were
975 done since then.
977 This command normally asks for confirmation before reverting files.
978 With a prefix argument, it reverts files without asking.
981 @item ediff-profile
982 @findex ediff-profile
983 Ediff has an admittedly primitive (but useful) facility for profiling
984 Ediff's commands.  It is meant for Ediff maintenance---specifically, for
985 making it run faster.  The function @code{ediff-profile} toggles
986 profiling of ediff commands.
987 @end table
989 @node Registry of Ediff Sessions, Session Groups, Session Commands, Top
990 @chapter Registry of Ediff Sessions
992 Ediff maintains a registry of all its invocations that are
993 still @emph{active}.  This feature is very convenient for switching among
994 active Ediff sessions or for quickly restarting a suspended Ediff session.
996 The focal point of this activity is a buffer
997 called @emph{*Ediff Registry*}.  You can display this buffer by typing
998 @kbd{R} in any Ediff Control Buffer or Session Group Buffer
999 (@pxref{Session Groups}), or by typing
1000 @kbd{M-x eregistry} into the Minibuffer.
1001 The latter would be the fastest way to bring up the registry
1002 buffer if no control or group buffer is displayed in any of the visible
1003 Emacs windows.
1004 If you are in a habit of running multiple long Ediff sessions and often need to
1005 suspend, resume, or switch between them, it may be a good idea to have the
1006 registry buffer permanently displayed in a separate, dedicated window.
1008 The registry buffer has several convenient key bindings.
1009 For instance, clicking mouse button 2 or typing
1010 @kbd{RET} or @kbd{v} over any session record resumes that session.
1011 Session records in the registry buffer provide a fairly complete
1012 description of each session, so it is usually easy to identify the right
1013 session to resume.
1015 Other useful commands are bound to @kbd{SPC} (next registry record)
1016 and @kbd{DEL} (previous registry record).  There are other commands as well,
1017 but you don't need to memorize them, since they are listed at the top of
1018 the registry buffer.
1020 @node Session Groups, Remote and Compressed Files, Registry of Ediff Sessions, Top
1021 @chapter Session Groups
1023 Several major entries of Ediff perform comparison and merging on
1024 directories.  On entering @code{ediff-directories},
1025 @code{ediff-directories3},
1026 @code{ediff-merge-directories},
1027 @code{ediff-merge-directories-with-ancestor},
1028 @code{ediff-directory-revisions},
1029 @code{ediff-merge-directory-revisions}, or
1030 @code{ediff-merge-directory-revisions-with-ancestor},
1031 the user is presented with a
1032 Dired-like buffer that lists files common to the directories involved along
1033 with their sizes.  (The list of common files can be further filtered through
1034 a regular expression, which the user is prompted for.)  We call this buffer
1035 @emph{Session Group Panel} because all Ediff sessions associated with the
1036 listed files will have this buffer as a common focal point.
1038 Clicking button 2 or typing @kbd{RET} or @kbd{v} over a
1039 record describing files invokes Ediff in the appropriate mode on these
1040 files.  You can come back to the session group buffer associated with a
1041 particular invocation of Ediff by typing @kbd{M} in Ediff control buffer of
1042 that invocation.
1044 Many commands are available in the session group buffer; some are
1045 applicable only to certain types of work.  The relevant commands are always
1046 listed at the top of each session group buffer, so there is no need to
1047 memorize them.
1049 In directory comparison or merging, a session group panel displays only the
1050 files common to all directories involved.  The differences are kept in a
1051 separate @emph{directory difference buffer} and are conveniently displayed
1052 by typing @kbd{D} to the corresponding session group panel.  Thus, as an
1053 added benefit, Ediff can be used to compare the contents of up to three
1054 directories.
1056 @cindex Directory difference buffer
1057 Sometimes it is desirable to copy some files from one directory to another
1058 without exiting Ediff. The @emph{directory difference buffer}, which is
1059 displayed by typing @kbd{D} as discussed above, can be used for this
1060 purpose. If a file is, say, in Ediff's Directory A, but is missing in
1061 Ediff's Directory B (Ediff will refuse to override existing files), then
1062 typing @kbd{C} or clicking mouse button 2 over that file (which must be
1063 displayed in directory difference buffer) will copy that file from
1064 Directory A to Directory B.
1066 Session records in session group panels are also marked with @kbd{+}, for
1067 active sessions, and with @kbd{-}, for finished sessions.
1069 Sometimes, it is convenient to exclude certain sessions from a group.
1070 Usually this happens when the user doesn't intend to run Ediff of certain
1071 files in the group, and the corresponding session records just add clutter
1072 to the session group buffer.  To help alleviate this problem, the user can
1073 type @kbd{h} to mark a session as a candidate for exclusion and @kbd{x} to
1074 actually hide the marked sessions.  There actions are reversible: with a
1075 prefix argument, @kbd{h} unmarks the session under the cursor, and @kbd{x}
1076 brings the hidden sessions into the view (@kbd{x} doesn't unmark them,
1077 though, so the user has to explicitly unmark the sessions of interest).
1079 Group sessions also understand the command @kbd{m}, which marks sessions
1080 for future operations (other than hiding) on a group of sessions.  At present,
1081 the only such group-level operation is the creation of a multi-file patch.
1083 @vindex ediff-autostore-merges
1084 For group sessions created to merge files, Ediff can store all merges
1085 automatically in a directory.  The user is asked to specify such directory
1086 if the value of @code{ediff-autostore-merges} is non-@code{nil}.  If the value is
1087 @code{nil}, nothing is done to the merge buffers---it will be the user's
1088 responsibility to save them.  If the value is @code{t}, the user will be
1089 asked where to save the merge buffers in all merge jobs, even those that do
1090 not originate from a session group.  It the value is neither @code{nil} nor
1091 @code{t}, the merge buffer is saved @emph{only} if this merge session was
1092 invoked from a session group.  This behavior is implemented in the function
1093 @code{ediff-maybe-save-and-delete-merge}, which is a hook in
1094 @code{ediff-quit-merge-hook}.  The user can supply a different hook, if
1095 necessary.
1097 The variable @code{ediff-autostore-merges} is buffer-local, so it can be
1098 set on a per-buffer basis.  Therefore, use @code{setq-default} to change
1099 this variable globally.
1101 @cindex Multi-file patches
1102 A multi-file patch is a concatenated output of several runs of the Unix
1103 @code{diff} command (some versions of @code{diff} let you create a
1104 multi-file patch in just one run).  Ediff facilitates creation of
1105 multi-file patches as follows.  If you are in a session group buffer
1106 created in response to @code{ediff-directories} or
1107 @code{ediff-directory-revisions}, you can mark (by typing @kbd{m}) the
1108 desired Ediff sessions and then type @kbd{P} to create a
1109 multi-file patch of those marked sessions.
1110 Ediff will then display a buffer containing the patch.
1111 The patch is generated by invoking @code{diff} on all marked individual
1112 sessions (represented by files) and session groups (represented by
1113 directories).  Ediff will also recursively descend into any @emph{unmarked}
1114 session group and will search for marked sessions there.  In this way, you
1115 can create multi-file patches that span file subtrees that grow out of
1116 any given directory.
1118 In an @code{ediff-directories} session, it is enough to just mark the
1119 requisite sessions.  In @code{ediff-directory-revisions} revisions, the
1120 marked sessions must also be active, or else Ediff will refuse to produce a
1121 multi-file patch.  This is because, in the latter-style sessions, there are
1122 many ways to create diff output, and it is easier to handle by running
1123 Ediff on the inactive sessions.
1125 Last, but not least, by typing @kbd{==}, you can quickly find out which
1126 sessions have identical entries, so you won't have to run Ediff on those
1127 sessions.  This, however, works only on local, uncompressed files.
1128 For compressed or remote files, this command won't report anything.
1129 Likewise, you can use @kbd{=h} to mark sessions with identical entries
1130 for hiding or, with @kbd{=m}, for further operations.
1132 The comparison operations @kbd{==}, @kbd{=h}, and @kbd{=m} can recurse into
1133 subdirectories to see if they have identical contents (so the user will not
1134 need to descend into those subdirectories manually). These commands ask the
1135 user whether or not to do a recursive descent.
1139 @node Remote and Compressed Files, Customization, Session Groups, Top
1140 @chapter Remote and Compressed Files
1142 Ediff works with remote, compressed, and encrypted files.  Ediff
1143 supports @file{ange-ftp.el}, @file{jka-compr.el}, @file{uncompress.el}
1144 and @file{crypt++.el}, but it may work with other similar packages as
1145 well.  This means that you can compare files residing on another
1146 machine, or you can apply a patch to a file on another machine.  Even
1147 the patch itself can be a remote file!
1149 When patching compressed or remote files, Ediff does not rename the source
1150 file (unlike what the @code{patch} utility would usually do).  Instead, the
1151 source file retains its name and the result of applying the patch is placed
1152 in a temporary file that has the suffix @file{_patched} attached.
1153 Generally, this applies to files that are handled using black magic, such
1154 as special file handlers (ange-ftp and some compression and encryption
1155 packages also use this method).
1157 Regular files are treated by the @code{patch} utility in the usual manner,
1158 i.e., the original is renamed into @file{source-name.orig} and the result
1159 of the patch is placed into the file source-name (@file{_orig} is used
1160 on systems like VMS, DOS, etc.)
1162 @node Customization, Credits, Remote and Compressed Files, Top
1163 @chapter Customization
1165 Ediff has a rather self-explanatory interface, and in most cases you
1166 won't need to change anything.  However, should the need arise, there are
1167 extensive facilities for changing the default behavior.
1169 Most of the customization can be done by setting various variables in the
1170 @file{.emacs} file.  Some customization (mostly window-related
1171 customization and faces) can be done by putting appropriate lines in
1172 @file{.Xdefaults}, @file{.xrdb}, or whatever X resource file is in use.
1174 With respect to the latter, please note that the X resource
1175 for Ediff customization is `Ediff', @emph{not} `emacs'.
1176 @xref{Window and Frame Configuration},
1177 @xref{Highlighting Difference Regions}, for further details.  Please also
1178 refer to Emacs manual for the information on how to set Emacs X resources.
1180 @menu
1181 * Hooks::                       Customization via the hooks.
1182 * Quick Help Customization::    How to customize Ediff's quick help feature.
1183 * Window and Frame Configuration::  Controlling the way Ediff displays things.
1184 * Selective Browsing::          Advanced browsing through difference regions.
1185 * Highlighting Difference Regions::  Controlling highlighting.
1186 * Narrowing::                   Comparing regions, windows, etc.
1187 * Refinement of Difference Regions::  How to control the refinement process.
1188 * Patch and Diff Programs::     Changing the utilities that compute differences
1189                                 and apply patches.
1190 * Merging and diff3::           How to customize Ediff in its Merge Mode.
1191 * Support for Version Control::  Changing the version control package.
1192                                  You are not likely to do that.
1193 * Customizing the Mode Line::   Changing the look of the mode line in Ediff.
1194 * Miscellaneous::               Other customization.
1195 * Notes on Heavy-duty Customization::  Customization for the gurus.
1196 @end menu
1198 @node Hooks, Quick Help Customization, Customization, Customization
1199 @section Hooks
1201 The bulk of customization can be done via the following hooks:
1203 @table @code
1204 @item ediff-load-hook
1205 @vindex ediff-load-hook
1206 This hook can be used to change defaults after Ediff is loaded.
1208 @item ediff-before-setup-hook
1209 @vindex ediff-before-setup-hook
1210 Hook that is run just before Ediff rearranges windows to its liking.
1211 Can be used to save windows configuration.
1213 @item ediff-keymap-setup-hook
1214 @vindex ediff-keymap-setup-hook
1215 @vindex ediff-mode-map
1216 This hook can be used to alter bindings in Ediff's keymap,
1217 @code{ediff-mode-map}.  These hooks are
1218 run right after the default bindings are set but before
1219 @code{ediff-load-hook}.  The regular user needs not be concerned with this
1220 hook---it is provided for implementors of other Emacs packages built on top
1221 of Ediff.
1223 @item ediff-before-setup-windows-hook
1224 @itemx ediff-after-setup-windows-hook
1225 @vindex ediff-before-setup-windows-hook
1226 @vindex ediff-after-setup-windows-hook
1227 These two hooks are called before and after Ediff sets up its window
1228 configuration.  These hooks are run each time Ediff rearranges windows to
1229 its liking. This happens whenever it detects that the user changed the
1230 windows setup.
1232 @item ediff-suspend-hook
1233 @itemx ediff-quit-hook
1234 @vindex ediff-suspend-hook
1235 @vindex ediff-quit-hook
1236 These two hooks are run when you suspend or quit Ediff.  They can be
1237 used to set desired window configurations, delete files Ediff didn't
1238 want to clean up after exiting, etc.
1240 By default, @code{ediff-quit-hook} holds one hook function,
1241 @code{ediff-cleanup-mess}, which cleans after Ediff, as appropriate in
1242 most cases.  You probably won't want to change it, but you might
1243 want to add other hook functions.
1245 Keep in mind that hooks executing before @code{ediff-cleanup-mess} start
1246 in @code{ediff-control-buffer;} they should also leave
1247 @code{ediff-control-buffer} as the current buffer when they finish.
1248 Hooks that are executed after @code{ediff-cleanup-mess} should expect
1249 the current buffer be either buffer A or buffer B.
1250 @code{ediff-cleanup-mess} doesn't kill the buffers being compared or
1251 merged (see @code{ediff-cleanup-hook}, below).
1253 @item ediff-cleanup-hook
1254 @vindex ediff-cleanup-hook
1255 This hook is run just before @code{ediff-quit-hook}.  This is a good
1256 place to do various cleanups, such as deleting the variant buffers.
1257 Ediff provides a function, @code{ediff-janitor}, as one such possible
1258 hook, which you can add to @code{ediff-cleanup-hook} with
1259 @code{add-hooks}.
1261 @findex ediff-janitor
1262 This function kills buffers A, B, and, possibly, C, if these buffers aren't
1263 modified.  In merge jobs, buffer C is never deleted.  However, the side
1264 effect of using this function is that you may not be able to compare the
1265 same buffer in two separate Ediff sessions: quitting one of them will
1266 delete this buffer in another session as well.
1268 @item ediff-quit-merge-hook
1269 @vindex ediff-quit-merge-hook
1270 @vindex ediff-autostore-merges
1271 @findex ediff-maybe-save-and-delete-merge
1272 This hook is called when Ediff quits a merge job.  By default, the value is
1273 @code{ediff-maybe-save-and-delete-merge}, which is a function that attempts
1274 to save the merge buffer according to the value of
1275 @code{ediff-autostore-merges}, as described later.
1277 @item ediff-before-setup-control-frame-hook
1278 @itemx ediff-after-setup-control-frame-hook
1279 @vindex ediff-before-setup-control-frame-hook
1280 @vindex ediff-after-setup-control-frame-hook
1281 These two hooks run before and after Ediff sets up the control frame.
1282 They can be used to relocate Ediff control frame when Ediff runs in a
1283 multiframe mode (i.e., when the control buffer is in its own dedicated
1284 frame).  Be aware that many variables that drive Ediff are local to
1285 Ediff Control Panel (@code{ediff-control-buffer}), which requires
1286 special care in writing these hooks.  Take a look at
1287 @code{ediff-default-suspend-hook} and @code{ediff-default-quit-hook} to
1288 see what's involved.
1290 @item ediff-startup-hook
1291 @vindex ediff-startup-hook
1292 This hook is run at the end of Ediff startup.
1294 @item ediff-select-hook
1295 @vindex ediff-select-hook
1296 This hook is run after Ediff selects the next difference region.
1298 @item ediff-unselect-hook
1299 @vindex ediff-unselect-hook
1300 This hook is run after Ediff unselects the current difference region.
1302 @item ediff-prepare-buffer-hook
1303 @vindex ediff-prepare-buffer-hook
1304 This hook is run for each Ediff buffer (A, B, C) right after the buffer
1305 is arranged.
1307 @item ediff-display-help-hook
1308 @vindex ediff-display-help-hook
1309 Ediff runs this hook each time after setting up the help message.  It
1310 can be used to alter the help message for custom packages that run on
1311 top of Ediff.
1313 @item ediff-mode-hook
1314 @vindex ediff-mode-hook
1315 This hook is run just after Ediff mode is set up in the control
1316 buffer.  This is done before any Ediff window is created.  You can use it to
1317 set local variables that alter the look of the display.
1319 @item ediff-registry-setup-hook
1320 @vindex ediff-registry-setup-hook
1321 Hooks run after setting up the registry for all active Ediff session.
1322 @xref{Session Groups}, for details.
1323 @item ediff-before-session-group-setup-hook
1324 @vindex ediff-before-session-group-setup-hook
1325 Hooks run before setting up a control panel for a group of related Ediff
1326 sessions. Can be used, for example, to save window configuration to restore
1327 later.
1328 @item ediff-after-session-group-setup-hook
1329 @vindex ediff-after-session-group-setup-hook
1330 Hooks run after setting up a control panel for a group of related Ediff
1331 sessions.  @xref{Session Groups}, for details.
1332 @item ediff-quit-session-group-hook
1333 @vindex ediff-quit-session-group-hook
1334 Hooks run just before exiting a session group.
1335 @item ediff-meta-buffer-keymap-setup-hook
1336 @vindex ediff-meta-buffer-keymap-setup-hook
1337 @vindex ediff-meta-buffer-map
1338 Hooks run just after setting up the @code{ediff-meta-buffer-map} --- the
1339 map that controls key bindings in the meta buffer.  Since
1340 @code{ediff-meta-buffer-map} is a local variable, you can set different
1341 bindings for different kinds of meta buffers.
1342 @end table
1344 @node Quick Help Customization, Window and Frame Configuration, Hooks, Customization
1345 @section Quick Help Customization
1346 @vindex ediff-use-long-help-message
1347 @vindex ediff-control-buffer
1348 @vindex ediff-startup-hook
1349 @vindex ediff-help-message
1351 Ediff provides quick help using its control panel window.  Since this window
1352 takes a fair share of the screen real estate, you can toggle it off by
1353 typing @kbd{?}.  The control window will then shrink to just one line and a
1354 mode line, displaying a short help message.
1356 The variable @code{ediff-use-long-help-message} tells Ediff whether
1357 you use the short message or the long one.  By default, it
1358 is set to @code{nil}, meaning that the short message is used.
1359 Set this to @code{t}, if you want Ediff to use the long
1360 message by default.  This property can always be changed interactively, by
1361 typing @kbd{?} into Ediff Control Buffer.
1363 If you want to change the appearance of the help message on a per-buffer
1364 basis, you must use @code{ediff-startup-hook} to change the value of
1365 the variable @code{ediff-help-message}, which is local to
1366 @code{ediff-control-buffer}.
1368 @node Window and Frame Configuration, Selective Browsing, Quick Help Customization, Customization
1369 @section Window and Frame Configuration
1371 On a non-windowing display, Ediff sets things up in one frame, splitting
1372 it between a small control window and the windows for buffers A, B, and C.
1373 The split between these windows can be horizontal or
1374 vertical, which can be changed interactively by typing @kbd{|} while the
1375 cursor is in the control window.
1377 On a window display, Ediff sets up a dedicated frame for Ediff Control
1378 Panel and then it chooses windows as follows: If one of the buffers
1379 is invisible, it is displayed in the currently selected frame.  If
1380 a buffer is visible, it is displayed in the frame where it is visible.
1381 If, according to the above criteria, the two buffers fall into the same
1382 frame, then so be it---the frame will be shared by the two.  The same
1383 algorithm works when you type @kbd{C-l} (@code{ediff-recenter}), @kbd{p}
1384 (@code{ediff-previous-difference}), @kbd{n}
1385 (@code{ediff-next-difference}), etc.
1387 The above behavior also depends on whether the current frame is splittable,
1388 dedicated, etc.  Unfortunately, the margin of this book is too narrow to
1389 present the details of this remarkable algorithm.
1391 The upshot of all this is that you can compare buffers in one frame or
1392 in different frames.  The former is done by default, while the latter can
1393 be achieved by arranging buffers A, B (and C, if applicable) to be seen in
1394 different frames.  Ediff respects these arrangements, automatically
1395 adapting itself to the multi-frame mode.
1397 Ediff uses the following variables to set up its control panel
1398 (a.k.a.@: control buffer, a.k.a.@: quick help window):
1400 @table @code
1401 @item ediff-control-frame-parameters
1402 @vindex ediff-control-frame-parameters
1403 You can change or augment this variable including the font, color,
1404 etc.  The X resource name of Ediff Control Panel frames is @samp{Ediff}.  Under
1405 X-windows, you can use this name to set up preferences in your
1406 @file{~/.Xdefaults}, @file{~/.xrdb}, or whatever X resource file is in
1407 use.  Usually this is preferable to changing
1408 @code{ediff-control-frame-parameters} directly.  For instance, you can
1409 specify in @file{~/.Xdefaults} the color of the control frame
1410 using the resource @samp{Ediff*background}.
1412 In general, any X resource pertaining the control frame can be reached
1413 via the prefix @code{Ediff*}.
1415 @item ediff-control-frame-position-function
1416 @vindex ediff-control-frame-position-function
1417 The preferred way of specifying the position of the control frame is by
1418 setting the variable @code{ediff-control-frame-position-function} to an
1419 appropriate function.
1420 The default value of this variable is
1421 @code{ediff-make-frame-position}.  This function places the control frame in
1422 the vicinity of the North-East corner of the frame displaying buffer A.
1424 @findex ediff-make-frame-position
1425 @end table
1427 The following variables can be used to adjust the location produced by
1428 @code{ediff-make-frame-position} and for related customization.
1430 @table @code
1431 @item ediff-narrow-control-frame-leftward-shift
1432 @vindex ediff-narrow-control-frame-leftward-shift
1433 Specifies the number of characters for shifting
1434 the control frame from the rightmost edge of frame A when the control
1435 frame is displayed as a small window.
1437 @item ediff-wide-control-frame-rightward-shift
1438 @vindex ediff-wide-control-frame-rightward-shift
1439 Specifies the rightward shift of the control frame
1440 from the left edge of frame A when the control frame shows the full
1441 menu of options.
1443 @item ediff-control-frame-upward-shift
1444 @vindex ediff-control-frame-upward-shift
1445 Specifies the number of pixels for the upward shift
1446 of the control frame.
1448 @item ediff-prefer-iconified-control-frame
1449 @vindex ediff-prefer-iconified-control-frame
1450 If this variable is @code{t}, the control frame becomes iconified
1451 automatically when you toggle the quick help message off.  This saves
1452 valuable real estate on the screen.  Toggling help back will deiconify
1453 the control frame.
1455 To start Ediff with an iconified Control Panel, you should set this
1456 variable to @code{t} and @code{ediff-prefer-long-help-message} to
1457 @code{nil} (@pxref{Quick Help Customization}).  This behavior is useful
1458 only if icons are allowed to accept keybord input (which depend on the
1459 window manager and other factors).
1460 @end table
1462 @findex ediff-setup-windows
1463 To make more creative changes in the way Ediff sets up windows, you can
1464 rewrite the function @code{ediff-setup-windows}.  However, we believe
1465 that detaching Ediff Control Panel from the rest and making it into a
1466 separate frame offers an important opportunity by allowing you to
1467 iconify that frame.  The icon will usually accept all of the Ediff
1468 commands, but will free up valuable real estate on your screen (this may
1469 depend on your window manager, though).
1471 The following variable controls how windows are set up:
1473 @table @code
1474 @item ediff-window-setup-function
1475 @vindex ediff-window-setup-function
1476 The multiframe setup is done by the
1477 @code{ediff-setup-windows-multiframe} function, which is the default on
1478 windowing displays.  The plain setup, one where all windows are always
1479 in one frame, is done by @code{ediff-setup-windows-plain}, which is the
1480 default on a non-windowing display (or in an xterm window).  In fact,
1481 under Emacs, you can switch freely between these two setups by executing
1482 the command @code{ediff-toggle-multiframe} using the Minibuffer of the
1483 Menubar.
1484 @findex ediff-setup-windows-multiframe
1485 @findex ediff-setup-windows-plain
1486 @findex ediff-toggle-multiframe
1488 If you don't like any of these setups, write your own function.  See the
1489 documentation for @code{ediff-window-setup-function} for the basic
1490 guidelines.  However, writing window setups is not easy, so you should
1491 first take a close look at @code{ediff-setup-windows-plain} and
1492 @code{ediff-setup-windows-multiframe}.
1493 @end table
1495 You can run multiple Ediff sessions at once, by invoking Ediff several
1496 times without exiting previous Ediff sessions.  Different sessions
1497 may even operate on the same pair of files.
1499 Each session has its own Ediff Control Panel and all the regarding a
1500 particular session is local to the associated control panel buffer.  You
1501 can switch between sessions by suspending one session and then switching
1502 to another control panel.  (Different control panel buffers are
1503 distinguished by a numerical suffix, e.g., @samp{Ediff Control Panel<3>}.)
1505 @node Selective Browsing, Highlighting Difference Regions, Window and Frame Configuration, Customization
1506 @section Selective Browsing
1508 Sometimes it is convenient to be able to step through only some difference
1509 regions, those that match certain regular expressions, and to ignore all
1510 others.  On other occasions, you may want to ignore difference regions that
1511 match some regular expressions, and to look only at the rest.
1513 The commands @kbd{#f} and @kbd{#h} let you do precisely this.
1515 Typing @kbd{#f} lets you specify regular expressions that match difference
1516 regions you want to focus on.
1517 We shall call these regular expressions @var{regexp-A}, @var{regexp-B} and
1518 @var{regexp-C}.
1519 Ediff will then start stepping through only those difference regions
1520 where the region in buffer A matches @var{regexp-A} and/or the region in
1521 buffer B matches @var{regexp-B}, etc.  Whether `and' or `or' will be used
1522 depends on how you respond to a question.
1524 When scanning difference regions for the aforesaid regular expressions,
1525 Ediff narrows the buffers to those regions.  This means that you can use
1526 the expressions @kbd{\`} and @kbd{\'} to tie search to the beginning or end
1527 of the difference regions.
1529 On the other hand, typing @kbd{#h} lets you specify (hide) uninteresting
1530 regions.  That is, if a difference region in buffer A matches
1531 @var{regexp-A}, the corresponding region in buffer B matches @var{regexp-B}
1532 and (if applicable) buffer C's region matches @var{regexp-C}, then the
1533 region will be ignored by the commands @kbd{n}/@key{SPC}
1534 (@code{ediff-next-difference}) and @kbd{p}/@key{DEL}
1535 (@code{ediff-previous-difference}) commands.
1537 Typing @kbd{#f} and @kbd{#h} toggles selective browsing on and off.
1539 Note that selective browsing affects only @code{ediff-next-difference}
1540 and @code{ediff-previous-difference}, i.e., the commands
1541 @kbd{n}/@key{SPC} and @kbd{p}/@key{DEL}.  @kbd{#f} and @kbd{#h} do not
1542 change the position of the point in the buffers.  And you can still jump
1543 directly (using @kbd{j})  to any numbered
1544 difference.
1546 Users can supply their own functions to specify how Ediff should do
1547 selective browsing.  To change the default Ediff function, add a function to
1548 @code{ediff-load-hook} which will do the following assignments:
1550 @example
1551 (setq ediff-hide-regexp-matches-function 'your-hide-function)
1552 (setq ediff-focus-on-regexp-matches-function 'your-focus-function)
1553 @end example
1555 @strong{Useful hint}: To specify a regexp that matches everything, don't
1556 simply type @key{RET} in response to a prompt.  Typing @key{RET} tells Ediff
1557 to accept the default value, which may not be what you want.  Instead, you
1558 should enter something like @key{^} or @key{$}.  These match every
1559 line.
1561 You can use the status command, @kbd{i}, to find out whether
1562 selective browsing is currently in effect.
1564 The regular expressions you specified are kept in the local variables
1565 @code{ediff-regexp-focus-A}, @code{ediff-regexp-focus-B},
1566 @code{ediff-regexp-focus-C}, @code{ediff-regexp-hide-A},
1567 @code{ediff-regexp-hide-B}, @code{ediff-regexp-hide-C}.  Their default value
1568 is the empty string (i.e., nothing is hidden or focused on).  To change the
1569 default, set these variables in @file{.emacs} using @code{setq-default}.
1571 In addition to the ability to ignore regions that match regular
1572 expressions, Ediff can be ordered to start skipping over certain
1573 ``uninteresting'' difference regions.  This is controlled by the following
1574 variable:
1576 @table @code
1577 @item ediff-ignore-similar-regions
1578 @vindex ediff-ignore-similar-regions
1579 If @code{t}, causes Ediff to skip over "uninteresting" difference regions,
1580 which are the regions where the variants differ only in the amount of the
1581 white space and newlines.  This feature can be toggled on/off interactively,
1582 via the command @kbd{##}.
1583 @end table
1585 @strong{Please note:} in order for this feature to work, auto-refining of
1586 difference regions must be on, since otherwise Ediff won't know if there
1587 are fine differences between regions.  On devices where Emacs can display
1588 faces, auto-refining is a default, but it is not turned on by default on
1589 text-only terminals.  In that case, you must explicitly turn auto-refining
1590 on (such as, by typing @kbd{@@}).
1592 @strong{Reassurance:} If many such uninteresting regions appear in a row,
1593 Ediff may take a long time to skip over them because it has to compute fine
1594 differences of all intermediate regions.  This delay does not indicate any
1595 problem.
1597 @vindex ediff-ignore-case-option
1598 @vindex ediff-ignore-case-option3
1599 @vindex ediff-ignore-case
1600 Finally, Ediff can be told to ignore the case of the letters. This behavior
1601 can be toggled with @kbd{#c} and it is controlled with three variables:
1602 Toggle case sensitivity in the diff program. All diffs are recomputed.
1603 Case sensitivity is controlled by the variables
1604 @code{ediff-ignore-case-option}, @code{ediff-ignore-case-option3}, and
1605 @code{ediff-ignore-case}.
1607 The variable @code{ediff-ignore-case-option} specifies the option to pass
1608 to the diff program for comparing two files or buffers. For GNU
1609 @code{diff}, this option is @code{"-i"}. The variable
1610 @code{ediff-ignore-case-option3} specifies the option to pass to the
1611 @code{diff3} program in order to make it case-insensitive. GNU @code{diff3}
1612 does not have such an option, so when merging or comparing three files with
1613 this program, ignoring the letter case is not supported.
1615 The variable @code{ediff-ignore-case} controls whether Ediff starts out by
1616 ignoring letter case or not. It can be set in @file{.emacs} using
1617 @code{setq-default}.
1619 @node Highlighting Difference Regions, Narrowing, Selective Browsing, Customization
1620 @section Highlighting Difference Regions
1622 The following variables control the way Ediff highlights difference
1623 regions:
1625 @table @code
1626 @item ediff-before-flag-bol
1627 @itemx ediff-after-flag-eol
1628 @itemx ediff-before-flag-mol
1629 @itemx ediff-after-flag-mol
1630 @vindex ediff-before-flag-bol
1631 @vindex ediff-after-flag-eol
1632 @vindex ediff-before-flag-mol
1633 @vindex ediff-after-flag-mol
1634 These variables hold strings that Ediff uses to mark the beginning and the
1635 end of the differences found in files A, B, and C on devices where Emacs
1636 cannot display faces.  Ediff uses different flags to highlight regions that
1637 begin/end at the beginning/end of a line or in a middle of a line.
1639 @item ediff-current-diff-face-A
1640 @itemx ediff-current-diff-face-B
1641 @itemx ediff-current-diff-face-C
1642 @vindex ediff-current-diff-face-A
1643 @vindex ediff-current-diff-face-B
1644 @vindex ediff-current-diff-face-C
1645 Ediff uses these faces to highlight current differences on devices where
1646 Emacs can display faces.  These and subsequently described faces can be set
1647 either in @file{.emacs} or in @file{.Xdefaults}.  The X resource for Ediff
1648 is @samp{Ediff}, @emph{not} @samp{emacs}.  Please refer to Emacs manual for
1649 the information on how to set X resources.
1650 @item ediff-fine-diff-face-A
1651 @itemx ediff-fine-diff-face-B
1652 @itemx ediff-fine-diff-face-C
1653 @vindex ediff-fine-diff-face-A
1654 @vindex ediff-fine-diff-face-B
1655 @vindex ediff-fine-diff-face-C
1656 Ediff uses these faces to show the fine differences between the current
1657 differences regions in buffers A, B, and C, respectively.
1659 @item ediff-even-diff-face-A
1660 @itemx ediff-even-diff-face-B
1661 @itemx ediff-even-diff-face-C
1662 @itemx ediff-odd-diff-face-A
1663 @itemx ediff-odd-diff-face-B
1664 @itemx ediff-odd-diff-face-C
1665 @vindex ediff-even-diff-face-A
1666 @vindex ediff-even-diff-face-B
1667 @vindex ediff-even-diff-face-C
1668 @vindex ediff-odd-diff-face-A
1669 @vindex ediff-odd-diff-face-B
1670 @vindex ediff-odd-diff-face-C
1671 Non-current difference regions are displayed using these alternating
1672 faces.  The odd and the even faces are actually identical on monochrome
1673 displays, because without colors options are limited.
1674 So, Ediff uses italics to highlight non-current differences.
1676 @item ediff-force-faces
1677 @vindex ediff-force-faces
1678 Ediff generally can detect when Emacs is running on a device where it can
1679 use highlighting with faces.  However, if it fails to determine that faces
1680 can be used, the user can set this variable to @code{t} to make sure that
1681 Ediff uses faces to highlight differences.
1683 @item ediff-highlight-all-diffs
1684 @vindex ediff-highlight-all-diffs
1685 Indicates whether---on a windowind display---Ediff should highlight
1686 differences using inserted strings (as on text-only terminals) or using
1687 colors and highlighting.  Normally, Ediff highlights all differences, but
1688 the selected difference is highlighted more visibly.  One can cycle through
1689 various modes of highlighting by typing @kbd{h}.  By default, Ediff starts
1690 in the mode where all difference regions are highlighted.  If you prefer to
1691 start in the mode where unselected differences are not highlighted, you
1692 should set @code{ediff-highlight-all-diffs} to @code{nil}.  Type @kbd{h} to
1693 restore highlighting for all differences.
1695 Ediff lets you switch between the two modes of highlighting.  That is,
1696 you can switch interactively from highlighting using faces to
1697 highlighting using string flags, and back.  Of course, switching has
1698 effect only under a windowing system.  On a text-only terminal or in an
1699 xterm window, the only available option is highlighting with strings.
1700 @end table
1702 @noindent
1703 If you want to change the default settings for @code{ediff-force-faces} and
1704 @code{ediff-highlight-all-diffs}, you must do it @strong{before} Ediff is
1705 loaded.
1707 You can also change the defaults for the faces used to highlight the
1708 difference regions.  There are two ways to do this.  The simplest and the
1709 preferred way is to use the customization widget accessible from the
1710 menubar.  Ediff's customization group is located under "Tools", which in
1711 turn is under "Programming".  The faces that are used to highlight
1712 difference regions are located in the "Highlighting" subgroup of the Ediff
1713 customization group.
1715 The second, much more arcane, method to change default faces is to include
1716 some Lisp code in @file{~/.emacs}.  For instance,
1718 @example
1719 (setq ediff-current-diff-face-A
1720       (copy-face 'bold-italic 'ediff-current-diff-face-A))
1721 @end example
1723 @noindent
1724 would use the pre-defined fase @code{bold-italic} to highlight the current
1725 difference region in buffer A (this face is not a good choice, by the way).
1727 If you are unhappy with just @emph{some} of the aspects of the default
1728 faces, you can modify them when Ediff is being loaded using
1729 @code{ediff-load-hook}.  For instance:
1731 @smallexample
1732 (add-hook 'ediff-load-hook
1733           (lambda ()
1734             (set-face-foreground
1735               ediff-current-diff-face-B "blue")
1736             (set-face-background
1737               ediff-current-diff-face-B "red")
1738             (make-face-italic
1739               ediff-current-diff-face-B)))
1740 @end smallexample
1742 @strong{Please note:} to set Ediff's faces, use only @code{copy-face}
1743 or @code{set/make-face-@dots{}} as shown above. Emacs' low-level
1744 face-manipulation functions should be avoided.
1746 @node Narrowing, Refinement of Difference Regions, Highlighting Difference Regions, Customization
1747 @section Narrowing
1749 If buffers being compared are narrowed at the time of invocation of
1750 Ediff, @code{ediff-buffers} will preserve the narrowing range.  However,
1751 if @code{ediff-files} is invoked on the files visited by these buffers,
1752 that would widen the buffers, since this command is defined to compare the
1753 entire files.
1755 Calling @code{ediff-regions-linewise} or @code{ediff-windows-linewise}, or
1756 the corresponding @samp{-wordwise} commands, narrows the variants to the
1757 particular regions being compared.  The original accessible ranges are
1758 restored when you quit Ediff.  During the command, you can toggle this
1759 narrowing on and off with the @kbd{%} command.
1761 These two variables control this narrowing behavior:
1763 @table @code
1764 @item ediff-start-narrowed
1765 @vindex ediff-start-narrowed
1766 If @code{t}, Ediff narrows the display to the appropriate range when it
1767 is invoked with an @samp{ediff-regions@dots{}} or
1768 @samp{ediff-windows@dots{}} command.  If @code{nil}, these commands do
1769 not automatically narrow, but you can still toggle narrowing on and off
1770 by typing @kbd{%}.
1772 @item ediff-quit-widened
1773 @vindex ediff-quit-widened
1774 Controls whether on quitting Ediff should restore the accessible range
1775 that existed before the current invocation.
1776 @end table
1778 @node Refinement of Difference Regions, Patch and Diff Programs, Narrowing, Customization
1779 @section Refinement of Difference Regions
1781 Ediff has variables to control the way fine differences are
1782 highlighted.  This feature gives you control over the process of refinement.
1783 Note that refinement ignores spaces, tabs, and newlines.
1785 @table @code
1786 @item ediff-auto-refine
1787 @vindex ediff-auto-refine
1788 This variable controls whether fine differences within regions are
1789 highlighted automatically (``auto-refining'').  The default is yes
1790 (@samp{on}).
1792 On a slow machine, automatic refinement may be painful.  In that case,
1793 you can turn auto-refining on or off interactively by typing
1794 @kbd{@@}.  You can also turn off display of refining that has
1795 already been done.
1797 When auto-refining is off, fine differences are shown only for regions
1798 for which these differences have been computed and saved before.  If
1799 auto-refining and display of refining are both turned off, fine
1800 differences are not shown at all.
1802 Typing @kbd{*} computes and displays fine differences for the current
1803 difference region, regardless of whether auto-refining is turned on.
1805 @item ediff-auto-refine-limit
1806 @vindex ediff-auto-refine-limit
1807 If auto-refining is on, this variable limits the size of the regions to
1808 be auto-refined.  This guards against the possible slowdown that may be
1809 caused by extraordinary large difference regions.
1811 You can always refine the current region by typing @kbd{*}.
1813 @item ediff-forward-word-function
1814 @vindex ediff-forward-word-function
1815 This variable controls how fine differences are computed.  The
1816 value must be a Lisp function that determines how the current difference
1817 region should be split into words.
1819 @vindex ediff-diff-program
1820 @vindex ediff-forward-word-function
1821 @findex ediff-forward-word
1822 Fine differences are computed by first splitting the current difference
1823 region into words and then passing the result to
1824 @code{ediff-diff-program}.  For the default forward word function (which is
1825 @code{ediff-forward-word}), a word is a string consisting of letters,
1826 @samp{-}, or @samp{_}; a string of punctuation symbols; a string of digits,
1827 or a string consisting of symbols that are neither space, nor a letter.
1829 This default behavior is controlled by four variables: @code{ediff-word-1},
1830 ..., @code{ediff-word-4}.  See the on-line documentation for these variables
1831 and for the function @code{ediff-forward-word} for an explanation of how to
1832 modify these variables.
1833 @vindex ediff-word-1
1834 @vindex ediff-word-2
1835 @vindex ediff-word-3
1836 @vindex ediff-word-4
1837 @end table
1839 Sometimes, when a region has too many differences between the variants,
1840 highlighting of fine differences is inconvenient, especially on
1841 color displays.  If that is the case, type @kbd{*} with a negative
1842 prefix argument.  This unhighlights fine differences for the current
1843 region.
1845 To unhighlight fine differences in all difference regions, use the
1846 command @kbd{@@}.  Repeated typing of this key cycles through three
1847 different states: auto-refining, no-auto-refining, and no-highlighting
1848 of fine differences.
1850 @node Patch and Diff Programs, Merging and diff3, Refinement of Difference Regions, Customization
1851 @section Patch and Diff Programs
1853 This section describes variables that specify the programs to be used for
1854 applying patches and for computing the main difference regions (not the
1855 fine difference regions):
1857 @table @code
1858 @item ediff-diff-program
1859 @itemx ediff-diff3-program
1860 @vindex ediff-patch-program
1861 @vindex ediff-diff-program
1862 @vindex ediff-diff3-program
1863 These variables specify the programs to use to produce differences
1864 and do patching.
1866 @item ediff-diff-options
1867 @itemx ediff-diff3-options
1868 @vindex ediff-patch-options
1869 @vindex ediff-diff-options
1870 @vindex ediff-diff3-options
1871 These variables specify the options to pass to the above utilities.
1873 In @code{ediff-diff-options}, it may be useful to specify options
1874 such as @samp{-w} that ignore certain kinds of changes.  However,
1875 Ediff does not let you use the option @samp{-c}, as it doesn't recognize this
1876 format yet.
1878 @item ediff-coding-system-for-read
1879 @vindex ediff-coding-system-for-read
1880 This variable specifies the coding system to use when reading the output
1881 that the programs @code{diff3} and @code{diff} send to Emacs. The default
1882 is @code{raw-text}, and this should work fine in Unix and in most
1883 cases under Windows NT/95/98/2000. There are @code{diff} programs
1884 for which the default option doesn't work under Windows. In such cases,
1885 @code{raw-text-dos} might work. If not, you will have to experiment with
1886 other coding systems or use GNU diff.
1888 @item ediff-patch-program
1889 The program to use to apply patches.  Since there are certain
1890 incompatibilities between the different versions of the patch program, the
1891 best way to stay out of trouble is to use a GNU-compatible version.
1892 Otherwise, you may have to tune the values of the variables
1893 @code{ediff-patch-options}, @code{ediff-backup-specs}, and
1894 @code{ediff-backup-extension} as described below.
1895 @item ediff-patch-options
1896 Options to pass to @code{ediff-patch-program}.
1898 Note: the `-b' and `-z' options should be specified in
1899 `ediff-backup-specs', not in @code{ediff-patch-options}.
1901 It is recommended to pass the `-f' option to the patch program, so it won't
1902 ask questions.  However, some implementations don't accept this option, in
1903 which case the default value of this variable should be changed.
1905 @item ediff-backup-extension
1906 Backup extension used by the patch program.  Must be specified, even if
1907 @code{ediff-backup-specs} is given.
1908 @item ediff-backup-specs
1909 Backup directives to pass to the patch program.
1910 Ediff requires that the old version of the file (before applying the patch)
1911 is saved in a file named @file{the-patch-file.extension}.  Usually
1912 `extension' is `.orig', but this can be changed by the user, and may also be
1913 system-dependent.  Therefore, Ediff needs to know the backup extension used
1914 by the patch program.
1916 Some versions of the patch program let the user specify `-b backup-extension'.
1917 Other versions only permit `-b', which (usually) assumes the extension `.orig'.
1918 Yet others force you to use `-z<backup-extension>'.
1920 Note that both `ediff-backup-extension' and `ediff-backup-specs' must be
1921 properly set.  If your patch program takes the option `-b', but not
1922 `-b extension', the variable `ediff-backup-extension' must still
1923 be set so Ediff will know which extension to use.
1925 @item ediff-custom-diff-program
1926 @itemx ediff-custom-diff-options
1927 @vindex ediff-custom-diff-program
1928 @vindex ediff-custom-diff-options
1929 @findex ediff-save-buffer
1930 Because Ediff limits the options you may want to pass to the @code{diff}
1931 program, it partially makes up for this drawback by letting you save the
1932 output from @code{diff} in your preferred format, which is specified via
1933 the above two variables.
1935 The output generated by @code{ediff-custom-diff-program} (which doesn't
1936 even have to be a standard-style @code{diff}!)@: is not used by Ediff.  It is
1937 provided exclusively so that you can
1938 refer to
1939 it later, send it over email, etc.  For instance, after reviewing the
1940 differences, you may want to send context differences to a colleague.
1941 Since Ediff ignores the @samp{-c} option in
1942 @code{ediff-diff-program}, you would have to run @code{diff -c} separately
1943 just to produce the list of differences.  Fortunately,
1944 @code{ediff-custom-diff-program} and @code{ediff-custom-diff-options}
1945 eliminate this nuisance by keeping a copy of a difference list in the
1946 desired format in a buffer that can be displayed via the command @kbd{D}.
1948 @item ediff-patch-default-directory
1949 @vindex ediff-patch-default-directory
1950 Specifies the default directory to look for patches.
1952 @end table
1954 @noindent
1955 @strong{Warning:} Ediff does not support the output format of VMS
1956 @code{diff}.  Instead, make sure you are using some implementation of POSIX
1957 @code{diff}, such as @code{gnudiff}.
1959 @node Merging and diff3, Support for Version Control, Patch and Diff Programs, Customization
1960 @section Merging and diff3
1962 Ediff supports three-way comparison via the functions @code{ediff-files3} and
1963 @code{ediff-buffers3}.  The interface is the same as for two-way comparison.
1964 In three-way comparison and merging, Ediff reports if any two difference
1965 regions are identical.  For instance, if the current region in buffer A
1966 is the same as the region in buffer C, then the mode line of buffer A will
1967 display @samp{[=diff(C)]} and the mode line of buffer C will display
1968 @samp{[=diff(A)]}.
1970 Merging is done according to the following algorithm.
1972 If a difference region in one of the buffers, say B, differs from the ancestor
1973 file while the region in the other buffer, A, doesn't, then the merge buffer,
1974 C, gets B's region.  Similarly when buffer A's region differs from
1975 the ancestor and B's doesn't, A's region is used.
1977 @vindex ediff-default-variant
1978 If both regions in buffers A and B differ from the ancestor file, Ediff
1979 chooses the region according to the value of the variable
1980 @code{ediff-default-variant}.  If its value is @code{default-A} then A's
1981 region is chosen.  If it is @code{default-B} then B's region is chosen.
1982 If it is @code{combined} then the region in buffer C will look like
1983 this:
1985 @comment Use @set to avoid triggering merge conflict detectors like CVS.
1986 @set seven-left <<<<<<<
1987 @set seven-right >>>>>>>
1988 @example
1989 @value{seven-left} variant A
1990 the difference region from buffer A
1991 @value{seven-right} variant B
1992 the difference region from buffer B
1993 ####### Ancestor
1994 the difference region from the ancestor buffer, if available
1995 ======= end
1996 @end example
1998 The above is the default template for the combined region. The user can
1999 customize this template using the variable
2000 @code{ediff-combination-pattern}.
2002 @vindex ediff-combination-pattern
2003 The variable @code{ediff-combination-pattern} specifies the template that
2004 determines how the combined merged region looks like.  The template is
2005 represented as a list of the form @code{(STRING1 Symbol1 STRING2 Symbol2
2006 STRING3 Symbol3 STRING4)}. The symbols here must be atoms of the form
2007 @code{A}, @code{B}, or @code{Ancestor}. They determine the order in which
2008 the corresponding difference regions (from buffers A, B, and the ancestor
2009 buffer) are displayed in the merged region of buffer C.  The strings in the
2010 template determine the text that separates the aforesaid regions. The
2011 default template is
2013 @smallexample
2014 ("@value{seven-left} variant A" A "@value{seven-right} variant B" B
2015    "####### Ancestor" Ancestor "======= end")
2016 @end smallexample
2018 @noindent
2019 (this is one long line) and the corresponding combined region is shown
2020 above. The order in which the regions are shown (and the separator
2021 strings) can be changed by changing the above template. It is even
2022 possible to add or delete region specifiers in this template (although
2023 the only possibly useful such modification seems to be the deletion of
2024 the ancestor).
2026 In addition to the state of the difference, Ediff displays the state of the
2027 merge for each region.  If a difference came from buffer A by default
2028 (because both regions A and B were different from the ancestor and
2029 @code{ediff-default-variant} was set to @code{default-A}) then
2030 @samp{[=diff(A) default-A]} is displayed in the mode line.  If the
2031 difference in buffer C came, say, from buffer B because the difference
2032 region in that buffer differs from the ancestor, but the region in buffer A
2033 does not (if merging with an ancestor) then @samp{[=diff(B) prefer-B]} is
2034 displayed.  The indicators default-A/B and prefer-A/B are inspired by
2035 Emerge and have the same meaning.
2037 Another indicator of the state of merge is @samp{combined}.  It appears
2038 with any difference region in buffer C that was obtained by combining
2039 the difference regions in buffers A and B as explained above.
2041 In addition to the state of merge and state of difference indicators, while
2042 merging with an ancestor file or buffer, Ediff informs the user when the
2043 current difference region in the (normally invisible) ancestor buffer is
2044 empty via the @emph{AncestorEmpty} indicator.  This helps determine if the
2045 changes made to the original in variants A and B represent pure insertion
2046 or deletion of text: if the mode line shows @emph{AncestorEmpty} and the
2047 corresponding region in buffers A or B is not empty, this means that new
2048 text was inserted.  If this indicator is not present and the difference
2049 regions in buffers A or B are non-empty, this means that text was
2050 modified.  Otherwise, the original text was deleted.
2052 Although the ancestor buffer is normally invisible, Ediff maintains
2053 difference regions there and advances the current difference region
2054 accordingly.  All highlighting of difference regions is provided in the
2055 ancestor buffer, except for the fine differences.  Therefore, if desired, the
2056 user can put the ancestor buffer in a separate frame and watch it
2057 there.  However, on a TTY, only one frame can be visible at any given time,
2058 and Ediff doesn't support any single-frame window configuration where all
2059 buffers, including the ancestor buffer, would be visible.  However, the
2060 ancestor buffer can be displayed by typing @kbd{/} to the control
2061 window.  (Type @kbd{C-l} to hide it again.)
2063 Note that the state-of-difference indicators @samp{=diff(A)} and
2064 @samp{=diff(B)} above are not redundant, even in the presence of a
2065 state-of-merge indicator.  In fact, the two serve different purposes.
2067 For instance, if the mode line displays @samp{=diff(B) prefer(B)} and
2068 you copy a difference region from buffer A to buffer C then
2069 @samp{=diff(B)} will change to @samp{diff-A} and the mode line will
2070 display @samp{=diff(A) prefer-B}.  This indicates that the difference
2071 region in buffer C is identical to that in buffer A, but originally
2072 buffer C's region came from buffer B.  This is useful to know because
2073 you can recover the original difference region in buffer C by typing
2074 @kbd{r}.
2077 Ediff never changes the state-of-merge indicator, except in response to
2078 the @kbd{!} command (see below), in which case the indicator is lost.
2079 On the other hand, the state-of-difference indicator is changed
2080 automatically by the copying/recovery commands, @kbd{a}, @kbd{b}, @kbd{r},
2081 @kbd{+}.
2083 The @kbd{!} command loses the information about origins of the regions
2084 in the merge buffer (default-A, prefer-B, or combined).  This is because
2085 recomputing differences in this case means running @code{diff3} on
2086 buffers A, B, and the merge buffer, not on the ancestor buffer.  (It
2087 makes no sense to recompute differences using the ancestor file, since
2088 in the merging mode Ediff assumes that you have not edited buffers A and
2089 B, but that you may have edited buffer C, and these changes are to be
2090 preserved.)  Since some difference regions may disappear as a result of
2091 editing buffer C and others may arise, there is generally no simple way
2092 to tell where the various regions in the merge buffer came from.
2094 In three-way comparison, Ediff tries to disregard regions that consist
2095 entirely of white space.  For instance, if, say, the current region in
2096 buffer A consists of the white space only (or if it is empty), Ediff will
2097 not take it into account for the purpose of computing fine differences.  The
2098 result is that Ediff can provide a better visual information regarding the
2099 actual fine differences in the non-white regions in buffers B and
2100 C.  Moreover, if the regions in buffers B and C differ in the white space
2101 only, then a message to this effect will be displayed.
2103 @vindex ediff-merge-window-share
2104 In the merge mode, the share of the split between window C (the window
2105 displaying the merge-buffer) and the windows displaying buffers A and B
2106 is controlled by the variable @code{ediff-merge-window-share}.  Its
2107 default value is 0.5.  To make the merge-buffer window smaller, reduce
2108 this amount.
2110 We don't recommend increasing the size of the merge-window to more than
2111 half the frame (i.e., to increase the value of
2112 @code{ediff-merge-window-share}) to more than 0.5, since it would be
2113 hard to see the contents of buffers A and B.
2115 You can temporarily shrink the merge window to just one line by
2116 typing @kbd{s}.  This change is temporary, until Ediff finds a reason to
2117 redraw the screen.  Typing @kbd{s} again restores the original window size.
2119 With a positive prefix argument, the @kbd{s} command will make the merge
2120 window slightly taller.  This change is persistent.  With `@kbd{-}' or
2121 with a negative prefix argument, the command @kbd{s} makes the merge
2122 window slightly shorter.  This change also persistent.
2124 @vindex ediff-show-clashes-only
2125 Ediff lets you automatically ignore the regions where only one of the
2126 buffers A and B disagrees with the ancestor.  To do this, set the
2127 variable @code{ediff-show-clashes-only} to non-@code{nil}.
2129 You can toggle this feature interactively by typing @kbd{$$}.
2131 Note that this variable affects only the show next/previous difference
2132 commands.  You can still jump directly to any difference region directly
2133 using the command @kbd{j} (with a prefix argument specifying the difference
2134 number).
2136 @vindex ediff-autostore-merges
2137 @vindex ediff-quit-merge-hook
2138 @findex ediff-maybe-save-and-delete-merge
2139 The variable @code{ediff-autostore-merges} controls what happens to the
2140 merge buffer when Ediff quits.  If the value is @code{nil}, nothing is done
2141 to the merge buffer---it will be the user's responsibility to save it.
2142 If the value is @code{t}, the user will be asked where to save the buffer
2143 and whether to delete it afterwards.  It the value is neither @code{nil} nor
2144 @code{t}, the merge buffer is saved @emph{only} if this merge session was
2145 invoked from a group of related Ediff session, such as those that result
2146 from @code{ediff-merge-directories},
2147 @code{ediff-merge-directory-revisions}, etc.
2148 @xref{Session Groups}.  This behavior is implemented in the function
2149 @code{ediff-maybe-save-and-delete-merge}, which is a hook in
2150 @code{ediff-quit-merge-hook}.  The user can supply a different hook, if
2151 necessary.
2153 The variable @code{ediff-autostore-merges} is buffer-local, so it can be
2154 set in a per-buffer manner.  Therefore, use @code{setq-default} to globally
2155 change this variable.
2157 @vindex ediff-merge-filename-prefix
2158 When merge buffers are saved automatically as directed by
2159 @code{ediff-autostore-merges}, Ediff attaches a prefix to each file, as
2160 specified by the variable @code{ediff-merge-filename-prefix}. The default
2161 is @code{merge_}, but this can be changed by the user.
2163 @node Support for Version Control, Customizing the Mode Line, Merging and diff3, Customization
2164 @section Support for Version Control
2167 Ediff supports version control and lets you compare versions of files
2168 visited by Emacs buffers via the function @code{ediff-revision}.  This
2169 feature is controlled by the following variables:
2171 @table @code
2172 @item ediff-version-control-package
2173 @vindex ediff-version-control-package
2174 A symbol.  The default is @samp{vc}.
2176 If you are like most Emacs users, Ediff will use VC as the version control
2177 package.  This is the standard Emacs interface to RCS, CVS, and SCCS.
2179 However, if your needs are better served by other interfaces, you will
2180 have to tell Ediff which version control package you are using, e.g.,
2181 @example
2182 (setq ediff-version-control-package 'rcs)
2183 @end example
2185 Apart from the standard @file{vc.el}, Ediff supports three other interfaces
2186 to version control: @file{rcs.el}, @file{pcl-cvs.el} (recently renamed
2187 pcvs.el), and @file{generic-sc.el}.  The package @file{rcs.el} is written
2188 by Sebastian Kremer <sk@@thp.Uni-Koeln.DE> and is available as
2189 @example
2190 @file{ftp.cs.buffalo.edu:pub/Emacs/rcs.tar.Z}
2191 @file{ftp.uni-koeln.de:/pub/gnu/emacs/rcs.tar.Z}
2192 @end example
2193 @pindex @file{vc.el}
2194 @pindex @file{rcs.el}
2195 @pindex @file{pcl-cvs.el}
2196 @pindex @file{generic-sc.el}
2197 @end table
2199 Ediff's interface to the above packages allows the user to compare the
2200 versions of the current buffer or to merge them (with or without an
2201 ancestor-version).  These operations can also be performed on directories
2202 containing files under version control.
2204 In case of @file{pcl-cvs.el}, Ediff can also be invoked via the function
2205 @code{run-ediff-from-cvs-buffer}---see the documentation string for this
2206 function.
2208 @node Customizing the Mode Line, Miscellaneous, Support for Version Control, Customization
2209 @section Customizing the Mode Line
2211 When Ediff is running, the mode line of @samp{Ediff Control Panel}
2212 buffer shows the current difference number and the total number of
2213 difference regions in the two files.
2215 The mode line of the buffers being compared displays the type of the
2216 buffer (@samp{A:}, @samp{B:}, or @samp{C:}) and (usually) the file name.
2217 Ediff tries to be intelligent in choosing the mode line buffer
2218 identification.  In particular, it works well with the
2219 @file{uniquify.el} and @file{mode-line.el} packages (which improve on
2220 the default way in which Emacs displays buffer identification).  If you
2221 don't like the way Ediff changes the mode line, you can use
2222 @code{ediff-prepare-buffer-hook} to modify the mode line.
2223 @vindex ediff-prepare-buffer-hook
2224 @pindex @file{uniquify.el}
2225 @pindex @file{mode-line.el}
2227 @node Miscellaneous, Notes on Heavy-duty Customization, Customizing the Mode Line, Customization
2228 @section Miscellaneous
2230 Here are a few other variables for customizing Ediff:
2232 @table @code
2233 @item ediff-split-window-function
2234 @vindex ediff-split-window-function
2235 Controls the way you want the window be split between file-A and file-B
2236 (and file-C, if applicable).  It defaults to the vertical split
2237 (@code{split-window-vertically}, but you can set it to
2238 @code{split-window-horizontally}, if you so wish.
2239 Ediff also lets you switch from vertical to horizontal split and back
2240 interactively.
2242 Note that if Ediff detects that all the buffers it compares are displayed in
2243 separate frames, it assumes that the user wants them to be so displayed
2244 and stops splitting windows.  Instead, it arranges for each buffer to
2245 be displayed in a separate frame.  You can switch to the one-frame mode
2246 by hiding one of the buffers A/B/C.
2248 You can also swap the windows where buffers are displayed by typing
2249 @kbd{~}.
2251 @item ediff-merge-split-window-function
2252 @vindex ediff-merge-split-window-function
2253 Controls how windows are
2254 split between buffers A and B in the merge mode.
2255 This variable is like @code{ediff-split-window-function}, but it defaults
2256 to @code{split-window-horizontally} instead of
2257 @code{split-window-vertically}.
2259 @item ediff-make-wide-display-function
2260 @vindex ediff-make-wide-display-function
2261 The value is a function to be called to widen the frame for displaying
2262 the Ediff buffers.  See the on-line documentation for
2263 @code{ediff-make-wide-display-function} for details.  It is also
2264 recommended to look into the source of the default function
2265 @code{ediff-make-wide-display}.
2267 You can toggle wide/regular display by typing @kbd{m}.  In the wide
2268 display mode, buffers A, B (and C, when applicable) are displayed in a
2269 single frame that is as wide as the entire workstation screen.  This is
2270 useful when files are compared side-by-side.  By default, the display is
2271 widened without changing its height.
2273 @item ediff-use-last-dir
2274 @vindex ediff-use-last-dir
2275 Controls the way Ediff presents the
2276 default directory when it prompts the user for files to compare.  If
2277 @code{nil},
2278 Ediff uses the default directory of the current buffer when it
2279 prompts the user for file names.  Otherwise, it will use the
2280 directories it had previously used for files A, B, or C, respectively.
2282 @item ediff-no-emacs-help-in-control-buffer
2283 @vindex ediff-no-emacs-help-in-control-buffer
2284 If @code{t}, makes @kbd{C-h}
2285 behave like the @key{DEL} key, i.e., it will move you back to the previous
2286 difference rather than invoking help.  This is useful when, in an xterm
2287 window or a text-only terminal, the Backspace key is bound to @kbd{C-h} and is
2288 positioned more conveniently than the @key{DEL} key.
2290 @item ediff-toggle-read-only-function
2291 @vindex ediff-toggle-read-only-function
2292 This variable's value is a function that Ediff uses to toggle
2293 the read-only property in its buffers.
2295 The default function that Ediff uses simply toggles the read-only property,
2296 unless the file is under version control.  For a checked-in file under
2297 version control, Ediff first tries to check the file out.
2299 @item ediff-make-buffers-readonly-at-startup nil
2300 @vindex ediff-make-buffers-readonly-at-startup
2301 If @code{t}, all variant buffers are made read-only at Ediff startup.
2303 @item ediff-keep-variants
2304 @vindex @code{ediff-keep-variants}
2305 The default is @code{t}, meaning that the buffers being compared or merged will
2306 be preserved when Ediff quits.  Setting this to @code{nil} causes Ediff to
2307 offer the user a chance to delete these buffers (if they are not modified).
2308 Supplying a prefix argument to the quit command (@code{q}) temporarily
2309 reverses the meaning of this variable.  This is convenient when the user
2310 prefers one of the behaviors most of the time, but occasionally needs the
2311 other behavior.
2313 However, Ediff temporarily resets this variable to @code{t} if it is
2314 invoked via one of the "buffer" jobs, such as @code{ediff-buffers}.
2315 This is because it is all too easy to loose day's work otherwise.
2316 Besides, in a "buffer" job, the variant buffers have already been loaded
2317 prior to starting Ediff, so Ediff just preserves status quo here.
2319 Using @code{ediff-cleanup-hook}, one can make Ediff delete the variants
2320 unconditionally (e.g., by making @code{ediff-janitor} into one of these hooks).
2321 @item ediff-grab-mouse
2322 @vindex @code{ediff-grab-mouse}
2323 Default is @code{t}.  Normally, Ediff grabs mouse and puts it in its
2324 control frame.  This is useful since the user can be sure that when he
2325 needs to type an Ediff command the focus will be in an appropriate Ediff's
2326 frame.  However, some users prefer to move the mouse by themselves.  The
2327 above variable, if set to @code{maybe}, will prevent Ediff from grabbing
2328 the mouse in many situations, usually after commands that may take more
2329 time than usual.  In other situation, Ediff will continue grabbing the mouse
2330 and putting it where it believes is appropriate.  If the value is
2331 @code{nil}, then mouse is entirely user's responsibility.
2332 Try different settings and see which one is for you.
2333 @end table
2336 @node Notes on Heavy-duty Customization, , Miscellaneous, Customization
2337 @section Notes on Heavy-duty Customization
2339 Some users need to customize Ediff in rather sophisticated ways, which
2340 requires different defaults for different kinds of files (e.g., SGML,
2341 etc.).  Ediff supports this kind of customization in several ways.  First,
2342 most customization variables are buffer-local.  Those that aren't are
2343 usually accessible from within Ediff Control Panel, so one can make them
2344 local to the panel by calling make-local-variable from within
2345 @code{ediff-startup-hook}.
2347 Second, the function @code{ediff-setup} accepts an optional sixth
2348 argument which has the form @code{((@var{var-name-1} .@: @var{val-1})
2349 (@var{var-name-2} .@: @var{val-2}) @dots{})}.  The function
2350 @code{ediff-setup} sets the variables in the list to the respective
2351 values, locally in the Ediff control buffer.  This is an easy way to
2352 throw in custom variables (which usually should be buffer-local) that
2353 can then be tested in various hooks.
2355 Make sure the variable @code{ediff-job-name} and @code{ediff-word-mode} are set
2356 properly in this case, as some things in Ediff depend on this.
2358 Finally, if you want custom-tailored help messages, you can set the
2359 variables @code{ediff-brief-help-message-function} and
2360 @code{ediff-long-help-message-function}
2361 to functions that return help strings.
2362 @vindex ediff-startup-hook
2363 @findex ediff-setup
2364 @vindex ediff-job-name
2365 @vindex ediff-word-mode
2366 @vindex ediff-brief-help-message-function
2367 @vindex ediff-long-help-message-function
2369 When customizing Ediff, some other variables are useful, although they are
2370 not user-definable.  They are local to the Ediff control buffer, so this
2371 buffer must be current when you access these variables.  The control buffer
2372 is accessible via the variable @code{ediff-control-buffer}, which is also
2373 local to that buffer.  It is usually used for checking if the current buffer
2374 is also the control buffer.
2376 Other variables of interest are:
2377 @table @code
2378 @item ediff-buffer-A
2379 The first of the data buffers being compared.
2381 @item ediff-buffer-B
2382 The second of the data buffers being compared.
2384 @item ediff-buffer-C
2385 In three-way comparisons, this is the third buffer being compared.
2386 In merging, this is the merge buffer.
2387 In two-way comparison, this variable is @code{nil}.
2389 @item ediff-window-A
2390 The window displaying buffer A.  If buffer A is not visible, this variable
2391 is @code{nil} or it may be a dead window.
2393 @item ediff-window-B
2394 The window displaying buffer B.
2396 @item ediff-window-C
2397 The window displaying buffer C, if any.
2399 @item ediff-control-frame
2400 A dedicated frame displaying the control buffer, if it exists.  It is
2401 non-@code{nil} only if Ediff uses the multiframe display, i.e., when
2402 the control buffer is in its own frame.
2403 @end table
2405 @node Credits, Index, Customization, Top
2406 @chapter Credits
2408 Ediff was written by Michael Kifer <kifer@@cs.stonybrook.edu>.  It was inspired
2409 by emerge.el written by Dale R.@: Worley <drw@@math.mit.edu>.  An idea due to
2410 Boris Goldowsky <boris@@cs.rochester.edu> made it possible to highlight
2411 fine differences in Ediff buffers.  Alastair Burt <burt@@dfki.uni-kl.de>
2412 ported Ediff to XEmacs, Eric Freudenthal <freudent@@jan.ultra.nyu.edu>
2413 made it work with VC, Marc Paquette <marcpa@@cam.org> wrote the
2414 toolbar support package for Ediff, and Hrvoje Niksic <hniksic@@xemacs.org>
2415 adapted it to the Emacs customization package.
2417 Many people provided help with bug reports, feature suggestions, and advice.
2418 Without them, Ediff would not be nearly as useful as it is today.
2419 Here is a hopefully full list of contributors:
2421 @example
2422 Adrian Aichner (aichner@@ecf.teradyne.com),
2423 Drew Adams (drew.adams@@oracle.com),
2424 Steve Baur (steve@@xemacs.org),
2425 Neal Becker (neal@@ctd.comsat.com),
2426 E.@: Jay Berkenbilt (ejb@@ql.org),
2427 Alastair Burt (burt@@dfki.uni-kl.de),
2428 Paul Bibilo (peb@@delcam.co.uk),
2429 Kevin Broadey (KevinB@@bartley.demon.co.uk),
2430 Harald Boegeholz (hwb@@machnix.mathematik.uni-stuttgart.de),
2431 Bradley A.@: Bosch (brad@@lachman.com),
2432 Michael D.@: Carney (carney@@ltx-tr.com),
2433 Jin S.@: Choi (jin@@atype.com),
2434 Scott Cummings (cummings@@adc.com),
2435 Albert Dvornik (bert@@mit.edu),
2436 Eric Eide (eeide@@asylum.cs.utah.edu),
2437 Paul Eggert (eggert@@twinsun.com),
2438 Urban Engberg (ue@@cci.dk),
2439 Kevin Esler (esler@@ch.hp.com),
2440 Robert Estes (estes@@ece.ucdavis.edu),
2441 Jay Finger (jayf@@microsoft.com),
2442 Xavier Fornari (xavier@@europe.cma.fr),
2443 Eric Freudenthal (freudent@@jan.ultra.nyu.edu),
2444 Job Ganzevoort (Job.Ganzevoort@@cwi.nl),
2445 Felix Heinrich Gatzemeier (felix.g@@tzemeier.info),
2446 Boris Goldowsky (boris@@cs.rochester.edu),
2447 Allan Gottlieb (gottlieb@@allan.ultra.nyu.edu),
2448 Aaron Gross (aaron@@bfr.co.il),
2449 Thorbjoern Hansen (thorbjoern.hansen@@mchp.siemens.de),
2450 Marcus Harnisch (marcus_harnisch@@mint-tech.com),
2451 Steven E. Harris (seh@@panix.com),
2452 Aaron S. Hawley (Aaron.Hawley@@uvm.edu),
2453 Xiaoli Huang (hxl@@epic.com),
2454 Andreas Jaeger (aj@@suse.de),
2455 Lars Magne Ingebrigtsen (larsi@@ifi.uio.no),
2456 Larry Gouge (larry@@itginc.com),
2457 Karl Heuer (kwzh@@gnu.org),
2458 (irvine@@lks.csi.com),
2459 (jaffe@@chipmunk.cita.utoronto.ca),
2460 David Karr (dkarr@@nmo.gtegsc.com),
2461 Norbert Kiesel (norbert@@i3.informatik.rwth-aachen.de),
2462 Leigh L Klotz (klotz@@adoc.xerox.com),
2463 Fritz Knabe (Fritz.Knabe@@ecrc.de),
2464 Heinz Knutzen (hk@@informatik.uni-kiel.d400.de),
2465 Andrew Koenig (ark@@research.att.com),
2466 Hannu Koivisto (azure@@iki.fi),
2467 Ken Laprade (laprade@@dw3f.ess.harris.com),
2468 Will C Lauer (wcl@@cadre.com),
2469 Richard Levitte (levitte@@e.kth.se),
2470 Mike Long (mike.long@@analog.com),
2471 Dave Love (d.love@@dl.ac.uk),
2472 Martin Maechler (maechler@@stat.math.ethz.ch),
2473 Simon Marshall (simon@@gnu.org),
2474 Paul C. Meuse (pmeuse@@delcomsys.com),
2475 Richard Mlynarik (mly@@adoc.xerox.com),
2476 Stefan Monnier (monnier@@cs.yale.edu),
2477 Chris Murphy (murphycm@@sun.aston.ac.uk),
2478 Erik Naggum (erik@@naggum.no),
2479 Eyvind Ness (Eyvind.Ness@@hrp.no),
2480 Ray Nickson (nickson@@cs.uq.oz.au),
2481 Dan Nicolaescu (dann@@ics.uci.edu),
2482 David Petchey (petchey_david@@jpmorgan.com),
2483 Benjamin Pierce (benjamin.pierce@@cl.cam.ac.uk),
2484 Francois Pinard (pinard@@iro.umontreal.ca),
2485 Tibor Polgar (tlp00@@spg.amdahl.com),
2486 David Prince (dave0d@@fegs.co.uk),
2487 Paul Raines (raines@@slac.stanford.edu),
2488 Stefan Reicher (xsteve@@riic.at),
2489 Charles Rich (rich@@merl.com),
2490 Bill Richter (richter@@math.nwu.edu),
2491 C.S.@: Roberson (roberson@@aur.alcatel.com),
2492 Kevin Rodgers (kevin.rodgers@@ihs.com),
2493 Sandy Rutherford (sandy@@ibm550.sissa.it),
2494 Heribert Schuetz (schuetz@@ecrc.de),
2495 Andy Scott (ascott@@pcocd2.intel.com),
2496 Axel Seibert (axel@@tumbolia.ppp.informatik.uni-muenchen.de),
2497 Vin Shelton (acs@@xemacs.org),
2498 Scott O. Sherman (Scott.Sherman@@mci.com),
2499 Richard Stallman (rms@@gnu.org),
2500 Richard Stanton (stanton@@haas.berkeley.edu),
2501 Sam Steingold (sds@@goems.com),
2502 Ake Stenhoff (etxaksf@@aom.ericsson.se),
2503 Stig (stig@@hackvan.com),
2504 Peter Stout (Peter_Stout@@cs.cmu.edu),
2505 Chuck Thompson (cthomp@@cs.uiuc.edu),
2506 Ray Tomlinson (tomlinso@@bbn.com),
2507 Raymond Toy (toy@@rtp.ericsson.se),
2508 Stephen J. Turnbull  (stephen@@xemacs.org),
2509 Jan Vroonhof (vroonhof@@math.ethz.ch),
2510 Colin Walters (walters@@cis.ohio-state.edu),
2511 Philippe Waroquiers (philippe.waroquiers@@eurocontrol.be),
2512 Klaus Weber (gizmo@@zork.north.de),
2513 Ben Wing (ben@@xemacs.org),
2514 Tom Wurgler (twurgler@@goodyear.com),
2515 Steve Youngs (youngs@@xemacs.org),
2516 Ilya Zakharevich (ilya@@math.ohio-state.edu),
2517 Eli Zaretskii (eliz@@is.elta.co.il)
2518 @end example
2520 @node Index, , Credits, Top
2521 @unnumbered Index
2522 @printindex cp
2524 @setchapternewpage odd
2525 @contents
2526 @bye
2528 @ignore
2529    arch-tag: 165ecb88-d03c-44b1-a921-b93f50b05b46
2530 @end ignore