~theo/emacs

ref: 9adf0579aecd318ca6284c27ab92f78dbaec8e12 emacs/doc/emacs/maintaining.texi -rw-r--r-- 123.3 KiB
9adf0579Theodor Thornhill Add command project-remove-known-project 5 months ago
                                                                                
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
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
@c This is part of the Emacs manual., Abbrevs, This is part of the Emacs manual., Top
@c Copyright (C) 1985--1987, 1993--1995, 1997, 1999--2021 Free Software
@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Maintaining
@chapter Maintaining Large Programs

  This chapter describes Emacs features for maintaining medium- to
large-size programs and packages.  These features include:

@itemize @minus
@item
Unified interface to Support for Version Control Systems
(@acronym{VCS}) that record the history of changes to source files.

@item
Commands for handling programming projects.

@item
A specialized mode for maintaining @file{ChangeLog} files that provide
a chronological log of program changes.

@item
@acronym{Xref}, a set of commands for displaying definitions of
symbols (a.k.a.@: ``identifiers'') and their references.

@item
@acronym{EDE}, the Emacs's own IDE.

@ifnottex
@item
A mode for merging changes to program sources made on separate
branches of development.
@end ifnottex
@end itemize

If you are maintaining a large Lisp program, then in addition to the
features described here, you may find the Emacs Lisp Regression
Testing (@acronym{ERT}) library useful (@pxref{Top,,ERT,ert, Emacs
Lisp Regression Testing}).

@menu
* Version Control::     Using version control systems.
* Projects::            Commands for handling source files in a project.
* Change Log::          Maintaining a change history for your program.
* Xref::                Find definitions and references of any function,
                          method, struct, macro, @dots{} in your program.
* EDE::                 An integrated development environment for Emacs.
@ifnottex
* Emerge::              A convenient way of merging two versions of a program.
@end ifnottex
@end menu

@node Version Control
@section Version Control
@cindex version control

  A @dfn{version control system} is a program that can record multiple
versions of a source file, storing information such as the creation
time of each version, who made it, and a description of what was
changed.

@cindex VC
  The Emacs version control interface is called @dfn{VC}@.  VC
commands work with several different version control systems;
currently, it supports Bazaar, CVS, Git, Mercurial, Monotone, RCS,
SRC, SCCS/CSSC, and Subversion.  Of these, the GNU project distributes
CVS, RCS, and Bazaar.

  VC is enabled automatically whenever you visit a file governed by a
