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