X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/1f31cd602858d168d5c5fed6d3a9870c904c8364..dc6cc05f5c36bfc65379f3fa25267669402635ca:/man/ediff.texi diff --git a/man/ediff.texi b/man/ediff.texi index 016fa45968..7a4c929a0e 100644 --- a/man/ediff.texi +++ b/man/ediff.texi @@ -15,25 +15,22 @@ @synindex pg cp @synindex ky cp -@dircategory Emacs -@direntry -* Ediff: (ediff). A visual interface for comparing and merging programs. -@end direntry - @iftex @finalout @end iftex @c @smallbook @comment %**end of header (This is for running Texinfo on a region.) -@ifinfo +@copying This file documents Ediff, a comprehensive visual interface to Unix diff and patch utilities. -Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. +Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +2003, 2004, 2005, 2006 Free Software Foundation, Inc. +@quotation Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or +under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', and with the Back-Cover Texts as in (a) below. A copy of the @@ -48,9 +45,14 @@ This document is part of a collection distributed under the GNU Free Documentation License. If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license. -@end ifinfo +@end quotation +@end copying + +@dircategory Emacs +@direntry +* Ediff: (ediff). A visual interface for comparing and merging programs. +@end direntry -@iftex @titlepage @title Ediff User's Manual @sp 4 @@ -62,28 +64,9 @@ license to the document, as described in section 6 of the license. @page @vskip 0pt plus 1filll -@noindent -Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU -Manual'', and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License'' in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify -this GNU Manual, like GNU software. Copies published by the Free -Software Foundation raise funds for GNU development.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. +@insertcopying @end titlepage -@page -@end iftex + @node Top, Introduction, (dir), (dir) @@ -152,7 +135,7 @@ The architecture and the interface are, of course, drastically different. @chapter Major Entry Points When Ediff starts up, it displays a small control window, which accepts the -Ediff commands and two or three windows displaying the files to be compared +Ediff commands, and two or three windows displaying the files to be compared or merged. The control window can be in its own small frame or it can be part of a bigger frame that displays other buffers. In any case, it is important that the control window be active (i.e., be the one receiving the @@ -172,6 +155,12 @@ Compare, Merge, and Apply Patch. @findex ediff Compare two files. +@item ediff-backup +@findex ediff-backup +Compare a file with its backup. If there are several numerical backups, use +the latest. If the file is itself a backup, then compare it with its +original. + @item ediff-buffers @findex ediff-buffers Compare two buffers. @@ -262,8 +251,8 @@ utility to change the original files on disk. This is not that dangerous, since you will always have the original contents of the file saved in another file that has the extension @file{.orig}. Furthermore, if the file is under version control, then you can always back -out to one of the previous versions (see the section on Version Countrol in -Emacs manual). +out to one of the previous versions (see the section on Version Control in +the Emacs manual). @code{ediff-patch-file} is careful about versions control: if the file to be patched is checked in, then Ediff will offer to check it out, because @@ -658,7 +647,7 @@ user can always forcefully refine specific difference regions by typing @kindex h Cycles between full highlighting, the mode where fine differences are not highlighted (but computed), and the mode where highlighting is done with -ASCII strings. The latter is not really recommended, unless on a dumb TTY. +@acronym{ASCII} strings. The latter is not really recommended, unless on a dumb TTY. @item r @kindex r @@ -697,6 +686,16 @@ Even though such regions will be skipped over, you can still jump to any one of them by typing the region number and then `j'. Typing @kbd{##} again puts Ediff back in the original state. +@item #c +@kindex #c +@vindex ediff-ignore-case-option +@vindex ediff-ignore-case-option3 +@vindex ediff-ignore-case +Toggle case sensitivity in the diff program. All diffs are recomputed. +Case sensitivity is controlled by the variables +@code{ediff-ignore-case-option}, @code{ediff-ignore-case-option3}, +and @code{ediff-ignore-case}, which are explained elsewhere. + @item #h @itemx #f @kindex #f @@ -830,7 +829,7 @@ identical to its default setting, as originally decided by Ediff. For instance, if Ediff is merging according to the `combined' policy, then the merge region is skipped over if it is different from the combination of the regions in buffers A and B. (Warning: swapping buffers A and B will confuse -things in this respect). If the merge region is marked as `prefer-A' then +things in this respect.) If the merge region is marked as `prefer-A' then this region will be skipped if it differs from the current difference region in buffer A, etc. @@ -894,9 +893,20 @@ what exactly differs inside these chunks. Since eyeballing large pieces of text is contrary to human nature, Ediff has a special command to help reduce the risk of developing a cataract. -The above command compares regions within Ediff buffers. This creates a -child Ediff session for comparing current Emacs regions in buffers A, B, or -C as follows: +In other situations, the currently highlighted region might be big and you +might want to reconcile of them interactively. + +All of this can be done with the above command, @kbd{=}, which +compares regions within Ediff buffers. Typing @kbd{=} creates a +child Ediff session for comparing regions in buffers A, B, or +C as follows. + +First, you will be asked whether you want to compare the fine differences +between the currently highlighted buffers on a word-by-word basis. If you +accept, a child Ediff session will start using the currently highlighted +regions. Ediff will let you step over the differences word-wise. + +If you reject the offer, you will be asked to select regions of your choice. @emph{If you are comparing 2 files or buffers:} Ediff will ask you to select regions in buffers A and B. @@ -1073,7 +1083,7 @@ the only such group-level operation is the creation of a multi-file patch. @vindex ediff-autostore-merges For group sessions created to merge files, Ediff can store all merges automatically in a directory. The user is asked to specify such directory -if the value of @code{ediff-autostore-merges} is non-nil. If the value is +if the value of @code{ediff-autostore-merges} is non-@code{nil}. If the value is @code{nil}, nothing is done to the merge buffers---it will be the user's responsibility to save them. If the value is @code{t}, the user will be asked where to save the merge buffers in all merge jobs, even those that do @@ -1112,10 +1122,18 @@ multi-file patch. This is because, in the latter-style sessions, there are many ways to create diff output, and it is easier to handle by running Ediff on the inactive sessions. -Last, but not least, by typing @kbd{=}, you can quickly find out which -sessions have identical files, so you won't have to run Ediff on those +Last, but not least, by typing @kbd{==}, you can quickly find out which +sessions have identical entries, so you won't have to run Ediff on those sessions. This, however, works only on local, uncompressed files. For compressed or remote files, this command won't report anything. +Likewise, you can use @kbd{=h} to mark sessions with identical entries +for hiding or, with @kbd{=m}, for further operations. + +The comparison operations @kbd{==}, @kbd{=h}, and @kbd{=m} can recurse into +subdirectories to see if they have identical contents (so the user will not +need to descend into those subdirectories manually). These commands ask the +user whether or not to do a recursive descent. + @node Remote and Compressed Files, Customization, Session Groups, Top @@ -1437,7 +1455,7 @@ the control frame. To start Ediff with an iconified Control Panel, you should set this variable to @code{t} and @code{ediff-prefer-long-help-message} to @code{nil} (@pxref{Quick Help Customization}). This behavior is useful -only if icons are allowed to accept keybord input (which depend on the +only if icons are allowed to accept keyboard input (which depends on the window manager and other factors). @end table @@ -1564,7 +1582,7 @@ white space and newlines. This feature can be toggled on/off interactively, via the command @kbd{##}. @end table -@strong{Note:} In order for this feature to work, auto-refining of +@strong{Please note:} in order for this feature to work, auto-refining of difference regions must be on, since otherwise Ediff won't know if there are fine differences between regions. On devices where Emacs can display faces, auto-refining is a default, but it is not turned on by default on @@ -1576,6 +1594,29 @@ Ediff may take a long time to skip over them because it has to compute fine differences of all intermediate regions. This delay does not indicate any problem. +@vindex ediff-ignore-case-option +@vindex ediff-ignore-case-option3 +@vindex ediff-ignore-case +Finally, Ediff can be told to ignore the case of the letters. This behavior +can be toggled with @kbd{#c} and it is controlled with three variables: +@code{ediff-ignore-case-option}, @code{ediff-ignore-case-option3}, and +@code{ediff-ignore-case}. + +The variable @code{ediff-ignore-case-option} specifies the option to pass +to the diff program for comparing two files or buffers. For GNU +@code{diff}, this option is @code{"-i"}. The variable +@code{ediff-ignore-case-option3} specifies the option to pass to the +@code{diff3} program in order to make it case-insensitive. GNU @code{diff3} +does not have such an option, so when merging or comparing three files with +this program, ignoring the letter case is not supported. + +The variable @code{ediff-ignore-case} controls whether Ediff starts out by +ignoring letter case or not. It can be set in @file{.emacs} using +@code{setq-default}. + +When case sensitivity is toggled, all difference +regions are recomputed. + @node Highlighting Difference Regions, Narrowing, Selective Browsing, Customization @section Highlighting Difference Regions @@ -1642,7 +1683,7 @@ Ediff uses faces to highlight differences. @item ediff-highlight-all-diffs @vindex ediff-highlight-all-diffs -Indicates whether---on a windowind display---Ediff should highlight +Indicates whether---on a windowing display---Ediff should highlight differences using inserted strings (as on text-only terminals) or using colors and highlighting. Normally, Ediff highlights all differences, but the selected difference is highlighted more visibly. One can cycle through @@ -1681,7 +1722,7 @@ some Lisp code in @file{~/.emacs}. For instance, @end example @noindent -would use the pre-defined fase @code{bold-italic} to highlight the current +would use the pre-defined face @code{bold-italic} to highlight the current difference region in buffer A (this face is not a good choice, by the way). If you are unhappy with just @emph{some} of the aspects of the default @@ -1699,8 +1740,8 @@ faces, you can modify them when Ediff is being loaded using ediff-current-diff-face-B))) @end smallexample -@strong{Note:} To set Ediff's faces, use only @code{copy-face} or -@code{set/make-face-@dots{}} as shown above. Emacs' low-level +@strong{Please note:} to set Ediff's faces, use only @code{copy-face} +or @code{set/make-face-@dots{}} as shown above. Emacs' low-level face-manipulation functions should be avoided. @node Narrowing, Refinement of Difference Regions, Highlighting Difference Regions, Customization @@ -2258,7 +2299,7 @@ version control, Ediff first tries to check the file out. @item ediff-make-buffers-readonly-at-startup nil @vindex ediff-make-buffers-readonly-at-startup -If t, all variant buffers are made read-only at Ediff startup. +If @code{t}, all variant buffers are made read-only at Ediff startup. @item ediff-keep-variants @vindex @code{ediff-keep-variants} @@ -2278,6 +2319,14 @@ prior to starting Ediff, so Ediff just preserves status quo here. Using @code{ediff-cleanup-hook}, one can make Ediff delete the variants unconditionally (e.g., by making @code{ediff-janitor} into one of these hooks). + +@item ediff-keep-tmp-versions +@vindex @code{ediff-keep-tmp-versions} +Default is @code{nil}. If @code{t}, the versions of the files being +compared or merged using operations such as @code{ediff-revision} or +@code{ediff-merge-revisions} are not deleted on exit. The normal action is +to clean up and delete these version files. + @item ediff-grab-mouse @vindex @code{ediff-grab-mouse} Default is @code{t}. Normally, Ediff grabs mouse and puts it in its @@ -2344,11 +2393,11 @@ The second of the data buffers being compared. @item ediff-buffer-C In three-way comparisons, this is the third buffer being compared. In merging, this is the merge buffer. -In two-way comparison, this variable is nil. +In two-way comparison, this variable is @code{nil}. @item ediff-window-A The window displaying buffer A. If buffer A is not visible, this variable -is nil or it may be a dead window. +is @code{nil} or it may be a dead window. @item ediff-window-B The window displaying buffer B. @@ -2357,9 +2406,9 @@ The window displaying buffer B. The window displaying buffer C, if any. @item ediff-control-frame -A dedicated frame displaying the control buffer, if it exists. -It is non-nil only if Ediff uses the multiframe display, i.e., when the -control buffer is in its own frame. +A dedicated frame displaying the control buffer, if it exists. It is +non-@code{nil} only if Ediff uses the multiframe display, i.e., when +the control buffer is in its own frame. @end table @node Credits, Index, Customization, Top @@ -2374,12 +2423,13 @@ made it work with VC, Marc Paquette wrote the toolbar support package for Ediff, and Hrvoje Niksic adapted it to the Emacs customization package. -Many people provided help with bug reports, patches, and advice. +Many people provided help with bug reports, feature suggestions, and advice. Without them, Ediff would not be nearly as useful as it is today. -Here is a full list of contributors (I hope I didn't miss anyone): +Here is a hopefully full list of contributors: @example Adrian Aichner (aichner@@ecf.teradyne.com), +Drew Adams (drew.adams@@oracle.com), Steve Baur (steve@@xemacs.org), Neal Becker (neal@@ctd.comsat.com), E.@: Jay Berkenbilt (ejb@@ql.org), @@ -2401,10 +2451,14 @@ Jay Finger (jayf@@microsoft.com), Xavier Fornari (xavier@@europe.cma.fr), Eric Freudenthal (freudent@@jan.ultra.nyu.edu), Job Ganzevoort (Job.Ganzevoort@@cwi.nl), +Felix Heinrich Gatzemeier (felix.g@@tzemeier.info), Boris Goldowsky (boris@@cs.rochester.edu), Allan Gottlieb (gottlieb@@allan.ultra.nyu.edu), Aaron Gross (aaron@@bfr.co.il), Thorbjoern Hansen (thorbjoern.hansen@@mchp.siemens.de), +Marcus Harnisch (marcus_harnisch@@mint-tech.com), +Steven E. Harris (seh@@panix.com), +Aaron S. Hawley (Aaron.Hawley@@uvm.edu), Xiaoli Huang (hxl@@epic.com), Andreas Jaeger (aj@@suse.de), Lars Magne Ingebrigtsen (larsi@@ifi.uio.no), @@ -2414,6 +2468,7 @@ Karl Heuer (kwzh@@gnu.org), (jaffe@@chipmunk.cita.utoronto.ca), David Karr (dkarr@@nmo.gtegsc.com), Norbert Kiesel (norbert@@i3.informatik.rwth-aachen.de), +Steffen Kilb (skilb@@gmx.net), Leigh L Klotz (klotz@@adoc.xerox.com), Fritz Knabe (Fritz.Knabe@@ecrc.de), Heinz Knutzen (hk@@informatik.uni-kiel.d400.de), @@ -2433,6 +2488,7 @@ Chris Murphy (murphycm@@sun.aston.ac.uk), Erik Naggum (erik@@naggum.no), Eyvind Ness (Eyvind.Ness@@hrp.no), Ray Nickson (nickson@@cs.uq.oz.au), +Dan Nicolaescu (dann@@ics.uci.edu), David Petchey (petchey_david@@jpmorgan.com), Benjamin Pierce (benjamin.pierce@@cl.cam.ac.uk), Francois Pinard (pinard@@iro.umontreal.ca), @@ -2440,6 +2496,7 @@ Tibor Polgar (tlp00@@spg.amdahl.com), David Prince (dave0d@@fegs.co.uk), Paul Raines (raines@@slac.stanford.edu), Stefan Reicher (xsteve@@riic.at), +Charles Rich (rich@@merl.com), Bill Richter (richter@@math.nwu.edu), C.S.@: Roberson (roberson@@aur.alcatel.com), Kevin Rodgers (kevin.rodgers@@ihs.com), @@ -2477,3 +2534,7 @@ Eli Zaretskii (eliz@@is.elta.co.il) @setchapternewpage odd @contents @bye + +@ignore + arch-tag: 165ecb88-d03c-44b1-a921-b93f50b05b46 +@end ignore