version control system.  To disable VC entirely, set the customizable
variable @code{vc-handled-backends} to @code{nil}
@iftex
(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
@end iftex
@ifnottex
(@pxref{Customizing VC}).
@end ifnottex

@findex vc-refresh-state
@findex vc-state-refresh
  To update the VC state information for the file visited in the
current buffer, use the command @code{vc-refresh-state}.  This command
is useful when you perform version control commands outside Emacs
(e.g., from the shell prompt), or if you put the buffer's file under a
different version control system, or remove it from version control
entirely.

@menu
* Introduction to VC::  How version control works in general.
* VC Mode Line::        How the mode line shows version control status.
* Basic VC Editing::    How to edit a file under version control.
* Log Buffer::          Features available in log entry buffers.
* Registering::         Putting a file under version control.
* Old Revisions::       Examining and comparing old versions.
* VC Change Log::       Viewing the VC Change Log.
* VC Undo::             Canceling changes before or after committing.
* VC Ignore::           Ignore files under version control system.
* VC Directory Mode::   Listing files managed by version control.
* Branches::            Multiple lines of development.
@ifnottex
* Miscellaneous VC::    Various other commands and features of VC.
* Customizing VC::      Variables that change VC's behavior.
@end ifnottex
@end menu

@node Introduction to VC
@subsection Introduction to Version Control

  VC allows you to use a version control system from within Emacs,
integrating the version control operations smoothly with editing.  It
provides a uniform interface for common operations in many version
control operations.

  Some uncommon or intricate version control operations, such as
altering repository settings, are not supported in VC@.  You should
perform such tasks outside VC, e.g., via the command line.

  This section provides a general overview of version control, and
describes the version control systems that VC supports.  You can skip
this section if you are already familiar with the version control system
you want to use.

@menu
* Why Version Control?::    Understanding the problems it addresses.
* Version Control Systems:: Supported version control back-end systems.
* VCS Concepts::            Words and concepts related to version control.
* VCS Merging::             How file conflicts are handled.
* VCS Changesets::          How changes are grouped.
* VCS Repositories::        Where version control repositories are stored.
* Types of Log File::       The VCS log in contrast to the ChangeLog.
@end menu

@node Why Version Control?
@subsubsection Understanding the Problems it Addresses

  Version control systems provide you with three important
capabilities:

@itemize @bullet
@item
@dfn{Reversibility}: the ability to back up to a previous state if you
discover that some modification you did was a mistake or a bad idea.

@item
@dfn{Concurrency}: the ability to have many people modifying the same
collection of files knowing that conflicting modifications can be
detected and resolved.

@item
@dfn{History}: the ability to attach historical data to your data,
such as explanatory comments about the intention behind each change.
Even for a programmer working solo, change histories are an important
aid to memory; for a multi-person project, they are a vitally
important form of communication among developers.
@end itemize

@node Version Control Systems
@subsubsection Supported Version Control Systems

@cindex back end (version control)
  VC currently works with many different version control systems,
which it refers to as @dfn{back ends}:

@itemize @bullet

@cindex SCCS
@item
SCCS was the first version control system ever built, and was long ago
superseded by more advanced ones.  VC compensates for certain features
missing in SCCS (e.g., tag names for releases) by implementing them
itself.  Other VC features, such as multiple branches, are simply
unavailable.  Since SCCS is non-free, we recommend avoiding it.

@cindex CSSC
@item
CSSC is a free replacement for SCCS@.  You should use CSSC only if, for
some reason, you cannot use a more recent and better-designed version
control system.

@cindex RCS
@item
RCS is the free version control system around which VC was initially
built.  It is relatively primitive: it cannot be used over the
network, and works at the level of individual files.  Almost
everything you can do with RCS can be done through VC.

@cindex CVS
@item
CVS is the free version control system that was, until circa 2008,
used by the majority of free software projects.  Since then, it has
been superseded by newer systems.  CVS allows concurrent multi-user
development either locally or over the network.  Unlike newer systems,
it lacks support for atomic commits and file moving/renaming.  VC
supports all basic editing operations under CVS.

@cindex SVN
@cindex Subversion
@item
Subversion (svn) is a free version control system designed to be
similar to CVS but without its problems (e.g., it supports atomic
commits of filesets, and versioning of directories, symbolic links,
meta-data, renames, copies, and deletes).

@cindex git
@item
Git is a decentralized version control system originally invented by
Linus Torvalds to support development of Linux (his kernel).  VC
supports many common Git operations, but others, such as repository
syncing, must be done from the command line.

@cindex hg
@cindex Mercurial
@item
Mercurial (hg) is a decentralized version control system broadly
resembling Git.  VC supports most Mercurial commands, with the
exception of repository sync operations.

@cindex bzr
@cindex Bazaar
@item
Bazaar (bzr) is a decentralized version control system that supports
both repository-based and decentralized versioning.  VC supports most
basic editing operations under Bazaar.

@cindex SRC
@cindex src
@item
SRC (src) is RCS, reloaded---a specialized version-control system
designed for single-file projects worked on by only one person.  It
allows multiple files with independent version-control histories to
exist in one directory, and is thus particularly well suited for
maintaining small documents, scripts, and dotfiles.  While it uses RCS
for revision storage, it presents a modern user interface featuring
lockless operation and integer sequential version numbers.  VC
supports almost all SRC operations.
@end itemize

@node VCS Concepts
@subsubsection Concepts of Version Control

@cindex repository
@cindex registered file
   When a file is under version control, we say that it is
@dfn{registered} in the version control system.  The system has a
@dfn{repository} which stores both the file's present state and its
change history---enough to reconstruct the current version or any
earlier version.  The repository also contains other information, such
as @dfn{log entries} that describe the changes made to each file.

@cindex work file
@cindex checking out files
  The copy of a version-controlled file that you actually edit is
called the @dfn{work file}.  You can change each work file as you
would an ordinary file.  After you are done with a set of changes, you
may @dfn{commit} (or @dfn{check in}) the changes; this records the
changes in the repository, along with a descriptive log entry.

@cindex working tree
  A directory tree of work files is called a @dfn{working tree}.

@cindex revision
@cindex revision ID
  Each commit creates a new @dfn{revision} in the repository.  The
version control system keeps track of all past revisions and the
changes that were made in each revision.  Each revision is named by a
@dfn{revision ID}, whose format depends on the version control system;
in the simplest case, it is just an integer.

  To go beyond these basic concepts, you will need to understand three
aspects in which version control systems differ.  As explained in the
next three sections, they can be lock-based or merge-based; file-based
or changeset-based; and centralized or decentralized.  VC handles all
these modes of operation, but it cannot hide the differences.

@node VCS Merging
@subsubsection Merge-based vs Lock-based Version Control

  A version control system typically has some mechanism to coordinate
between users who want to change the same file.  There are two ways to
do this: merging and locking.

@cindex merging-based version
  In a version control system that uses merging, each user may modify
a work file at any time.  The system lets you @dfn{merge} your work
file, which may contain changes that have not been committed, with the
latest changes that others have committed.

@cindex locking-based version
  Older version control systems use a @dfn{locking} scheme instead.
Here, work files are normally read-only.  To edit a file, you ask the
version control system to make it writable for you by @dfn{locking}
it; only one user can lock a given file at any given time.  This
procedure is analogous to, but different from, the locking that Emacs
uses to detect simultaneous editing of ordinary files
(@pxref{Interlocking}).  When you commit your changes, that unlocks
the file, and the work file becomes read-only again.  Other users may
then lock the file to make their own changes.

  Both locking and merging systems can have problems when multiple
users try to modify the same file at the same time.  Locking systems
have @dfn{lock conflicts}; a user may try to check a file out and be
unable to because it is locked.  In merging systems, @dfn{merge
conflicts} happen when you commit a change to a file that conflicts
with a change committed by someone else after your checkout.  Both
kinds of conflict have to be resolved by human judgment and
communication.  Experience has shown that merging is superior to
locking, both in convenience to developers and in minimizing the
number and severity of conflicts that actually occur.

  SCCS always uses locking.  RCS is lock-based by default but can be
told to operate in a merging style.  CVS and Subversion are
merge-based by default but can be told to operate in a locking mode.
Decentralized version control systems, such as Git and Mercurial, are
exclusively merging-based.

  VC mode supports both locking and merging version control.  The
terms ``commit'' and ``update'' are used in newer version control
systems; older lock-based systems use the terms ``check in'' and
``check out''.  VC hides the differences between them as much as
possible.

@node VCS Changesets
@subsubsection Changeset-based vs File-based Version Control

@cindex file-based version control
  On SCCS, RCS, CVS, and other early version control systems (and also
in SRC), version control operations are @dfn{file-based}: each file
has its own comment and revision history separate from that of all
other files.  Newer systems, beginning with Subversion, are
@dfn{changeset-based}: a commit may include changes to several files,
and the entire set of changes is handled as a unit.  Any comment
associated with the change does not belong to a single file, but to
the changeset itself.

@cindex changeset-based version control
  Changeset-based version control is more flexible and powerful than
file-based version control; usually, when a change to multiple files
has to be reversed, it's good to be able to easily identify and remove
all of it.

@node VCS Repositories
@subsubsection Decentralized vs Centralized Repositories

@cindex centralized version control
@cindex decentralized version control
@cindex distributed version control
  Early version control systems were designed around a
@dfn{centralized} model in which each project has only one repository
used by all developers.  SCCS, RCS, CVS, Subversion, and SRC share this
kind of model.  One of its drawbacks is that the repository is a choke
point for reliability and efficiency.

  GNU Arch pioneered the concept of @dfn{distributed} or
@dfn{decentralized} version control, later implemented in Git,
Mercurial, and Bazaar.  A project may have several different
repositories, and these systems support a sort of super-merge between
repositories that tries to reconcile their change histories.  In
effect, there is one repository for each developer, and repository
merges take the place of commit operations.

  VC helps you manage the traffic between your personal workfiles and
a repository.  Whether the repository is a single master, or one of a
network of peer repositories, is not something VC has to care about.

@node Types of Log File
@subsubsection Types of Log File
@cindex types of log file
@cindex log File, types of
@cindex version control log

  Projects that use a version control system can have two types of log
for changes.  One is the log maintained by the version control system:
each time you commit a change, you fill out a @dfn{log entry} for the
change (@pxref{Log Buffer}).  This is called the @dfn{version control
log}.

  The other kind of log is the file @file{ChangeLog} (@pxref{Change
Log}).  It provides a chronological record of all changes to a large
portion of a program---typically one directory and its subdirectories.
A small program would use one @file{ChangeLog} file; a large program
may have a @file{ChangeLog} file in each major directory.
@xref{Change Log}.  Programmers have used change logs since long
before version control systems.

  Changeset-based version systems typically maintain a changeset-based
modification log for the entire system, which makes change log files
somewhat redundant.  One advantage that they retain is that it is
sometimes useful to be able to view the transaction history of a
single directory separately from those of other directories.  Another
advantage is that commit logs can't be fixed in many version control
systems.

  A project maintained with version control can use just the version
control log, or it can use both kinds of logs.  It can handle some
files one way and some files the other way.  Each project has its
policy, which you should follow.

  When the policy is to use both, you typically want to write an entry
for each change just once, then put it into both logs.  You can write
the entry in @file{ChangeLog}, then copy it to the log buffer with
@kbd{C-c C-a} when committing the change (@pxref{Log Buffer}).  Or you
can write the entry in the log buffer while committing the change
(with the help of @kbd{C-c C-w}), and later use the @kbd{C-x v a}
command to copy it to @file{ChangeLog}
@iftex
(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
@end iftex
@ifnottex
(@pxref{Change Logs and VC}).
@end ifnottex

@node VC Mode Line
@subsection Version Control and the Mode Line
@cindex VC mode line indicator

  When you visit a file that is under version control, Emacs indicates
this on the mode line.  For example, @samp{Bzr-1223} says that Bazaar
is used for that file, and the current revision ID is 1223.

@cindex version control status
  The character between the back-end name and the revision ID
indicates the @dfn{version control status} of the work file.  In a
merge-based version control system, a @samp{-} character indicates
that the work file is unmodified, and @samp{:} indicates that it has
been modified.  @samp{!} indicates that the file contains conflicts as
result of a recent merge operation (@pxref{Merging}), or that the file
was removed from the version control.  Finally, @samp{?} means that
the file is under version control, but is missing from the working
tree.

  In a lock-based system, @samp{-} indicates an unlocked file, and
@samp{:} a locked file; if the file is locked by another user (for
instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
@samp{@@} means that the file was locally added, but not yet committed
to the master repository.

  On a graphical display, you can move the mouse over this mode line
indicator to pop up a tool-tip, which displays a more verbose
description of the version control status.  Pressing @kbd{mouse-1}
over the indicator pops up a menu of VC commands, identical to
@samp{Tools / Version Control} on the menu bar.

@vindex auto-revert-check-vc-info
  When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is
under version control, it updates the version control information in
the mode line.  However, Auto Revert mode may not properly update this
information if the version control status changes without changes to
the work file, from outside the current Emacs session.  If you set
@code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates
the version control status information every
@code{auto-revert-interval} seconds, even if the work file itself is
unchanged.  The resulting CPU usage depends on the version control
system, but is usually not excessive.

@node Basic VC Editing
@subsection Basic Editing under Version Control

@cindex filesets, VC
@cindex VC filesets
   Most VC commands operate on @dfn{VC filesets}.  A VC fileset is a
collection of one or more files that a VC operation acts on.  When you
type VC commands in a buffer visiting a version-controlled file, the
VC fileset is simply that one file.  When you type them in a VC
Directory buffer, and some files in it are marked, the VC fileset
consists of the marked files (@pxref{VC Directory Mode}).

  On modern changeset-based version control systems (@pxref{VCS
Changesets}), VC commands handle multi-file VC filesets as a group.
For example, committing a multi-file VC fileset generates a single
revision, containing the changes to all those files.  On older
file-based version control systems like CVS, each file in a multi-file
VC fileset is handled individually; for example, a commit generates
one revision for each changed file.

@table @kbd
@item C-x v v
Perform the next appropriate version control operation on the current
VC fileset.
@end table

@findex vc-next-action
@kindex C-x v v
  The principal VC command is a multi-purpose command, @kbd{C-x v v}
(@code{vc-next-action}), which performs the most appropriate
action on the current VC fileset: either registering it with a version
control system, or committing it, or unlocking it, or merging changes
into it.  The precise actions are described in detail in the following
subsections.  You can use @kbd{C-x v v} either in a file-visiting
buffer or in a VC Directory buffer.

  Note that VC filesets are distinct from the named filesets used
for viewing and visiting files in functional groups
(@pxref{Filesets}).  Unlike named filesets, VC filesets are not named
and don't persist across sessions.

@menu
* VC With A Merging VCS::  Without locking: default mode for CVS.
* VC With A Locking VCS::  RCS in its default mode, SCCS, and optionally CVS.
* Advanced C-x v v::       Advanced features available with a prefix argument.
@end menu

@node VC With A Merging VCS
@subsubsection Basic Version Control with Merging

  On a merging-based version control system (i.e., most modern ones;
@pxref{VCS Merging}), @kbd{C-x v v} does the following:

@itemize @bullet
@item
If there is more than one file in the VC fileset and the files have
inconsistent version control statuses, signal an error.  (Note,
however, that a fileset is allowed to include both newly-added
files and modified files; @pxref{Registering}.)

@item
If none of the files in the VC fileset are registered with a version
control system, register the VC fileset, i.e., place it under version
control.  @xref{Registering}.  If Emacs cannot find a system to
register under, it prompts for a repository type, creates a new
repository, and registers the VC fileset with it.

@item
If every work file in the VC fileset is unchanged, do nothing.

@item
If every work file in the VC fileset has been modified, commit the
changes.  To do this, Emacs pops up a @file{*vc-log*} buffer; type the
desired log entry for the new revision, followed by @kbd{C-c C-c} to
commit.  @xref{Log Buffer}.

If committing to a shared repository, the commit may fail if the
repository has been changed since your last update.  In that
case, you must perform an update before trying again.  On a
decentralized version control system, use @kbd{C-x v +}
(@pxref{Pulling / Pushing}) or @kbd{C-x v m} (@pxref{Merging}).
On a centralized version control system, type @kbd{C-x v v} again to
merge in the repository changes.

@item
Finally, if you are using a centralized version control system, check
if each work file in the VC fileset is up-to-date.  If any file has
been changed in the repository, offer to update it.
@end itemize

  These rules also apply when you use RCS in its non-locking mode,
except that changes are not automatically merged from the repository.
Nothing informs you if another user has committed changes in the same
file since you began editing it; when you commit your revision, that
other user's changes are removed (however, they remain in the
repository and are thus not irrevocably lost).  Therefore, you must
verify that the current revision is unchanged before committing your
changes.  In addition, locking is possible with RCS even in this mode:
@kbd{C-x v v} with an unmodified file locks the file, just as it does
with RCS in its normal locking mode (@pxref{VC With A Locking VCS}).

@node VC With A Locking VCS
@subsubsection Basic Version Control with Locking

  On a locking-based version control system (such as SCCS, and RCS in
its default mode), @kbd{C-x v v} does the following:

@itemize @bullet
@item
If there is more than one file in the VC fileset and the files have
inconsistent version control statuses, signal an error.

@item
If each file in the VC fileset is not registered with a version
control system, register the VC fileset.  @xref{Registering}.  If
Emacs cannot find a system to register under, it prompts for a
repository type, creates a new repository, and registers the VC
fileset with it.

@item
If each file is registered and unlocked, lock it and make it writable,
so that you can begin to edit it.

@item
If each file is locked by you and contains changes, commit the
changes.  To do this, Emacs pops up a @file{*vc-log*} buffer; type the
desired log entry for the new revision, followed by @kbd{C-c C-c} to
commit (@pxref{Log Buffer}).

@item
If each file is locked by you, but you have not changed it, release
the lock and make the file read-only again.

@item
If each file is locked by another user, ask whether you want to
steal the lock.  If you say yes, the file becomes locked by you,
and a warning message is sent to the user who had formerly locked the
file.
@end itemize

  These rules also apply when you use CVS in locking mode, except
that CVS does not support stealing locks.

@node Advanced C-x v v
@subsubsection Advanced Control in @kbd{C-x v v}

@cindex revision ID in version control
  When you give a prefix argument to @code{vc-next-action} (@kbd{C-u
C-x v v}), it still performs the next logical version control
operation, but accepts additional arguments to specify precisely how
to do the operation.

@itemize @bullet
@item
@cindex specific version control system
You can specify the name of a version control system.  This is useful
if the fileset can be managed by more than one version control system,
and Emacs fails to detect the correct one.

@item
Otherwise, if using CVS, RCS or SRC, you can specify a revision ID.

If the fileset is modified (or locked), this makes Emacs commit with
that revision ID@.  You can create a new branch by supplying an
appropriate revision ID (@pxref{Branches}).

If the fileset is unmodified (and unlocked), this checks the specified
revision into the working tree.  You can also specify a revision on
another branch by giving its revision or branch ID (@pxref{Switching
Branches}).  An empty argument (i.e., @kbd{C-u C-x v v @key{RET}})
checks out the latest (head) revision on the current branch.

This is silently ignored on a decentralized version control system.
Those systems do not let you specify your own revision IDs, nor do
they use the concept of checking out individual files.
@end itemize

@node Log Buffer
@subsection Features of the Log Entry Buffer

@kindex C-c C-c @r{(Log Edit mode)}
@findex log-edit-done
  When you tell VC to commit a change, it pops up a buffer named
@file{*vc-log*}.  In this buffer, you should write a @dfn{log entry}
describing the changes you have made (@pxref{Why Version Control?}).
After you are done, type @kbd{C-c C-c} (@code{log-edit-done}) to exit
the buffer and commit the change, together with your log entry.

@cindex Log Edit mode
@cindex mode, Log Edit
@vindex vc-log-mode-hook
@c FIXME: Mention log-edit-mode-hook here?  --xfq
  The major mode for the @file{*vc-log*} buffer is Log Edit mode, a
variant of Text mode (@pxref{Text Mode}).  On entering Log Edit mode,
Emacs runs the hooks @code{text-mode-hook} and @code{vc-log-mode-hook}
(@pxref{Hooks}).

  In the @file{*vc-log*} buffer, you can write one or more @dfn{header
lines}, specifying additional information to be supplied to the
version control system.  Each header line must occupy a single line at
the top of the buffer; the first line that is not a header line is
treated as the start of the log entry.  For example, the following
header line states that the present change was not written by you, but
by another developer:

@smallexample
Author: J. R. Hacker <jrh@@example.com>
@end smallexample

@noindent
Apart from the @samp{Author} header, Emacs recognizes the headers
@samp{Summary} (a one-line summary of the changeset), @samp{Date} (a
manually-specified commit time), and @samp{Fixes} (a reference to a
bug fixed by the change).  Not all version control systems recognize
all headers.  If you specify a header for a system that does not
support it, the header is treated as part of the log entry.

@kindex C-c C-f @r{(Log Edit mode)}
@findex log-edit-show-files
@kindex C-c C-d @r{(Log Edit mode)}
@findex log-edit-show-diff
  While in the @file{*vc-log*} buffer, the current VC fileset is
considered to be the fileset that will be committed if you type
@w{@kbd{C-c C-c}}.  To view a list of the files in the VC fileset,
type @w{@kbd{C-c C-f}} (@code{log-edit-show-files}).  To view a diff
of changes between the VC fileset and the version from which you
started editing (@pxref{Old Revisions}), type @kbd{C-c C-d}
(@code{log-edit-show-diff}).

@kindex C-c C-w @r{(Log Edit mode)}
@findex log-edit-generate-changelog-from-diff
  To help generate ChangeLog entries, type @kbd{C-c C-w}
(@code{log-edit-generate-changelog-from-diff}), to generate skeleton
ChangeLog entries, listing all changed file and function names based
on the diff of the VC fileset.  Consecutive entries left empty will be
combined by @kbd{C-q} (@code{fill-paragraph}).

@kindex C-c C-a @r{(Log Edit mode)}
@findex log-edit-insert-changelog
  If the VC fileset includes one or more @file{ChangeLog} files
(@pxref{Change Log}), type @kbd{C-c C-a}
(@code{log-edit-insert-changelog}) to pull the relevant entries into
the @file{*vc-log*} buffer.  If the topmost item in each
@file{ChangeLog} was made under your user name on the current date,
this command searches that item for entries matching the file(s) to be
committed, and inserts them.
@ifnottex
If you are using CVS or RCS, see @ref{Change Logs and VC}, for the
opposite way of working---generating ChangeLog entries from the Log
Edit buffer.
@end ifnottex

  To abort a commit, just @emph{don't} type @kbd{C-c C-c} in that
buffer.  You can switch buffers and do other editing.  As long as you
don't try to make another commit, the entry you were editing remains
in the @file{*vc-log*} buffer, and you can go back to that buffer at
any time to complete the commit.

@kindex M-n @r{(Log Edit mode)}
@kindex M-p @r{(Log Edit mode)}
@kindex M-s @r{(Log Edit mode)}
@kindex M-r @r{(Log Edit mode)}
  You can also browse the history of previous log entries to duplicate
a commit comment.  This can be useful when you want to make several
commits with similar comments.  The commands @kbd{M-n}, @kbd{M-p},
@kbd{M-s} and @kbd{M-r} for doing this work just like the minibuffer
history commands (@pxref{Minibuffer History}), except that they are
used outside the minibuffer.

@node Registering
@subsection Registering a File for Version Control

@table @kbd
@item C-x v i
Register the visited file for version control.
@end table

@kindex C-x v i
@findex vc-register
  The command @kbd{C-x v i} (@code{vc-register}) @dfn{registers} each
file in the current VC fileset, placing it under version control.
This is essentially equivalent to the action of @kbd{C-x v v} on an
unregistered VC fileset (@pxref{Basic VC Editing}), except that if the
VC fileset is already registered, @kbd{C-x v i} signals an error
whereas @kbd{C-x v v} performs some other action.

  To register a file, Emacs must choose a version control system.  For
a multi-file VC fileset, the VC Directory buffer specifies the system
to use (@pxref{VC Directory Mode}).  For a single-file VC fileset, if
the file's directory already contains files registered in a version
control system, or if the directory is part of a directory tree
controlled by a version control system, Emacs chooses that system.  In
the event that more than one version control system is applicable,
Emacs uses the one that appears first in the variable
@iftex
@code{vc-handled-backends}.
@end iftex
@ifnottex
@code{vc-handled-backends} (@pxref{Customizing VC}).
@end ifnottex
If Emacs cannot find a version control system to register the file
under, it prompts for a repository type, creates a new repository, and
registers the file into that repository.

  On most version control systems, registering a file with @kbd{C-x v
i} or @kbd{C-x v v} adds it to the working tree but not to the
repository.  Such files are labeled as @samp{added} in the VC
Directory buffer, and show a revision ID of @samp{@@@@} in the mode
line.  To make the registration take effect in the repository, you
must perform a commit (@pxref{Basic VC Editing}).  Note that a single
commit can include both file additions and edits to existing files.

  On a locking-based version control system (@pxref{VCS Merging}),
registering a file leaves it unlocked and read-only.  Type @kbd{C-x v
v} to start editing it.

@node Old Revisions
@subsection Examining And Comparing Old Revisions

@table @kbd
@item C-x v =
Compare the work files in the current VC fileset with the versions you
started from (@code{vc-diff}).  With a prefix argument, prompt for two
revisions of the current VC fileset and compare them.  You can also
call this command from a Dired buffer (@pxref{Dired}).

@ifnottex
@item M-x vc-ediff
Like @kbd{C-x v =}, but using Ediff.  @xref{Top,, Ediff, ediff, The
Ediff Manual}.
@end ifnottex

@item C-x v D
Compare the entire working tree to the revision you started from
(@code{vc-root-diff}).  With a prefix argument, prompt for two
revisions and compare their trees.

@item C-x v ~
Prompt for a revision of the current file, and visit it in a separate
buffer (@code{vc-revision-other-window}).

@item C-x v g
Display an annotated version of the current file: for each line, show
the latest revision in which it was modified (@code{vc-annotate}).
@end table

@findex vc-diff
@kindex C-x v =
  @kbd{C-x v =} (@code{vc-diff}) displays a @dfn{diff} which compares
each work file in the current VC fileset to the version(s) from which
you started editing.  The diff is displayed in another window, in a
Diff mode buffer (@pxref{Diff Mode}) named @file{*vc-diff*}.  The
usual Diff mode commands are available in this buffer.  In particular,
the @kbd{g} (@code{revert-buffer}) command performs the file
comparison again, generating a new diff.

@kindex C-u C-x v =
  To compare two arbitrary revisions of the current VC fileset, call
@code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}.  This
prompts for two revision IDs (@pxref{VCS Concepts}), and displays a
diff between those versions of the fileset.  This will not work
reliably for multi-file VC filesets, if the version control system is
file-based rather than changeset-based (e.g., CVS), since then
revision IDs for different files would not be related in any
meaningful way.

  Instead of the revision ID, some version control systems let you
specify revisions in other formats.  For instance, under Bazaar you
can enter @samp{date:yesterday} for the argument to @kbd{C-u C-x v =}
(and related commands) to specify the first revision committed after
yesterday.  See the documentation of the version control system for
details.

  If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a Dired buffer
(@pxref{Dired}), the file listed on the current line is treated as the
current VC fileset.

@ifnottex
@findex vc-ediff
  @kbd{M-x vc-ediff} works like @kbd{C-x v =}, except that it uses an
Ediff session.  @xref{Top,, Ediff, ediff, The Ediff Manual}.
@end ifnottex

@findex vc-root-diff
@kindex C-x v D
  @kbd{C-x v D} (@code{vc-root-diff}) is similar to @kbd{C-x v =}, but
it displays the changes in the entire current working tree (i.e., the
working tree containing the current VC fileset).  If you invoke this
command from a Dired buffer, it applies to the working tree containing
the directory.

@findex vc-root-version-diff
@kindex C-u C-x v D
  To compare two arbitrary revisions of the whole trees, call
@code{vc-root-diff} with a prefix argument: @kbd{C-u C-x v D}.  This
prompts for two revision IDs (@pxref{VCS Concepts}), and displays a
diff between those versions of the entire version-controlled directory
trees (RCS, SCCS, CVS, and SRC do not support this feature).

@vindex vc-diff-switches
  You can customize the @command{diff} options that @kbd{C-x v =} and
@kbd{C-x v D} use for generating diffs.  The options used are taken
from the first non-@code{nil} value amongst the variables
@code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, and
@code{diff-switches} (@pxref{Comparing Files}), in that order.  Here,
@var{backend} stands for the relevant version control system,
e.g., @code{bzr} for Bazaar.  Since @code{nil} means to check the
next variable in the sequence, either of the first two may use the
value @code{t} to mean no switches at all.  Most of the
@code{vc-@var{backend}-diff-switches} variables default to @code{nil},
but some default to @code{t}; these are for version control systems
whose @code{diff} implementations do not accept common diff options,
such as Subversion.

@findex vc-revision-other-window
@kindex C-x v ~
  To directly examine an older version of a file, visit the work file
and type @kbd{C-x v ~ @var{revision} @key{RET}}
(@code{vc-revision-other-window}).  This retrieves the file version
corresponding to @var{revision}, saves it to
@file{@var{filename}.~@var{revision}~}, and visits it in a separate
window.

@findex vc-annotate
@vindex vc-annotate-background-mode
@kindex C-x v g
  Many version control systems allow you to view files @dfn{annotated}
with per-line revision information, by typing @kbd{C-x v g}
(@code{vc-annotate}).  This creates a new ``annotate'' buffer
displaying the file's text, with each line colored to show how old it
is.  Red text is new, blue is old, and intermediate colors indicate
intermediate ages.  By default, the color is scaled over the full
range of ages, such that the oldest changes are blue, and the newest
changes are red.  If the variable @code{vc-annotate-background-mode}
is non-@code{nil}, the colors expressing the age of each line are
applied to the background color, leaving the foreground at its default
color.

  When you give a prefix argument to this command, Emacs reads two
arguments using the minibuffer: the revision to display and annotate
(instead of the current file contents), and the time span in days the
color range should cover.

  From the ``annotate'' buffer, these and other color scaling options are
available from the @samp{VC-Annotate} menu.  In this buffer, you can
also use the following keys to browse the annotations of past revisions,
view diffs, or view log entries:

@table @kbd
@item p
Annotate the previous revision, i.e., the revision before the one
currently annotated.  A numeric prefix argument is a repeat count, so
@kbd{C-u 10 p} would take you back 10 revisions.

@item n
Annotate the next revision, i.e., the revision after the one
currently annotated.  A numeric prefix argument is a repeat count.

@item j
Annotate the revision indicated by the current line.

@item a
Annotate the revision before the one indicated by the current line.
This is useful to see the state the file was in before the change on
the current line was made.

@item f
Show in a buffer the file revision indicated by the current line.

@item d
Display the diff between the current line's revision and the previous
revision.  This is useful to see what the current line's revision
actually changed in the file.

@item D
Display the diff between the current line's revision and the previous
revision for all files in the changeset (for VC systems that support
changesets).  This is useful to see what the current line's revision
actually changed in the tree.

@item l
Show the log of the current line's revision.  This is useful to see
the author's description of the changes in the revision on the current
line.

@item w
Annotate the working revision--the one you are editing.  If you used
@kbd{p} and @kbd{n} to browse to other revisions, use this key to
return to your working revision.

@item v
Toggle the annotation visibility.  This is useful for looking just at
the file contents without distraction from the annotations.
@end table

@node VC Change Log
@subsection VC Change Log
@cindex VC change log

@table @kbd
@item C-x v l
Display the change history for the current fileset
(@code{vc-print-log}).

@item C-x v L
Display the change history for the current repository
(@code{vc-print-root-log}).

@item C-x v I
Display the changes that a ``pull'' operation will retrieve
(@code{vc-log-incoming}).

@item C-x v O
Display the changes that will be sent by the next ``push'' operation
(@code{vc-log-outgoing}).

@item C-x v h
Display the history of changes made in the region of file visited by
the current buffer (@code{vc-region-history}).

@item M-x vc-log-search @key{RET}
Search the change history for a specified pattern.
@end table

@kindex C-x v l
@findex vc-print-log
  @kbd{C-x v l} (@code{vc-print-log}) displays a buffer named
@file{*vc-change-log*}, showing the history of changes made to the
current file, including who made the changes, the dates, and the log
entry for each change (these are the same log entries you would enter
via the @file{*vc-log*} buffer; @pxref{Log Buffer}).  Point is
centered at the revision of the file currently being visited.  With a
prefix argument, the command prompts for the revision to center on,
and the maximum number of revisions to display.

  If you call @kbd{C-x v l} from a VC Directory buffer (@pxref{VC
Directory Mode}) or a Dired buffer (@pxref{Dired}), it applies to the
file listed on the current line.

@kindex C-x v L
@findex vc-print-root-log
@findex log-view-toggle-entry-display
  @kbd{C-x v L} (@code{vc-print-root-log}) displays a
@file{*vc-change-log*} buffer showing the history of the entire
version-controlled directory tree (RCS, SCCS, CVS, and SRC do not
support this feature).  With a prefix argument, the command prompts
for the maximum number of revisions to display.  A numeric prefix
argument specifies the maximum number of revisions without prompting.
When the numeric prefix argument is 1, as in @w{@kbd{C-1 C-x v L}} or
@w{@kbd{C-u 1 C-x v L}}, the command prompts for the revision ID, and
displays the log entry of that revision together with the changes
(diffs) it introduced.  (Some less capable version control systems,
such as RCS and CVS, don't have commands to show a revision log with
its diffs; for them the command displays only the log entry, and you
can request to show the diffs by typing @kbd{d} or @kbd{D}, see
below.)

  The @kbd{C-x v L} history is shown in a compact form, usually
showing only the first line of each log entry.  However, you can type
@key{RET} (@code{log-view-toggle-entry-display}) in the
@file{*vc-change-log*} buffer to reveal the entire log entry for the
revision at point.  A second @key{RET} hides it again.

@kindex C-x v I
@kindex C-x v O
@findex vc-log-incoming
@findex vc-log-outgoing
  On a decentralized version control system, the @kbd{C-x v I}
(@code{vc-log-incoming}) command displays a log buffer showing the
changes that will be applied, the next time you run the version
control system's pull command to get new revisions from another
repository (@pxref{Pulling / Pushing}).  This other repository is the default
one from which changes are pulled, as defined by the version control
system; with a prefix argument, @code{vc-log-incoming} prompts for a
specific repository.  Similarly, @kbd{C-x v O}
(@code{vc-log-outgoing}) shows the changes that will be sent to
another repository, the next time you run the push command; with a
prefix argument, it prompts for a specific destination repository.

@cindex VC log buffer, commands in
@cindex vc-log buffer
  In the @file{*vc-change-log*} buffer, you can use the following keys
to move between the logs of revisions and of files, and to examine and
compare past revisions (@pxref{Old Revisions}):

@table @kbd
@item p
Move to the previous revision entry.  (Revision entries in the log
buffer are usually in reverse-chronological order, so the previous
revision-item usually corresponds to a newer revision.)  A numeric
prefix argument is a repeat count.

@item n
Move to the next revision entry.  A numeric prefix argument is a
repeat count.

@item P
Move to the log of the previous file, if showing logs for a multi-file
VC fileset.  Otherwise, just move to the beginning of the log.  A
numeric prefix argument is a repeat count.

@item N
Move to the log of the next file, if showing logs for a multi-file VC
fileset.  A numeric prefix argument is a repeat count.

@item a
Annotate the revision on the current line (@pxref{Old Revisions}).

@item e
Modify the change comment displayed at point.  Note that not all VC
systems support modifying change comments.

@item f
Visit the revision indicated at the current line.

@item d
Display a diff between the revision at point and the next earlier
revision, for the specific file.

@item D
Display the changeset diff between the revision at point and the next
earlier revision.  This shows the changes to all files made in that
revision.

@item @key{RET}
In a compact-style log buffer (e.g., the one created by @kbd{C-x v
L}), toggle between showing and hiding the full log entry for the
revision at point.
@end table

@vindex vc-log-show-limit
Because fetching many log entries can be slow, the
@file{*vc-change-log*} buffer displays no more than 2000 revisions by
default.  The variable @code{vc-log-show-limit} specifies this limit;
if you set the value to zero, that removes the limit.  You can also
increase the number of revisions shown in an existing
@file{*vc-change-log*} buffer by clicking on the @samp{Show 2X
entries} or @samp{Show unlimited entries} buttons at the end of the
buffer.  However, RCS, SCCS, CVS, and SRC do not support this feature.

@kindex C-x v h
@findex vc-region-history
A useful variant of examining history of changes is provided by the command
@kbd{vc-region-history} (by default bound to @kbd{C-x v h}), which shows
a @file{*VC-history*} buffer with the history of changes made in the region
of the current buffer's file between point and the mark (@pxref{Mark}).  The
history of changes includes the commit log messages and also the
changes themselves in the Diff format.

Invoke this command after marking in the current buffer the region in
whose changes you are interested.  In the @file{*VC-history*} buffer
it pops up, you can use all of the commands available in the
@file{*vc-change-log*} buffer described above, and also the commands
defined by Diff mode (@pxref{Diff Mode}).

This command is currently available only with Git and Mercurial (hg).

@findex vc-log-search
The command @code{vc-log-search} allows searching for a pattern in the
log of changes.  It prompts for a pattern (a regular expression), and
displays all entries in the change history whose log messages match
the pattern.  When invoked with a prefix argument, the command will
also prompt for a specific VCS shell command to run for this purpose.

@node VC Undo
@subsection Undoing Version Control Actions

@table @kbd
@item C-x v u
Revert the work file(s) in the current VC fileset to the last revision
(@code{vc-revert}).
@end table

@kindex C-x v u
@findex vc-revert
@vindex vc-revert-show-diff
  If you want to discard all the changes you have made to the current
VC fileset, type @kbd{C-x v u} (@code{vc-revert}).  This shows
you a diff between the work file(s) and the revision from which you
started editing, and asks for confirmation for discarding the changes.
If you agree, the fileset is reverted.  If you don't want @kbd{C-x v
u} to show a diff, set the variable @code{vc-revert-show-diff} to
@code{nil} (you can still view the diff directly with @kbd{C-x v =};
@pxref{Old Revisions}).

  On locking-based version control systems, @kbd{C-x v u} leaves files
unlocked; you must lock again to resume editing.  You can also use
@kbd{C-x v u} to unlock a file if you lock it and then decide not to
change it.

@node VC Ignore
@subsection Ignore Version Control Files

@table @kbd
@item C-x v G
Ignore a file under current version control system.  (@code{vc-ignore}).
@end table

@kindex C-x v G
@findex vc-ignore
  Many source trees contain some files that do not need to be
versioned, such as editor backups, object or bytecode files, and built
programs.  You can simply not add them, but then they'll always crop
up as unknown files.  You can also tell the version control system to
ignore these files by adding them to the ignore file at the top of the
tree.  @kbd{C-x v G} (@code{vc-ignore}) can help you do this.  When
called with a prefix argument, you can remove a file from the ignored
file list.

@node VC Directory Mode
@subsection VC Directory Mode

@cindex VC Directory buffer
  The @dfn{VC Directory buffer} is a specialized buffer for viewing
the version control statuses of the files in a directory tree, and
performing version control operations on those files.  In particular,
it is used to specify multi-file VC filesets for commands like
@w{@kbd{C-x v v}} to act on (@pxref{VC Directory Commands}).

@kindex C-x v d
@findex vc-dir
  To use the VC Directory buffer, type @kbd{C-x v d} (@code{vc-dir}).
This reads a directory's name using the minibuffer, and switches to a VC
Directory buffer for that directory.  By default, the buffer is named
@file{*vc-dir*}.  Its contents are described
@iftex
below.
@end iftex
@ifnottex
in @ref{VC Directory Buffer}.
@end ifnottex

  The @code{vc-dir} command automatically detects the version control
system to be used in the specified directory.  In the event that more
than one system is being used in the directory, you should invoke the
command with a prefix argument, @kbd{C-u C-x v d}; this prompts for
the version control system which the VC Directory buffer should use.

@ifnottex
@cindex PCL-CVS
@pindex cvs
@cindex CVS directory mode
  In addition to the VC Directory buffer, Emacs has a similar facility
called PCL-CVS which is specialized for CVS@.  @xref{Top, , About
PCL-CVS, pcl-cvs, PCL-CVS---The Emacs Front-End to CVS}.
@end ifnottex

@menu
* Buffer: VC Directory Buffer.      What the buffer looks like and means.
* Commands: VC Directory Commands.  Commands to use in a VC directory buffer.
@end menu

@node VC Directory Buffer
@subsubsection The VC Directory Buffer

  The VC Directory buffer contains a list of version-controlled files
and their version control statuses.  It lists files in the current
directory (the one specified when you called @kbd{C-x v d}) and its
subdirectories, but only those with a noteworthy status.  Files
that are up-to-date (i.e., the same as in the repository) are
omitted.  If all the files in a subdirectory are up-to-date, the
subdirectory is not listed either.  As an exception, if a file has
become up-to-date as a direct result of a VC command, it is listed.

  Here is an example of a VC Directory buffer listing:

@smallexample
@group
                     ./
    edited           configure.ac
*   added            README
    unregistered     temp.txt
                     src/
*   edited           src/main.c
@end group
@end smallexample

@noindent
Two work files have been modified but not committed:
@file{configure.ac} in the current directory, and @file{main.c} in the
@file{src/} subdirectory.  The file named @file{README} has been added
but is not yet committed, while @file{temp.txt} is not under version
control (@pxref{Registering}).

The @samp{*} characters next to the entries for @file{README} and
@file{src/main.c} indicate that the user has marked these files as
the current VC fileset
@iftex
(see below).
@end iftex
@ifnottex
(@pxref{VC Directory Commands}).
@end ifnottex

  The above example is typical for a decentralized version control
system like Bazaar, Git, or Mercurial.  Other systems can show other
statuses.  For instance, CVS shows the @samp{needs-update} status if
the repository has changes that have not been applied to the work
file.  RCS and SCCS show the name of the user locking a file as its
status.

@ifnottex
  On CVS, the @code{vc-dir} command normally contacts the repository,
which may be on a remote machine, to check for updates.  If you change
the variable @code{vc-cvs-stay-local} to @code{nil} (@pxref{CVS
Options}), then Emacs avoids contacting a remote repository when
generating the VC Directory buffer (it will still contact it when
necessary, e.g., when doing a commit).  This may be desirable if you
are working offline or the network is slow.
@end ifnottex

@vindex vc-directory-exclusion-list
  The VC Directory buffer omits subdirectories listed in the variable
@code{vc-directory-exclusion-list}.  Its default value contains
directories that are used internally by version control systems.

@node VC Directory Commands
@subsubsection VC Directory Commands

  Emacs provides several commands for navigating the VC Directory
buffer, and for marking files as belonging to the current VC
fileset.

@table @kbd
@item n
@itemx @key{SPC}
Move point to the next entry (@code{vc-dir-next-line}).

@item p
Move point to the previous entry (@code{vc-dir-previous-line}).

@item @key{TAB}
Move to the next directory entry (@code{vc-dir-next-directory}).

@item S-@key{TAB}
Move to the previous directory entry
(@code{vc-dir-previous-directory}).

@item @key{RET}
@itemx f
Visit the file or directory listed on the current line
(@code{vc-dir-find-file}).

@item o
Visit the file or directory on the current line, in a separate window
(@code{vc-dir-find-file-other-window}).

@item m
Mark the file or directory on the current line (@code{vc-dir-mark}),
putting it in the current VC fileset.  If the region is active, mark
all files in the region.

A file cannot be marked with this command if it is already in a marked
directory, or one of its subdirectories.  Similarly, a directory
cannot be marked with this command if any file in its tree is marked.

@item M
If point is on a file entry, mark all files with the same status; if
point is on a directory entry, mark all files in that directory tree
(@code{vc-dir-mark-all-files}).  With a prefix argument, mark all
listed files and directories.

@item G
Add the file under point to the list of files that the VC should
ignore (@code{vc-dir-ignore}).  For instance, if the VC is Git, it
will append this file to the @file{.gitignore} file.  If given a
prefix, do this with all the marked files.

@item q
Quit the VC Directory buffer, and bury it (@code{quit-window}).

@item u
Unmark the file or directory on the current line.  If the region is
active, unmark all the files in the region (@code{vc-dir-unmark}).

@item U
If point is on a file entry, unmark all files with the same status; if
point is on a directory entry, unmark all files in that directory tree
(@code{vc-dir-unmark-all-files}).  With a prefix argument, unmark all
files and directories.

@item x
Hide files with @samp{up-to-date} or @samp{ignored} status
(@code{vc-dir-hide-up-to-date}).  With a prefix argument, hide items
whose state is that of the item at point.
@end table

@findex vc-dir-mark
@findex vc-dir-mark-all-files
  While in the VC Directory buffer, all the files that you mark with
@kbd{m} (@code{vc-dir-mark}) or @kbd{M} (@code{vc-dir-mark-all-files})
are in the current VC fileset.  If you mark a directory entry with
@kbd{m}, all the listed files in that directory tree are in the
current VC fileset.  The files and directories that belong to the
current VC fileset are indicated with a @samp{*} character in the VC
Directory buffer, next to their VC status.  In this way, you can set
up a multi-file VC fileset to be acted on by VC commands like
@w{@kbd{C-x v v}} (@pxref{Basic VC Editing}), @w{@kbd{C-x v =}}
(@pxref{Old Revisions}), and @w{@kbd{C-x v u}} (@pxref{VC Undo}).

  The VC Directory buffer also defines some single-key shortcuts for
VC commands with the @kbd{C-x v} prefix: @kbd{=}, @kbd{+}, @kbd{l},
@kbd{i}, @kbd{D}, @kbd{L}, @kbd{G}, @kbd{I}, @kbd{O}, and @kbd{v}.

  For example, you can commit a set of edited files by opening a VC
Directory buffer, where the files are listed with the @samp{edited}
status; marking the files; and typing @kbd{v} or @kbd{C-x v v}
(@code{vc-next-action}).  If the version control system is
changeset-based, Emacs will commit the files in a single revision.

  While in the VC Directory buffer, you can also perform search and
replace on the current VC fileset, with the following commands:

@table @kbd
@item S
Search the fileset (@code{vc-dir-search}).

@item Q
Do a regular expression query replace on the fileset
(@code{vc-dir-query-replace-regexp}).

@item M-s a C-s
Do an incremental search on the fileset (@code{vc-dir-isearch}).

@item M-s a C-M-s
Do an incremental regular expression search on the fileset
(@code{vc-dir-isearch-regexp}).
@end table

@noindent
Apart from acting on multiple files, these commands behave much like
their single-buffer counterparts (@pxref{Search}).

  The VC Directory buffer additionally defines some branch-related
commands starting with the prefix @kbd{B}:

@table @kbd
@item B c
Create a new branch (@code{vc-create-tag}).

@item B l
Prompt for the name of a branch and display the change history of that
branch (@code{vc-print-branch-log}).

@item B s
Switch to a branch (@code{vc-retrieve-tag}).  @xref{Switching
Branches}.

@item d
Delete the marked files, or the current file if no marks
(@code{vc-dir-clean-delete)}.  The files will not be marked as
deleted in the version control system, so this function is mostly
useful for unregistered files.
@end table

@cindex stashes in version control
@cindex shelves in version control
  The above commands are also available via the menu bar, and via a
context menu invoked by @kbd{mouse-2}.  Furthermore, some VC backends
use the menu to provide extra backend-specific commands.  For example,
Git and Bazaar allow you to manipulate @dfn{stashes} and @dfn{shelves}
(which are a way to temporarily put aside uncommitted changes, and
bring them back at a later time).

@node Branches
@subsection Version Control Branches
@cindex branch (version control)

  One use of version control is to support multiple independent lines
of development, which are called @dfn{branches}.  Amongst other
things, branches can be used for maintaining separate stable and
development versions of a program, and for developing unrelated
features in isolation from one another.

  VC's support for branch operations is currently fairly limited.  For
decentralized version control systems, it provides commands for
@dfn{updating} one branch with the contents of another, and for
@dfn{merging} the changes made to two different branches
(@pxref{Merging}).  For centralized version control systems, it
supports checking out different branches and committing into new or
different branches.

@menu
* Switching Branches::    How to get to another existing branch.
* Pulling / Pushing::     Receiving/sending changes from/to elsewhere.
* Merging::               Transferring changes between branches.
* Creating Branches::     How to start a new branch.
@end menu

@node Switching Branches
@subsubsection Switching between Branches

  The various version control systems differ in how branches are
implemented, and these differences cannot be entirely concealed by VC.

  On some decentralized version control systems, including Bazaar and
Mercurial in its normal mode of operation, each branch has its own
working directory tree, so switching between branches just involves
switching directories.  On Git, branches are normally @dfn{co-located}
in the same directory, and switching between branches is done using
the @kbd{git checkout} command, which changes the contents of the
working tree to match the branch you switch to.  Bazaar also supports
co-located branches, in which case the @kbd{bzr switch} command
will switch branches in the current directory.  With Subversion, you
switch to another branch using the @kbd{svn switch} command.  With
Mercurial, command @kbd{hg update} is used to switch to another
branch.

  The VC command to switch to another branch in the current directory
is @kbd{C-x v r @var{branch-name} @key{RET}} (@code{vc-retrieve-tag}).

  On centralized version control systems, you can also switch between
branches by typing @kbd{C-u C-x v v} in an up-to-date work file
(@pxref{Advanced C-x v v}), and entering the revision ID for a
revision on another branch.  On CVS, for instance, revisions on the
@dfn{trunk} (the main line of development) normally have IDs of the
form 1.1, 1.2, 1.3, @dots{}, while the first branch created from (say)
revision 1.2 has revision IDs 1.2.1.1, 1.2.1.2, @dots{}, the second
branch created from revision 1.2 has revision IDs 1.2.2.1, 1.2.2.2,
@dots{}, and so forth.  You can also specify the @dfn{branch ID},
which is a branch revision ID omitting its final component
(e.g., 1.2.1), to switch to the latest revision on that branch.

  On a locking-based system, switching to a different branch also
unlocks (write-protects) the working tree.

  Once you have switched to a branch, VC commands will apply to that
branch until you switch away; for instance, any VC filesets that you
commit will be committed to that specific branch.

@node Pulling / Pushing
@subsubsection Pulling/Pushing Changes into/from a Branch

@table @kbd
@item C-x v P
On a decentralized version control system, update another location
with changes from the current branch (a.k.a. ``push'' changes).  This
concept does not exist for centralized version control systems

@item C-x v +
On a decentralized version control system, update the current branch
by ``pulling in'' changes from another location.

On a centralized version control system, update the current VC
fileset.
@end table

@kindex C-x v P
@findex vc-push
On a decentralized version control system, the command @kbd{C-x v P}
(@code{vc-push}) updates another location with changes from the
current branch.  With a prefix argument, it prompts for the exact
version control command to run, which lets you specify where to push
changes; the default is @kbd{bzr push} with Bazaar, @kbd{git
push} with Git, and @kbd{hg push} with Mercurial.  The default
commands always push to a default location determined by the version
control system from your branch configuration.

Prior to pushing, you can use @kbd{C-x v O} (@code{vc-log-outgoing})
to view a log buffer of the changes to be sent.  @xref{VC Change Log}.

@cindex bound branch (Bazaar VCS)
This command is currently supported only by Bazaar, Git, and Mercurial.
The concept of ``pushing'' does not exist for centralized version
control systems, where this operation is a part of committing a
changeset, so invoking this command on a centralized VCS signals an
error.  This command also signals an error when attempted in a Bazaar
@dfn{bound branch}, where committing a changeset automatically pushes
the changes to the remote repository to which the local branch is
bound.

@kindex C-x v +
@findex vc-pull
  On a decentralized version control system, the command @kbd{C-x v +}
(@code{vc-pull}) updates the current branch and working tree.  It is
typically used to update a copy of a remote branch.  If you supply a
prefix argument, the command prompts for the exact version control
command to use, which lets you specify where to pull changes from.
Otherwise, it pulls from a default location determined by the version
control system.

  Amongst decentralized version control systems, @kbd{C-x v +} is
currently supported only by Bazaar, Git, and Mercurial.  With Bazaar,
it calls @kbd{bzr pull} for ordinary branches (to pull from a
master branch into a mirroring branch), and @kbd{bzr update} for a
bound branch (to pull from a central repository).  With Git, it calls
@kbd{git pull} to fetch changes from a remote repository and merge
it into the current branch.  With Mercurial, it calls @kbd{hg pull
-u} to fetch changesets from the default remote repository and update
the working directory.

  Prior to pulling, you can use @kbd{C-x v I} (@code{vc-log-incoming})
to view a log buffer of the changes to be applied.  @xref{VC Change
Log}.

  On a centralized version control system like CVS, @kbd{C-x v +}
updates the current VC fileset from the repository.

@node Merging
@subsubsection Merging Branches
@cindex merging changes

@table @kbd
@item C-x v m
On a decentralized version control system, merge changes from another
branch into the current one.

On a centralized version control system, merge changes from another
branch into the current VC fileset.
@end table

  While developing a branch, you may sometimes need to @dfn{merge} in
changes that have already been made in another branch.  This is not a
trivial operation, as overlapping changes may have been made to the
two branches.

  On a decentralized version control system, merging is done with the
command @kbd{C-x v m} (@code{vc-merge}).  On Bazaar, this prompts for
the exact arguments to pass to @kbd{bzr merge}, offering a
sensible default if possible.  On Git, this prompts for the name of a
branch to merge from, with completion (based on the branch names known
to the current repository).  With Mercurial, this prompts for argument
to pass to @kbd{hg merge}.  The output from running the merge
command is shown in a separate buffer.

  On a centralized version control system like CVS, @kbd{C-x v m}
prompts for a branch ID, or a pair of revision IDs (@pxref{Switching
Branches}); then it finds the changes from that branch, or the changes
between the two revisions you specified, and merges those changes into
the current VC fileset.  If you just type @kbd{@key{RET}}, Emacs simply
merges any changes that were made on the same branch since you checked
the file out.

@cindex conflicts
@cindex resolving conflicts
  Immediately after performing a merge, only the working tree is
modified, and you can review the changes produced by the merge with
@kbd{C-x v D} and related commands (@pxref{Old Revisions}).  If the
two branches contained overlapping changes, merging produces a
@dfn{conflict}; a warning appears in the output of the merge command,
and @dfn{conflict markers} are inserted into each affected work file,
surrounding the two sets of conflicting changes.  You must then
resolve the conflict by editing the conflicted files.  Once you are
done, the modified files must be committed in the usual way for the
merge to take effect (@pxref{Basic VC Editing}).

@node Creating Branches
@subsubsection Creating New Branches

  On centralized version control systems like CVS, Emacs supports
creating new branches as part of a commit operation.  When committing
a modified VC fileset, type @kbd{C-u C-x v v} (@code{vc-next-action}
with a prefix argument; @pxref{Advanced C-x v v}).  Then Emacs prompts
for a revision ID for the new revision.  You should specify a suitable
branch ID for a branch starting at the current revision.  For example,
if the current revision is 2.5, the branch ID should be 2.5.1, 2.5.2,
and so on, depending on the number of existing branches at that point.

  This procedure will not work for distributed version control systems
like git or Mercurial.  For those systems you should use the prefix
argument to @code{vc-create-tag} (@kbd{C-u C-x v s}) instead.

  To create a new branch at an older revision (one that is no longer
the head of a branch), first select that revision (@pxref{Switching
Branches}).  Your procedure will then differ depending on whether you
are using a locking or merging-based VCS.

  On a locking VCS, you will need to lock the old revision branch with
@kbd{C-x v v}.  You'll be asked to confirm, when you lock the old
revision, that you really mean to create a new branch---if you say no,
you'll be offered a chance to lock the latest revision instead.  On a
merging-based VCS you will skip this step.

  Then make your changes and type @kbd{C-x v v} again to commit a new
revision.  This creates a new branch starting from the selected
revision.

  After the branch is created, subsequent commits create new revisions
on that branch.  To leave the branch, you must explicitly select a
different revision with @kbd{C-u C-x v v}.

@ifnottex
@include vc1-xtra.texi
@end ifnottex

@node Projects
@section Working with Projects
@cindex projects

@cindex project root
  A @dfn{project} is a collection of files used for producing one or
more programs.  Files that belong to a project are typically stored in
a hierarchy of directories; the top-level directory of the hierarchy
is known as the @dfn{project root}.

@cindex project back-end
  Whether a given directory is a root of some project is determined by
the project-specific infrastructure, known as @dfn{project back-end}.
Emacs currently supports two such back-ends: VC (@pxref{Version
Control}), whereby a VCS repository is considered a project; and EDE
(@pxref{EDE}).  This is expected to be extended in the future to
support additional types of projects.

  Which files do or don't belong to a project is also determined by
the project back-end.  For example, the VC back-end doesn't consider
``ignored'' files (@pxref{VC Ignore}) to be part of the project.

@menu
* Project File Commands::   Commands for handling project files.
* Project Buffer Commands:: Commands for handling project buffers.
* Switching Projects::      Switching between projects.
@end menu

@node Project File Commands
@subsection Project Commands That Operate on Files

@table @kbd
@item C-x p f
Visit a file that belongs to the current project
(@code{project-find-file}).
@item C-x p g
Find matches for a regexp in all files that belong to the current
project (@code{project-find-regexp}).
@item M-x project-search
Interactively search for regexp matches in all files that belong to
the current project.
@item C-x p r
Perform query-replace for a regexp in all files that belong to the
current project (@code{project-query-replace-regexp}).
@item C-x p d
Run Dired in the current project's root directory
(@code{project-dired}).
@item C-x p v
Run @code{vc-dir} in the current project's root directory
(@code{project-vc-dir}).
@item C-x p s
Start an inferior shell in the current project's root directory
(@code{project-shell}).
@item C-x p e
Start Eshell in the current project's root directory
(@code{project-eshell}).
@item C-x p c
Run compilation in the current project's root directory
(@code{project-compile}).
@item C-x p !
Run shell command in the current project's root directory
(@code{project-shell-command}).
@item C-x p &
Run shell command asynchronously in the current project's root
directory (@code{project-async-shell-command}).
@end table

  Emacs provides commands for handling project files conveniently.
This subsection describes these commands.

@cindex current project
  All of the commands described here share the notion of the
@dfn{current project}.  The current project is determined by the
@code{default-directory} (@pxref{File Names}) of the buffer that is
the current buffer when the command is invoked.  If that directory
doesn't seem to belong to a recognizable project, these commands
prompt you for the project directory.

@findex project-find-file
  The command @kbd{C-x p f} (@code{project-find-file}) is a convenient
way of visiting files (@pxref{Visiting}) that belong to the current
project.  Unlike @kbd{C-x C-f}, this command doesn't require to type
the full file name of the file to visit, you can type only the file's
base name (i.e., omit the leading directories).  In addition, the
completion candidates considered by the command include only the files
belonging to the current project, and nothing else.  If there's a file
name at point, this command offers that file as the default to visit.

@findex project-find-regexp
  The command @kbd{C-x p g} (@code{project-find-regexp}) is similar to
@code{rgrep} (@pxref{Grep Searching}), but it searches only the files
that belong to the current project.  The command prompts for the
regular expression to search, and pops up an Xref mode buffer with the
search results, where you can select a match using the Xref mode
commands (@pxref{Xref Commands}).  When invoked with a prefix
argument, this command additionally prompts for the base directory
from which to start the search; this allows, for example, to limit the
search only to project files under a certain subdirectory of the
project root.

@findex project-search
  @kbd{M-x project-search} is an interactive variant of
@code{project-find-regexp}.  It prompts for a regular expression to
search in the current project's files, but instead of finding all the
matches and displaying them, it stops when it finds a match and visits
the matched file at the locus of the match, allowing you to edit the
matched file.  To find the rest of the matches, type @w{@kbd{M-x
fileloop-continue @key{RET}}}.

@findex project-query-replace-regexp
  @kbd{C-x p r} (@code{project-query-replace-regexp}) is similar to
@code{project-search}, but it prompts you for whether to replace each
match it finds, like @code{query-replace} does (@pxref{Query
Replace}), and continues to the next match after you respond.  If your
response causes Emacs to exit the query-replace loop, you can later
continue with @w{@kbd{M-x fileloop-continue @key{RET}}}.

@findex project-dired
  The command @kbd{C-x p d} (@code{project-dired}) opens a Dired
buffer (@pxref{Dired}) listing the files in the current project's root
directory.

@findex project-vc-dir
  The command @kbd{C-x p v} (@code{project-vc-dir}) opens a VC
Directory buffer (@pxref{VC Directory Mode}) listing the version
control statuses of the files in a directory tree under the current
project's root directory.

@findex project-shell
  The command @kbd{C-x p s} (@code{project-shell}) starts a shell
session (@pxref{Shell}) in a new buffer with the current project's
root as the working directory.

@findex project-eshell
  The command @kbd{C-x p e} (@code{project-eshell}) starts an Eshell
session in a new buffer with the current project's root as the working
directory.  @xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}.

