summaryrefslogtreecommitdiffstats
path: root/contrib/cvs/FAQ
blob: 7a1b4e8c128d1365f50ee99a11d8089dd9d588b2 (plain)
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
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
3916
3917
3918
3919
3920
3921
3922
3923
3924
3925
3926
3927
3928
3929
3930
3931
3932
3933
3934
3935
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
3951
3952
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975
3976
3977
3978
3979
3980
3981
3982
3983
3984
3985
3986
3987
3988
3989
3990
3991
3992
3993
3994
3995
3996
3997
3998
3999
4000
4001
4002
4003
4004
4005
4006
4007
4008
4009
4010
4011
4012
4013
4014
4015
4016
4017
4018
4019
4020
4021
4022
4023
4024
4025
4026
4027
4028
4029
4030
4031
4032
4033
4034
4035
4036
4037
4038
4039
4040
4041
4042
4043
4044
4045
4046
4047
4048
4049
4050
4051
4052
4053
4054
4055
4056
4057
4058
4059
4060
4061
4062
4063
4064
4065
4066
4067
4068
4069
4070
4071
4072
4073
4074
4075
4076
4077
4078
4079
4080
4081
4082
4083
4084
4085
4086
4087
4088
4089
4090
4091
4092
4093
4094
4095
4096
4097
4098
4099
4100
4101
4102
4103
4104
4105
4106
4107
4108
4109
4110
4111
4112
4113
4114
4115
4116
4117
4118
4119
4120
4121
4122
4123
4124
4125
4126
4127
4128
4129
4130
4131
4132
4133
4134
4135
4136
4137
4138
4139
4140
4141
4142
4143
4144
4145
4146
4147
4148
4149
4150
4151
4152
4153
4154
4155
4156
4157
4158
4159
4160
4161
4162
4163
4164
4165
4166
4167
4168
4169
4170
4171
4172
4173
4174
4175
4176
4177
4178
4179
4180
4181
4182
4183
4184
4185
4186
4187
4188
4189
4190
4191
4192
4193
4194
4195
4196
4197
4198
4199
4200
4201
4202
4203
4204
4205
4206
4207
4208
4209
4210
4211
4212
4213
4214
4215
4216
4217
4218
4219
4220
4221
4222
4223
4224
4225
4226
4227
4228
4229
4230
4231
4232
4233
4234
4235
4236
4237
4238
4239
4240
4241
4242
4243
4244
4245
4246
4247
4248
4249
4250
4251
4252
4253
4254
4255
4256
4257
4258
4259
4260
4261
4262
4263
4264
4265
4266
4267
4268
4269
4270
4271
4272
4273
4274
4275
4276
4277
4278
4279
4280
4281
4282
4283
4284
4285
4286
4287
4288
4289
4290
4291
4292
4293
4294
4295
4296
4297
4298
4299
4300
4301
4302
4303
4304
4305
4306
4307
4308
4309
4310
4311
4312
4313
4314
4315
4316
4317
4318
4319
4320
4321
4322
4323
4324
4325
4326
4327
4328
4329
4330
4331
4332
4333
4334
4335
4336
4337
4338
4339
4340
4341
4342
4343
4344
4345
4346
4347
4348
4349
4350
4351
4352
4353
4354
4355
4356
4357
4358
4359
4360
4361
4362
4363
4364
4365
4366
4367
4368
4369
4370
4371
4372
4373
4374
4375
4376
4377
4378
4379
4380
4381
4382
4383
4384
4385
4386
4387
4388
4389
4390
4391
4392
4393
4394
4395
4396
4397
4398
4399
4400
4401
4402
4403
4404
4405
4406
4407
4408
4409
4410
4411
4412
4413
4414
4415
4416
4417
4418
4419
4420
4421
4422
4423
4424
4425
4426
4427
4428
4429
4430
4431
4432
4433
4434
4435
4436
4437
4438
4439
4440
4441
4442
4443
4444
4445
4446
4447
4448
4449
4450
4451
4452
4453
4454
4455
4456
4457
4458
4459
4460
4461
4462
4463
4464
4465
4466
4467
4468
4469
4470
4471
4472
4473
4474
4475
4476
4477
4478
4479
4480
4481
4482
4483
4484
4485
4486
4487
4488
4489
4490
4491
4492
4493
4494
4495
4496
4497
4498
4499
4500
4501
4502
4503
4504
4505
4506
4507
4508
4509
4510
4511
4512
4513
4514
4515
4516
4517
4518
4519
4520
4521
4522
4523
4524
4525
4526
4527
4528
4529
4530
4531
4532
4533
4534
4535
4536
4537
4538
4539
4540
4541
4542
4543
4544
4545
4546
4547
4548
4549
4550
4551
4552
4553
4554
4555
4556
4557
4558
4559
4560
4561
4562
4563
4564
4565
4566
4567
4568
4569
4570
4571
4572
4573
4574
4575
4576
4577
4578
4579
4580
4581
4582
4583
4584
4585
4586
4587
4588
4589
4590
4591
4592
4593
4594
4595
4596
4597
4598
4599
4600
4601
4602
4603
4604
4605
4606
4607
4608
4609
4610
4611
4612
4613
4614
4615
4616
4617
4618
4619
4620
4621
4622
4623
4624
4625
4626
4627
4628
4629
4630
4631
4632
4633
4634
4635
4636
4637
4638
4639
4640
4641
4642
4643
4644
4645
4646
4647
4648
4649
4650
4651
4652
4653
4654
4655
4656
4657
4658
4659
4660
4661
4662
4663
4664
4665
4666
4667
4668
4669
4670
4671
4672
4673
4674
4675
4676
4677
4678
4679
4680
4681
4682
4683
4684
4685
4686
4687
4688
4689
4690
4691
4692
4693
4694
4695
4696
4697
4698
4699
4700
4701
4702
4703
4704
4705
4706
4707
4708
4709
4710
4711
4712
4713
4714
4715
4716
4717
4718
4719
4720
4721
4722
4723
4724
4725
4726
4727
4728
4729
4730
4731
4732
4733
4734
4735
4736
4737
4738
4739
4740
4741
4742
4743
4744
4745
4746
4747
4748
4749
4750
4751
4752
4753
4754
4755
4756
4757
4758
4759
4760
4761
4762
4763
4764
4765
4766
4767
4768
4769
4770
4771
4772
4773
4774
4775
4776
4777
4778
4779
4780
4781
4782
4783
4784
4785
4786
4787
4788
4789
4790
4791
4792
4793
4794
4795
4796
4797
4798
4799
4800
4801
4802
4803
4804
4805
4806
4807
4808
4809
4810
4811
4812
4813
4814
4815
4816
4817
4818
4819
4820
4821
4822
4823
4824
4825
4826
4827
4828
4829
4830
4831
4832
4833
4834
4835
4836
4837
4838
4839
4840
4841
4842
4843
4844
4845
4846
4847
4848
4849
4850
4851
4852
4853
4854
4855
4856
4857
4858
4859
4860
4861
4862
4863
4864
4865
4866
4867
4868
4869
4870
4871
4872
4873
4874
4875
4876
4877
4878
4879
4880
4881
4882
4883
4884
4885
4886
4887
4888
4889
4890
4891
4892
4893
4894
4895
4896
4897
4898
4899
4900
4901
4902
4903
4904
4905
4906
4907
4908
4909
4910
4911
4912
4913
4914
4915
4916
4917
4918
4919
4920
4921
4922
4923
4924
4925
4926
4927
4928
4929
4930
4931
4932
4933
4934
4935
4936
4937
4938
4939
4940
4941
4942
4943
4944
4945
4946
4947
4948
4949
4950
4951
4952
4953
4954
4955
4956
4957
4958
4959
4960
4961
4962
4963
4964
4965
4966
4967
4968
4969
4970
4971
4972
4973
4974
4975
4976
4977
4978
4979
4980
4981
4982
4983
4984
4985
4986
4987
4988
4989
4990
4991
4992
4993
4994
4995
4996
4997
4998
4999
5000
5001
5002
5003
5004
5005
5006
5007
5008
5009
5010
5011
5012
5013
5014
5015
5016
5017
5018
5019
5020
5021
5022
5023
5024
5025
5026
5027
5028
5029
5030
5031
5032
5033
5034
5035
5036
5037
5038
5039
5040
5041
5042
5043
5044
5045
5046
5047
5048
5049
5050
5051
5052
5053
5054
5055
5056
5057
5058
5059
5060
5061
5062
5063
5064
5065
5066
5067
5068
5069
5070
5071
5072
5073
5074
5075
5076
5077
5078
5079
5080
5081
5082
5083
5084
5085
5086
5087
5088
5089
5090
5091
5092
5093
5094
5095
5096
5097
5098
5099
5100
5101
5102
5103
5104
5105
5106
5107
5108
5109
5110
5111
5112
5113
5114
5115
5116
5117
5118
5119
5120
5121
5122
5123
5124
5125
5126
5127
5128
5129
5130
5131
5132
5133
5134
5135
5136
5137
5138
5139
5140
5141
5142
5143
5144
5145
5146
5147
5148
5149
5150
5151
5152
5153
5154
5155
5156
5157
5158
5159
5160
5161
5162
5163
5164
5165
5166
5167
5168
5169
5170
5171
5172
5173
5174
5175
5176
5177
5178
5179
5180
5181
5182
5183
5184
5185
5186
5187
5188
5189
5190
5191
5192
5193
5194
5195
5196
5197
5198
5199
5200
5201
5202
5203
5204
5205
5206
5207
5208
5209
5210
5211
5212
5213
5214
5215
5216
5217
5218
5219
5220
5221
5222
5223
5224
5225
5226
5227
5228
5229
5230
5231
5232
5233
5234
5235
5236
5237
5238
5239
5240
5241
5242
5243
5244
5245
5246
5247
5248
5249
5250
5251
5252
5253
5254
5255
5256
5257
5258
5259
5260
5261
5262
5263
5264
5265
5266
5267
5268
5269
5270
5271
5272
5273
5274
5275
5276
5277
5278
5279
5280
5281
5282
5283
5284
5285
5286
5287
5288
5289
5290
5291
5292
5293
5294
5295
5296
5297
5298
5299
5300
5301
5302
5303
5304
5305
5306
5307
5308
5309
5310
5311
5312
5313
5314
5315
5316
5317
5318
5319
5320
5321
5322
5323
5324
5325
5326
5327
5328
5329
5330
5331
5332
5333
5334
5335
5336
5337
5338
5339
5340
5341
5342
5343
5344
5345
5346
5347
5348
5349
5350
5351
5352
5353
5354
5355
5356
5357
5358
5359
5360
5361
5362
5363
5364
5365
5366
5367
5368
5369
5370
5371
5372
5373
5374
5375
5376
5377
5378
5379
5380
5381
5382
5383
5384
5385
5386
5387
5388
5389
5390
5391
5392
5393
5394
5395
5396
5397
5398
5399
5400
5401
5402
5403
5404
5405
5406
5407
5408
5409
5410
5411
5412
5413
5414
5415
5416
5417
5418
5419
5420
5421
5422
5423
5424
5425
5426
5427
5428
5429
5430
5431
5432
5433
5434
5435
5436
5437
5438
5439
5440
5441
5442
5443
5444
5445
5446
5447
5448
5449
5450
5451
5452
5453
5454
5455
5456
5457
5458
5459
5460
5461
5462
5463
5464
5465
5466
5467
5468
5469
5470
5471
5472
5473
5474
5475
5476
5477
5478
5479
5480
5481
5482
5483
5484
5485
5486
5487
5488
5489
5490
5491
5492
5493
5494
5495
5496
5497
5498
5499
5500
5501
5502
5503
5504
5505
5506
5507
5508
5509
5510
5511
5512
5513
5514
5515
5516
5517
5518
5519
5520
5521
5522
5523
5524
5525
5526
5527
5528
5529
5530
5531
5532
5533
5534
5535
5536
5537
5538
5539
5540
5541
5542
5543
5544
5545
5546
5547
5548
5549
5550
5551
5552
5553
5554
5555
5556
5557
5558
5559
5560
5561
5562
5563
5564
5565
5566
5567
5568
5569
5570
5571
5572
5573
5574
5575
5576
5577
5578
5579
5580
5581
5582
5583
5584
5585
5586
5587
5588
5589
5590
5591
5592
5593
5594
5595
5596
5597
5598
5599
5600
5601
5602
5603
5604
5605
5606
5607
5608
5609
5610
5611
5612
5613
5614
5615
5616
5617
5618
5619
5620
5621
5622
5623
5624
5625
5626
5627
5628
5629
5630
5631
5632
5633
5634
5635
5636
5637
5638
5639
5640
5641
5642
5643
5644
5645
5646
5647
5648
5649
5650
5651
5652
5653
5654
5655
5656
5657
5658
5659
5660
5661
5662
5663
5664
5665
5666
5667
5668
5669
5670
5671
5672
5673
5674
5675
5676
5677
5678
5679
5680
5681
5682
5683
5684
5685
5686
5687
5688
5689
5690
5691
5692
5693
5694
5695
5696
5697
5698
5699
5700
5701
5702
5703
5704
5705
5706
5707
5708
5709
5710
5711
5712
5713
5714
5715
5716
5717
5718
5719
5720
5721
5722
5723
5724
5725
5726
5727
5728
5729
5730
5731
5732
5733
5734
5735
5736
5737
5738
5739
5740
5741
5742
5743
5744
5745
5746
5747
5748
5749
5750
5751
5752
5753
5754
5755
5756
5757
5758
5759
5760
5761
5762
5763
5764
5765
5766
5767
5768
5769
5770
5771
5772
5773
5774
5775
5776
5777
5778
5779
5780
5781
5782
5783
5784
5785
5786
5787
5788
5789
5790
5791
5792
5793
5794
5795
5796
5797
5798
5799
5800
5801
5802
5803
5804
5805
5806
5807
5808
5809
5810
5811
5812
5813
5814
5815
5816
5817
5818
5819
5820
5821
5822
5823
5824
5825
5826
5827
5828
5829
5830
5831
5832
5833
5834
5835
5836
5837
5838
5839
5840
5841
5842
5843
5844
5845
5846
5847
5848
5849
5850
5851
5852
5853
5854
5855
5856
5857
5858
5859
5860
5861
5862
5863
5864
5865
5866
5867
5868
5869
5870
5871
5872
5873
5874
5875
5876
5877
5878
5879
5880
5881
5882
5883
5884
5885
5886
5887
5888
5889
5890
5891
5892
5893
5894
5895
5896
5897
5898
5899
5900
5901
5902
5903
5904
5905
5906
5907
5908
5909
5910
5911
5912
5913
5914
5915
5916
5917
5918
5919
5920
5921
5922
5923
5924
5925
5926
5927
5928
5929
5930
5931
5932
5933
5934
5935
5936
5937
5938
5939
5940
5941
5942
5943
5944
5945
5946
5947
5948
5949
5950
5951
5952
5953
5954
5955
5956
5957
5958
5959
5960
5961
5962
5963
5964
5965
5966
5967
5968
5969
5970
5971
5972
5973
5974
5975
5976
5977
5978
5979
5980
5981
5982
5983
5984
5985
5986
5987
5988
5989
5990
5991
5992
5993
5994
5995
5996
5997
5998
5999
6000
6001
6002
6003
6004
6005
6006
6007
6008
6009
6010
6011
6012
6013
6014
6015
6016
6017
6018
6019
6020
6021
6022
6023
6024
6025
6026
6027
6028
6029
6030
6031
6032
6033
6034
6035
6036
6037
6038
6039
6040
6041
6042
6043
6044
6045
6046
6047
6048
6049
6050
6051
6052
6053
6054
6055
6056
6057
6058
6059
6060
6061
6062
6063
6064
6065
6066
6067
6068
6069
6070
6071
6072
6073
6074
6075
6076
6077
6078
6079
6080
6081
6082
6083
6084
6085
6086
6087
6088
6089
6090
6091
6092
6093
6094
6095
6096
6097
6098
6099
6100
6101
6102
6103
6104
6105
6106
6107
6108
6109
6110
6111
6112
6113
6114
6115
6116
6117
6118
6119
6120
6121
6122
6123
6124
6125
6126
6127
6128
6129
6130
6131
6132
6133
6134
6135
6136
6137
6138
6139
6140
6141
6142
6143
6144
6145
6146
6147
6148
6149
6150
6151
6152
6153
6154
6155
6156
6157
6158
6159
6160
6161
6162
6163
6164
6165
6166
6167
6168
6169
6170
6171
6172
6173
6174
6175
6176
6177
6178
6179
6180
6181
6182
6183
6184
6185
6186
6187
6188
6189
6190
6191
6192
6193
6194
6195
6196
6197
6198
6199
6200
6201
6202
6203
6204
6205
6206
6207
6208
6209
6210
6211
6212
6213
6214
6215
6216
6217
6218
6219
6220
6221
6222
6223
6224
6225
6226
6227
6228
6229
6230
6231
6232
6233
6234
6235
6236
6237
6238
6239
6240
6241
6242
6243
6244
6245
6246
6247
6248
6249
6250
6251
6252
6253
6254
6255
6256
6257
6258
6259
6260
6261
6262
6263
6264
6265
6266
6267
6268
6269
6270
6271
6272
6273
6274
6275
6276
6277
6278
6279
6280
6281
6282
6283
6284
6285
6286
6287
6288
6289
6290
6291
6292
6293
6294
6295
6296
6297
6298
6299
6300
6301
6302
6303
6304
6305
6306
6307
6308
6309
6310
6311
6312
6313
6314
6315
6316
6317
6318
6319
6320
6321
6322
6323
6324
6325
6326
6327
6328
6329
6330
6331
6332
6333
6334
6335
6336
6337
6338
6339
6340
6341
6342
6343
6344
6345
6346
6347
6348
6349
6350
6351
6352
6353
6354
6355
6356
6357
6358
6359
6360
6361
6362
6363
6364
6365
6366
6367
6368
6369
6370
6371
6372
6373
6374
6375
6376
6377
6378
6379
6380
6381
6382
6383
6384
6385
6386
6387
6388
6389
6390
6391
6392
6393
6394
6395
6396
6397
6398
6399
6400
6401
6402
6403
6404
6405
6406
6407
6408
6409
6410
6411
6412
6413
6414
6415
6416
6417
6418
6419
6420
6421
6422
6423
6424
6425
6426
6427
6428
6429
6430
6431
6432
6433
6434
6435
6436
6437
6438
6439
6440
6441
6442
6443
6444
6445
6446
6447
6448
6449
6450
6451
6452
6453
6454
6455
6456
6457
6458
6459
6460
6461
6462
6463
6464
6465
6466
6467
6468
6469
6470
6471
6472
6473
6474
6475
6476
6477
6478
6479
6480
6481
6482
6483
6484
6485
6486
6487
6488
6489
6490
6491
6492
6493
6494
6495
6496
6497
6498
6499
6500
6501
6502
6503
6504
6505
6506
6507
6508
6509
6510
6511
6512
6513
6514
6515
6516
6517
6518
6519
6520
6521
6522
6523
6524
6525
6526
6527
6528
6529
6530
6531
6532
6533
6534
6535
6536
6537
6538
6539
6540
6541
6542
6543
6544
6545
6546
6547
6548
6549
6550
6551
6552
6553
6554
6555
6556
6557
6558
6559
6560
6561
6562
6563
6564
6565
6566
6567
6568
6569
6570
6571
6572
6573
6574
6575
6576
6577
6578
6579
6580
6581
6582
6583
6584
6585
6586
6587
6588
6589
6590
6591
6592
6593
6594
6595
6596
6597
6598
6599
6600
6601
6602
6603
6604
6605
6606
6607
6608
6609
6610
6611
6612
6613
6614
6615
6616
6617
6618
6619
6620
6621
6622
6623
6624
6625
6626
6627
6628
6629
6630
6631
6632
6633
6634
6635
6636
6637
6638
6639
6640
6641
6642
6643
6644
6645
6646
6647
6648
6649
6650
6651
6652
6653
6654
6655
6656
6657
6658
6659
6660
6661
6662
6663
6664
6665
6666
6667
6668
6669
6670
6671
6672
6673
6674
6675
6676
6677
6678
6679
6680
6681
6682
6683
6684
6685
6686
6687
6688
6689
6690
6691
6692
6693
6694
6695
6696
6697
6698
6699
6700
6701
6702
6703
6704
6705
6706
6707
6708
6709
6710
6711
6712
6713
6714
6715
6716
6717
6718
6719
6720
6721
6722
6723
6724
6725
6726
6727
6728
6729
6730
6731
6732
6733
6734
6735
6736
6737
6738
6739
6740
6741
6742
6743
6744
6745
6746
6747
6748
6749
6750
6751
6752
6753
6754
6755
6756
6757
6758
6759
6760
6761
6762
6763
6764
6765
6766
6767
6768
6769
6770
6771
6772
6773
6774
6775
6776
6777
6778
6779
6780
6781
6782
6783
6784
6785
6786
6787
6788
6789
6790
6791
6792
6793
6794
6795
6796
6797
6798
6799
6800
6801
6802
6803
6804
6805
6806
6807
6808
6809
6810
6811
6812
6813
6814
6815
6816
6817
6818
6819
6820
6821
6822
6823
6824
6825
6826
6827
6828
6829
6830
6831
6832
6833
6834
6835
6836
6837
6838
6839
6840
6841
6842
6843
6844
6845
6846
6847
6848
6849
6850
6851
6852
6853
6854
6855
6856
6857
6858
6859
6860
6861
6862
6863
6864
6865
6866
6867
6868
6869
6870
6871
6872
6873
6874
6875
6876
6877
6878
6879
6880
6881
6882
6883
6884
6885
6886
6887
6888
6889
6890
6891
6892
6893
6894
6895
6896
6897
6898
6899
6900
6901
6902
6903
6904
6905
6906
6907
6908
6909
6910
6911
6912
6913
6914
6915
6916
6917
6918
6919
6920
6921
6922
6923
6924
6925
6926
6927
6928
6929
6930
6931
6932
6933
6934
6935
6936
6937
6938
6939
6940
6941
6942
6943
6944
6945
6946
6947
6948
6949
6950
6951
6952
6953
6954
6955
6956
6957
6958
6959
6960
6961
6962
6963
6964
6965
6966
6967
6968
6969
6970
6971
6972
6973
6974
6975
6976
6977
6978
6979
6980
6981
6982
6983
6984
6985
6986
6987
6988
6989
6990
6991
6992
6993
6994
6995
6996
6997
6998
6999
7000
7001
7002
7003
7004
7005
7006
7007
7008
7009
7010
7011
7012
7013
7014
7015
7016
7017
7018
7019
7020
7021
7022
7023
7024
7025
7026
7027
7028
7029
7030
7031
7032
7033
7034
7035
7036
7037
7038
7039
7040
7041
7042
7043
7044
7045
7046
7047
7048
7049
7050
7051
7052
7053
7054
7055
7056
7057
7058
7059
7060
7061
7062
7063
7064
7065
7066
7067
7068
7069
7070
7071
7072
7073
7074
7075
7076
7077
7078
7079
7080
7081
7082
7083
7084
7085
7086
7087
7088
7089
7090
7091
7092
7093
7094
7095
7096
7097
7098
7099
7100
7101
7102
7103
7104
7105
7106
7107
7108
7109
7110
7111
7112
7113
7114
7115
7116
7117
7118
7119
7120
7121
7122
7123
7124
7125
7126
7127
7128
7129
7130
7131
7132
7133
7134
7135
7136
7137
7138
7139
7140
7141
7142
7143
7144
7145
7146
7147
7148
7149
7150
7151
7152
7153
7154
7155
7156
7157
7158
7159
7160
7161
7162
7163
7164
7165
7166
7167
7168
7169
7170
7171
7172
7173
7174
7175
7176
7177
7178
7179
7180
7181
7182
7183
7184
7185
7186
7187
7188
7189
7190
7191
7192
7193
7194
7195
7196
7197
7198
7199
7200
7201
7202
7203
7204
7205
7206
7207
7208
7209
7210
7211
7212
7213
7214
7215
7216
7217
7218
7219
7220
7221
7222
7223
7224
7225
7226
7227
7228
7229
7230
7231
7232
7233
7234
7235
7236
7237
7238
7239
7240
7241
7242
7243
7244
7245
7246
7247
7248
7249
7250
7251
7252
7253
7254
7255
7256
7257
7258
7259
7260
7261
7262
7263
7264
7265
7266
7267
7268
7269
7270
7271
7272
7273
7274
7275
7276
7277
7278
7279
7280
7281
7282
7283
7284
7285
7286
7287
7288
7289
7290
7291
7292
7293
7294
7295
7296
7297
7298
7299
7300
7301
7302
7303
7304
7305
7306
7307
7308
7309
7310
7311
7312
7313
7314
7315
7316
7317
7318
7319
7320
7321
7322
7323
7324
7325
7326
7327
7328
7329
7330
7331
7332
7333
7334
7335
7336
7337
7338
7339
7340
7341
7342
7343
7344
7345
7346
7347
7348
7349
7350
7351
7352
7353
7354
7355
7356
7357
7358
7359
7360
7361
7362
7363
7364
7365
7366
7367
7368
7369
7370
7371
7372
7373
7374
7375
7376
7377
7378
7379
7380
7381
7382
7383
7384
7385
7386
7387
7388
7389
7390
7391
7392
7393
7394
7395
7396
7397
7398
7399
7400
7401
7402
7403
7404
7405
7406
7407
7408
7409
7410
7411
7412
7413
7414
7415
7416
7417
7418
7419
7420
7421
7422
7423
7424
7425
7426
7427
7428
7429
7430
7431
7432
7433
7434
7435
7436
7437
7438
7439
7440
7441
7442
7443
7444
7445
7446
7447
7448
7449
7450
7451
7452
7453
7454
7455
7456
7457
7458
7459
7460
7461
7462
7463
7464
7465
7466
7467
7468
7469
7470
7471
7472
7473
7474
7475
7476
7477
7478
7479
7480
7481
7482
7483
7484
7485
7486
7487
7488
7489
7490
7491
7492
7493
7494
7495
7496
7497
7498
7499
7500
7501
7502
7503
7504
7505
7506
7507
7508
7509
7510
7511
7512
7513
7514
7515
7516
7517
7518
7519
7520
7521
7522
7523
7524
7525
7526
7527
7528
7529
7530
7531
7532
7533
7534
7535
7536
7537
7538
7539
7540
7541
7542
7543
7544
7545
7546
7547
7548
7549
7550
7551
7552
7553
7554
7555
7556
7557
7558
7559
7560
7561
7562
7563
7564
7565
7566
7567
7568
7569
7570
7571
7572
7573
7574
7575
7576
7577
7578
7579
7580
7581
7582
7583
7584
7585
7586
7587
7588
7589
7590
7591
7592
7593
7594
7595
7596
7597
7598
7599
7600
7601
7602
7603
7604
7605
7606
7607
7608
7609
7610
7611
7612
7613
7614
7615
7616
7617
7618
7619
7620
7621
7622
7623
7624
7625
7626
7627
7628
7629
7630
7631
7632
7633
7634
7635
7636
7637
7638
7639
7640
7641
7642
7643
7644
7645
7646
7647
7648
7649
7650
7651
7652
7653
7654
7655
7656
7657
7658
7659
7660
7661
7662
7663
7664
7665
7666
7667
7668
7669
7670
7671
7672
7673
7674
7675
7676
7677
7678
7679
7680
7681
7682
7683
7684
7685
7686
7687
7688
7689
7690
7691
7692
7693
7694
7695
7696
7697
7698
7699
7700
7701
7702
7703
7704
7705
7706
7707
7708
7709
7710
7711
7712
7713
7714
7715
7716
7717
7718
7719
7720
7721
7722
7723
7724
7725
7726
7727
7728
7729
7730
7731
7732
7733
7734
7735
7736
7737
7738
7739
7740
7741
7742
7743
7744
7745
7746
7747
7748
7749
7750
7751
7752
7753
7754
7755
7756
7757
7758
7759
7760
7761
7762
7763
7764
7765
7766
7767
7768
7769
7770
7771
7772
7773
7774
7775
7776
7777
7778
7779
7780
7781
7782
7783
7784
7785
7786
7787
7788
7789
7790
7791
7792
7793
7794
7795
7796
7797
7798
7799
7800
7801
7802
7803
7804
7805
7806
7807
7808
7809
7810
7811
7812
7813
7814
7815
7816
7817
7818
7819
7820
7821
7822
7823
7824
7825
7826
7827
7828
7829
7830
7831
7832
7833
7834
7835
7836
7837
7838
7839
7840
7841
7842
7843
7844
7845
7846
7847
7848
7849
7850
7851
7852
7853
7854
7855
7856
7857
7858
7859
7860
7861
7862
7863
7864
7865
7866
7867
7868
7869
7870
7871
7872
7873
7874
7875
7876
7877
7878
7879
7880
7881
7882
7883
7884
7885
7886
7887
7888
7889
7890
7891
7892
7893
7894
7895
7896
7897
7898
7899
7900
7901
7902
7903
7904
7905
7906
7907
7908
7909
7910
7911
7912
7913
7914
7915
7916
7917
7918
7919
7920
7921
7922
7923
7924
7925
7926
7927
7928
7929
7930
7931
7932
7933
7934
7935
7936
7937
7938
7939
7940
7941
7942
7943
7944
7945
7946
7947
7948
7949
7950
7951
7952
7953
7954
7955
7956
7957
7958
7959
7960
7961
7962
7963
7964
7965
7966
7967
7968
7969
7970
7971
7972
7973
7974
7975
7976
7977
7978
7979
7980
7981
7982
7983
7984
7985
7986
7987
7988
7989
7990
7991
7992
7993
7994
7995
7996
7997
7998
7999
8000
8001
8002
8003
8004
8005
8006
8007
8008
8009
8010
8011
8012
8013
8014
8015
8016
8017
8018
8019
8020
8021
8022
8023
8024
8025
8026
8027
8028
8029
8030
8031
8032
8033
8034
8035
8036
8037
8038
8039
8040
8041
8042
8043
8044
8045
8046
8047
8048
8049
8050
8051
8052
8053
8054
8055
8056
8057
8058
8059
8060
8061
8062
8063
8064
8065
8066
8067
8068
8069
8070
8071
8072
8073
8074
8075
8076
8077
8078
8079
8080
8081
8082
8083
8084
8085
8086
8087
8088
8089
8090
8091
8092
8093
8094
8095
8096
8097
8098
8099
8100
8101
8102
8103
8104
8105
8106
8107
8108
8109
8110
8111
8112
8113
8114
8115
8116
8117
8118
8119
8120
8121
8122
8123
8124
8125
8126
8127
8128
8129
8130
8131
8132
8133
8134
8135
8136
8137
8138
8139
8140
8141
8142
8143
8144
8145
8146
8147
8148
8149
8150
8151
8152
8153
8154
8155
8156
8157
8158
8159
8160
8161
8162
8163
8164
8165
8166
8167
8168
8169
8170
8171
8172
8173
8174
8175
8176
8177
8178
8179
8180
8181
8182
8183
8184
8185
8186
8187
8188
8189
8190
8191
8192
8193
8194
8195
8196
8197
8198
8199
8200
8201
8202
8203
8204
8205
8206
8207
8208
8209
8210
8211
8212
8213
8214
8215
8216
8217
8218
8219
8220
8221
8222
8223
8224
8225
8226
8227
8228
8229
8230
8231
8232
8233
8234
8235
8236
8237
8238
8239
8240
8241
8242
8243
8244
8245
8246
8247
8248
8249
8250
8251
8252
8253
8254
8255
8256
8257
8258
8259
8260
8261
8262
8263
8264
8265
8266
8267
8268
8269
8270
8271
8272
8273
8274
8275
8276
8277
8278
8279
8280
8281
8282
8283
8284
8285
8286
8287
8288
8289
8290
8291
8292
8293
8294
8295
8296
8297
8298
8299
8300
8301
8302
8303
8304
8305
8306
8307
8308
8309
8310
8311
8312
8313
8314
8315
8316
8317
8318
8319
8320
8321
8322
8323
8324
8325
8326
8327
8328
8329
8330
8331
8332
8333
8334
8335
8336
8337
8338
8339
8340
8341
8342
8343
8344
8345
8346
8347
8348
8349
8350
8351
8352
8353
8354
8355
8356
8357
8358
8359
8360
8361
8362
8363
8364
8365
8366
8367
8368
8369
8370
8371
8372
8373
8374
8375
8376
8377
8378
8379
8380
8381
8382
8383
8384
8385
8386
8387
8388
8389
8390
8391
8392
8393
8394
8395
8396
8397
8398
8399
8400
8401
8402
8403
8404
8405
8406
8407
8408
8409
8410
8411
8412
8413
8414
8415
8416
8417
8418
8419
8420
8421
8422
8423
8424
8425
8426
8427
8428
8429
8430
8431
8432
8433
8434
8435
8436
8437
8438
8439
8440
8441
8442
8443
8444
8445
8446
8447
8448
8449
8450
8451
8452
8453
8454
8455
8456
8457
8458
8459
8460
8461
8462
8463
8464
8465
8466
8467
8468
8469
8470
8471
8472
8473
8474
8475
8476
8477
8478
8479
8480
8481
8482
8483
8484
8485
8486
8487
8488
8489
8490
8491
8492
8493
8494
8495
8496
8497
8498
8499
8500
8501
8502
8503
8504
8505
8506
8507
8508
8509
8510
8511
8512
8513
8514
8515
8516
8517
8518
8519
8520
8521
8522
8523
8524
8525
8526
8527
8528
8529
8530
8531
8532
8533
8534
8535
8536
8537
8538
8539
8540
8541
8542
8543
8544
8545
8546
8547
8548
8549
8550
8551
8552
8553
8554
8555
8556
8557
8558
8559
8560
This file contains a CVS FAQ.  Until 1995 it was maintained by David
Grubbs.  It was out of date and not being maintained, but it had a
certain following and in 1997 Pascal Molli decided to start
maintaining it with the FAQ-O-Matic package which allows any
contributor with a web browser to help maintain it.  The following
text is (mostly automatically) extracted from the FAQ-O-Matic.  The
odds are good that the file that you are currently reading is out of
date with respect to the online FAQ-O-Matic, which is part of Pascal
Molli's CVS web site at http://www.loria.fr/~molli/cvs-index.html
(currently under "Documentation").  The online version is also
somewhat better in terms of things like tables of contents (at least
until someone can write some code to extract data from a FAQ-O-Matic
and insert things like tables of contents).

The answers which are dated "6/13/1997" below are really from the 1995
FAQ, for the most part.  Many of them are out of date.  If you have
some time, you are encouraged to double-check them against other
sources like the Cederqvist manual and update the FAQ.  If you don't
have such time, take them with a grain of salt or a few.

Since Feb. 2000 CVS is being maintained by OpenAvenue, Inc. and many of
the existing resources have been centeralized on http://www.cvshome.org.

  Category: /, all questions
  
  Category: /
  
          " [INLINE] "
          
    1. About FAQ-O-Matic 
    
This is FAQ-O-Matic, a quick-and-dirty Perl hack (aren't they all?) by
Jon Howell.

It seems like most FAQ maintainers make a valiant initial effort, then get
a life and don't have time to keep their FAQs up to date. Also, I often
find out a solution to a problem, and feel like I could write a single
FAQ answer on it in a few minutes, but where to post it?

Thus the FAQ-O-Matic was born. FAQ-O-Matic is a couple sleazy Perl scripts
that allow people to submit FAQ answers to this database, so it can stay
current, with just a tiny bit of work on any one person's part.

Yes, a bad guy could come along and wipe out all the FAQ entries. Please don't.
But to give the good guys some measure of comfort, each submission is stored
in an RCS file, so if someone does tamper, we can recover the database.

Guidelines for submissions:

1. Please _try to be fairly unbiased in matters of opinion._ Mailing lists are
the place to start flame wars (just kidding :v), but definitely not here.

2. Please _use HTML only conservatively_ in your entries. Links are appropriate
,
but put the URL in the plaintext also so it's useable on printed versions of
the FAQ. Inline images pointing off this site are inappropriate, as is much
fancy formatting. This is meant to be bandwidth-light and dumb-browser-friendly
.

3. If you feel there's a place for a _new category, or a reorganization of
existing questions_, don't hesitate to mail me (molli@loria.fr).
Category changes need to be done from my end.

4. Please _leave an email address_ at the bottom of your submission so that oth
ers
can drop you a note.

5. _If you only have a question_, not an answer, you should probably post
it to a mailing list, not here. If there are frequently asked questions to whic
h
the answer is not forthcoming on mailing lists (or perhaps there's no
useful answer yet other than "no one knows"), then it's appropriate to
post here, in hopes that someone will see it and know the answer.

6. Please refrain from crude or inconsiderate language. Please don't use
this as a forum for advertising. However, mention of worthy commercial
products is certainly appropriate (even if you sell said product). Just
don't overdo it. :v)

          Last modified: _6/13/1997_
          
    2. Adding a new category ? 
    
just send me a mail at
molli@loria.fr

          Last modified: _6/13/1997_
          
  Category: /Advanced_Topics_/
  
          " Advanced Topics "
          
  Category: /Advanced_Topics_/Branching_and_Mergin/
  
          " + Branching and Merging"
          
    1. What is a branch? 
    
          Unfortunately, the word "branch" is an overloaded technical
          term. It is used in too many different ways in three
          categories. It might help to understand some of the issues by
          going through the categories:
          
     How Humans use the word "branch":
          
          Most development starts with everyone working on the same
          software, making changes and heading toward a single goal. This
          is called something like "Main Line Development". Note that
          though many people do main line development on CVS's "Main
          Branch", that is a choice, not a requirement.
          
          After a release or when one or more developers want to go off
          and work on some project for a while, the Software Engineers
          assigned to deal with large software issues generate a "Branch
          in Development" to support the release or project. (Keep in
          mind that a programmer is no more a Software Engineer than a
          carpenter is a Civil Engineer.)
          
          Essentially, the word "branch" implies a way to allow
          simultaneous development on the same files by multiple people.
          
          The above terms are human-oriented. They refer to actions that
          people would like to take. They do *not* imply any particular
          implementation or set of procedures. Branches in development
          can be supported in many different ways.
          
     How CVS uses the word "branch":
          
          CVS uses the word "branch" in a number of ways. The two most
          important are:
          
          - The vendor branch holds releases from (normally) an outside
          software vendor. It is implemented using a specific RCS branch
          (i.e. 1.1.1).
          
          - The "Main Branch", which normally holds your "Main Line
          Development", but is defined as the collection of revisions you
          get when you "checkout" something fresh, or when you use the
          '-A' option to "update".
          
          Important Note: The CVS "Main Branch" is *not* the same as the
          RCS concept with the same name. If you are using Vendor
          Branches, files you have never changed are on three branches at
          the same time:
          
          - The RCS 1.1.1 branch.
          - The CVS Vendor branch.
          - The CVS "Main Branch".
          
          The concepts overlap, but they are not equivalent.
          
          In referring to CVS, "branch" can be used in four other ways:
          
          - A CVS working directory satisfies the definition of "branch"
          for a single developer -- you are on a private "virtual branch"
          that does not appear in any of the RCS files or the CVS control
          files.
          
          - The CVS "default branch" is the Repository source for the
          collection of files in your working directory. It is *not* the
          same as the RCS "default branch". Normally the CVS default
          branch is the same as the CVS Main branch. If you use the "-r
          <branch_tag>" option to the "checkout" command, you will record
          a "sticky" tag that changes your default branch to the one you
          checked out.
          
          - A "magic" branch can be a branch that hasn't happened yet. It
          is implemented by a special tag you can check out that is not
          attached to a real RCS branch. When you commit a file to a
          magic branch, the branch becomes real (i.e. a physical RCS
          branch).
          
          - And, of course, CVS uses "branch" to indicate a
          human-oriented "branch in development".
          
     How RCS uses the word "branch":
          
          - The RCS "Main Branch" (Synonym: "The Trunk") contains a
          series of two-part revision numbers separated by a single '.'
          (e.g. 1.2). It is treated specially and is the initial default
          branch. (The default default?)
          
          - The RCS "Default" branch starts out attached to the RCS "Main
          Branch". For RCS purposes, it can be changed to point to any
          branch. Within CVS, you *must*not* alter the RCS default
          branch. It is used to support the CVS idea of a "Main Branch"
          and it must either point to the RCS Main Branch, or the Vendor
          Branch (1.1.1) if you haven't made any changes to the file
          since you executed "import".
          
   Last modified: _6/13/1997_
   
    2. Why (or when) would I want to create a branch? 
    
   Remember that you can think of your working directory as a "branch for
   one". You can consider yourself to be on a branch all the time because
   you can work without interfering with others until your project (big
   or small) is done.
   
   The four major situations when you should create a branch:
   
     When you expect to take a long time or make a large set of changes
   that the merging process will be difficult. Both "long" and "large"
   are defined in your own environment.
   
     When you want to be able to "commit" and "tag" your work repeatedly
   without affecting others.
   
   If you ever think you need Source Control for your own work, but don't
   want your changes to affect others, create a private branch. (Put your
   username in the branch tag, to make it obvious that it is private.)
   
     When you need to share code among a group of developers, but not the
   whole development organization working on the files.
   
   Rather than trying to share a working directory, you can move onto a
   branch and share your work with others by "committing" your work onto
   the branch. Developers not working on the branch won't see your work
   unless they switch to your branch or explicitly merge your branch into
   theirs.
   
     When you need to make minor changes to a released system.
   
   Normally a "release" is labeled by a branch tag, allowing later work
   on the released files. If the release is labeled by a non-branch tag,
   it is easy to add a branch tag to a previously tagged module with the
   "rtag" command. If the release is not tagged, you made a mistake.
   Recovery requires identifying all revisions involved in the release
   and adding a tag to them.
   
   Last modified: _6/13/1997_
   
    3. How do I create and checkout a branch? 
    
   Suggested technique:
   
     Attach a non-branch tag to all the revisions you want to branch
   from. (i.e. the branch point revisions)
   
     When you decide you really need a branch, attach a branch tag to the
   same revisions marked by the non-branch tag.
   
     "Checkout" or "update" your working directory onto the branch.
   
     Suggested procedure when using modules:
   
     cvs rtag <branch_point_tag> module
   
     cvs rtag -b -r <branch_point_tag> <branch_tag> <module>
   
     cvs checkout -r <branch_tag> module
   
     Suggested procedure when using your working directory, which
   contains the revisions of your working files you want to branch from:
   
     cvs tag <branch_point_tag>
   
     cvs rtag -b -r <branch_point_tag> <branch_tag> <module>
   
     cvs update -r <branch_tag>
   
   In each procedure above, Step #1 applies a non-branch tag to all the
   branch point revisions in the module/directory. Though this is not
   strictly necessary, if you don't add a non-branch tag to the revisions
   you branch from, you won't be able to refer to the branch point in the
   future.
   
   Between steps 1 & 2 you may commit changes. The result would be same
   because "rtag -r <oldtag> <newtag>" applies <newtag> to the same
   revision that <oldtag> is attached to. You can use this technique to
   avoid attaching *any* branch tags until you need them.
   
   Step B.2 has two corollaries:
   
     If you plan to create the branch tag before committing anything in
   your working directory, you can use "cvs tag -b <branch_tag>" instead
   of the "rtag" command.
   
     The <module> can be a relative path to a directory from which your
   working directory was checked out.
   
   If you have trouble figuring out what <module> to use (or pathname to
   use in its place), you can aim it at whatever parent directories you
   believe will cover all your work.
   
   If you are sure the <branch_tag> is not being used anywhere else, you
   can even aim it at the whole Repository ($CVSROOT), if you have to. It
   might take some extra time, but assuming that your <tag> is a unique
   string and you don't use the '-f' option to "rtag -r", "rtag" will
   only add a <tag> to files in which it actually *finds* the earlier
   <tag>.
   
   In each procedure above, Step #3 may occur any time after step 2.
   Unless you explicitly remove them with "tag -d", a <tag> is permanent.
   
   The <branch_tag> is an unusual creature. It labels a branch in a way
   that allows you to "checkout" the branch, to "commit" files to the end
   of the branch and to refer to the end of the branch. It does not label
   the base of the branch (the branch point).
   
   There are two obvious ways to choose the <branch_point_tag> and
   <branch_tag> names. But keep in mind that the <branch_tag> is typed by
   any developer who wants to work on the branch -- you should make it
   mean something to them.
   
   Style #1 presumes that the simple version string refers to a set of
   designed, documented or promised features, not to a specific set of
   files. In this case, you tag the branch with the generic Version
   string and assume that whenever you refer to "Version", you want the
   "latest" set of files associated with that Version, including all
   patches. (You can substitute whatever you like for "bp_", as long as
   your <branch_point_tag> is some modification of the <branch_tag>.)
   
                <branch_point_tag>      Matching <branch_tag>

                bp_V1_3                 V1_3
                bp_Release2-3-5         Release2-3-5
                bp_Production4_5        Release4_5

   Style #2 presumes that the simple version string refers to the
   specific set of files used to construct the first release of
   "version". In this case, you tag the branch-point revisions with the
   generic Version string and assume that whenever you refer to this
   Version, you want the original set of released revisions. To get the
   latest patched revisions of the release, you refer to the branch tag
   "latest_<branch_point_tag>". (You can substitute what ever you like
   for "latest_", as long as your <branch_tag> is some modification of
   the <branch_point_tag>.)
   
                <branch_point_tag>      Matching <branch_tag>

                V1_3                    latest_V1_3
                Release2-3-5            latest_Release2-3-5
                Release4_5              latest_Production4_5

   In both styles you can find out what you had to change since the
   original release of this Version by typing:
   
            cvs diff -r <branch_point_tag> -r <branch_tag>

   For Style 1, this is:
   
            cvs diff -r bp_<branch_tag> -r <branch_tag>

   For Style 2, this is:
   
            cvs diff -r <branch_point_tag> -r latest_<branch_point_tag>

   Notes on "being on a branch":
   
   - "update -r <tag>" tells CVS to attach a "sticky tag" to working
   directory (in ./CVS/Tag) and the checked-out files (on each line of
   ./CVS/Entries).
   
   - A "sticky" <tag> (including a <branch_tag>) causes most CVS commands
   to act as if "-r <tag>" were on the command line.
   
   - A "sticky" <branch_tag> indicates that the working directory (and
   working files) are "on the branch".
   
   Last modified: _6/13/1997_
   
    4. Once created, how do I manage a branch? 
    
   The most important thing you should know about managing a branch is
   that the creation of a branch is not a lightweight act. When you
   create a branch, you must also create a set of procedures to keep
   track of it.
   
   Specifically, you must:
   
   - Remember that the branch exists. (This is non-trivial if you create
   a lot of them.)
   
   - Plan when to merge it back into the main line of development.
   
   - Schedule the order that multiple branch merges are to be done.
   
   - If you ever intend to merge branches into each other, instead of
   limiting merges of branch work back into the "main line", you must
   keep careful track of which parts of which branches have merged into
   which other branches.
   
   The simplest way to deal with branches is to limit their number,
   "collapse" them back into the main line as quickly as is reasonable
   and forget them. If a group wants to continue working, tell them to
   create another branch off the fully merged main line.
   
   Remember that CVS is just a tool. Over time, it will probably handle
   branching better, requiring less careful attendance. But no matter how
   good it becomes, the whole idea of "branching" is a complicated
   management problem. Don't take it lightly.
   
   Last modified: _6/13/1997_
   
    5. Are there any extra issues in managing multiple branches? 
    
   If you plan to split from the "main line" and merge back after a time,
   the only problem will be scheduling the order of branch merges. As
   each branch is merged, the main line must be rebuilt and tested.
   Merging multiple branches (i.e. "lines of development") before
   building and testing creates more problems than you are ready for.
   
   If you plan to collapse some branches into others, then move the
   combined branches back into the main line, you have to be careful with
   the revisions and tags you hand to your "update -j" command, but it
   shouldn't be much trouble.
   
   If you plan to allow every branch to incrementally take the work done
   on other branches, you are creating an almost insurmountable
   bookkeeping problem. Every developer will say "Hey, I can handle
   taking just this little bit," but for the system as a whole it is
   disaster. Try it once and see. If you are forced into this situation,
   you will need to keep track of the beginning and end points of every
   merge ever done. Good Luck.
   
   Last modified: _6/13/1997_
   
    6. How do I merge a whole branch back into the trunk? 
    
   If you don't have a working directory, you can checkout and merge in
   one command:
   
                cvs checkout -j <branch_tag> <module>
                cd <module>

   If you already have a working directory:
   
                cd <working_directory>
                cvs update      <== Optional, to bring it up to date.
                cvs update -j <branch_tag>

   CVS will print lines beginning with
   
   'U' for files that you hadn't changed, but the branch did.
   
   'M' for files that you changed and the branch didn't
                *and* for files that you both changed that were merged
                without overlaps.  (This overload is unfortunate.)

   'C' for files that you both changed in a way that conflicts
                with each other.

   You need to go edit all the 'C' files and clean up the conflicts. Then
   you must commit them.
   
   Last modified: _6/13/1997_
   
    7. How do I merge changes from the trunk into my branch or between
    branches? 
    
   The idea is similar to the above, but since CVS doesn't treat the main
   branch like other branches, you'll have to be more careful. There are
   5 different ways to look at the problem.
   
     The way to merge *all* changes made on the trunk into a working
   branch is to move to the branch you want via "checkout -r" or "update
   -r":
   
                cvs update -r <branch_tag> {optional files}

   Then merge the changes from the trunk into your working branch using
   the pseudo-tag named "HEAD":
   
                cvs up -j HEAD {optional files}

   You will get everything from the branch point of the branch named
   <branch_tag> up to the HEAD of the main branch. This is still kind of
   strange. If the file is on a branch, HEAD should be the latest thing
   on the branch, not the HEAD of MAIN. But that's not the way CVS
   (currently) works.
   
   If you run "cvs up -j HEAD" again after adding more revisions to the
   trunk, you may get overlaps for the text you have already merged. It
   depends on your version of your RCS "merge" command (actually the "co
   -j" option, which depends on the version of "diff3" you configured RCS
   to use).
   
     You can merge the difference between any two <tags> using two "-j"
   options on "update" or "checkout".
   
   Identify the two tags on the branch you want to merge from.
   
                cvs update -j <tag1> -j <tag2> {optional files}

   This step assumes you were careful about tagging milestones. You can
   use this technique for any two <tags> on the same branch, even the
   trunk. It is also possible to use tags on different branches, but
   you'll have to ponder the meaning of the difference between those two
   tags.
   
   In place of one of the <tags>, you can use a <branch_tag> to refer to
   the latest revision on that branch. See 4C.11 and 4C.3 for info on
   branch points.
   
   Merges can also be performed by handing RCS revisions to the '-j'
   options, but since revision numbers aren't the same in all files,
   merging by number is normally limited to one file. Sets of files with
   the exact same trees of branches and revision numbers would work too,
   but that's a rare situation.
   
     To "take" revisions from other branches instead of merging them, see
   4C.19 for an idea.
   
     A way to gain the effect of merging the main to the branch is to
   merge the branch into the main using the normal
   
                cvs update -A {optional files}
                cvs update -j <branch_tag> {optional files}
                cvs commit
                cvs tag -F  -b <same_branch_tag> {optional files}

   See part B of 4D.5
   
     Other oddities.
   
   This also works, but is probably not officially supported:
   
                   cvs update -j N {optional files}

   where N is a number. This will merge all the changes from the branch
   point up to the highest revision on the main branch starting with N.
   For example, if your highest trunk revision is 1.52, you can use this
   to grab revisions from the trunk:
   
                   cvs update -j 1 {optional files}

   Another example: Say you have a branch point at rev 1.2 for a branch
   named "BR1" and trunk revisions 1.3, 1.4, 2.1, 2.2, 2.3, 3.1, 3.2.
   Then:
   
                   cvs update -j 1 {optional files}

   will merge the changes from 1.2 to 1.4
   
                   cvs update -j 2 {optional files}

   will merge the changes from 1.2 to 2.3
   
                   cvs update -j 3 {optional files}

   will merge the changes from 1.2 to 3.2, which in this example, is
   equivalent to the use of "-j HEAD" in part A above.
   
   The intuitive (at least to me):
   
                   cvs up -j MAIN (or TRUNK) {optional files}

   doesn't work. If the trunk (i.e. "main branch") had an implicit branch
   named "MAIN", you could use:
   
                   cvs up -j MAIN:10/26 -j MAIN:now {optional files}

   and refer to date-stamped revisions on the trunk using the
   <branch_tag>:<date> support that works on other branches.
   
   You might also think you could place an explicit tag on branch 1 (or
   higher) (e.g. MAINHACK:1) and use it in place of the implicit "MAIN",
   but I haven't found the right combination.
   
   [[If you find working techniques, I'll add them here.]]
   
   Last modified: _6/13/1997_
   
    8. How do I merge onto the Main Branch a file that exists only on a branch
    other than the Main Branch? (i.e. it is in the Attic) 
    
   For how such a file can exist, see 3A.2 and 3A.3.
   
   For how to avoid creating such a file, see 3A.5.
   
   Though you might think that the "update -j" command could perform the
   "merge" of a file from the side branch to the Main Branch, it isn't
   (yet) smart enough. Unfortunately, there is no single CVS command to
   do this -- it takes three steps:
   
     To move something onto the Main Branch from the Attic, you have to
   physically move the file from the Attic to the main Repository
   directory associated with your working directory.
   
   It is exactly like resurrecting a removed file. See 3L.4
   
   I use something like this: (csh-like syntax)
   
   set repos = `cat ./CVS/Repository` mv $repos/Attic/filename,v
   $repos/filename,v
   
   (If you use relative paths in your Repository files, that first line
   becomes: set repos = $CVSROOT/`cat ./CVS/Repository`)
   
     Now that the file is physically in the right place within the
   Repository, "update -A" will make it appear in your working directory
   on the Main Branch. Do that now.
   
     You now have a choice. The act of physically moving the file has
   fused together the <branch_tag> branch and the Main Branch for this
   file. You can continue that way, making changes along the RCS Main
   Branch which CVS will (for this type of file only) treat as both the
   Main Branch and the <branch_tag> branch.
   
   The other choice, which I would suggest, is to re-tag the file with
   <branch_tag>, restoring a normal-looking magic branch tag to the file:
   
                cvs tag -F -b <branch_tag> <file>

   After you have done the above, you can run "update -A" or "update -r
   <branch_tag>" to resume whatever you were doing before you started
   this procedure.
   
   Caveat: The final result is a file whose revision tree doesn't look
   like it was ever on any branch but the Main Branch until the above
   "tag -F -b" command was executed. CVS and RCS have no way of saving
   the history of the actions you have just performed.
   
   Last modified: _6/13/1997_
   
    9. How do I know what branch I'm (working) on? 
    
   Type:
                cvs status

   and look at the "Sticky Tag" field for each file. If:
   
     The *same* tag is on *every* file in your working tree, *and*
   
     That tag matches the contents of the ./CVS/Tag file, *and*
   
     That tag is a branch tag,
   
   then you know what branch you are working on. You can get sticky Tag
   information directly from the ./CVS/Entries file instead of "cvs
   status".
   
   If all the sticky Tags don't agree, then your directory is temporarily
   inconsistent. This is a feature allowing you to make changes (or
   perform merges) to individual files on multiple branches without
   checking out the whole directory.
   
   The sticky Tag on each file in the ./CVS/Entries file (as displayed by
   the "status" command) indicates what branch the working file is on.
   New files are added to the Tag stored in ./CVS/Tag.
   
   To force your entire working directory onto the same branch, type:
   
                cvs update -r <branch_tag>

   Last modified: _6/13/1997_
   
    10. Do I really have to know the name of the branch I'm working on? 
    
   If a developer can't be relied on to know what branch of development
   to work on, then either the developer's manager isn't planning
   branches properly or the developer has serious problems.
   
   I have found that one of the hardest concepts to get across to
   developers (and some managers) is that "a branch in development" (as
   opposed to the use of RCS branches to support some other scheme) is a
   heavyweight act. Every time you create a real branch in development,
   you must spawn a set of managerial procedures and a schedule by which
   you plan to merge each branch into each other branch. Unless you plan
   to keep it simple and collapse (by merging and forgetting) branches
   quickly, they are not to be created lightly.
   
   In other words, if you don't regularly attend group meetings in which
   the branch to be worked on is a major topic of discussion, then the
   group is not managing branches properly.
   
   We created a couple major branches a few months ago and even the
   customer service people refer to the "XYZ branch" as a shorthand for
   "continuing development on the XYZ project".
   
   Last modified: _6/13/1997_
   
    11. How do I refer to the revision where I branched so I can see what
    changed since the Branch Point on another branch? 
    
   Given the current <branch_tag> format, there is no direct way to refer
   to the branch point, which is more useful in many ways than referring
   to the branch, which always refers to the latest revision on the
   branch.
   
   When CVS adds a branch tag, it attaches an RCS symbol to a
   non-existent revision number containing the revision number of the
   branch point as a prefix. (See Section 3O, on the "tag" command.) RCS
   can't use the CVS magic branch tag and many of the CVS commands can't
   refer to it.
   
   To be certain of your ability to refer to a branch point, you must
   create a "branch point" tag at the same time as the Branch tag. See
   4C.3.
   
   Last modified: _6/13/1997_
   
    12. Why didn't the command "cvs admin -bBRANCH1 *" create a branch? 
    
   Because your command creates an RCS branch, not a CVS branch. See the
   above discussion on branches. RCS branches are used to support CVS
   branches, but they are not the same. You can't act as if you have
   direct control over the RCS files.
   
   The "admin" command was placed there as a convenience to allow you to
   execute raw "rcs" commands on the Repository, taking advantage of
   CVS's ability to find the files in the Repository.
   
   But you have to remember that you are using RCS commands on a CVS
   Repository, which is not generally safe unless you know exactly what
   CVS depends on.
   
   For one thing, CVS insists on control of the default branch. It is set
   either to the Main branch or the Vendor branch depending on whether
   you have changed the Vendor's code. If you change the default branch,
   you are monkeying with the internals and you will get unexpected
   results.
   
   To set your "default CVS branch" to BRANCH1, you must use "checkout"
   or "update" with the "-r BRANCH1" option. Then you have changed CVS's
   idea of your "default branch", which has little to do with RCS's
   default branch.
   
   Last modified: _6/13/1997_
   
    13. Is it possible to set the "default CVS branch" for everyone? 
    
   No. It doesn't work that way.
   
   When using CVS, all administrative information (such as what branch
   you checked out) is stored in CVS sub-directories, local to the user.
   There is no global state, other than the description and logging files
   in the $CVSROOT/CVSROOT directory.
   
   You tell "checkout" or "update" what branch you want to check out via
   the "-r <tag>" option. The default is CVS's "Main Branch".
   
   I don't see a problem in *designing* a new way to indicate what branch
   you get by default, instead of the main one, but that's not how it
   currently works.
   
   Last modified: _6/13/1997_
   
    14. How do I perform a large merge? 
    
   Large merges require a bit more planning to be able to track what has
   happened in the inevitable cases where something goes wrong. No tool
   can force a "merge" to make perfect sense.
   
   Though you can handle the details in many different ways, the two ends
   of the spectrum of merge techniques are: gonzo and paranoid.
   
     The gonzo method assumes that you know everything about your sources
   so that recovery from failures is "just a matter of typing." You
   created the branch this way:
   
                cvs checkout <module>
                cd <module>
                cvs tag -b <branch_tag>
                cvs update -r <branch_tag>
                >>> Edit away.
                cvs commit              <<== Onto branch

   Now you want to merge your branch back into the Main branch, you are
   certain you can make it work, or at least detect all the failures, so
   you dive in and hack away: (For simplicity, we will assume you are
   collapsing (i.e. merging and forgetting) a side-branch into the Main
   branch from your single working directory.)
   
                cvs update -A
                cvs update -j <branch_tag>
                >>> Edit the 'C' files and remove the overlaps.
                >>> Edit some more to make it all compile and work.
                cvs commit

   Looks simple. For more details on the output from the "update -j"
   command, see 3P.2 and 4C.6.
   
   Note: You could also checkout a whole new working directory and
                 perform the merge at the same time by replacing the two
                 update commands with these two commands:

                        cvs checkout -j <branch_tag> <module>
                        cd <module>

     The paranoid way is more difficult, but it can catch all sorts of
   problems. You created the branch this way:
   
                cvs checkout <module>
                cd <module>
                cvs tag <branch_point_tag>
                cvs tag -b <branch_tag>
                cvs update -r <branch_tag>
                >>> Edit away.
                cvs commit              <<== Onto branch

   The extra tag command places a non-branch tag on the Branch Point, an
   act that makes it easier to do "diffs" later. Now we decide to perform
   the merge:
   
                cvs tag <latest_on_branch_tag>
                cvs update -A
           *1*  cvs diff -r <branch_point_tag> -r <latest_on_branch_tag>
                >>> *1* shows all the changes on the branch.
           *2*  cvs diff -r <branch_point_tag> -r HEAD
                >>> *2* shows the changes on the trunk since branching.
                cvs tag <premerge_tag>
                cvs update -j <branch_tag>
                >>> Edit the 'C' files and remove the overlaps.
           *3*  cvs diff
                >>> Verify that *3* matches *1*, except for line numbers.
                cvs commit
                cvs tag <just_merge_changes_tag>
                >>> Edit some more to make it all compile and work.
                cvs commit
                cvs tag <after_merge_cleanup_tag>

   The reason *3* and *1* match so closely is that they are the
   differences between two pairs of starting points and ending points
   after the same data was inserted. If they are significantly different,
   you will want to figure out why.
   
   NOTE: You will have to tell everyone to stay the hell out of the
   Repository while you do this. If they commit something while you are
   in the middle of a merge, your job will be much more difficult. If
   they "update" at the wrong time, their work will be randomized until
   you finish. It's better to call a halt.
   
   See 3H.13 for some more information about dealing with merges after
   import. The last part of the procedure is applicable to any large
   merge.
   
   Last modified: _6/13/1997_
   
    15. Is a Vendor merge any different from a branch merge? 
    
   No. In most ways, a Vendor branch is exactly the same as any other
   branch. In a Vendor merge, the data is append to the branch by the
   "import" command, rather than by hand-editing, but the merge process
   is the same.
   
   See the "import" command in section 3H.
   
   Last modified: _6/13/1997_
   
    16. How do I go back to a previous version of the code on a branch? 
    



        You can avoid digging into RCS revision numbers (executing "update
        -r (rev)" on each file) by trying one of these:

Use non-branch tags as you normally would.  Non-branch tags
           attach to specific revisions, so a "tag (tag)" command would
           mark the revisions you have in your working directory, which
           are on your branch.  If you need to retrieve them, use "update
           -r (non-branch-tag)"

           Doing this overrides the sticky (branch-tag) attached to your
           working directory with a non-branch tag, which means you won't
           be able to commit until you again move forward to the end of
           the branch with "update -r (branch-tag)".

Use the "update -r (branch-tag):(date)" trick.

           This is almost like using the '-D' option, but it looks for
           revisions extant on (date) only along the given branch.

           As in #1, you can't commit to this kind of working area,
           because it has a sticky date referring to revisions in the
           middle of a branch.

[comment from the audience:  You are dreaming..
this does not work.. try it, you get
No such tag: "MYTAG:May 1"
or similar. I wish it did because I need it. julian@whistle.com]


You can branch a branch.

           If you add a branch tag to file in a working directory that was
           checked out on a branch, you will branch the branch.  This
           works just fine, though you'll have to play some games to merge
           everything back together again.  You'll also create 6-part
           revision numbers.  (They'll be 8-part revision numbers if you
           branch a branch that started out with some unmodified files on
           the Vendor branch.  Think about it.  How does revision
           1.2.4.2.4.2.2.1 grab you?)


(fixed formatting, kingdon@cyclic.com)

   Last modified: _9/8/1997_
   
    17. Once I've found the files I want, how do I start changing them? I keep
    getting warnings about sticky tags. 
    
   What you probably did was type "cvs update -r <tag>" where <tag> is a
   non-branch tag. "update" created a sticky tag for a specific revision,
   not a branch. To start working right there, you have to create a
   branch to work on.
   
   You have two choices.
   
     You can do it in place and keep working:
   
           cvs tag -b <branch_tag>      <<== To tag the current files.
           cvs update -r <branch_tab>   <<== To move onto the branch.

     You can do it "externally" and create a new working directory:
   
           cvs rtag -b -r <tag> <branch_tag> <module>
           cvs checkout -r <branch_tag> <module>

   <module> can be a relative path within the Repository.
   
   <tag> in the above is the non-branch tag you placed earlier
                 that caused the error in your question.  Be warned that
                 if <tag> is not set on all the files (or all the right
                 revisions) you won't get exactly what you wanted.

   Last modified: _6/13/1997_
   
    18. Why do I get the latest files on the branch when I tried to "update -r
    <tag>"? 
    
   If "update -r <tag>" always retrieves the latest files on a branch,
   then <tag> is really a <branch_tag>. A branch tag is supposed to be
   used to grab a branch to work on. Since you can't modify a file in the
   middle of a branch, checking out a <branch_tag> will give you the
   latest revision on the branch.
   
   If you want to "checkout" a specific collection of revisions, you must
   use a "non-branch" tag. See the first part of 4C.16.
   
   Last modified: _6/13/1997_
   
    19. How can I avoid a merge? I just want to move the latest revision on my
    working branch directly onto the trunk. 
    
   There is no direct way to do this using CVS, though the technique is
   not difficult using shell commands. Here's one way:
   
     Move your working directory to the Main Branch.
   
                cvs update -A

     Use "update -p" to grab the latest revision on the branch and write
   it over your working files. Make sure you don't have an modified files
   -- you will lose them. The following is in "csh" syntax. Change the
   wildcard to grab the files you want
   
   foreach i (Makefile *.cc *.hh)
                    cvs update -p -r <branch_tag> $i > $i
                end

     Commit all the working files onto the Main Branch.
   
                cvs commit -m 'Moved branch <branch_tag> onto MAIN'

   You should experiment with the above before blasting everything.
   
   Last modified: _6/13/1997_
   
    20. How to I avoid merge collisions in the RCS $\Log$ data? 
    
   In short, you can't. The RCS $\Log$ keyword is handled differently
   from all other RCS keywords.
   
   On the info-cvs mailing list, there is a periodic discussion that goes
   something like this:
   
   Question: How do I deal with $\Log$? Answer1: You can't do much with
   it. Here's how it works. . . Answer2: I've found a limited way to use
   it. . . Answer3: Get rid of it. $\Log$ is an abomination.
   
   I tend to lean toward answer #3. There are only two sets of people who
   would ever have access to logs stored within sources files, developers
   and source customers.
   
   For developers:
   
     Log entries within sources files are notoriously incomplete, rushed,
   poorly phrased and in many cases incorrect, making them useless for
   debugging or file maintenance. I remember a maxim from "Software
   Tools" (I believe): "Read the code, not the comments." No managerial
   order or plan for programmer discipline will affect this in the real
   world.
   
     Log entries are usually in an unreadable mixture of styles. Many log
   entries are just plain meaningless. Some are foolish. Some are even
   insulting. Examples:
   
   "Corrected spelling of misspelling." "Bug fix." "Reversed stupid
   change in previous revisions." "If Joe could do his job, this would
   already have worked."
   
     Log entries are not managed well by the tools. Any merge can cause
   conflicts in the $\Log$ data. Branch merges produce incomplete logs.
   They can be edited into chaos and they are not regenerated. They waste
   space duplicating information available to the developer with a single
   command.
   
     Even if correct when originally entered, as changes are made to the
   file, log entries become false over time. Humans are not good at
   reading down through a list and remembering only the last change
   affecting something. Over time *most* of the log is wrong.
   
     Even if still correct, the log data is almost useless to developers
   without the code diffs. If you can get code diffs, you can display the
   log.
   
   For source customers the problem is even worse. The last thing you
   want to show customers is a hodge-podge of tiny comments about large
   changes followed by a series of emergency fixes before delivery. If
   you distribute sources, then you should provide documentation, or
   changelogs reviewed by people who won't let comments like "Fixed for
   stupid customer." out the door.
   
   Conclusion: Though some people would prefer to see in this FAQ
   techniques for making the $\Log$ entries the best they can be, I
   believe them to be a lost cause. My suggestion is to hunt down, root
   out and destroy all occurrences of $\Log$ and the unusable data
   attached to it wherever you may find it.
   
   Last modified: _6/13/1997_
   
    21. Why should I trust automatic merges? 
    
   Some developers have the feeling that three-way merging doesn't work.
   They fear and distrust the way the "update" command automatically
   merges committed changes from the Repository into the working file.
   
   Experience has shown that most merges are utterly painless and most of
   the rest are easily resolved. The few conflicts that cause headaches
   are nearly all due to poor communication between developers, a problem
   no source control system can obviate.
   
   Some developers were troubled in the past by flaky Unix software. I
   can't say that everything is perfect, but the tools CVS depends on
   (RCS and diff, mainly) are fairly solid nowadays. They work.
   
   Since it does seem to work for most of us, the algorithm is unlikely
   to change soon. Why not test it on a couple trouble spots and if it
   works for you, use it for a while? Then you can make an informed
   decision.
   
   Last modified: _6/13/1997_
   
    22. How does CVS decide if it can safely perform a merge? 
    
   CVS can merge any text file, possibly discovering a conflict and
   leaving overlaps for you to edit. Editing the conflict markers out of
   the file is a moment's work, but resolving the conflict could take an
   arbitrary amount of time. CVS works to determine if it *should* merge,
   not if it *can*.
   
   See 2B.6 for how the merge proceeds.
   
   Last modified: _6/13/1997_
   
    23. After resolving merge conflicts in a file, what if I want to keep my
    previous version, and not take any of the branch changes? 
    
   If you want to retain your previous version, a version on the MAIN
   branch greater than 1.1 (one you committed there), just throw the
   merged file away and "cvs update" the file.
   
   You don't need to commit something to remember it. The tags you place
   before and after the merge should give all the handles you need to
   find various versions. You don't have to create a new version of the
   file.
   
   If you want to retain the previous Vendor revision, you can grab a
   copy of it using "cvs update -p" and commit it or use the technique
   described in 3B.3 to revert back to the Vendor branch.
   
   Last modified: _6/13/1997_
   
  Category: /Advanced_Topics_/Engineering/
  
   " + Engineering"
   
    1. Where can I find out about Software Engineering? 
    
   A couple different people suggested this book:
   
   Software Configuration Management: Coordination for Team Productivity;
   Wayne A. Babich; Addison Wesley; 1986; ISBN 0-201-10161-0
   
   A number of others suggested Appendix B of the book "Decline and Fall
   of the American Programmer" by Ed Yourdon, called "The Programmer's
   Bookshelf". It list 87 books you are expected to have read. Since they
   publish many of the books, Prentice-Hall distributes this list as
   "Prentice Hall Professional Technical reference PTR-125-AA3.
   
   One interesting item from the Yourdon book: The total number of
   professional computer books sold is less than the number of
   programmers currently in the United States. It wasn't clear from the
   book whether this meant "per year" or not, but it is still
   frightening.
   
   Last modified: _6/13/1997_
   
    2. How do I flexibly arrange the modules file to describe my sources? 
    
   An equivalent question might be, "How do I structure my sources?" This
   can be a difficult question especially in the areas that are more
   political than technical.
   
   Generally you want to think about which pieces of your system need to
   be checked out together, built as one system or tagged as a consistent
   whole. You should certainly create module names that correspond to
   complete, buildable collections that you would tag and release as one
   "product". It is also convenient to create module names for small
   sections of the Repository containing files that will all be worked on
   at the same time by the same person or group.
   
   Once you have defined the structure of your work, you can usually see
   how to lay it out in a Repository. After that the modules file is
   easy. You set up module names and aliases to match what you need to
   check out by name. If you like relative directories, it is possible,
   but not recommended, to work completely without a modules file. See
   1D.11 and 2C.7 for some info about the modules file.
   
   Here are a few types of modules. You should experiment to see what
   kind of structure each of these produces. They all have different
   uses.
   
     Connected projects in one group with two separate helper
   directories. The helper directories can contain build tools, header
   files, libraries, or whatever you like.
   
   These are all aliases that checkout relative pathnames. The equivalent
   results could be produced by placing the selected relative pathnames
   on the "cvs checkout" command line.
   
           pr1  -a P1 HELPERS
           pr2  -a P2 HELPERS
           pr3  -a P3 HELPERS
           pr12 -a P1 P2 HELPERS
           pr13 -a P1 P3 HELPERS
           pr23 -a P2 P3 HELPERS

           P1           -a group1/proj1
           P2           -a group1/proj2
           P3           -a group1/proj3
           HELPERS      -a group1/helper1 group1/helper2 MAKEFILE
           MAKEFILE     -a group1/Makefile

   Actual Repository directory structure: (from $CVSROOT down)
   
   group1/ Makefile The top level Makefile. helper1/ helper2/ Helper
   files and dirs proj1/ Files and dirs proj2/ Files and dirs proj3/
   Files and dirs
   
   "checkout group1" produces a duplicate of the above. "checkout projX"
   produces all but "projY" and "projZ". "checkout projXY" produces all
   but "projZ".
   
     Here is the exact same set of module names describing the same
   Repository layout using module names (and aliases containing module
   names) instead of merely aliases for relative pathnames.
   
   There is one difference in the result. The name of the top level
   directory in the checked out working tree will match the "module" name
   (e.g. pr1) instead of always being "group1" as it was in the first
   example above.
   
           pr1  group1 proj1 &HELPERS
           pr2  group1 proj2 &HELPERS
           pr3  group1 proj3 &HELPERS
           pr12 group1 proj1 proj2 &HELPERS
           pr13 group1 proj1 proj3 &HELPERS
           pr23 group1 proj2 proj3 &HELPERS

           HELPERS      -a helper1 helper2 group1-Makefile
           helper1      group1/helper1
           helper2      group1/helper2
           group1-Makefile -d . group1 Makefile

   The above line (with the -d in it) says that when the module named
   "group1-Makefile" is checked out, the file named Makefile file will be
   found in a directory named $CVSROOT/group1 and will be checked out
   into a directory named '.', which obviously already exists.
   
   The & references say to interpret those pathnames relative to the
   directory where the whole module is stored. For the "pr1" module, that
   directory is "group1", so the &HELPERS reference winds up placing
   Makefile in '.' relative to "group1".
   
     A short one containing the basic "module" actions:
   
           m1           head/path file1 dir2 file3 dir4 file5

   When checked out, a directory named "m1" appears in your current
   directory. Elements named file1, dir2, file3, dir4, and file5 appear
   in it. They were originally taken as relative paths from
   $CVSROOT/head/path.
   
     Here's another way to construct a working directory out of pieces of
   the Repository:
   
                projX   projX Makefile &projX_inc &projX_src &projX_doc

                # The first line selects a single file within projX, plus
                # the contents of three other modules.  Those three other
                # modules rename their directories.

   projX_inc -d include projX/inc projX_src -d source projX/src projX_doc
   -d documentation projX/doc
   
     A Unix tree. This is similar to what CVS was developed for and the
   way I have used it for years.
   
                # Top level
                unix            unix
                u_bin           unix/bin
                u_etc           unix/etc
                u_man           unix/man
                usr-bin         unix/usr.bin

                # Subdirs of top level dirs.  (tiny subset)
                ls              unix/bin/ls
                fsck            unix/etc/fsck
                man8            unix/man/man8

                # Programs without subdirs. (tiny subset)
                cat             unix/bin Makefile cat.c
                uniq            unix/usr.bin Makefile uniq.c

                # /usr/local/src
                localsrc        localsrc
                gnu             localsrc/gnu
                public          localsrc/public
                X11             localsrc/X11

                # GNU and PD tools
                cvs             localsrc/gnu/cvs
                emacs           localsrc/gnu/emacs
                rcs             localsrc/gnu/rcs
                btoa            localsrc/public/btoa
                tcsh            localsrc/public/tcsh

                # X11 related items.
                tvtwm           localsrc/X11/contrib/tvtwm

   "unix" was checked out and built from the top down, using a set of
   Makefiles that knew about the whole structure. "localsrc" was kept
   checked out in /usr/local/src.
   
   At any time I could run "checkout ls" or "checkout cat" and get a
   simple directory with only that tool in it, plus a subset Makefile
   that knew how to build that tool against the installed (or alternate,
   via environment variables) headers and libraries.
   
   I found it very handy to be able to run "ls" and see the three tools I
   was porting that week.
   
   Last modified: _6/13/1997_
   
    3. Can I have multiple source repositories, one for each project? 
    
   Yes, you can have as many Repositories as you like. But each
   Repository must be managed separately, creating additional work.
   
   Question 4A.1 provides a short description of setting up a single
   Repository. A few additional considerations:
   
     It is a good idea to start by creating a single Repository and split
   it up (or create additional Repositories) only if you believe it is
   really necessary. I would only create a new Repository if the data is
   completely disconnected from the rest of the main Repository.
   
     If there is a lot of overlap among the developers working on the
   collections of files you want to place in different Repositories, or
   if there is any connection between those collections, I would go out
   of my way to create a single Repository. It is much easier to manage.
   
     Disk space should not be a factor since you can build up a
   Repository using symbolic links and/or remote mounts.
   
     Each Repository is completely distinct. You can't check out modules
   from different Repositories at the same time. A better way of looking
   at it is that if you *can* check out two modules or directories with a
   single "checkout" command (without contortions or explicit absolute
   pathnames), then they are in the same Repository.
   
     To "checkout" modules from multiple Repositories, you must use the
   "cvs -d" option on all CVS commands or alter your $CVSROOT variable
   when you change focus to another Repository. If you work with multiple
   Repositories, it is a good idea to configure CVS to use absolute
   pathnames in the ./CVS/Repository file, since most commands (other
   than "checkout") will use that file rather than $CVSROOT.
   
     If you configure CVS to use relative pathnames in your
   ./CVS/Repository files, you must always be careful to set your
   $CVSROOT properly or you will get unexpected results.
   
   If you have two modules or directories by the same name at the same
   relative path inside two different Repositories, you are asking for
   disaster. You could unexpectedly update a directory with completely
   unrelated files. This is not a fanciful example -- a Repository is
   occasionally duplicated for release purposes in which case *all* the
   paths in the two Repositories are the same.
   
   Last modified: _6/13/1997_
   
    4. Who should administer the Repository and manage the modules file? 
    
   This is a "management style" question. In large or traditional groups,
   the CVS procedures are warped to conform to local conventions. In
   small groups, in groups with strong personalities or on new projects
   the choice of source control procedures can help create some of the
   working environment. Here is a taxonomy of environments I have worked
   in or helped set up:
   
   Situation 1.
   
   A small number of competent developers working on a medium size
   project. We all got along and we all respected each other (at least
   technically). Anyone edited anything.
   
   Modules and Repository admin was mostly left to me. I never found a
   problem in minor changes made by anyone else.
   
   Situation 2.
   
   A large number of experienced developers sprinkled with wackos. Many
   of the developers didn't want to deal with any kind of source control.
   They wanted a full-service source control system that caused them zero
   thought.
   
   I learned "big stick" diplomacy here. There was a small number of
   "designated" (by me) people who were allowed to do *anything* other
   than "update" and "commit". Even "checkouts" were controlled. This is
   where I found "history" and "release" the most useful.
   
   Situation 3.
   
   A small number of developers who wanted me to "help", but who didn't
   want to deal with anything other than their favorite algorithms.
   
   I didn't have the time to baby-sit this group, so I designated one of
   them to be my official contact and made him do it all. He felt sullied
   by the requirement to pay attention to anything other than his pet
   coding projects, but enjoyed the "status" of being the only one who
   could touch the control files without my kicking the chair out from
   under him.
   
   Situation 4.
   
   A huge number of developers of covering the whole spectrum of
   competence and experience split into 20 groups, none of which
   cooperated with the others, working on 57 different projects, most of
   which didn't inter-operate.
   
   Managing it in any coherent way was not my responsibility (and beyond
   my tolerance for chaos). Too many people. So I privately designated a
   person in each group to be the contact and kept watch on the
   Repository activity. When something went wrong, I notified the contact
   for the group and told him what was happening and *he* kept his troops
   in line. They were tougher with their own group that I would have
   been.
   
   Eventually only a few people were willing to touch the control files,
   since they were flamed from all directions if they screwed up.
   
   Situation 5.
   
   In a medium group of really *serious*, and seriously overworked,
   people, someone else was designated the "master". I convinced the
   master I knew what I was doing and went on my way.
   
   No one else in the world was allowed to touch anything.
   
   Situation 6.
   
   In a large amorphous group of beginners, experts and clowns, over whom
   no one had official control, I was forced to employ a group of
   relative beginners (who became experts rather quickly) to police the
   world. The ultimate in locking the barn after the horse was stolen, we
   kept Chaos from destroying us only by use of superior firepower.
   
   My choice, if allowed, is to let anyone touch anything. I keep backups
   of important items and let people know individually whether I want
   them to touch things or not. If someone on my "no touch" list touches
   and succeeds, they are allowed more slack. If they screw up after
   being warned, their screwup becomes public. After a few months, I
   usually have no trouble keeping the world running smoothly, at least
   from my (and CVS's) perspective.
   
   Last modified: _6/13/1997_
   
    5. Isn't disk space a big factor? CVS copies files out of the Repository,
    duplicating everything. 
    
   Everyone knows that disk space is getting cheaper. How do we reconcile
   this with the equally well-known problem that *all* disk is *always*
   filled up?
   
   In my opinion, the main reason disk space will never be an unlimited
   resource is that it is the major variable in organizational time/space
   tradeoffs. It isn't a problem of waste or an aspect of Murphy's law,
   as some claim it is, but rather a direct consequence of good
   management. Disk space is, and will always be, a limited resource.
   
   First, the cost of *deploying* that disk is not dropping as fast as
   the cost of the storage medium. The cost of machines to hold the disks
   and the networks to connect them are dropping more slowly than disk
   media. And the cost of the human time necessary to manage the
   machines, networks, disks, and the developers using them, is not
   dropping at all. The cost of human time continues to rise.
   
   If management decides that expensive human time can be saved by using
   all that new disk space to keep the last three releases online, then
   that's what it will be used for. If each release takes up a Gigabyte
   and you support 30 platforms, a simple time-saving suggestion has just
   grabbed 100 Gigabytes of disk space. And we've ignored the potential
   disk storage needed to support "better Customer Service", another
   management refrain.
   
   Even at 30 cents per Megabyte (next year's price), you've just used up
   $30,000 of disk space. And that doesn't count the computers, tape
   drives and humans necessary to maintain and deploy all of it. Spending
   money to save time has its own overhead, too.
   
   Binaries are getting bigger. Graphics and data collection devices can
   eat up any amount of disk. There are more tools available, more
   libraries, more raw data than you can ever store. My home computer has
   a Gigabyte of disk on it. It could easily handle 30.
   
   The "economy" of disk storage media will never remove the need to
   manage disk space.
   
   So, here's an un-reviewed suggestion originally from Graydon Dodson
   <grdodson@lexmark.com>, which I've altered and edited heavily.
   
   - Keep a directory where the whole tree is checked out. (It might be
   built and tested once in a while to make sure it is worth linking to,
   but that doesn't affect the source control aspect of this procedure).
   Let's call it /master/build.
   
   - Write a tool that creates a tree of directories (like the X11
   "lndir" command) filled with links to the checked out files in the
   /master/build tree.
   
   This tool should also provide real copies of, not symlinks to, all the
   files within the CVS administrative directories.
   
   - You could also provide a way for the tool to take a list of whole
   directories that you will never change, for which it would create a
   single symlink to the directory and not a subtree of symlinks to
   files. Or you could rm -r pieces of the resulting working directory
   yourself and replace it with links.
   
   - If you want to edit a file, you have to grab a real copy and keep it
   until your revision shows up in the /master/build tree. I'd create a
   script to do this: cvsgrab <file>
   
                #!/bin/csh -f
                set f = $1
                if (! -l $f) then
                   echo "file $f is not a symlink"
                   exit 1
                endif
                rm $f
                set rev = `grep "^/$f/" CVS/Entries | awk -F/ '{print $3}'`
                cvs update -p -r $rev $f > $f

   You can't do a plain "cvs update" since that would grab newer
   revisions from the Repository, not the revision you wanted to start
   with. After the file is no longer a symlink, you can work normally.
   You'll have to run "update" before "commit" anyway if there are newer
   revisions.
   
   - Presumably there would also be a tool to traverse the link tree and
   revert it to links if there are no modified files and/or if all the
   real files match the revision of the /master/build tree.
   
   - To avoid confusing CVS when the /master/build revisions are updated
   but your CVS/Entries files is not, CVS would have to change to handle
   symlinks. It currently causes problems with this scenario:
   
     ./<file> is a symlink.
   
     ./CVS/Entries says you are revision 1.2.
   
     The corresponding CVS/Entries file in /master/build says the latest
   revision is 1.3.
   
     cvs update <file> shows a 'C' conflict flag.
   
   Last modified: _6/13/1997_
   
  Category: /Advanced_Topics_/Installing_CVS/
  
   " + Installing CVS"
   
    1. What do I have to do before I install CVS? 
    
     You must decide where to set up a Repository.
   
   Though you can construct a Repository tree structure using links and
   mount points, there must be a single copy of each real file across
   your entire organization. You may not "rdist" files and expect to edit
   both copies.
   
   CVS does not support a truly distributed Repository. You can have
   multiple Repositories, but each one must be mounted (not copied or
   "rdist"ed) from a single place onto all machines where it will be
   used.
   
   Initially, a Repository takes about same amount of disk space as the
   sources you want to put into it, plus a bit of overhead for the RCS
   files.
   
   See Section 4B. For multiple Repositories, see 4G.3
   
     You need a directory in everyone's $PATH variable where you can
   install all the executables. /usr/local/bin is a common place.
   
     You need some helper tools besides CVS such as "RCS" and a good set
   of "diff" and "diff3" programs. See 1B.4 for suggestions.
   
     Read the README, INSTALL and ChangeLog files to see what you are
   getting into.
   
     Make sure you have versions of all the programs mentioned in the
   "cvs/src/options.h" and "cvs/src/rcs.h" files.
   
     Though you can probably muddle along without it, you should appoint
   one or more "Repository Administrators" who will be responsible for
   maintaining the Repository structure, administrative files and the
   "modules" interface.
   
   Someone at your site should probably be on the info-cvs mailing list.
   See 1B.5.
   
   Last modified: _6/13/1997_
   
    2. How do I configure the CVS programs? 
    
     You should certainly start by reading the README file, the INSTALL
   files and possibly the ChangeLogs in each directory, the Makefile.in
   files and the "cvsinit.sh" program.
   
     Edit the "options.h" file in the "src" directory.
   
   You might need to specify a few site-specific pieces of information
   including the names of a number of functions.
   
   Hint1: You probably want to set the DIFF macro to use your version of
   the GNU diff program with the '-a' option. Ours is set to "gdiff -a".
   
   Hint2: You want to use RCS 5.6.0.1 or greater and set the "HAVE_RCS5"
   macro.
   
     Execute the ./configure command.
   
     Type "make".
   
     After running "make" you might try running the "sanity.sh" script:
   ./src/sanity.sh `pwd`/src/cvs
   
   It writes into /tmp/cvs-sanity by default.
   
     Finish reading the INSTALL file and test out the system.
   
   Last modified: _6/13/1997_
   
    3. What do I have to install? 
    
     Install the "cvs" executable and "mkmodules" from the CVS sources.
   The man page is useful too. If you plan to report bugs, you should
   also install "cvsbug".
   
     Make sure you have versions of all the programs mentioned in the
   options.h file, most of which are included in a standard Unix system.
   
     Unless you plan to reimplement RCS [:-)], you must install RCS.
   
   It is a very good idea to examine the RCS installation instructions
   and make sure you are using the GNU versions of "diff" and "diff3" or
   merges (an important part of CVS) will not work as well as you'd like.
   
     Set your $CVSROOT environment variable and create the Repository
   (which you planned out in 4A.1) with the "cvsinit" command at the top
   of the CVS sources.
   
     You'll need to edit the Repository control files created by
   "cvsinit".
   
     Install any helper programs mentioned in the modules file.
   
   Last modified: _6/13/1997_
   
    4. How do I work around the merge problems in GNU diff version 2.1 or
    later? 
    
   See 1B.4 If you use recent versions of RCS and "diff", you won't run
   into the above. If you do, see 5B.8
   
   Last modified: _6/13/1997_
   
  Category: /Advanced_Topics_/Internal_errors/
  
   " + Internal errors"
   
    1. Explain: "ci error: unexpected EOF in diff output" 
    
   RCS versions earlier than 5.5 print the above error when a file does
   not end in a newline character. It can be caused by:
   
   - Editing with Emacs and not using "require-final-newline".
   - Committing a binary file.
   - Filesystem failures (NFS!) that put nulls in your file.
   
   The solution is to upgrade to RCS 5.5 or later. (Of course, this won't
   fix filesystem failures. It will merely allow RCS (and therefore CVS)
   to handle the file without error.)
   
   Last modified: _6/13/1997_
   
    2. Explain: "RCS file /Repository/module/file.c,v is in use" 
    
   This is an RCS error that occurs when its internal lock file has been
   left around by an RCS command interrupted by some sort of system
   crash, disk failure or SIGKILL signal.
   
   Go into the Repository and look for files with names similar to
   "file.c,v", usually starting with ',', '_' or '#'. Make sure they are
   really crash remnants and do not belong to transactions in progress --
   a recent last-modified timestamp is a good indicator of a live
   transaction. Delete them if they are old.
   
   Last modified: _6/13/1997_
   
    3. Explain: "co error, line 2: Missing access list" 
    
   This is an error message from RCS Version 3 when it tries to read a
   file created by a later version of RCS.
   
   HP decided to "standardize" on an ancient version of RCS some time
   ago. You can't use it for CVS. See 4H.6.
   
   Since the error comes from having a later version of RCS than HP
   supports, you probably did install the later version but must have
   recently changed your $PATH or installed the HP package that has RCS
   in it.
   
   You should either reconfigure CVS to use absolute pathnames to the
   proper versions of the RCS programs that CVS uses, or change your PATH
   to look there first. If you haven't installed the latest version of
   RCS, you should upgrade. See 1B.4
   
   Last modified: _6/13/1997_
   
    4. Explain: "error: RCS file name `xyz .c' contains white space" 
    
   RCS 5.6 doesn't allow white space in filenames. Apparently this
   restriction will be removed in RCS 5.7, but CVS may still require that
   filenames have no white space in them.
   
   Last modified: _6/13/1997_
   
    5. Explain: cvs checkout: warning: <X> is not (any longer) pertinent 
    
   This message occurs in three instances:
   
     When there is an entry in the ./CVS/Entries for file <X> and there
   is no RCS file in the Repository to back it up.
   
   If the working file exists, and hasn't changed (determined from the
   timestamp) it is removed.
   
     When you try to check out a piece of the Repository with:
   
   cvs checkout some/place/in/repository/tree
   
   and at least the first element of the path (i.e. "some" in the above)
   exists, but some part of the rest of it does not.
   
   The checkout command checks the modules file first for the whole path,
   then for a prefix of the path as a module name. If it doesn't find
   *any* portion of your path in the modules file, it says:
   
                cvs checkout: cannot find module `<module/path>' - ignored

   If it finds some set of prefix directories, it prints the message you
   see.
   
   In practice this is usually a spelling error.
   
     If the Repository files you are trying to check out or update are
   not readable by you, the same problems can occur. Check the
   permissions on the files involved.
   
   Last modified: _6/13/1997_
   
    6. Why did a Repository file change from <file>,v to ,<file>,? 
    
   This is an RCS problem, since the ,<file>, syntax for file names is
   used by RCS and not CVS.
   
   RCS constructs a new <file>,v in a temporary file named ,<file>,
   (which doubles as a lock file) then renames it to <file>,v when it is
   done. The only way this is reliable is if your system's version of
   rename(2) is an atomic, as required by POSIX.
   
   If your system has a non-atomic (and therefore non-POSIX) rename(2)
   system call, RCS runs uses an internal version of this algorithm to
   approximate the atomic rename:
   
   rm <file>,v; ln ,<file>, <file>,v; rm ,<file>,
   
   If the system crashes, or you lose your NFS connection between the
   first "rm", but before the "ln", you can be left only with the
   ,<file>, file. If the crash or network failure occurs between the "ln"
   and the final "rm", you could be left with a pair of linked names.
   
   Recovery:
   - If only the ,<file>, exists, rename it to <file>,v.
   
   - If both ,<file>, and <file>,v exist and are linked, remove the
   ,<file>, file.
   
   - If both ,<file>, and <file>,v exist and are separate files, look at
   the dates, "diff" them and make your best guess. This sounds like the
   remnants of two separate events.
   
   Last modified: _6/13/1997_
   
  Category: /Advanced_Topics_/Other_Systems/
  
   " + Other Systems"
   
    1. I use a NeXT. Is there anything I need to know? 
    
   NeXTSTEP 3.0's Interface Builder uses "nib" directories, rather than
   the files used in previous revisions. It removes files it doesn't
   recognize, making it impossible to place such a directory under CVS --
   the CVS admin directory will be removed.
   
   Some time ago, <Bob_Vadnais@pdh.com> posted a palette named CVSPalette
   that claimed to resolve this problem. It was intended to preserve the
   CVS administrative directories within nib documents (directories) that
   Interface Builder usually removes.
   
   CVSPalette is no longer in its announced place:
   
                ftp.cs.orst.edu:/pub/next/submissions

   though I did find two other interesting files on ftp.cs.orst.edu:
   
                /software/NeXT/sources/tools/cvs-next-2_1_1.tar.Z

   which is a port of CVS 1.3 (along with RCS and diff) and:
   
                /software/NeXT/sources/programming/cvs.postamble-2.4.gz

   which appears to be a set of wrappers for CVS commands that claim to
   allow you to use CVS effectively (and without need for the "command
   line") on a NeXT machine.
   
   [[Anyone know the truth about CVS and NeXT?]]
   
   Last modified: _6/13/1997_
   
    2. I use OS/2 and/or DOS and/or Windows. Is there anything I need to know? 
    
   When using a local repository, be sure to specify the local access
   method or CVS will interpret the drive letter as a remote host name
   due to the : following it:
   
        WRONG:  CVSROOT=C:\SRC\CVSROOT

        RIGHT:  CVSROOT=:local:C:\SRC\CVSROOT

   (larry.jones@sdrc.com)
   
   You can share RCS files between Unix and DOS while avoiding the MS-DOS
   file name limits by setting your RCSINIT environment variable to
   '-x/,v'. New RCS files will be created without the standard ",v"
   suffix, though files ending in ",v" will still be found if there is no
   matching file in the same directory without the ",v".
   
   Erik van Linstee offers an OS/2 and a DOS port of CVS 1.3 in:
   
   ftp.informatik.tu-muenchen.de:/pub/comp/os/os2/gnu/devtools or
   ftp.rrzn.uni-hannover.de:/pub/os2-local
   
   The files are named:
   
                cvs13p?[bs].zip

   Where the ? stands for the patch level (currently 8) and the b is for
   the binaries, the s for the sources.
   
   There are three binaries. An OS/2 only one (32-bit), a DOS only one
   (16-bit) and an EMX one that runs on both (32-bit).
   
   There are many differences between the Unix and the DOS versions of
   CVS. Read the material that comes with the DOS version before using
   it.
   
   [[Updates?]].

   Last modified: _9/22/1997_
   
    3. I use SCO Unix. Is there anything I need to know? 
    
   On SCO/UNIX 3.2 V2.0 POSIX signals don't work. Unfortunately the
   configure program detects POSIXness and configures in the use of POSIX
   signals. Workaround : Edit out the check for POSIXness in the
   configure script. [[You could also remove all occurrences of
   "-DPOSIX=1" from the Makefiles after configure is run. -dgg-]]
   
   SCO/UNIX doesn't understand #!/<some shell> syntax. This breaks the
   use of log.pl as it gets invoked by /bin/sh instead of
   !#/usr/local/bin/perl. WorkAround : edit log.pl and change it into a
   shell script which invokes perl with log.perl (renamed from log.pl) as
   input.
                                Contributed by Joe Drumgoole

   Last modified: _6/13/1997_
   
    4. I use AIX. Is there anything I need to know? 
    
   The only report on AIX claims to have no trouble using it in concert
   with SunOS and IRIX platforms.
   
   Last modified: _6/13/1997_
   
    5. I use IRIX. Is there anything I need to know? 
    
   If you see "uid" numbers where you would expect user names, try adding
   -lsun to the link line. Without it CVS is unable to retrieve "passwd"
   data through NIS.
   
   Last modified: _6/13/1997_
   
    6. I use an HP system. Is there anything I need to know? 
    
   HP distributes RCS version 3 (a circa 1983 release!) with HP-UX. CVS
   does not work with RCS version 3; it requires RCS version 4 or later.
   Your best bet is to find the latest version of RCS and install it
   somewhere.
   
   HP-UX 8.07 has a serious bug with the mmap system call and NFS files;
   the bug can crash the operating system. Make sure that you configure
   RCS to avoid mmap by setting has_mmap to 0 in RCS's conf.h. This bug
   is fixed in HP-UX 9.
   
                                Contributed by Paul Eggert

   If using the setgid() trick described in 4D.13, you will have to
   create an entry in the /etc/privgroup file to give the group assigned
   to the cvs executable setgid permission (see setprivgrp(1m)).
   Additionally, if you are restricting "read" access to the Repository
   by limiting access to the executable (this requires yet another
   group), then you will require that /etc/logingroup exists and is
   configured correctly (usually it's just alink to /etc/group).
   
                                Contributed by Dale Woolridge

   Last modified: _6/13/1997_
   
    7. I use AFS. Is there anything I need to know? 
    
   There is a problem with the way CVS performs its locking when the
   files are within AFS. When your current PTS id != your uid, the locks
   are not deleted. The stat() system call returns the PTS id of the
   owner. If that id != your uid, CVS assumes you did not lock it, and
   leaves the lock files alone. The next time you try to use it, it
   complains that someone has the repository locked.
   
                                Contributed by Michael Ganzberger

   [[This was against CVS 1.3. Is it still in CVS 1.4?]]
   
   Last modified: _6/13/1997_
   
    8. I use A/UX. Is there anything I need to know? 
    
   [[??]]
   
   Last modified: _6/13/1997_
   
  Category: /Advanced_Topics_/Related_Software/
  
   " + Related Software"
   
    1. How do I use CVS under Emacs? Is there an Emacs cvs-mode? 
    
   The pcl-cvs package distributed with CVS is an emacs package that
   helps with the update/commit process. When you are ready to update,
   you use the 'cvs-update' command within emacs. This executes "update"
   and fills a cvs-mode buffer with a line for each file that changed.
   The most helpful features are: descriptive words for what happened
   (i.e. Merged or Conflict rather than 'U' or 'C'), single keys bound to
   diffs and commits, and the ability to mark arbitrary groups of files,
   possibly from different directories, for commit as a whole.
   
   All the developers in my group that use emacs find pcl-cvs a much
   friendlier and more helpful way to update/commit than raw cvs. One vi
   user even converted to emacs just to use pcl-cvs.
   
                                Contributed by Jeffrey M Loomis

   Last modified: _6/13/1997_
   
    2. What is GIC (Graphical Interface to CVS)? 
    



        GIC provides a graphical user interface to the Concurrent Version
        System (CVS), a powerful revision control system.  GIC is
        implemented in the Tcl/Tk programming language and is intended to
        augment the sometimes cumbersome CVS command line interface.
        
        Note that according to the official GIC page at
        http://www.cpsc.ucalgary.ca/redirect/grouplab/projects/gic/
        GIC is no longer being maintained and tkCVS is recommended
        instead.  For more on tkCVS, see http://www.cyclic.com/tkcvs/

        kingdon@cyclic.com

   Last modified: _9/6/1997_
   
    3. What is CAVEMAN? 
    
   CAVEMAN is a front end to CVS written in PERL providing a collection
   of features desired by the site where it was developed.
   
   - The ability to spread a "project" over multiple Repositories.
   - Optional automatic tagging after each commit.
   - Additional locking of files.
   - Extra before and after program hooks.
   - A layer of event logging.
   - All sorts of error messages.
   - Many changes to the semantics of commands.
   
   It is available via anonymous ftp on ftp.llnl.gov [128.115.54.18] in
   gnu/caveman_vX.Y.Z.tar.gz (The numbers X, Y, & Z vary.)
   
   contact Kathleen Dyer kdyer@llnl.gov
                                (510)423-6803
                                (510)423-5112 FAX

   [[Does someone want to elaborate?]]
   
   Last modified: _6/13/1997_
   
  Category: /Advanced_Topics_/Setting_up_and_Manag/
  
   " + Setting up and Managing the Repository"
   
    1. What do I do first? How do I create a Repository? 
    
   First, install all the programs. (See Section 4A.)
   
   Then create a Repository by executing "cvs -d init". (This works with
   CVS 1.9.)
   
   Now you can configure your repository by checking out CVSROOT: "cvs -d
   checkout CVSROOT". Change into the created directory CVSROOT. Edit the
   files you want to edit, and afterwards, commit the changes by typing
   "cvs commit".
   
   You will certainly want to add modules of your own. Edit the "modules"
   file and add lines to describe the items you want to "checkout" by
   module name. Here's a short list that could be used for storing a
   small number of GNU and PD sources:
   
                local   local

                gnu     local/gnu
                emacs   local/gnu/emacs
                cvs     local/gnu/cvs

                public  local/public
                pdprog1 local/public/pdprog1
                pdprog2 local/public/pdprog2

                test    test
                junk    test/junk

   Andreas Kostyrka
   
   Last modified: _4/21/1998_
   
    2. What are those files in $CVSROOT/CVSROOT? 
    
   There are eight Repository control (or "database") files of interest
   in the CVSROOT directory:
   
     modules contains the "modules" database. See 1D.11, 2C.7, 4B.6 and
   4B.7 for more details.
   
     commitinfo contains two columns: 1. a regular expression to match
   against pathnames within the Repository and
   
     a <command> to execute for matching pathnames.
   
   When you execute "commit", CVS passes the Repository pathname for each
   directory (and the files to commit within that directory) to
   <command>. If <command> exits with a non-zero status, the commit is
   blocked.
   
   A <command> associated with a pathname of "DEFAULT" is executed if
   nothing else matches. Every <command> associated with a pathname of
   "ALL" is executed separately.
   
     rcsinfo contains the same first column as commitinfo, but the second
   column is a template file for specifying the log entry you are
   required to enter for each commit.
   
   "DEFAULT" and "ALL" work the same as in the commitinfo file.
   
     editinfo contains the same two columns as commitinfo, but the
   <command> in the second column is intended to do some consistency
   checking on the commit log.
   
   "DEFAULT" works as in commitinfo.
   
     loginfo contains the same two columns as commitinfo, but the
   <command> is expected to read a log message from its standard input.
   The <command> can do anything it wants with the log information, but
   normally it is appended to a log file or sent to mailing lists.
   
   "DEFAULT" & "ALL" work the same as in commitinfo.
   
     cvsignore contains "ignore" patterns that are added to the built-in
   ignore list. See 2D.10.
   
     checkoutlist contains a list of other files kept under RCS in
   $CVSROOT/CVSROOT that should be checked out by mkmodules to provide a
   readable copy.
   
     history contains a stream of text records, one for each event that
   the "history" command is interested in. Though the contents of the
   history file can be read, it is intended to be read and displayed by
   the "history" command. This file is the only one in the above list
   that is not under RCS.
   
   Last modified: _6/13/1997_
   
    3. Is there any other state stored in the Repository besides in the
    $CVSROOT/CVSROOT directory? 
    
   Only in the RCS files. The Repository holds exactly two things: the
   tree of RCS files (each usually ending in ",v") and the CVSROOT
   directory described above.
   
   Last modified: _6/13/1997_
   
    4. How do I put sources into the Repository? 
    
   There are three main ways to put files in the Repository:
   
     Use the "import" command described in Section 3H.
   
   This method is the fastest way to put trees of new code into the
   Repository and the *only* way to handle source releases from a 3rd
   party software vendor.
   
     Use "add" followed by "commit".
   
   This is how to add new files and directories to the Repository, a few
   at a time. Directories don't need to be committed.
   
     You can move RCS files directly into the Repository.
   
   You should create a directory hierarchy to hold them, but you can just
   move arbitrary ",v" files into the Repository. The only "state" in the
   Repository other than within ",v" files is in the required CVSROOT
   directory at the top of the Repository.
   
   Last modified: _6/13/1997_
   
    5. What file permissions should I use on (and in) the Repository? 
    
   If you are using pserver (password-authenticated access), see below.
   
   If you run a completely open environment (which usually means that you
   don't have, or don't want to waste, the time to deal with it):
   
   - Set all directory permissions to 777.
   
   - Have everyone set their umasks to 0.
   
   (BTW, I don't suggest this. I am merely reporting it.)
   
   If you are a normal Unix shop and want to use groups effectively:
   
   - Set all the directory permissions in the Repository to 775.
   
   If you are using a system that handles both System V and BSD
   filesystems, you might have to set the permissions to 2775.)
   
   If you are using one of the many recent versions of Unix that don't
   allow you to use the full octal mode, then you'll have to type: chmod
   u=rwx,g=rwx,o=rx,g+s dir&gt;
   
   - Change all the groups on the directories to match the groups you
   want to write to various directories.
   
   - Make sure every user is in the appropriate groups.
   
   - Have everyone set their umask to 002, including root.
   
   If you don't want non-group members to even read the files, do the
   above, but change:
   
   - Repository directory permissions to 770. (or 2770)
   
   - umasks to 007.
   
   If you work in an environment where people can't be trusted to set
   their "umask" to something reasonable, you might want to set the umask
   for them:
   
                mv /usr/local/bin/cvs /usr/local/bin/cvs.real
                cat > /usr/local/bin/cvs
                #!/bin/sh
                umask 2         # Or whatever your site standard is.
                exec /usr/local/bin/cvs.real ${1+"$@"}
                ^D

   Pserver (Password-Authenticated Access) &lt;blome@de.ibm.com&gt;
   
   The above suggestions are not valid when you use the pserver facility.
   Be sure to read and understand the manual section about this (should
   be 4.6.something). Above all: do /not/ make the repository and CVSROOT
   group writeable. In CVSROOT, make `history´ group or world writeable
   instead.
   
   I suggest creating one unix group per project group. In the
   repository, you would then create one directory for each group, group
   writeable. New projects must then be created in these group
   directories. If you don't want to say &lt;group&gt;/&lt;project&gt; on
   checkout, create a &lt;project&gt; module and point it there.
   
   Last modified: _9/24/1998_
   
    6. How do I structure my Repository? 
    
   The Repository holds your software. It can be all interrelated or it
   can be a bunch of separately managed directories.
   
   How you break a whole system down into its component parts, while
   defining interfaces between them, is one aspect of "Software
   Engineering", a discipline that requires the study of dozens of
   strange and wonderful areas of the computer and management worlds.
   
   CVS provides a way to keep track of changes to individual files, a way
   to "tag" collections of files, and a way to "name" collections of
   files and directories. That's all. Everything else is in the way you
   apply it.
   
   In other words, you should structure your Repository to match your
   needs, usually tied in with the other tools you use to build, install
   and distribute your work. Common needs include the ability to:
   
   - mount (or automount) directories from many places in your
   organization.
   - check out just what you need and no more.
   - check out multiple sections in a fixed relation to each other.
   - check out large sections to match the assumptions built into your
   build system. (Makefiles?)
   
   In my opinion, you should start small and keep everything in one tree,
   placing each major sub-system into a separate directory. Later, when
   you know what you are doing, you can make it more sophisticated.
   
   Last modified: _6/13/1997_
   
    7. Why would anyone use "modules"? They are too restrictive. I want to be
    able to select just the files I want to edit. 
    
   Any form of structure is restrictive. If you believe that total chaos
   is a viable working paradigm, or if you believe you can keep track of
   the interrelations between all portions of your Repository in your
   head, then you can do what you please.
   
   If you believe that systems of files require management and structure,
   then the "modules" idea is very useful. It is a way to impose a naming
   scheme on a tree of files, a naming scheme that can be simpler than a
   large list of relative pathnames.
   
   The "modules" file represents a published interface to the Repository
   set up by your Repository Administrator. If s/he did a creditable job,
   the modules offered will be internally consistent and will smoothly
   interact with the rest of your environment.
   
   Last modified: _6/13/1997_
   
    8. How do I rename a file or directory? What are the consequences? 
    
   In CVS there is no single "rename" command.
   
   See 2C.4 for the suggested way to rename a file or directory.
   
   The rest of this section covers some of the consequences of renaming.
   
   A "renaming database" has been proposed that would keep track of name
   changes so that "update -r <tag>" would continue to work across the
   renaming. But as it stands, you have to pick one of the following
   options:
   
     Use the technique described in 2C.4. (For each file, duplicate the
   file in the Repository, "remove" the old version so it winds up in the
   Attic and strip all Tags off the new version.)
   
   - "update -r <tag>" produces the correct files.
   
   - The duplicated revision history can be slightly misleading.
   
   - A plain (i.e. without the "-r <tag>") "checkout" or "update -d" will
   create directories "renamed" this way, but you can delete it and a
   plain "update" won't bring it back.
   
     Move the files and directories in the Repository to the new names.
   
   - You save the revision history under a different file name.
   
   - You save a little space.
   
   - "update -r <tag>" produces the wrong files or directories.
   
   This is not a good general solution, but if you plan never to look
   back (someone may be gaining on you!), it is sometimes a useful
   notion.
   
   If you are clever with Makefiles, you might be able to rework them to
   handle either the new or old names, depending on which ones exist at
   the time. Then you can move an old <tag> onto the new, more
   sophisticated, revision of the Makefile. (Yes, this changes the
   "released" file if <tag> indicates a release. But it is an option.)
   
   - Important Note: If you rename a directory, you must rename the
   corresponding directory in every checked-out working directory. At the
   same time, you must edit the pathname stored in the ./CVS/Repository
   file within each of the moved directories.
   
   The easiest way to move a lot of directories around is to tell
   everyone to remove their working directories and check them out again
   from scratch.
   
   - The file exists in the working directory and in the ./CVS/Entries
   file, but not in the Repository. For the old file, "update" prints:
   
   cvs update: xyz.c is no longer in the repository
   
   and deletes the file. If the file was modified, "update" prints:
   
   cvs update: conflict: xyz.c is modified but no longer in the
   repository C xyz.c
   
   and leaves the file alone. In the new directory, you see:
   
   U xyz.c
   
   as you would if someone else executed "add" and "commit".
   
     For each file, copy the working file to a new name in the working
   directory and use the "cvs remove" to get rid of the old old file and
   "cvs add" to add the new one. Since there is no way for CVS to remove
   a directory, this only works for files.
   
   - This is what most people think of first. Without a "rename" command,
   the remove/add technique seems obvious.
   
   - You lose the connection of your new working file to its past
   revision history.
   
   Last modified: _6/13/1997_
   
    9. What are "Attic" directories? 
    
   When you use the "remove" command on a file, CVS doesn't delete the
   file, it only registers your desire to delete it.
   
   When you "commit" a removed file, CVS moves the Repository's matching
   RCS file into a sub-directory named "Attic" within the Repository.
   
   Attic files are examined when the '-r' or '-D' option is used on
   "checkout" or "update". If the specified revision, tag or date matches
   one on a file in the Attic, that file is checked out with the others.
   
   You can think of the Attic as a sort of dead branch, which is only
   looked at when you refer to a <tag> or <date>.
   
   Last modified: _6/13/1997_
   
    10. Is it OK to remove anything from the Repository? 
    
   In general, removing anything from the Repository is a bad idea. The
   information in a deleted object is lost forever. There are many ways
   to skip over files, directories and revisions without deleting them.
   
   Here are some of the consequences of removing the following things
   stored in the Repository:
   
     CVSROOT files (Repository control files)
   
   The Repository will work without any of them, but you should
   understand what you are losing by deleting them. See 4B.2.
   
     Revisions
   
   The only way to remove revisions is to use the "admin -o" command (or
   the equivalent RCS command "rcs -o").
   
   They are lost forever. Any tags formerly attached to deleted revisions
   are now pointing into the Phantom Zone. You'll need to contact Jor-el
   to get them back.
   
     Files
   
   You should not remove a file unless you truly never want to see it
   again. If you want to be able to check out an old revision of this
   file, use "cvs remove" instead.
   
     Tags
   
   Tags take up little space and you can't recover from deleting them. If
   you depend on tags for releases you will lose vital information.
   
     Directories
   
   There is no Attic for directories, so the only way to remove them is
   to use "rm -r". They are gone forever.
   
   If you delete (or move) a directory, all checked-out versions of that
   directory will cause CVS to halt. You'll have to visit each
   checked-out directory and remove the matching working directory by
   hand.
   
     Attic files
   
   The "remove" command sends files to the Attic. To really delete them,
   you have to go into the Attic and use "rm".
   
   If a file in the Attic has a Tag on it that you might ever want to
   check out again, you probably don't want to delete it.
   
     Lock files (named: "#cvs.[wr]fl.<pid>")
   
   These are lock files. If you are getting "lock" errors and the dates
   on the lock files indicate that they are old, you can delete them.
   
   Deleting lock files still in use by a CVS process might produce
   unusual errors.
   
   Last modified: _6/13/1997_
   
    11. Can I convert to CVS from RCS without losing my revision history? 
    
   Yes, you can simply move (or copy) your RCS files into a directory
   within the Repository, check out that directory and start working.
   
   Last modified: _6/13/1997_
   
    12. Can I move RCS files with branches in them into the Repository? 
    
   Yes, but they may not work if you created branches in a way that
   conflicts with CVS's assumptions:
   
     You can't use .0. branches. (They are reserved for "Magic" branch
   tags.)
   
     If you use branch 1.1.1, you can't use the Vendor branch.
   
   You can use other RCS branches under CVS. There is no need to create
   "magic" branch tags because the physical branch already exists.
   
   Last modified: _6/13/1997_
   
    13. Can I use raw RCS commands on the Repository? 
    
   You can use raw rcs commands directly on the Repository if you take a
   little care. The Repository itself contains no "CVS state" (as opposed
   to RCS revision histories) outside the CVSROOT directory.
   
   But using raw RCS commands to change branches, tags or other things
   that CVS depends on may render the files unusable.
   
   See 4D.7 on RCS/CVS sharing of the Repository and Section 3B on the
   "admin" command.
   
   Last modified: _6/13/1997_
   
    14. How do I convert from SCCS to RCS? 
    
   You'll have to execute something like "sccs2rcs" (in the CVS contrib
   directory) on every file. Then you can move the resulting RCS files
   into the Repository as described above.
   
   Last modified: _6/13/1997_
   
    15. How do I limit access to the Repository? 
    
   There are all sorts of ways to restrict access to Repository files,
   none of which are hooked directly into CVS.
   
   Techniques for limiting access include:
   
     Training, management and good backups.
   
   The best form of Repository control is a combination of:
   
   - A reliable backup scheme (verify it!)
   - Enough training to ensure your developers are competent and
   knowledgeable about all areas of your sources.
   - Effective management of the boundaries and grey areas.
   
   In many cases, technical solutions to "security" problems are
   inadequate. You should first try to avoid them.
   
   Personal Opinion: In an environment where "unknowns" are allowed to
   touch important sources the "owner" of the CVS Repository must be a
   large, loud, vigorous lout with a well-balanced truncheon and the
   right to use it. Don't underestimate the effectiveness of letting
   everyone know they will be strapped into the stocks on the Town Common
   and pelted with vegetables if they break something they don't
   understand without first asking the experts.
   
     Set Unix groups and permissions. See 4B.5. You can set different
   owners, groups and permissions for each sub-directory within the
   Repository if that helps.
   
     Catch invocations of "commit" by defining pre-commit programs in the
   "commitinfo" file. This is fairly powerful, since it can block commits
   based on anything you can program. Take a look at the programs in the
   "contrib" directory of the CVS source tree.
   
     Use multiple Repositories, each with its own protection scheme. If
   you use NFS (or AFS) you can even use "export" restrictions to various
   groups of machines to keep (for example) the Engineering Repository
   off the Customer Service machines.
   
     Try the "setgid" trick described in 4D.13.
   
     Try to use the RCS access control lists, though I don't think CVS
   will handle them cleanly.
   
     Edit the source code to CVS to add your own access control.
   
   Last modified: _6/13/1997_
   
    16. What are the Repository Administrator's responsibilities? 
    
   Generally, the Administrator should set "policy", create the
   Repository and monitor its size and control files.
   
   Some specific responsibilities include:
   
     Examining the Repository once in a while to clean up:
   
     Trash files left by misguided developers who mistake the Repository
   for a working directory.
   
     Non-RCS files. Other than the files CVS needs in the
   $CVSROOT/CVSROOT directory, every file in the Repository should be an
   RCS file.
   
     Lock files (both CVS '#*' and RCS ',*' files) left around after
   crashes.
   
     Wrong permissions, groups and ownerships.
   
     Locked files. (RCS locks, that is.)
   
     Attic files that should never have been under CVS at all. Don't
   blindly delete files from Attic directories -- they were mostly put
   there (via the "cvs remove") for a reason. Files that should be
   deleted are binary files (e.g. '*.o', 'core', executables) that were
   mistakenly inserted by "import -I !".
   
     Maintaining the modules file.
   
     Storing site-specific ignore patterns in the
   $CVSROOT/CVSROOT/cvsignore file.
   
     Storing the names of non-standard CVSROOT files (See 4B.2) in the
   $CVSROOT/CVSROOT/checkoutlist
   
     Maintaining the other Repository control files: commitinfo, loginfo,
   rcsinfo and editinfo.
   
     Pruning the history file every once in a while. (Try the
   "cln_hist.pl" script in the "contrib" directory.)
   
     Staying aware of developments on the info-cvs mailing list and what
   is available in the FTP and WWW archives.
   
     Running "ps ax" once in a while and kill off any "update" programs
   not running as "root". It is too easy to leave the "cvs" off the front
   of the "cvs update" command.
   
     Executing monitor programs to check the internal consistency of the
   Repository files. Ideas:
   
     Files that have a default RCS branch that is not 1.1.1 (From an
   abuse of "admin -b".)
   
     Files that have only Revisions 1.1 and 1.1.1.1, with a default
   branch of "MAIN". (From an abuse of "admin -o".)
   
     Existing branch tags and various branch consistency checks.
   
   Last modified: _6/13/1997_
   
    17. How do I move the whole Repository? 
    
   Copy or move the tree. (On Unix systems, a set of piped "tar" commands
   works great. If the Repository does not contain any symlinks, which it
   normally doesn't, you can also use "cp -r".)
   
   If you can avoid changing $CVSROOT (i.e. the "logical" pathname of the
   Repository) by replacing the old location with a symbolic link to the
   new location, you don't have to do anything else.
   
   (You could also mount the new location on top of the old location if
   you are using NFS or some other filesystem that allows it.)
   
   If you must change $CVSROOT, you must also tell everyone to change the
   CVSROOT environment variable in all running shells and in any personal
   configuration files ('.' files on Unix) where it is set.
   
   The Repository itself contains no references to its own name, except
   possibly in some of the files in the CVSROOT directory. If your
   modules (or loginfo, commitinfo, etc.) file mentions helper programs
   directly in the Repository, you'll have to change the pathnames to
   point to the new Repository location.
   
   The main changes you'll have to make are to all the CVS administrative
   files (./CVS/Repository and ./CVS/Root) in every working directory
   ever checked out from the previous location of the Repository you just
   moved.
   
   You have three choices:
   
     If all ./CVS/Repository files in all working directories contain
   relative pathnames, you don't have to do anything else.
   
     Have everyone "release" or delete their working directories (after
   committing, or just saving, their work) and check them all out again
   from the new Repository after the move.
   
     Use "find . ( -name Repository -o -name Root )" and a PERL or shell
   script to run through all the ./CVS/Repository and ./CVS/Root files
   and edit the values in the files.
   
   Last modified: _6/13/1997_
   
    18. How do I change permissions on a file in the Repository by using a CVS
    command? (i.e. without using "chmod 777 $CVSROOT/dir/file") 
    
   When you first "import" or "add"/"commit" a file, the read and execute
   bits on the Repository file are inherited from the original source
   file, while the write bits on the Repository file are are turned off.
   This is a standard RCS action.
   
   After that, there is no way to alter the permissions on a file in the
   Repository using CVS (or RCS) commands. You have to change the
   permissions on both your working file and on the Repository file from
   which it was retrieved.
   
   Whenever you "checkout" the file or retrieve a new revision via
   "update" (or after a "commit"), your working file is set to match the
   permissions of the Repository file, minus any "umask" bits you have
   set.
   
   Last modified: _6/13/1997_
   
  Category: /Advanced_Topics_/Tricks_of_the_Trade/
  
   " + Tricks of the Trade"
   
    1. How can you even check in binary files, let alone allow CVS to do its
    auto-merge trick on them? 
    

First of all, if you want to use binary files, you should get RCS 5.7
and CVS 1.9 or later (earlier versions had some support, but there have been
bug fixes).  Secondly, follow the instructions for installing RCS very
carefully (it is easy to get it installed so it works for everything
except binary files).

Then, specify 'cvs add -kb' instead of just 'cvs add' to add a binary
file.  If you want to set an existing file to binary, run 'cvs admin
-kb' (and then check in a new copy of the file).  Note that old
versions of CVS used -ko instead of -kb for binary files, so if you
see a reference to -ko in the context of binary files, you should
think -kb instead.

Of course when 'cvs update' finds that a merge is needed, it can't
do this for binary files the same way as for text files.  With the
latest versions (e.g. CVS 1.9.14), it should be able to give you both
versions and let you merge manually.  Another approach is to
run 'cvs admin -l' to lock files, as described in
"How can I lock files while I'm working on them the way RCS does?"
elsewhere in this FAQ.  See also
"Is there any way to import binary files?" and
"How do I "add" a binary file?" elsewhere in this FAQ.

kingdon@cyclic.com

   Last modified: _9/6/1997_
   
    2. Can I edit the RCS (",v") files in the Repository? 
    
   Yes, but be very careful. The RCS files are not free-form files, they
   have a structure that is easily broken by hand-editing. The only time
   I would suggest doing this is to recover from emergency failures that
   are difficult to deal with using CVS commands, including the "admin"
   command, which can talk directly to RCS.
   
   Though no one actively encourages the editing of RCS files, many
   people have succumbed to the urge to do so when pressed for time. The
   reasons given, usually with evident contrition, include:
   
   - Editing mistakes in, or adding text to, log entries. (If you have
   RCS 5.6 or later, you should use `cvs admin -m'.)
   - Renaming or moving symbolic names. (You should `cvs admin -N'
   instead.)
   - Unlocking a file by changing the "locker" from someone else to
   yourself. (It's safer to use `cvs admin -u -l'.)
   - Making global changes to past history. Example: Eradicating former
   employees names from old documents and Author entries. (And someone
   thought the "history" command was evidence of Big Brother! I never
   realized how much help a wide-open revision control system could have
   provided to The Ministry of Truth.)
   
   Last modified: _6/13/1997_
   
    3. Can I edit the ./CVS/{Entries,Repository,Tag} files? 
    
   Yes, but with CVS 1.3 and later, there is almost no reason to edit any
   of the CVS administrative files.
   
   If you move pieces of your Repository around it can be faster to edit
   all the ./CVS/Repository files rather than checking out a large tree.
   But that is nearly the only reason to do so.
   
   Last modified: _6/13/1997_
   
    4. Someone executed "admin -o" and removed revisions to which tags/symbols
    were attached. How do I fix them? 
    
   It depends on what you mean by "fix". I can think of three ways to fix
   your predicament:
   
     Remove the tags.
   
   Assuming you really wanted to get rid of the revision and its
   associated tags, you can remove them with the "admin" command. The
   "tag -d" command will only remove tags attached to existing revisions.
   You can remove a tag, even if it is attached to a non-existent
   revision, by typing:
   
                cvs admin -N<tag> <file>

     Retrieve the outdated revision.
   
   You should first look in your backup system for recent versions of the
   file. If you can't use them, you can carefully extract each revision
   that followed the earliest outdated revision using RCS (or "cvs
   admin") commands and reconstruct the file with all the right
   revisions, branches and tags. This is a lot of work.
   
   You *can't* insert a revision into the current RCS file.
   
     Move the Tags to another revision in each file.
   
   If you want to move the tags to another valid revision, you have two
   choices, both of which require that you find all the revision numbers
   of the files you want to "tag" and execute the following command
   sequences on each <file>.
   
     Use "update" to grab the revision you want, then execute a normal
   "tag" command to Tag that revision:
   
                        cvs update -r <rev> <file>
                        cvs tag <tag> <file>

     Use "admin" to set the tag to a specific revision:
   
                        cvs admin -N<tag>:<rev> <file>

   Last modified: _6/13/1997_
   
    5. How do I move or rename a magic branch tag? 
    
   (To rename a non-branch <tag> see 3O.9.)
   
   Before reading this, read 3M.3 and 3M.4 and understand exactly how tag
   and rtag use '-r' and why it won't do the right job here.
   
     First, I have to explain exactly what a magic branch tag is.
   
   A magic <branch_tag> is an artificial tag attached to a non-existent
   revision on a non-existent branch number zero. It looks like this:
   
                TAG1:<X>.0.Y

   <X> is the "branch point revision", a normal revision with an
                odd number of '.'s in it. (e.g. 1.5, 1.3.1.6, etc)

             Y  is an even number (e.g. 2, 4, 6, etc.)  All CVS branches,
                other than the Vendor branch, are even numbered.

   TAG1 is considered by CVS to be attached to revision <X>. The first
   "update -r TAG1 <file>" after applying TAG1 will produce a copy of
   revision <X> with a sticky tag of TAG1. The first "commit" to that
   file will cause CVS to construct an RCS branch named <X>.Y and check
   in revision <X>.Y.1 on the new branch.
   
   Note: TAG1 is *not* considered to be attached to <X> by RCS, which
   explains why you can't refer directly to the branch point revision for
   some CVS commands.
   
     Moving a magic <branch_tag> is the act of reapplying the same tag to
   different revisions in the file:
   
                TAG1:<X>.0.Y
           to
                TAG1:<X>.0.Z    or      TAG1:<A>.0.B

   You can move a magic branch tag to the revisions of your choice by
   using "update" to find the revisions you want to tag and reapplying
   the tag to all the files with the '-F' option to force it to move the
   existing <branch_tag>.
   
                cvs update -r <tag/rev>  (or '-A' for the Main Branch)
                cvs tag -F -b <branch_tag>

   If the earlier location of TAG1 refers to a physical branch within any
   RCS file, moving it will make the existing branch in the file seem to
   disappear from CVS's view. This is not a good idea unless you really
   want to forget the existence of those RCS branches.
   
   If the "update" above retrieves the original branch point revision
   (<X>), the "tag" command above will create the tag:
   
                TAG1:<X>.0.Z

   Where Z is 2 greater than the highest magic branch already on revision
   <X>. The TAG1 branch will still have the same branch point (i.e.
   revision <X>), but the first commit to the new TAG1 branch will create
   a different RCS branch number (<X>.Z instead of <X>.Y).
   
     Renaming a magic <branch_tag> is the act of changing
   
                TAG1:<X>.0.Y
           to
                TAG2:<X>.0.Y

   There is no harm in changing a tag name as long as you forget that
   TAG1 ever existed and you clean up any working directories with sticky
   TAG1 tags on them by using "update -A", "update -r <other_tag>" or by
   removing the working directories.
   
   On the other hand, actually changing the tag is not easy.
   
   See 3M.3 for why the seemingly obvious solution won't work:
   
                cvs tag -b -r <old_branch_tag> <new_branch_tag>

   The only direct way to rename a magic tag is to use the "admin"
   command on each file: (You might want to use '-n'. Read "man rcs" and
   look at the '-n' and '-N' options.)
   
                cvs admin -N<new_branch_tag>:<old_branch_tag> .
                cvs tag -d <old_branch_tag>

   But you have to be careful because "admin" is different from other CVS
   commands:
   
     "admin" can be used recursively, but only by specifying directory
   names in its argument list (e.g. '.'),
   
     Where "rtag -r <old_branch_tag>" would interpret <old_branch_tag> as
   a magic CVS branch tag, "admin" is a direct interface to RCS which
   sees a magic branch tag as a simple (though non-existent) RCS revision
   number.
   
   This is good for us in this particular case, but different from normal
   CVS.
   
     "admin" also skips the Attic and produces different kinds of errors
   than CVS usually does. (Because they are coming directly from RCS.)
   
   The other way to rename a magic <branch_tag> is to edit the Repository
   files with a script of some kind. I've done it in the past, but I'll
   leave it as an exercise for the reader.
   
   Last modified: _6/13/1997_
   
    6. Can I use RCS locally to record my changes without making them globally
    visible by committing them? 
    
   You can, but it will probably confuse CVS to have ",v" files in your
   working directory. And you will lose all your log entries when you
   finally commit it.
   
   Your best bet is to create your own CVS branch and work there. You can
   commit as many revisions as you want, then merge it back into the main
   line (or parent branch) when you are finished.
   
   Last modified: _6/13/1997_
   
    7. How can I allow access to the Repository by both CVS and RCS? 
    
   The first step is to try not to. If some people are using CVS, there
   is no reason for everyone not to. It is not hard to learn the basics
   and CVS makes certain operations *easier* than a series of RCS
   commands. Personal preference in what software tools can be applied to
   a shared Repository has to take second place to system integration
   needs. If you disagree, try writing some Lisp code for inclusion in
   your Unix kernel and see what kind of reception you get.
   
   If you really must allow routine RCS access to the CVS Repository, you
   can link an RCS sub-directory into a piece of the Repository:
   
                ln -s /Repository/some/directory/I/want RCS

   and RCS will work just fine.
   
   Those who are using RCS will have to keep the following in mind:
   
     If a file was originally added to the Repository by "import" and has
   not been changed using CVS, the *RCS* default branch will remain
   attached to the Vendor branch, causing revisions checked-in by "ci" to
   wind up on the Vendor branch, instead of the main branch. Only CVS
   moves the RCS default branch on first commit.
   
   The way around this is to checkin (using "ci") all the files first and
   move them into the Repository. That way they won't have Vendor
   branches. Then RCS will work OK.
   
     It is possible to use "rcs" and "ci" to make the files unusable by
   CVS. The same is true of the CVS "admin" command.
   
     Normal RCS practice locks a file on checkout with "co -l". In such
   an environment, RCS users should plan to keep survival gear and food
   for at least 30 days near their desks. When faced with bizarre and
   unexpected permission errors, howling mobs of slavering CVS users will
   run the RCS users out of town with pitchforks and machetes.
   
   See 3C.8 for a way to avoid machetes aroused by lock collisions.
   
     Though files checked in by RCS users will correctly cause
   "up-to-date" failures during CVS "commits" and they will be
   auto-merged into CVS working directories during "update", the opposite
   won't happen.
   
   RCS users will get no warning and will not be required to merge older
   work into their code. They can easily checkin an old file on top of a
   new revision added by CVS, discarding work committed earlier by CVS
   users.
   
   See the howling mob scenario described above.
   
   RCS is great. I have used it for years. But I wouldn't mix it this
   way. In a two-camp society, you are asking for real trouble, both in
   technical hassles to clean up and in political hassles to soothe.
   Branch merges will also be a major problem.
   
   Last modified: _6/13/1997_
   
    8. I "updated" a file my friend, "bubba", committed yesterday. Why doesn't
    the file now have a modified date of yesterday? 
    
   CVS restores dates from the RCS files only on first "checkout". After
   that, it is more important to maintain a timestamp relative to the
   other files in the working directory.
   
   Example: You committed a source file at 5PM. Bubba updated his copy of
   the file, grabbing your changes, then changed and committed a new
   revision of the file at 6PM. At 7PM, you compile your file. Then you
   execute "update". If CVS sets the date to the one in the RCS file, the
   file would be given a timestamp of 6PM and your Makefile wouldn't
   rebuild anything that depended on it. Bad news.
   
   Note that the same logic applies to retrieving a revision out of the
   Repository to replace a deleted file. If CVS changes your file in an
   existing working directory, whether it was because a new revision was
   committed by someone else or because you deleted your working file,
   the timestamp on the retrieved working file *must* be set to the
   current time.
   
   When you first retrieve a file, there is no reason to expect any
   particular timestamp on the file within your working area. But later,
   when dependency checking is performed during a build, it is more
   important for the timestamps on the local files to be consistent with
   each other than than it is for working files to match the timestamps
   on the files in the Repository. See 4D.17 for some more about
   timestamps.
   
   Last modified: _6/13/1997_
   
    9. Why do timestamps sometimes get set to the date of the revision,
    sometimes not? The inconsistency causes unnecessary recompiles. 
    
   The "checkout" command normally sets the timestamp of a working file
   to match the timestamp stored on the revision in the Repository's RCS
   file.
   
   The "commit" command retains the timestamp of the file, if the act of
   checking it in didn't change it (by expanding keywords).
   
   The "update" command sets the time to the revision time the first time
   it sees the file. After that, it sets the time of the file to the
   current time. See 4D.8 for a reason why.
   
   Here's a two-line PERL program to set timestamps on files based on
   other timestamps. I've found this program useful. When you are certain
   you don't want a source file to be recompiled, you can set its
   timestamp to the stamp on the object file.
   
        #!/usr/local/bin/perl
        #
        # Set timestamp of args 2nd-Last to that of the first arg.
        #
        ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,$atime,$mtime,$ctime)
                = stat(shift);
        utime($atime,$mtime,@ARGV);

   Last modified: _6/13/1997_
   
    10. While in the middle of a large "commit", how do I run other commands,
    like "diff" or "stat" without seeing lock errors? 
    
   Type:
                cvs -n <command>

   The '-n' option to the main cvs command turns off lock checking, a
   reasonable act for read-only commands given the promise offered by
   '-n' not to alter anything. The "diff", "log" and "stat" commands
   provide the same information (for files that are not being committed)
   when used with and without the '-n' option.
   
   Warning: Ignoring locks can produce inconsistent information across a
   collection of files if you are looking at the revisions affected by an
   active commit. Be careful when creating "patches" from the output of
   "cvs -n diff". If you are looking only at your working files, tagged
   revisions, and BASE revisions (revisions whose numbers are read from
   your ./CVS/Entries files), you should get consistent results. Of
   course, if you catch a single file in the middle of RCS activity, you
   might get some strange errors.
   
   Note that the suggested command is "cvs -n <command>". The visually
   similar command "cvs <command> -n" has no relation to the suggested
   usage and has an entirely different meaning for each command.
   
   "cvs -n update" also works in the middle of a commit, providing
   slightly different information from a plain "cvs update". But, of
   course, it also avoids modifying anything.
   
   You could also use the RCS functions, "rlog" and "rcsdiff" to display
   some of the information by referring directly to the Repository files.
   
   You need RCS version 5 or later for the commands described above to
   work reliably.
   
   Last modified: _6/13/1997_
   
    11. Where did the ./CVS/Entries.Static file come from? What is it for? 
    
   Each CVS working directory contains a ./CVS/Entries file listing the
   files managed by CVS in that working directory. Normally, if the
   "update" command finds a file in the Repository that is not in the
   ./CVS/Entries file, "update" copies the appropriate revision of the
   "new" file out of the Repository and adds the filename to the Entries
   file. This happens for files:
   
     Added to the Repository from another working directory.
   
     Dragged out of the Attic when switching branches with "update -A" or
   "update -r".
   
     Whose names were deleted from the ./CVS/Entries file.
   
   If the ./CVS/Entries.Static file exists, CVS will only bring out
   revisions of files that are contained in either ./CVS/Entries or
   ./CVS/Entries.Static. If a Repository file is found in *neither* file,
   it is ignored.
   
   The ./CVS/Entries.Static file is created when you check out an
   individual file or a module that creates working directories that
   don't contain all files in the corresponding Repository directory. In
   those cases, without an ./CVS/Entries.Static file, a simple "update"
   would bring more files out of the Repository than the original
   "checkout" wanted.
   
   The ./CVS/Entries.Static file can be removed by hand. It is
   automatically removed if you run "update -d" to create new directories
   (even if no new directories are created). (Internally, since
   "checkout" turns on the '-d' flag and calls the "update" routine, a
   "checkout" of a module or directory that writes into an existing
   directory will also remove the ./CVS/Entries.Static file.)
   
   Last modified: _6/13/1997_
   
    12. Why did I get the wrong Repository in the loginfo message? 
    
   You probably:
   
     Use multiple Repositories.
   
     Configured CVS to use absolute pathnames in the ./CVS/Repository
   file.
   
     Configured CVS not to use the ./CVS/Root file.
   
     Typed the "commit" command in one Repository with your $CVSROOT
   pointing at another.
   
   "commit" and all other CVS commands will heed an absolute pathname in
   the ./CVS/Repository file (or in the "-d CVSrootdir" override), but
   the log function doesn't take arguments -- it just looks at $CVSROOT.
   
   If you avoid even one of the four steps above, you won't see this
   problem. If you configure ./CVS/Root, you won't be allowed to execute
   the program causing the error.
   
   Last modified: _6/13/1997_
   
    13. How do I run CVS setuid so I can only allow access through the CVS
    program itself? 
    
   Setuid to root is not a great idea. Any program that modifies files
   and is used by a widely distributed group of users is not a good
   candidate for a setuid program. (The worst suggestion I've ever heard
   was to make *Emacs* setuid to root.)
   
   Root access on Unix is too powerful. Also, it might not work in some
   (secure?) environments.
   
   Running it setuid to some user other than root might work, if you add
   this line to main.c near the beginning:
   
                setuid(geteuid());

   Otherwise it uses *your* access rights, rather than the effective
   uid's.
   
   Also, you have to invent a fake user whose name will show up in
   various places. But many sites, especially those who might want a
   setuid CVS for "security", want personal accountability -- no generic
   accounts. I don't know whether accountability outweighs file security.
   
   And finally, unless you take action to limit the "admin" command, you
   are leaving yourself unprotected anyway.
   
   Last modified: _6/13/1997_
   
    14. How about using groups and setgid() then? 
    
   Here is a way to run CVS setgid in some environments:
   
     Stick this near the front of the main() in main.c:
   
   setgid(getegid());
   
   This will allow "access" to work on systems where it only works on the
   real gid.
   
     Create a group named "cvsg". (This example uses "cvsg". You can name
   it as you wish.)
   
     Put *no* users in the "cvsg" group. You can put Repository
   administrators in this group if you want to.
   
     Set the cvs executable to setgid (not setuid):
   
   cd /usr/local/bin; chown root.cvsg cvs; chmod 2755 cvs
   
     Make sure every file in the Repository is in group "cvsg":
   
   chown -R root.cvsg $CVSROOT
   
     Change all directory permissions to 770. This allows all access to
   the files by the "cvsg" group (which has no members!) and no access at
   all to anyone else.
   
   find $CVSROOT -type d -exec chmod 2770 {} \;
   
   On some systems you might have to type:
   
   find $CVSROOT -type d -exec chmod u=rwx,g=rwx,o=,g+s {} \;
   
   This should allow only the cvs program (or other "setgid to group
   cvsg") programs to write into the area, but no one else. Yes the user
   winds up owning the file, but s/he can't find it again later since
   s/he can't traverse the tree. (If you enable the world execute bit
   (mode 2771) on directories, users can traverse the tree and the user
   who last wrote the file can still write to it.)
   
   If you want to allow read access, check out an entire tree somewhere.
   You have to do this anyway to build it.
   
   Note: If you are using a stupid file system that can't inherit file
   groups from the parent directory (even with the "setgid" (Octal 2000)
   bit set), you might have to modify CVS (or RCS) to reset the group
   every time you create a new file. I have not tested this.
   
   The setgid() method shares with the setuid() method the problem of
   keeping "admin" from breaking things.
   
   Last modified: _6/13/1997_
   
    15. How do I use the "commitinfo" file? 
    
   Go read 4B.2 first.
   
   The "commitinfo" file allows you to execute "sanity check" functions
   before allowing a commit. If any function called from within the
   commitinfo file exits with a non-zero status, the commit is denied.
   
   To fill out a "commitinfo" file, ask yourself (and those sharing your
   Repository) these questions:
   
   - Is there anything you want to check or change before someone is
   allowed to commit a file? If not, forget commitinfo.
   
   If you want to serialize binary files, you might consider something
   like the rcslock.pl program in the contrib directory of the CVS
   sources.
   
   - Do you want to execute the same exact thing before committing to
   every file in the Repository? (This is useful if you want to program
   the restrictions yourself.) If so, set up a single line in the
   commitinfo:
   
                DEFAULT         /absolute/path/to/program

   CVS executes the program once for each directory that "commit"
   traverses, passing as arguments the directory and the files to be
   committed within that directory.
   
   Write your program accordingly. Some examples exist in the contrib
   directory.
   
   - Do you want a different kind of sanity check performed for different
   directories? If so, you'll have to decide what to do for all
   directories and enter lines like this:
   
                regexp1         /absolute/path/to/program-for-regexp1
                regexp2         /absolute/path/to/program-for-regexp2
                DEFAULT         /absolute/path/to/program-for-all-else

   - Is there anything you want to happen before *all* commits, in
   addition to other pattern matches? If so, include a line like this:
   
                ALL             /absolute/path/to/program

   It is executed independently of all the above. And it's repeatable --
   you can have as many ALL lines as you like.
   
   Last modified: _6/13/1997_
   
    16. How do I use the "loginfo" files? 
    
   See 4B.2 and the "commitinfo" question above.
   
   The "loginfo" file has the same format as the "commitinfo" file, but
   its function is different. Where the "commitinfo" information is used
   before a commit, the "loginfo" file is used after a commit.
   
   All the commands in the "loginfo" file should read data from standard
   input, then either append it to a file or send a message to a mailing
   list. If you want to make it simple, you can put shell (the shell used
   by "popen(3)") command lines directly in the "loginfo" (or
   "commitinfo") file. These seem to work:
   
   ^special /usr/ucb/Mail -s %s special-mailing-list ^other /usr/ucb/Mail
   -s %s other-mailing-list DEFAULT (echo '===='; echo %s; cat) >
   /path/name/to/log/file
   
   Last modified: _6/13/1997_
   
    17. How can I keep people with restrictive umask values from blocking
    access to the Repository? 
    
   If a user creates a new file with restricted permissions (e.g. 0600),
   and commits it, the Repository will have a file in it that is
   unreadable by everyone. The 0600 example would be unreadable by
   *anyone* but root and the user who created it.
   
   There are 3 solutions to this:
   
     Let it happen. This is a valid way to protect things. If everyone is
   working alone, a umask of 077 is OK. If everyone is working only in
   small groups, a umask of 007 is OK.
   
     Train your users not to create such things if you expect to share
   them.
   
     See 4B.5 for a small script that will reset the umask.
   
   I personally don't like the idea of a program automatically
   *loosening* security. It would be better for you all to talk about the
   issue and decide how to work together.
   
   Last modified: _6/13/1997_
   
  Category: /Commands_/
  
   " Commands "
   
  Category: /Commands_/add_ad_new/
  
   " + "add", "ad", "new""
   
    1. What is "add" for? 
    
   To add a new directory to the Repository or to register the desire to
   add a new file to the Repository.
   
   The directory is created immediately, while the desire to add the file
   is recorded in the local ./CVS administrative directory. To really add
   the file to the Repository, you must then "commit" it.
   
   Last modified: _6/13/1997_
   
    2. How do I add a new file to the branch I'm working on? 
    
   The user actions for adding a file to any branch, including the Main
   Branch, are exactly the same.
   
   You are in a directory checked out (or updated) with the '-A' option
   (to place you on the Main Branch) or the "-r <branch_tag>" option (to
   place you on a branch tagged with <branch_tag>). To add <file> to the
   branch you are on, you type:
   
                cvs add <file>
                cvs commit <file>

   If no ./CVS/Tag file exists (the '-A' option deletes it), the file
   will be added to the Main Branch. If a ./CVS/Tag file exists (the "-r
   <branch_tag>" option creates it), the file will be added to the branch
   named (i.e. tagged with) <branch_tag>.
   
   Unless you took steps to first add the file to the Main Branch, your
   new file ends up in the Attic.
   
   Last modified: _6/13/1997_
   
    3. Why did my new file end up in the Attic? 
    
   The file is thrown into the Attic to keep it from being visible when
   you check out the Main Branch, since it was never committed to the
   Main Branch.
   
   Last modified: _6/13/1997_
   
    4. Now that it's in the Attic, how do I connect it to the Main branch? 
    
   That can be considered a kind of "merge". See 4C.8
   
   Last modified: _6/13/1997_
   
    5. How do I avoid the hassle of reconnecting an Attic-only file to the Main
    Branch? 
    
   You create it on the Main Branch first, then branch it.
   
   If you haven't yet added the file or if you decided to delete the new
   Attic file and start over, then do the following: (If you added the
   file (or worse, the 157 files) to the Attic and don't want to start
   over, try the procedure in 4C.8.)
   
     Temporarily remove the sticky branch information. Either:
   
     Move the whole directory back to the Main Branch. [This might not be
   a good idea if you have modified files, since it will require a merge
   in each direction.]
   
                cvs update -A

                        *or*

     Move the ./CVS/Tag file out of the way.
   
                mv ./CVS/Tag HOLD_Tag

     Add and branch the file "normally":
   
                cvs add <file>
                cvs commit <file>
                cvs tag -b <branch_tag> <file>

   [<branch_tag> is the same Branch Tag as you used on all the other
   files. Look at ./CVS/Entries or the output from "cvs stat" for sticky
   tags.]
   
     Clean up the temporary step.
   
     If you moved the ./CVS/Tag file, put it back. Then move the new file
   onto the branch where you are working.
   
                mv HOLD_Tag ./CVS/Tag
                cvs update -r <branch_tag> <file>

     If you ran "update -A" rather than moving the ./CVS/Tag file, move
   the whole directory (including the new file) back onto the branch
   where you were working:
   
                cvs update -r <branch_tag>

   Last modified: _6/13/1997_
   
    6. How do I cancel an "add"? 
    
   If you want to remove the file entirely and cancel the "add" at the
   same time, type:
   
                cvs remove -f <file>

   If you want to cancel the "add", but leave the file as it was before
   you typed "cvs add", then you have to fake it:
   
                mv <file> <file>.hold
                cvs remove <file>
                mv <file>.hold <file>

   Last modified: _6/13/1997_
   
    7. What are the ./CVS/file,p and ./CVS/file,t files for? 
    
   The ./CVS/file,p and ./CVS/file,t files are created by the "add"
   command to hold command line options and message text between the time
   of the "add" command and the expected "commit".
   
   The ./CVS/file,p file is always null, since its function was absorbed
   by the "options" field in the ./CVS/Entries file. If you put something
   in this file it will be used as arguments to the RCS "ci" command that
   commit uses to check the file in, but CVS itself doesn't put anything
   there.
   
   The ./CVS/file,t file is null unless you specify an initial message in
   an "add -m 'message'" command. The text is handed to "rcs -i
   -t./CVS/file,t" to create the initial RCS file container.
   
   Both files must exist to commit a newly added file. If the
   ./CVS/file,p file doesn't exist, CVS prints an error and aborts the
   commit. If the ./CVS/file,t file doesn't exist, RCS prints an error
   and CVS gets confused, but does no harm.
   
   To recover from missing ,p and ,t files, just create two zero-length
   files and rerun the "commit".
   
   Last modified: _6/13/1997_
   
    8. How do I "add" a binary file? 
    
   If you configured CVS to use the GNU version of "diff" and "diff3",
   you only need to turn off RCS keyword expansion.
   
   First you turn off RCS keyword expansion for the initial checkin by
   using "add -ko". It works like "update -ko" in creating a "sticky"
   option only for the copy of the file in the current working directory.
   
                cvs add -ko <file>

   Commit the file normally. The sticky -ko option will be used.
   
                cvs commit <file>

   Then mark the RCS file in the Repository so that keyword expansion is
   turned off for all checked out versions of the file.
   
                cvs admin -ko <file>

   Since "admin -ko" records the keyword substitution value in the
   Repository's RCS file, you no longer need the sticky option. You can
   turn it off with the "update -A" command, but if you were on a branch,
   you'll have to follow it "update -r <branch_tag>" to put yourself back
   on the branch.
   
   Managing that binary file is another problem. See 4D.1.
   
   Last modified: _6/13/1997_
   
  Category: /Commands_/admin_adm_rcs/
  
   " + "admin", "adm", "rcs""
   
    1. What is "admin" for? 
    
   To provide direct access to the underlying "rcs" command (which is not
   documented in this FAQ) bypassing all safeguards and CVS assumptions.
   
   Last modified: _6/13/1997_
   
    2. Wow! Isn't that dangerous? 
    
   Yes.
   
   Though you can't hurt the internal structure of an RCS file using its
   own "rcs" command, you *can* change the underlying RCS files using
   "admin" in ways that CVS can't handle.
   
   If you feel the need to use "admin", create some test files with the
   RCS "ci" command and experiment on them with "rcs" before blasting any
   CVS files.
   
   Last modified: _6/13/1997_
   
    3. What would I normally use "admin" for? 
    
   Normally, you wouldn't use admin at all. In unusual circumstances,
   experts can use it to set up or restore the internal RCS state that
   CVS requires.
   
   You can use "admin -o" (for "outdate") to remove revisions you don't
   care about. This has its own problems, such as leaving dangling Tags
   and confusing the "update" command.
   
   There is some feeling among manipulators of binary files that "admin
   -l" should be used to serialize access. See 3C.8.
   
   An interesting use for "admin" came up while maintaining CVS itself. I
   import versions of CVS onto the Vendor branch of my copy of CVS, make
   changes to some files and ship the diffs (created by "cvs diff -c -r
   TO_BRIAN") off to Brian Berliner. After creating the diff, I retag
   ("cvs tag -F TO_BRIAN") the working directory, which is then ready to
   produce the next patch.
   
   I'll use "add.c" as an example (only because the name is short).
   
   When the next release came out, I discovered that the released "add.c"
   (version 1.1.1.3 on the Vendor branch) was exactly the same as my
   modified file (version 1.3). I didn't care about the changelog on
   versions 1.2 and 1.3 (or the evidence of having done the work), so I
   decided to revert the file to the state where it looked like I had not
   touched the file -- where I was just using the latest on the vendor
   branch after a sequence of imports.
   
   To do that, I removed all the revisions on the main branch, except for
   the original 1.1 from which the Vendor branch sprouts:
   
                cvs admin -o1.2: add.c

   Then I set the RCS "default branch" back to the Vendor branch, the way
   import would have created it:
   
                cvs admin -b1.1.1 add.c

   And I moved the "TO_BRIAN" Tag to the latest revision on the Vendor
   branch, since that is the base from which further patches would be
   created (if I made any):
   
                cvs admin -NTO_BRIAN:1.1.1.3 add.c

   Instead of 1.1.1.3, I could have used one of the "Release Tags" last
   applied by "import" (3rd through Nth arguments).
   
   Suggestion: Practice on non-essential files.
   
   Last modified: _6/13/1997_
   
    4. What should I avoid when using "admin"? 
    
   If you know exactly what you are doing, hack away. But under normal
   circumstances:
   
   Never use "admin" to alter branches (using the '-b' option), which CVS
   takes very seriously. If you change the default branch, CVS will not
   work as expected. If you create new branches without using the "tag
   -b" command, you may not be able to treat them as CVS branches.
   
   See 3C.8 for a short discussion of how to use "admin -l" for
   serializing access to binary files.
   
   The "admin -o <file>" allows you to delete revisions, usually a bad
   idea. You should commit a correction rather than back out a revision.
   Outdating a revision is prone to all sorts of problems:
   
     Discarding data is always a bad idea. Unless something in the
   revision you just committed is a threat to your job or your life,
   (like naming a function "<boss's name>_is_a_dweeb", or including the
   combination to the local Mafioso's safe in a C comment), just leave it
   there. No one cares about simple mistakes -- just commit a corrected
   revision.
   
     The time travel paradoxes you can cause by changing history are not
   worth the trouble. Even if CVS can't interfere with your parents'
   introduction, it *can* log commits in at least two ways (history and
   loginfo). The reports now lie -- the revision referred to in the logs
   no longer exists.
   
     If you used "import" to place <file> into CVS, outdating all the
   revisions on the Main branch back to and including revision 1.2 (or
   worse, 1.1), will produce an invalid CVS file.
   
   If the <file>,v file only contains revision 1.1 (and the connected
   branch revision 1.1.1.1), then the default branch must be set to the
   Vendor branch as it was when you first imported the file. Outdating
   back through 1.2 doesn't restore the branch setting. Despite the above
   admonition against it, "admin -b" is the only way to recover:
   
                cvs admin -b1.1.1 <file>

     Although you can't outdate a physical (RCS) branch point without
   removing the whole branch, you *can* outdate a revision referred to by
   a magic branch tag. If you do so, you will invalidate the branch.
   
     If you "outdate" a tagged revision, you will invalidate all uses of
   the <tag>, not just the one on <file>. A tag is supposed to be
   attached to a consistent set of files, usually a set built as a unit.
   By discarding one of the files in the set, you have destroyed the
   utility of the <tag>. And it leaves a dangling tag, which points to
   nothing.
   
     And even worse, if you commit a revision already tagged, you will
   alter what the <tag> pointed to without using the "tag" command. For
   example, if revision 1.3 has <tag> attached to it and you "outdate"
   the 1.3 revision, <tag> will point to a nonexistent revision. Although
   this is annoying, it is nowhere near as much trouble as the problem
   that will occur when you commit to this file again, recreating
   revision 1.3. The old tag will point to the new revision, a file that
   was not in existence when the <tag> was applied. And the discrepancy
   is nearly undetectable.
   
   If you don't understand the above, you should not use the admin
   command at all.
   
   Last modified: _6/13/1997_
   
    5. How do I restrict the "admin" command? The -i flag in the modules file
    can restrict commits. What's the equivalent for "admin"? 
    
   At this writing, to disable the "admin" command, you will have to
   change the program source code, recompile and reinstall.
   
   Last modified: _6/13/1997_
   
    6. I backed out a revision with "admin -o" and committed a replacement. Why
    doesn't "update" retrieve the new revision? 
    
   CVS is confused because the revision in the ./CVS/Entries file matches
   the latest revision in the Repository *and* the timestamp in the
   ./CVS/Entries file matches your working file. CVS believes that your
   file is "up-to-date" and doesn't need to be updated.
   
   You can cause CVS to notice the change by "touch"ing the file.
   Unfortunately what CVS will tell you is that you have a "Modified"
   file. If you then "commit" the file, you will bypass the normal CVS
   check for "up-to-date" and will probably commit the revision that was
   originally removed by "admin -o".
   
   Changing a file without changing the revision number confuses CVS no
   matter whether you did it by replacing the revision (using "admin -o"
   and "commit" or raw RCS commands) or by applying an editor directly to
   a Repository (",v") file. Don't do it unless you are absolutely
   certain no one has the latest revision of the file checked out.
   
   The best solution to this is to institute a program of deterrent
   flogging of abusers of "admin -o".
   
   The "admin" command has other problems." See 3B.4 above.
   
   Last modified: _6/13/1997_
   
  Category: /Commands_/checkout_co_get/
  
   " + "checkout", "co", "get""
   
    1. What is "checkout" for? 
    
   To acquire a copy of a module (or set of files) to work on.
   
   All work on files controlled by CVS starts with a "checkout".
   
   Last modified: _6/13/1997_
   
    2. What is the "module" that "checkout" takes on the command line? 
    
   It is a name for a directory or a collection of files in the
   Repository. It provides a compact name space and the ability to
   execute before and after helper functions based on definitions in the
   modules file.
   
   See 1D.11.
   
   Last modified: _6/13/1997_
   
    3. Isn't a CVS "checkout" just a bunch of RCS checkouts? 
    
   Like much of CVS, a similar RCS concept is used to support a CVS
   function. But a CVS checkout is *not* the same as an RCS checkout.
   
   Differences include:
   
     CVS does not lock the files. Others may access them at the same
   time.
   
     CVS works best when you provide a name for a collection of files (a
   module or a directory) rather than an explicit list of files to work
   on.
   
     CVS remembers what revisions you checked out and what branch you are
   on, simplifying later commands.
   
   Last modified: _6/13/1997_
   
    4. What's the difference between "update" and "checkout"? 
    
   The "checkout" and "update" commands are nearly equivalent in how they
   treat individual files. They differ in the following ways:
   
     The "checkout" command always creates a directory, moves into it,
   then becomes equivalent to "update -d".
   
     The "update" command does not create directories unless you add the
   '-d' option.
   
     "Update" is intended to be executed within a working directory
   created by "checkout". It doesn't take a module or directory argument,
   but figures out what Repository files to look at by reading the files
   in the ./CVS administrative directory.
   
     The two commands generate completely different types of records in
   the "history" file.
   
   Last modified: _6/13/1997_
   
    5. Why can't I check out a file from within my working directory? 
    
   Though you *can* check out a file, you normally check out a module or
   directory. And you normally do it only once at the beginning of a
   project.
   
   After the initial "checkout", you can use the "update" command to
   retrieve any file you want within the checked-out directory. There is
   no need for further "checkout" commands.
   
   If you want to retrieve another module or directory to work on, you
   must provide two pathnames: where to find it in the Repository and
   where to put it on disk. The "modules" file and your current directory
   supply two pieces of naming information. While inside a checked-out
   working directory, the CVS administrative information provides most of
   the rest.
   
   You should be careful not to confuse CVS with RCS and use "checkout"
   in the RCS sense. An RCS "checkout" (which is performed by the RCS
   "co" command) is closer to a "cvs update" than to a "cvs checkout".
   
   Last modified: _6/13/1997_
   
    6. How do I avoid dealing with those long relative pathnames? 
    
   This question has also been phrased:
   
   How do I avoid all those layers of directories on checkout? or Why do
   I have to go to the top of my working directory and checkout some long
   pathname to get a file or two?
   
   This type of question occurs only among groups of people who decide
   not to use "modules". The answer is to use "modules".
   
   When you hand the "checkout" command a relative pathname rather than a
   module name, all directories in the path are created, maintaining the
   same directory hierarchy as in the Repository. The same kind of
   environment results if you specify a "module" that is really an alias
   expanding into a list of relative pathnames rather than a list of
   module names.
   
   If you use "module" names, "checkout" creates a single directory by
   the name of the module in your current directory. This "module"
   directory becomes your working directory.
   
   The "module" concept combines the ability to "name" a collection of
   files with the ability to structure the Repository so that consistent
   sets of files are checked out together. It is the responsibility of
   the Repository Administrators to set up a modules file that describes
   the software within the Repository.
   
   Last modified: _6/13/1997_
   
    7. Can I move a checked-out directory? Does CVS remember where it was
    checked out? 
    
   Yes and Yes.
   
   The ./CVS/Repository file in each working directory contains a
   pathname pointing to the matching directory within the Repository. The
   pathname is either absolute or relative to $CVSROOT, depending on how
   you configured CVS.
   
   When you move a checked-out directory, the CVS administrative files
   will move along with it. As long as you don't move the Repository
   itself, or alter your $CVSROOT variable, the moved directory will
   continue to be usable.
   
   CVS remembers where you checked out the directory in the "history"
   file, which can be edited, or even ignored if you don't use the
   "working directory" information displayed by the "history" command.
   
   Last modified: _6/13/1997_
   
    8. How can I lock files while I'm working on them the way RCS does? 
    
   Until the day arrives of the all-powerful merge tool, there are still
   files that must be accessed serially. For those instances, here's a
   potential solution:
   
     Install a pre-commit program in the "commitinfo" file to check for
   RCS locks. The program "rcslock.pl" performs this function. It can be
   found in the contrib directory of the CVS source distribution.
   
     When you want to make a change to a file you know can't be merged,
   first use "cvs admin -l" to lock the file. If you can't acquire the
   lock, use the standard "locked out" protocol: go talk to the person
   holding the lock.
   
     Make sure the pre-commit program prints a message and exits with a
   non-zero status if someone besides the user running "commit" has the
   file locked. This non-zero exist status will cause the "commit" to
   fail cleanly.
   
     Make sure the pre-commit program exits with a zero status if the
   file is either unlocked or locked by the user running "commit". The
   "cvs commit" command that kicked off the pre-commit program will take
   a zero exist status as an OK and checkin the file, which has the
   side-effect of unlocking it.
   
   ===> The following is opinion and context. Don't read it if you are
   looking for a quick fix.
   
   The topic of locking CVS files resurfaces on the network every so
   often, producing the same results each time:
   
   The Big Endians:
   
   CVS was designed to avoid locks, using a copy-modify-merge model.
   Locking is not necessary and you should take the time to learn the CVS
   model which many people find workable. So why not get with the program
   and learn how to think the CVS way?
   
   The Little Endians:
   
   The users determine how a tool is to be used, not the designers. We,
   the users, have always used locking, our bosses demand locking,
   locking is good, locking is God. I don't want to hear any more
   lectures on the CVS model. Make locking work.
   
   Any organization making active changes to a source base will
   eventually face the need to do parallel development. Parallel
   development implies merges. (If you plan to keep separate copies of
   everything and never merge, good luck. Tell me who you work for so I
   can buy stock in your disk suppliers this year and sell your stock
   short next year.)
   
   Merges will never go away. CVS chose to make "merges" stand front and
   center as an important, common occurrence in development. It is one
   way of looking at things.
   
   For free-format text, the merge paradigm gives you a considerable
   amount of freedom. It does take a bit of management, but any project
   should be ready to deal with it.
   
   On the other hand, there are many files that can't be merged using
   text merge techniques. Straight text merge programs like "diff3" are
   guaranteed to fail on executables (with relative branch statements),
   files with self-referential counts stored in the file (such as TAGS
   files), or files with relative motion statements in them (such as
   Frame MIF files, many postscript files). They aren't all binary files.
   
   For these types of files, and many others, there are only two
   solutions:
   
     Complex merge tools that are intimately aware of the contents of the
   files to be merged. (ClearCase, and probably others, allow you to
   define your own "files types" with associated "merge tools".)
   
     Serialization of access to the file. The only technical solution to
   the problem of serialization is "locking".
   
   Since you can call a program that offers:
   
   "Which one do you want? A/B?"
   
   a "merge tool", more and more merge tools will appear which can be
   hooked into a merge-intensive program like CVS. Think of a bitmap
   "merge" tool that displays the bitmaps on the screen and offers a
   "paint" interface to allow you to cut and paste, overlay, invert or
   fuse the two images such that the result is a "merged" file.
   
   My conclusion is that the need for locking is temporary, awaiting
   better technology. For large development groups, locking is not an
   alternative to merging for text files.
   
   Last modified: _6/13/1997_
   
    9. What is "checkout -s"? How is it different from "checkout -c"? 
    
   The '-c' and '-s' options to "checkout" both cause the modules file to
   appear on standard output, but formatted differently.
   
   "checkout -c" lists the modules file alphabetized by the module name.
   It also prints all data (including options like '-a' and "-o <prog>")
   specified in the modules file.
   
   "checkout -s" lists the modules file sorted by "status" field, then by
   module name. The status field was intended to allow you to mark
   modules with strings of your choice to get a quick sorted report based
   on the data you chose to put in the status fields. I have used it for
   priority ("Showstopper", etc as tied into a bug database), for porting
   status ("Ported", "Compiled", etc. when porting a large collection of
   modules), for "assignee" (the person responsible for maintenance), and
   for "test suite" (which automatic test procedure to run for a
   particular module).
   
   Last modified: _6/13/1997_
   
  Category: /Commands_/commit_ci_com/
  
   " + "commit", "ci", "com""
   
    1. What is "commit" for? 
    
   To store new revisions in the Repository, making them visible to other
   users.
   
   Last modified: _6/13/1997_
   
    2. If I edit ten files, do I have to type "commit" ten times? 
    
   No. The "commit" command will take multiple filenames, directory names
   and relative pathnames on the command line and commit them all with
   the same log message. If a file is unchanged, even if it is explicitly
   listed on the command line, CVS will skip it.
   
   Like all CVS commands, "commit" will work on the whole directory by
   default. Just type "cvs commit" to tell CVS to commit all modified
   files (i.e. the files that "update" would display preceded by 'M') in
   the current directory and in all sub-directories.
   
   Last modified: _6/13/1997_
   
    3. Explain: cvs commit: Up-to-date check failed for `<file>' 
    
   You may not "commit" a file if your BASE revision (i.e. the revision
   you last checked out, committed or retrieved via "update") doesn't
   match the HEAD revision (i.e the latest revision on your branch,
   usually the Main Branch).
   
   In other words, someone committed a revision since you last executed
   "checkout", "update" or "commit". You must now execute "update" to
   merge the other person's changes into your working file before
   "commit" will work. You are thus protected (somewhat) from a common
   form of race condition in source control systems, where a checkin of a
   minor alteration of a second copy of the same base file obliterates
   the changes made in the first.
   
   Normally, the "update" command's auto-merge should be followed by
   another round of building and testing before the "commit".
   
   Last modified: _6/13/1997_
   
    4. What happens if two people try to "commit" conflicting changes? 
    
   Conflicts can occur only when two developers check out the same
   revision of the same file and make changes. The first developer to
   commit the file has no chance of seeing the conflict. Only the second
   developer runs into it, usually when faced with the "Up-to-date" error
   explained in the previous question.
   
   There are two types of conflicts:
   
     When two developers make changes to the same section of code, the
   auto-merge caused by "update" will print a 'C' on your terminal and
   leave "overlap" markers in the file.
   
   You are expected to examine and clean them up before committing the
   file. (That may be obvious to *some* of you, but . . .)
   
     A more difficult problem arises when two developers change different
   sections of code, but make calls to, or somehow depend on, the old
   version of each other's code.
   
   The auto-merge does the "right" thing, if you view the file as a
   series of text lines. But as a program, the two developers have
   created a problem for themselves.
   
   This is no different from making cross-referential changes in
   *separate* files. CVS can't help you. In a perfect world, you would
   each refer to the specification and resolve it independently. In the
   real world you have to talk/argue, read code, test and debug until the
   combined changes work again.
   
   Welcome to the world of parallel development.
   
   Last modified: _6/13/1997_
   
    5. I committed something and I don't like it. How do I remove it? 
    
   Though you *can* use the "admin -o" (synonym: "rcs -o") command to
   delete revisions, unless the file you committed is so embarrassing
   that the need to eradicate it overrides the need to be careful, you
   should just grab an old version of the file ("update -p -r
   <previous-rev>" might help here) and commit it on top of the offending
   revision.
   
   See Section 3B on "admin".
   
   Last modified: _6/13/1997_
   
    6. Explain: cvs commit: sticky tag `V3' for file `X' is not a branch 
    
   The message implies two things:
   
     You created your working directory by using "checkout -r V3", or you
   recently executed "update -r V3".
   
     The tag named V3 is not a branch tag.
   
   CVS records (i.e. makes "sticky") any "-r <tag/rev>" argument handed
   to the "checkout" or "update" commands. The <tag/rev> is recorded as
   the CVS working branch, which is the branch to which "commit" will add
   a new revision.
   
   Branch tags are created when you use the -b switch on the "tag" or
   "rtag" commands. Branch tags are magic tags that don't create a
   physical branch, but merely mark the revision to branch from when the
   branch is needed. The first commit to a magic branch creates a
   physical branch in the RCS files.
   
   You can commit onto the end of the Main Trunk, if you have no sticky
   tag at all, or onto the end of a branch, if you have a sticky branch
   tag. But you can't commit a file that has a sticky tag not pointing to
   a branch. CVS assumes a sticky Tag or Revision that does not refer to
   a branch is attached to the middle of a series of revisions. You can't
   squeeze a new revision between two others. Sticky dates also block
   commits since they never refer to a branch.
   
   Scenario1:
   
   If you don't want a branch and were just looking at an old revision,
   then you can move back to the Main Branch by typing:
   
                cvs update -A {files or dirs, default is '.'}

   or you can move to the branch named <branch_tag> by:
   
                cvs update -r <branch_tag> {files or dirs, default is '.'}

   Scenario2:
   
   If you really wanted to be on a branch and made an earlier mistake by
   tagging your branch point with a non-branch tag, you can recover by
   adding a new branch tag to the old non-branch tag:
   
                    cvs rtag -b -r <oldtag> <newtag> <module>

   (It was not a big mistake. Branch-point tags can be useful. But the
   <newtag> must have a different name.)
   
   If you don't know the <module> name or don't use "modules", you can
   also use "tag" this way:
   
                    cvs update -r <oldtag>
                    cvs tag -b <newtag> .

   Then, to put your working directory onto the branch, you type:
   
                    cvs update -r <newtag>

   You can't delete <oldtag> before adding <newtag>, and I would not
   advise deleting the <oldtag> at all, because it is useful in referring
   to the branch point. If you must, you can delete the non-branch tag
   by:
   
                    cvs rtag -d <oldtag> <module>
                or
                    cvs tag -d <oldtag> .

   Scenario3:
   
   If you made the same mistake as in Scenario2 (of placing a non-branch
   tag where you wanted a branch tag), but really want <oldtag> to be the
   name of your branch, you can execute a slightly different series of
   commands to rename it and move your working directory onto the branch.
   
   Warning: This is not a way to rename a branch tag. It is a way to turn
   a non-branch tag into a branch tag with the same name.
   
                    cvs rtag -r <oldtag> <branch_point_tag> <module>
                    cvs rtag -d <oldtag> <module>
                    cvs rtag -b -r <branch_point_tag> <oldtag> <module>

   Then, if you really must, delete the <branch_point_tag>:
   
                    cvs rtag -d <branch_point_tag> <module>

   Note: The unwieldy mixture of "tag" and "rtag" is mostly because you
   can't specify a revision (-r <tag>) to the "tag" command.
   
   See 4C.3 for more info on creating a branch.
   
   Last modified: _6/13/1997_
   
    7. Why does "commit -r <tag/rev>" put newly added files in the Attic? 
    
   If you specify "-r <rev>" (where <rev> is a dotted numeric number like
   2.4), it correctly sets the initial revision to <rev>, but it also
   attaches the numeric <rev> as a sticky tag and throws the file into
   the Attic. This is a bug. The obvious solution is to move the file out
   of the Attic into the associated Repository directory and "update -A"
   the file. There are no Tags to clean up.
   
   If you specify "-r <tag>" to commit a newly added file, the <tag> is
   treated like a <branch_tag>, which becomes a symbolic RCS label
   pointing to the string '1', which can be considered to be the "Main
   branch number" when the main branch is still at revision 1.N. The file
   is also thrown into the Attic. See 4C.8 for a way to recover from
   this.
   
   In fact, a plain "commit" without the "-r" will throw a newly added
   file into the Attic if you added it to a directory checked out on a
   branch. See 3A.[2-5].
   
   See Section 4C, on Branching, for many more details.
   
   Last modified: _6/13/1997_
   
    8. Why would a "commit" of a newly added file not produce rev 1.1? 
    
   When committing a newly added file CVS looks for the highest main
   branch major number in all files in the ./CVS/Entries file. Normally
   it is '1', but if you have a file of revision 3.27 in your directory,
   CVS will find the '3' and create revision 3.1 for the first rev of
   <file>. Normally, the first revision is 1.1.
   
   Last modified: _6/13/1997_
   
  Category: /Commands_/diff_di_dif/
  
   " + "diff", "di", "dif""
   
    1. What is "diff" for? 
    
     To display the difference between a working file and its BASE
   revision (the revision last checked out, updated or committed):
   
                cvs diff <file>

     To display the difference between a working file and a committed
   revision of the same file:
   
                cvs diff -r <tag/rev> <file>

     To display the difference between two committed revisions of the
   same file:
   
                cvs diff -r <tag1/rev1> -r <tag2/rev2> <file>

   You can specify any number of <file> arguments. Without any <file>
   arguments, it compares the whole directory.
   
   In the examples above, "-D <date>" may be substituted wherever "-r
   <tag/rev>" appears. The revision a <date> refers to is the revision
   that existed on that date.
   
   Last modified: _6/13/1997_
   
    2. Why did "diff" display nothing when I know there are later committed
    revisions in the Repository? 
    
   By default, "diff" displays the difference between your working file
   and the BASE revision. If you haven't made any changes to the file
   since your last "checkout", "update" or "commit" there is no
   difference to display.
   
   To display the difference between your working file and the latest
   revision committed to your current branch, type:
   
                cvs diff -r HEAD <file>

   Last modified: _6/13/1997_
   
    3. How do I display what changed in the Repository since I last executed
    "checkout", "update" or "commit"? 
    
   A special tag (interpreted by CVS -- it does not appear in the Tag
   list) named "BASE" always refers to the revision you last checked out,
   updated or committed. Another special tag named "HEAD" always refers
   to the latest revision on your working branch.
   
   To compare BASE and HEAD, you type:
   
                cvs diff -r BASE -r HEAD <file>

   Last modified: _6/13/1997_
   
    4. How do I display the difference between my working file and what I
    checked in last Thursday? 
    
                cvs diff -D "last Thursday" <file>

   where "last Thursday" is a date string. To be more precise, the
   argument to the '-D' option is a timestamp. Many formats are accepted.
   See the man page under "-D date_spec" for details.
   
   Last modified: _6/13/1997_
   
    5. Why can't I pass long options, like --unified, to "diff"? 
    
   CVS only handles single character '-X' arguments, not the FSF long
   options. CVS also passes through only arguments it knows about,
   because a few arguments are captured and interpreted by CVS.
   
   If you didn't configure RCS and CVS to use the GNU version of diff,
   long options wouldn't work even if future versions of CVS acquire the
   ability to pass them through.
   
   Most of the long options have equivalent single-character options,
   which do work. The "--unified" option is equivalent to '-u' in
   revisions of GNU diff since 1.15.
   
   Last modified: _6/13/1997_
   
  Category: /Commands_/export_exp_ex/
  
   " + "export", "exp", "ex""
   
    1. What is "export" for? 
    
   "export" checks out a copy of a module in a form intended for export
   outside the CVS environment. The "export" command produces the same
   directory and file structure as the "checkout" command, but it doesn't
   create "CVS" sub-directories and it removes all the RCS keywords from
   the files.
   
   Last modified: _6/13/1997_
   
    2. Why does it remove the RCS keywords so I can't use the "ident" command
    on the source files? 
    
   It removes the RCS keywords, so that if the recipient of the exported
   sources checks them into another set of RCS files (with or without
   CVS), and then makes modifications through RCS or CVS commands, the
   revision numbers that they had when you exported them will be
   preserved. (That ident no longer works is just an unfortunate side
   effect.)
   
   The theory is that you are exporting the sources to someone else who
   will make independent changes, and at some point you or they will want
   to know what revisions from your Repository they started with
   (probably to merge changes, or to try to decide whether to merge
   changes).
   
   A better way to handle this situation would be to give them their own
   branch of your Repository. They would need to remember to checkin the
   exported sources with RCS IDs intact (ci -k) so that their changes
   would get revision numbers from the branch, rather than starting at
   1.1 again. Perhaps a future version of CVS will provide a way to
   export sources this way.
   
                                Contributed by Dan Franklin

   Last modified: _6/13/1997_
   
    3. Can I override the '-kv' flag CVS passes to RCS? 
    
   Not as of CVS version 1.4.
   
   Last modified: _6/13/1997_
   
    4. Why doesn't "export" have a '-k' flag like "import" does? 
    
   Export is intended for a specific purpose -- to remove all trace of
   revision control on the way *out* of CVS.
   
   Last modified: _6/13/1997_
   
    5. Why does "export -D" check out every file in the Attic? 
    
   See 5B.3 for an explanation of the same problem with "update".
   
   Last modified: _6/13/1997_
   
  Category: /Commands_/history_hi_his/
  
   " + "history", "hi", "his""
   
    1. What is "history" for? 
    
   To provide information difficult or impossible to extract out of the
   RCS files, such as a "tag" history or a summary of module activities.
   
   Last modified: _6/13/1997_
   
    2. Of what use is it? 
    
   I have found it useful in a number of ways, including:
   
     Providing a list of files changed since
   
   - A tagged release.
   - Yesterday, last Thursday, or a specific date.
   - Someone changed a specific file.
   
     Providing a list of special events:
   
   - Files added or removed since one of the above events.
   - Merge failures since one of the above events. (Where did the
   conflicts occur?)
   - Has anyone (and who) grabbed the revision of this file I committed
   last week, or are they still working blind?
   
     Telling me how often a file/directory/module has been changed.
   
     Dumping a summary of work done on a particular module, including who
   last worked on it and what changed.
   
     Displaying the checked-out modules and where they are being worked
   on.
   
     To tell me what users "joe" and "malcolm" have done this week.
   
   Last modified: _6/13/1997_
   
    3. What is this, Big Brother? 
    
                War is Peace.
                Freedom is Slavery.
                Ignorance is Strength.

   Normally manager types and those with the power to play Big Brother
   don't care about this information. The Software Engineer responsible
   for integration usually wants to know who is working on what and what
   changed. Use your imagination.
   
   Last modified: _6/13/1997_
   
    4. I deleted my working directory and "history" still says I have it
    checked out. How do I fix it? 
    
   You can use "release -f" to forcibly add a "release" record to the
   history file for a working directory associated with a "module". If
   your version of "release" doesn't have the '-f' option, or you checked
   out the directory using a relative path, you have to edit the
   $CVSROOT/CVSROOT/history file.
   
   You can remove the last 'O' line in the history file referring to the
   module in question or add an 'F' record.
   
   Last modified: _6/13/1997_
   
    5. So I *can* edit the History file? 
    
   Yes, but if you are using history at all, you should take a little
   care not to lose information. I normally use Emacs on the file, since
   it can detect that a file has changed out from under it. You could
   also copy and zero out the history file, edit the copy and append any
   new records to the edited copy before replacing it.
   
   Last modified: _6/13/1997_
   
    6. Why does the history file grow so quickly? 
    
   It stores 'U' records, which come in handy sometimes when you are
   tracking whether people have updated each other's code before testing.
   There should (and probably will sometime) be a way to choose what
   kinds of events go into the history file.
   
   The contributed "cln_hist.pl" script will remove all the 'U' records,
   plus matching pairs of 'O' and 'F' records during your normal clean up
   of the history file.
   
   Last modified: _6/13/1997_
   
    7. What is the difference between "cvs history -r <tag/rev>" and "cvs
    history -t <tag>"? 
    
   The '-t' option looks for a Tag record stored by "rtag" in the history
   file and limits the search to dates after the last <tag> of the given
   name was added.
   
   The '-r' option was intended to search all files looking for the <tag>
   in the RCS files. It takes forever and needs to be rewritten.
   
   Last modified: _6/13/1997_
   
    8. Why does "cvs history -c -t <tag>" fail to print anything? 
    
   You have been using "tag" instead of "rtag". The "tag" command
   currently doesn't store a history record. This is another remnant of
   CVS's earlier firm belief in "modules". But it also has a basis in how
   "rtag" and "tag" were originally used.
   
   "rtag" was intended for large-scale tagging of large chunks of the
   Repository, an event work recording. "tag" was intended for adding and
   updating tags on a few files or directories, though it could also be
   used to tag the entire checked-out working tree when there is no
   module defined to match the tree or when the working tree is the only
   place where the right collection of revisions to tag can be found.
   
   Last modified: _6/13/1997_
   
    9. "cvs history -a -o" only printed one line for each checked-out module.
    Shouldn't it print all the directories where the modules are checked out? 
    
   Not as designed.
   
        Command                 Question it is supposed to answer.
        ----------------        ------------------------------------------
        cvs history -o          What modules do I have checked out?
        cvs history -a -o       <same for all users>

        cvs history -o -w       What working directories have I created
                                and what modules are in them?
        cvs history -a -o -w    <same for every user>

   The -o option chooses the "checked out modules" report, which is the
   default history report.
   
   Last modified: _6/13/1997_
   
    10. I can't figure out "history", can you give me concrete examples? 
    
   Default output selects records only for the user who executes the
   "history" command. To see records for other users, add one or more "-u
   user" options or the '-a' option to select *all* users.
   
   To list (for the selected users): Type "cvs history" and:
   
   * Checked out modules: -o (the default)
   * Files added since creation: -x A
   * Modified files since creation: -c
   * Modified files since last Friday: -c -D 'last Friday'
   * Modified files since TAG was added: -c -t <tag>
   * Modified files since TAG on files: -c -r <tag>
   * Last modifier of file/Repository X? -c -l -[fp] X
   * Modified files since string "str": -c -b str
   * Tag history: (Actually "rtag".) -T
   * History of file/Repository/module X: -[fpn] X
   * Module report on "module": -m module
   
   Last modified: _6/13/1997_
   
    11. Can we merge history files when we merge Repositories? 
    
   Assuming that the two Repositories have different sets of pathnames,
   it should be possible to merge two history files by sorting them
   together by the timestamp fields.
   
   You should be able to run:
   
   sort +0.1 ${dir1}/history ${dir2}/history > history
   
   If you "diff" a standard history file before and after such a sort,
   you might see other differences caused by garbage (split lines, nulls,
   etc) in the file. If your Repository is mounted through NFS onto
   multiple machines you will also see a few differences caused by
   different clocks on different machines. (Especially if you don't use
   NTP to keep the clocks in sync.)
   
   Last modified: _6/13/1997_
   
  Category: /Commands_/import_im_imp/
  
   " + "import", "im", "imp""
   
    1. What is "import" for? 
    
   The "import" command is a fast way to insert a whole tree of files
   into CVS.
   
   The first "import" to a particular file within the Repository creates
   an RCS file with a single revision on the "Vendor branch." Subsequent
   "import"s of the same file within the Repository append a new revision
   onto the Vendor branch. It does not, as some seem to believe, create a
   new branch for each "import". All "imports" are appended to the single
   Vendor branch.
   
   If the file hasn't changed, no new revision is created -- the new
   "Release-Tag" is added to the previous revision.
   
   After the import is finished, files you have not changed locally are
   considered to have changed in the "Main line of development". Files
   you *have* changed locally must have the new Vendor code merged into
   them before they are visible on the "Main line".
   
                See 4C.6 and 4C.15

   Last modified: _6/13/1997_
   
    2. How am I supposed to use "import"? 
    
   Create a source directory containing only the files you want to
   import. Make sure you clean up any cruft left over from previous
   builds or editing. You want to make sure that the directory contains
   only what you want to call "source" from which everything else is
   built.
   
   If this is not the first import from this "Vendor", you should also
   compare the output of "find . ! -name CVS -print | sort" executed both
   at the head of a checked out working directory and at the head of the
   sources to be imported. If you find any deleted or renamed files, you
   have to deal with them by hand. (See 4B.8 on renaming.)
   
   "cd" into your source directory and type:
   
            cvs import -m "Message" <repos> <Vendor-Tag> <Release-Tag>

   where <repos> is the relative directory pathname within the Repository
   that corresponds to the sources you are importing.
   
   You might also consider using the "-I !" option to avoid ignoring
   anything. It is easier to remove bogus files from the Repository than
   to create a sparse tree of the ignored files and rerun "import".
   
   For example, if the FSF, CVS, Make and I are still active in the year
   2015, I'll import version 89.53 of GNU make this way:
   
            cvs import -m "GNUmake V89.53" gnu/make GNU GNUMAKE_89_53

   See 3H.13 for more details.
   
   Last modified: _6/13/1997_
   
    3. Why does import put files on a branch? Why can't I work on the main
    trunk instead of a Vendor branch? 
    
   This was a Design choice. The Vendor branch is the way "import" deals
   with a Vendor release. It is a solution to the Engineering problem of
   how to merge multiple external releases of Vendor-supplied sources
   into your ongoing work. The Vendor releases are kept on a separate,
   special, "Vendor" branch and your work is kept on the RCS trunk. New
   Vendor releases are imported onto the Vendor branch and then merged
   into your work, if there is any, on the trunk.
   
   This way, you can use CVS to find out not only about your work, but
   you can also find out what the Vendor changed by diffing between two
   of the Release Tags you handed to "import".
   
   CVS was designed to work this way. If you use CVS in some other way,
   you should think carefully about what you are doing.
   
   Note that the CVS "Main Branch" and the RCS Main Trunk are not the
   same. Placing files on the Vendor Branch doesn't keep you from
   creating a development branch to work on.
   
   See Section 4C, on Branching.
   
   If you are not working with 3rd party (i.e. Vendor) sources, you can
   skip the "import" and avoid the Vendor branch entirely. It works just
   as well to move pre-existing RCS files into Repository directories.
   
   You can create a whole Repository tree by copying a directory
   hierarchy of normal source files directly into the Repository and
   applying CVS to it. Here's an idea you should *test* before using:
   
                cd <your source tree>
                set source = `pwd`
                set module = xyzzy      <<== Your choice of directory name
                mkdir $CVSROOT/$module
                cd $CVSROOT/$module
                (cd $source; tar cf - .) | tar xvpBf -
                find . -type f -exec ci -t-Original. {} \;

   The RCS "ci" command, without -u or -l options, will turn your source
   file into an RCS (",v") and delete the original source.
   
   Last modified: _6/13/1997_
   
    4. Is there any way to import binary files? 
    
   If you configured CVS to use the GNU version of "diff" and "diff3",
   then you can import any kind of file.
   
   Binary files with RCS keywords in them are a problem, since you don't
   want them to expand.
   
   If the tree you are about to "import" is entirely filled with binary
   files, you can use the '-ko' option on "import". Otherwise, I would
   run the import normally, then fix the binary files as described below
   in 3H.5.
   
   See 4D.1 on Binary files.
   
   Last modified: _6/13/1997_
   
    5. Why does "import" corrupt some binary files? 
    
   The RCS "co" command, when it is invoked by a CVS "checkout" or
   "update" (or after a "commit") command, searches for and expands a
   list of keywords within the file. They are documented in the RCS "co"
   man page. Strings such as "$\Id$" (or "$\Id:"), or "$\Revision$" (or
   "$\Revision:") are altered to the include the indicated information.
   
   [[Note: The keywords should appear in the text without the '\'
   character I have inserted to *avoid* expansion here. The only real RCS
   keywords in this document are at the top of the file, where I store
   the Revision and Date.]]
   
   If RCS keyword strings show up in a binary file, they will be altered
   unless you set the '-ko' option on the RCS files to tell RCS to keep
   the original keyword values and not to expand new ones. After
   "import", you can set the '-ko' option this way:
   
                cvs admin -ko <file>
                rm <file>
                cvs update <file>

   After an import that didn't use '-ko' (because the whole tree wasn't
   of binary files) you should fix up the binary files as described above
   before checking out any new copies of the files and before updating
   any working directories you checked out earlier.
   
   See 4D.1 on Binary files.
   
   Last modified: _6/13/1997_
   
    6. How do I retain the original $\Revision$ strings in the sources? 
    
   If you want to leave old RCS keywords as they are, you can use the
   '-ko' tricks described above.
   
   Last modified: _6/13/1997_
   
    7. I imported some files for the Yarg compiler that compiles files with a
    suffix of ".yarg" and whose comment prefix is "YARG> ". When I check them
    out, they will no longer compile because they have this junk in them. Why? 
    
        YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>
        YARG> $\Log:
        # Revision 1.3  1998/03/03  00:16:16  bubba
        # What is 2+2 anyway?
        #
        # Revision 1.2  1998/03/03  00:15:15  bubba
        # Added scorekeeping.
        YARG>
        YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>

   Well bubba, "Yarg" hasn't hit the big time yet. Neither RCS nor CVS
   know about your suffix or your comment prefix. So you have two
   choices:
   
     Check out the Yarg-less module, and tell all the files about your
   comment prefix. Visit each directory and type:
   
                cvs admin -c"YARG> " *.yarg

   If *all* files in the whole directory tree are Yarg files, you can use
   this instead:
   
                cvs admin -c"YARG> " .

   Then save any changes you made, remove all the "*.yarg" files and grab
   new copies from the Repository:
   
   rm *.yarg (or: find . -name '*.yarg' -exec rm {} ';') (or: find .
   -name '*.yarg' -print | xargs rm) (or: find . -name '*.yarg' -print0 |
   xargs -0 rm if you have spaces in filenames and the GNU find/xargs.)
   cvs update
   
   It might be faster to remove the whole directory and check it out
   again.
   
     Change the import.c file in the CVS sources and add the .yarg
   suffix, along with the "YARG> " comment prefix to the "comtable"
   array.
   
   If you ever plan to add new files with $\Log in them, you should also
   go into the RCS sources and make the same change in the table
   contained in the "rcsfnms.c" file.
   
   Then delete the imported files from the Repository and re-"import" the
   sources.
   
   Last modified: _6/13/1997_
   
    8. How do I make "import" save the timestamps on the original files? 
    
   Use "import -d" to save the current timestamps on the files as the RCS
   revision times.
   
   See 4D.8 for another aspect of file timestamps.
   
   Last modified: _6/13/1997_
   
    9. Why can't I "import" 3 releases on different branches? 
    
   I'll bet you typed something like this:
   
                cd /src/blasto.v2
                cvs import -b 1.1.2  VENDOR2 Version2
                cd /src/blasto.v3
                cvs import -b 1.1.3  VENDOR3 Version3
                cd /src/blasto.v4
                cvs import -b 1.1.4  VENDOR4 Version4

   This is wrong, or at least it won't help you much. You have created
   three separate Vendor branches, which is probably not what you wanted.
   
   Earlier versions of CVS, as described in Brian Berliner's Usenix
   paper, tried to support multiple Vendor branches on the theory that
   you might receive source for the *same* program from multiple vendors.
   It turns out that this is very rare, whereas the need to branch in
   *your* development, for releases and for project branches, is much
   greater.
   
   So the model now is to use a single vendor branch to contain a series
   of releases from the same vendor. Your work moves along on the Main
   Trunk, or on a CVS branch to support a real "branch in development".
   
   To set this up, you should type this instead of the above:
   
                cd /src/blasto.v2
                cvs import VENDOR Version2
                cd /src/blasto.v3
                cvs import VENDOR Version3
                cd /src/blasto.v4
                cvs import VENDOR Version4

   Last modified: _6/13/1997_
   
    10. What do I do if the Vendor adds or deletes files between releases? 
    
   Added files show up with no extra effort. To handle "removed" files,
   you should always compare the tree structure of the new release
   against the one you have in your Repository. If the Vendor has removed
   files since the previous release, go into a working directory
   containing your current version of the sources and "cvs remove"
   (followed by "cvs commit" to make it really take effect) each file
   that is no longer in the latest release.
   
   Using this scheme will allow you to "checkout" any version of the
   vendor's code, with the correct revisions and files, by using
   "checkout -r Version[234]".
   
   Renames are harder to find, since you have to compare file contents to
   determine that one has occurred. If you notice one, see 4B.8 on
   renaming files.
   
   Last modified: _6/13/1997_
   
    11. What about if the Vendor changes the names of files or directories, or
    rearranges the whole structure between releases? 
    
   Currently CVS can't handle this cleanly. It requires "renaming" a
   bunch of files or directories.
   
   See 4B.8 on "renaming" for more details.
   
   What I generally do is to close the Repository for a while and make
   changes in both the Repository and in a copy of the vendor release
   until the structure matches, then execute the import.
   
   If you ever have to check out and build an old version, you may have
   to use the new, or completely different Makefiles.
   
   Last modified: _6/13/1997_
   
    12. I thought "import" was for Vendor releases, why would I use it for code
    of my own? Do I have to use import? 
    
   For code you produce yourself, "import" is a convenience for fast
   insertion of whole trees. It is not necessary. You can just as easily
   create ",v" files using the RCS "ci" command and move them directly
   into the Repository.
   
   Other than the CVSROOT directory, the Repository consists entirely of
   directories of ",v" files. The Repository contains no other state
   information.
   
   See Section 4B, on Setting up and Managing the Repository.
   
   Last modified: _6/13/1997_
   
    13. How do I import a large Vendor release? 
    
   When the sum of the changes made by the Vendor and the changes made by
   local developers is small, "import" is not a big problem. But when you
   are managing a large Repository, any care taken up front will save you
   time later.
   
   First read the following, then, before executing "import", see the
   questions in Section 4C dealing with branch merges and Vendor branch
   merges.
   
     If this is not the first import of this code, before starting, rtag
   the whole directory you will be changing.
   
     The first step is to make sure the structure of the new files
   matches the structure of the current Repository.
   
   Run "find . -print | sort" on both trees and "diff" the output.
   
     Alter the "source" tree until the "diff" (of the list of filenames,
   not of the whole trees) shows that the directory structures are
   equivalent.
   
   The "comm" command, if you have it, can help figure out what has been
   added or deleted between releases.
   
     If they deleted any files, you can handle them cleanly with "cvs
   remove". The command "comm -23 files.old files.new" will show you a
   list of files that need to be removed.
   
   You should examine the list first to see if any have been renamed
   rather than simply deleted.
   
     If they renamed any files, see 4B.8 on renaming files.
   
     Remember to *SAVE* the output from the import command.
   
     When you have dealt with removed and renamed files, then you can
   execute the import:
   
   cd <new source>
           cvs import -I ! -m "Message" <repos> <VendorTag> <ReleaseTag>

   Where
   
   "-I !" is an optional argument that keeps "import" from ignoring
   files. The comparison of the "find" commands above will probably avoid
   the need for this, but it is easier to remove files from the
   Repository than to run a subset "import" to catch just the ignored
   files. [You might have to quote or backwhack the '!'.]
   
           Message      is the log message to be stored in the RCS files.

           <repos>      is a relative path to a directory within the
                        Repository.  The directory <new source> must be at
                        the same relative level within the new sources as
                        the <repos> you give is within the Repository.  (I
                        realize this is not obvious.  Experiment first.)

           <VendorTag>  is a Tag used to identify the Vendor who sent you
                        the files you are importing.  All "imports" into
                        the same <repos> *must* use the same VendorTag.
                        You can find it later by using the "log" command.

   <ReleaseTag> is a Tag used to identify the particular release of the
   software you are importing. It must be unique and should be mnemonic
   -- at least include the revision number in it. (Note: you can't use
   '.' characters in a Tag. Substitute '_' or '-'.)
   
     There will be six categories of files to deal with. (Actually there
   are eight, but you have already dealt with "removed" and "renamed"
   files.)
   
   If this is the first "import" into a given <repos> directory, only the
   first three of these ('I', 'L' and 'N') can occur.
   
     Ignored file.
   
   CVS prints: I filename
   
   You'll need to examine it to see if it *should* have been ignored. If
   you use "-I !", nothing will be ignored.
   
     Symbolic link.
   
   CVS prints: L linkname
   
   Links are "ignored", but you'll probably want to create a "checkout
   helper" function to regenerate them.
   
     New file.
   
   CVS prints: N filename
   
   CVS creates a new file in the Repository. You don't have to do
   anything to the file, but you might have to change Makefiles to refer
   to it if this is really a new file.
   
     A file unchanged by the Vendor since its last release.
   
   CVS prints: U filename
   
   CVS will notice this and simply add the new ReleaseTag to the latest
   rev on the Vendor branch.
   
   No work will be needed by you, whether you have changed the file or
   not. No one will notice anything.
   
     A file changed by the Vendor, but not by you.
   
   CVS prints: U filename
   
   CVS should add the file onto the vendor branch and attach the Release
   Tag to it.
   
   When you next execute "update" in any working directory you'll get the
   new revision.
   
     A file changed by both the Vendor and by you.
   
   CVS prints: C filename
   
   These are the trouble files. For each of these files (or in groups --
   I usually do one directory at a time), you must execute:
   
                    cvs update -j <PreviousReleaseTag> -j <ReleaseTag>
                or
                    cvs update -j <VendorTag:yesterday> -j <VendorTag>

   It will print either 'M' (if no overlaps) or 'C', if overlaps. If a
   'C' shows up, you'll need to edit the file by hand.
   
   Then, for every file, you'll need to execute "cvs commit".
   
   See the part of Section 4C dealing with branch merges.
   
     If you are truly performing a large import, you will most likely
   need help. Managing those people is another problem area.
   
   Since the merge of the Vendor branch is just like any other merge, you
   should read section 4C for more info about performing and cleaning up
   merges.
   
   The larger the import, and the larger the group of people involved,
   the more often you should use "tag" and "rtag" to record even trivial
   milestones. See 4C.14, especially the "paranoid" section.
   
   Before starting the import, you should install and test a "commitinfo"
   procedure to record all commits in a file or via Email to a mail
   archive. Along with the tags you placed on the Repository before the
   import, this archive will help to track what was changed, if problems
   occur
   
   There are four stages to the recovery:
   
     Parcel out the work -- Effective Emacs Engineering.
   
   As input to the assignment process, you might want to examine the tree
   and record the last person who changed the file. You can also
   research, if you don't already know, who is expert in each area of the
   software.
   
   Examine the import log (you saved the output, right?), estimate how
   much work is involved in each area and assign groups of files to
   individual developers. Unless some directory is immense, it is easier
   to manage if you assign whole directories to one person.
   
   Keep a list. Suggest a completion date/time. Tell them to "commit" the
   file when they are finished with the merge. If you tagged the
   Repository before starting the import, you should have no trouble
   figuring out what happened.
   
   If you can, find out (or tell them) which working directory to use.
   You should verify that the working directory they use is on the Main
   Branch ("update -A") and without modified files.
   
   If you trust your crew, have them notify you by Email. Have them send
   you the output from "cvs update" in their working directory. You might
   have to poll some people until you are certain they have finished, or
   have given up. (This is not an invention. I've heard a false, "Yeah,
   sure. I finished yesterday," more times that you'd believe.)
   
   When all reports are in, go on to the Source Verification stage.
   
     Source Verification -- CVS and other Tools.
   
   If you didn't dictate which ones to use, find all working directories
   and run "cvs -n update" in all of them. The history command and the
   "commitinfo" log you set up might help to find checked out working
   directories.
   
   Sticky conflict flags will help, but they can't recover from
   sloppiness or incompetence. You might want to check everything out
   into a tree and grep for the parts of the merge conflict markers CVS
   doesn't look for. CVS looks for the string '^>>>>>>> '. The merge
   operation also puts '^<<<<<<< ' and '^======= ' markers in the file
   that careless developers might leave there.
   
   If you find problems simply by looking at the source files and working
   directories, start the flogging now. Resolving the textual conflicts
   is the easy part. Weed the turkeys out before reaching the next part
   of the cleanup -- the resolution of logical conflicts.
   
   Then apply a set of post-commit tags.
   
     Logical Verification -- Diff and powerful eyeballs.
   
   No source control system can solve the problem of resolving
   distributed conflicts in program logic. If you change the argument
   template for function A (defined in file A.c) and add new calls to
   function A from within function B (defined in file B.c) using the old
   argument format, you are outside the realm of CVS's competence.
   
   Assign someone to understand what the Vendor changed by running "cvs
   diff -c -r <PreviousReleaseTag> <ReleaseTag>", where the tags were
   those handed to the last two invocations of "import".
   
   Then have the same person compare that output (logically or you can
   actually diff the diffs) to the output of the similar "cvs diff -c -r
   <pre-import-tag> <post-commit-tag>". The two sets of differences
   should be almost identical. They should both show only the work *you*
   have performed.
   
     Product Verification -- Build and Test.
   
   Don't let your help off the hook until you verify that the merge
   actually produced something that can compile and pass tests. Compiling
   should really be part of the logical verification phase, but you
   should test the output of the build system before declaring victory
   and releasing the troops.
   
     After it is all built, apply another set of tags to mark the end of
   the "import process". You can delete the intermediate tags you added
   during source and logic testing, but keep the "pre-import" and
   "post-import" tags forever.
   
   Of course, experience can tell you when to skip a step. But I'd start
   out by considering each one as necessary unless you can prove
   otherwise.
   
   Last modified: _6/13/1997_
   
    14. Explain: ERROR: cannot create link to <file>: Permission denied 
    
   This error appears when you try to execute a second (or later)
   "import" into the same module from a directory to which you don't have
   write access.
   
   The "link error" is caused by a feature purposely added to speed up
   the import.
   
   Though the error message is somewhat strange, it indicates that
   "import" is supposed to be executed only in writable directories.
   
   Last modified: _6/13/1997_
   
    15. Where does the -m <message> go when the file doesn't change? 
    
   The <message> handed to import is used as an RCS log message, but only
   if the imported file changed since the last version on the Vendor
   branch. If the imported file hasn't changed, then no new revision is
   created. The <ReleaseTag> is still applied, but to the previous
   revision. So the Tags are still correct, but the message is lost.
   
   Maybe it should be appended to the previous log message. But currently
   it isn't.
   
   Last modified: _6/13/1997_
   
    16. How do I "import" just the files ignored by a previous "import"? 
    
   A real answer follows, but first, an editorial:
   
   I am now convinced that you should always use the "-I !" option.
   Removing a few extraneous files from the Repository is a lot easier
   than the recovery step described below.
   
   Let's assume your original import procedure was: (We assume there is
   enough disk space in /tmp.)
   
   cd <head-of-vendor-tree>
            cvs import -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3 | tee /tmp/IMP

   To import just the files ignored by "import", I would do this:
   
     Create a list of the ignored files to import:
   
   cd <head-of-vendor-tree> awk '/^I / {print $2}' /tmp/IMP | sed
   's|^gnu/xyz/||' > /tmp/IG [Edit the IG file to contain just the files
   you want.]
   
     Then create a sparse directory by handing your list to the GNU
   version of "tar", installed in many places as "gtar":
   
   mkdir /tmp/FIXUP gtar -T /tmp/IG -c -f - . | (cd /tmp/FIXUP; gtar xvBf
   -)
   
     Then rerun the import. Use the exact same command, but execute it in
   the sparse directory tree you just created. And this time, tell it not
   to ignore anything.
   
   cd /tmp/FIXUP
           cvs import -I ! -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3

   Last modified: _6/13/1997_
   
    17. Why did "import" ignore all the symlinks? 
    
   This is another design choice.
   
   Like the Unix "tar" command, "import" could sprout an option to follow
   symbolic links, but I don't think CVS will ever follow symbolic links
   by default.
   
   Two possible future enhancements have been seriously discussed:
   
     Treat symbolic links as data in its parent directory (the way
   ClearCase does) in some sort of per-directory control file.
   
     Treat symbolic links as version-controlled elements themselves,
   whose data is the value of readlink(2).
   
   For now, they are simply ignored.
   
   If you want to save and reconstruct symlinks, you might want to define
   a "checkout" or "update" program in the modules file which could
   consult a file kept under CVS in your working directory and make sure
   the specified links are in place.
   
   Last modified: _6/13/1997_
   
  Category: /Commands_/log_lo_rlog/
  
   " + "log", "lo", "rlog""
   
    1. What is "log" for? 
    
   To provide an interface to the RCS "rlog" command, which displays
   information about the underlying RCS files, including the revision
   history and Tag (RCS calls it a "symbol") list.
   
   Last modified: _6/13/1997_
   
    2. How do I extract the log entries between two revisions? 
    
   If both <rev1> and <rev2> are on the same branch, you can get what you
   are looking for with: (If they aren't on the same branch you'll either
   get an error or a display of the whole change log.)
   
                cvs log -r<rev1>:<rev2> <file>

   If you want all the revisions on the branch from <rev1> to the end of
   the branch <rev1> is on, you can use:
   
                cvs log -r<rev1>: <file>

   (If <rev1> is a numeric RCS symbol attached to a branch revision with
   an even number of '.'s in it, you get the whole branch.)
   
   If you want all the revisions on the branch from the beginning of the
   branch <rev2> is on up to revision <rev2>, you can use:
   
                cvs log -r:<rev2> <file>

   Note: Depending on whether <rev1> and <rev2> are:
   
                        - numeric or symbolic
                        - in the file or not
                        - on the same branch or not

                the RCS "rlog" (and therefore the "cvs log") command will
                display some combination of:

                        - error messages
                        - (intuitively correct) partial log listings
                        - a display of the entire change log.

   Last modified: _6/13/1997_
   
    3. How do I extract the log entries on a whole branch? 
    
                cvs log -r<rev> <file>

   where <rev> must be a branch revision (one with an even number of
   dots) or a *non-branch* tag on a branch revision. Non-branch tags on a
   branch revision are not normally attached by CVS, to add one you will
   have to explicitly tag a physical branch number within each file.
   Since these branch numbers are almost never the same in different
   files, this command is not all that useful.
   
   The intuitive command (at least from the CVS perspective):
   
                cvs log -r<branch_tag> <file>

   does not work.
   
   Last modified: _6/13/1997_
   
    4. How do I generate ChangeLogs from RCS logs? 
    
   A program called rcs2log is distributed as part of GNU Emacs 19. A
   (possibly older) version of this program appears in the contrib
   directory of the cvs source tree.
   
   Last modified: _6/13/1997_
   
    5. Why does "log" tell me a file was committed exactly 5 hours later 
    
   than I know it was?
   
   I can tell by this question that you were working in a time zone that
   is 5 hours behind GMT (e.g. the U.S. East Coast in winter).
   
   RCS file dates are stored in GMT to allow users in different time
   zones to agree on the meaning of a timestamp. At first glance this
   doesn't seem necessary, but many companies use distributed file
   systems, such as NFS or AFS, across multiple timezones.
   
   Some standard form must be used. GMT, as the "grid origin", is an
   obvious candidate. The only other reasonable choice is to put the
   timezone information in all the time stamps, but that changes the RCS
   file format incompatibly, a step which has been avoided in the last
   few RCS releases.
   
   Last modified: _6/13/1997_
   
  Category: /Commands_/patch_pa_rdiff/
  
   " + "patch", "pa", "rdiff""
   
    1. What is "patch" for? 
    
   To produce a "diff" between tagged releases to be handed to the
   "patch" command at other sites. This is the standard way that source
   patches are distributed on the network.
   
   Last modified: _6/13/1997_
   
    2. Why does "patch" include files from the Attic when I use '-D'? 
    
   See the explanation of the same problem with "update -D" contained in
   section 5B.
   
   Last modified: _6/13/1997_
   
    3. How do I make "patch" produce a patch for one or two files? It seems to
    work only with modules. 
    
   Patch is intended for producing patches of whole modules between
   releases to be distributed to remote sites. Instead of "patch", you
   can use the "diff" command with the '-c' context option:
   
             cvs diff -c -r <rev/tag> -r <rev/tag> <file1> . . .

   The patch command will be able to merge such a "diff" into the remote
   source files.
   
   If you configured CVS to use a version of "diff" that supports the
   '-u' option, you can produce a more compact "patch" in "unidiff"
   format. The latest revisions of the patch command can parse and apply
   patches in "unidiff" format.
   
   Last modified: _6/13/1997_
   
  Category: /Commands_/release_re_rel/
  
   " + "release", "re", "rel""
   
    1. What is "release" for? 
    
   To register that a module is no longer in use. It is intended to
   reverse the effects of a "checkout" by adding a record to the history
   file to balance the checkout record and by optionally allowing you to
   delete the checked-out directory associated with the module name.
   
   Last modified: _6/13/1997_
   
    2. Why can't I reverse a "cvs checkout path/name/subdir" with a "cvs
    release path/name/subdir" without an "unknown module name"? 
    
   A simplistic implementation. (I can say this -- I wrote it.)
   
   The "release" function was written for CVS 1.2 under the assumption
   that the "module name" is a first class, unavoidable interface to the
   Repository, allowing no way to retrieve anything other than by module
   name. Though it is easier to program that way, many users of CVS
   believe the modules support to be too primitive to allow such a
   limitation.
   
   Since "release" was written, other parts of CVS broke that assumption.
   It needs to be revised.
   
   Last modified: _6/13/1997_
   
    3. Why can't I "release" portions of a checked out directory? I should be
    able to "release" any file or sub-directory within my working directory. 
    
   This isn't really a limitation in "release", per se. CVS doesn't try
   to keep track of which files in which directories are "checked out"
   and which are just lying there. You can delete directories and
   "update" will not bring them back unless you add a special "-d"
   option.
   
   In other words, CVS doesn't keep track of how you adjust the partition
   between files you consider part of your working set and files that
   were checked out because they are part of the same module or
   directory. And neither does "release".
   
   In future CVS releases, "release" might become sophisticated enough to
   handle both the reversal of a "checkout" and the deletion of random
   portions of the working directory, but it isn't that way now.
   
   Last modified: _6/13/1997_
   
    4. I removed the tree that I was about to start working on. How do I tell
    cvs that I want to release it if I don't have it anymore? 
    
   See 3G.4.
   
   Last modified: _6/13/1997_
   
    5. Why doesn't "release -d module" reverse a "checkout module"? 
    
   It does, if you are using "module" in a way that "release" expects: a
   non-alias string in the left column of the "modules" database.
   
   If "module" is really an alias, or if you are using a relative path in
   the place of "module", or if you renamed the directory with the -d
   option in the modules file or on the "checkout" command line, then the
   current version of "release" won't work.
   
   Future versions of "release" will probably fix most of these.
   
   Last modified: _6/13/1997_
   
    6. Why can't I release a module renamed with "cvs checkout -d"? 
    
   The current version of "release" doesn't know how to track the
   renaming option ('-d') of the "checkout" command. It will probably be
   fixed in the future.
   
   Last modified: _6/13/1997_
   
  Category: /Commands_/remove_rm_delete/
  
   " + "remove", "rm", "delete""
   
    1. What is "remove" for? 
    
   To remove a file from the working branch. It removes a file from the
   main branch by placing it in an "Attic" directory.
   
   Last modified: _6/13/1997_
   
    2. Why doesn't "remove" work on directories when it appears to try? 
    
   Oversight. It should be able to delete an empty directory, but you
   still don't have a way to remember when it was there and when it
   disappeared to allow the "-D " option to work.
   
   You'll have to remove the working directory and the matching directory
   in the Repository.
   
   Note that you want to do a _cvs remove dir_ in the working directory,
   do a cvs commit, and then do a _rmdir dir_ in the Repository.
   (msusrtsp.mark at eds dot com)
   
   Last modified: _12/18/1997_
   
    3. I don't like removing files. Is there another way to ignore them? 
    
   There's no reason to be hasty in using the "remove" command.
   
   If there is a way to ignore files in your build procedures, I'd just
   do that. Later, when you decide that the files are really ancient, you
   can execute a "remove" command to clean up.
   
   The CVS "ignore" concept can't ignore files already in CVS.
   
   Last modified: _6/13/1997_
   
    4. I just removed a file. How do I resurrect it? 
    
   If you executed "remove", but haven't typed "commit" (you can tell
   this by the 'R' notation that "update" prints next to the file), you
   can execute "add" to reverse the "remove".
   
   If you followed the "remove" with a "commit", you'll have to move it
   back out of the Attic by hand:
   
   I use something like this: (csh-like syntax)
   
                set repos = `cat ./CVS/Repository`
                mv $repos/Attic/filename,v $repos/filename,v

   (If you use relative paths in your Repository files, that first line
   becomes: set repos = $CVSROOT/`cat ./CVS/Repository`)
   
   While a file is in the Attic, you can't "add" another file by the same
   name. To add such a file you either have to move it by hand as in the
   above, or delete it from the Attic.
   
   The main reason for the Attic is to retain files with tags in them. If
   you execute: "update -r <oldtag>", files with <oldtag> attached to
   some revision will be taken from the normal Repository area and from
   the Attic. That's why you can't "add" a file with the same name.
   "remove" only moves a file off the main branch, it doesn't obliterate
   it.
   
   Last modified: _6/13/1997_
   
    5. Why doesn't "remove" delete the file? Instead, it prints an error
    message and tells me to remove the file by hand. 
    
   Design choice. Unix software written within last decade, usually
   requires an extra verification step, such as answering a question or
   adding a flag on the command line. CVS currently requires that you
   delete the file first unless you specify the '-f' (force) option,
   which deletes the file before performing "cvs remove".
   
   Last modified: _6/13/1997_
   
  Category: /Commands_/rtag_rt_rfreeze/
  
   " + "rtag", "rt", "rfreeze""
   
    1. What is "rtag" for? 
    
   To add a symbolic label (a "tag") to the last committed revisions of a
   module directly in the Repository.
   
   Last modified: _6/13/1997_
   
    2. Why use "rtag"? It assumes no one is changing the Repository. 
    
   Though the "tag" command is more useful in marking the revisions you
   have in a particular working directory, "rtag" is much handier for
   whole-Repository actions, which occur at major release boundaries.
   
   Last modified: _6/13/1997_
   
    3. What revision does "rtag -r <tag1> <tag2>" actually put the tag on? 
    
   In short, the '-r' option is another way to select the revision to
   tag. The revision is selected the same way for all commands that
   accept a "-r <tag/rev>" option.
   
   Depending on whether <tag1> is a <branch_tag>, or a non-branch <tag>
   and on whether you use the '-b' option to "rtag", you get four
   different results:
   
     rtag -r <tag1> <tag2>
   
   Adds the non-branch tag <tag2> to the same revision that the
   non-branch tag <tag1> is attached to.
   
   Example:
                <tag1>          --> TT1
                <tag2>          --> TT2
                <file>          --> Symbols: TT1:1.4
                After           --> Symbols: TT1:1.4,TT2:1.4

     rtag -r <branch_tag1> <tag2>
   
   Adds the non-branch tag <tag2> to the HEAD of (the highest revision
   number on) the branch labelled with tag <branch_tag1>.
   
   Example:
                <branch_tag1>   --> BR1
                <tag2>          --> TT2
                <file>          --> Symbols: BR1:1.2.0.2 (1.2.2.5 is HEAD)
                After           --> Symbols: BR1:1.2.0.2,TT2:1.2.2.5

   If the branch tagged by <branch_tag1> has not been created, then the
   tag shows up on the branch point revision:
   
   Example:
                <branch_tag1>   --> BR1
                <tag2>          --> TT2
                <file>          --> Symbols: BR1:1.2.0.2 (No 1.2.X exists.)
                After           --> Symbols: BR1:1.2.0.2,TT2:1.2

     rtag -b -r <tag1> <branch_tag2>
   
   Adds the magic branch tag <branch_tag2> to the revision that the
   non-branch tag <tag1> is attached to, preparing it to be a branch
   point.
   
   Example:
                <tag1>          --> TT1
                <branch_tag2>   --> BR2
                <file>          --> Symbol: TT1:1.4
                After           --> Symbol: TT1:1.4, BR2:1.4.0.2

     rtag -b -r <branch_tag1> <branch_tag2>
   
   Adds the magic branch tag <branch_tag2> to the revision at the HEAD of
   (the highest revision number on) the branch labelled with
   <branch_tag1>, preparing it to be a branch point.
   
   Example:
                <branch_tag1>   --> BR1
                <branch_tag2>   --> BR2
                <file>          --> Symbol: BR1:1.2.0.2 (1.2.2.5 is HEAD)
                After           --> Symbol: BR1:1.2.0.2,BR2:1.2.2.5.0.2

   If the branch tagged by <branch_tag1> has not been created, then the
   tag shows up as a second branch off the same branch point revision:
   
   Example:
                <branch_tag1>   --> BR1
                <tag2>          --> TT2
                <file>          --> Symbols: BR1:1.2.0.2 (No 1.2.X exists.)
                After           --> Symbols: BR1:1.2.0.2,TT2:1.2.0.4

   In all four cases above, if <tag2> already exists on the file, you get
   an error unless you specify the '-F' option.
   
   In all four cases, if <tag1> does not exist on the file, <tag2> is not
   added unless you specify the '-f' option.
   
   Last modified: _6/13/1997_
   
    4. What happens if the tags are the same in "rtag -r <tag> <tag>"? 
    
   Again, there are four cases depending on whether <tag> is a branch
   tag, or a non-branch tag and on whether you use the '-b' option to
   "rtag":
   
     rtag -r <tag> <tag>
   
   Is a no-op. It does nothing even with '-F' specified.
   
   If you add the '-f' option ("rtag -f -r <tag> <tag>"), then <tag> is
   attached to the latest revision on the Main Branch if the file does
   *not* already have <tag> on some revision.
   
   If the <tag> is already on the file, using "rtag -f" is still a no-op.
   
     rtag -r <branch_tag> <branch_tag>
   
   Produces an error, since the <branch_tag> is already on some revision
   of the file.
   
   But, "rtag -F -r <branch_tag> <branch_tag>" turns the magic branch tag
   into a non-branch tag.
   
   Symbols: BR1:1.4.0.2 becomes Symbols: BR1:1.4
   
     rtag -b -r <tag> <tag>
   
   Produces an error, since the <tag> is already on the file.
   
   But, "rtag -F -b -r <tag> <tag>" turns the non-branch tag into a magic
   branch tag.
   
   Symbols: BR1:1.4 becomes Symbols: BR1:1.4.0.2
   
     rtag -b -r <branch_tag> <branch_tag>
   
   Produces an error, since the <branch_tag> is already on the file.
   
   But, "rtag -F -b -r <branch_tag> <branch_tag>" increments the branch
   number. It essentially removes the branch and creates a new one by the
   same name.
   
   Symbols: BR1:1.2.0.4 becomes Symbols: BR1:1.2.0.6
   
   Last modified: _6/13/1997_
   
    5. Why doesn't "rtag -b -r <branch_tag1> <branch_tag2>" rename or duplicate
    a magic branch tag? 
    
   None of the "tag" or "rtag" options rename anything. They only apply
   (or, with the '-F' option, move) tags to specific revisions in the
   file.
   
   See 3M.[3-4] above for details of how it works.
   
   To rename a non-branch tag, see 3O.9. To rename a magic branch tag,
   see 4D.5
   
   Last modified: _6/13/1997_
   
  Category: /Commands_/status_st_stat/
  
   " + "status", "st", "stat""
   
    1. What is "status" for? 
    
   To display the status of files, including the revision and branch you
   are working on and the existence of "sticky" information.
   
   Last modified: _6/13/1997_
   
    2. Why does "status" limit the File: at the top to 17 characters? 
    
   Designed that way to line up with other data. You can find the whole
   filename in the line beginning with "RCS version:", which is not
   limited in length.
   
   Last modified: _6/13/1997_
   
    3. Why does it print "Sticky" lines when the values are "(none)"? 
    
   Oversight. It should probably elide lines without information.
   
   Last modified: _6/13/1997_
   
    4. Shouldn't the status "Needs Checkout" be "Needs Update"? 
    
   Probably.
   
   [[Did this show up in CVS 1.4?]]
   
   Last modified: _6/13/1997_
   
  Category: /Commands_/tag_ta_freeze/
  
   " + "tag", "ta", "freeze""
   
    1. What is "tag" for? 
    
   To add a symbolic label (a "tag") to the RCS files last checked out,
   updated or committed in a working directory.
   
   Last modified: _6/13/1997_
   
    2. What is the difference between "tag" and "rtag"? 
    
   The end result of both commands is that a <tag>, or symbolic name, is
   attached to a single revision in each of a collection of files.
   
   The differences lie in:
   
     The collection of files they work on.
   
   "rtag" works on the collection of files referred to by a "module" name
   as defined in the "modules" file, or a relative path within the
   Repository.
   
   "tag" works on files and directories specified on the command line
   within the user's working directory. (Default is '.')
   
   Both commands recursively follow directory hierarchies within the
   named files and directories.
   
     The revisions they choose to tag.
   
   "rtag" places a tag on the latest committed revision of each file on
   the branch specified by the '-r' option. By default it tags the Main
   Branch.
   
   "tag" places a tag on the BASE (i.e. last checked out, updated or
   committed) revision of each file found in the working directory. (The
   BASE revision of a file is the one stored in the ./CVS/Entries file.)
   
     A different set of command line options.
   
   For example, "rtag" takes a "-r <oldtag>" option to retag an existing
   tag. The "tag" command does not.
   
     How it is logged.
   
   Currently "rtag" records the <tag> and the module in the "history"
   file, while "tag" does not.
   
   Last modified: _6/13/1997_
   
    3. Why does "tag -b" not put a tag on the Branch Point revision? How do I
    refer to the Branch Point? 
    
   This is probably an oversight, or a disbelief in the need for it. If
   everything works perfectly, the "update -j" command will do the merge
   you need and you don't need to check up on it by playing with the
   branch point revision.
   
   The '-b' option attaches a magic branch tag to allow CVS later to
   figure out the branch point. The actual revision that <tag> is
   attached to does not exist. References to the branch tag are
   equivalent to references to the latest revision on the branch.
   
   There is no way to refer to the branch point without adding a
   non-branch tag. You might want to add non-branch tags as a habit and
   add branch tags later, possibly immediate after adding the non-branch
   tag. See 4C.3 on Creating a Branch.
   
   Last modified: _6/13/1997_
   
    4. So "{r}tag" labels a bunch of files. What do you use a Tag for? 
    
   You use it to "checkout" the labeled collection of files as a single
   object, referring to it by name.
   
   Anywhere a revision number can be used a Tag can be used. In fact tags
   are more useful because they draw a line through a collection of
   files, marking a development milestone.
   
   The way to think about a Tag is as a curve drawn through a matrix of
   filename vs. revision number. Consider this:
   
   Say we have 5 files (in some arbitrary modules, some may be in 2 or
   more modules by name, some may be in 2 or more modules because of the
   Repository tree structure) with the following revisions:
   
                file1   file2   file3   file4   file5

                1.1     1.1     1.1     1.1  /--1.1*      <-*-  <tag>
                1.2*-   1.2     1.2    -1.2*-
                1.3  \- 1.3*-   1.3   / 1.3
                1.4          \  1.4  /  1.4
                              \-1.5*-   1.5
                                1.6

   At some time in the past, the '*' versions were tagged. Think of the
   <tag> as a handle attached to the curve drawn through the tagged
   revisions. When you pull on the handle, you get all the tagged
   revisions. Another way to look at it is that you draw a straight line
   through the set of revisions you care about and shuffle the other
   revisions accordingly. Like this:
   
                file1   file2   file3   file4   file5

                                1.1
                                1.2
                        1.1     1.3                       _
                1.1     1.2     1.4     1.1              /
                1.2*----1.3*----1.5*----1.2*----1.1     (--- <-- Look here
                1.3             1.6     1.3              \_
                1.4                     1.4
                                        1.5

   I find that using these visual aids, it is much easier to understand
   what a <tag> is and what it is useful for.
   
   Last modified: _6/13/1997_
   
    5. How do I get "tag" and "rtag" to send mail the way "commit" does? 
    
   The "commit" command is supported by two files ("commitinfo" and
   "loginfo") not used by other commands. To do logging the same way for
   "tag" and "rtag" would require another file like loginfo, which
   currently doesn't exist.
   
   The "rtag" command requires a "module" entry, which can specify a
   "tag" program using the "-t programname" option on the module line.
   
   There is no equivalent support for "tag".
   
   Last modified: _6/13/1997_
   
    6. Why can't "tag" handle the '-r' option that "rtag" takes? 
    
   Oversight. The answer is probably "Fixed in a Future Release."
   
   Last modified: _6/13/1997_
   
    7. After a "tag <tag>" in my working directory, why doesn't "checkout -r
    <tag>" somewhere else produce copies of my current files? 
    
   The only reason this would fail, other than misspelling the <tag>
   string, is that you didn't "commit" your work before "tagging" it.
   Only committed revisions may be tagged. Modified files are not marked
   for later tagging.
   
   Last modified: _6/13/1997_
   
    8. Why doesn't "tag" write a history record the way "rtag" does? 
    
   The "rtag" command was originally intended to place major "release"
   tags onto modules. The "tag" functionality was developed to *move* the
   more significant tag when slight changes to individual files sneaked
   in after the release tag was stamped onto the Repository.
   
   The significant event was the "rtag", which was recorded in the
   "history" file for the "history -T" option to work.
   
   It turns out that "tag" is generally more useful than "rtag", so the
   model has changed. Future revisions of CVS will probably store both
   kinds of tags in the history file.
   
   Last modified: _6/13/1997_
   
    9. How do I rename a <tag>? 
    
   For a procedure to rename a branch tag, See section 4D.5 The following
   covers only non-branch tags.
   
   First, pick a <newtag> that is not in use. You could reuse (i.e. move)
   an existing tag to the new revisions using the '-F' option, but that
   will confuse matters when both tags are not already on a file. (It
   will probably confuse "rtag -f" too.)
   
   Use "rtag" to place <newtag> only on revisions attached to <oldtag> in
   the whole Repository, then delete the old one.
   
                cvs rtag -r <oldtag> <newtag> world
                cvs rtag -d <oldtag> world.

   You can also checkout or update your working directory to the <oldtag>
   and "tag" rather than "rtag" the result. But that will take longer and
   it has the chance of producing conflicts.
   
                cvs update -r <oldtag>
                cvs tag <newtag>
                cvs tag -d <oldtag>
                cvs update -A  (or cvs update -r <previous_tag>)

   Last modified: _6/13/1997_
   
  Category: /Commands_/update_up_upd/
  
   " + "update", "up", "upd""
   
    1. What is "update" for? 
    
   The "update" command is by far the most important command and is
   probably also the most used command.
   
   It has five purposes: (And many options.)
   
     To display the status of your working files.
   
   Though a plain "update" also displays the status, it does so after
   possibly altering your working directory. To see the status of your
   working files without changing anything, type:
   
                cvs -n update {optional list of files}

     To merge changes made by others to the branch you are working on
   into your working files.
   
   Each working directory is attached to a branch, usually the Main
   branch. To merge changes made on your working branch since your last
   checkout, update or commit, type:
   
   cvs update {optional list of files}
   
     To merge changes made on another branch into the branch you are
   working on (your "working branch").
   
   If you want to grab a whole branch, from the branch point, which is
   assumed to be on the Main Branch, to the end of the branch, you type:
   
                cvs update -j <branch_tag> {optional files}

   If you want to grab the changes made between two tags or revisions,
   you type:
   
                cvs update -j <tag1> -j <tag2> {optional files}

   (If you are working with a single file, the Tags could also be
   revisions numbers. Unless you take great care to match revision
   numbers across different files (a waste of time given the way Tags
   work), using revision numbers in place of the Tags for multiple files
   would be meaningless.)
   
     To move your working directory to another branch.
   
   A working directory is presumed to be attached to (or working on) a
   particular branch, usually the Main branch. To alter what CVS believes
   to be your working branch, you "move" to that branch.
   
   To move to a tagged branch, type:
   
                cvs update -r <branch_tag> {optional files}

   To move to the Main Branch, type:
   
                cvs update -A {optional files}

   If you have modified files in your working directory, this is not a
   clean move. CVS will attempt to merge the changes necessary to make it
   look like you made the same changes to the new branch as you made in
   the old one. But if you do this twice without resolving the merge
   conflicts each time, you can lose work.
   
     To retrieve old revisions of files.
   
   This option is similar to 4 above but you are not restricted to using
   a <branch_tag>. You may specify any revision or <tag> with '-r' and
   get the specified revision or the tagged revision:
   
                cvs update -r <tag/rev> {optional files}

   Or you may specify any date with '-D':
   
                cvs update -D <date> {optional files}

   The '-p' option sends the revisions to standard output (normally your
   terminal) rather than setting the "sticky" tag and changing the files.
   
   Last modified: _6/13/1997_
   
    2. What do 'U', 'M' and 'C' mean when I type "update"? Are they different
    for "cvs -n update"? 
    
   "cvs update" merges changes made to the Repository, since your last
   "checkout", "update" or "commit", into your working files. You can
   think of it as changing your BASE revision.
   
   "cvs update" prints lines beginning with:
   
   'U' after replacing your unmodified file with a different
                revision from the Repository.

   'M' for two different reasons:
   
     for files you have modified that have not changed in the Repository.
   
     after a merge, if it detected no conflicts.
   
   'C' after a merge, if it detected conflicts. See 2D.7 and 3P.6 for
   more info on conflict resolution and "sticky conflicts."
   
   "cvs -n update" shows what it *would* do, rather than doing it. Or,
   another way of looking at it, "cvs -n update" displays the
   relationship between your current BASE revisions (identified in your
   ./CVS/Entries file) and the HEAD revisions (the latest revisions in
   the Repository).
   
   "cvs -n update" prints lines beginning with:
   
   'U' for files you have not modified that have changed in the
   Repository.
   
   'M' for files you have modified that have not changed in the
   Repository.
   
   'C' for files you have modified that have also been changed in the
   Repository.
   
   See 4C.6 for what the letters mean when merging in from another
   branch. The output is almost the same for a normal update if you
   consider the Repository as the branch and your working directory as
   the "trunk".
   
   Last modified: _6/13/1997_
   
    3. What's the difference between "update" and "checkout"? 
    
   See 3C.4 above.
   
   Last modified: _6/13/1997_
   
    4. Why don't I get new files when I execute "update"? 
    
   There are six reasons for nothing to happen during an "update":
   
     Nothing on your branch changed in the Repository.
   
   If no one has committed anything to the branch you are working on
   (normally the Main branch) since the last time you executed
   "checkout", "update" or "commit", nothing will happen.
   
   It's like shouting "xyzzy" or "plugh" in the wrong room.
   
     You have a "sticky" non-branch <tag> or <date> attached to the
   working files you are trying to "update".
   
   At some time in the past you checked out or updated your directory
   with the "-r <tag>" or "-D <date>" option. Until you do it again with
   a different tag or date, or go back to the Main Branch with "update
   -A", you will never again see any updates.
   
     The ./CVS/Entries.Static file exists and you are expecting a new
   file.
   
   If your ./CVS administrative directory contains a file named
   Entries.Static, no files will be checked out that aren't already in
   the Entries or Entries.Static file.
   
     You forgot to use the '-d' option and are looking for new
   directories.
   
   If you execute "update" without the '-d' option, it will not create
   new directories that have been added to the Repository.
   
     You typed "update" instead of "cvs update".
   
   On most Unix systems, your disk caches are now furiously being flushed
   by multiple update daemons, destroying performance and proving to
   management that you need more CPU power. :-)
   
   On HP systems you might be asked what package you want to install from
   the "update server".
   
     Someone removed (using "admin -o") your BASE revision (the revision
   CVS thought you had in your working directory), then committed a
   "replacement". CVS is now confused because the revision in the
   Repository matches your BASE revision when the files themselves don't
   match. See 3B.6.
   
   Last modified: _6/13/1997_
   
    5. Why does "update" say 'M' both for plain modified files and for
    successful (i.e. conflict-free) merges? Aren't they different? 
    
   A design choice. Yes, they are different internally, but that
   shouldn't matter. Your files are in the same condition after the
   "update" as they were before -- a "diff" will display only your
   modifications. And you are expected to continue onward with parts two
   and three of the normal development cycle: "emacs" (a synonym for
   "edit" in most of the civilized world) and "commit".
   
   Last modified: _6/13/1997_
   
    6. What's a "sticky conflict"? How does it know a conflict occurred? 
    
   When a "cvs update" (or an "update -j") creates a conflict, it prints
   a 'C' and stores the timestamp of the file after the merge in a
   special field in the ./CVS/Entries file.
   
   This conflict indication implies that the merge command altered your
   working file to contain conflict markers surrounding the overlapping
   code segments. For example, say that
   
   - Two developers acquire revision 1.2 of <file> via "checkout" or
   "update".
   
   - Developer A changes line 1 from "9999" to "5555", then commits the
   file, creating revision 1.3.
   
   - Developer B changes line 1 from "9999" to "7777", then tries to
   commit the file, but is blocked because the file is not up to date.
   Developer B then runs "update" and sees the conflict marker 'C'. The
   beginning of the file would look like this:
   
   <<<<<<< <file> The working <file> in question.
            7777                Change made to the working <file>.
            =======
            5555                Change made in the first commit (1.3)
            >>>>>>> 1.3         The revision created by the first commit.

   The conflict is "sticky", which means that until the conflict is
   cleared, the "update" command will continue to display the file's
   status as 'C' and the "status" command will show the file's status as
   "Unresolved Conflict".
   
   Until the conflict is cleared, "commit" is blocked for this file.
   
   The sticky conflict indicator can be cleared by:
   
     Resolving the conflict by editing the file. Two things must happen
   before the conflict is considered resolved:
   
   The timestamp of the file must change. *and* The file must contain no
   conflict markers. (The string searched for in the file is the regexp:
   "^>>>>>>> ".)
   
   After clearing the sticky conflict indicator, you may then commit the
   file normally.
   
     Removing the file and running "update". This throws away the local
   changes and accepts the latest committed file on this branch. No
   commit is needed.
   
     Forcing the commit to happen by using "commit -f". This is probably
   a mistake since there are few lines of real text that begin with
   ">>>>>>> ".
   
   Last modified: _6/13/1997_
   
    7. Is there a feature to tell me what I have changed, added and removed
    without changing anything? 
    
   The command "cvs -n update" will do exactly that.
   
   Last modified: _6/13/1997_
   
    8. Why were all my files deleted when I executed "update"? 
    
   You probably executed "update -r <tag>" some time ago, then removed
   <tag> from the Repository files. "update -r <tag>" will delete a file
   that doesn't contain <tag>.
   
   A way to fix this is to "cd" into your working directory and type:
   
                cvs update -A

   If you don't want the latest revisions on the Main (or Vendor) Branch,
   then decide what Tag (normal or branch) you want and type:
   
                cvs update -r <the_tag_you_want>

   Another way to make a file disappear is to execute "update -D <date>"
   where <date> is before the date stamped onto the first revision in the
   RCS file.
   
   Last modified: _6/13/1997_
   
  Category: /Past__Future_/
  
   " Past & Future "
   
  Category: /Past__Future_/Bugs_and_Patches/
  
   " + Bugs and Patches"
   
    1. Why can't CVS handle deletion of directories? 
    
   An oversight, probably. [[Fixed in a future release?]]
   
   Last modified: _6/13/1997_
   
    2. Why can't CVS handle the moving of sources from one place in the 
    
   directory hierarchy to another?
   
   A "renaming database" has been proposed to track the history of
   pathname changes in the Repository. A general solution is a difficult
   problem. See 4B.8.
   
   Last modified: _6/13/1997_
   
    3. When I typed "cvs update -D <date>", why did it check out all 
    
   sorts of ancient files from the Attic? Shouldn't it just create the
   set of files and revisions that existed at that date?
   
   This seems to be a bug, but is really the lack of any obvious place to
   store the date when a file is "removed".
   
   There are four ranges of dates that CVS has to deal with when trying
   to determine what revision was available on <date>:
   
     Dates before the earliest revision in the file.
   
     Dates between any two revisions in the file.
   
     Dates between the latest revision in the file and the date when the
   file was moved to the Attic by "commit".
   
     Dates after moving the file to the Attic.
   
   Since the date when a file is moved to the Attic is not stored
   anywhere, CVS can't tell the difference between #3 and #4. To avoid
   not producing a file that should exist in case #3, it produces
   extraneous files in case #4.
   
   For the above reason, if you have removed files in the Attic, it is
   better to use "-r <tag>, or even "-r HEAD" than to use a date spec.
   
   If you must use "-D <date>", then you should either archive and delete
   Attic files (losing some past history) or construct your Makefiles to
   work with an explicit list of files and let the old source files stay
   in the working directory. The contents of the revision-controlled
   Makefile can then be considered to contain deletion "information".
   
   Last modified: _6/13/1997_
   
    4. When I typed "cvs update -D <date>" in my branch, why did it screw up
    all my files? 
    
   Currently, the internal routine ("version_ts") that looks up info
   about a file, overrides both the tag and date if *either* the tag or
   date is specified on the command line. If only the date is specified,
   it should not override a branch tag, but it does.
   
   In CVS 1.3, the documented "-D <branch_tag>:<date>" syntax only works
   with the Main Branch and the Vendor Branch.
   
   [[Is this fixed in CVS 1.4? This is one item I didn't check.]]
   
   Last modified: _6/13/1997_
   
    5. When I executed "checkout" into an existing directory I got "No such
    file or directory" errors. Why? 
    
   Though the man page says that "checkout" turns into an "update -d" in
   directories that already exist, it is referring to directories that
   already exist *and* were created by CVS.
   
   When you try to run "checkout" on top of an existing directory
   structure, some of which wasn't created by CVS, it will handle
   directories and non-CVS files within directories already under CVS,
   but it will display the above error on non-CVS files within non-CVS
   directories.
   
   Last modified: _6/13/1997_
   
    6. Why does "update" send all output to the terminal after 26 files have
    been updated? 
    
   CVS uses the "tmpnam()" function to generate temporary file names. The
   ANSI standard for the "tmpnam()" function says:
   
   "The tmpnam function generates a different string each time it is
   called, up to TMP_MAX times. If it is called more than TMP_MAX times,
   the behavior is implementation defined."
   
   Later it says that the value of "TMP_MAX shall be at least 25."
   
   On some platforms, the above specification is taken literally by
   turning "at least 25" into "exactly 26" and by doing something foolish
   (i.e. "implementation defined") after that. Some systems return the
   same name repeatedly, which causes one form of trouble. Others return
   NULL or garbage, which causes a different form of trouble.
   
   The broken systems appear to be cycling a single character through the
   alphabet. SunOS cycles 3 characters through the alphabet, so it won't
   cause trouble until 26 cubed or 17576 calls to "tmpnam()".
   
   Since CVS doesn't depend on the exact format of the tmp files, the
   workaround is to provide a "tmpnam()" that doesn't have a limit on the
   number of calls to it.
   
   Last modified: _6/13/1997_
   
    7. Why does the merge occasionally resurrect lines of code? 
    
   The diff3 program provided by GNU diff version 1.15 has a bug that
   occasionally causes text to come back from the dead.
   
   This is an old problem which you can avoid by upgrading to the latest
   GNU "diffutils" package. If you were using GNU diff version 1.15 and
   plan to upgrade to the latest GNU diff program, see the next question.
   
   Last modified: _6/13/1997_
   
    8. Why does the merge fail when my "rcsmerge" program is configured to use
    GNU diff version 2.1 or later? 
    
   A change in the overlap format was introduced in GNU diff3 between
   versions 2.0 and 2.1 that causes RCS versions before 5.6.0.1 to fail
   during a merge.
   
   To get consistent rcsmerge behavior, you have four choices:
   
     Go back to using GNU diff 1.15 or 2.0 with RCS versions 5.5 or 5.6.
   If you want to use GNU diff 2.1 or later, you'll have to pick one of
   the other three choices in this list.
   
     Grab RCS version 5.6.0.1 from an FSF archive and set the DIFF3_A
   macro to '1' as it tells you to in the Makefile:
   
   #define DIFF3_A 1
   
     Patch the RCS 5.6 source. Change line 84 in "merger.c" from:
   
   DIFF3, "-am", "-L", label[0], "-L", label[1], to DIFF3, "-amE", "-L",
   label[0], "-L", "", "-L", label[1],
   
     Wait both for RCS version 5.7 to be released and for a new version
   of CVS that can deal with it.
   
   Last modified: _6/13/1997_
   
  Category: /Past__Future_/Contributors/
  
   " + Contributors"
   
    1. Who wrote CVS? 
    
   Brian Berliner <berliner@sun.com> converted a collection of scripts
   written by Dick Grune <dick@cs.vu.nl> into a C program, then added all
   sorts of features. He continues to maintain CVS.
   
   Jeff Polk <polk@bsdi.com> wrote much of the code added between
   revisions 1.2 and 1.3. Many others were involved at some level.
   
   david d zuhn <zoo@armadillo.com> fixed a number of bugs, added some of
   the new features, reworked the whole thing to be more portable, and
   provided much of the energy to push CVS 1.4 out the door.
   
   Jim Kingdon implemented CVS 1.5's remote repository access features,
   fixed many bugs, and managed the release of version 1.5.
   
   Take a look at the README and the ChangeLog files in the CVS sources
   for more contributors.
   
   Last modified: _6/13/1997_
   
    2. You didn't write all of this FAQ, did you? 
    
   In the original hunt for questions to answer (performed in Jan/Feb,
   1993), I polled hundreds of people and I rephrased all sorts of text
   found on the net. Between 2/93 and 10/93, I released about 20
   versions, with corrections and additions from the info-cvs mailing
   list and private correspondence.
   
   Between 10/93 and 10/94 I extracted frequently asked questions from
   the 1200 mail messages to the info-cvs mailing list, turned them into
   focused questions and tried to answer them.
   
   93/02/?? ~4000 lines 93/06/?? ~5000 lines 93/10/23 7839 lines 278K
   94/10/29 9856 lines 360K 95/05/09 9981 lines 365K
   
   Because there are so many posers of questions, I will list only those
   who contribute answers or help significantly with the content and
   structure of this document.
   
   If I used someone else's text verbatim, I mentioned it in the given
   answer. The people whose email postings have added to this document or
   who have added to my understanding are:
   
   Brian Berliner <berliner@sun.com>, CVS maintainer. Paul Eggert
   <eggert@twinsun.com>, RCS maintainer.
   
   Gray Watson <gray@antaire.com> Per Cederqvist <ceder@signum.se> Pete
   Clark <pclark@is.com>
   
   all of whom have sent me copies of their tutorials and local CVS
   documentation.
   
   Additional contributors, who have sent me ideas, text, corrections and
   support include (in alphabetical order):
   
   Per Abrahamsen <amanda@iesd.auc.dk> Donald Amby
   <amby@mixcom.mixcom.com> Mark D Baushke <mdb@cisco.com> Jim Blandy
   <jimb@cyclic.com> Tom Cunningham <tomc@bouwsma,sps.mot.com> Graydon
   Dodson <grdodson@lexmark.com> Joe Drumgoole
   <joed@splatter.demon.co.uk> Don Dwiggins <dwig@markv.com> Bryant
   Eastham <bryant@ced.utah.edu> Dan Franklin <dan@diamond.bbn.com>
   Michael Ganzberger <ganzbergermd@ES.net> Steve Harris
   <vsh%etnibsd@uunet.uu.net> Erik van Linstee
   <linstee@dutecaj.et.tudelft.nl> Jeffrey M Loomis <jml@world.std.com>
   Barry Margolin <barmar@near.net> Mark K. Mellis <mkm@ncd.com> Chris
   Moore <Chris.Moore@src.bae.co.uk> Gary Oberbrunner <garyo@avs.com>
   Steve Turner <stevet@carrier.sps.mot.com> Dave Wolfe
   <dwolfe@pffft.sps.mot.com> Dale Woolridge <dwoolridge@cid.aes.doe.ca>
   
   Please send corrections. If I forgot you, remind me and I'll add your
   name to the list.
   
   Last modified: _6/13/1997_
   
  Category: /Past__Future_/Development/
  
   " + Development"
   
    1. Where do I send bug reports? 
    
   First make sure it is a bug. Talk to your friends, coworkers and
   anyone you know who uses CVS. Search this FAQ for related issues. Then
   test it carefully. Try out variations to narrow down the problem. Make
   sure it is repeatable. Look for workarounds so you can report them.
   
   If you are still sure it's a bug and you tried to fix it, skip to the
   next question. Otherwise, send a message to the info-cvs mailing list
   containing one of the following:
   
     If you have a good repeatable case and you think you know what is
   going on, then describe the problem in detail. Include a workaround if
   you have one.
   
     If you have no idea what is going on, go ahead and send a question
   to the info-cvs mailing list. Include any information you have
   describing the symptoms.
   
   Last modified: _6/13/1997_
   
    2. Where do I send fixes and patches? 
    
   First make sure the "fix" does something useful. Have someone review
   your fix. Spend a bit of one person's time in a detailed analysis of
   your vast idea before displaying a half-vast idea to hundreds of
   people.
   
   If you tried to fix it and the patch is small, include the patch in
   your message. Make sure the patch is based on the latest released
   version of CVS.
   
   If you tried to fix it and the patch is large, you should think about
   why it is so large. Did you add a generally useful feature, or did it
   grow out of hand?
   
   If you still believe it is solid, produce a patch file using the CVS
   commands "patch" or "diff -c". [[You *are* keeping CVS under CVS,
   right?]] The patch should be based on the latest released version of
   CVS. Then use the "cvsbug" program (provided with the CVS sources) to
   send it to the CVS maintainers. A self-contained patch that provides a
   single useful feature or correction might show up independently in the
   patches directory of the FTP archive.
   
   If careful testing reveals an RCS bug rather than a CVS bug, you can
   send bug reports to: rcs-bugs@cs.purdue.edu
   
   Last modified: _6/13/1997_
   
    3. Where do I send ideas for future development? 
    
   If you have a bright idea, discuss it on the info-cvs mailing list. If
   you have the time to implement something you can test, send the diffs
   along too as described above.
   
   Last modified: _6/13/1997_
   
    4. What plans are there for new features? 
    


A "rename" or "per-directory" database has been bandied about on
the net for years.  Many of the goals of the rename database have
been achieved by the so-called "death support" in recent versions of
CVS (such as 1.9).  For more information on what may remain to be
done, see item #189 in the TODO file of a development version of CVS.

CVS version 1.5 supports remote repository access, but Paul
Kunz  has produced another version
(rCVS) that also runs remotely.  Note that as far as I know there
are no advantages to rCVS over the remote CVS in CVS 1.5 and later,
and the rCVS user community has migrated to remote CVS.
rCVS is *not* a multisite CVS (see item #186 in TODO for more on
multisite).  For more on rCVS, see

ftp://ftp.slac.stanford.edu/software/rcvs

kingdon@cyclic.com

   Last modified: _9/6/1997_
   
    5. I have some time and I'd like to help. What can I do for you? 
    

        You can review this document, correct errors and fill in any of
        the incomplete sections.

        You can write scripts or CVS add-ons and make them available by
        web/FTP/etc.

        You could work on the regression test suite (src/sanity.sh in the
        CVS source distribution).

        You can write specs for new features, fix bugs, review the
        documentation or . . .

        For more information, see the files HACKING and DEVEL-CVS in the
        CVS source distribution or
        http://www.cyclic.com/cyclic-pages/cvsdev.html

        kingdon@cyclic.com

   Last modified: _9/6/1997_
   
  Category: /Past__Future_/Professional_Support/
  
   " + Professional Support"
   
    1. Doesn't Cygnus support CVS? 
    



        Cygnus is a company that supports free software such as the GCC
        compiler.  They have never sold support for CVS, however.  They
        do use CVS internally and have contributed much code to CVS over
        the years (for which CVS users should be grateful).

        kingdon@cyclic.com

   Last modified: _9/6/1997_
   
    2. What is Cyclic Software doing with CVS? 
    

Cyclic Software exists to provide support for CVS.  For details such
as prices and what this covers, see http://www.cyclic.com or ask
info@cyclic.com.

kingdon@cyclic.com

   Last modified: _9/6/1997_
   
  Category: /User_Tasks_/
  
   " User Tasks "
   
  Category: /User_Tasks_/Common_User_Tasks/
  
   " + Common User Tasks"
   
    1. What is the absolute minimum I have to do to edit a file? 
    
   Tell your Repository Administrator to create a module covering the
   directory or files you care about. You will be told that your module
   name is <module>. Then type:
   
                cvs checkout <module>
                cd <module>
                emacs <file>          # Isn't Emacs a synonym for edit?
                cvs commit <file>

   If you don't use modules (in my opinion, a mistake), you can check out
   a directory by substituting its relative path within the Repository
   for <module> in the example above.
   
   To work on a single file, you'll have to change "cd <module>" to "cd
   `dirname <module>`".
   
   Last modified: _6/13/1997_
   
    2. If I edit multiple files, must I type "commit" for each one? 
    
   No. You can commit a list of files and directories, including relative
   paths into multiple directories. You can also commit every modified
   file in the current directory or in all directories and subdirectories
   from your current directory downward. See 3D.2.
   
   Last modified: _6/13/1997_
   
    3. How do I get rid of the <module> directory that "checkout" created? 
    
   Change your directory to be the same as when you executed the
   "checkout" command that created <module>.
   
   If you want to get rid of the CVS control information, but leave the
   files and directories, type:
   
                cvs release <module>

   If you want to obliterate the entire directory, type:
   
                cvs release -d <module>

   ("release -d" searches through the output of "cvs -n update" and
   refuses to continue if the "update" command finds any modified files
   or non-ignored foreign files. Foreign directories too.)
   
   If you don't care about keeping "history", or checking for modified
   and foreign files, you can just remove the whole directory. That's "rm
   -rf <module>" under Unix.
   
   Last modified: _6/13/1997_
   
    4. How do I find out what has changed since my last update? 
    
   There are many ways to answer this.
   
   To find out what you've changed in your current working directory
   since your last checkout, update or commit, type:
   
                cvs diff

   To find out what other people have added (to your branch) since you
   last checked out or updated, type:
   
                cvs diff -r BASE -r HEAD

   To look at a revision history containing the comments for all changes,
   you can use the "log" command.
   
   You can also use "history" to trace a wide variety of events.
   
   Last modified: _6/13/1997_
   
    5. I just created a new file. How do I add it to the Repository? 
    
   The "update" command will mark files CVS doesn't know about in your
   working directory with a '?' indicator.
   
                ? <file>

   To add <file> to the Repository, type:
   
                cvs add <file>
                cvs commit <file>

   See 3A.[2-5] and 4C.8 for branch and merge considerations.
   
   Last modified: _6/13/1997_
   
    6. How do I merge changes made by others into my working directory? 
    
   If you are asking about other branches, see Section 4C on "Branching".
   You will have to use the "update -j" command.
   
   Retrieving changes made to the Repository on the *same* branch you are
   working on is the main purpose of the "update" command. The "update"
   command tries to merge work committed to the Repository by others
   since you last executed "checkout", "update" or "commit" into your
   working files.
   
   For a single file, there are six possible results when you type the
   "update" command:
   
     If the file is lying in your working directory, but is not under
   CVS, it will do nothing but print:
   
   ? <file>
   
     If neither you nor anyone else has committed changes to <file>,
   since your last "checkout", "update" or "commit", "update" will print
   nothing and do nothing.
   
     If you have made no changes to a working file, but you or others
   have committed changes to the Repository since your last "checkout",
   "update" or "commit" of this working file, CVS will remove your
   working file and replace it with a copy of the latest revision of that
   file in the Repository. It will print:
   
   U <file>
   
   You might want to examine the changes (using the CVS "diff" command)
   to see if they mesh with your own in related files.
   
     If you have made changes to a working file, but no one has changed
   your BASE revision (the revision you retrieved from the Repository in
   your last "checkout", "update" or "commit"), "update" will print:
   
   M <file>
   
   Nothing changes. You were told that you have a modified file in your
   directory.
   
     If you have made changes to your working file and you or others have
   committed changes to the Repository, but in different sections of the
   file, CVS will merge the changes stored in the Repository since your
   last "checkout", "update" or "commit" into your working file. "update"
   will print:
   
   RCS file: /Repository/module/<file> retrieving revision 1.X retrieving
   revision 1.Y Merging differences between 1.X and 1.Y into <file> M
   <file>
   
   If you execute "diff" before and after this step, you should see the
   same output, since both the base file and your working file changed in
   parallel. This is one of the few times the otherwise nonsensical
   phrase "same difference" means something.
   
     If both you and those who committed files (since your last checkout,
   update or commit) have made changes to the same section of a file, CVS
   will merge the changes into your file as in #5 above, but it will
   leave conflict indicators in the file. "update" will print:
   
   RCS file: /Repository/module/<file> retrieving revision 1.X retrieving
   revision 1.Y Merging differences between 1.X and 1.Y into <file>
   rcsmerge warning: overlaps during merge
                cvs update: conflicts found in <file>
                C <file>

   This is a "conflict". The file will contain markers surrounding the
   overlapping text. The 'C' conflict indicator is sticky -- subsequent
   "update" commands will continue to show a 'C' until you edit the file.
   
   You must examine the overlaps with care and resolve the problem by
   analyzing how to retain the features of both changes. See 2D.7 and
   3P.6 for more details on conflict resolution.
   
   Last modified: _6/13/1997_
   
    7. How do I label a set of revisions so I can retrieve them later? 
    
   To "tag" the BASE revisions (the ones you last checked out, updated,
   or committed) you should "cd" to the head of the working directory you
   want to tag and type:
   
                cvs tag <tag>

   It recursively walks through your working directory tagging the BASE
   revisions of all files.
   
   To "tag" the latest revision on the Main branch in the Repository, you
   can use the following from anywhere: (No "cd" is required -- it works
   directly on the Repository.)
   
                cvs rtag <tag> <module>

   Last modified: _6/13/1997_
   
    8. How do I checkout an old release of a module, directory or file? 
    
   Module names and directories are simply ways to name sets of files.
   Once the names are determined, there are 6 ways to specify which
   revision of a particular file to check out:
   
     By tag or symbolic name, via the "-r <tag>" option.
   
     By date, via the "-D <date>" option.
   
     By branch tag (a type of tag with a magic format), via the "-r
   <branch_tag>" option.
   
     By date within a branch, via the "-r <branch_tag>:<date>" option.
   
     By an explicit branch revision number ("-r <rev>"), which refers to
   the latest revision on the branch. This isn't really an "old"
   revision, from the branch's perspective, but from the user's
   perspective the whole branch might have been abandoned in the past.
   
     An explicit revision number: "-r <rev>" Though this works, it is
   almost useless for more than one file.
   
   You type:
   
                cvs checkout <option-specified-above> <module>
                cd <module>

   Last modified: _6/13/1997_
   
    9. What do I have to remember to do periodically? 
    
   You should execute "cvs -n update" fairly often to keep track of what
   you and others have changed. It won't change anything -- it will just
   give you a report.
   
   Unless you are purposely delaying the inclusion of others' work, you
   should execute "update" once in a while and resolve the conflicts. It
   is not good to get too far out of sync with the rest of the developers
   working on your branch.
   
   It is assumed that your system administrators have arranged for editor
   backup and Unix temp files (#* and .#*) to be deleted after a few
   weeks. But you might want to look around for anything else that is
   ignored or hidden. Try "cvs -n update -I !" to see all the ignored
   files.
   
   If you are the Repository Administrator, see 4B.16 on Administrator
   responsibilities.
   
   Last modified: _6/13/1997_
   
  Category: /User_Tasks_/General_Questions/
  
   " + General Questions"
   
    1. How do I see what CVS is trying to do? 
    
   The '-t' option on the main "cvs" command will display every external
   command (mostly RCS commands and file deletions) it executes. When
   combined with the '-n' option, which prevents the execution of any
   command that might modify a file, you can see what it will do before
   you let it fly. The '-t' option will *not* display every internal
   action, only calls to external programs.
   
   To see a harmless example, try typing:
   
                cvs -nt update

   Some systems offer a "trace" or "truss" command that will display all
   system calls as they happen. This is a *very* low-level interface that
   does not normally follow the execution of external commands, but it
   can be useful.
   
   The most complete answer is to read the source, compile it with the
   '-g' option and step through it under a debugger.
   
   Last modified: _6/13/1997_
   
    2. If I work with multiple modules, should I check them all out and commit
    them occasionally? Is it OK to leave modules checked out? 
    
   The simple answers are "Yes."
   
   There is no reason to remove working directories, other than to save
   disk space. As long as you have committed the files you choose to make
   public, your working directory is just like any other directory.
   
   CVS doesn't care whether you leave modules checked out or not. The
   advantage of leaving them checked out is that you can quickly visit
   them to make and commit changes.
   
   Last modified: _6/13/1997_
   
    3. What is a "sticky" tag? What makes it sticky? How do I loosen it? 
    
   When you execute "update -r <tag>", CVS remembers the <tag>. It has
   become "sticky" in the sense that until you change it or remove it,
   the tag is remembered and used in references to the file as if you had
   typed "-r <tag>" on the command line.
   
   It is most useful for a <branch_tag>, which is a sticky tag indicating
   what branch you are working on.
   
   A revision number ("-r <rev-number>") or date ("-D <date>") can also
   become sticky when they are specified on the command line.
   
   A sticky tag, revision or date remains until you specify another tag,
   revision or date the same way. The "update -A" command moves back to
   the Main branch, which has the side-effect of clearing all sticky
   items on the updated files.
   
   The "checkout" command creates sticky tags, revisions and dates the
   same way "update" does.
   
   Also, the '-k' option records a "sticky" keyword option that is used
   in further "updates until "update -A" is specified.
   
   Last modified: _6/13/1997_
   
    4. How do I get an old revision without updating the "sticky tag"? 
    
   Use the '-p' option to "pipe" data to standard output. The command
   "update -p -r <tag/rev>" sends the selected revision to your standard
   output (usually the terminal, unless redirected). The '-p' affects no
   disk files, leaving a "sticky tag" unaltered and avoiding all other
   side-effects of a normal "update".
   
   If you want to save the result, you can redirect "stdout" to a file
   using your shell's redirection capability. In most shells the
   following command works:
   
            cvs update -p -r <tag/rev> filename > diskfile

   Last modified: _6/13/1997_
   
    5. What operations disregard sticky tags? 
    
   The functions that routinely disregard sticky tags are:
   
     Those that work directly on the Repository or its administrative
   files:
   
                admin   rtag    log     status  remove  history

     Those that take Tags or revisions as arguments and ignore everything
   else: (They also never *set* a sticky tag.)
   
                rdiff   import  export

     The "release" command itself ignores sticky tags, but it calls "cvs
   -n update" (which *does* pay attention to a sticky tag) to figure out
   what inconsistencies exist in the working directory. If no
   discrepancies exist between the files you originally checked out
   (possibly marked by a sticky tag) and what is there now, "release -d"
   will delete them all.
   
     The "tag" command works on the revision lying in the working
   directory however it got there. That the revision lying there might
   happen to have a sticky tag attached to it is not the "tag" command's
   concern.
   
   The main function that *does* read and write sticky tags is the
   "update" command. You can avoid referring to or changing the sticky
   tag by using the '-p' option, which sends files to your terminal,
   touching nothing else.
   
   The "checkout" command sets sticky tags when checking out a new module
   and it acts like "update" when checking out a module into an existing
   directory.
   
   The "diff" and "commit" commands use the sticky tags, unless
   overridden on the command line. They do not set sticky tags. Note that
   you can only "commit" to a file checked out with a sticky tag, if the
   tag identifies a branch.
   
   There are really two types of sticky tags, one attached to individual
   files (in the ./CVS/Entries file) and one attached to each directory
   (in the ./CVS/Tag file). They can differ.
   
   The "add" command registers the desire to add a new file. If the
   "directory tag" (./CVS/Tag) file exists at the time of the "add", the
   value stored in ./CVS/Tag becomes the "sticky tag" on the new file.
   The file doesn't exist in the Repository until you "commit" it, but
   the ./CVS/Entries file holds the sticky tag name from the time of the
   "add" forward.
   
   Last modified: _6/13/1997_
   
    6. Is there a way to avoid reverting my Emacs buffer after committing a
    file? Is there a "cvs-mode" for Emacs? 
    
   See Section 4F.1
   
   Last modified: _6/13/1997_
   
    7. How does conflict resolution work? What *really* happens if two of us
    change the same file? 
    
   While editing files, there is no conflict. You are working on separate
   copies of the file stored in the virtual "branch" represented by your
   working directories. After one of you commits a file, the other may
   not commit the same file until "update" has merged the earlier
   committed changes into the later working file.
   
   For example, say you both check out rev 1.2 of <file> and make change
   to your working files. Your coworker commits revision 1.3. When you
   try to commit your file, CVS says:
   
                cvs commit: Up-to-date check failed for `<file>'

   You must merge your coworker's changes into your working file by
   typing:
   
                cvs update <file>

   which will produce the output described in 2B.6.
   
   If a conflict occurs, the filename will be shown with a status of 'C'.
   After you resolve any overlaps caused by the merging process, you may
   then commit the file. See 3P.6 for info on "sticky conflicts".
   
   Even if you get a simple 'M', you should examine the differences
   before committing the file. A smooth, error-free text merge is still
   no indication that the file is in proper shape. Compile and test it at
   least.
   
   The answer to two obvious questions is "Yes".
   
   Yes, the first one who commits avoids the merge. Later developers have
   to merge the earlier changes into their working files before
   committing the merged result. Depending on how difficult the merge is
   and how important the contending projects are, the order of commits
   and updates might have to be carefully staged.
   
   And yes, between the time you execute "update" and "commit" (while you
   are fixing conflicts and testing the results) someone else may commit
   another revision of <file>. You will have to execute "update" again to
   merge the new work before committing. Most organizations don't have
   this problem. If you do, you might consider splitting the file. Or
   hiring a manager.
   
   Last modified: _6/13/1997_
   
    8. How can I tell who has a module checked out? 
    
   If you "checkout" module names (not relative pathnames) and you use
   the release command, the "history" command will display active
   checkouts, who has them and where they were checked out. It is
   advisory only; it can be circumvented by using the '-l' option on the
   main "cvs" command.
   
   Last modified: _6/13/1997_
   
    9. Where did the .#<file>.1.3 file in my working directory come from? 
    
   It was created during an "update" when CVS merged changes from the
   Repository into your modified working file.
   
   It serves the same purpose as any "backup" file: saving your bacon
   often enough to be worth retaining. It is invaluable in recovering
   when things go wrong.
   
   Say Developers A (you) and B check out rev 1.3 of file <file>. You
   both make changes -- different changes. B commits first, so <file>,v
   in the Repository contains revisions up through 1.4.
   
   At this point, there are 5 (yes, five) versions of the file of
   interest to you:
   
     Revision 1.3 (What you originally checked out.)
   
     Revision 1.4 (What you need from developer B.)
   
     Your old working file. (Before the update.)
   
     Your new working file. (After the merge caused by "update".)
   
     Revision 1.5 (Which you will commit shortly.)
   
   In the case where your working file was not modified, #1 and #3 will
   be the same, as will #2 and #4. In this degenerate case, there is no
   need to create #5. The following assumes that your working file was
   modified.
   
   If the merge executed by the "update" caused no overlaps, and you
   commit the file immediately, #4 and #5 will be the same. But you can
   make arbitrary changes before committing, so the difference between #4
   and #5 might be more than just the correction of overlaps. In general,
   though, you don't need #4 after a commit.
   
   But #3 (which is the one saved as ".#<file>.1.3") holds all of your
   work, independent of B's work. It could represent a major effort that
   you couldn't afford to lose. If you don't save it somewhere, the merge
   makes #3 *disappear* under a potential blizzard of conflicts caused by
   overlapping changes.
   
   I have been saved a few times, and others I support have been saved
   hundreds of times, by the ability to "diff <original file> <original
   file with only my work added>", which can be done in the example above
   by the Unix shell command:
   
                cvs update -p -r 1.3 <file> | diff - .#<file>.1.3

   The assumption is that the ".#" files will be useful far beyond the
   "commit" point, but not forever. You are expected to run the "normal"
   Unix cleanup script from "cron", which removes "#*" and ".#*" files
   older than a some period chosen by your sysadmin, usually ranging from
   7 to 30 days.
   
   A question was raised about the need for #3 after #5 has been
   committed, under the assumption that you won't commit files until
   everything is exactly as you like them.
   
   This assumes perfect humans, which violates one of the Cardinal rules
   of Software Engineering: Never assume any form of discipline on the
   part of the users of software. If restrictions are not bound into the
   software, then you, the toolsmith, have to arrange a recovery path.
   
   In other words, I've seen every possible variety of screwup you can
   imagine in #5. There is no way to make assumptions about what "should"
   happen. I've seen #5 filled with zeros because of NFS failures, I've
   seen emacs core dumps that leave #5 in an unreasonable state, I've
   seen a foolish developer uppercase the whole file (with his "undo"
   size set low so he couldn't undo it) and decide that it would be less
   work to play with the uppercased file than to blow it away and start
   over. I've even seen committed files with conflict markers still in
   them, a sure sign of carelessness.
   
   There are all sorts of scenarios where having #3 is incredibly useful.
   You can move it back into place and try again.
   
   Last modified: _6/13/1997_
   
    10. What is this "ignore" business? What is it ignoring? 
    
   The "update" and "import" commands use collections of Unix wildcards
   to skip over files and directories matching any of those patterns.
   
   You may add to the built-in ignore list by adding lines of
   whitespace-separated wildcards to the following places: (They are read
   in this order.)
   
     In a file named "cvsignore" in $CVSROOT/CVSROOT.
   
   A Repository Administrator uses this to add site-specific files and
   patterns to the built-in ignore list.
   
     In a file named ".cvsignore" in your home directory.
   
   For user-specific files. For example, if you use "__" as your default
   junk file prefix, you can put "__*" in your .cvsignore file.
   
   People who play around exclusively in directory trees where the
   Makefiles are generated by "imake" or "configure" might want to put
   "Makefile" in their ignore list, since they are all generated and
   usually don't end up in the Repository.
   
     In the CVSIGNORE environment variable.
   
   For session-specific files.
   
     Via the '-I' option on "import" or "update" commands.
   
   For this-command-only files.
   
     In a file named ".cvsignore" within each directory.
   
   The contents of a ".cvsignore" file in each directory is temporarily
   added to the ignore list. This way you can ignore files that are
   peculiar to that directory, such as executables and other generated
   files without known wildcard patterns.
   
   In any of the places listed above, a single '!' character nulls out
   the ignore list. A Repository administrator can use this to override,
   rather than enhance, the built-in ignore list. A user can choose to
   override the system-wide ignore list. For example, if you place "! *.o
   *.a" in your .cvsignore file, only *.o *.a files, plus any files a
   local-directory .cvsignore file, are ignored.
   
   A variant of the ignore-file scheme is used internally during
   checkout. "Module names" found in the modules file (or on the
   "checkout" command line) that begin with a '!' are ignored during
   checkout. This is useful to permanently ignore (if the '!' path is in
   the modules file) or temporarily ignore (if the '!' path is on the
   command line) a sub-directory within a Repository hierarchy. For
   example:
   
   cvs checkout !gnu/emacs/tests gnu/emacs
   
   would checkout the module (or relative path within $CVSROOT) named
   "gnu/emacs", but ignore the "tests" directory within it.
   
   Last modified: _6/13/1997_
   
    11. Is there a way to set user-specific configuration options? 
    
   User-specific configuration is available through use of a ".cvsrc"
   file in your home directory.
   
   CVS searches the first column of your ~/.cvsrc file for the cvs
   command name you invoked. If the command is found, the rest of the
   line is treated like a set of command line options, stuffed into the
   command line before the arguments you actually typed.
   
   For example, if you always want to see context diffs and you never
   want to have to delete a file before you run "cvs remove", then you
   should create a .cvsrc file containing the following:
   
                diff -c
                remove -f

   which will add the given options to every invocation of the given
   commands.
   
   [[The rest of this will be removed someday, when CVS changes.]]
   
   I would like to stop here with a comment that the command name to use
   is the full, canonical one. But the command that the cvsrc support
   uses is the string you typed on the command line, not the proper
   command. So to get the full effect of the above example, you should
   also add all the alternate command names:
   
                di -c
                dif -c
                rm -f
                delete -f

   There are two other limitations that will probably be fixed when CVS
   sprouts long option names:
   
     It only affects options made available on the command line.
   
   There is a limited number of short options. With long option names,
   there is no problem. You can have as many long options as you like,
   affecting anything that looks malleable.
   
     The existing command line options do not come in on/off pairs, so
   there is no easy way to override your ~/.cvsrc configuration for a
   single invocation of a command.
   
   Choosing a good set of long option pairs would fix this.
   
   Last modified: _6/13/1997_
   
    12. Is it safe to interrupt CVS using Control-C? 
    
   It depends on what you mean by "safe". ("Ah," said Arthur, "this is
   obviously some strange usage of the word *safe* that I wasn't
   previously aware of." -- Hitchhiker's Guide to the Galaxy)
   
   You won't hurt the underlying RCS files and if you are executing a
   command that only *reads* data, you will have no cleanup to do.
   
   But you may have to hit Control-C repeatedly to stop it. CVS uses the
   Unix "system" routine which blocks signals in the CVS parent process.
   A single Control-C during "system" will only halt the child process,
   usually some form of RCS command.
   
   If you don't hit another Control-C while the CVS process has control,
   it is likely to continue onto the next task assuming that the earlier
   one did its job. It is not enough to hit two Control-C's. You might
   simply kill two child processes and not interrupt CVS at all.
   Depending on the speed of your processor, your terminal and your
   fingers, you might have to hit dozens of Control-C's to stop the damn
   thing.
   
   Executing a CVS command, such as "commit" or "tag" that writes to the
   files is a different matter.
   
   Since CVS is not a full-fledged database, with what database people
   call "commit points", merely stopping the process will not back out
   the "transaction" and place you back in the starting blocks. CVS has
   no concept of an "atomic" transaction or of "backtracking", which
   means that a command can be half-executed.
   
   Hitting Control-C will usually leave lock files that you have to go
   clean up in the Repository.
   
   Example1:
   
                If you interrupt a multi-file "commit" in the middle of
                an RCS checkin, RCS will leave the file either fully
                checked-in or in its original state.  But CVS might have
                been half-way through the list of files to commit.  The
                directory or module will be inconsistent.

                To recover, you must remove the lock files, then decide
                whether you want to back out or finish the job.

                To back out, you'll have to apply the "admin -o"
                command, very carefully, to remove the newly committed
                revisions.  This is usually a bad idea, but is
                occasionally necessary.

                To finish, you can simply retype the same commit command.
                CVS will figure out what files are still modified and
                commit them.  It helps that RCS doesn't leave a file in an
                intermediate state.

   Example2:
   
                If you interrupt a multi-file "tag" command, you have a
                problem similar, but not equivalent, to interrupting a
                "commit".  The RCS file will still be consistent, but
                unlike "commit", which only *adds* to the RCS file, "tag"
                can *move* a tag and it doesn't keep a history of what
                revision a tag used to be attached to.

                Normally, you have little choice but to re-execute the
                command and allow it to tag everything consistently.

                You might be able to recover by carefully re-applying the
                tags via the "cvs admin -N" command, but you'll still have
                to dig up from outside sources the information you use to
                determine what tag was on what revision in what file.
                the Repository, or by using the equivalent: "cvs admin".

   Halting a new "checkout" should cause no harm. If you don't want it,
   "release" (or rm -rf) it. If you do want it, re-execute the command. A
   repeated "checkout" from above a directory acts like a repeated
   "update -d" within it.
   
   Halting "update" half-way will give you an unpredictable collection of
   files and revisions. To continue, you can rerun the update and it
   should move you forward into in a known state. To back out, you'll
   have to examine the output from the first "update" command, take a
   look at each file that was modified and reconstruct the previous state
   by editing the ./CVS/Entries file and by using "cvs admin". Good Luck.
   
   Last modified: _6/13/1997_
   
    13. How do I turn off the "admin" command? 
    
   In the current revision, you'd have to edit the source code.
   
   Last modified: _6/13/1997_
   
    14. How do I turn off the ability to disable history via "cvs -l"? 
    
   In the current revision, you'd have to edit the source code.
   
   Last modified: _6/13/1997_
   
    15. How do I keep certain people from accessing certain directories? 
    
   If you don't try to run CVS set[ug]id, you can use Unix groups and
   permissions to limit access to the Repository.
   
   If you only want to limit "commit" commands, you can write a program
   to put in the "commitinfo" file. In the "contrib" directory, there are
   a few scripts that might help you out.
   
   Last modified: _6/13/1997_
   
  Category: /User_Tasks_/Getting_Started/
  
   " + Getting Started"
   
    1. What is the first thing I have to know? 
    
   Your organization has most likely assigned one or more persons to
   understand, baby-sit and administer the CVS programs and the data
   Repository. I call these persons Repository Administrators. They
   should have set up a Repository and "imported" files into it.
   
   If you don't believe anyone has this responsibility, or you are just
   testing CVS, then *you* are the Repository Administrator.
   
   If you are a normal user of CVS ask your Repository Administrator what
   module you should check out.
   
   Then you can work.
   
   If you *are* the Repository Administrator, you will want to read
   everything you can get your hands on, including this FAQ. Source
   control issues can be difficult, especially when you get to branches
   and release planning. Expect to feel stupid for a few days/weeks.
   
   No tool in the universe avoids the need for intelligent organization.
   In other words, there are all sorts of related issues you will
   probably have to learn. Don't expect to dive in without any
   preparation, stuff your 300 Megabytes of sources into CVS and expect
   to start working. If you don't prepare first, you will probably spend
   a few sleepless nights.
   
   Last modified: _6/13/1997_
   
    2. Where do I work? 
    
   Wherever you have disk space. That's one of the advantages of CVS: you
   use the "checkout" command to copy files from the Repository to your
   working directory, which can be anywhere you have the space.
   
   Your local group might have conventions for where to work. Ask your
   peers.
   
   Last modified: _6/13/1997_
   
    3. What does CVS use from my environment? 
    
   You must set two environment variables. Some shells share these
   variables with local shell variables using a different syntax. You'll
   have to learn how your shell handles them.
   
        Variable        Value (or action)
        ---------       ---------------------
        CVSROOT         Absolute pathname of the head of your Repository.

        PATH            Normally set to a list of ':'-separated directory
                        pathnames searched to find executables.  You must
                        make sure "cvs" is in one of the directories.

                        If your CVS was built with the RCSBIN directory set
                        to null (""), and you don't set the RCSBIN
                        variable mentioned below, then the RCS commands
                        also must be somewhere in your PATH.

   Optional variables: (Used if set, but ignored otherwise.)
   
        Variable        Value (or action)
        ---------       ---------------------
        CVSEDITOR       The name of your favorite fast-start editor
                        program.  You'll be kicked into your editor to
                        supply revision comments if you don't specify them
                        via -m "Log message" on the command line.

        EDITOR          Used if CVSEDITOR doesn't exist.  If EDITOR
                        doesn't exist, CVS uses a configured constant,
                        usually, "vi".

        CVSREAD         Sets files to read-only on "checkout".

        RCSBIN          Changes where CVS finds the RCS commands.

        CVSIGNORE       Adds to the ignore list.  See Section 2D.

   Other variables used by CVS that are normally set upon login:
   
        Variable        Value (or action)
        ---------       ---------------------
        LOGNAME         Used to find the real user name.

        USER            Used to find the real user name if no LOGNAME.

        HOME            Used to determine your home directory, if set.
                        Otherwise LOGNAME/USER/getuid() are used to find
                        your home directory from the passwd file.

        TMPDIR          Used during import.  It might also be used if your
                        platform's version of mktemp(3) is unusual, or
                        you have changed the source to use tmpnam(3).

   Last modified: _6/13/1997_
   
    4. OK, I've been told that CVS is set up, my module is named "ralph" and I
    have to start editing. What do I type? 
    
                cd <where you have some space to work>
                cvs checkout ralph
                cd ralph

   And hack away.
   
   Last modified: _6/13/1997_
   
    5. I have been using RCS for a while. Can I convert to CVS without losing
    my revision history? How about converting from SCCS? 
    
   If you are asking such questions, you are not a mere user of CVS, but
   one of its Administrators! You should take a look at Section 4A,
   "Installing CVS" and Section 4B, "Setting up and Managing the
   Repository".
   
   Last modified: _6/13/1997_
   
  Category: /User_Tasks_/Less_Common_User_Tas/
  
   " + Less Common User Tasks"
   
    1. Can I create non-CVS sub-directories in my working directory? 
    
   Yes. Unless the directory exists in the Repository, "update" will skip
   over them and print a '?' the way it does for files you forgot to add.
   You can avoid seeing the '?' by adding the name of the foreign
   directory to the ./.cvsignore file, just ask you can do with files.
   
   If you explicitly mention a foreign directory on the "update" command
   line, it will traverse the directory and waste a bit of time, but if
   any directory or sub-directory lacks the ./CVS administrative
   directory, CVS will print an error and abort.
   
   Last modified: _6/13/1997_
   
    2. How do I add new sub-directories to the Repository? 
    
   The "add" command will work on directories. You type:
   
   mkdir <dir>
            cvs add <dir>

   It will respond:
   
   Directory /Repos/<dir> added to the repository
   
   and will create both a matching directory in the Repository and a
   ./CVS administrative directory within the local <dir> directory.
   
   Last modified: _6/13/1997_
   
    3. How do I remove a file I don't need? 
    
   (See the questions in Section 4B on removing files from the
   Repository.)
   
   You type:
   
                rm <file>
                cvs remove <file>

   CVS registers the file for removal. To complete the removal, you must
   type:
   
                cvs commit <file>

   CVS moves the file to the Attic associated with your working
   directory. Each directory in the Repository stores its deleted files
   in an Attic sub-directory. A normal "checkout" doesn't look in the
   Attic, but if you specify a tag, a date or a revision, the "checkout"
   (or "update") command will retrieve files from the Attic with that
   tag, date or revision.
   
   Last modified: _6/13/1997_
   
    4. How do I rename a file? 
    
   CVS does not offer a way to rename a file in a way that CVS can track
   later. See Section 4B for more information.
   
   Here is the best (to some, the only acceptable) way to get the effect
   of renaming, while preserving the change log:
   
     Copy the RCS (",v") file directly in the Repository.
   
   cp $CVSROOT/<odir>/<ofile>,v $CVSROOT/<ndir>/<nfile>,v
   
   By duplicating the file, you will preserve the change history and the
   ability to retrieve earlier revisions of the old file via the "-r
   <tag/rev>" or "-D <date>" options to "checkout" and "update".
   
     Remove the old file using CVS.
   
   cd <working-dir>/<odir> rm <ofile>
                cvs remove <ofile>
                cvs commit <ofile>

   This will move the <ofile> to the Attic associated with <odir>.
   
     Retrieve <nfile> and remove all the Tags from it.
   
   By stripping off all the old Tags, "checkout -r" and "update -r" won't
   retrieve revisions Tagged before the renaming.
   
   cd <working-dir>/<ndir>
                cvs update <nfile>
                cvs log <nfile>                 # Save the list of Tags
                cvs tag -d <tag1> <nfile>
                cvs tag -d <tag2> <nfile>
                . . .

   This technique can be used to rename files within one directory or
   across different directories. You can apply this idea to directories
   too, as long as you apply the above to each file and don't delete the
   old directory.
   
   Of course, you have to change your build system (e.g. Makefile) in
   your <working-dir> to know about the name change.
   
   Warning: Stripping the old tags from the copied file will allow "-r
   <tag>" to do the right thing, but you will still have problems with
   "-D <date>" because there is no place to store the "deletion time".
   See 5B.3 for more details.
   
   Last modified: _6/13/1997_
   
    5. How do I make sure that all the files and directories in my working
    directory are really in the Repository? 
    
   A "cvs update", or "cvs -n update" (which won't modify your working
   directory) will display foreign elements, which have no counterpart in
   the Repository, preceded by a '?'. To register foreign directories,
   you can use "cvs add". To register foreign files, you can use "cvs
   add" followed by "cvs commit".
   
   You could also checkout your module, or the Repository directory
   associated with your working directory, a second time into another
   work area and compare it to your working directory using the (non-CVS)
   "diff -r" command.
   
   By default many patterns of files are ignored. If you create a file
   named "core" or a file ending in ".o", it is usually ignored. If you
   really want to see all the files that aren't in the Repository, you
   can use a special "ignore" pattern to say "ignore no files". Try
   executing: (You may have to quote or backwhack (i.e. precede by '\')
   the '!' in your shell.)
   
                cvs -n update -I !

   The above command will display not only the normal modified, update
   and conflict indicators ('M', 'U', and 'C' respectively) on files
   within the Repository, but it will also display each file not in the
   Repository preceded by a '?' character.
   
   The '-n' option will not allow "update" to alter your working
   directory.
   
   Last modified: _6/13/1997_
   
    6. How do I create a branch? 
    
   Type this in your working directory:
   
                cvs tag -b <branch_tag>

   and you will create a branch. No files have real branches in them yet,
   but if you move onto the branch by typing:
   
                cvs update -r <branch_tag>

   and commit a file in the normal way:
   
                cvs commit <file>

   then a branch will be created in the underlying <file>,v file and the
   new revision of <file> will appear only on that branch.
   
   See Section 4C, on Branching.
   
   Last modified: _6/13/1997_
   
    7. How do I modify the modules file? How about the other files in the
    CVSROOT administrative area? 
    
   A module named "modules" has been provided in the default modules
   file, so you can type:
   
                cvs checkout modules
                cd modules

   Another module named CVSROOT has been provided in the default modules
   file, covering all the administrative files. Type:
   
                cvs checkout CVSROOT
                cd CVSROOT

   Then you can edit your files, followed by:
   
                cvs commit

   If you start with the provided template for the "modules" file, the
   CVSROOT and the "modules" module will have the "mkmodules" program as
   a "commit helper". After a file is committed to such a module,
   "mkmodules" will convert a number of standard files (See 4B.2) in the
   CVSROOT directory inside the Repository into a form that is usable by
   CVS.
   
   Last modified: _6/13/1997_
   
    8. How do I split a file into pieces, retaining revision histories? 
    
   If you and a coworker find yourselves repeatedly committing the same
   file, but never for changes in the same area of the file, you might
   want to split the file into two or more pieces. If you are both
   changing the same section of code, splitting the file is of no use.
   You should talk to each other instead.
   
   If you decide to split the file, here's a suggestion. In many ways, it
   is similar to multiple "renamings" as described in 2C.4 above.
   
   Say you want to split , which already in the Repository, into three
   pieces, , and .
   
     Copy the RCS (",v") files directly in the Repository, creating the
   new files, then bring readable copies of the new files into the
   working directory via "update".
   
   cp $CVSROOT//,v $CVSROOT//,v cp $CVSROOT//,v $CVSROOT//,v
                cvs update

     Then remove all the from the new files, either using:
   
                cvs log               # Save the list of
                cvs tag -d
                cvs tag -d
                . . .

   (eivind@freebsd.org) or using the following little script to
   autmatically remove the tags directly from the repository files:

#!/bin/sh
for file in $*
do
        TAGS=`rlog $file | awk '/^symbolic names:/,/^keyword subst/' | awk 'BEG
IN {FS=":"} /^\t/ {print $1}'`
        echo The tags in $file are
        echo $TAGS
        echo Is it OK to remove these?
        read confirm
        if [ "$confirm" = "y" -o "$confirm" = "yes" ]
        then
                for tag in $TAGS
                do
                        echo Removing $file:$tag
                        rcs -n$tag $file
                done
        fi
done

     Edit each file until it has the data you want in it. This is a
   hand-editing job, not something CVS can handle. Then commit all the
   files.
   
   [From experience, I'd suggest making sure that only one copy of each
   line of code exists among the three files, except for "include"
   statements, which must be duplicated. And make sure the code
   compiles.]
   
   emacs
                cvs commit

   As in the "rename" case, by duplicating the files, you'll preserve the
   change history and the ability to retrieve earlier revisions.
   
   Of course, you have to alter your build system (e.g. Makefiles) to
   take the new names and the change in contents into account.
   
   Last modified: _3/11/1998_
   
  Category: /What_is_CVS_/
  
   " What is CVS? "
   
  Category: /What_is_CVS_/How_does_CVS_differ_/
  
   " + How does CVS differ from other, similar software?"
   
    1. How does CVS differ from RCS? 
    
   CVS uses RCS to do much of its work and absolutely all the work of
   changing the underlying RCS files in the Repository.
   
   RCS comprises a set of programs designed to keep track of changes to
   individual files. Of course, it also allows you to refer to multiple
   files on the command line, but they are handled by iterating over
   individual files. There is no pretense of coordinated interaction
   among groups of files.
   
   CVS's main intent is to provide a set of grouping functions that allow
   you to treat a collection of RCS files as a single object. Of course,
   CVS also has to do a lot of iteration, but it tries its best to hide
   that it is doing so. In addition, CVS has some truly group-oriented
   facets, such as the modules file and the CVS administrative files that
   refer to a whole directory or module.
   
   One group aspect that can be a bit confusing is that a CVS branch is
   not the same as an RCS branch. To support a CVS branch, CVS uses
   "tags" (what RCS calls "symbols") and some local state, in addition to
   RCS branches.
   
   Other features offered by CVS that are not supported directly by RCS
   are
   
     Automatic determination of the state of a file, (e.g. modified,
   up-to-date with the Repository, already tagged with the same string,
   etc.) which helps in limiting the amount of displayed text you have to
   wade through to figure out what changed and what to do next.
   
     A copy-modify-merge scheme that avoids locking the files and allows
   simultaneous development on a single file.
   
     Serialization of commits. CVS requires you to merge all changes
   committed (via "update") since you checked out your working copy of
   the file. Although it is still possible to commit a file filled with
   old data, it is less likely than when using raw RCS.
   
     Relatively easy merging of releases from external Vendors.
   
   Last modified: _6/13/1997_
   
    2. How does CVS differ from SCCS? 
    
   SCCS is much closer to RCS than to CVS, so some of the previous entry
   applies.
   
   You might want to take a look at Walter Tichy's papers on RCS, which
   are referred to in the RCS man pages.
   
   [[More info here?]]
   
   Last modified: _6/13/1997_
   
    3. How does CVS differ from ClearCase? 
    
   ClearCase is a distributed client-server version control system.
   ClearCase is a variant DSEE tools, formerly available on Apollo
   platforms. The ClearCase tool set includes a few X-based interface
   tools, a command-line interface, and C programmer API. It is currently
   available on Sun, HP, SGI and OSF/1 platforms.
   
   ClearCase uses a special Unix filesystem type, called "mvfs" for
   "multi-version file system". Conceptually, mvfs adds another dimension
   to a regular Unix filesystem. The new axis is used to store the
   different versions of files and to provide a tree-hierarchical view of
   a collection of objects that might be scattered across any number of
   separate hosts on your local network.
   
   Each user acquires a "view" into the file database by creating a
   special mvfs mount point on their machine. Each view has a
   "configuration spec" containing a set of selection rules that specify
   the particular version of each file to make visible in that view. You
   can think of a "view" as a work area in CVS, except that the files
   don't really exist on your local disk until you modify them. This
   technique conserves disk space because it doesn't keep private copies
   of read-only files.
   
   Another advantage is that a view is "transparent" in the sense that
   all of the files in a "view" appear to be regular Unix files to other
   tools and Unix system calls. An extended naming convention allows
   access to particular versions of a file directly:
   "test.cc@@/main/bugfix/3" identifies the third version of test.c on
   the bugfix branch.
   
   ClearCase supports both the copy-modify-merge model of CVS (by using
   what are called "unreserved checkouts" and the checkin/checkout
   development model with file locking. Directories are
   version-controlled objects as well as files. A graphical merge tool is
   provided. Like RCS, ClearCase supports branches, symbolic tags, and
   delta compression. ASCII as well as binary files are supported, and
   converters from RCS, SCCS, DSEE formats are also included.
   
   A make-compatible build facility is provided that can identify common
   object code and share it among developers. A build auditing feature
   automatically records file dependencies by tracking every file that is
   opened when producing a derived object, thus making explicit
   dependency lists unnecessary. Pre- and post-event triggers are
   available for most ClearCase operations to invoke user programs or
   shell scripts. User-defined attributes can be assigned to any version
   or object. Hyper-links between version controlled objects can record
   their relationship.
   
   For more information, contact:
   
   Atria Software, Inc. 24 Prime Park Way Natick, MA 01760 info@atria.com
   
   (508) 650-1193 (phone) (508) 650-1196 (fax)
   
                                Originally contributed by Steve Turner
                                Edited by the author of this FAQ.

   Last modified: _6/13/1997_
   
    4. How does CVS differ from TeamWare/SparcWorks? 
    
   TeamWare is a configuration management tool from Sun Microsystems, a
   part of SparcWorks. It uses the same copy and merge model as CVS. The
   central abstraction is a workspace, which corresponds to either a CVS
   branch or a checked out module. TeamWare allows you to manipulate
   workspaces directly, including moving and merging code between
   workspaces. You can put your workspace on tape and continue to work
   with it at home, just like you can with CVS. TeamWare is built upon
   and compatible with SCCS.
   
   TeamWare provides both a command line interface and a graphical
   interface. The CodeManager tool will display the project as a tree of
   workspaces, and allows you to manipulate them with drag and drop. The
   other tools are VersionTool that displays and manipulates a dag with a
   version history of a single file, CheckPoint that will create symbolic
   tags, MakeTool, a make compatible tool with a GUI, and FileMerge which
   will interactively merge files when needed (like emerge for emacs). If
   you have a sun, you can try /usr/old/mergetool for an old SunView
   version of FileMerge.
   
   Email: sunprosig@sun.com
   
                                Originally extracted from TeamWare
                                Marketing literature by Per Abrahamsen.
                                Edited by the author of this FAQ.

   For more information, contact:
   
   SunExpress, Inc. P.O. Box 4426 Bridgeton, MO 63044-9863 (800)873-7869
   
   Last modified: _6/13/1997_
   
    5. How does CVS differ from Aegis? 
    
   Aegis appears to be a policy-setting tool that allows you to use other
   sub-programs (make, RCS, etc.) to implement pieces of the imposed
   policy.
   
   The initial document seems to say that most Unix tools are inadequate
   for use under Aegis.
   
   It is not really similar to CVS and requires a different mindset.
   
   [[Need more info here.]]
   
   Last modified: _6/13/1997_
   
    6. How does CVS differ from Shapetools? 
    
   Shapetools includes a build mechanism (called Shape, not surprisingly)
   that is aware of the version mechanism, and some dependency tracking.
   It is based on a file system extension called Attributed File System,
   which allows arbitrary-sized "attributes" to be associated with a
   file. Files are version controlled in a manner similar to RCS.
   Configurations are managed through the Shapefile, an extension of the
   Makefile syntax and functionality. Shape includes version selection
   rules to allow sophisticated selection of component versions in a
   build.
   
   Shapetools' concurrency control is pessimistic, in contrast to that of
   CVS. Also, there's very limited support for branching and merging. It
   has a built-in policy for transitioning a system from initial
   development to production.
   
                                Contributed by Don Dwiggins

   Last modified: _6/13/1997_
   
    7. How does CVS differ from TeamNet? 
    
   TeamNet is a configuration management tool from TeamOne.
   
   For more information, contact:
   
   TeamOne 710 Lakeway Drive, Ste 100 Sunnyvale, CA 94086 (800) 442-6650
   
                                Contributed by Steve Turner

   Last modified: _6/13/1997_
   
    8. How does CVS differ from ProFrame? 
    
   ProFrame is a new system integration framework from IBM. ProFrame is
   compliant with the CFI (CAD Framework Initiative) industry standards,
   including the Scheme extension language.
   
   ProFrame consists of three major components: (1) the Process Manager
   that automates your local design methodology (2) the Design Data
   Manager handles configuration management, and (3) Inter-tool
   Communication to provide a communication path among tools running on
   heterogeneous servers.
   
   The Design Data Manager(2) is probably the appropriate component to
   compare to CVS. The Design Data Manager provides version control with
   checkin/checkout capability, configuration management, and data
   dependency tracking. A graphical data selection interface is provided.
   Using this interface, you may create and manipulate objects and
   hierarchy structures, view the revision history for an object, and
   view and assign attributes to a design object.
   
   The ProFrame server currently runs only on RS6000, but clients may be
   a wide variety of Unix platforms. Contact IBM for the latest platform
   information.
   
   For more information, contact:
   
   IBM EDA Marketing and Sales P.O. Box 950, M/S P121 Poughkeepsie, NY
   12602 (800) 332-0066
   
                                Contributed by Steve Turner
                        [extracted from the ProFrame 1.1.0 datasheet]

   Last modified: _6/13/1997_
   
    9. How does CVS differ from CaseWare/CM? 
    
   CaseWare/CM is a software configuration management product from
   CaseWare, Inc. CaseWare/CM may be customized to support a wide variety
   of methodologies, including various phases of the software lifecycle,
   and different access rights for users.
   
   A GUI is provided to view version histories and configurations. A
   merge tools is also included. CaseWare supports type-specific
   lifecycles, which allows different types of files to move through
   different lifecycles. Also provided is a build facility to support
   automatic dependency analysis, parallel, distributed, and remote
   builds, and variant releases.
   
   CaseWare/CM has been integrated with other CASE tools, including
   FrameMaker, ALSYS Ada, CodeCenter/Object Center, HP SoftBench, and
   Software Through Pictures. CaseWare also offers CaseWare/PT, a problem
   tracking system to integrate change requests with configuration
   management.
   
   Multiple vendors and operating systems are supported.
   
   For more information, contact:
   
   CaseWare, Inc. 108 Pacifica, 2nd Floor Irvine, CA 92718-3332 (714)
   453-2200 (phone) (714) 453-2276 (fax)
   
                                Contributed by Steve Turner
                        [extracted from the CaseWare/CM data sheet]

   Last modified: _6/13/1997_
   
    10. How does CVS differ from SABLIME? 
    
   Produced by AT&T. Sablime uses SCCS as the underlying source code
   control system. It uses some other control system (called sbcs I
   think) for managing binary files. It uses lock, edit, comit, unlock
   mechanism. It has a motif based GUI and curses based GUI (that works
   only with ksh, not tcsh, or bash) to do more common tasks. It has even
   a command line interface.
   
   Changing source happens as a result of MR. A testing person or a
   developer assigns an MR (modification request) to a group of people.
   They are allowed to take out files under that MR and change them and
   check them back in. You can set up dependencies between and MR and do
   release management to say "I want the sources to include these MRs"
   etc. It is a reasonably good maintanance system. It is bit heavy
   weight though, and the interface is not too polished and does not work
   on windows (though that may have changed). rama@savera.com
   
   Last modified: _7/30/1998_
   
    11. How does CVS differ from PVCS? 
    
   PVCS works on single files like RCS and SCCS, CVS works on complete
   subsystems. PVCS has a make utility (called a configuration builder),
   CVS does not. PVCS has a GUI interface for Unix, DOS, OS/2, and MS
   Windows.
   
                Intersolv, Inc.
                1700 NW 167th Place
                OR 97006

                                Contributed by Per Abrahamsen
                        [Extracted from Intersolv Marketing literature.]

   Last modified: _6/13/1997_
   
    12. How does CVS differ from CMVC? 
    
   CMVC is an IBM Configuration Management and Version Control system.
   (Though I'm not certain that's the right acronym expansion.) It runs
   on Suns, HPs, RS6000s, OS/2 and Windows.
   
   Other than revision control, it apparently has features to manage
   releases, bug tracking and the connection between alterations and
   reported bugs and feature requests. It is a client/server system,
   based on a choice of commercial Relational Database systems, and it
   provides a Motif or command line interface.
   
   Unlike CVS, it uses a strict locking protocol to serialize source code
   alterations.
   
   Last modified: _6/13/1997_
   
  Category: /What_is_CVS_/What_do_you_mean_by_/
  
   " + What do you mean by . . .? (Definitions)"
   
    1. What are "The Repository", "$CVSROOT" and "CVSROOT"? 
    
   The Repository is a directory tree containing the CVS administrative
   files and all the RCS files that constitute "imported" or "committed"
   work. The Repository is kept in a shared area, separate from the
   working areas of all developers.
   
   Users of CVS must set their "CVSROOT" environment variable to the
   absolute pathname of the head of the Repository. Most command line
   interpreters replace an instance of "$CVSROOT" with the value of the
   "CVSROOT" environment variable. By analogy, in this document
   "$CVSROOT" is used as shorthand for "the absolute pathname of the
   directory at the head of the Repository".
   
   One of the things found in $CVSROOT is a directory named CVSROOT. It
   contains all the "state", the administrative files, that CVS needs
   during execution. The "modules", "history", "commitinfo", "loginfo"
   and other files can be found there. See 4B.2 for more information
   about CVSROOT files.
   
   Last modified: _6/13/1997_
   
    2. What is an RCS file? 
    
   An RCS file is a text file containing the source text and the revision
   history for all committed revisions of a source file. It is stored
   separately from the working files, in a directory hierarchy, called
   the Repository.
   
   RCS is the "Revision Control System" that CVS uses to manage
   individual files. RCS file names normally end in ",v", but that can be
   altered (via the RCS -x option) to conform to file naming standards on
   platforms with unusual filename limitations.
   
   Last modified: _6/13/1997_
   
    3. What is a working file? 
    
   A working file is a disk file containing a checked-out copy of a
   source file that earlier had been placed under CVS. If the working
   file has been edited, the changes since the last committed revision
   are invisible to other users of CVS.
   
   Last modified: _6/13/1997_
   
    4. What is a working directory (or working area)? 
    
   A working directory is the place where you work and the place from
   which you "commit" files.
   
   The "checkout" command creates a tree of working directories, filling
   them with working files. Each working directory contains a
   sub-directory named ./CVS containing three administrative files, which
   are created by "checkout" and are always present:
   
   ./CVS/Entries
                contains information about working files.

   ./CVS/Repository
                contains the location of the directory within the
                Repository that was used to create the working directory.

   ./CVS/Root
                contains the value of $CVSROOT at the time you created
                the working directory.

   Other files may also appear in ./CVS depending on the state of your
   working directory:
   
   ./CVS/Tag
                contains the "sticky tag" associated with the whole
                directory.  See 3A.2 for its main purpose.
                [Created by "checkout" or "update" when using "-r <tag>".]
                [Deleted by "checkout" or "update" when using '-A'.]

   ./CVS/Entries.Static
                contains a fixed list of working files.  If this file
                exists, an "update" doesn't automatically bring newly
                added files out of the Repository.
                [Created and maintained by hand.]

   ./CVS/Checkin.prog
                contains a program to run whenever anything in the
                working directory is committed.
                [Created by checkout if "-i <prog>" appears in the
                 modules file for the checked-out module.]

   ./CVS/Update.prog
                contains a program to run whenever anything in the
                working directory is updated.
                [Created by checkout if "-u <prog>" appears in the
                 modules file for the checked-out module.]

   ./CVS/<file>,p ./CVS/<file>,t
                contain (possibly zero-length) state information about an
                "add" that has not been committed.
                [Created by "add".]
                [Deleted by "commit" or "remove".]

   Last modified: _6/13/1997_
   
    5. What is "checking out"? 
    
   "Checking out" is the act of using the "checkout" command to copy a
   particular revision from a set of RCS files into your working area.
   You normally execute "checkout" only once per working directory (or
   tree of working directories), maintaining them thereafter with the
   "update" command.
   
   See section 3C on the "checkout" command.
   
   Last modified: _6/13/1997_
   
    6. What is a revision? 
    
   A "revision" is a version of a file that was "committed" ("checked
   in", in RCS terms) some time in the past. CVS (and RCS) can retrieve
   any file that was committed by specifying its revision number or its
   "tag" ("symbolic name", in RCS terms).
   
   In CVS, a "tag" is more useful than a revision number. It usually
   marks a milestone in development represented by different revision
   numbers in different files, all available as one "tagged" collection.
   
   Sometimes the word "revision" is used as shorthand for "the file you
   get if you retrieve (via "checkout" or "update") the given revision
   from the Repository."
   
   Last modified: _6/13/1997_
   
    7. What is a "Tag"? 
    
   A "Tag" is a symbolic name, a synonym or alias for a particular
   revision number in a file. The CVS "tag" command places the same "Tag"
   on all files in a working directory, allowing you to retrieve those
   files by name in the future.
   
   The CVS "Tag" is implemented by applying RCS "symbols" to each
   individual file. The Tags on a file (or collection of files) may be
   displayed using the "log" command.
   
   Last modified: _6/13/1997_
   
    8. What are "HEAD" and "BASE"? 
    
   HEAD and BASE are built-in tags that don't show up in the "log" or
   "status" listings. They are interpreted directly by CVS.
   
   "HEAD" refers to the latest revision on the current branch in the
   Repository. The current branch is either the main line of development,
   or a branch in development created by placing a branch tag on a set of
   files and checking out that branch.
   
   "BASE" refers to the revision on the current branch you last checked
   out, updated, or committed. If you have not modified your working
   file, "BASE" is the committed revision matching it.
   
   Most of the time BASE and HEAD refer to the same revision. They can
   become different in two ways:
   
     Someone else changed HEAD by committing a new revision of your file
   to the Repository. You can pull BASE up to equal HEAD by executing
   "update".
   
     You moved BASE backward by executing "checkout" or "update" with the
   option "-r <rev/tag>" or "-D <date>". CVS records a sticky tag and
   moves your files to the specified earlier revision. You can clear the
   sticky tag and pull BASE up to equal HEAD again by executing "update
   -A".
   
   Last modified: _6/13/1997_
   
    9. What is a Branch? 
    
   In general, a branch is any mechanism that allows one or more
   developers to modify a file without affecting anyone other than those
   working on the same branch.
   
   There are four kinds of "branch" CVS can manage:
   
     The Vendor Branch.
   
   A single vendor branch is supported. The "import" command takes a
   sequence of releases from a source code vendor (called a "vendor" even
   if no money is involved), placing them on a special "Vendor" branch.
   The Vendor branch is considered part of the "Main line" of
   development, though it must be merged into locally modified files on
   the RCS Main branch before the "import" is complete.
   
   See Section 3H ("import").
   
     Your Working directory.
   
   A checked-out working directory, can be treated like a private branch.
   No one but you can touch your files. You have complete control over
   when you include work committed by others. However, you can't commit
   or tag intermediate versions of your work.
   
     A Development branch.
   
   A group of developers can share changes among the group, without
   affecting the Main line of development, by creating a branch. Only
   those who have checked-out the branch see the changes committed to
   that branch. This kind of branch is usually temporary, collapsing
   (i.e. merge and forget) into the Main line when the project requiring
   the branch is completed.
   
   You can also create a private branch of this type, allowing an
   individual to commit (and tag) intermediate revisions without changing
   the Main line. It should be managed exactly like a Development Branch
   -- collapsed into the Main line (or its parent branch, if that is not
   the Main Branch) and forgotten when the work is done.
   
     A Release branch.
   
   At release time, a branch should be created marking what was released.
   Later, small changes (sometimes called "patches") can be made to the
   release without including everything else on the Main line of
   development. You avoid forcing the customer to accept new, possibly
   untested, features added since the release. This is also the way to
   correct bugs found during testing in an environment where other
   developers have continued to commit to the Main line while you are
   testing and packaging the release.
   
   Although the internal format of this type of branch (branch tag and
   RCS branches) is the same as in a development branch, its purpose and
   the way it is managed are different. The major difference is that a
   Release branch is normally Permanent. Once you let a release out the
   door to customers, or to the next stage of whatever process you are
   using, you should retain forever the branch marking that release.
   
   Since the branch is permanent, you cannot incorporate the branch fixes
   into the Main line by "collapsing" (merging and forgetting) the
   release branch. For large changes to many files on the release branch,
   you will have to perform a branch merge using "update -j <rev> -j
   <rev>". (See 4C.7)
   
   The most common way to merge small changes back into Main line
   development is to make the change in both places simultaneously. This
   is faster than trying to perform a selective merge.
   
   See 1D.12 (merges) and Section 4C, on Branching for more info.
   
   Last modified: _6/13/1997_
   
    10. What is "the trunk"? 
    
   Another name for the RCS Main Branch. The RCS Main Branch is related,
   but not equivalent, to both the CVS Main branch and what developers
   consider to be the Main line of development. See 3H.3 and Section 4C
   on Branching.
   
   Last modified: _6/13/1997_
   
    11. What is a module? 
    
   In essence, a module is a name you hand to the "checkout" command to
   retrieve one or more files to work on. It was originally intended to
   be a simple, unique name in the "modules" file attached to a directory
   or a subset of files within a directory.
   
   The module idea is now a somewhat slippery concept that can be defined
   in two different ways:
     * A module is an argument to "checkout". There are three types:
         1. An entry in the modules file. A "module" name as described in
            'B.' below.
         2. A relative path to a directory or file in the Repository.
         3. A mixed-mode string of "modulename/relative-path". Everything
            up to the first slash ('/') is looked up as a module. The
            relative path is appended to the directory associated with
            the module name and the resulting path is checked out as in
            #2 above.
     * A module is a unique (within the file) character string in the
       first column of the modules file. There are five types:
         1. A name for a directory within the Repository that allows you
            to ignore the parent directories above it.
            Example:
                  emacs  gnu/emacs
         2. A name for a subset of the files within such a directory.
            Example:
                  ls    unix/bin Makefile ls.c
            The 2nd through Nth strings in the above can be files,
            directories or module substitutions. No relative paths.
            A module substitution occurs when you use a '&module-name'
            reference. The module-name referred to is logically
            substituted for the '&module-name' string.
         3. A relative pathname to a directory within the Repository
            which, when checked out, creates an image of part of the
            Repository structure in your current directory.
            Example:
            gnu/emacs -o /bin/emacs.helper gnu/emacs
            The files checked out are exactly the same as the files
            "checkout" would retrieve if the path weren't even in the
            modules file. The only reason to put this kind of relative
            pathname into the modules file is to hook one of the helper
            functions onto it.
         4. A relative pathname to a single file within the Repository
            which, when checked out, creates something you probably don't
            want: It creates a directory by the name of the file and puts
            the file in it.
            Example:
            gnu/emacs/Makefile -o /bin/emacs.helper gnu/emacs Makefile
            The file checked out is the same as what you would get if you
            handed the relative pathname to the "checkout" command. But
            it puts it in a strange place. The only reason to do this is
            to hook a helper function onto a specific file name.
         5. An alias consisting of a list of any of the above, including
            other aliases, plus exceptions.
            Example:
            my_work -a emacs !emacs/tests gnu/bison unix/bin/ls.c
            The exception "!emacs/test" above is functionally equivalent
            to specifying "!emacs/tests" on the "checkout" command line.
       
   Another way to look at it is that the modules file is simply another
   way to "name" files. The hierarchical directory structure provides
   another. You should use whatever turns out to be simplest for your
   development group.
   
   See 4G.2 for some specific ideas about how to use the modules file.
   
   Last modified: _11/12/1997_
   
    12. What does "merge" mean? 
    
   A merge is a way of combining changes made in two independent copies
   of a common starting file. Checking out an RCS revision produces a
   file, so for the purposes of a merge "file" and "revision" are
   equivalent. So, we can say there are always three "files" involved in
   a merge:
   
     The original, starting, "base" or "branch point" file.
   
     A copy of the base file modified in one way.
   
     Another copy of the base file modified in a different way.
   
   Humans aren't very good at handling three things at once, so the
   terminology dealing with merges can become strained. One way to think
   about it is that all merges are performed by inserting the difference
   between a base revision and a later revision (committed by someone
   else) into your working file. Both the "later" revision and your
   working file are presumed to have started life as a copy of the "base"
   revision.
   
   In CVS, there are three main types of "merge":
   
     The "update" command automatically merges revisions committed by
   others into your working file. In this case, the three files involved
   in the merge are:
   
   Base: The revision you originally checked out. Later: A revision
   committed onto the current branch after you checked out the Base
   revision. Working: Your working file. The one lying in the working
   directory containing changes you have made.
   
     The "update -j <branch_tag> {optional files}" command merges changes
   made on the given branch into your working files, which is presumed to
   be on the Main line of development.
   
   See 4C.6
   
     The "update -j <rev> -j <rev> {optional files}" command merges the
   difference between two specified revisions into files in your working
   directory. The two revisions <rev> are usually on the same branch and,
   when updating multiple files, they are most useful when they are Tag
   names rather than numeric revisions.
   
   See 4C.7
   
   Last modified: _6/13/1997_
   
  Category: /What_is_CVS_/What_is_CVS_Whats_it/
  
   " + What is CVS? What's it for? Why CVS?"
   
    1. What does CVS stand for? Can you describe it in one sentence? 
    
   "CVS" is an acronym for the "Concurrent Versions System".
   
   CVS is a "Source Control" or "Revision Control" tool designed to keep
   track of source changes made by groups of developers working on the
   same files, allowing them to stay in sync with each other as each
   individual chooses.
   
   Last modified: _6/13/1997_
   
    2. What is CVS for? What does it do for me? 
    
   CVS is used to keep track of collections of files in a shared
   directory called "The Repository". Each collection of files can be
   given a "module" name, which is used to "checkout" that collection.
   
   After checkout, files can be modified (using your favorite editor),
   "committed" back into the Repository and compared against earlier
   revisions. Collections of files can be "tagged" with a symbolic name
   for later retrieval.
   
   You can add new files, remove files you no longer want, ask for
   information about sets of files in three different ways, produce patch
   "diffs" from a base revision and merge the committed changes of other
   developers into your working files.
   
   Last modified: _6/13/1997_
   
    3. How does CVS work? 
    
   CVS saves its version-control information in RCS files stored in a
   directory hierarchy, called the Repository, which is separate from the
   user's working directory.
   
   Files in the Repository are stored in a format dictated by the RCS
   commands CVS uses to do much of its real work. RCS files are standard
   byte-stream files with an internal format described by keywords stored
   in the files themselves.
   
   To begin work, you execute a "checkout" command, handing it a module
   name or directory path (relative to the $CVSROOT variable) you want to
   work on. CVS copies the latest revision of each file in the specified
   module or directory out of the Repository and into a directory tree
   created in your current directory. You may specify a particular branch
   to work on by symbolic name if you don't want to work on the default
   (main or trunk) branch.
   
   You may then modify files in the new directory tree, build them into
   output files and test the results. When you want to make your changes
   available to other developers, you "commit" them back into the
   Repository.
   
   Other developers can check out the same files at the same time. To
   merge the committed work of others into your working files you use the
   "update" command. When your merged files build and test correctly, you
   may commit the merged result. This method is referred to as
   "copy-modify-merge", which does not require locks on the source files.
   
   At any time, usually at some milestone, you can "tag" the committed
   files, producing a symbolic name that can be handed to a future
   "checkout" command. A special form of "tag" produces a branch in
   development, as usually happens at "release" time.
   
   When you no longer plan to modify or refer to your local copy of the
   files, they can be removed.
   
   Last modified: _6/13/1997_
   
    4. What is CVS useful for? 
    
   CVS is intended to handle source control for files in three major
   situations:
   
     Multiple developers working on the same files.
   
   The major advantage of using CVS over the simpler tools like RCS or
   SCCS is that it allows multiple developers to work on the same sources
   at the same time.
   
   The shared Repository provides a rendezvous for committed sources that
   allows developers a fair amount of flexibility in how often to publish
   (via the "commit" command) changes or include work committed by others
   (via the "update" command).
   
     Tracking a stream of releases from a source vendor.
   
   If you are making changes to sources distributed by someone else, the
   CVS feature, called the Vendor Branch, allows you to combine local
   modifications with repeated vendor releases.
   
   I have found this most useful when dealing with sources from three
   major classes of source vendor:
   
     Large companies who send you tapes full of the latest release (e.g.
   Unix OS vendors, database companies).
   
     Public Domain software which *always* requires work.
   
     Pseudo-Public sources which may require work. (e.g. GNU programs, X,
   CVS itself, etc.)
   
     Branching development.
   
   Aside from the "Vendor Branch", there are three kinds of "branches in
   development" that CVS can support:
   
     Your working directory can be treated as a private branch.
   
     A Development branch can be shared by one or more developers.
   
     At release time, a branch is usually created for bug fixes.
   
   (See 1D.9 and Section 4C for more info on branches.)
   
   CVS's branch support is a bit primitive, but it was designed to allow
   you to create branches, work on them for while and merge them back
   into the main line of development. You should also be able to merge
   work performed on the main branch into the branch you are working on.
   Arbitrary sharing and merging between branches is not currently
   supported.
   
   Last modified: _6/13/1997_
   
    5. What is CVS *not* useful for? 
    
   CVS is not a build system.
   
   Though the structure of your Repository and modules file interact with
   your build system (e.g. a tree of Makefiles), they are essentially
   independent.
   
   CVS does not dictate how you build anything. It merely stores files
   for retrieval in a tree structure you devise.
   
   CVS does not dictate how to use disk space in the checked out working
   directories. If you require your Makefiles or build procedures to know
   the relative positions of everything else, you wind up requiring the
   entire Repository to be checked out. That's simply bad planning.
   
   If you modularize your work, and construct a build system that will
   share files (via links, mounts, VPATH in Makefiles, etc.), you can
   arrange your disk usage however you like.
   
   But you have to remember that *any* such system is a lot of work to
   construct and maintain. CVS does not address the issues involved. You
   must use your brain and a collection of other tools to provide a build
   scheme to match your plans.
   
   Of course, you should use CVS to maintain the tools created to support
   such a build system (scripts, Makefiles, etc).
   
   CVS is not a substitute for management.
   
   You and your project leaders are expected to plan what you are doing.
   Everyone involved must be aware of schedules, merge points, branch
   names, release dates and the range of procedures needed to build
   products. (If you produce it and someone else uses it, it is a
   product.) CVS can't cover for a failure to manage your project.
   
   CVS is an instrument for making sources dance to your tune. But you
   are the piper and the composer. No instrument plays itself or writes
   its own music.
   
   CVS is not a substitute for developer communication.
   
   When faced with conflicts within a single file, most developers manage
   to resolve them without too much effort. But a more general definition
   of "conflict" includes problems too difficult to solve without
   communication between developers.
   
   CVS cannot determine when simultaneous changes within a single file,
   or across a whole collection of files, will logically conflict with
   one another. Its concept of a "conflict" is purely textual, arising
   when two changes to the same base file are near enough to spook the
   merge command into dropping conflict markers into the merged file.
   
   CVS is not capable of figuring out distributed conflicts in program
   logic. For example, if you change the arguments to function X defined
   in file A and, at the same time, edit file B, adding new calls to
   function X using the old arguments. You are outside the realm of CVS's
   competence.
   
   Acquire the habit of reading specs and talking to your peers.
   
   CVS is not a configuration management system.
   
   CVS is a source control system. The phrase "configuration management"
   is a marketing term, not an industry-recognized set of functions.
   
   A true "configuration management system" would contain elements of the
   following:
   
                * Source control.
                * Dependency tracking.
                * Build systems (i.e. What to build and how to find
                  things during a build.  What is shared?  What is local?)
                * Bug tracking.
                * Automated Testing procedures.
                * Release Engineering documentation and procedures.
                * Tape Construction.
                * Customer Installation.
                * A way for users to run different versions of the same
                  software on the same host at the same time.

   CVS provides only the first.
   
   Last modified: _6/13/1997_
   
  Category: /What_is_CVS_/Where_do_I_find_CVS_/
  
   " + Where do I find CVS? Where can I find Help?"
   
    1. How do I get more information about CVS? 
    
     The first thing I would do is to read the Info file that comes with
   the CVS sources under "doc". You can format and read the cvs.texinfo
   file in two ways: 1. Use TeX to format it and a "dvips" command to
   print it and 2. Install the cvs.info files that are created by the
   Makefile and read them online using the Emacs "info-mode" or a
   stand-alone "info" reader.
   
     Then I'd run "cvsinit" to set up a Repository and read the man page
   while trying out the commands.
   
   Type "cvs -H" for general help or "cvs -H command" for
   command-specific help.
   
     For background, you can read the original CVS paper (in the source
   tree, under "doc"). It describes the purpose of CVS and some of how it
   was designed. Note that the emphasis of the document (especially on
   multiple vendors providing the same sources) is somewhat out of date.
   
     For more detailed information about "internals", read the man pages
   for RCS. If you are a programmer, you can also read the source code to
   CVS.
   
     Other information and tutorials may be available in the "doc"
   directory of the FTP archive described below.
   
     For current information, and a fair amount of detail, join the
   info-cvs mailing list described below.
   
   Last modified: _6/13/1997_
   
    2. Is there an archive of CVS material? 
    
   An anonymous FTP area has been set up. It contains many of the CVS
   files you might want, including extra documentation, patches and a
   copy of the latest release.
   
                ftp ftp.delos.com
                >>> User:       anonymous
                >>> Passwd:
                cd /pub/cvs
                get README
                get Index

   The README has more (and more up-to-date) information. The Index
   contains a terse list of what is in the archive.
   
   A WWW home page is also available at http://www.delos.com/cvs.
   
                          This Didn't Exist 6/23/1998
                                       
   Last modified: _6/24/1998_
   
    3. How do I get files out of the archive if I don't have FTP? 
    
   Use one of the FTP<->Email servers. These are the ones I've been told
   about:
   
     FTPMAIL service is available from the same host as the FTP server
   described above. Send mail to "ftpmail@delos.com" containing "help" in
   the body of the message. For example, on most Unix systems, you can
   type:
   
   echo help | Mail ftpmail@delos.com
   
   The FTPMAIL server will respond with a document describing how to use
   the server. If the "Mail" command doesn't exist on your system, try
   "mailx", "/usr/ucb/mail" or "/bin/mail".
   
     If you are on BITNET, use Princeton's BITFTP server. Type
   
   echo 'send help' | Mail bitftp@pucc.princeton.edu
   
   (It is likely that only BITNET addresses can use this one.)
   
     Other possibilities I've heard of from the net: (Try the one closest
   to you.)
   
   ftpmail@decwrl.dec.com ftpmail@sunsite.unc.edu ftpmail@cs.arizona.edu
   ftpmail@cs.uow.edu.au ftpmail@doc.ic.ac.uk
   
   Last modified: _6/13/1997_
   
    4. How do I get a copy of the latest version of CVS? 
    
   The latest released version of CVS and all the programs it depends on
   should be available through anonymous FTP on any FSF archive. The main
   FSF archive is at "prep.ai.mit.edu". There are mirrors of the FSF
   archive on UUNET and other large Internet sites.
   
                Program(s)      Suggested revision
                -----------     -----------------------
                CVS             1.5
                RCS             5.7 (latest version available today)
                GNU diff        2.7 (or later) [contained in diffutils-2.7]
                GDBM            1.5 (or later) [optional]

   The GNU version of diff is suggested by both the RCS and CVS
   configuration instructions because it works better than the standard
   version.
   
   It is a good idea not to accept the versions of CVS, RCS or diff you
   find lying on your system unless you have checked out their
   provenance. Using inconsistent collections of tools can cause you more
   trouble than you can probably afford.
   
   The FTP archive mentioned above should contain the latest official
   release of CVS, some official and unofficial patches and possibly
   complete patched versions of CVS in use somewhere.
   
   Last modified: _6/13/1997_
   
    5. Is there a mailing list devoted to CVS? How do I find it? 
    
   An Internet mailing list named "info-cvs" grew out of the private
   mailing list used by the CVS 1.3 alpha testers in early 1992.
   Throughout 1994, the list received an average of 100 messages per
   month.
   
   You can add yourself to the mailing list by sending an Email message
   to:
   
                info-cvs-request@prep.ai.mit.edu

   (Don't forget the "-request" or you'll send a message to the whole
   list, some of whom are capable of remote execution.)
   
   Mail to the whole list should be sent to:
   
                info-cvs@prep.ai.mit.edu

   An archive of the mailing list is maintained in the FTP archive
   mentioned above.
   
   Last modified: _6/13/1997_
   
    6. What happened to the CVS Usenet newsgroup I heard about? 
    

        A Usenet newsgroup named "gnu.cvs.info" was announced in April
        1993, with an expected creation date of August, 1993.  However,
        nothing came of this.

        If you want to discuss CVS on usenet, the correct group is
        comp.software.config-mgmt (which also covers other configuration
        management systems).  Someday it might be possible to create a
        comp.software.config-mgmt.cvs, but only if there is sufficient
        CVS traffic on comp.software.config-mgmt.

        kingdon@cyclic.com

   Last modified: _9/6/1997_
     _________________________________________________________________
   
   [Add an answer to this category]
   
   [Category /]
     _________________________________________________________________
   
   _Search the FAQ-O-Matic:_ ____________________ Search
   [matching all words]
   Or look for questions modified in the last: [7.] Days
     _________________________________________________________________
   
   The FAQ-O-Matic lives at http://gille.loria.fr:7000/cgi-bin/faqomatic.
   The code was written by Jon Howell, and the content by folks from all
   over the web.
     _________________________________________________________________
OpenPOWER on IntegriCloud