Source

ediff / ediff.texi

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
\input texinfo                  @c -*-texinfo-*-
@c documentation for Ediff
@c Written by Michael Kifer

@comment %**start of header (This is for running Texinfo on a region.)

@comment Using ediff.info instead of ediff in setfilename breaks DOS.
@comment @setfilename ediff
@comment @setfilename ediff.info
@setfilename ../info/ediff

@settitle Ediff User's Manual
@synindex vr cp
@synindex fn cp
@synindex pg cp
@synindex ky cp

@iftex
@finalout
@end iftex
@c      @smallbook
@comment %**end of header (This is for running Texinfo on a region.)

@copying
This file documents Ediff, a comprehensive visual interface to Unix diff
and patch utilities.

Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
   2003, 2004, 2005 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''

This document is part of a collection distributed under the GNU Free
Documentation License.  If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying

@dircategory Editors
@direntry
* Ediff: (ediff).       A visual interface for comparing and merging programs.
@end direntry

@titlepage
@title Ediff User's Manual
@sp 4
@subtitle Ediff version 2.76.1
@sp 1
@subtitle January 2002
@sp 5
@author Michael Kifer
@page

@vskip 0pt plus 1filll
@insertcopying
@end titlepage


@node Top, Introduction, (dir), (dir)


@menu
* Introduction::                About Ediff.
* Major Entry Points::          How to use Ediff.
* Session Commands::            Ediff commands used within a session.
* Registry of Ediff Sessions::  Keeping track of multiple Ediff sessions.
* Session Groups::              Comparing and merging directories.
* Remote and Compressed Files::  You may want to know about this.
* Customization::               How to make Ediff work the way YOU want.
* Credits::                     Thanks to those who helped.
* Index::
@end menu

@node Introduction, Major Entry Points, Top, Top
@chapter Introduction

@cindex Comparing files and buffers
@cindex Merging files and buffers
@cindex Patching files and buffers
@cindex Finding differences

Ediff provides a convenient way for simultaneous browsing through
the differences between a pair (or a triple) of files or buffers
(which are called @samp{variants} for our purposes).  The
files being compared, file-A, file-B, and file-C (if applicable) are
shown in separate windows (side by side, one above the another, or in
separate frames), and the differences are highlighted as you step
through them.  You can also copy difference regions from one buffer to
another (and recover old differences if you change your mind).

Another powerful feature is the ability to merge a pair of files into a
third buffer.  Merging with an ancestor file is also supported.
Furthermore, Ediff is equipped with directory-level capabilities that
allow the user to conveniently launch browsing or merging sessions on
groups of files in two (or three) different directories.