@findex project-compile
  The command @kbd{C-x p c} (@code{project-compile}) runs compilation
(@pxref{Compilation}) in the current project's root directory.

@findex project-shell-command
  The command @kbd{C-x p !} (@code{project-shell-command}) runs
@code{shell-command} in the current project's root directory.

@findex project-async-shell-command
  The command @kbd{C-x p &} (@code{project-async-shell-command}) runs
@code{async-shell-command} in the current project's root directory.

@node Project Buffer Commands
@subsection Project Commands That Operate on Buffers

@table @kbd
@item C-x p b
Switch to another buffer belonging to the current project
(@code{project-switch-to-buffer}).
@item C-x p k
Kill all live buffers that belong to the current project
(@code{project-kill-buffers}).
@end table

@findex project-switch-to-buffer
  Working on a project could potentially involve having many buffers
visiting files that belong to the project, and also buffers that
belong to the project, but don't visit any files (like the
@file{*compilation*} buffer created by @code{project-compile}).  The
command @kbd{C-x p b} (@code{project-switch-to-buffer}) helps you
switch between buffers that belong to the current project by prompting
for a buffer to switch and considering only the current project's
buffers as candidates for completion.

@findex project-kill-buffers
@vindex project-kill-buffer-conditions
  When you finish working on the project, you may wish to kill all the
