![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to rcsintro.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / rcs / man|
Return to rcsintro.1 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / rcs / man |
1.1 root 1: .TH RCSINTRO 1L "May 11, 1983" "Purdue University"
2: .SH NAME
3: rcsintro - introduction to RCS commands
4: .SH DESCRIPTION
5: The Revision Control System (RCS) manages multiple revisions of text files.
6: RCS automates the storing, retrieval, logging, identification, and merging
7: of revisions. RCS is useful for text that is revised frequently, for example
8: programs, documentation, graphics, papers, form letters, etc.
9: .PP
10: The basic user interface is extremely simple. The novice only needs
11: to learn two commands:
12: .IR ci (1L)
13: and
14: .IR co (1L).
15: \fICi\fR, short for "check in", deposits the contents of a
16: text file into an archival file called an RCS file. An RCS file
17: contains all revisions of a particular text file.
18: \fICo\fR, short for "check out", retrieves revisions from an RCS file.
19: .PP
20: .B "Functions of RCS"
21: .PP
22: .IP \(bu
23: Storage and retrieval of multiple revisions of text. RCS saves all old
24: revisions in a space efficient way.
25: Changes no longer destroy the original, because the
26: previous revisions remain accessible. Revisions can be retrieved according to
27: ranges of revision numbers, symbolic names, dates, authors, and
28: states.
29: .IP \(bu
30: Maintenance of a complete history of changes. RCS logs all changes automatically.
31: Besides the text of each revision, RCS stores the author, the date and time of
32: check-in, and a log message summarizing the change.
33: The logging makes it easy to find out
34: what happened to a module, without having to compare
35: source listings or having to track down colleagues.
36: .IP \(bu
37: Resolution of access conflicts. When two or more programmers wish to
38: modify the same revision, RCS alerts the programmers and prevents one
39: modification from corrupting the other.
40: .IP \(bu
41: Maintenance of a tree of Revisions. RCS can maintain separate lines of development
42: for each module. It stores a tree structure that represents the
43: ancestral relationships among revisions.
44: .IP \(bu
45: Merging of revisions and resolution of conflicts.
46: Two separate lines of development of a module can be coalesced by merging.
47: If the revisions to be merged affect the same sections of code, RCS alerts the
48: user about the overlapping changes.
49: .IP \(bu
50: Release and configuration control. Revisions can be assigned symbolic names
51: and marked as released, stable, experimental, etc.
52: With these facilities, configurations of modules can be
53: described simply and directly.
54: .IP \(bu
55: Automatic identification of each revision with name, revision number,
56: creation time, author, etc.
57: The identification is like a stamp that can be embedded at an appropriate place
58: in the text of a revision.
59: The identification makes it simple to determine which
60: revisions of which modules make up a given configuration.
61: .IP \(bu
62: Minimization of secondary storage. RCS needs little extra space for
63: the revisions (only the differences). If intermediate revisions are
64: deleted, the corresponding deltas are compressed accordingly.
65: .sp
66: .PP
67: .B "Getting Started with RCS"
68: .PP
69: Suppose you have a file f.c that you wish to put under control of RCS.
70: Invoke the check-in command
71: .PP
72: .ti 1.5i
73: .B "ci f.c
74: .PP
75: This command creates the RCS file f.c,v, stores f.c into it as revision 1.1, and
76: deletes f.c. It also asks you for a description. The description
77: should be a synopsis of the contents of the file. All later check-in
78: commands will ask you for a log entry, which should summarize the
79: changes that you made.
80: .PP
81: Files ending in ,v are called RCS files (`v' stands for `versions'),
82: the others are called working files.
83: To get back the working file f.c in the previous example, use the check-out
84: command
85: .PP
86: .ti 1.5i
87: .B "co f.c
88: .PP
89: This command extracts the latest revision from f.c,v and writes
90: it into f.c. You can now edit f.c and check it back in by invoking
91: .PP
92: .ti 1.5i
93: .B "ci f.c
94: .PP
95: \fICi\fR increments the revision number properly.
96: If \fIci\fR complains with the message
97: .PP
98: ci error: no lock set by <your login>
99: .PP
100: then your system administrator has decided to create all RCS files
101: with the locking attribute set to `strict'. In this case, you should
102: have locked the revision during the previous check-out. Your last check-out
103: should have been
104: .PP
105: .ti 1.5i
106: .B "co \-l f.c
107: .PP
108: Of course, it is too late now to do the check-out with locking, because you
109: probably modified f.c already, and a second check-out would
110: overwrite your modifications. Instead, invoke
111: .PP
112: .ti 1.5i
113: .B "rcs \-l f.c
114: .PP
115: This command will lock the latest revision for you, unless somebody
116: else got ahead of you already. In this case, you'll have to negotiate with
117: that person.
118: .PP
119: Locking assures that you, and only you, can check in the next update, and
120: avoids nasty problems if several people work on the same file.
121: Even if a revision is locked, it can still be checked out for
122: reading, compiling, etc. All that locking
123: prevents is a CHECK-IN by anybody but the locker.
124: .PP
125: If your RCS file is private, i.e., if you are the only person who is going
126: to deposit revisions into it, strict locking is not needed and you
127: can turn it off.
128: If strict locking is turned off,
129: the owner of the RCS file need not have a lock for check-in; all others
130: still do. Turning strict locking off and on is done with the commands
131: .PP
132: .ti 1.5i
133: .BR "rcs \-U f.c" " and " "rcs \-L f.c"
134: .PP
135: If you don't want to clutter your working directory with RCS files, create
136: a subdirectory called RCS in your working directory, and move all your RCS
137: files there. RCS commands will look first into that directory to find
138: needed files. All the commands discussed above will still work, without any
139: modification.
140: (Actually, pairs of RCS and working files can be specified in 3 ways:
141: (a) both are given, (b) only the working file is given, (c) only the
142: RCS file is given. Both RCS and working files may have arbitrary path prefixes;
143: RCS commands pair them up intelligently).
144: .PP
145: To avoid the deletion of the working file during check-in (in case you want to
146: continue editing), invoke
147: .PP
148: .ti 1.5i
149: .BR "ci \-l f.c" " or " "ci \-u f.c"
150: .PP
151: These commands check in f.c as usual, but perform an implicit
152: check-out. The first form also locks the checked in revision, the second one
153: doesn't. Thus, these options save you one check-out operation.
154: The first form is useful if locking is strict, the second one if not strict.
155: Both update the identification markers in your working file (see below).
156: .PP
157: You can give \fIci\fR the number you want assigned to a checked in
158: revision. Assume all your revisions were numbered 1.1, 1.2, 1.3, etc.,
159: and you would like to start release 2.
160: The command
161: .PP
162: .ti 1.5i
163: .BR "ci \-r2 f.c" " or " "ci \-r2.1 f.c"
164: .PP
165: assigns the number 2.1 to the new revision.
166: From then on, \fIci\fR will number the subsequent revisions
167: with 2.2, 2.3, etc. The corresponding \fIco\fR commands
168: .PP
169: .ti 1.5i
170: .BR "co \-r2 f.c" " and " "co \-r2.1 f.c"
171: .PP
172: retrieve the latest revision numbered 2.x and the revision 2.1,
173: respectively. \fICo\fR without a revision number selects
174: the latest revision on the "trunk", i.e., the highest
175: revision with a number consisting of 2 fields. Numbers with more than 2
176: fields are needed for branches.
177: For example, to start a branch at revision 1.3, invoke
178: .PP
179: .ti 1.5i
180: .B "ci \-r1.3.1 f.c
181: .PP
182: This command starts a branch numbered 1 at revision 1.3, and assigns
183: the number 1.3.1.1 to the new revision. For more information about
184: branches, see \fIrcsfile\fR(5L).
185: .sp
186: .PP
187: .B "Automatic Identification"
188: .PP
189: RCS can put special strings for identification into your source and object
190: code. To obtain such identification, place the marker
191: .PP
192: .ti 1.5i
193: $\&Header$
194: .PP
195: into your text, for instance inside a comment.
196: RCS will replace this marker with a string of the form
197: .PP
198: .ti 1.5i
199: $\&Header: filename revision_number date time author state $
200: .PP
201: With such a marker on the first page of each module, you can
202: always see with which revision you are working.
203: RCS keeps the markers up to date automatically.
204: To propagate the markers into your object code, simply put
205: them into literal character strings. In C, this is done as follows:
206: .PP
207: .ti 1.5i
208: static char rcsid[] = "$\&Header$";
209: .PP
210: The command \fIident\fR extracts such markers from any file, even object code
211: and dumps.
212: Thus, \fIident\fR lets you find out
213: which revisions of which modules were used in a given program.
214: .PP
215: You may also find it useful to put the marker $\&Log$
216: into your text, inside a comment. This marker accumulates
217: the log messages that are requested during check-in.
218: Thus, you can maintain the complete history of your file directly inside it.
219: There are several additional identification markers; see \fIco\fR(1L) for
220: details.
221: .SH IDENTIFICATION
222: .de VL
223: \\$2
224: ..
225: Author: Walter F. Tichy,
226: Purdue University, West Lafayette, IN, 47907.
227: .br
228: Revision Number:
229: .VL $Revision: 1.2 $
230: ; Release Date:
231: .VL $Date: 89/05/02 11:17:54 $
232: \&.
233: .br
234: Copyright \(co 1982, 1988, 1989 by Walter F. Tichy.
235: .SH SEE ALSO
236: ci(1L), co(1L), ident(1L), merge(1L), rcs(1L), rcsdiff(1L), rcsmerge(1L), rlog(1L),
237: rcsfile(5L),
238: .br
239: Walter F. Tichy, "Design, Implementation, and Evaluation of a Revision Control
240: System," in \fIProceedings of the 6th International Conference on Software
241: Engineering\fR, IEEE, Tokyo, Sept. 1982.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.