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
|
<!-- $Id$ -->
<html>
<head>
<title>CVS Minimal Help</title>
<link rev=made href="mailto:levine@cs.wustl.edu">
<!-- Changed by: David Levine, 26-Mar-1997 -->
</head>
<body text = "#000000"
link = "#000fff"
vlink = "#ff0f0f"
bgcolor = "#ffffff">
<hr><p>
<center>
<h1>CVS Minimal Help</h1>
<h2><a href="mailto:levine@cs.wustl.edu">David L. Levine</a></h2>
<font size=-1>
Last modified Monday, 30-Sep-2002 11:15:16 CDT.
</font>
</center>
<h2> </h2>
This page contains the minimum (and then some) commands necessary to
access and update <a href="http://www.cs.wustl.edu/~schmidt/ACE.html">ACE</a>
through <a href="file:/project/doc/pkg/cvs/cvs-1.10/doc/cvs.ps">CVS</a>
version control. The intended audience is local ACE developers, so
it's not by any means a general introduction to CVS. And some HTML
links and other references are local only.<p>
The information here is based on CVS versions 1.9 and 1.10.5 and later.<p>
Notes to emacs users: the emacs Tools/Version Control (or vc) pulldown
has CVS commands: it's well worth checking out. And, see the
<a href="#Preliminaries">Preliminaries</a> section for a handy
addition to your .emacs file.<p>
If you'd like to update your CVS workspace remotely, see
<a href="http://www.cs.wustl.edu/~nanbor/">Nanbor Wang</a>'s  
<a href="http://www.cs.wustl.edu/~nanbor/CVSUP/">CVSup</a>  page.<p>
Please <a href="mailto:levine@cs.wustl.edu">email me</a> any corrections or
suggestions!<p>
<font size="+2"><strong>Contents:</strong></font>
<ol>
<li><a href="#The Model">The Model</a>
<li><a href="#Preliminaries">Preliminaries</a>
<li><a href="#Getting started with ACE on CVS">Getting
started with ACE on CVS</a>
<li><a href="#Windows NT setup">Windows NT setup</a>
<li><a href="#Checking in changes">Checking in changes</a>
<li><a href="#Workspace update">Workspace update</a>
<li><a href="#Adding/removing files/directories">Adding/removing
files/directories</a>
<li><a href="#Modules">Modules</a>
<li><a href="#ChangeLog updates">ChangeLog updates</a>
<li><a href="#File revisions">File revisions</a>
<li><a href="#File reversion">File reversion</a>
<li><a href="#Renaming a file">Renaming a file</a>
<li><a href="#Local version control">Local version control</a>
<li><a href="#Branches">Branches</a>
<li><a href="#Remote repositories">Remote repositories</a>
<li><a href="#Exporting from CVS">Exporting from CVS</a>
<li><a href="#ACE_wrappers-frozen workspace">ACE_wrappers-frozen
workspace</a>
<li><a href="#ACE release bug-fix branch">ACE release bug-fix branch</a>
<li><a href="#Warning messages/problems">Warning messages/problems</a>
<li><a href="#For more info on CVS">For more info on CVS</a>
</ol>
<hr><p>
<h3>1. <a name="The Model">The Model</a></h3>
The following terms are used in the discussion in this web page:<br>
<ul>
<li><em>Repository</em>: The master store of all versions of all
controlled files.<p>
<li><em>Workspace</em>: A user's collection of controlled files.
The user may modify these files at will.<p>
<li><em>Check out</em>: Retrieve one or more files from the
repository, and place them in a workspace. Any version of any
file may be retrieved; typically, that will be the latest version.<p>
<li><em>Check in, or commit</em>: Update the latest version of
one or more files in the repository. This is done from a workspace.<p>
<li><em>Module</em>: Directory.
</ul>
Our use of CVS fits into the
<a href="http://www.cs.wustl.edu/~levine/ACE_wrappers/docs/ACE-development-process.html">ACE development process</a>.<p>
<hr><p>
<h3>2. <a name="Preliminaries">Preliminaries</a></h3>
<p>The <code>CVSROOT</code> environment variable listed below is <font
color=red> <strong><blink>required</blink></strong></font>. If you
want to use CVS from within emacs, you'll have to restart it from a
shell that has <code>CVSROOT</code> defined.<p>
Emacs users might want to add <var>(setq vc-follow-symlinks t)</var>
to your .emacs file to instruct emacs to follow symlinks to
version-controlled plain files.<p>
For lack of a better place to put the following, I'll put it here.
It's a good idea to insert a CVS/RCS keyword string at the top of
every file that you place under CVS control. This includes source
files, Makefiles, config files, <em>etc</em>. It will embed in the
file a concise record of the filename, last update time, revision
number, and last user who updated it. For C++ files, the keyword
string is:
<pre>
// $<!-- -->Id$
</pre>
It's not necessary to fill in the fields of the keyword string,
or modify them when you edit a file that already has one. CVS
does that automatically when you checkout or update the file.<p>
On Unix systems, you might want to create a file called <code>.cvsrc</code>
in your home directory with the following contents:
<pre><code>
co -P
update -P
</code></pre>
That will cause CVS to prune empty directories on checkout or update.
<p>
<hr><p>
<h3>3. <a name="Getting started with ACE on CVS">Getting started with ACE on CVS</a></h3>
Note: the first three steps are for UNIX platforms. See the
<a href="#Windows NT setup">Windows NT setup</a> section for
setup information for Windows NT.
<ol>
<li>% <code>setenv CVSROOT /project/cvs-repository </code> ####
site-specific location<p>
<li>cd to the directory that you want your ACE_wrappers workspace
to be under.<p>
<li>% <code>setenv ACE_ROOT `pwd` </code> #### to set the ACE_ROOT
environment<p>
<li>Change your umask to something like 022 <strong>if</strong> you want
others to be able to view your workspace.<p>
<li>% <code>cvs checkout ACE_wrappers</code><p>
<li>Add the ace/config.h and include/makeinclude/platform_macros.GNU
symlinks. For example, for Sun C++ on SunOS 5.5:
<pre><code>
% ln -s config-sunos5.5.h ace/config.h
% ln -s platform_sunos5_sunc++.GNU include/makeinclude/platform_macros.GNU
</code></pre><p>
<li>Hack away in your own workspace. All files have user write
permission.
</ol><p>
<hr><p>
<h3>4. <a name="Windows NT setup">Windows NT setup</a></h3>
Thanks to <a href="http://www.cs.wustl.edu/~brunsch/">Darrell Brunsch</a>
and <a href="http://www.cs.wustl.edu/~irfan/">Irfan Pyarali</a> for
providing this NT setup information. (It contains a site-specific
<code>CVSROOT</code>.)<p>
You can use the CVS client under Windows NT to keep a local repository
of ACE. To set it up, follow these steps:<P>
<ol>
<li>Find or create a directory in your path (I just created a utils
directory and added it to my path).<p>
<li>Download the files cvs.exe, patch.exe, and win32gnu.dll. They're
in a zip file on
<a href="http://download.cyclic.com/pub/cvs-1.10.5/windows/">Cyclic
Software's download site.</a> (Cyclic Software hsa been acquired
by SourceGear Corporation.)<p>
Alternatively, <a href="http://www.wincvs.org">WinCVS</a> provides
a graphical front-end on Windows. <strong>NOTE: </strong>if
you use WinCVS, beware that it enables read-only checkout by
default. So be sure not to check out that way if you want to
edit files.<p>
Thanks to <a href="http://www.riverace.com">Steve Huston</a> for that
note.<p>
<li>Be sure that the <a href="http://www.sourcegear.com/CVS">SourceGear</a>
cvs utilities precede any
<a href="http://www.cygnus.com/misc/gnu-win32/">Cygnus
GNU-Win32 utilities</a> in your path, something like this:<p>
<pre>
d:\utilities\cvs;D:\utilities\gnuwin32\b18\H-i386-cygwin32\bin
</pre>
<li>Add to your environment: <BR>
<code>LOGNAME = </code><em>username</em><br>
<code>CVSROOT = ace.cs.wustl.edu:/project/cvs-repository</code><br>
</ol>
Please note that this approach uses a remote shell. So, your
account must be able to rsh to the server machine.<p>
For an alternative approach that uses CVS pserver instead of rsh,
please see Darrell's <a
href="http://tao.cs.wustl.edu/howto/use_win32_pserver.html">CVS
pserver page for Win32</a>.<p>
<hr><p>
<h3>5. <a name="Checking in changes">Checking in changes</a></h3>
By convention, any repository change should be documented in
an appropriate ChangeLog. The ChangeLog entry should start with
a line of this form:
<pre>
ChangeLogTag: <em>date</em> <em>name</em> <<em>email address</em>>
</pre><p>
In all examples below, <code>ChangeLog</code> refers to appropriate
ChangeLog.<p>
<h4>5.1. Command line</h4>
To enter your workspace changes into the master repository from
the command line::<p>
<pre>
% cvs commit -m "ChangeLogTag: `head -1 ChangeLog`" <em>file(s)/directori(es)</em> ChangeLog
</pre><p>
<h4>5.2. From emacs</h4>
To checkin one file or directory to the repository:<p>
<ol>
<li><code>C-x v v </code>(vc-next-action) to check the file or directory
in<p>
<li>Insert the ChangeLogTag, using the first line of your ChangeLog entry<p>
<li><code>C-c C-c </code> to finish checkin
</ol><p>
<hr><p>
<h3>6. <a name="Workspace update">Workspace update</a></h3>
To update your workspace from the master repository, to pick up changes
by others:<p>
<blockquote>% <code>cvs update ACE_wrappers</code></blockquote><p>
cvs will print out a line for each directory that it enters
(by default, it will recurse through the directory tree; to
disable this and only update one directory, add <code>-l</code>
after <code>update</code>).<p>
cvs will print out a line for each file that differs from what is
in the repository. This first character indicates the file status:
<ul>
<li><code>U</code> the file was brought <strong>up-to-date</strong>, so
now it agrees with what is in the repository
<li><code>P</code> same as <code>U</code>, except used by CVS server
when it sends a patch instead of the entire file
<li><code>M</code> the file is <strong>modified</strong> in your
workspace with respect to the repository; without any
other message, it means that the file was not modified
by this update operation. If changes were
successfully merged (without conflict), then cvs will
note on the previous lines.
<li><code>C</code> the file needs to be updated, but a
<strong>conflict</strong> was detected. The file now
contains the differences, demarcated with
<code><<<<<<<</code> and
<code>>>>>>>></code>. The
unmodified file was moved to <em>.#file.revision</em>.
You'll need to edit the file to resolve the
differences. I get a lot of false positives on files
that I know I didn't modify locally: for those cases,
I just remove the file and rerun update.
<li><code>A</code> or <code>R</code> The file has been
<strong>added</strong> or <strong>removed</strong>
to/from your workspace, but the add or
remove has not yet been committed.
<li><code>?</code> the file is <strong>private</strong> to your
workspace: it does not exist in the repository
</ul>
To show what update would do to the currently directory (recursively),
without actually doing it:
<blockquote>% <code>cvs -n update <strong>.</strong></code></blockquote>
<blockquote>
The -q option to update suppresses the ``Updating'' message for each
directory:
<blockquote>%
<code>cvs -nq update <strong>.</strong></code></blockquote>
</blockquote>
To get the status of the current directory (recursively) with respect to
the repository:
<blockquote>% <code>cvs status <strong>.</strong></code></blockquote>
To get the status of a single file with respect to the repository,
with symbolic tags displayed:
<blockquote>% <code>cvs status -v <em>file</em></code></blockquote>
To show local (in current workspace) changes to one or more files,
relative to the versions that they were checked out from:
<blockquote>% <code>cvs diff <em>file(s)/directori(es)</em></code>
</blockquote>
To show local (in current workspace) changes to one or more files,
relative to the latest versions in the repository:
<blockquote>% <code>cvs diff -rHEAD <em>file(s)/directori(es)</em></code>
</blockquote><p>
<hr><p>
<h3>7. <a name="Adding/removing files/directories">Adding/removing files/directories</a></h3>
Adding one or more text files requires two steps:
<pre>
% cvs add <em>file . . .</em>
% cvs commit <em>file . . .</em>
</pre><br>
The commit may be done later, on the entire directory, etc.
Note that cvs <strong>add</strong> is not recursive, so
that the files in each directory of a hierarchy must be
added in separate commands. Also, only files in the current
directory can be added.<p>
Binary files require the <code>-kb</code> option to <code>cvs add</code>:
<pre>
% cvs add -kb <em>file . . .</em>
% cvs commit <em>file . . .</em>
</pre><br>
If not applied during the <code>add</code> operation, <code>-kb</code>
can be applied using <code>cvs admin -kb</code>.<p>
Removing files is similar, except the cvs <strong>remove</strong>
command is used instead of the <strong>add</strong> command:
<pre>
% cvs remove <em>file . . .</em>
% cvs commit <em>file . . .</em>
</pre><p>
An add of an empty directory doesn't require a commit.<p>
Removing a directory is more problematic. There is no CVS command to
remove (or rename) a directory: it has to be done behind CVS' back,
directly in the repository. This is by design; a CVS command can't be
used to irrevocably destroy information. Therefore, never remove a
directory. You can safely remove all of the files in it, using the
above steps.
To just remove a directory from a workspace (without removing it from
the repository): first, remove the directory and all of its files
using usual OS commands. Second, run
<pre>
% cvs update -P <em>directory-path </em>
</pre><br>
to prune the directory from the workspace.<p>
<hr><p>
<h3>8. <a name="Modules">Modules</a></h3>
Instead of referring to ``ACE_wrappers'' above, you can refer
to a module, such as ace, tests, performance-tests, and so on.
To get a list of known modules, use the -c option to checkout:
<blockquote>% <code>cvs checkout -c</code></blockquote><p>
<strong>IMPORTANT</strong>: if a subdirectory is added to ACE, it
<strong>must</strong> be added to the list of known modules in
<code>$CVSROOT/CVSROOT/modules</code>! If you don't want to edit that
file, please tell <a href="mailto:levine@cs.wustl.edu">David</a>. The
<code>CVSROOT</code> files are under RCS control. emacs' VC tools
handle them the same way that they handle CVS-controlled files. So,
you can check them out and back in with <code>C-x v v</code>.<p>
To add an entirely new module:
<ol>
<li>Create the directories/files.<p>
<li>Add the module to <code>$CVSROOT/CVSROOT/modules</code>, as
mentioned above.<p>
<li>Create a new directory in <code>$CVSROOT</code>, owned by the appropriate
group and with sufficient (probably group write+setuid) permissions.<p>
<li>Change to the directory just above the top-level directory for
the module in your workspace.<p>
<li><code>cvs checkout <em>new module name</em></code><p>
<li>Add all of the new directories/files in the module, as described
<a href="#Adding/removing files/directories">above</a>, then commit.
</ol>
<hr><p>
<h3>9. <a name="ChangeLog updates">ChangeLog updates</a></h3>
To automatically update the ChangeLog, use the emacs command:
<pre>
C-u C-x v a
</pre>
Thanks to James Hu <jxh@cs.wustl.edu> for this useful tidbit.<p>
To set a specific host address in your ChangeLog entries, add a line
like this to your <code>~/.emacs</code>:
<pre>
(setq mail-host-address "cs.wustl.edu")
</pre><p>
To set a specific name in your ChangeLog entries, add a line like
this to your <code>~/.emacs</code>:
<pre>
(setq user-full-name "my full name")
</pre>
Otherwise, CVS uses the name (GECOS field) from your passwd entry.<p>
<hr><p>
<h3>10. <a name="File revisions">File revisions</a></h3>
File revisions in and below the current directory may be tagged with:
<pre>
% cvs tag <em>tag</em> <strong>.</strong>
</pre><p>
To retrieve an old revision of a file, use the -r option to cvs
<strong>update</strong>:
<pre>
% cvs update -r<em>tag file</em>
</pre>
The revision tags of a file can be viewed
with the cvs <strong>log</strong> command.<p>
Or, to retrieve the file and/or directory versions as of a
certain date and time, use the -D option to cvs <strong>update</strong>,
for example:
<pre>
% cvs update -D "last Saturday" OS.{h,i,cpp}
</pre>
<strong>NOTE: </strong>The -r and -D options are ``sticky''; they will
apply to the file(s)/directories until overwritten with another revision
tag or date, or until disabled.
They are disabled by using the update -A option, which also checks out
the latest revision:
<pre>
% cvs update -A <em>file</em>
</pre><p>
To change the log message for a particular revision of a file:<p>
<pre>
% cvs admin -m<em>revision</em>:"<em>new message</em>" <em>file</em>
</pre><p>
<hr><p>
<h3>11. <a name="File reversion">File reversion</a></h3>
There are a few ways to revert a file to the last revision that is in
the repository, if you want to abandon your changes to it:
<ul>
<li>The easiest way to abandon your changes <strong>in your
workspace</strong> is to use the emacs command <code>C-x v u </code>
(vc-revert-buffer). Or from the shell, you could remove the
file and update it with <code>cvs update <em>file</em></code>.<p>
<li><strong>Do not remove a revision from the cvs repository
directly.</strong> To revert a revision that you made, use the
following command to revert the change in your workspace and
check in the reverted version:
<pre>
% cvs update -j<em>after_change</em> -j<em>before_change</em> <em>file</em>
</pre>
For example, if the version containing the version you want to
revert is 4.10, then, <em>after_change</em> should be
<code>4.10</code> and <em>before_change</em> should be
<code>4.9</code>.<p>
<strong>NOTE:</strong> this doesn't seem to work with CVS version 1.10.<p>
Make sure the patch succeeded (if you are not reverting a change
you made long time ago, most likely it will succeed) before
checking in the reverted version.<p>
Also make sure the you add a ChangeLog entry explaining why
you reverted the change.
</ul>
<hr><p>
<h3>12. <a name="Renaming a file">Renaming a file</a></h3>
There are three ways to rename a CVS-controlled file. The first
preserves the revision log, but it must be accessed by either the
original or new name, depending on what you want to see. And
revision numbers will start over at 1.0 unless set with the
<code>-r</code> option. It's all done in the user's workspace:
<pre>
Add ChangeLog entry containing:
Renamed <em>OLD</em> to <em>NEW</em>
% mv <em>OLD</em> <em>NEW</em>
% cvs remove <em>OLD</em>
% cvs add <em>NEW</em>
% cvs commit -m "ChangeLogTag: `head -1 ChangeLog`" <em>OLD</em> <em>NEW</em> ChangeLog
</pre><br>
The second method maintains the revision log in one place and the
revision number sequence. It makes fetching old releases of the
module more difficult, which may be an advantage or disadvantage
depending on local circumstances. It is more dangerous because the
repository is modified directly; see the warning in the cvs info page
about other users accessing the history file while it is being moved:
<pre>
% cd $CVSROOT/<em>MODULE</em>
% mv <em>OLD</em>,v <em>NEW</em>,v
</pre><br>
The third method is to copy the history file in the repository.
Instead of moving the history file, as in the second method above,
copy it. It's not necessary to prevent others from accessing the
file. The cvs info pages show other steps, to remove the old tags
from the new history file. While technically correct, I don't think
that's necessary for our purposes.<p>
While the first method is the safest, it has the distinct disadvantage
of hindering access of old versions. If that's not a problem for a
particular file, then it is the preferred approach. As Carlos would
probably say if you asked him, ``it's the right thing to do.''<p>
If easy access to old versions is desired, I would use the third
approach: copy the history file in the repository.<p>
<hr><p>
<h3>13. <a name="Local version control">Local version control</a></h3>
All version control with CVS is done through the master repository.
CVS doesn't provide any facility for local checkpoints. If you want
local version control in your workspace, there's nothing to stop you
from using RCS or SCCS locally (but it might confuse emacs' version
control). The preferred approach is to create a branch, and
checkpoint as much as you want on that branch. When the time comes to
make the changes public, just merge the branch. See the <a
href="#Branches">Branches</a> section of this page, and the cvs man
page, for instructions on creating and using a branch.<p>
<hr><p>
<h3>14. <a name="Branches">Branches</a></h3>
To create a branch, you must first create a tag to identify the
branch. Then, you can checkout on that branch. There are various
ways to go about doing this, but these steps show how when starting
from scratch:
<pre>
% cvs rtag -b <em>branch_tag</em> <em>module(s)</em>
% cvs checkout -r <em>branch_tag</em> <em>module(s)</em>
</pre>
It's not necessary to checkout all the files in a directory or module
on the branch, but it's probably the easiest and least confusing
approach in the long run. <strong>Note</strong> that it's usually
tricky to tag individual files on a branch because CVS won't
be able to identify which module they're in. By way of example,
to checkout just <code>ace/OS.h</code> on a branch, you'd have to do
this, assuming that you're already in the <code>ace</code> directory:
<pre>
% cd ..
% cvs rtag -b <em>branch_tag</em> ace/OS.h
% cvs checkout -r <em>branch_tag</em> ace/OS.h
% cd ace
</pre>
This can be done after modifying files, and CVS will retain your
modifications. However, if you don't trust CVS, it's best to backup
your files first.<p>
Checkouts on a branch are sticky, and will apply until the head
version of the file(s) have been checked out with the <code>-A</code>
option to <code>cvs update</code>. Presumably, this will be done
after merging the branch to the main trunk. See the
<a href="#Old file revisions">Old file revisions</a> section of this
page for similar discussion of sticky tags.<p>
To merge an entire branch to the main trunk, use the <code>-j</code>
(for <em>join</em>) option to <code>cvs checkout</code>. That just
merges in your workspace; the repository can then be updated from the
workspace using <code>commit</code> as usual:
<pre>
Add ChangeLog entry containing:
merged <em>branch_tag</em>
% cvs checkout -P -Aj <em>branch_tag</em> <em>file(s)/directori(es)</em>
% cvs commit -m "ChangeLogTag: `head -1 ChangeLog`" <em>file(s)/directori(es)</em> ChangeLog
</pre>
(The <code>-A</code> is needed if you are in the workspace that has
the checkouts on the branch. It updates the workspace to the latest
versions on the main trunk. So, <strong>don't</strong> use it if
you want to keep working on the branch.)<p>
To merge any changes on the main trunk to a branch, the first time:
<pre>
Add ChangeLog entry containing:
merged main trunk changes
% cvs update -jHEAD <em>file(s)/directori(es)</em>
% cvs commit -m "ChangeLogTag: `head -1 ChangeLog`" <em>file(s)/directori(es)</em> ChangeLog
% cvs tag <em>merged_foo_branch</em> <em>file(s)/directori(es)</em>
</pre>
<strong>AFTER MERGING, APPLY A LABEL TO THE SOURCE BRANCH,
as shown above.</strong>
For example, if you merged from the main trunk to a branch,
apply a new label to the main trunk. You can use that label
later to merge any subsequent changes on the main trunk. The
<code>cvs</code> info pages have a good example of this.
Briefly:
<pre>
Add ChangeLog entry containing:
merged main trunk changes
% cvs update -j<em>merged_foo_branch</em> -jHEAD <em>file(s)/directori(es)</em>
% cvs commit -m "ChangeLogTag: `head -1 ChangeLog`" <em>file(s)/directori(es)</em> ChangeLog
% cvs tag <em>merged_foo_branch_again</em> <em>file(s)/directori(es)</em>
</pre>
Note that any files created on the branch won't be visible on
the main trunk, even after the merge. I'm not sure of right
way to take care of this, but I follow these steps for each
file created on the branch:<p>
<ol>
<li>In the repository, move the RCS file from the <var>Attic</var>
directory up to its parent directory.
<li>Edit the RCS file, replacing the "dead" state with "Exp".
<li>Merge from the branch to the main trunk:
<pre>
Add ChangeLog entry containing:
merged <em>branch_tag</em>
% cvs update -Aj <em>branch_tag</em> <em>file</em>
% cvs commit -m "ChangeLogTag: `head -1 ChangeLog`" <em>file</em> ChangeLog
</pre>
</ol>
To create a file on a branch, in a directory that has not been
checked out on the branch:
<ol>
<li>Add the file and commit it to the main branch
<li>Create the branch tag on the file, and check the file out
on the branch.
<li>Remove the file, cvs remove the file, and commit the removal.
<li>Check the file out on the branch.
</ol>
Alternatively, the recommended procedure is to simply check the
entire directory out on the branch, then create the file.<p>
In general, deleting branch tags is not recommended. But it's often
necessary, especially when getting started with branches. The
<code>-d</code> option to <code>cvs rtag</code> can be used to delete
a branch tag.<p>
The use of a branch for maintaining a release is illustrated
in the section on the <a href="#ACE release bug-fix branch">ACE
release bug-fix branch</a>.<p>
<hr><p>
<h3>15. <a name="Remote repositories">Remote repositories</a></h3>
Before setting up a repository for remote access, be sure to see
the <a href="file:/project/doc/pkg/cvs/cvs-1.10/doc/cvs.ps">CVS
documentation</a>. There are important security considerations.<p>
An easy way to access a remote repository is via rsh. These steps
ought to get you going:
<ol>
<li>Install cvs on the local system, if it doesn't already have it.<p>
<li>Add yourself to an <code>.rhosts</code> file on the remote machine
of a user that can access the repository.<p>
<li>Set your <code>CVSROOT</code> environment variable to:<br>
<pre>
<em>remote user</em>@<em>remote host</em>:<em>remote repository</em>
</pre>
</ol>
Then, you can issue cvs commands just as you would on the remote machine.<p>
If you have ssh on your client machine, you can use ssh instead of
rsh. Just set your <code>CVS_RSH</code> environment variable to
<code>ssh</code>. You don't need to add an <code>.rhosts</code>
entry with ssh, so it's the best alternative for remote repository
access.<p>
Another way to access to remote cvs repository is to run cvs in
client-server mode. To use this feature, first check if you have your
<code>HOME</code> environment variable set properly. Then, set your
<code>CVSROOT</code> to:<p>
<pre>
:pserver:your_user_id@ace.cs.wustl.edu:/project/cvs-repository
</pre><p>
Then, do a cvs login as
<pre>
% cvs login
</pre><p>
Type in your password when CVS prompts you to enter your password.
This will create a file call "<code>.cvspass</code>" in your home
directory (as defined by <code>$HOME</code>) that contains the
encripted password for the server. You can now perform regular CVS
operation directly.<p>
<strong>Notice:</strong> It's not difficult to decode the passwords in
<code>.cvspass</code> file. Therefore, never use cvs in client-server
mode in a unsafe environment. (Where others can read your .cvspass
file.)<p>
To speed up client-server mode operations, it might help to use
the <code>cvs</code> <code>-z</code> option. It requires that
<code>gzip</code> be on your search path on both the client and
server. An example use is:<p>
<pre>
% cvs -z 1 update
</pre><p>
Thanks to <a href="http://www.cs.wustl.edu/~nanbor/">Nanbor Wang</a>
and <a href="http://www.cs.wustl.edu/~brunsch/">Darrell Brunsch</a>
for figuring out and providing this documentation for cvs
client-server mode.<p>
<hr><p>
<h3>16. <a name="Exporting from CVS">Exporting from CVS</a></h3>
There are two different strategies for exporting CVS-controlled files,
such as for code releases. The first, preferred approach is to use
the cvs <strong>export</strong> command to stage a version of the
controlled files to a non-controlled directory. This version will
not have any of the CVS files in it. THe second approach is to
create a release from a user's CVS-controlled workspace.<p>
To use cvs <strong>export</strong>, either a date or revision
tag must be specified. It's usually a good idea to tag the sources
with a revision tag and use that. So, the steps would be:<br>
<pre>
% cd <em>root of directory tree</em>
% cvs tag <em>tag</em> <strong>.</strong>
% cd <em>staging directory</em>
% cvs export -r <em>tag</em>
% find . -print | cpio -o -H tar | gzip -9 > <em>tar filename</em>
</pre>
To tag and create a release in the form of a gzip'ped tar file
from a user's workspace:
<pre>
% cd <em>root of directory tree</em>
% cvs tag <em>tag</em> <strong>.</strong>
% find . -name CVS -prune -o -print | cpio -o -H tar | gzip -9 > <em>tar filename</em>
</pre>
The relative advantage of the first, export approach is that you will
be sure that only CVS-controlled files will be released. However, it
requires the extra step and creation of the staging area.<p>
This extra step is one reason why we don't currently stage releases of
ACE. Instead, they are built from Doug's personal workspace. That
workspace is visible on the web, so that ACE users can track the very
latest changes without any explicit action by Doug. If we were to
stage it, to make any change visible would require an explicit move to
the staging area.<p>
<hr><p>
<h3>17. <a name="ACE_wrappers-frozen workspace">ACE_wrappers-frozen workspace</a></h3>
This section applies to the DOC group at Wash. U. only:<p>
There's now a ``frozen'' ACE in
<strong>/project/cvs-repository/ACE_wrappers-frozen/</strong>.
It contains the latest official release of ACE.<p>
There are complete g++ 2.7.2.1 and Sun C++ 4.2 builds in the
<strong>build</strong> directory below the directory noted above.
To use one of these builds, set or prepend to these environment variables:<p>
<table border>
<tr>
<th>Compiler</th>
<th>set <strong>WRAPPER_ROOT</strong> to:</th>
<th>prepend to <strong>LD_LIBRARY_PATH</strong>:</th>
<tr>
<td>g++</td>
<td>/project/cvs-repository/ACE_wrappers-frozen/build/SunOS5_g++</td>
<td>/project/cvs-repository/ACE_wrappers-frozen/build/SunOS5_g++/ace</td>
<tr>
<td>Sun C++</td>
<td>/project/cvs-repository/ACE_wrappers-frozen/build/SunOS5_sunc++-4.2</td>
<td>/project/cvs-repository/ACE_wrappers-frozen/build/SunOS5_sunc++-4.2/ace</td>
</table><p>
<hr><p>
<h3>18. <a name="ACE release bug-fix branch">ACE release bug-fix branch</a></h3>
This section applies to the DOC group at Wash. U. only:<p>
The ``main line'' CVS branch will (continue to) be the ``new features''
branch. If you want the very latest and greatest ACE at all times, no
changes to the use of your workspace are required. Just
<code>cvs update</code> it as usual.<p>
Bug fixes to the official release will go on a branch. For the ACE
4.2 release, for example, this branch is name
<strong>ACE-4_2</strong>. (CVS does not allow periods in branch names
or any other tags.) To use it, do this in your workspace:
<pre>
% cd ..
% cvs checkout -r ACE-4_2 ACE_wrappers
</pre>
From that point on, all updates and commits in that workspace
will be from/to the <strong>ACE-4_2</strong> branch.<p>
<hr><p>
<h3>19. <a name="Warning messages/problems">Warning messages/problems</a></h3>
<dl>
<blockquote>
<dt><pre>cvs update: conflict: <em>foo </em>is modified but no longer in the repository<br>
U <em>bar</em></pre>
<dd>That might indicate that file <em>foo</em> was renamed to <em>bar</em>.
If so, <em>foo</em> should be removed from the current workspace. (And
that warning will not reoccur for the workspace, because its CVS will
have removed <em>foo</em> from the workspace entries and checked out
<em>bar</em>.)<p>
<dt><pre>cvs update: [<em>time</em>] waiting for <em>user</em>'s lock in <em>repository</em></pre>
<dd>Check for lock files and directories in the <code>$CVSROOT/CVSROOT</code>
and lock files anywhere in the <code>$CVSROOT</code> hierarchy. Remove
ones that no longer appear to be in use and retry. Lock files and
directories have names starting with ``.#'', I think.<p>
<dt>Why does a file in the repository not have group and/or other read
permission?<p>
<dd>Because it didn't have those permissions when it was added to the
repository. To fix it, those permissions can be added to the ,v file in
the repository. To avoid it, those permissions should be added to the
file before it is created/committed the first time.<p>
<dt>Why does CVS keep removing group/and or other read permission from a
file in my workspace?<p>
<dd>Because your umask is something like 7 or 77. Change it to something
like 22. If you don't want to change it for everything, then alias cvs;
in t/csh:<br>
<blockquote>% <code>alias cvs '(umask 22; \cvs \!*)'</code></blockquote>
<p>
Also, the file will have to have mode 644 before you commit it. So if
your editor removes group/other read permission, you'll have to ``fix''
that as well.<p>
<dt>I modified Makefile in my workspace so I don't build static or shared
ACE libraries. But, I forgot about it and commited the modified
Makefile to the repository. Help?<p>
<dd>You'll have to correct the Makefile and commit your corrections.<p>
Instead of modifying your makefile, try these commands to build the
ACE static and shared libraries, respectively:
<blockquote>% make <code>static_libs_only=1</code></blockquote>
<blockquote>% make <code>shared_libs_only=1</code></blockquote>
</blockquote>
</dl><p>
<hr><p>
<h3>20. <a name="For more info on CVS">For more info on CVS</a></h3>
Please see these sources for more information on CVS:
<ul>
<li>David Discher's <a href="http://dpd.dpdtech.com/cvs/">Quick N
Dirty CVS HOW-TO</a> is really helpful.<p>
<li>Please check out David G. Grubbs' great, comprehensive <a
href="http://cellworks.washington.edu/pub/docs/cvs/cvs-FAQ/cvsfaq0.html">"The
CVS FAQ"</a>.<p>
<li><a href="http://www.loria.fr/~molli/cvs-index.html">CVS Bubbles</a>
is a collection of useful CVS information and links.<p>
<li>Commercial support for CVS is available from <a
href="http://www.sourcegear.com/CVS">SourceGear Corporation</a>.
Their web pages are very helpful.<p>
<li>Terris Linenbach has an interesting, brief discussion of
source code management on-line at <a
href="http://devguy.com/fp/ProgrammersCanvas">Programmers'
Canvas</a>. Programmers' Canvas is a pattern language,
also quite interesting.
</ul>
<p><hr>
<p>Back to
<a href="http://www.cs.wustl.edu/~levine">David L. Levine's home page</a>.
<p>
<font size=-1>
Last modified 11:15:16 CDT 30 September 2002.
<br>
[an error occurred while processing this directive]
[an error occurred while processing this directive]
<p>
</font>
</body>
</html>
|