buffers that belong to the project, to keep your Emacs session
smaller.  The command @kbd{C-x p k} (@code{project-kill-buffers})
accomplishes that: it kills all the buffers that belong to the current
project that satisfy any of @code{project-kill-buffer-conditions}.

@node Switching Projects
@subsection Switching Projects

@table @kbd
@item C-x p p
Run an Emacs command for another project (@code{project-switch-project}).
@end table

@findex project-switch-project
@vindex project-switch-commands
  Commands that operate on project files (@pxref{Project File
Commands}) will conveniently prompt you for a project directory when
no project is current.  When you are inside some project, but you want
to operate on a different project, use the @kbd{C-x p p} command
(@code{project-switch-project}).  This command prompts you to choose a
directory among known project roots, and then displays the menu of
available commands to operate on the project you choose.  The variable
@code{project-switch-commands} controls which commands are available
in the menu, and which key invokes each command.

@vindex project-list-file
  The variable @code{project-list-file} names the file in which Emacs
records the list of known projects.  It defaults to the file
@file{projects} in @code{user-emacs-directory} (@pxref{Find Init}).

@node Managing project list file
@subsection Managing Projects

@table @kbd
@item M-x project-remove-known-project
Remove a known project from the (@code{project-list-file}).
@end table

@findex project-remove-known-project
  Normally Emacs handle adding and removing projects to the
