![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to rcs.ms CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps1 / 13.rcs|
Return to rcs.ms CVS log | Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps1 / 13.rcs |
1.1 root 1: .\" Copyright (c) 1986 Regents of the University of California.
2: .\" All rights reserved. The Berkeley software License Agreement
3: .\" specifies the terms and conditions for redistribution.
4: .\"
5: .\" @(#)rcs.ms 6.1 (Berkeley) 5/7/86
6: .\"
7: .OH 'Introduction to RCS''PS1:13-%'
8: .EH 'PS1:13-%''Introduction to RCS'
9: .TL
10: An Introduction to the Revision Control System
11: .AU
12: Walter F. Tichy
13: .AI
14: Department of Computer Sciences
15: Purdue University
16: West Lafayette, IN 47907
17: .AB
18: The Revision Control System (RCS) manages software libraries.
19: It greatly increases programmer productivity
20: by centralizing and cataloging changes to a software project.
21: This document describes the benefits of using a source code control system.
22: It then gives a tutorial introduction to the use of RCS.
23: .AE
24: .SH
25: Functions of RCS
26: .PP
27: The Revision Control System (RCS) manages multiple revisions of text files.
28: RCS automates the storing, retrieval, logging, identification, and merging
29: of revisions. RCS is useful for text that is revised frequently, for example
30: programs, documentation, graphics, papers, form letters, etc.
31: It greatly increases programmer productivity
32: by providing the following functions.
33: .IP 1.
34: RCS stores and retrieves multiple revisions of program and other text.
35: Thus, one can maintain one or more releases while developing the next
36: release, with a minimum of space overhead. Changes no longer destroy the
37: original -- previous revisions remain accessible.
38: .RS
39: .IP a.
40: Maintains each module as a tree of revisions.
41: .IP b.
42: Project libraries can
43: be organized centrally, decentralized, or any way you like.
44: .IP c.
45: RCS works for any type of text: programs, documentation, memos, papers,
46: graphics, VLSI layouts, form letters, etc.
47: .RE
48: .IP 2.
49: RCS maintains a complete history of changes.
50: Thus, one can find out what happened to a module easily
51: and quickly, without having to compare source listings or
52: having to track down colleagues.
53: .RS
54: .IP a.
55: RCS performs automatic record keeping.
56: .IP b.
57: RCS logs all changes automatically.
58: .IP c.
59: RCS guarantees project continuity.
60: .RE
61: .IP 3.
62: RCS manages multiple lines of development.
63: .IP 4.
64: RCS can merge multiple lines of development.
65: Thus, when several parallel lines of development must be consolidated
66: into one line, the merging of changes is automatic.
67: .IP 5.
68: RCS flags coding conflicts.
69: If two or more lines of development modify the same section of code,
70: RCS can alert programmers about overlapping changes.
71: .IP 6.
72: RCS resolves access conflicts.
73: When two or more programmers wish to modify the same revision,
74: RCS alerts the programmers and makes sure that one change will not wipe
75: out the other one.
76: .IP 7.
77: RCS provides high-level retrieval functions.
78: Revisions can be retrieved according to ranges of revision numbers,
79: symbolic names, dates, authors, and states.
80: .IP 8.
81: RCS provides release and configuration control.
82: Revisions can be marked as released, stable, experimental, etc.
83: Configurations of modules can be described simply and directly.
84: .IP 9.
85: RCS performs automatic identification of modules with name, revision
86: number, creation time, author, etc.
87: Thus, it is always possible to determine which revisions of which
88: modules make up a given configuration.
89: .IP 10.
90: Provides high-level management visibility.
91: Thus, it is easy to track the status of a software project.
92: .RS
93: .IP a.
94: RCS provides a complete change history.
95: .IP b.
96: RCS records who did what when to which revision of which module.
97: .RE
98: .IP 11.
99: RCS is fully compatible with existing software development tools.
100: RCS is unobtrusive -- its interface to the file system is such that
101: all your existing software tools can be used as before.
102: .IP 12.
103: RCS' basic user interface is extremely simple. The novice only
104: needs to learn two commands. Its more sophisticated features have been
105: tuned towards advanced software development environments and the
106: experienced software professional.
107: .IP 13.
108: RCS simplifies software distribution if customers
109: also maintain sources with RCS. This technique assures proper
110: identification of versions and configurations, and tracking of customer
111: changes. Customer changes can be merged into distributed
112: versions locally or by the development group.
113: .IP 14.
114: RCS needs little extra space for the revisions (only the differences).
115: If intermediate revisions are deleted, the corresponding
116: differences are compressed into the shortest possible form.
117: .SH
118: Getting Started with RCS
119: .PP
120: Suppose you have a file f.c that you wish to put under control of RCS.
121: Invoke the checkin command:
122: .DS
123: ci f.c
124: .DE
125: This command creates f.c,v, stores f.c into it as revision 1.1, and
126: deletes f.c.
127: It also asks you for a description. The description should be
128: a synopsis of the contents of the file.
129: All later checkin commands will ask you for a log entry,
130: which should summarize the changes that you made.
131: .PP
132: Files ending in ,v are called RCS files ("v" stands for "versions"),
133: the others are called working files.
134: To get back the working file f.c in the previous example, use the checkout
135: command:
136: .DS
137: co f.c
138: .DE
139: This command extracts the latest revision from f.c,v and writes
140: it into f.c.
141: You can now edit f.c and check it in back in by invoking:
142: .DS
143: ci f.c
144: .DE
145: \fICi\fR increments the revision number properly.
146: If \fIci\fR complains with the message
147: .DS
148: ci error: no lock set by <your login>
149: .DE
150: then your system administrator has decided to create all RCS files
151: with the locking attribute set to ``strict''.
152: With strict locking, you you must lock the revision during
153: the previous checkout.
154: Thus, your last checkout should have been
155: .DS
156: co -l f.c
157: .DE
158: Locking assures that you, and only you, can check in the next update, and
159: avoids nasty problems if several people work on the same file.
160: Of course, it is too late now to do the checkout with locking, because you
161: probably modified f.c already, and a second checkout would
162: overwrite your changes. Instead, invoke
163: .DS
164: rcs -l f.c
165: .DE
166: This command will lock the latest revision for you, unless somebody
167: else got ahead of you already.
168: If someone else has the lock you will have to negotiate your changes
169: with them.
170: .PP
171: If your RCS file is private, i.e., if you are the only person who is going
172: to deposit revisions into it, strict locking is not needed and you
173: can turn it off.
174: If strict locking is turned off,
175: the owner off the RCS file need not have a lock for checkin; all others
176: still do. Turning strict locking off and on is done with the commands:
177: .DS
178: rcs -U f.c and rcs -L f.c
179: .DE
180: You can set the locking to strict or non-strict on every RCS file.
181: .PP
182: If you do not want to clutter your working directory with RCS files, create
183: a subdirectory called RCS in your working directory, and move all your RCS
184: files there. RCS commands will look first into that directory to find
185: needed files. All the commands discussed above will still work, without any
186: change*.
187: .FS
188: * Pairs of RCS and working files can really be specified in 3 ways:
189: a) both are given, b) only the working file is given, c) only the
190: RCS file is given. Both files may have arbitrary path prefixes;
191: RCS commands pair them up intelligently.
192: .FE
193: .PP
194: To avoid the deletion of the working file during checkin (should you want to
195: continue editing), invoke
196: .DS
197: ci -l f.c
198: .DE
199: This command checks in f.c as usual, but performs an additional
200: checkout with locking.
201: Thus, it saves you one checkout operation.
202: There is also an option
203: \fB-u\fR for \fIci\fR that does a checkin followed by a checkout without
204: locking. This is useful if you want to compile the file after the checkin.
205: Both options also update the identification markers in your file (see below).
206: .PP
207: You can give \fIci\fR the number you want assigned to a checked in
208: revision. Assume all your revisions were numbered 1.1, 1.2, 1.3, etc.,
209: and you would like to start release 2.
210: The command
211: .DS
212: ci -r2 f.c or ci -r2.1 f.c
213: .DE
214: assigns the number 2.1 to the new revision.
215: From then on, \fIci\fR will number the subsequent revisions
216: with 2.2, 2.3, etc. The corresponding \fIco\fR commands
217: .DS
218: co -r2 f.c and co -r2.1 f.c
219: .DE
220: retrieve the latest revision numbered 2.x and the revision 2.1,
221: respectively. \fICo\fR without a revision number selects
222: the latest revision on the "trunk", i.e., the highest
223: revision with a number consisting of 2 fields. Numbers with more than 2
224: fields are needed for branches.
225: For example, to start a branch at revision 1.3, invoke
226: .DS
227: ci -r1.3.1 f.c
228: .DE
229: This command starts a branch numbered 1 at revision 1.3, and assigns
230: the number 1.3.1.1 to the new revision. For more information about
231: branches, see \fIrcsfile\fR(5).
232: .SH
233: Automatic Identification
234: .PP
235: RCS can put special strings for identification into your source and object
236: code. To obtain such identification, place the marker
237: .DS
238: $Header$
239: .DE
240: into your text, for instance inside a comment.
241: RCS will replace this marker with a string of the form
242: .DS
243: $Header: filename revisionnumber date time author state $
244: .DE
245: You never need to touch this string, because RCS keeps it
246: up to date automatically.
247: To propagate the marker into your object code, simply put
248: it into a literal character string. In C, this is done as follows:
249: .DS
250: static char rcsid[] = "$Header$";
251: .DE
252: The command \fIident\fR extracts such markers from any file, even object code.
253: Thus, \fIident\fR helps you to find out
254: which revisions of which modules were used in a given program.
255: .PP
256: You may also find it useful to put the marker
257: .DS
258: $Log$
259: .DE
260: into your text, inside a comment. This marker accumulates
261: the log messages that are requested during checkin.
262: Thus, you can maintain the complete history of your file directly inside it.
263: There are several additional identification markers; see \fIco\fR (1) for
264: details.
265: .SH
266: How to combine MAKE and RCS
267: .PP
268: If your RCS files are in the same directory as your working files,
269: you can put a default rule into your makefile. Do not use a rule
270: of the form .c,v.c, because such a rule keeps a copy of every
271: working file checked out, even those you are not working on. Instead, use this:
272: .DS
273:
274: .SUFFIXES: .c,v
275:
276: .c,v.o:
277: co -q $*.c
278: cc $(CFLAGS) -c $*.c
279: rm -f $*.c
280:
281: prog: f1.o f2.o .....
282: cc f1.o f2.o ..... -o prog
283: .DE
284: This rule has the following effect. If a file f.c does not exist, and f.o
285: is older than f.c,v, MAKE checks out f.c, compiles f.c into f.o, and then
286: deletes f.c.
287: From then on, MAKE will use f.o until you change f.c,v.
288: .PP
289: If f.c exists (presumably because you are working on it), the default
290: rule .c.o takes precedence, and f.c is compiled into f.o, but not deleted.
291: .PP
292: If you keep your RCS file in the directory ./RCS, all this will not work
293: and you have to write explicit checkout rules for every file, like
294: .DS
295: f1.c: RCS/f1.c,v; co -q f1.c
296: .DE
297: Unfortunately, these rules do not
298: have the property of removing unneeded .c-files.
299: .SH
300: Additional Information on RCS
301: .PP
302: If you want to know more about RCS, for example how to work
303: with a tree of revisions and how to use symbolic revision numbers, read
304: the following paper:
305: .sp 1
306: Walter F. Tichy, ``Design, Implementation, and Evaluation of a
307: Revision Control System,'' in \fIProceedings of the 6th International
308: Conference on Software Engineering\fR, IEEE, Tokyo, Sept. 1982.
309: .PP
310: Taking a look at the manual page \fIRCSFILE\fP(5)
311: should also help to understand the revision tree permitted by RCS.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.