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