(@code{project-list-file}) automatically.  Sometimes you still want to
manually edit the available
projects. @kbd{M-x project-remove-known-project} will prompt you for the
available projects, and upon selecting one, it will disappear from the
@code{project-list-file}

@node Change Log
@section Change Logs

@cindex change log
  Many software projects keep a @dfn{change log}.  This is a file,
normally named @file{ChangeLog}, containing a chronological record of
when and how the program was changed.  Sometimes, these files are
automatically generated from the change log entries stored in version
control systems, or are used to generate these change log entries.
Sometimes, there are several change log files, each recording the
changes in one directory or directory tree.

@menu
* Change Log Commands:: Commands for editing change log files.
* Format of ChangeLog:: What the change log file looks like.
@end menu

@node Change Log Commands
@subsection Change Log Commands

@kindex C-x 4 a
@findex add-change-log-entry-other-window
  The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
file for the file you are editing
(@code{add-change-log-entry-other-window}).  If that file is actually
a backup file, it makes an entry appropriate for the file's
parent---that is useful for making log entries for functions that
have been deleted in the current version.

  @kbd{C-x 4 a} visits the change log file and creates a new entry
unless the most recent entry is for today's date and your name.  It
also creates a new item for the current file.  For many languages, it
can even guess the name of the function or other object that was
changed.