In addition, Ediff can apply a patch to a file and then let you step through
both files, the patched and the original one, simultaneously,
difference-by-difference.  You can even apply a patch right out of a mail
buffer, i.e., patches received by mail don't even have to be saved.  Since
Ediff lets you copy differences between variants, you can, in effect, apply
patches selectively (i.e., you can copy a difference region from
@file{file.orig} to @file{file}, thereby undoing any particular patch that
you don't like).

Ediff even understands multi-file patches and can apply them interactively!
(Ediff can recognize multi-file patches only if they are in the context
format or GNU unified format.  All other patches are treated as 1-file
patches.  Ediff is [hopefully] using the same algorithm as @code{patch} to
determine which files need to be patched.)

Ediff is aware of version control, which lets you compare
files with their older versions.  Ediff also works with remote and
compressed files, automatically ftp'ing them over and uncompressing them.
@xref{Remote and Compressed Files}, for details.

This package builds upon ideas borrowed from Emerge, and several of Ediff's
functions are adaptations from Emerge.  Although Ediff subsumes and greatly
extends Emerge, much of the functionality in Ediff is influenced by Emerge.
The architecture and the interface are, of course, drastically different.

@node Major Entry Points, Session Commands, Introduction, Top
@chapter Major Entry Points

When Ediff starts up, it displays a small control window, which accepts the
Ediff commands and two or three windows displaying the files to be compared
or merged. The control window can be in its own small frame or it can be
part of a bigger frame that displays other buffers. In any case, it is
important that the control window be active (i.e., be the one receiving the
keystrokes) when you use Ediff. You can switch to other Emacs buffers at
will and even edit the files currently being compared with Ediff and then
switch back to Ediff at any time by activating the appropriate Emacs windows.

Ediff can be invoked interactively using the following functions, which can
be run either from the minibuffer or from the menu bar.  In the menu bar,
all Ediff's entry points belong to three submenus of the Tools menu:
Compare, Merge, and Apply Patch.

@table @code
@item ediff-files
@itemx ediff
@findex ediff-files
@findex ediff
Compare two files.

@item ediff-backup
@findex ediff-backup
Compare a file with its backup. If there are several numerical backups, use
the latest. If the file is itself a backup, then compare it with its
original.

@item ediff-buffers
@findex ediff-buffers
Compare two buffers.

@item ediff-files3
@itemx ediff3
@findex ediff-files3
@findex ediff3
Compare three files.

@item ediff-buffers3
@findex ediff-buffers3
Compare three buffers.

@item edirs
@itemx ediff-directories
@findex edirs
@findex ediff-directories
 Compare files common to two directories.
@item edirs3
@itemx ediff-directories3
@findex edirs3
@findex ediff-directories3
 Compare files common to three directories.
@item edir-revisions
@itemx ediff-directory-revisions
@findex ediff-directory-revisions
@findex edir-revisions
 Compare versions of files in a given directory.  Ediff selects only the
files that are under version control.
@item edir-merge-revisions
@itemx ediff-merge-directory-revisions
@findex edir-merge-revisions
@findex ediff-merge-directory-revisions
 Merge versions of files in a given directory.  Ediff selects only the
files that are under version control.
@item edir-merge-revisions-with-ancestor
@itemx ediff-merge-directory-revisions-with-ancestor
@findex edir-merge-revisions-with-ancestor
@findex ediff-merge-directory-revisions-with-ancestor
 Merge versions of files in a given directory using other versions as
ancestors.  Ediff selects only the files that are under version control.

@item ediff-windows-wordwise
@findex ediff-windows-wordwise
Compare windows word-by-word.

@item ediff-windows-linewise
@findex ediff-windows-linewise
Compare windows line-by-line.

@item ediff-regions-wordwise
@findex ediff-regions-wordwise
Compare regions word-by-word.  The regions can come from the same buffer
and they can even overlap.  You will be asked to specify the buffers that
contain the regions, which you want to compare. For each buffer, you will
also be asked to mark the regions to be compared. Pay attention to the
messages that appear in the minibuffer.

@item ediff-regions-linewise
@findex ediff-regions-linewise
Similar to @code{ediff-windows-linewise}, but compares the regions
line-by-line. See @code{ediff-windows-linewise} for more details.

@item ediff-revision
@findex ediff-revision
 Compare versions of the current buffer, if the buffer is visiting
 a file under version control.

@item ediff-patch-file
@itemx epatch
@findex ediff-patch-file
@findex epatch

Patch a file or multiple files, then compare.  If the patch applies to just
one file, Ediff will invoke a regular comparison session.  If it is a
multi-file patch, then a session group interface will be used and the user
will be able to patch the files selectively.  @xref{Session Groups}, for
more details.

Since the patch might be in a buffer or a file, you will be asked which is
the case. To avoid this extra prompt, you can invoke this command with a
prefix argument.  With an odd prefix argument, Ediff assumes the patch
is in a file; with an even argument, a buffer is assumed.

Note that @code{ediff-patch-file} will actually use the @code{patch}
utility to change the original files on disk.  This is not that
dangerous, since you will always have the original contents of the file
saved in another file that has the extension @file{.orig}.
Furthermore, if the file is under version control, then you can always back
out to one of the previous versions (see the section on Version Control in
the Emacs manual).

@code{ediff-patch-file} is careful about versions control: if the file
to be patched is checked in, then Ediff will offer to check it out, because
failing to do so may result in the loss of the changes when the file is
checked out the next time.

If you don't intend to modify the file via the patch and just want to see
what the patch is all about (and decide later), then
@code{ediff-patch-buffer} might be a better choice.

@item ediff-patch-buffer
@itemx epatch-buffer
@findex ediff-patch-buffer
@findex epatch-buffer
Patch a buffer, then compare.  The buffer being patched and the file visited
by that buffer (if any) is @emph{not} modified.  The result of the patch
appears in some other buffer that has the name ending with @emph{_patched}.

This function would refuse to apply a multifile patch to a buffer.  Use
@code{ediff-patch-file} for that (and when you want the original file to be
modified by the @code{patch} utility).

Since the patch might be in a buffer or a file, you will be asked which is
the case. To avoid this extra prompt, you can invoke this command with a
prefix argument.  With an odd prefix argument, Ediff assumes the patch
is in a file; with an even argument, a buffer is assumed.

@item ediff-merge-files
@itemx ediff-merge
@findex ediff-merge-files
@findex ediff-merge
Merge two files.

@item ediff-merge-files-with-ancestor
@itemx ediff-merge-with-ancestor
@findex ediff-merge-files-with-ancestor
@findex ediff-merge-with-ancestor
Like @code{ediff-merge}, but with a third ancestor file.

@item ediff-merge-buffers
@findex ediff-merge-buffers
Merge two buffers.

@item ediff-merge-buffers-with-ancestor
@findex ediff-merge-buffers-with-ancestor
Same but with ancestor.


@item edirs-merge
@itemx ediff-merge-directories
@findex edirs-merge
@findex ediff-merge-directories
 Merge files common to two directories.
@item edirs-merge-with-ancestor
@itemx ediff-merge-directories-with-ancestor
@findex edirs-merge-with-ancestor
@findex ediff-merge-directories-with-ancestor
 Same but using files in a third directory as ancestors.
 If a pair of files doesn't have an ancestor in the ancestor-directory, you
 will still be able to merge them without the ancestor.

@item ediff-merge-revisions
@findex ediff-merge-revisions
Merge two versions of the file visited by the current buffer.

@item ediff-merge-revisions-with-ancestor
@findex ediff-merge-revisions-with-ancestor
Same but with ancestor.

@item ediff-documentation
@findex ediff-documentation
Brings up this manual.

@item ediff-show-registry
@itemx eregistry
Brings up Ediff session registry.  This feature enables you to quickly find
and restart active Ediff sessions.
@end table

@noindent
If you want Ediff to be loaded from the very beginning of your Emacs
session, you should put this line in your @file{~/.emacs} file:

@example
(require 'ediff)
@end example

@noindent
Otherwise, Ediff will be loaded automatically when you use one of the
above functions, either directly or through the menus.

When the above functions are invoked, the user is prompted for all the
necessary information---typically the files or buffers to compare, merge, or
patch.  Ediff tries to be smart about these prompts.  For instance, in
comparing/merging files, it will offer the visible buffers as defaults.  In
prompting for files, if the user enters a directory, the previously input
file name will be appended to that directory.  In addition, if the variable
@code{ediff-use-last-dir} is not @code{nil}, Ediff will offer
previously entered directories as defaults (which will be maintained
separately for each type of file, A, B, or C).
@vindex @code{ediff-use-last-dir}

All the above functions use the POSIX @code{diff} or @code{diff3} programs
to find differences between two files.  They process the @code{diff} output
and display it in a convenient form.  At present, Ediff understands only
the plain output from diff.  Options such as @samp{-c} are not supported,
nor is the format produced by incompatible file comparison programs such as
the VMS version of @code{diff}.

The functions @code{ediff-files}, @code{ediff-buffers},
@code{ediff-files3}, @code{ediff-buffers3} first display the coarse,
line-based difference regions, as reported by the @code{diff} program.  The
total number of difference regions and the current difference number are
always displayed in the mode line of the control window.

Since @code{diff} may report fairly large chunks of text as being different,
even though the difference may be localized to just a few words or even
to the white space or line breaks, Ediff further @emph{refines} the
regions to indicate which exact words differ.  If the only difference is
in the white space and line breaks, Ediff says so.

On a color display, fine differences are highlighted with color; on a
monochrome display, they are underlined.  @xref{Highlighting Difference
Regions}, for information on how to customize this.

The commands @code{ediff-windows-wordwise},
@code{ediff-windows-linewise}, @code{ediff-regions-wordwise} and
@code{ediff-regions-linewise} do comparison on parts of existing Emacs
buffers.  The commands @code{ediff-windows-wordwise} and
@code{ediff-regions-wordwise} are intended for relatively small segments
of buffers (e.g., up to 100 lines, depending on the speed of your machine),
as they perform comparison on the basis of words rather than lines.
(Word-wise comparison of large chunks of text can be slow.)

To compare large regions, use @code{ediff-regions-linewise}.  This
command displays differences much like @code{ediff-files} and
@code{ediff-buffers}.

The functions @code{ediff-patch-file} and @code{ediff-patch-buffer} apply a
patch to a file or a buffer and then run Ediff on the appropriate
files/buffers, displaying the difference regions.

The entry points @code{ediff-directories}, @code{ediff-merge-directories},
etc., provide a convenient interface for comparing and merging files in
different directories.  The user is presented with Dired-like interface from
which one can run a group of related Ediff sessions.

For files under version control, @code{ediff-revision} lets you compare
the file visited by the current buffer to one of its checked-in versions.
You can also compare two checked-in versions of the visited file.
Moreover, the functions @code{ediff-directory-revisions},
@code{ediff-merge-directory-revisions}, etc., let you run a group of
related Ediff sessions by taking a directory and comparing (or merging)
versions of files in that directory.

@node Session Commands, Registry of Ediff Sessions, Major Entry Points, Top
@chapter Session Commands

All Ediff commands are displayed in a Quick Help window, unless you type
@kbd{?} to shrink the window to just one line.  You can redisplay the help
window by typing @kbd{?} again.  The Quick Help commands are detailed below.

Many Ediff commands take numeric prefix arguments.  For instance, if you
type a number, say 3, and then @kbd{j} (@code{ediff-jump-to-difference}),
Ediff moves to the third difference region.  Typing 3 and then @kbd{a}
(@code{ediff-diff-to-diff}) copies the 3d difference region from variant A
to variant B.  Likewise, 4 followed by @kbd{ra} restores the 4th difference
region in buffer A (if it was previously written over via the command
@kbd{a}).

Some commands take negative prefix arguments as well.  For instance, typing
@kbd{-} and then @kbd{j} will make the last difference region
current.  Typing @kbd{-2} then @kbd{j} makes the penultimate difference
region current, etc.

Without the prefix argument, all commands operate on the currently
selected difference region.  You can make any difference region
current using the various commands explained below.

For some commands, the actual value of the prefix argument is
immaterial.  However, if supplied, the prefix argument may modify the
command (see @kbd{ga}, @kbd{gb}, and @kbd{gc}).

@menu
* Quick Help Commands::             Frequently used commands.
* Other Session Commands::          Commands that are not bound to keys.
@end menu

@node Quick Help Commands,Other Session Commands,,Session Commands
@section Quick Help Commands

@table @kbd
@item ?
@kindex ?
Toggles the Ediff Quick Help window ON and OFF.
@item G
@kindex G
Prepares a mail buffer for sending a praise or a curse to the Ediff maintainer.

@item E
@kindex E
Brings up the top node of this manual, where you can find further
information on the various Ediff functions and advanced issues, such as
customization, session groups, etc.

@item v
@kindex v
Scrolls up buffers A and B (and buffer C where appropriate) in a
coordinated fashion.
@item V
@kindex V
Scrolls the buffers down.

@item <
@kindex <
Scrolls the buffers to the left simultaneously.
@item >
@kindex >
Scrolls buffers to the right.

@item wd
@kindex wd
Saves the output from the diff utility, for further reference.

With prefix argument, saves the plain output from @code{diff} (see
@code{ediff-diff-program} and @code{ediff-diff-options}).  Without the
argument, it saves customized @code{diff} output (see
@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options}), if
it is available.

@item wa
@kindex wa
Saves buffer A, if it was modified.
@item wb
@kindex wb
Saves buffer B, if it was modified.
@item wc
@kindex wc
Saves buffer C, if it was modified (if you are in a session that
compares three files simultaneously).

@item a
@kindex a
@emph{In comparison sessions:}
Copies the current difference region (or the region specified as the prefix
to this command) from buffer A to buffer B.
Ediff saves the old contents of buffer B's region; it can
be restored via the command @kbd{rb}, which see.

@emph{In merge sessions:}
Copies the current difference region (or the region specified as the prefix
to this command) from buffer A to the merge buffer.  The old contents of
this region in buffer C can be restored via the command @kbd{r}.

@item b
@kindex b
Works similarly, but copies the current difference region from buffer B to
buffer A (in @emph{comparison sessions}) or the merge buffer (in
@emph{merge sessions}).

Ediff saves the old contents of the difference region copied over; it can
be reinstated via the command @kbd{ra} in comparison sessions and
@kbd{r} in merge sessions.

@item ab
@kindex ab
Copies the current difference region (or the region specified as the prefix
to this command) from buffer A to buffer B.  This (and the next five)
command is enabled only in sessions that compare three files
simultaneously.  The old region in buffer B is saved and can be restored
via the command @kbd{rb}.
@item ac
@kindex ac
Copies the difference region from buffer A to buffer C.
The old region in buffer C is saved and can be restored via the command
@kbd{rc}.
@item ba
@kindex ba
Copies the difference region from buffer B to buffer A.
The old region in buffer A is saved and can be restored via the command
@kbd{ra}.
@item bc
@kindex bc
Copies the difference region from buffer B to buffer C.
The command @kbd{rc} undoes this.
@item ca
@kindex ca
Copies the difference region from buffer C to buffer A.
The command @kbd{ra} undoes this.
@item cb
@kindex cb
Copies the difference region from buffer C to buffer B.
The command @kbd{rb} undoes this.

@item p
@itemx DEL
@kindex p
@kindex DEL
Makes the previous difference region current.
@item n
@itemx SPC
@kindex n
@kindex SPC
Makes the next difference region current.

@item j
@itemx -j
@itemx Nj
@kindex j
Makes the very first difference region current.

@kbd{-j} makes the last region current.  Typing a number, N, and then `j'
makes the difference region N current.  Typing -N (a negative number) then
`j' makes current the region Last - N.

@item ga
@kindex ga
Makes current the difference region closest to the position of the point in
buffer A.

However, with a prefix argument, Ediff would position all variants
around the area indicated by the current point in buffer A: if
the point is inside a difference region, then the variants will be
positioned at this difference region.  If the point is not in any difference
region, then it is in an area where all variants agree with each other.  In
this case, the variants will be positioned so that each would display this
area (of agreement).
@item gb
@kindex gb
Makes current the difference region closest to the position of the point in
buffer B.

With a prefix argument, behaves like @kbd{ga}, but with respect to buffer B.
@item gc
@kindex gc
@emph{In merge sessions:}
makes current the difference region closest to the point in the merge buffer.

@emph{In 3-file comparison sessions:}
makes current the region closest to the point in buffer C.

With a prefix argument, behaves like @kbd{ga}, but with respect to buffer C.

@item !
@kindex !
Recomputes the difference regions, bringing them up to date.  This is often
needed because it is common to do all sorts of editing during Ediff
sessions, so after a while, the highlighted difference regions may no
longer reflect the actual differences among the buffers.

@item *
@kindex *
Forces refinement of the current difference region, which highlights the exact
words of disagreement among the buffers.  With a negative prefix argument,
unhighlights the current region.

Forceful refinement may be needed if Ediff encounters a difference region
that is larger than @code{ediff-auto-refine-limit}.  In this situation,
Ediff doesn't do automatic refinement in order to improve response time.
(Ediff doesn't auto-refine on dumb terminals as well, but @kbd{*} still
works there.  However, the only useful piece of information it can tell you
is whether or not the difference regions disagree only in the amount of
white space.)

This command is also useful when the highlighted fine differences are
no longer current, due to user editing.

@item m
@kindex m
Displays the current Ediff session in a frame as wide as the physical
display.  This is useful when comparing files side-by-side.  Typing `m' again
restores the original size of the frame.

@item |
@kindex |
Toggles the horizontal/vertical split of the Ediff display.  Horizontal
split is convenient when it is possible to compare files
side-by-side.  If the frame in which files are displayed is too narrow
and lines are cut off, typing @kbd{m} may help some.

@item @@
@kindex @@
Toggles auto-refinement of difference regions (i.e., automatic highlighting
of the exact words that differ among the variants).  Auto-refinement is
turned off on devices where Emacs doesn't support highlighting.

On slow machines, it may be advantageous to turn auto-refinement off.  The
user can always forcefully refine specific difference regions by typing
@kbd{*}.

@item h
@kindex h
Cycles between full highlighting, the mode where fine differences are not
highlighted (but computed), and the mode where highlighting is done with
@acronym{ASCII} strings.  The latter is not really recommended, unless on a dumb TTY.

@item r
@kindex r
Restores the old contents of the region in the merge buffer.
(If you copied a difference region from buffer A or B into the merge buffer
using the commands @kbd{a} or @kbd{b}, Ediff saves the old contents of the
region in case you change your mind.)

This command is enabled in merge sessions only.

@item ra
@kindex ra
Restores the old contents of the current difference region in buffer A,
which was previously saved when the user invoked one of these commands:
@kbd{b}, @kbd{ba}, @kbd{ca}, which see.  This command is enabled in
comparison sessions only.
@item rb
@kindex rb
Restores the old contents of the current difference region in buffer B,
which was previously saved when the user invoked one of these commands:
@kbd{a}, @kbd{ab}, @kbd{cb}, which see.  This command is enabled in
comparison sessions only.
@item rc
@kindex rc
Restores the old contents of the current difference region in buffer C,
which was previously saved when the user invoked one of these commands:
@kbd{ac}, @kbd{bc}, which see.  This command is enabled in 3-file
comparison sessions only.

@item ##
@kindex ##
Tell Ediff to skip over regions that disagree among themselves only in the
amount of white space and line breaks.

Even though such regions will be skipped over, you can still jump to any
one of them by typing the region number and then `j'.  Typing @kbd{##}
again puts Ediff back in the original state.

@item #h
@itemx #f
@kindex #f
@kindex #h
Ediff works hard to ameliorate the effects of boredom in the workplace...

Quite often differences are due to identical replacements (e.g., the word
`foo' is replaced with the word `bar' everywhere).  If the number of regions
with such boring differences exceeds your tolerance threshold, you may be
tempted to tell Ediff to skip these regions altogether (you will still be able
to jump to them via the command @kbd{j}).  The above commands, @kbd{#h}
and @kbd{#f}, may well save your day!

@kbd{#h} prompts you to specify regular expressions for each
variant.  Difference regions where each variant's region matches the
corresponding regular expression will be skipped from then on.  (You can
also tell Ediff to skip regions where at least one variant matches its
regular expression.)

@kbd{#f} does dual job: it focuses on regions that match the corresponding
regular expressions.  All other regions will be skipped
over.  @xref{Selective Browsing}, for more.

@item A
@kindex A
Toggles the read-only property in buffer A.
If file A is under version control and is checked in, it is checked out
(with your permission).
@item B
@kindex B
Toggles the read-only property in buffer B.
If file B is under version control and is checked in, it is checked out.
@item C
@kindex C
Toggles the read-only property in buffer C (in 3-file comparison sessions).
If file C is under version control and is checked in, it is checked out.

@item ~
@kindex ~
Swaps the windows where buffers A and B are displayed.  If you are comparing
three buffers at once, then this command would rotate the windows among
buffers A, B, and C.

@item i
@kindex i
Displays all kinds of useful data about the current Ediff session.
@item D
@kindex D
Runs @code{ediff-custom-diff-program} on the variants and displays the
buffer containing the output.  This is useful when you must send the output
to your Mom.

With a prefix argument, displays the plain @code{diff} output.
@xref{Patch and Diff Programs}, for details.

@item R
@kindex R
Displays a list of currently active Ediff sessions---the Ediff Registry.
You can then restart any of these sessions by either clicking on a session
record or by putting the cursor over it and then typing the return key.

(Some poor souls leave so many active Ediff sessions around that they loose
track of them completely...  The `R' command is designed to save these
people from the recently discovered Ediff Proficiency Syndrome.)

Typing @kbd{R} brings up Ediff Registry only if it is typed into an Ediff
Control Panel.  If you don't have a control panel handy, type this in the
minibuffer: @kbd{M-x eregistry}.  @xref{Registry of Ediff Sessions}.

@item M
@kindex M
Shows the session group buffer that invoked the current Ediff session.
@xref{Session Groups}, for more information on session groups.

@item z
@kindex z
Suspends the current Ediff session.  (If you develop a condition known as
Repetitive Ediff Injury---a serious but curable illness---you must change
your current activity.  This command tries hard to hide all Ediff-related
buffers.)

The easiest way to resume a suspended Ediff session is through the registry
of active sessions.  @xref{Registry of Ediff Sessions}, for details.
@item q
@kindex q
Terminates this Ediff session.  With a prefix argument (e.g.,@kbd{1q}), asks
if you also want to delete the buffers of the variants.
Modified files and the results of merges are never deleted.

@item %
@kindex %
Toggles narrowing in Ediff buffers.  Ediff buffers may be narrowed if you
are comparing only parts of these buffers via the commands
@code{ediff-windows-*} and @code{ediff-regions-*}, which see.

@item C-l
@kindex C-l
Restores the usual Ediff window setup.  This is the quickest way to resume
an Ediff session, but it works only if the control panel of that session is
visible.

@item $$
@kindex $$
While merging with an ancestor file, Ediff is determined to reduce user's
wear and tear by saving him and her much of unproductive, repetitive
typing.  If it notices that, say, file A's difference region is identical to
the same difference region in the ancestor file, then the merge buffer will
automatically get the difference region taken from buffer B.  The rationale
is that this difference region in buffer A is as old as that in the
ancestor buffer, so the contents of that region in buffer B represents real
change.

You may want to ignore such `obvious' merges and concentrate on difference
regions where both files `clash' with the ancestor, since this means that
two different people have been changing this region independently and they
had different ideas on how to do this.

The above command does this for you by skipping the regions where only one
of the variants clashes with the ancestor but the other variant agrees with
it.  Typing @kbd{$$} again undoes this setting.

@item $*
@kindex $*
When merging files with large number of differences, it is sometimes
convenient to be able to skip the difference regions for which you already
decided which variant is most appropriate. Typing @kbd{$*} will accomplish
precisely this.

To be more precise, this toggles the check for whether the current merge is
identical to its default setting, as originally decided by Ediff.  For
instance, if Ediff is merging according to the `combined' policy, then the
merge region is skipped over if it is different from the combination of the
regions in buffers A and B.  (Warning: swapping buffers A and B will confuse
things in this respect).  If the merge region is marked as `prefer-A' then
this region will be skipped if it differs from the current difference
region in buffer A, etc.

@item /
@kindex /
Displays the ancestor file during merges.
@item &
@kindex &
In some situations, such as when one of the files agrees with the ancestor file
on a difference region and the other doesn't, Ediff knows what to do: it copies
the current difference region from the second buffer into the merge buffer.

In other cases, the right course of action is not that clearcut, and Ediff
would use a default action.  The above command changes the default action.
The default action can be @samp{default-A} (choose the region from buffer
A), @samp{default-B} (choose the region from buffer B), or @samp{combined}
(combine the regions from the two buffers).
@xref{Merging and diff3}, for further details.

The command @kbd{&} also affects the regions in the merge buffers that have
@samp{default-A}, @samp{default-B}, or @samp{combined} status, provided
they weren't changed with respect to the original.  For instance, if such a
region has the status @samp{default-A} then changing the default action to
@samp{default-B} will also replace this merge-buffer's region with the
corresponding region from buffer B.

@item s
@kindex s
Causes the merge window shrink to its minimum size, thereby exposing as much
of the variant buffers as possible.  Typing `s' again restores
the original size of that window.

With a positive prefix argument, this command enlarges the merge window.
E.g., @kbd{4s} increases the size of the window by about 4 lines, if
possible.  With a negative numeric argument, the size of the merge window
shrinks by that many lines, if possible.  Thus, @kbd{-s} shrinks the window
by about 1 line and @kbd{-3s} by about 3 lines.

This command is intended only for temporary viewing; therefore, Ediff
restores window C to its original size whenever it makes any other change
in the window configuration.  However, redisplaying (@kbd{C-l}) or jumping
to another difference does not affect window C's size.

The split between the merge window and the variant windows is controlled by
the variable @code{ediff-merge-window-share}, which see.

@item +
@kindex +
Combines the difference regions from buffers A and B and copies the
result into the merge buffer.  @xref{Merging and diff3}, and the
variables @code{ediff-combine-diffs} and @code{ediff-combination-pattern}.


@item =
@kindex =
You may run into situations when a large chunk of text in one file has been
edited and then moved to a different place in another file.  In such a case,
these two chunks of text are unlikely to belong to the same difference
region, so the refinement feature of Ediff will not be able to tell you
what exactly differs inside these chunks.  Since eyeballing large pieces of
text is contrary to human nature, Ediff has a special command to help
reduce the risk of developing a cataract.

In other situations, the currently highlighted region might be big and you
might want to reconcile of them interactively.

All of this can be done with the above command, @kbd{=}, which
compares regions within Ediff buffers.  Typing @kbd{=} creates a
child Ediff session for comparing regions in buffers A, B, or
C as follows.

First, you will be asked whether you want to compare the fine differences
between the currently highlighted buffers on a word-by-word basis. If you
accept, a child Ediff session will start using the currently highlighted
regions. Ediff will let you step over the differences word-wise.

If you reject the offer, you will be asked to select regions of your choice.

@emph{If you are comparing 2 files or buffers:}
Ediff will ask you to select regions in buffers A and B.

@emph{If you are comparing 3 files or buffers simultaneously:} Ediff will
ask you to choose buffers and then select regions inside those buffers.

@emph{If you are merging files or buffers (with or without ancestor):}
Ediff will ask you to choose which buffer (A or B) to compare with the
merge buffer and then select regions in those buffers.

@end table

@node Other Session Commands,,Quick Help Commands,Session Commands
@section Other Session Commands

The following commands can be invoked from within any Ediff session,
although some of them are not bound to a key.

@table @code
@item eregistry
@itemx ediff-show-registry
@findex eregistry
@findex ediff-show-registry
This command brings up the registry of active Ediff sessions.  Ediff
registry is a device that can be used to resume any active Ediff session
(which may have been postponed because the user switched to some other
activity).  This command is also useful for switching between multiple
active Ediff sessions that are run at the same time.  The function
@code{eregistry} is an alias for @code{ediff-show-registry}.
@xref{Registry of Ediff Sessions}, for more information on this registry.

@item ediff-toggle-multiframe
@findex ediff-toggle-multiframe
Changes the display from the multi-frame mode (where the quick help window
is in a separate frame) to the single-frame mode (where all Ediff buffers
share the same frame), and vice versa.  See
@code{ediff-window-setup-function} for details on how to make either of
these modes the default one.

This function can also be invoked from the Menubar.  However, in some
cases, the change will take place only after you execute one of the Ediff
commands, such as going to the next difference or redisplaying.

@item ediff-toggle-use-toolbar
@findex ediff-toggle-use-toolbar
Available in XEmacs only.  The Ediff toolbar provides quick access to some
of the common Ediff functions.  This function toggles the display of the
toolbar.  If invoked from the menubar, the function may take sometimes
effect only after you execute an Ediff command, such as going to the next
difference.

@item ediff-use-toolbar-p
@vindex ediff-use-toolbar-p
The use of the toolbar can also be specified via the variable
@code{ediff-use-toolbar-p} (default is @code{t}).  This variable can be set
only in @file{.emacs} --- do @strong{not} change it interactively.  Use the
function @code{ediff-toggle-use-toolbar} instead.

@item ediff-revert-buffers-then-recompute-diffs
@findex ediff-revert-buffers-then-recompute-diffs
This command reverts the buffers you are comparing and recomputes their
differences.  It is useful when, after making changes, you decided to
make a fresh start, or if at some point you changed the files being
compared but want to discard any changes to comparison buffers that were
done since then.

This command normally asks for confirmation before reverting files.
With a prefix argument, it reverts files without asking.


@item ediff-profile
@findex ediff-profile
Ediff has an admittedly primitive (but useful) facility for profiling
Ediff's commands.  It is meant for Ediff maintenance---specifically, for
making it run faster.  The function @code{ediff-profile} toggles
profiling of ediff commands.
@end table

@node Registry of Ediff Sessions, Session Groups, Session Commands, Top
@chapter Registry of Ediff Sessions

Ediff maintains a registry of all its invocations that are
still @emph{active}.  This feature is very convenient for switching among
active Ediff sessions or for quickly restarting a suspended Ediff session.

The focal point of this activity is a buffer
called @emph{*Ediff Registry*}.  You can display this buffer by typing
@kbd{R} in any Ediff Control Buffer or Session Group Buffer
(@pxref{Session Groups}), or by typing
@kbd{M-x eregistry} into the Minibuffer.
The latter would be the fastest way to bring up the registry
buffer if no control or group buffer is displayed in any of the visible
Emacs windows.
If you are in a habit of running multiple long Ediff sessions and often need to
suspend, resume, or switch between them, it may be a good idea to have the
registry buffer permanently displayed in a separate, dedicated window.

The registry buffer has several convenient key bindings.
For instance, clicking mouse button 2 or typing
@kbd{RET} or @kbd{v} over any session record resumes that session.
Session records in the registry buffer provide a fairly complete
description of each session, so it is usually easy to identify the right
session to resume.

Other useful commands are bound to @kbd{SPC} (next registry record)
and @kbd{DEL} (previous registry record).  There are other commands as well,
but you don't need to memorize them, since they are listed at the top of
the registry buffer.

@node Session Groups, Remote and Compressed Files, Registry of Ediff Sessions, Top
@chapter Session Groups

Several major entries of Ediff perform comparison and merging on
directories.  On entering @code{ediff-directories},
@code{ediff-directories3},
@code{ediff-merge-directories},
@code{ediff-merge-directories-with-ancestor},
@code{ediff-directory-revisions},
@code{ediff-merge-directory-revisions}, or
@code{ediff-merge-directory-revisions-with-ancestor},
the user is presented with a
Dired-like buffer that lists files common to the directories involved along
with their sizes.  (The list of common files can be further filtered through
a regular expression, which the user is prompted for.)  We call this buffer
@emph{Session Group Panel} because all Ediff sessions associated with the
listed files will have this buffer as a common focal point.

Clicking button 2 or typing @kbd{RET} or @kbd{v} over a
record describing files invokes Ediff in the appropriate mode on these
files.  You can come back to the session group buffer associated with a
particular invocation of Ediff by typing @kbd{M} in Ediff control buffer of
that invocation.

Many commands are available in the session group buffer; some are
applicable only to certain types of work.  The relevant commands are always
listed at the top of each session group buffer, so there is no need to
memorize them.

In directory comparison or merging, a session group panel displays only the
files common to all directories involved.  The differences are kept in a
separate @emph{directory difference buffer} and are conveniently displayed
by typing @kbd{D} to the corresponding session group panel.  Thus, as an
added benefit, Ediff can be used to compare the contents of up to three
directories.

@cindex Directory difference buffer
Sometimes it is desirable to copy some files from one directory to another
without exiting Ediff. The @emph{directory difference buffer}, which is
displayed by typing @kbd{D} as discussed above, can be used for this
purpose. If a file is, say, in Ediff's Directory A, but is missing in
Ediff's Directory B (Ediff will refuse to override existing files), then
typing @kbd{C} or clicking mouse button 2 over that file (which must be
displayed in directory difference buffer) will copy that file from
Directory A to Directory B.

Session records in session group panels are also marked with @kbd{+}, for
active sessions, and with @kbd{-}, for finished sessions.

Sometimes, it is convenient to exclude certain sessions from a group.
Usually this happens when the user doesn't intend to run Ediff of certain
files in the group, and the corresponding session records just add clutter
to the session group buffer.  To help alleviate this problem, the user can
type @kbd{h} to mark a session as a candidate for exclusion and @kbd{x} to
actually hide the marked sessions.  There actions are reversible: with a
prefix argument, @kbd{h} unmarks the session under the cursor, and @kbd{x}
brings the hidden sessions into the view (@kbd{x} doesn't unmark them,
though, so the user has to explicitly unmark the sessions of interest).

Group sessions also understand the command @kbd{m}, which marks sessions
for future operations (other than hiding) on a group of sessions.  At present,
the only such group-level operation is the creation of a multi-file patch.

@vindex ediff-autostore-merges
For group sessions created to merge files, Ediff can store all merges
automatically in a directory.  The user is asked to specify such directory
if the value of @code{ediff-autostore-merges} is non-@code{nil}.  If the value is
@code{nil}, nothing is done to the merge buffers---it will be the user's
responsibility to save them.  If the value is @code{t}, the user will be
asked where to save the merge buffers in all merge jobs, even those that do
not originate from a session group.  It the value is neither @code{nil} nor
@code{t}, the merge buffer is saved @emph{only} if this merge session was
invoked from a session group.  This behavior is implemented in the function
@code{ediff-maybe-save-and-delete-merge}, which is a hook in
@code{ediff-quit-merge-hook}.  The user can supply a different hook, if
necessary.

The variable @code{ediff-autostore-merges} is buffer-local, so it can be
set on a per-buffer basis.  Therefore, use @code{setq-default} to change
this variable globally.

@cindex Multi-file patches
A multi-file patch is a concatenated output of several runs of the Unix
@code{diff} command (some versions of @code{diff} let you create a
multi-file patch in just one run).  Ediff facilitates creation of
multi-file patches as follows.  If you are in a session group buffer
created in response to @code{ediff-directories} or
@code{ediff-directory-revisions}, you can mark (by typing @kbd{m}) the
desired Ediff sessions and then type @kbd{P} to create a
multi-file patch of those marked sessions.
Ediff will then display a buffer containing the patch.
The patch is generated by invoking @code{diff} on all marked individual
sessions (represented by files) and session groups (represented by
directories).  Ediff will also recursively descend into any @emph{unmarked}
session group and will search for marked sessions there.  In this way, you
can create multi-file patches that span file subtrees that grow out of
any given directory.

In an @code{ediff-directories} session, it is enough to just mark the
requisite sessions.  In @code{ediff-directory-revisions} revisions, the
marked sessions must also be active, or else Ediff will refuse to produce a
multi-file patch.  This is because, in the latter-style sessions, there are
many ways to create diff output, and it is easier to handle by running
Ediff on the inactive sessions.

Last, but not least, by typing @kbd{==}, you can quickly find out which
sessions have identical entries, so you won't have to run Ediff on those
sessions.  This, however, works only on local, uncompressed files.
For compressed or remote files, this command won't report anything.
Likewise, you can use @kbd{=h} to mark sessions with identical entries
for hiding or, with @kbd{=m}, for further operations.

The comparison operations @kbd{==}, @kbd{=h}, and @kbd{=m} can recurse into
subdirectories to see if they have identical contents (so the user will not
need to descend into those subdirectories manually). These commands ask the
user whether or not to do a recursive descent.



@node Remote and Compressed Files, Customization, Session Groups, Top
@chapter Remote and Compressed Files

Ediff works with remote, compressed, and encrypted files.  Ediff
supports @file{ange-ftp.el}, @file{jka-compr.el}, @file{uncompress.el}
and @file{crypt++.el}, but it may work with other similar packages as
well.  This means that you can compare files residing on another
machine, or you can apply a patch to a file on another machine.  Even
the patch itself can be a remote file!

When patching compressed or remote files, Ediff does not rename the source
file (unlike what the @code{patch} utility would usually do).  Instead, the
source file retains its name and the result of applying the patch is placed
in a temporary file that has the suffix @file{_patched} attached.
Generally, this applies to files that are handled using black magic, such
as special file handlers (ange-ftp and some compression and encryption
packages also use this method).

Regular files are treated by the @code{patch} utility in the usual manner,
i.e., the original is renamed into @file{source-name.orig} and the result
of the patch is placed into the file source-name (@file{_orig} is used
on systems like VMS, DOS, etc.)

@node Customization, Credits, Remote and Compressed Files, Top
@chapter Customization

Ediff has a rather self-explanatory interface, and in most cases you
won't need to change anything.  However, should the need arise, there are
extensive facilities for changing the default behavior.

Most of the customization can be done by setting various variables in the
@file{.emacs} file.  Some customization (mostly window-related
customization and faces) can be done by putting appropriate lines in
@file{.Xdefaults}, @file{.xrdb}, or whatever X resource file is in use.

With respect to the latter, please note that the X resource
for Ediff customization is `Ediff', @emph{not} `emacs'.
@xref{Window and Frame Configuration},
@xref{Highlighting Difference Regions}, for further details.  Please also
refer to Emacs manual for the information on how to set Emacs X resources.

@menu
* Hooks::                       Customization via the hooks.
* Quick Help Customization::    How to customize Ediff's quick help feature.
* Window and Frame Configuration::  Controlling the way Ediff displays things.
* Selective Browsing::          Advanced browsing through difference regions.
* Highlighting Difference Regions::  Controlling highlighting.
* Narrowing::                   Comparing regions, windows, etc.
* Refinement of Difference Regions::  How to control the refinement process.
* Patch and Diff Programs::     Changing the utilities that compute differences
                                and apply patches.
* Merging and diff3::           How to customize Ediff in its Merge Mode.
* Support for Version Control::  Changing the version control package.
                                 You are not likely to do that.
* Customizing the Mode Line::   Changing the look of the mode line in Ediff.
* Miscellaneous::               Other customization.
* Notes on Heavy-duty Customization::  Customization for the gurus.
@end menu

@node Hooks, Quick Help Customization, Customization, Customization
@section Hooks

The bulk of customization can be done via the following hooks:

@table @code
@item ediff-load-hook
@vindex ediff-load-hook
This hook can be used to change defaults after Ediff is loaded.

@item ediff-before-setup-hook
@vindex ediff-before-setup-hook
Hook that is run just before Ediff rearranges windows to its liking.
Can be used to save windows configuration.

@item ediff-keymap-setup-hook
@vindex ediff-keymap-setup-hook
@vindex ediff-mode-map
This hook can be used to alter bindings in Ediff's keymap,
@code{ediff-mode-map}.  These hooks are
run right after the default bindings are set but before
@code{ediff-load-hook}.  The regular user needs not be concerned with this
hook---it is provided for implementors of other Emacs packages built on top
of Ediff.

@item ediff-before-setup-windows-hook
@itemx ediff-after-setup-windows-hook
@vindex ediff-before-setup-windows-hook
@vindex ediff-after-setup-windows-hook
These two hooks are called before and after Ediff sets up its window
configuration.  These hooks are run each time Ediff rearranges windows to
its liking. This happens whenever it detects that the user changed the
windows setup.

@item ediff-suspend-hook
@itemx ediff-quit-hook
@vindex ediff-suspend-hook
@vindex ediff-quit-hook
These two hooks are run when you suspend or quit Ediff.  They can be
used to set desired window configurations, delete files Ediff didn't
want to clean up after exiting, etc.

By default, @code{ediff-quit-hook} holds one hook function,
@code{ediff-cleanup-mess}, which cleans after Ediff, as appropriate in
most cases.  You probably won't want to change it, but you might
want to add other hook functions.

Keep in mind that hooks executing before @code{ediff-cleanup-mess} start
in @code{ediff-control-buffer;} they should also leave
@code{ediff-control-buffer} as the current buffer when they finish.
Hooks that are executed after @code{ediff-cleanup-mess} should expect
the current buffer be either buffer A or buffer B.
@code{ediff-cleanup-mess} doesn't kill the buffers being compared or
merged (see @code{ediff-cleanup-hook}, below).

@item ediff-cleanup-hook
@vindex ediff-cleanup-hook
This hook is run just before @code{ediff-quit-hook}.  This is a good
place to do various cleanups, such as deleting the variant buffers.
Ediff provides a function, @code{ediff-janitor}, as one such possible
hook, which you can add to @code{ediff-cleanup-hook} with
@code{add-hooks}.

@findex ediff-janitor
This function kills buffers A, B, and, possibly, C, if these buffers aren't
modified.  In merge jobs, buffer C is never deleted.  However, the side
effect of using this function is that you may not be able to compare the
same buffer in two separate Ediff sessions: quitting one of them will
delete this buffer in another session as well.

@item ediff-quit-merge-hook
@vindex ediff-quit-merge-hook
@vindex ediff-autostore-merges
@findex ediff-maybe-save-and-delete-merge
This hook is called when Ediff quits a merge job.  By default, the value is
@code{ediff-maybe-save-and-delete-merge}, which is a function that attempts
to save the merge buffer according to the value of
@code{ediff-autostore-merges}, as described later.

@item ediff-before-setup-control-frame-hook
@itemx ediff-after-setup-control-frame-hook
@vindex ediff-before-setup-control-frame-hook
@vindex ediff-after-setup-control-frame-hook
These two hooks run before and after Ediff sets up the control frame.
They can be used to relocate Ediff control frame when Ediff runs in a
multiframe mode (i.e., when the control buffer is in its own dedicated
frame).  Be aware that many variables that drive Ediff are local to
Ediff Control Panel (@code{ediff-control-buffer}), which requires
special care in writing these hooks.  Take a look at
@code{ediff-default-suspend-hook} and @code{ediff-default-quit-hook} to
see what's involved.

@item ediff-startup-hook
@vindex ediff-startup-hook
This hook is run at the end of Ediff startup.

@item ediff-select-hook
@vindex ediff-select-hook
This hook is run after Ediff selects the next difference region.

@item ediff-unselect-hook
@vindex ediff-unselect-hook
This hook is run after Ediff unselects the current difference region.

@item ediff-prepare-buffer-hook
@vindex ediff-prepare-buffer-hook
This hook is run for each Ediff buffer (A, B, C) right after the buffer
is arranged.

@item ediff-display-help-hook
@vindex ediff-display-help-hook
Ediff runs this hook each time after setting up the help message.  It
can be used to alter the help message for custom packages that run on
top of Ediff.

@item ediff-mode-hook
@vindex ediff-mode-hook
This hook is run just after Ediff mode is set up in the control
buffer.  This is done before any Ediff window is created.  You can use it to
set local variables that alter the look of the display.

@item ediff-registry-setup-hook
@vindex ediff-registry-setup-hook
Hooks run after setting up the registry for all active Ediff session.
@xref{Session Groups}, for details.
@item ediff-before-session-group-setup-hook
@vindex ediff-before-session-group-setup-hook
Hooks run before setting up a control panel for a group of related Ediff
sessions. Can be used, for example, to save window configuration to restore
later.
@item ediff-after-session-group-setup-hook
@vindex ediff-after-session-group-setup-hook
Hooks run after setting up a control panel for a group of related Ediff
sessions.  @xref{Session Groups}, for details.
@item ediff-quit-session-group-hook
@vindex ediff-quit-session-group-hook
Hooks run just before exiting a session group.
@item ediff-meta-buffer-keymap-setup-hook
@vindex ediff-meta-buffer-keymap-setup-hook
@vindex ediff-meta-buffer-map
Hooks run just after setting up the @code{ediff-meta-buffer-map} --- the
map that controls key bindings in the meta buffer.  Since
@code{ediff-meta-buffer-map} is a local variable, you can set different
bindings for different kinds of meta buffers.
@end table

@node Quick Help Customization, Window and Frame Configuration, Hooks, Customization
@section Quick Help Customization
@vindex ediff-use-long-help-message
@vindex ediff-control-buffer
@vindex ediff-startup-hook
@vindex ediff-help-message

Ediff provides quick help using its control panel window.  Since this window
takes a fair share of the screen real estate, you can toggle it off by
typing @kbd{?}.  The control window will then shrink to just one line and a
mode line, displaying a short help message.

The variable @code{ediff-use-long-help-message} tells Ediff whether
you use the short message or the long one.  By default, it
is set to @code{nil}, meaning that the short message is used.
Set this to @code{t}, if you want Ediff to use the long
message by default.  This property can always be changed interactively, by
typing @kbd{?} into Ediff Control Buffer.

If you want to change the appearance of the help message on a per-buffer
basis, you must use @code{ediff-startup-hook} to change the value of
the variable @code{ediff-help-message}, which is local to
@code{ediff-control-buffer}.

@node Window and Frame Configuration, Selective Browsing, Quick Help Customization, Customization
@section Window and Frame Configuration

On a non-windowing display, Ediff sets things up in one frame, splitting
it between a small control window and the windows for buffers A, B, and C.
The split between these windows can be horizontal or
vertical, which can be changed interactively by typing @kbd{|} while the
cursor is in the control window.

On a window display, Ediff sets up a dedicated frame for Ediff Control
Panel and then it chooses windows as follows: If one of the buffers
is invisible, it is displayed in the currently selected frame.  If
a buffer is visible, it is displayed in the frame where it is visible.
If, according to the above criteria, the two buffers fall into the same
frame, then so be it---the frame will be shared by the two.  The same
algorithm works when you type @kbd{C-l} (@code{ediff-recenter}), @kbd{p}
(@code{ediff-previous-difference}), @kbd{n}
(@code{ediff-next-difference}), etc.

The above behavior also depends on whether the current frame is splittable,
dedicated, etc.  Unfortunately, the margin of this book is too narrow to
present the details of this remarkable algorithm.

The upshot of all this is that you can compare buffers in one frame or
in different frames.  The former is done by default, while the latter can
be achieved by arranging buffers A, B (and C, if applicable) to be seen in
different frames.  Ediff respects these arrangements, automatically
adapting itself to the multi-frame mode.

Ediff uses the following variables to set up its control panel
(a.k.a.@: control buffer, a.k.a.@: quick help window):

@table @code
@item ediff-control-frame-parameters
@vindex ediff-control-frame-parameters
You can change or augment this variable including the font, color,
etc.  The X resource name of Ediff Control Panel frames is @samp{Ediff}.  Under
X-windows, you can use this name to set up preferences in your
@file{~/.Xdefaults}, @file{~/.xrdb}, or whatever X resource file is in
use.  Usually this is preferable to changing
@code{ediff-control-frame-parameters} directly.  For instance, you can
specify in @file{~/.Xdefaults} the color of the control frame
using the resource @samp{Ediff*background}.

In general, any X resource pertaining the control frame can be reached
via the prefix @code{Ediff*}.

@item ediff-control-frame-position-function
@vindex ediff-control-frame-position-function
The preferred way of specifying the position of the control frame is by
setting the variable @code{ediff-control-frame-position-function} to an
appropriate function.
The default value of this variable is
@code{ediff-make-frame-position}.  This function places the control frame in
the vicinity of the North-East corner of the frame displaying buffer A.

@findex ediff-make-frame-position
@end table

The following variables can be used to adjust the location produced by
@code{ediff-make-frame-position} and for related customization.

@table @code
@item ediff-narrow-control-frame-leftward-shift
@vindex ediff-narrow-control-frame-leftward-shift
Specifies the number of characters for shifting
the control frame from the rightmost edge of frame A when the control
frame is displayed as a small window.

@item ediff-wide-control-frame-rightward-shift
@vindex ediff-wide-control-frame-rightward-shift
Specifies the rightward shift of the control frame
from the left edge of frame A when the control frame shows the full
menu of options.

@item ediff-control-frame-upward-shift
@vindex ediff-control-frame-upward-shift
Specifies the number of pixels for the upward shift
of the control frame.

@item ediff-prefer-iconified-control-frame
@vindex ediff-prefer-iconified-control-frame
If this variable is @code{t}, the control frame becomes iconified
automatically when you toggle the quick help message off.  This saves
valuable real estate on the screen.  Toggling help back will deiconify
the control frame.

To start Ediff with an iconified Control Panel, you should set this
variable to @code{t} and @code{ediff-prefer-long-help-message} to
@code{nil} (@pxref{Quick Help Customization}).  This behavior is useful
only if icons are allowed to accept keybord input (which depend on the
window manager and other factors).
@end table

@findex ediff-setup-windows
To make more creative changes in the way Ediff sets up windows, you can
rewrite the function @code{ediff-setup-windows}.  However, we believe
that detaching Ediff Control Panel from the rest and making it into a
separate frame offers an important opportunity by allowing you to
iconify that frame.  The icon will usually accept all of the Ediff
commands, but will free up valuable real estate on your screen (this may
depend on your window manager, though).

The following variable controls how windows are set up:

@table @code
@item ediff-window-setup-function
@vindex ediff-window-setup-function
The multiframe setup is done by the
@code{ediff-setup-windows-multiframe} function, which is the default on
windowing displays.  The plain setup, one where all windows are always
in one frame, is done by @code{ediff-setup-windows-plain}, which is the
default on a non-windowing display (or in an xterm window).  In fact,
under Emacs, you can switch freely between these two setups by executing
the command @code{ediff-toggle-multiframe} using the Minibuffer of the
Menubar.
@findex ediff-setup-windows-multiframe
@findex ediff-setup-windows-plain
@findex ediff-toggle-multiframe

If you don't like any of these setups, write your own function.  See the
documentation for @code{ediff-window-setup-function} for the basic
guidelines.  However, writing window setups is not easy, so you should
first take a close look at @code{ediff-setup-windows-plain} and
@code{ediff-setup-windows-multiframe}.
@end table

You can run multiple Ediff sessions at once, by invoking Ediff several
times without exiting previous Ediff sessions.  Different sessions
may even operate on the same pair of files.

Each session has its own Ediff Control Panel and all the regarding a
particular session is local to the associated control panel buffer.  You
can switch between sessions by suspending one session and then switching
to another control panel.  (Different control panel buffers are
distinguished by a numerical suffix, e.g., @samp{Ediff Control Panel<3>}.)

@node Selective Browsing, Highlighting Difference Regions, Window and Frame Configuration, Customization
@section Selective Browsing

Sometimes it is convenient to be able to step through only some difference
regions, those that match certain regular expressions, and to ignore all
others.  On other occasions, you may want to ignore difference regions that
match some regular expressions, and to look only at the rest.

The commands @kbd{#f} and @kbd{#h} let you do precisely this.

Typing @kbd{#f} lets you specify regular expressions that match difference
regions you want to focus on.
We shall call these regular expressions @var{regexp-A}, @var{regexp-B} and
@var{regexp-C}.
Ediff will then start stepping through only those difference regions
where the region in buffer A matches @var{regexp-A} and/or the region in
buffer B matches @var{regexp-B}, etc.  Whether `and' or `or' will be used
depends on how you respond to a question.

When scanning difference regions for the aforesaid regular expressions,
Ediff narrows the buffers to those regions.  This means that you can use
the expressions @kbd{\`} and @kbd{\'} to tie search to the beginning or end
of the difference regions.

On the other hand, typing @kbd{#h} lets you specify (hide) uninteresting
regions.  That is, if a difference region in buffer A matches
@var{regexp-A}, the corresponding region in buffer B matches @var{regexp-B}
and (if applicable) buffer C's region matches @var{regexp-C}, then the
region will be ignored by the commands @kbd{n}/@key{SPC}
(@code{ediff-next-difference}) and @kbd{p}/@key{DEL}
(@code{ediff-previous-difference}) commands.

Typing @kbd{#f} and @kbd{#h} toggles selective browsing on and off.

Note that selective browsing affects only @code{ediff-next-difference}
and @code{ediff-previous-difference}, i.e., the commands
@kbd{n}/@key{SPC} and @kbd{p}/@key{DEL}.  @kbd{#f} and @kbd{#h} do not
change the position of the point in the buffers.  And you can still jump
directly (using @kbd{j})  to any numbered
difference.

Users can supply their own functions to specify how Ediff should do
selective browsing.  To change the default Ediff function, add a function to
@code{ediff-load-hook} which will do the following assignments:

@example
(setq ediff-hide-regexp-matches-function 'your-hide-function)
(setq ediff-focus-on-regexp-matches-function 'your-focus-function)
@end example

@strong{Useful hint}: To specify a regexp that matches everything, don't
simply type @key{RET} in response to a prompt.  Typing @key{RET} tells Ediff
to accept the default value, which may not be what you want.  Instead, you
should enter something like @key{^} or @key{$}.  These match every
line.

You can use the status command, @kbd{i}, to find out whether
selective browsing is currently in effect.

The regular expressions you specified are kept in the local variables
@code{ediff-regexp-focus-A}, @code{ediff-regexp-focus-B},
@code{ediff-regexp-focus-C}, @code{ediff-regexp-hide-A},
@code{ediff-regexp-hide-B}, @code{ediff-regexp-hide-C}.  Their default value
is the empty string (i.e., nothing is hidden or focused on).  To change the
default, set these variables in @file{.emacs} using @code{setq-default}.

In addition to the ability to ignore regions that match regular
expressions, Ediff can be ordered to start skipping over certain
``uninteresting'' difference regions.  This is controlled by the following
variable:

@table @code
@item ediff-ignore-similar-regions
@vindex ediff-ignore-similar-regions
If @code{t}, causes Ediff to skip over "uninteresting" difference regions,
which are the regions where the variants differ only in the amount of the
white space and newlines.  This feature can be toggled on/off interactively,
via the command @kbd{##}.
@end table

@strong{Please note:} in order for this feature to work, auto-refining of
difference regions must be on, since otherwise Ediff won't know if there
are fine differences between regions.  On devices where Emacs can display
faces, auto-refining is a default, but it is not turned on by default on
text-only terminals.  In that case, you must explicitly turn auto-refining
on (such as, by typing @kbd{@@}).

@strong{Reassurance:} If many such uninteresting regions appear in a row,
Ediff may take a long time to skip over them because it has to compute fine
differences of all intermediate regions.  This delay does not indicate any
problem.

@node Highlighting Difference Regions, Narrowing, Selective Browsing, Customization
@section Highlighting Difference Regions

The following variables control the way Ediff highlights difference
regions:

@table @code
@item ediff-before-flag-bol
@itemx ediff-after-flag-eol
@itemx ediff-before-flag-mol
@itemx ediff-after-flag-mol
@vindex ediff-before-flag-bol
@vindex ediff-after-flag-eol
@vindex ediff-before-flag-mol
@vindex ediff-after-flag-mol
These variables hold strings that Ediff uses to mark the beginning and the
end of the differences found in files A, B, and C on devices where Emacs
cannot display faces.  Ediff uses different flags to highlight regions that
begin/end at the beginning/end of a line or in a middle of a line.

@item ediff-current-diff-face-A
@itemx ediff-current-diff-face-B
@itemx ediff-current-diff-face-C
@vindex ediff-current-diff-face-A
@vindex ediff-current-diff-face-B
@vindex ediff-current-diff-face-C
Ediff uses these faces to highlight current differences on devices where
Emacs can display faces.  These and subsequently described faces can be set
either in @file{.emacs} or in @file{.Xdefaults}.  The X resource for Ediff
is @samp{Ediff}, @emph{not} @samp{emacs}.  Please refer to Emacs manual for
the information on how to set X resources.
@item ediff-fine-diff-face-A
@itemx ediff-fine-diff-face-B
@itemx ediff-fine-diff-face-C
@vindex ediff-fine-diff-face-A
@vindex ediff-fine-diff-face-B
@vindex ediff-fine-diff-face-C
Ediff uses these faces to show the fine differences between the current
differences regions in buffers A, B, and C, respectively.

@item ediff-even-diff-face-A
@itemx ediff-even-diff-face-B
@itemx ediff-even-diff-face-C
@itemx ediff-odd-diff-face-A
@itemx ediff-odd-diff-face-B
@itemx ediff-odd-diff-face-C
@vindex ediff-even-diff-face-A
@vindex ediff-even-diff-face-B
@vindex ediff-even-diff-face-C
@vindex ediff-odd-diff-face-A
@vindex ediff-odd-diff-face-B
@vindex ediff-odd-diff-face-C
Non-current difference regions are displayed using these alternating
faces.  The odd and the even faces are actually identical on monochrome
displays, because without colors options are limited.
So, Ediff uses italics to highlight non-current differences.

@item ediff-force-faces
@vindex ediff-force-faces
Ediff generally can detect when Emacs is running on a device where it can
use highlighting with faces.  However, if it fails to determine that faces
can be used, the user can set this variable to @code{t} to make sure that
Ediff uses faces to highlight differences.

@item ediff-highlight-all-diffs
@vindex ediff-highlight-all-diffs
Indicates whether---on a windowind display---Ediff should highlight
differences using inserted strings (as on text-only terminals) or using
colors and highlighting.  Normally, Ediff highlights all differences, but
the selected difference is highlighted more visibly.  One can cycle through
various modes of highlighting by typing @kbd{h}.  By default, Ediff starts
in the mode where all difference regions are highlighted.  If you prefer to
start in the mode where unselected differences are not highlighted, you
should set @code{ediff-highlight-all-diffs} to @code{nil}.  Type @kbd{h} to
restore highlighting for all differences.

Ediff lets you switch between the two modes of highlighting.  That is,
you can switch interactively from highlighting using faces to
highlighting using string flags, and back.  Of course, switching has
effect only under a windowing system.  On a text-only terminal or in an
xterm window, the only available option is highlighting with strings.
@end table

@noindent
If you want to change the default settings for @code{ediff-force-faces} and
@code{ediff-highlight-all-diffs}, you must do it @strong{before} Ediff is
loaded.

You can also change the defaults for the faces used to highlight the
difference regions.  There are two ways to do this.  The simplest and the
preferred way is to use the customization widget accessible from the
menubar.  Ediff's customization group is located under "Tools", which in
turn is under "Programming".  The faces that are used to highlight
difference regions are located in the "Highlighting" subgroup of the Ediff
customization group.

The second, much more arcane, method to change default faces is to include
some Lisp code in @file{~/.emacs}.  For instance,

@example
(setq ediff-current-diff-face-A
      (copy-face 'bold-italic 'ediff-current-diff-face-A))
@end example

@noindent
would use the pre-defined fase @code{bold-italic} to highlight the current
difference region in buffer A (this face is not a good choice, by the way).

If you are unhappy with just @emph{some} of the aspects of the default
faces, you can modify them when Ediff is being loaded using
@code{ediff-load-hook}.  For instance:

@smallexample
(add-hook 'ediff-load-hook
          (lambda ()
            (set-face-foreground
              ediff-current-diff-face-B "blue")
            (set-face-background
              ediff-current-diff-face-B "red")
            (make-face-italic
              ediff-current-diff-face-B)))
@end smallexample

@strong{Please note:} to set Ediff's faces, use only @code{copy-face}
or @code{set/make-face-@dots{}} as shown above. Emacs' low-level
face-manipulation functions should be avoided.

@node Narrowing, Refinement of Difference Regions, Highlighting Difference Regions, Customization
@section Narrowing

If buffers being compared are narrowed at the time of invocation of
Ediff, @code{ediff-buffers} will preserve the narrowing range.  However,
if @code{ediff-files} is invoked on the files visited by these buffers,
that would widen the buffers, since this command is defined to compare the
entire files.

Calling @code{ediff-regions-linewise} or @code{ediff-windows-linewise}, or
the corresponding @samp{-wordwise} commands, narrows the variants to the
particular regions being compared.  The original accessible ranges are
restored when you quit Ediff.  During the command, you can toggle this
narrowing on and off with the @kbd{%} command.

These two variables control this narrowing behavior:

@table @code
@item ediff-start-narrowed
@vindex ediff-start-narrowed
If @code{t}, Ediff narrows the display to the appropriate range when it
is invoked with an @samp{ediff-regions@dots{}} or
@samp{ediff-windows@dots{}} command.  If @code{nil}, these commands do
not automatically narrow, but you can still toggle narrowing on and off
by typing @kbd{%}.

@item ediff-quit-widened
@vindex ediff-quit-widened
Controls whether on quitting Ediff should restore the accessible range
that existed before the current invocation.
@end table

@node Refinement of Difference Regions, Patch and Diff Programs, Narrowing, Customization
@section Refinement of Difference Regions

Ediff has variables to control the way fine differences are
highlighted.  This feature gives you control over the process of refinement.
Note that refinement ignores spaces, tabs, and newlines.

@table @code
@item ediff-auto-refine
@vindex ediff-auto-refine
This variable controls whether fine differences within regions are
highlighted automatically (``auto-refining'').  The default is yes
(@samp{on}).

On a slow machine, automatic refinement may be painful.  In that case,
you can turn auto-refining on or off interactively by typing
@kbd{@@}.  You can also turn off display of refining that has
already been done.

When auto-refining is off, fine differences are shown only for regions
for which these differences have been computed and saved before.  If
auto-refining and display of refining are both turned off, fine
differences are not shown at all.

Typing @kbd{*} computes and displays fine differences for the current
difference region, regardless of whether auto-refining is turned on.

@item ediff-auto-refine-limit
@vindex ediff-auto-refine-limit
If auto-refining is on, this variable limits the size of the regions to
be auto-refined.  This guards against the possible slowdown that may be
caused by extraordinary large difference regions.

You can always refine the current region by typing @kbd{*}.

@item ediff-forward-word-function
@vindex ediff-forward-word-function
This variable controls how fine differences are computed.  The
value must be a Lisp function that determines how the current difference
region should be split into words.

@vindex ediff-diff-program
@vindex ediff-forward-word-function
@findex ediff-forward-word
Fine differences are computed by first splitting the current difference
region into words and then passing the result to
@code{ediff-diff-program}.  For the default forward word function (which is
@code{ediff-forward-word}), a word is a string consisting of letters,
@samp{-}, or @samp{_}; a string of punctuation symbols; a string of digits,
or a string consisting of symbols that are neither space, nor a letter.

This default behavior is controlled by four variables: @code{ediff-word-1},
..., @code{ediff-word-4}.  See the on-line documentation for these variables
and for the function @code{ediff-forward-word} for an explanation of how to
modify these variables.
@vindex ediff-word-1
@vindex ediff-word-2
@vindex ediff-word-3
@vindex ediff-word-4
@end table

Sometimes, when a region has too many differences between the variants,
highlighting of fine differences is inconvenient, especially on
color displays.  If that is the case, type @kbd{*} with a negative
prefix argument.  This unhighlights fine differences for the current
region.

To unhighlight fine differences in all difference regions, use the
command @kbd{@@}.  Repeated typing of this key cycles through three
different states: auto-refining, no-auto-refining, and no-highlighting
of fine differences.

@node Patch and Diff Programs, Merging and diff3, Refinement of Difference Regions, Customization
@section Patch and Diff Programs

This section describes variables that specify the programs to be used for
applying patches and for computing the main difference regions (not the
fine difference regions):

@table @code
@item ediff-diff-program
@itemx ediff-diff3-program
@vindex ediff-patch-program
@vindex ediff-diff-program
@vindex ediff-diff3-program
These variables specify the programs to use to produce differences
and do patching.

@item ediff-diff-options
@itemx ediff-diff3-options
@vindex ediff-patch-options
@vindex ediff-diff-options
@vindex ediff-diff3-options
These variables specify the options to pass to the above utilities.

In @code{ediff-diff-options}, it may be useful to specify options
such as @samp{-w} that ignore certain kinds of changes.  However,
Ediff does not let you use the option @samp{-c}, as it doesn't recognize this
format yet.

@item ediff-coding-system-for-read
@vindex ediff-coding-system-for-read
This variable specifies the coding system to use when reading the output
that the programs @code{diff3} and @code{diff} send to Emacs. The default
is @code{raw-text}, and this should work fine in Unix and in most
cases under Windows NT/95/98/2000. There are @code{diff} programs
for which the default option doesn't work under Windows. In such cases,
@code{raw-text-dos} might work. If not, you will have to experiment with
other coding systems or use GNU diff.

@item ediff-patch-program
The program to use to apply patches.  Since there are certain
incompatibilities between the different versions of the patch program, the
best way to stay out of trouble is to use a GNU-compatible version.
Otherwise, you may have to tune the values of the variables
@code{ediff-patch-options}, @code{ediff-backup-specs}, and
@code{ediff-backup-extension} as described below.
@item ediff-patch-options
Options to pass to @code{ediff-patch-program}.

Note: the `-b' and `-z' options should be specified in
`ediff-backup-specs', not in @code{ediff-patch-options}.

It is recommended to pass the `-f' option to the patch program, so it won't
ask questions.  However, some implementations don't accept this option, in
which case the default value of this variable should be changed.

@item ediff-backup-extension
Backup extension used by the patch program.  Must be specified, even if
@code{ediff-backup-specs} is given.
@item ediff-backup-specs
Backup directives to pass to the patch program.
Ediff requires that the old version of the file (before applying the patch)
is saved in a file named @file{the-patch-file.extension}.  Usually
`extension' is `.orig', but this can be changed by the user, and may also be
system-dependent.  Therefore, Ediff needs to know the backup extension used
by the patch program.

Some versions of the patch program let the user specify `-b backup-extension'.
Other versions only permit `-b', which (usually) assumes the extension `.orig'.
Yet others force you to use `-z<backup-extension>'.

Note that both `ediff-backup-extension' and `ediff-backup-specs' must be
properly set.  If your patch program takes the option `-b', but not
`-b extension', the variable `ediff-backup-extension' must still
be set so Ediff will know which extension to use.

@item ediff-custom-diff-program
@itemx ediff-custom-diff-options
@vindex ediff-custom-diff-program
@vindex ediff-custom-diff-options
@findex ediff-save-buffer
Because Ediff limits the options you may want to pass to the @code{diff}
program, it partially makes up for this drawback by letting you save the
output from @code{diff} in your preferred format, which is specified via
the above two variables.

The output generated by @code{ediff-custom-diff-program} (which doesn't
even have to be a standard-style @code{diff}!)@: is not used by Ediff.  It is
provided exclusively so that you can
refer to
it later, send it over email, etc.  For instance, after reviewing the
differences, you may want to send context differences to a colleague.
Since Ediff ignores the @samp{-c} option in
@code{ediff-diff-program}, you would have to run @code{diff -c} separately
just to produce the list of differences.  Fortunately,
@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options}
eliminate this nuisance by keeping a copy of a difference list in the
desired format in a buffer that can be displayed via the command @kbd{D}.

@item ediff-patch-default-directory
@vindex ediff-patch-default-directory
Specifies the default directory to look for patches.

@end table

@noindent
@strong{Warning:} Ediff does not support the output format of VMS
@code{diff}.  Instead, make sure you are using some implementation of POSIX
@code{diff}, such as @code{gnudiff}.

@node Merging and diff3, Support for Version Control, Patch and Diff Programs, Customization
@section Merging and diff3

Ediff supports three-way comparison via the functions @code{ediff-files3} and
@code{ediff-buffers3}.  The interface is the same as for two-way comparison.
In three-way comparison and merging, Ediff reports if any two difference
regions are identical.  For instance, if the current region in buffer A
is the same as the region in buffer C, then the mode line of buffer A will
display @samp{[=diff(C)]} and the mode line of buffer C will display
@samp{[=diff(A)]}.

Merging is done according to the following algorithm.

If a difference region in one of the buffers, say B, differs from the ancestor
file while the region in the other buffer, A, doesn't, then the merge buffer,
C, gets B's region.  Similarly when buffer A's region differs from
the ancestor and B's doesn't, A's region is used.

@vindex ediff-default-variant
If both regions in buffers A and B differ from the ancestor file, Ediff
chooses the region according to the value of the variable
@code{ediff-default-variant}.  If its value is @code{default-A} then A's
region is chosen.  If it is @code{default-B} then B's region is chosen.
If it is @code{combined} then the region in buffer C will look like
this:

@comment Use @set to avoid triggering merge conflict detectors like CVS.
@set seven-left <<<<<<<
@set seven-right >>>>>>>
@example
@value{seven-left} variant A
the difference region from buffer A
@value{seven-right} variant B
the difference region from buffer B
####### Ancestor
the difference region from the ancestor buffer, if available
======= end
@end example

The above is the default template for the combined region. The user can
customize this template using the variable
@code{ediff-combination-pattern}.

@vindex ediff-combination-pattern
The variable @code{ediff-combination-pattern} specifies the template that
determines how the combined merged region looks like.  The template is
represented as a list of the form @code{(STRING1 Symbol1 STRING2 Symbol2
STRING3 Symbol3 STRING4)}. The symbols here must be atoms of the form
@code{A}, @code{B}, or @code{Ancestor}. They determine the order in which
the corresponding difference regions (from buffers A, B, and the ancestor
buffer) are displayed in the merged region of buffer C.  The strings in the
template determine the text that separates the aforesaid regions. The
default template is

@smallexample
("@value{seven-left} variant A" A "@value{seven-right} variant B" B
   "####### Ancestor" Ancestor "======= end")
@end smallexample

@noindent
(this is one long line) and the corresponding combined region is shown
above. The order in which the regions are shown (and the separator
strings) can be changed by changing the above template. It is even
possible to add or delete region specifiers in this template (although
the only possibly useful such modification seems to be the deletion of
the ancestor).

In addition to the state of the difference, Ediff displays the state of the
merge for each region.  If a difference came from buffer A by default
(because both regions A and B were different from the ancestor and
@code{ediff-default-variant} was set to @code{default-A}) then
@samp{[=diff(A) default-A]} is displayed in the mode line.  If the
difference in buffer C came, say, from buffer B because the difference
region in that buffer differs from the ancestor, but the region in buffer A
does not (if merging with an ancestor) then @samp{[=diff(B) prefer-B]} is
displayed.  The indicators default-A/B and prefer-A/B are inspired by
Emerge and have the same meaning.

Another indicator of the state of merge is @samp{combined}.  It appears
with any difference region in buffer C that was obtained by combining
the difference regions in buffers A and B as explained above.

In addition to the state of merge and state of difference indicators, while
merging with an ancestor file or buffer, Ediff informs the user when the
current difference region in the (normally invisible) ancestor buffer is
empty via the @emph{AncestorEmpty} indicator.  This helps determine if the
changes made to the original in variants A and B represent pure insertion
or deletion of text: if the mode line shows @emph{AncestorEmpty} and the
corresponding region in buffers A or B is not empty, this means that new
text was inserted.  If this indicator is not present and the difference
regions in buffers A or B are non-empty, this means that text was
modified.  Otherwise, the original text was deleted.

Although the ancestor buffer is normally invisible, Ediff maintains
difference regions there and advances the current difference region
accordingly.  All highlighting of difference regions is provided in the
ancestor buffer, except for the fine differences.  Therefore, if desired, the
user can put the ancestor buffer in a separate frame and watch it
there.  However, on a TTY, only one frame can be visible at any given time,
and Ediff doesn't support any single-frame window configuration where all
buffers, including the ancestor buffer, would be visible.  However, the
ancestor buffer can be displayed by typing @kbd{/} to the control
window.  (Type @kbd{C-l} to hide it again.)

Note that the state-of-difference indicators @samp{=diff(A)} and
@samp{=diff(B)} above are not redundant, even in the presence of a
state-of-merge indicator.  In fact, the two serve different purposes.

For instance, if the mode line displays @samp{=diff(B) prefer(B)} and
you copy a difference region from buffer A to buffer C then
@samp{=diff(B)} will change to @samp{diff-A} and the mode line will
display @samp{=diff(A) prefer-B}.  This indicates that the difference
region in buffer C is identical to that in buffer A, but originally
buffer C's region came from buffer B.  This is useful to know because
you can recover the original difference region in buffer C by typing
@kbd{r}.


Ediff never changes the state-of-merge indicator, except in response to
the @kbd{!} command (see below), in which case the indicator is lost.
On the other hand, the state-of-difference indicator is changed
automatically by the copying/recovery commands, @kbd{a}, @kbd{b}, @kbd{r},
@kbd{+}.

The @kbd{!} command loses the information about origins of the regions
in the merge buffer (default-A, prefer-B, or combined).  This is because
recomputing differences in this case means running @code{diff3} on
buffers A, B, and the merge buffer, not on the ancestor buffer.  (It
makes no sense to recompute differences using the ancestor file, since
in the merging mode Ediff assumes that you have not edited buffers A and
B, but that you may have edited buffer C, and these changes are to be
preserved.)  Since some difference regions may disappear as a result of
editing buffer C and others may arise, there is generally no simple way
to tell where the various regions in the merge buffer came from.

In three-way comparison, Ediff tries to disregard regions that consist
entirely of white space.  For instance, if, say, the current region in
buffer A consists of the white space only (or if it is empty), Ediff will
not take it into account for the purpose of computing fine differences.  The
result is that Ediff can provide a better visual information regarding the
actual fine differences in the non-white regions in buffers B and
C.  Moreover, if the regions in buffers B and C differ in the white space
only, then a message to this effect will be displayed.

@vindex ediff-merge-window-share
In the merge mode, the share of the split between window C (the window
displaying the merge-buffer) and the windows displaying buffers A and B
is controlled by the variable @code{ediff-merge-window-share}.  Its
default value is 0.5.  To make the merge-buffer window smaller, reduce
this amount.

We don't recommend increasing the size of the merge-window to more than
half the frame (i.e., to increase the value of
@code{ediff-merge-window-share}) to more than 0.5, since it would be
hard to see the contents of buffers A and B.

You can temporarily shrink the merge window to just one line by
typing @kbd{s}.  This change is temporary, until Ediff finds a reason to
redraw the screen.  Typing @kbd{s} again restores the original window size.

With a positive prefix argument, the @kbd{s} command will make the merge
window slightly taller.  This change is persistent.  With `@kbd{-}' or
with a negative prefix argument, the command @kbd{s} makes the merge
window slightly shorter.  This change also persistent.

@vindex ediff-show-clashes-only
Ediff lets you automatically ignore the regions where only one of the
buffers A and B disagrees with the ancestor.  To do this, set the
variable @code{ediff-show-clashes-only} to non-@code{nil}.

You can toggle this feature interactively by typing @kbd{$$}.

Note that this variable affects only the show next/previous difference
commands.  You can still jump directly to any difference region directly
using the command @kbd{j} (with a prefix argument specifying the difference
number).

@vindex ediff-autostore-merges
@vindex ediff-quit-merge-hook
@findex ediff-maybe-save-and-delete-merge
The variable @code{ediff-autostore-merges} controls what happens to the
merge buffer when Ediff quits.  If the value is @code{nil}, nothing is done
to the merge buffer---it will be the user's responsibility to save it.
If the value is @code{t}, the user will be asked where to save the buffer
and whether to delete it afterwards.  It the value is neither @code{nil} nor
@code{t}, the merge buffer is saved @emph{only} if this merge session was
invoked from a group of related Ediff session, such as those that result
from @code{ediff-merge-directories},
@code{ediff-merge-directory-revisions}, etc.
@xref{Session Groups}.  This behavior is implemented in the function
@code{ediff-maybe-save-and-delete-merge}, which is a hook in
@code{ediff-quit-merge-hook}.  The user can supply a different hook, if
necessary.

The variable @code{ediff-autostore-merges} is buffer-local, so it can be
set in a per-buffer manner.  Therefore, use @code{setq-default} to globally
change this variable.

@vindex ediff-merge-filename-prefix
When merge buffers are saved automatically as directed by
@code{ediff-autostore-merges}, Ediff attaches a prefix to each file, as
specified by the variable @code{ediff-merge-filename-prefix}. The default
is @code{merge_}, but this can be changed by the user.

@node Support for Version Control, Customizing the Mode Line, Merging and diff3, Customization
@section Support for Version Control


Ediff supports version control and lets you compare versions of files
visited by Emacs buffers via the function @code{ediff-revision}.  This
feature is controlled by the following variables:

@table @code
@item ediff-version-control-package
@vindex ediff-version-control-package
A symbol.  The default is @samp{vc}.

If you are like most Emacs users, Ediff will use VC as the version control
package.  This is the standard Emacs interface to RCS, CVS, and SCCS.

However, if your needs are better served by other interfaces, you will
have to tell Ediff which version control package you are using, e.g.,
@example
(setq ediff-version-control-package 'rcs)
@end example

Apart from the standard @file{vc.el}, Ediff supports three other interfaces
to version control: @file{rcs.el}, @file{pcl-cvs.el} (recently renamed
pcvs.el), and @file{generic-sc.el}.  The package @file{rcs.el} is written
by Sebastian Kremer <sk@@thp.Uni-Koeln.DE> and is available as
@example
@file{ftp.cs.buffalo.edu:pub/Emacs/rcs.tar.Z}
@file{ftp.uni-koeln.de:/pub/gnu/emacs/rcs.tar.Z}
@end example
@pindex @file{vc.el}
@pindex @file{rcs.el}
@pindex @file{pcl-cvs.el}
@pindex @file{generic-sc.el}
@end table

Ediff's interface to the above packages allows the user to compare the
versions of the current buffer or to merge them (with or without an
ancestor-version).  These operations can also be performed on directories
containing files under version control.

In case of @file{pcl-cvs.el}, Ediff can also be invoked via the function
@code{run-ediff-from-cvs-buffer}---see the documentation string for this
function.

@node Customizing the Mode Line, Miscellaneous, Support for Version Control, Customization
@section Customizing the Mode Line

When Ediff is running, the mode line of @samp{Ediff Control Panel}
buffer shows the current difference number and the total number of
difference regions in the two files.

The mode line of the buffers being compared displays the type of the
buffer (@samp{A:}, @samp{B:}, or @samp{C:}) and (usually) the file name.
Ediff tries to be intelligent in choosing the mode line buffer
identification.  In particular, it works well with the
@file{uniquify.el} and @file{mode-line.el} packages (which improve on
the default way in which Emacs displays buffer identification).  If you
don't like the way Ediff changes the mode line, you can use
@code{ediff-prepare-buffer-hook} to modify the mode line.
@vindex ediff-prepare-buffer-hook
@pindex @file{uniquify.el}
@pindex @file{mode-line.el}

@node Miscellaneous, Notes on Heavy-duty Customization, Customizing the Mode Line, Customization
@section Miscellaneous

Here are a few other variables for customizing Ediff:

@table @code
@item ediff-split-window-function
@vindex ediff-split-window-function
Controls the way you want the window be split between file-A and file-B
(and file-C, if applicable).  It defaults to the vertical split
(@code{split-window-vertically}, but you can set it to
@code{split-window-horizontally}, if you so wish.
Ediff also lets you switch from vertical to horizontal split and back
interactively.

Note that if Ediff detects that all the buffers it compares are displayed in
separate frames, it assumes that the user wants them to be so displayed
and stops splitting windows.  Instead, it arranges for each buffer to
be displayed in a separate frame.  You can switch to the one-frame mode
by hiding one of the buffers A/B/C.

You can also swap the windows where buffers are displayed by typing
@kbd{~}.

@item ediff-merge-split-window-function
@vindex ediff-merge-split-window-function
Controls how windows are
split between buffers A and B in the merge mode.
This variable is like @code{ediff-split-window-function}, but it defaults
to @code{split-window-horizontally} instead of
@code{split-window-vertically}.

@item ediff-make-wide-display-function
@vindex ediff-make-wide-display-function
The value is a function to be called to widen the frame for displaying
the Ediff buffers.  See the on-line documentation for
@code{ediff-make-wide-display-function} for details.  It is also
recommended to look into the source of the default function
@code{ediff-make-wide-display}.

You can toggle wide/regular display by typing @kbd{m}.  In the wide
display mode, buffers A, B (and C, when applicable) are displayed in a
single frame that is as wide as the entire workstation screen.  This is
useful when files are compared side-by-side.  By default, the display is
widened without changing its height.

@item ediff-use-last-dir
@vindex ediff-use-last-dir
Controls the way Ediff presents the
default directory when it prompts the user for files to compare.  If
@code{nil},
Ediff uses the default directory of the current buffer when it
prompts the user for file names.  Otherwise, it will use the
directories it had previously used for files A, B, or C, respectively.

@item ediff-no-emacs-help-in-control-buffer
@vindex ediff-no-emacs-help-in-control-buffer
If @code{t}, makes @kbd{C-h}
behave like the @key{DEL} key, i.e., it will move you back to the previous
difference rather than invoking help.  This is useful when, in an xterm
window or a text-only terminal, the Backspace key is bound to @kbd{C-h} and is
positioned more conveniently than the @key{DEL} key.

@item ediff-toggle-read-only-function
@vindex ediff-toggle-read-only-function
This variable's value is a function that Ediff uses to toggle
the read-only property in its buffers.

The default function that Ediff uses simply toggles the read-only property,
unless the file is under version control.  For a checked-in file under
version control, Ediff first tries to check the file out.

@item ediff-make-buffers-readonly-at-startup nil
@vindex ediff-make-buffers-readonly-at-startup
If @code{t}, all variant buffers are made read-only at Ediff startup.

@item ediff-keep-variants
@vindex @code{ediff-keep-variants}
The default is @code{t}, meaning that the buffers being compared or merged will
be preserved when Ediff quits.  Setting this to @code{nil} causes Ediff to
offer the user a chance to delete these buffers (if they are not modified).
Supplying a prefix argument to the quit command (@code{q}) temporarily
reverses the meaning of this variable.  This is convenient when the user
prefers one of the behaviors most of the time, but occasionally needs the
other behavior.

However, Ediff temporarily resets this variable to @code{t} if it is
invoked via one of the "buffer" jobs, such as @code{ediff-buffers}.
This is because it is all too easy to loose day's work otherwise.
Besides, in a "buffer" job, the variant buffers have already been loaded
prior to starting Ediff, so Ediff just preserves status quo here.

Using @code{ediff-cleanup-hook}, one can make Ediff delete the variants
unconditionally (e.g., by making @code{ediff-janitor} into one of these hooks).
@item ediff-grab-mouse
@vindex @code{ediff-grab-mouse}
Default is @code{t}.  Normally, Ediff grabs mouse and puts it in its
control frame.  This is useful since the user can be sure that when he
needs to type an Ediff command the focus will be in an appropriate Ediff's
frame.  However, some users prefer to move the mouse by themselves.  The
above variable, if set to @code{maybe}, will prevent Ediff from grabbing
the mouse in many situations, usually after commands that may take more
time than usual.  In other situation, Ediff will continue grabbing the mouse
and putting it where it believes is appropriate.  If the value is
@code{nil}, then mouse is entirely user's responsibility.
Try different settings and see which one is for you.
@end table


@node Notes on Heavy-duty Customization, , Miscellaneous, Customization
@section Notes on Heavy-duty Customization

Some users need to customize Ediff in rather sophisticated ways, which
requires different defaults for different kinds of files (e.g., SGML,
etc.).  Ediff supports this kind of customization in several ways.  First,
most customization variables are buffer-local.  Those that aren't are
usually accessible from within Ediff Control Panel, so one can make them
local to the panel by calling make-local-variable from within
@code{ediff-startup-hook}.

Second, the function @code{ediff-setup} accepts an optional sixth
argument which has the form @code{((@var{var-name-1} .@: @var{val-1})
(@var{var-name-2} .@: @var{val-2}) @dots{})}.  The function
@code{ediff-setup} sets the variables in the list to the respective
values, locally in the Ediff control buffer.  This is an easy way to
throw in custom variables (which usually should be buffer-local) that
can then be tested in various hooks.

Make sure the variable @code{ediff-job-name} and @code{ediff-word-mode} are set
properly in this case, as some things in Ediff depend on this.

Finally, if you want custom-tailored help messages, you can set the
variables @code{ediff-brief-help-message-function} and
@code{ediff-long-help-message-function}
to functions that return help strings.
@vindex ediff-startup-hook
@findex ediff-setup
@vindex ediff-job-name
@vindex ediff-word-mode
@vindex ediff-brief-help-message-function
@vindex ediff-long-help-message-function

When customizing Ediff, some other variables are useful, although they are
not user-definable.  They are local to the Ediff control buffer, so this
buffer must be current when you access these variables.  The control buffer
is accessible via the variable @code{ediff-control-buffer}, which is also
local to that buffer.  It is usually used for checking if the current buffer
is also the control buffer.

Other variables of interest are:
@table @code
@item ediff-buffer-A
The first of the data buffers being compared.

@item ediff-buffer-B
The second of the data buffers being compared.

@item ediff-buffer-C
In three-way comparisons, this is the third buffer being compared.
In merging, this is the merge buffer.
In two-way comparison, this variable is @code{nil}.

@item ediff-window-A
The window displaying buffer A.  If buffer A is not visible, this variable
is @code{nil} or it may be a dead window.

@item ediff-window-B
The window displaying buffer B.

@item ediff-window-C
The window displaying buffer C, if any.

@item ediff-control-frame
A dedicated frame displaying the control buffer, if it exists.  It is
non-@code{nil} only if Ediff uses the multiframe display, i.e., when
the control buffer is in its own frame.
@end table

@node Credits, Index, Customization, Top
@chapter Credits

Ediff was written by Michael Kifer <kifer@@cs.stonybrook.edu>.  It was inspired
by emerge.el written by Dale R.@: Worley <drw@@math.mit.edu>.  An idea due to
Boris Goldowsky <boris@@cs.rochester.edu> made it possible to highlight
fine differences in Ediff buffers.  Alastair Burt <burt@@dfki.uni-kl.de>
ported Ediff to XEmacs, Eric Freudenthal <freudent@@jan.ultra.nyu.edu>
made it work with VC, Marc Paquette <marcpa@@cam.org> wrote the
toolbar support package for Ediff, and Hrvoje Niksic <hniksic@@xemacs.org>
adapted it to the Emacs customization package.

Many people provided help with bug reports, feature suggestions, and advice.
Without them, Ediff would not be nearly as useful as it is today.
Here is a hopefully full list of contributors:

@example
Adrian Aichner (aichner@@ecf.teradyne.com),
Steve Baur (steve@@xemacs.org),
Neal Becker (neal@@ctd.comsat.com),
E.@: Jay Berkenbilt (ejb@@ql.org),
Alastair Burt (burt@@dfki.uni-kl.de),
Paul Bibilo (peb@@delcam.co.uk),
Kevin Broadey (KevinB@@bartley.demon.co.uk),
Harald Boegeholz (hwb@@machnix.mathematik.uni-stuttgart.de),
Bradley A.@: Bosch (brad@@lachman.com),
Michael D.@: Carney (carney@@ltx-tr.com),
Jin S.@: Choi (jin@@atype.com),
Scott Cummings (cummings@@adc.com),
Albert Dvornik (bert@@mit.edu),
Eric Eide (eeide@@asylum.cs.utah.edu),
Paul Eggert (eggert@@twinsun.com),
Urban Engberg (ue@@cci.dk),
Kevin Esler (esler@@ch.hp.com),
Robert Estes (estes@@ece.ucdavis.edu),
Jay Finger (jayf@@microsoft.com),
Xavier Fornari (xavier@@europe.cma.fr),
Eric Freudenthal (freudent@@jan.ultra.nyu.edu),
Job Ganzevoort (Job.Ganzevoort@@cwi.nl),
Felix Heinrich Gatzemeier (felix.g@@tzemeier.info),
Boris Goldowsky (boris@@cs.rochester.edu),
Allan Gottlieb (gottlieb@@allan.ultra.nyu.edu),
Aaron Gross (aaron@@bfr.co.il),
Thorbjoern Hansen (thorbjoern.hansen@@mchp.siemens.de),
Marcus Harnisch (marcus_harnisch@@mint-tech.com),
Steven E. Harris (seh@@panix.com),
Aaron S. Hawley (Aaron.Hawley@@uvm.edu),
Xiaoli Huang (hxl@@epic.com),
Andreas Jaeger (aj@@suse.de),
Lars Magne Ingebrigtsen (larsi@@ifi.uio.no),
Larry Gouge (larry@@itginc.com),
Karl Heuer (kwzh@@gnu.org),
(irvine@@lks.csi.com),
(jaffe@@chipmunk.cita.utoronto.ca),
David Karr (dkarr@@nmo.gtegsc.com),
Norbert Kiesel (norbert@@i3.informatik.rwth-aachen.de),
Leigh L Klotz (klotz@@adoc.xerox.com),
Fritz Knabe (Fritz.Knabe@@ecrc.de),
Heinz Knutzen (hk@@informatik.uni-kiel.d400.de),
Andrew Koenig (ark@@research.att.com),
Hannu Koivisto (azure@@iki.fi),
Ken Laprade (laprade@@dw3f.ess.harris.com),
Will C Lauer (wcl@@cadre.com),
Richard Levitte (levitte@@e.kth.se),
Mike Long (mike.long@@analog.com),
Dave Love (d.love@@dl.ac.uk),
Martin Maechler (maechler@@stat.math.ethz.ch),
Simon Marshall (simon@@gnu.org),
Paul C. Meuse (pmeuse@@delcomsys.com),
Richard Mlynarik (mly@@adoc.xerox.com),
Stefan Monnier (monnier@@cs.yale.edu),
Chris Murphy (murphycm@@sun.aston.ac.uk),
Erik Naggum (erik@@naggum.no),
Eyvind Ness (Eyvind.Ness@@hrp.no),
Ray Nickson (nickson@@cs.uq.oz.au),
Dan Nicolaescu (dann@@ics.uci.edu),
David Petchey (petchey_david@@jpmorgan.com),
Benjamin Pierce (benjamin.pierce@@cl.cam.ac.uk),
Francois Pinard (pinard@@iro.umontreal.ca),
Tibor Polgar (tlp00@@spg.amdahl.com),
David Prince (dave0d@@fegs.co.uk),
Paul Raines (raines@@slac.stanford.edu),
Stefan Reicher (xsteve@@riic.at),
Charles Rich (rich@@merl.com),
Bill Richter (richter@@math.nwu.edu),
C.S.@: Roberson (roberson@@aur.alcatel.com),
Kevin Rodgers (kevin.rodgers@@ihs.com),
Sandy Rutherford (sandy@@ibm550.sissa.it),
Heribert Schuetz (schuetz@@ecrc.de),
Andy Scott (ascott@@pcocd2.intel.com),
Axel Seibert (axel@@tumbolia.ppp.informatik.uni-muenchen.de),
Vin Shelton (acs@@xemacs.org),
Scott O. Sherman (Scott.Sherman@@mci.com),
Richard Stallman (rms@@gnu.org),
Richard Stanton (stanton@@haas.berkeley.edu),
Sam Steingold (sds@@goems.com),
Ake Stenhoff (etxaksf@@aom.ericsson.se),
Stig (stig@@hackvan.com),
Peter Stout (Peter_Stout@@cs.cmu.edu),
Chuck Thompson (cthomp@@cs.uiuc.edu),
Ray Tomlinson (tomlinso@@bbn.com),
Raymond Toy (toy@@rtp.ericsson.se),
Stephen J. Turnbull  (stephen@@xemacs.org),
Jan Vroonhof (vroonhof@@math.ethz.ch),
Colin Walters (walters@@cis.ohio-state.edu),
Philippe Waroquiers (philippe.waroquiers@@eurocontrol.be),
Klaus Weber (gizmo@@zork.north.de),
Ben Wing (ben@@xemacs.org),
Tom Wurgler (twurgler@@goodyear.com),
Steve Youngs (youngs@@xemacs.org),
Ilya Zakharevich (ilya@@math.ohio-state.edu),
Eli Zaretskii (eliz@@is.elta.co.il)
@end example

@node Index, , Credits, Top
@unnumbered Index
@printindex cp

@setchapternewpage odd
@contents
@bye

@ignore
   arch-tag: 165ecb88-d03c-44b1-a921-b93f50b05b46
@end ignore
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.