1RCSINTRO(1) General Commands Manual RCSINTRO(1)
2
6 rcsintro - introduction to RCS commands
7
9 The Revision Control System (RCS) manages multiple revisions of files.
10 RCS automates the storing, retrieval, logging, identification, and
11 merging of revisions. RCS is useful for text that is revised fre‐
12 quently, for example programs, documentation, graphics, papers, and
13 form letters.
14 The basic user interface is extremely simple. The novice only needs to
16 learn two commands: ci(1) and co(1). ci, short for “check in”,
17 deposits the contents of a file into an archival file called an RCS
18 file. An RCS file contains all revisions of a particular file. co,
19 short for “check out”, retrieves revisions from an RCS file.
20 Functions of RCS
22 · Store and retrieve multiple revisions of text. RCS saves all
23 old revisions in a space efficient way. Changes no longer
24 destroy the original, because the previous revisions remain
25 accessible. Revisions can be retrieved according to ranges of
26 revision numbers, symbolic names, dates, authors, and states.
27 · Maintain a complete history of changes. RCS logs all changes
29 automatically. Besides the text of each revision, RCS stores
30 the author, the date and time of check-in, and a log message
31 summarizing the change. The logging makes it easy to find out
32 what happened to a module, without having to compare source
33 listings or having to track down colleagues.
34 · Resolve access conflicts. When two or more programmers wish to
36 modify the same revision, RCS alerts the programmers and pre‐
37 vents one modification from corrupting the other.
38 · Maintain a tree of revisions. RCS can maintain separate lines
40 of development for each module. It stores a tree structure that
41 represents the ancestral relationships among revisions.
42 · Merge revisions and resolve conflicts. Two separate lines of
44 development of a module can be coalesced by merging. If the
45 revisions to be merged affect the same sections of code, RCS
46 alerts the user about the overlapping changes.
47 · Control releases and configurations. Revisions can be assigned
49 symbolic names and marked as released, stable, experimental,
50 etc. With these facilities, configurations of modules can be
51 described simply and directly.
52 · Automatically identify each revision with name, revision number,
54 creation time, author, etc. The identification is like a stamp
55 that can be embedded at an appropriate place in the text of a
56 revision. The identification makes it simple to determine which
57 revisions of which modules make up a given configuration.
58 · Minimize secondary storage. RCS needs little extra space for
60 the revisions (only the differences). If intermediate revisions
61 are deleted, the corresponding deltas are compressed accord‐
62 ingly.
63 Getting Started with RCS
65 Suppose you have a file f.c that you wish to put under control of RCS.
66 If you have not already done so, make an RCS directory with the command
67 mkdir RCS
69 Then invoke the check-in command
71 ci f.c
73 This command creates an RCS file in the RCS directory, stores f.c into
75 it as revision 1.1, and deletes f.c. It also asks you for a descrip‐
76 tion. The description should be a synopsis of the contents of the
77 file. All later check-in commands will ask you for a log entry, which
78 should summarize the changes that you made.
79 Files in the RCS directory are called RCS files; the others are called
81 working files. To get back the working file f.c in the previous exam‐
82 ple, use the check-out command
83 co f.c
85 This command extracts the latest revision from the RCS file and writes
87 it into f.c. If you want to edit f.c, you must lock it as you check it
88 out with the command
89 co -l f.c
91 You can now edit f.c.
93 Suppose after some editing you want to know what changes that you have
95 made. The command
96 rcsdiff f.c
98 tells you the difference between the most recently checked-in version
100 and the working file. You can check the file back in by invoking
101 ci f.c
103 This increments the revision number properly.
105 If ci complains with the message
107 ci error: no lock set by your name
109 then you have tried to check in a file even though you did not lock it
111 when you checked it out. Of course, it is too late now to do the
112 check-out with locking, because another check-out would overwrite your
113 modifications. Instead, invoke
114 rcs -l f.c
116 This command will lock the latest revision for you, unless somebody
118 else got ahead of you already. In this case, you'll have to negotiate
119 with that person.
120 Locking assures that you, and only you, can check in the next update,
122 and avoids nasty problems if several people work on the same file.
123 Even if a revision is locked, it can still be checked out for reading,
124 compiling, etc. All that locking prevents is a check-in by anybody but
125 the locker.
126 If your RCS file is private, i.e., if you are the only person who is
128 going to deposit revisions into it, strict locking is not needed and
129 you can turn it off. If strict locking is turned off, the owner of the
130 RCS file need not have a lock for check-in; all others still do. Turn‐
131 ing strict locking off and on is done with the commands
132 rcs -U f.c and rcs -L f.c
134 If you don't want to clutter your working directory with RCS files,
136 create a subdirectory called RCS in your working directory, and move
137 all your RCS files there. RCS commands will look first into that
138 directory to find needed files. All the commands discussed above will
139 still work, without any modification. (Actually, pairs of RCS and
140 working files can be specified in three ways: (a) both are given, (b)
141 only the working file is given, (c) only the RCS file is given. Both
142 RCS and working files may have arbitrary path prefixes; RCS commands
143 pair them up intelligently.)
144 To avoid the deletion of the working file during check-in (in case you
146 want to continue editing or compiling), invoke
147 ci -l f.c or ci -u f.c
149 These commands check in f.c as usual, but perform an implicit check-
151 out. The first form also locks the checked in revision, the second one
152 doesn't. Thus, these options save you one check-out operation. The
153 first form is useful if you want to continue editing, the second one if
154 you just want to read the file. Both update the identification markers
155 in your working file (see below).
156 You can give ci the number you want assigned to a checked in revision.
158 Assume all your revisions were numbered 1.1, 1.2, 1.3, etc., and you
159 would like to start release 2. The command
160 ci -r2 f.c or ci -r2.1 f.c
162 assigns the number 2.1 to the new revision. From then on, ci will num‐
164 ber the subsequent revisions with 2.2, 2.3, etc. The corresponding co
165 commands
166 co -r2 f.c and co -r2.1 f.c
168 retrieve the latest revision numbered 2.x and the revision 2.1, respec‐
170 tively. co without a revision number selects the latest revision on
171 the trunk, i.e. the highest revision with a number consisting of two
172 fields. Numbers with more than two fields are needed for branches.
173 For example, to start a branch at revision 1.3, invoke
174 ci -r1.3.1 f.c
176 This command starts a branch numbered 1 at revision 1.3, and assigns
178 the number 1.3.1.1 to the new revision. For more information about
179 branches, see rcsfile(5).
180 Automatic Identification
182 RCS can put special strings for identification into your source and
183 object code. To obtain such identification, place the marker
184 $Id$
186 into your text, for instance inside a comment. RCS will replace this
188 marker with a string of the form
189 $Id: filename revision date time author state $
191 With such a marker on the first page of each module, you can always see
193 with which revision you are working. RCS keeps the markers up to date
194 automatically. To propagate the markers into your object code, simply
195 put them into literal character strings. In C, this is done as fol‐
196 lows:
197 static char rcsid[] = "$Id$";
199 The command ident extracts such markers from any file, even object code
201 and dumps. Thus, ident lets you find out which revisions of which mod‐
202 ules were used in a given program.
203 You may also find it useful to put the marker $Log$ into your text,
205 inside a comment. This marker accumulates the log messages that are
206 requested during check-in. Thus, you can maintain the complete history
207 of your file directly inside it. There are several additional identi‐
208 fication markers; see co(1) for details.
209
211 Author: Walter F. Tichy.
212 Manual Page Revision: 5.3; Release Date: 1993/11/03.
213 Copyright © 1982, 1988, 1989 Walter F. Tichy.
214 Copyright © 1990, 1991, 1992, 1993 Paul Eggert.
215
217 ci(1), co(1), ident(1), rcs(1), rcsdiff(1), rcsintro(1), rcsmerge(1),
218 rlog(1)
219 Walter F. Tichy, RCS--A System for Version Control, Software--Practice
220 & Experience 15, 7 (July 1985), 637-654.
221GNU 1993/11/03 RCSINTRO(1)