@c Not worth it.
@c @vindex change-log-directory-files
To find the change log file, Emacs searches up the directory tree from
the file you are editing.  By default, it stops if it finds a
directory that seems to be the root of a version-control repository.
To change this, customize @code{change-log-directory-files}.

@vindex add-log-keep-changes-together
  When the variable @code{add-log-keep-changes-together} is
non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file,
rather than starting a new item.

You can combine multiple changes of the same nature.  If you don't
enter any text after the initial @kbd{C-x 4 a}, any subsequent
@kbd{C-x 4 a} adds another symbol to the change log entry.

@vindex add-log-always-start-new-record
  If @code{add-log-always-start-new-record} is non-@code{nil},
@kbd{C-x 4 a} always makes a new entry, even if the last entry
was made by you and on the same date.

@vindex change-log-version-info-enabled
@vindex change-log-version-number-regexp-list
@cindex file version in change log entries
  If the value of the variable @code{change-log-version-info-enabled}
is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
change log entry.  It finds the version number by searching the first
ten percent of the file, using regular expressions from the variable
@code{change-log-version-number-regexp-list}.

@cindex Change Log mode
@findex change-log-mode
  The change log file is visited in Change Log mode.  In this major
mode, each bunch of grouped items counts as one paragraph, and each
entry is considered a page.  This facilitates editing the entries.
@kbd{C-j} and auto-fill indent each new line like the previous line;
this is convenient for entering the contents of an entry.

@findex change-log-goto-source
  You can use the command @code{change-log-goto-source} (by default
bound to @kbd{C-c C-c}) to go to the source location of the change log
entry near point, when Change Log mode is on.  Then subsequent
invocations of the @code{next-error} command (by default bound to
@kbd{M-g M-n} and @kbd{C-x `}) will move between entries in the change
log.  You will jump to the actual site in the file that was changed,
not just to the next change log entry.  You can also use
@code{previous-error} to move back through the change log entries.

@findex change-log-merge
  You can use the command @kbd{M-x change-log-merge} to merge other
log files into a buffer in Change Log Mode, preserving the date
ordering of entries.

@vindex add-log-dont-create-changelog-file
  Version control systems are another way to keep track of changes in
your program and keep a change log.  Many projects that use a VCS don't
keep a separate versioned change log file nowadays, so you may wish to
avoid having such a file in the repository.  If the value of
@code{add-log-dont-create-changelog-file} is non-@code{nil}, commands
like @kbd{C-x 4 a} (@code{add-change-log-entry-other-window}) will
record changes in a suitably named temporary buffer instead of a file,
if such a file does not already exist.

Whether you have a change log file or use a temporary buffer for
change logs, you can type @kbd{C-c C-a}
(@code{log-edit-insert-changelog}) in the VC Log buffer to insert the
relevant change log entries, if they exist.  @xref{Log Buffer}.

@node Format of ChangeLog
@subsection Format of ChangeLog

  A change log entry starts with a header line that contains the
current date, your name (taken from the variable
@code{add-log-full-name}), and your email address (taken from the
variable @code{add-log-mailing-address}).  Aside from these header
lines, every line in the change log starts with a space or a tab.  The
bulk of the entry consists of @dfn{items}, each of which starts with a
line starting with whitespace and a star.  Here are two entries, both
dated in May 1993, with two items and one item respectively.

@iftex
@medbreak
@end iftex
@smallexample
1993-05-25  Richard Stallman  <rms@@gnu.org>

        * man.el: Rename symbols 'man-*' to 'Man-*'.
        (manual-entry): Make prompt string clearer.

        * simple.el (blink-matching-paren-distance):
        Change default to 12,000.

1993-05-24  Richard Stallman  <rms@@gnu.org>

        * vc.el (minor-mode-map-alist): Don't use it if it's void.
        (vc-cancel-version): Doc fix.
@end smallexample

  One entry can describe several changes; each change should have its
own item, or its own line in an item.  Normally there should be a
blank line between items.  When items are related (parts of the same
change, in different places), group them by leaving no blank line
between them.

  You should put a copyright notice and permission notice at the
end of the change log file.  Here is an example:

@smallexample
Copyright 1997, 1998 Free Software Foundation, Inc.
Copying and distribution of this file, with or without modification, are
permitted provided the copyright notice and this notice are preserved.
@end smallexample

@noindent
Of course, you should substitute the proper years and copyright holder.

@node Xref
@section Find Identifier References
@cindex xref

@cindex tag
  An @dfn{identifier} is a name of a syntactical subunit of the
program: a function, a subroutine, a method, a class, a data type, a
macro, etc.  In a programming language, each identifier is a symbol in
the language's syntax.  Identifiers are also known as @dfn{tags}.

Program development and maintenance requires capabilities to quickly
find where each identifier was defined and referenced, to rename
identifiers across the entire project, etc.  These capabilities are
also useful for finding references in major modes other than those
defined to support programming languages.  For example, chapters,
sections, appendices, etc.@: of a text or a @TeX{} document can be
treated as subunits as well, and their names can be used as
identifiers.  In this chapter, we use the term ``identifiers'' to
collectively refer to the names of any kind of subunits, in program
source and in other kinds of text alike.

Emacs provides a unified interface to these capabilities, called
@samp{xref}.

@cindex xref backend
To do its job, @code{xref} needs to make use of information and to
employ methods specific to the major mode.  What files to search for
identifiers, how to find references to identifiers, how to complete on
identifiers---all this and more is mode-specific knowledge.
@code{xref} delegates the mode-specific parts of its job to a
@dfn{backend} provided by the mode; it also includes defaults for some
of its commands, for those modes that don't provide their own.

A backend can implement its capabilities in a variety of ways.  Here
are a few examples:

@enumerate a
@item
Some major modes provide built-in means for looking up the language
symbols.  For example, Emacs Lisp symbols can be identified by
searching the package load history, maintained by the Emacs Lisp
interpreter, and by consulting the built-in documentation strings; the
Emacs Lisp mode uses these facilities in its backend to allow finding
definitions of symbols.  (One disadvantage of this kind of backend is
that it only knows about subunits that were loaded into the
interpreter.)

@item
An external program can extract references by scanning the relevant
files, and build a database of these references.  A backend can then
access this database whenever it needs to list or look up references.
The Emacs distribution includes @command{etags}, a command for tagging
identifier definitions in programs, which supports many programming
languages and other major modes, such as HTML, by extracting
references into @dfn{tags tables}.  @xref{Create Tags Table}.  Major
modes for languages supported by @command{etags} can use tags tables
as basis for their backend.  (One disadvantage of this kind of backend
is that tags tables need to be kept reasonably up to date, by
rebuilding them from time to time.)
@end enumerate

@menu
* Find Identifiers::    Commands to find where an identifier is defined
                          or referenced, to list identifiers, etc.
* Tags Tables::         Tags table records which file defines a symbol.
* Select Tags Table::   How to visit a specific tags table.
@end menu

@node Find Identifiers
@subsection Find Identifiers

  This subsection describes the commands that find references to
identifiers and perform various queries about identifiers.  Each such
reference could @emph{define} an identifier, e.g., provide the
implementation of a program subunit or the text of a document section;
or it could @emph{use} the identifier, e.g., call a function or a
method, assign a value to a variable, mention a chapter in a
cross-reference, etc.

@menu
* Looking Up Identifiers:: Commands to find the definition of an identifier.
* Xref Commands::          Commands in the @file{*xref*} buffer.
* Identifier Search::      Searching and replacing identifiers.
* List Identifiers::       Listing identifiers and completing on them.
@end menu

@node Looking Up Identifiers
@subsubsection Looking Up Identifiers
@cindex find definition of symbols
@cindex identifier, finding definition of
@cindex find references to symbols

  The most important thing that @code{xref} enables you to do is to find
the definition of a specific identifier.

@table @kbd
@item M-.@:
Find definitions of an identifier (@code{xref-find-definitions}).
@item C-M-. @var{pattern} @key{RET}
Find all identifiers whose name matches @var{pattern}
(@code{xref-find-apropos}).
@item C-x 4 .@: @key{RET}
Find definitions of identifier, but display it in another window
(@code{xref-find-definitions-other-window}).
@item C-x 5 .@: @key{RET}
Find definition of identifier, and display it in a new frame
(@code{xref-find-definitions-other-frame}).
@item M-x xref-find-definitions-at-mouse
Find definition of identifier at mouse click.
@item M-,
Go back to where you previously invoked @kbd{M-.} and friends
(@code{xref-pop-marker-stack}).
@item M-x xref-etags-mode
Switch @code{xref} to use the @code{etags} backend.
@end table

@kindex M-.
@findex xref-find-definitions
@vindex xref-prompt-for-identifier
  @kbd{M-.}@: (@code{xref-find-definitions}) shows the definitions of
the identifier at point.  With a prefix argument, or if there's no
identifier at point, it prompts for the identifier.  (If you want it
to always prompt, customize @code{xref-prompt-for-identifier} to
@code{t}.)

If the specified identifier has only one definition, the command jumps
to it.  If the identifier has more than one possible definition (e.g.,
in an object-oriented language, or if there's a function and a
variable by the same name), the command shows the candidate
definitions in the @file{*xref*} buffer, together with the files in
which these definitions are found.  Selecting one of these candidates
by typing @kbd{@key{RET}} or clicking @kbd{mouse-2} will pop a buffer
showing the corresponding definition.

  When entering the identifier argument to @kbd{M-.}, the usual
minibuffer completion commands can be used (@pxref{Completion}), with
the known identifier names as completion candidates.

@kindex C-x 4 .
@findex xref-find-definitions-other-window
@kindex C-x 5 .
@findex xref-find-definitions-other-frame
  Like most commands that can switch buffers,
@code{xref-find-definitions} has a variant that displays the new
buffer in another window, and one that makes a new frame for it.  The
former is @w{@kbd{C-x 4 .}}
(@code{xref-find-definitions-other-window}), and the latter is
@w{@kbd{C-x 5 .}}  (@code{xref-find-definitions-other-frame}).

  The command @code{xref-find-definitions-at-mouse} works like
@code{xref-find-definitions}, but it looks for the identifier name at
or around the place of a mouse event.  This command is intended to be
bound to a mouse event, such as @kbd{C-M-mouse-1}, for example.

@findex xref-find-apropos
@kindex C-M-.
  The command @kbd{C-M-.} (@code{xref-find-apropos}) finds the
definitions of one or more identifiers that match a specified regular
expression.  It is just like @kbd{M-.} except that it does regexp
matching of identifiers instead of matching symbol names as fixed
strings.

  When any of the above commands finds more than one definition, it
presents the @file{*xref*} buffer showing the definition candidates.
In that buffer, you have several specialized commands, described in
@ref{Xref Commands}.

@kindex M-,
@findex xref-pop-marker-stack
@vindex xref-marker-ring-length
  To go back to places @emph{from where} you found the definition,
use @kbd{M-,} (@code{xref-pop-marker-stack}).  It jumps back to the
point of the last invocation of @kbd{M-.}.  Thus you can find and
examine the definition of something with @kbd{M-.} and then return to
where you were with @kbd{M-,}.  @kbd{M-,} allows you to retrace your
steps to a depth determined by the variable
@code{xref-marker-ring-length}, which defaults to 16.

@findex xref-etags-mode
  Some major modes install @code{xref} support facilities that might
sometimes fail to find certain identifiers.  For example, in Emacs
Lisp mode (@pxref{Lisp Eval}) @kbd{M-.} will by default find only
functions and variables from Lisp packages which are loaded into the
current Emacs session or are auto-loaded (@pxref{Autoload,,, elisp,
The Emacs Lisp Reference Manual}).  If @kbd{M-.} fails to find some
identifiers, you can try forcing @code{xref} to use the @code{etags}
backend (@pxref{Xref}).  To this end, turn on the Xref Etags minor
mode with @w{@kbd{M-x xref-etags-mode}}, then invoke @kbd{M-.} again.
(For this to work, be sure to run @command{etags} to create the tags
table in the directory tree of the source files, see @ref{Create Tags
Table}.)

@node Xref Commands
@subsubsection Commands Available in the @file{*xref*} Buffer
@cindex commands in @file{*xref*} buffers
@cindex XREF mode

  The following commands are provided in the @file{*xref*} buffer by
the special XREF mode:

@table @kbd
@item @key{RET}
@itemx mouse-2
Display the reference on the current line.

@item n
@itemx .
@findex xref-next-line
Move to the next reference and display it in the other window
(@code{xref-next-line}).

@item N
@findex xref-next-group
Move to the first reference of the next reference group and display it
in the other window (@code{xref-next-group}).

@item p
@itemx ,
@findex xref-prev-line
Move to the previous reference and display it in the other window
(@code{xref-prev-line}).

@item P
@findex xref-prev-group
Move to the first reference of the previous reference group and
display it in the other window (@code{xref-prev-group}).

@item C-o
@findex xref-show-location-at-point
Display the reference on the current line in the other window
(@code{xref-show-location-at-point}).

@item @key{TAB}
@findex xref-quit-and-goto-xref
Display the reference on the current line and bury the @file{*xref*}
buffer (@code{xref-quit-and-goto-xref}).

@item r @var{pattern} @key{RET} @var{replacement} @key{RET}
Perform interactive query-replace on references that match
@var{pattern} (@code{xref-query-replace-in-results}), replacing
the match with @var{replacement}.  @xref{Identifier Search}.

@item g
@findex xref-revert-buffer
Refresh the contents of the @file{*xref*} buffer
(@code{xref-revert-buffer}.

@findex xref-quit
@item q
Quit the window showing the @file{*xref*} buffer (@code{xref-quit}).
@end table

In addition, the usual navigation commands, such as the arrow keys,
@kbd{C-n}, and @kbd{C-p} are available for moving around the buffer
without displaying the references.

@node Identifier Search
@subsubsection Searching and Replacing with Identifiers
@cindex search and replace in multiple source files
@cindex multiple source file search and replace

  The commands in this section perform various search and replace
operations either on identifiers themselves or on files that reference
them.

@table @kbd
@item M-?
Find all the references for the identifier at point.

@item M-x xref-query-replace-in-results @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
Interactively replace @var{regexp} with @var{replacement} in the names
of all the identifiers shown in the @file{*xref*} buffer.

@item M-x tags-search @key{RET} @var{regexp} @key{RET}
Search for @var{regexp} through the files in the selected tags
table.

@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
Perform a @code{query-replace-regexp} on each file in the selected tags table.

@item M-x fileloop-continue
Restart one of the last 2 commands above, from the current location of point.
@end table

@kindex M-?
@findex xref-find-references
  @kbd{M-?} finds all the references for the identifier at point,
prompting for the identifier as needed, with completion.  Depending on
the current backend (@pxref{Xref}), the command may prompt even if it
finds a valid identifier at point.  When invoked with a prefix
argument, it always prompts for the identifier.  (If you want it to
prompt always, customize the value of the variable
@code{xref-prompt-for-identifier} to @code{t}; or set it to @code{nil}
to prompt only if there's no usable identifier at point.)  The command
then presents the @file{*xref*} buffer with all the references to the
identifier, showing the file name and the line where the identifier is
referenced.  The XREF mode commands are available in this buffer, see
@ref{Xref Commands}.

@findex xref-query-replace-in-results
  @kbd{M-x xref-query-replace-in-results} reads a regexp to match identifier
names and a replacement string, just like ordinary @kbd{M-x
query-replace-regexp}.  It then performs the specified replacement in
the names of the matching identifiers in all the places in all the
files where these identifiers are referenced.  This is useful when you
rename your identifiers as part of refactoring.  This command should
be invoked in the @file{*xref*} buffer generated by @kbd{M-?}.

@findex tags-search
  @kbd{M-x tags-search} reads a regexp using the minibuffer, then
searches for matches in all the files in the selected tags table, one
file at a time.  It displays the name of the file being searched so
you can follow its progress.  As soon as it finds an occurrence,
@code{tags-search} returns.  This command requires tags tables to be
available (@pxref{Tags Tables}).

@findex fileloop-continue
  Having found one match with @code{tags-search}, you probably want to
find all the rest.  @kbd{M-x fileloop-continue} resumes the
@code{tags-search}, finding one more match.  This searches the rest of
the current buffer, followed by the remaining files of the tags table.

@findex tags-query-replace
  @kbd{M-x tags-query-replace} performs a single
@code{query-replace-regexp} through all the files in the tags table.  It
reads a regexp to search for and a string to replace with, just like
ordinary @kbd{M-x query-replace-regexp}.  It searches much like @kbd{M-x
tags-search}, but repeatedly, processing matches according to your
input.  @xref{Query Replace}, for more information on query replace.

@vindex tags-case-fold-search
@cindex case-sensitivity and tags search
  You can control the case-sensitivity of tags search commands by
customizing the value of the variable @code{tags-case-fold-search}.  The
default is to use the same setting as the value of
@code{case-fold-search} (@pxref{Lax Search}).

  It is possible to get through all the files in the tags table with a
single invocation of @kbd{M-x tags-query-replace}.  But often it is
useful to exit temporarily, which you can do with any input event that
has no special query replace meaning.  You can resume the query
replace subsequently by typing @kbd{M-x fileloop-continue}; this
command resumes the last tags search or replace command that you did.
For instance, to skip the rest of the current file, you can type
@w{@kbd{M-> M-x fileloop-continue}}.

  Note that the commands described above carry out much broader
searches than the @code{xref-find-definitions} family.  The
@code{xref-find-definitions} commands search only for definitions of
identifiers that match your string or regexp.  The commands
@code{xref-find-references}, @code{tags-search}, and
@code{tags-query-replace} find every occurrence of the identifier or
regexp, as ordinary search commands and replace commands do in the
current buffer.

  As an alternative to @code{xref-find-references} and
@code{tags-search}, you can run @command{grep} as a subprocess and
have Emacs show you the matching lines one by one.  @xref{Grep
Searching}.

@node List Identifiers
@subsubsection Identifier Inquiries

@table @kbd
@item C-M-i
@itemx M-@key{TAB}
Perform completion on the text around point, possibly using the
selected tags table if one is loaded (@code{completion-at-point}).

@item M-x xref-find-apropos @key{RET} @var{regexp} @key{RET}
Display a list of all known identifiers matching @var{regexp}.

@item M-x list-tags @key{RET} @var{file} @key{RET}
Display a list of the identifiers defined in the program file
@var{file}.

@item M-x tags-next-file
Visit files recorded in the selected tags table.
@end table

  In most programming language modes, you can type @kbd{C-M-i} or
@kbd{M-@key{TAB}} (@code{completion-at-point}) to complete the symbol
at point.  Some modes provide specialized completion for this command
tailored to the mode; for those that don't, if there is a tags table
loaded, this command can use it to generate completion candidates.
@xref{Symbol Completion}.

@findex list-tags
  @kbd{M-x list-tags} reads the name of one of the files covered by
the selected tags table, and displays a list of tags defined in that
file.  Do not include a directory as part of the file name unless the
file name recorded in the tags table includes a directory.  This
command works only with the etags backend, and requires a tags table
for the project to be available.  @xref{Tags Tables}.  If used
interactively, the default tag is file name of the current buffer if
used interactively.

@c Sadly, the new-and-improved Xref feature doesn't provide anything
@c close to the described below features of the now-obsoleted
@c tags-apropos.  I'm leaving this here to encourage enhancements to
@c xref.el.
@ignore
@findex tags-apropos
@vindex tags-apropos-verbose
@vindex tags-tag-face
@vindex tags-apropos-additional-actions
  @kbd{M-x tags-apropos} is like @code{apropos} for tags
(@pxref{Apropos}).  It displays a list of tags in the selected tags
table whose entries match @var{regexp}.  If the variable
@code{tags-apropos-verbose} is non-@code{nil}, it displays the names
of the tags files together with the tag names.  You can customize the
appearance of the output by setting the variable @code{tags-tag-face}
to a face.  You can display additional output by customizing the
variable @code{tags-apropos-additional-actions}; see its documentation
for details.
@end ignore

@findex tags-next-file
  @kbd{M-x tags-next-file} visits files covered by the selected tags table.
The first time it is called, it visits the first file covered by the
table.  Each subsequent call visits the next covered file, unless a
prefix argument is supplied, in which case it returns to the first
file.  This command requires a tags table to be selected.

@node Tags Tables
@subsection Tags Tables
@cindex tags and tag tables

  A @dfn{tags table} records the tags@footnote{
A @dfn{tag} is a synonym for identifier reference.  Commands and
features based on the @code{etags} package traditionally use ``tag''
with this meaning, and this subsection follows that tradition.
} extracted by scanning the source code of a certain program or a
certain document.  Tags extracted from generated files reference the
original files, rather than the generated files that were scanned
during tag extraction.  Examples of generated files include C files
generated from Cweb source files, from a Yacc parser, or from Lex
scanner definitions; @file{.i} preprocessed C files; and Fortran files
produced by preprocessing @file{.fpp} source files.

@cindex etags
  To produce a tags table, you run the @command{etags} shell command
on a document or the source code file.  The @samp{etags} program
writes the tags to a @dfn{tags table file}, or @dfn{tags file} in
short.  The conventional name for a tags file is @file{TAGS}@.
@xref{Create Tags Table}.  (It is also possible to create a tags table
by using one of the commands from other packages that can produce such
tables in the same format.)

  Emacs uses the tags tables via the @code{etags} package as one of
the supported backends for @code{xref}.  Because tags tables are
produced by the @command{etags} command that is part of an Emacs
distribution, we describe tags tables in more detail here.

@cindex C++ class browser, tags
@cindex tags, C++
@cindex class browser, C++
@cindex Ebrowse
  The Ebrowse facility is similar to @command{etags} but specifically
tailored for C++.  @xref{Top,, Ebrowse, ebrowse, Ebrowse User's
Manual}.  The Semantic package provides another way to generate and
use tags, separate from the @command{etags} facility.
@xref{Semantic}.

@menu
* Tag Syntax::          Tag syntax for various types of code and text files.
* Create Tags Table::   Creating a tags table with @command{etags}.
* Etags Regexps::       Create arbitrary tags using regular expressions.
@end menu

@node Tag Syntax
@subsubsection Source File Tag Syntax

  Here is how tag syntax is defined for the most popular languages:

@itemize @bullet
@item
In C code, any C function or typedef is a tag, and so are definitions of
@code{struct}, @code{union} and @code{enum}.
@code{#define} macro definitions, @code{#undef} and @code{enum}
constants are also
tags, unless you specify @samp{--no-defines} when making the tags table.
Similarly, global variables are tags, unless you specify
@samp{--no-globals}, and so are struct members, unless you specify
@samp{--no-members}.  Use of @samp{--no-globals}, @samp{--no-defines}
and @samp{--no-members} can make the tags table file much smaller.

You can tag function declarations and external variables in addition
to function definitions by giving the @samp{--declarations} option to
@command{etags}.

@item
In C++ code, in addition to all the tag constructs of C code, member
functions are also recognized; member variables are also recognized,
unless you use the @samp{--no-members} option.  @code{operator}
definitions have tag names like @samp{operator+}.  If you specify the
@samp{--class-qualify} option, tags for variables and functions in
classes are named @samp{@var{class}::@var{variable}} and
@samp{@var{class}::@var{function}}.  By default, class methods and
members are not class-qualified, which allows to identify their names in
the sources more accurately.

@item
In Java code, tags include all the constructs recognized in C++, plus
the @code{interface}, @code{extends} and @code{implements} constructs.
Tags for variables and functions in classes are named
@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.

@item
In @LaTeX{} documents, the arguments for @code{\chapter},
@code{\section}, @code{\subsection}, @code{\subsubsection},
@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},
@code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},
@code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
@code{\newenvironment} and @code{\renewenvironment} are tags.

Other commands can make tags as well, if you specify them in the
environment variable @env{TEXTAGS} before invoking @command{etags}.  The
value of this environment variable should be a colon-separated list of
command names.  For example,

@example
TEXTAGS="mycommand:myothercommand"
export TEXTAGS
@end example

@noindent
specifies (using Bourne shell syntax) that the commands
@samp{\mycommand} and @samp{\myothercommand} also define tags.

@item
In Lisp code, any function defined with @code{defun}, any variable
defined with @code{defvar} or @code{defconst}, and in general the
first argument of any expression that starts with @samp{(def} in
column zero is a tag.  As an exception, expressions of the form
@code{(defvar @var{foo})} are treated as declarations, and are only
tagged if the @samp{--declarations} option is given.

@item
In Scheme code, tags include anything defined with @code{def} or with a
construct whose name starts with @samp{def}.  They also include variables
set with @code{set!} at top level in the file.
@end itemize

  Several other languages are also supported:

@itemize @bullet

@item
In Ada code, functions, procedures, packages, tasks and types are
tags.  Use the @samp{--packages-only} option to create tags for
packages only.

In Ada, the same name can be used for different kinds of entity
(e.g., for a procedure and for a function).  Also, for things like
packages, procedures and functions, there is the spec (i.e., the
interface) and the body (i.e., the implementation).  To make it
easier to pick the definition you want, Ada tag names have suffixes
indicating the type of entity:

@table @samp
@item /b
package body.
@item /f
function.
@item /k
task.
@item /p
procedure.
@item /s
package spec.
@item /t
type.
@end table

  Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
directly to the body of the package @code{bidule}, while @kbd{M-x
find-tag @key{RET} bidule @key{RET}} will just search for any tag
@code{bidule}.

@item
In assembler code, labels appearing at the start of a line,
followed by a colon, are tags.

@item
In Bison or Yacc input files, each rule defines as a tag the nonterminal
it constructs.  The portions of the file that contain C code are parsed
as C code.

@item
In Cobol code, tags are paragraph names; that is, any word starting in
column 8 and followed by a period.

@item
In Erlang code, the tags are the functions, records and macros defined
in the file.

@item
In Fortran code, functions, subroutines and block data are tags.

@item
In Go code, packages, functions, and types are tags.

@item
In HTML input files, the tags are the @code{title} and the @code{h1},
@code{h2}, @code{h3} headers.  Also, tags are @code{name=} in anchors
and all occurrences of @code{id=}.

@item
In Lua input files, all functions are tags.

@item
In makefiles, targets are tags; additionally, variables are tags
unless you specify @samp{--no-globals}.

@item
In Objective C code, tags include Objective C definitions for classes,
class categories, methods and protocols.  Tags for variables and
functions in classes are named @samp{@var{class}::@var{variable}} and
@samp{@var{class}::@var{function}}.

@item
In Pascal code, the tags are the functions and procedures defined in
the file.

@item
In Perl code, the tags are the packages, subroutines and variables
defined by the @code{package}, @code{sub}, @code{use constant},
@code{my}, and @code{local} keywords.  Use @samp{--globals} if you
want to tag global variables.  Tags for subroutines are named
@samp{@var{package}::@var{sub}}.  The name for subroutines defined in
the default package is @samp{main::@var{sub}}.

@item
In PHP code, tags are functions, classes and defines.  Vars are tags
too, unless you use the @samp{--no-members} option.

@item
In PostScript code, the tags are the functions.

@item
In Prolog code, tags are predicates and rules at the beginning of
line.

@item
In Python code, @code{def} or @code{class} at the beginning of a line
generate a tag.

@item
In Ruby code, @code{def} or @code{class} or @code{module} at the
beginning of a line generate a tag.  Constants also generate tags.
@end itemize

  You can also generate tags based on regexp matching (@pxref{Etags
Regexps}) to handle other formats and languages.

@node Create Tags Table
@subsubsection Creating Tags Tables
@cindex @command{etags} program

  The @command{etags} program is used to create a tags table file.  It knows
the syntax of several languages, as described in
@iftex
the previous section.
@end iftex
@ifnottex
@ref{Tag Syntax}.
@end ifnottex
Here is how to run @command{etags}:

@example
etags @var{inputfiles}@dots{}
@end example

@noindent
The @command{etags} program reads the specified files, and writes a tags
table named @file{TAGS} in the current working directory.  You can
optionally specify a different file name for the tags table by using the
@samp{--output=@var{file}} option; specifying @file{-} as a file name
prints the tags table to standard output.  You can also append the
newly created tags table to an existing file by using the @samp{--append}
option.

  If the specified files don't exist, @command{etags} looks for
compressed versions of them and uncompresses them to read them.  Under
MS-DOS, @command{etags} also looks for file names like @file{mycode.cgz}
if it is given @samp{mycode.c} on the command line and @file{mycode.c}
does not exist.

  If the tags table becomes outdated due to changes in the files
described in it, you can update it by running the @command{etags}
program again.  If the tags table does not record a tag, or records it
for the wrong file, then Emacs will not be able to find that
definition until you update the tags table.  But if the position
recorded in the tags table becomes a little bit wrong (due to other
editing), Emacs will still be able to find the right position, with a
slight delay.

   Thus, there is no need to update the tags table after each edit.
You should update a tags table when you define new tags that you want
to have listed, or when you move tag definitions from one file to
another, or when changes become substantial.

  You can make a tags table @dfn{include} another tags table, by
passing the @samp{--include=@var{file}} option to @command{etags}.  It
then covers all the files covered by the included tags file, as well
as its own.

  If you specify the source files with relative file names when you run
@command{etags}, the tags file will contain file names relative to the
directory where the tags file was initially written.  This way, you can
move an entire directory tree containing both the tags file and the
source files, and the tags file will still refer correctly to the source
files.  If the tags file is @file{-} or is in the @file{/dev} directory,
however, the file names are
made relative to the current working directory.  This is useful, for
example, when writing the tags to the standard output.

  When using a relative file name, it should not be a symbolic link
pointing to a tags file in a different directory, because this would
generally render the file names invalid.

  If you specify absolute file names as arguments to @command{etags}, then
the tags file will contain absolute file names.  This way, the tags file
will still refer to the same files even if you move it, as long as the
source files remain in the same place.  Absolute file names start with
@samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.

   When you want to make a tags table from a great number of files,
you may have problems listing them on the command line, because some
systems have a limit on its length.  You can circumvent this limit by
telling @command{etags} to read the file names from its standard
input, by typing a dash in place of the file names, like this:

@smallexample
find . -name "*.[chCH]" -print | etags -
@end smallexample

  @command{etags} recognizes the language used in an input file based on
its file name and contents.  It first tries to match the file's name and
extension to the ones commonly used with certain languages.  Some
languages have interpreters with known names (e.g., @command{perl} for
Perl or @command{pl} for Prolog), so @command{etags} next looks for an
interpreter specification of the form @samp{#!@var{interp}} on the first
line of an input file, and matches that against known interpreters.  If
none of that works, or if you want to override the automatic detection of
the language, you can specify the language explicitly with the
@samp{--language=@var{name}} option.  You can intermix these options with
file names; each one applies to the file names that follow it.  Specify
@samp{--language=auto} to tell @command{etags} to resume guessing the
language from the file names and file contents.  Specify
@samp{--language=none} to turn off language-specific processing entirely;
then @command{etags} recognizes tags by regexp matching alone
(@pxref{Etags Regexps}).  This comes in handy when an input file uses a
language not yet supported by @command{etags}, and you want to avoid
having @command{etags} fall back on Fortran and C as the default
languages.

  The option @samp{--parse-stdin=@var{file}} is mostly useful when
calling @command{etags} from programs.  It can be used (only once) in
place of a file name on the command line.  @command{etags} will read from
standard input and mark the produced tags as belonging to the file
@var{file}.

  @samp{etags --help} outputs the list of the languages @command{etags}
knows, and the file name rules for guessing the language.  It also prints
a list of all the available @command{etags} options, together with a short
explanation.  If followed by one or more @samp{--language=@var{lang}}
options, it outputs detailed information about how tags are generated for
@var{lang}.

@node Etags Regexps
@subsubsection Etags Regexps

  The @samp{--regex} option to @command{etags} allows tags to be
recognized by regular expression matching.  You can intermix this
option with file names; each one applies to the source files that
follow it.  If you specify multiple @samp{--regex} options, all of
them are used in parallel.  The syntax is:

@smallexample
--regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
@end smallexample

@noindent
The essential part of the option value is @var{tagregexp}, the regexp
for matching tags.  It is always used anchored, that is, it only
matches at the beginning of a line.  If you want to allow indented
tags, use a regexp that matches initial whitespace; start it with
@samp{[ \t]*}.

  In these regular expressions, @samp{\} quotes the next character,
and all the C character escape sequences are supported: @samp{\a} for
bell, @samp{\b} for back space, @samp{\e} for escape, @samp{\f} for
formfeed, @samp{\n} for newline, @samp{\r} for carriage return,
@samp{\t} for tab, and @samp{\v} for vertical tab.  In addition,
@samp{\d} stands for the @code{DEL} character.

  Ideally, @var{tagregexp} should not match more characters than are
needed to recognize what you want to tag.  If the syntax requires you
to write @var{tagregexp} so it matches more characters beyond the tag
itself, you should add a @var{nameregexp}, to pick out just the tag.
This will enable Emacs to find tags more accurately and to do
completion on tag names more reliably.  In @var{nameregexp}, it is
frequently convenient to use ``back references'' (@pxref{Regexp
Backslash}) to parenthesized groupings @w{@samp{\( @dots{} \)}} in
@var{tagregexp}.  For example, @samp{\1} refers to the first such
parenthesized grouping.  You can find some examples of this below.

  The @var{modifiers} are a sequence of zero or more characters that
modify the way @command{etags} does the matching.  A regexp with no
modifiers is applied sequentially to each line of the input file, in a
case-sensitive way.  The modifiers and their meanings are:

@table @samp
@item i
Ignore case when matching this regexp.
@item m
Match this regular expression against the whole file, so that
multi-line matches are possible.
@item s
Match this regular expression against the whole file, and allow
@samp{.} in @var{tagregexp} to match newlines.
@end table

  The @samp{-R} option cancels all the regexps defined by preceding
@samp{--regex} options.  It too applies to the file names following
it.  Here's an example:

@smallexample
etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
    bar.ber -R --lang=lisp los.er
@end smallexample

@noindent
Here @command{etags} chooses the parsing language for @file{voo.doo} and
@file{bar.ber} according to their contents.  @command{etags} also uses
@var{reg1} to recognize additional tags in @file{voo.doo}, and both
@var{reg1} and @var{reg2} to recognize additional tags in
@file{bar.ber}.  @var{reg1} is checked against each line of
@file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while
@var{reg2} is checked against the whole @file{bar.ber} file,
permitting multi-line matches, in a case-sensitive way.  @command{etags}
uses only the Lisp tags rules, with no user-specified regexp matching,
to recognize tags in @file{los.er}.

  You can restrict a @samp{--regex} option to match only files of a
given language by using the optional prefix @var{@{language@}}.
(@samp{etags --help} prints the list of languages recognized by
@command{etags}.)  This is particularly useful when storing many
predefined regular expressions for @command{etags} in a file.  The
following example tags the @code{DEFVAR} macros in the Emacs source
files, for the C language only:

@smallexample
--regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/'
@end smallexample

@noindent
When you have complex regular expressions, you can store the list of
them in a file.  The following option syntax instructs @command{etags} to
read two files of regular expressions.  The regular expressions
contained in the second file are matched without regard to case.

@smallexample
--regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file}
@end smallexample

@noindent
A regex file for @command{etags} contains one regular expression per
line.  Empty lines, and lines beginning with space or tab are ignored.
When the first character in a line is @samp{@@}, @command{etags} assumes
that the rest of the line is the name of another file of regular
expressions; thus, one such file can include another file.  All the
other lines are taken to be regular expressions.  If the first
non-whitespace text on the line is @samp{--}, that line is a comment.

  For example, we can create a file called @samp{emacs.tags} with the
following contents:

@smallexample
        -- This is for GNU Emacs C source files
@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
@end smallexample

@noindent
and then use it like this:

@smallexample
etags --regex=@@emacs.tags *.[ch] */*.[ch]
@end smallexample

  Here are some more examples.  The regexps are quoted to protect them
from shell interpretation.

@itemize @bullet

@item
Tag Octave files:

@smallexample
etags --language=none \
      --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
      --regex='/###key \(.*\)/\1/' \
      --regex='/[ \t]*global[ \t].*/' \
      *.m
@end smallexample

@noindent
Note that tags are not generated for scripts, so that you have to add
a line by yourself of the form @samp{###key @var{scriptname}} if you
want to jump to it.

@item
Tag Tcl files:

@smallexample
etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
@end smallexample

@item
Tag VHDL files:

@smallexample
etags --language=none \
  --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
  --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
  \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
@end smallexample
@end itemize

@node Select Tags Table
@subsection Selecting a Tags Table

@findex visit-tags-table
  Emacs has at any time at most one @dfn{selected} tags table.  All
the commands for working with tags tables use the selected one.  To
select a tags table, type @kbd{M-x visit-tags-table}, which reads the
tags table file name as an argument, with @file{TAGS} defaulting to
the first directory that contains a file named @file{TAGS} encountered
when recursively searching upward from the default directory.

@vindex tags-file-name
  Emacs does not actually read in the tags table contents until you
try to use them; all @code{visit-tags-table} does is store the file
name in the variable @code{tags-file-name}, and not much more.  The
variable's initial value is @code{nil}; that value tells all the
commands for working with tags tables that they must ask for a tags
table file name to use.

  Using @code{visit-tags-table} when a tags table is already loaded
gives you a choice: you can add the new tags table to the current list
of tags tables, or start a new list.  The tags commands use all the tags
tables in the current list.  If you start a new list, the new tags table
is used @emph{instead} of others.  If you add the new table to the
current list, it is used @emph{as well as} the others.

@vindex tags-table-list
  You can specify a precise list of tags tables by setting the variable
@code{tags-table-list} to a list of strings, like this:

@c keep this on two lines for formatting in smallbook
@example
@group
(setq tags-table-list
      '("~/.emacs.d" "/usr/local/lib/emacs/src"))
@end group
@end example

@noindent
This tells the tags commands to look at the @file{TAGS} files in your
@file{~/.emacs.d} directory and in the @file{/usr/local/lib/emacs/src}
directory.  The order depends on which file you are in and which tags
table mentions that file.

  Do not set both @code{tags-file-name} and @code{tags-table-list}.

@node EDE
@section Emacs Development Environment
@cindex EDE (Emacs Development Environment)
@cindex Emacs Development Environment
@cindex Integrated development environment

EDE (@dfn{Emacs Development Environment}) is a package that simplifies
the task of creating, building, and debugging large programs with
Emacs.  It provides some of the features of an IDE, or @dfn{Integrated
Development Environment}, in Emacs.

This section provides a brief description of EDE usage.
@ifnottex
For full details, see @ref{Top, EDE,, ede, Emacs Development Environment}.
@end ifnottex
@iftex
For full details on Ede, type @kbd{C-h i} and then select the EDE
manual.
@end iftex

  EDE is implemented as a global minor mode (@pxref{Minor Modes}).  To
enable it, type @kbd{M-x global-ede-mode} or click on the
@samp{Project Support (EDE)} item in the @samp{Tools} menu.  You can
also enable EDE each time you start Emacs, by adding the following
line to your initialization file:

@smallexample
(global-ede-mode t)
@end smallexample

@noindent
Activating EDE adds a menu named @samp{Development} to the menu bar.
Many EDE commands, including the ones described below, can be invoked
from this menu.

  EDE organizes files into @dfn{projects}, which correspond to
directory trees.  The @dfn{project root} is the topmost directory of a
project.  To define a new project, visit a file in the desired project
root and type @kbd{M-x ede-new}.  This command prompts for a
@dfn{project type}, which refers to the underlying method that EDE
will use to manage the project (@pxref{Creating a project, EDE,, ede,
Emacs Development Environment}).  The most common project types are
@samp{Make}, which uses Makefiles, and @samp{Automake}, which uses GNU
Automake (@pxref{Top, Automake,, automake, Automake}).  In both cases,
EDE also creates a file named @file{Project.ede}, which stores
information about the project.

  A project may contain one or more @dfn{targets}.  A target can be an
object file, executable program, or some other type of file, which is
built from one or more of the files in the project.

  To add a new @dfn{target} to a project, type @kbd{C-c . t}
(@code{M-x ede-new-target}).  This command also asks if you wish to
add the current file to that target, which means that the target
is to be built from that file.  After you have defined a target, you
can add more files to it by typing @kbd{C-c . a}
(@code{ede-add-file}).

  To build a target, type @kbd{C-c . c} (@code{ede-compile-target}).
To build all the targets in the project, type @kbd{C-c . C}
(@code{ede-compile-project}).  EDE uses the file types to guess how
the target should be built.

@ifnottex
@include emerge-xtra.texi
@end ifnottex