1RCSINTRO(1L)                                                      RCSINTRO(1L)
2
3
4

NAME

6       rcsintro - introduction to RCS commands
7

DESCRIPTION

9       The  Revision  Control  System (RCS) manages multiple revisions of text
10       files.  RCS automates the storing, retrieval, logging,  identification,
11       and  merging  of revisions. RCS is useful for text that is revised fre‐
12       quently, for example programs, documentation,  graphics,  papers,  form
13       letters, etc.
14
15       The  basic user interface is extremely simple. The novice only needs to
16       learn two commands: ci(1L) and  co(1L).   Ci,  short  for  "check  in",
17       deposits  the  contents  of a text file into an archival file called an
18       RCS file. An RCS file contains all revisions of a particular text file.
19       Co, short for "check out", retrieves revisions from an RCS file.
20
21       Functions of RCS
22
23       ·      Storage  and  retrieval of multiple revisions of text. RCS saves
24              all old revisions in a space efficient way.  Changes  no  longer
25              destroy  the  original,  because  the  previous revisions remain
26              accessible. Revisions can be retrieved according  to  ranges  of
27              revision numbers, symbolic names, dates, authors, and states.
28
29       ·      Maintenance  of  a  complete  history  of  changes. RCS logs all
30              changes automatically.  Besides the text of each  revision,  RCS
31              stores the author, the date and time of check-in, and a log mes‐
32              sage summarizing the change.  The logging makes it easy to  find
33              out  what happened to a module, without having to compare source
34              listings or having to track down colleagues.
35
36       ·      Resolution of access conflicts. When  two  or  more  programmers
37              wish to modify the same revision, RCS alerts the programmers and
38              prevents one modification from corrupting the other.
39
40       ·      Maintenance of a tree of Revisions. RCS  can  maintain  separate
41              lines of development for each module. It stores a tree structure
42              that represents the ancestral relationships among revisions.
43
44       ·      Merging of revisions and resolution of conflicts.  Two  separate
45              lines  of  development  of a module can be coalesced by merging.
46              If the revisions to be merged affect the same sections of  code,
47              RCS alerts the user about the overlapping changes.
48
49       ·      Release  and  configuration  control.  Revisions can be assigned
50              symbolic names and marked  as  released,  stable,  experimental,
51              etc.   With  these  facilities, configurations of modules can be
52              described simply and directly.
53
54       ·      Automatic identification of each revision  with  name,  revision
55              number,  creation time, author, etc.  The identification is like
56              a stamp that can be embedded at an appropriate place in the text
57              of  a revision.  The identification makes it simple to determine
58              which revisions of which modules make up a given configuration.
59
60       ·      Minimization of secondary storage. RCS needs little extra  space
61              for  the revisions (only the differences). If intermediate revi‐
62              sions are  deleted,  the  corresponding  deltas  are  compressed
63              accordingly.
64
65
66       Getting Started with RCS
67
68       Suppose  you have a file f.c that you wish to put under control of RCS.
69       Invoke the check-in command
70
71               ci  f.c
72
73       This command creates the RCS file f.c,v, stores f.c into it as revision
74       1.1, and deletes f.c.  It also asks you for a description. The descrip‐
75       tion should be a synopsis of the contents of the file. All later check-
76       in  commands  will  ask you for a log entry, which should summarize the
77       changes that you made.
78
79       Files ending in ,v are called RCS files (`v'  stands  for  `versions'),
80       the  others are called working files.  To get back the working file f.c
81       in the previous example, use the check-out command
82
83               co  f.c
84
85       This command extracts the latest revision from f.c,v and writes it into
86       f.c. You can now edit f.c and check it back in by invoking
87
88               ci  f.c
89
90       Ci  increments  the revision number properly.  If ci complains with the
91       message
92
93                 ci error: no lock set by <your login>
94
95       then your system administrator has decided to create all RCS files with
96       the  locking  attribute  set to `strict'. In this case, you should have
97       locked the revision during the previous check-out. Your last  check-out
98       should have been
99
100               co  -l  f.c
101
102       Of course, it is too late now to do the check-out with locking, because
103       you probably modified f.c already, and a second check-out  would  over‐
104       write your modifications. Instead, invoke
105
106               rcs  -l  f.c
107
108       This  command  will  lock  the latest revision for you, unless somebody
109       else got ahead of you already. In this case, you'll have  to  negotiate
110       with that person.
111
112       Locking  assures  that you, and only you, can check in the next update,
113       and avoids nasty problems if several people  work  on  the  same  file.
114       Even  if a revision is locked, it can still be checked out for reading,
115       compiling, etc. All that locking prevents is a CHECK-IN by anybody  but
116       the locker.
117
118       If  your  RCS  file is private, i.e., if you are the only person who is
119       going to deposit revisions into it, strict locking is  not  needed  and
120       you can turn it off.  If strict locking is turned off, the owner of the
121       RCS file need not have a lock for check-in; all others still do.  Turn‐
122       ing strict locking off and on is done with the commands
123
124               rcs  -U  f.c     and     rcs  -L  f.c
125
126       If  you  don't  want  to clutter your working directory with RCS files,
127       create a subdirectory called RCS in your working  directory,  and  move
128       all your RCS files there. RCS commands will look first into that direc‐
129       tory to find needed files. All the commands discussed above will  still
130       work,  without  any  modification.  (Actually, pairs of RCS and working
131       files can be specified in 3 ways: (a) both  are  given,  (b)  only  the
132       working  file  is  given,  (c) only the RCS file is given. Both RCS and
133       working files may have arbitrary path prefixes; RCS commands pair  them
134       up intelligently).
135
136       To  avoid the deletion of the working file during check-in (in case you
137       want to continue editing), invoke
138
139               ci  -l  f.c     or     ci  -u  f.c
140
141       These commands check in f.c as usual, but perform  an  implicit  check-
142       out.  The first form also locks the checked in revision, the second one
143       doesn't. Thus, these options save you  one  check-out  operation.   The
144       first  form  is  useful  if  locking  is  strict, the second one if not
145       strict.  Both update the identification markers in  your  working  file
146       (see below).
147
148       You  can give ci the number you want assigned to a checked in revision.
149       Assume all your revisions were numbered 1.1, 1.2, 1.3,  etc.,  and  you
150       would like to start release 2.  The command
151
152               ci  -r2  f.c     or     ci  -r2.1  f.c
153
154       assigns the number 2.1 to the new revision.  From then on, ci will num‐
155       ber the subsequent revisions with 2.2, 2.3, etc. The  corresponding  co
156       commands
157
158               co  -r2  f.c     and     co  -r2.1  f.c
159
160       retrieve the latest revision numbered 2.x and the revision 2.1, respec‐
161       tively. Co without a revision number selects the latest revision on the
162       "trunk",  i.e.,  the  highest  revision  with  a number consisting of 2
163       fields. Numbers with more than 2 fields are needed for  branches.   For
164       example, to start a branch at revision 1.3, invoke
165
166               ci  -r1.3.1  f.c
167
168       This  command  starts  a branch numbered 1 at revision 1.3, and assigns
169       the number 1.3.1.1 to the new  revision.  For  more  information  about
170       branches, see rcsfile(5L).
171
172
173       Automatic Identification
174
175       RCS  can  put  special  strings for identification into your source and
176       object code. To obtain such identification, place the marker
177
178               $Header$
179
180       into your text, for instance inside a comment.  RCS will  replace  this
181       marker with a string of the form
182
183               $Header:   filename  revision_number  date  time  author  state
184       $
185
186       With such a marker on the first page of each module, you can always see
187       with  which revision you are working.  RCS keeps the markers up to date
188       automatically.  To propagate the markers into your object code,  simply
189       put them into literal character strings. In C, this is done as follows:
190
191               static char rcsid[] = "$Header$";
192
193       The command ident extracts such markers from any file, even object code
194       and dumps.  Thus, ident lets you find out which revisions of which mod‐
195       ules were used in a given program.
196
197       You  may  also  find  it useful to put the marker $Log$ into your text,
198       inside a comment. This marker accumulates the  log  messages  that  are
199       requested during check-in.  Thus, you can maintain the complete history
200       of your file directly inside it.  There are several additional  identi‐
201       fication markers; see co(1L) for details.
202

IDENTIFICATION

204       Author: Walter F. Tichy, Purdue University, West Lafayette, IN, 47907.
205       Revision Number: 1.2 ; Release Date: 87/02/27 .
206       Copyright © 1982 by Walter F. Tichy.
207

SEE ALSO

209       ci(1L),    co(1L),    ident(1L),   merge(1L),   rcs(1L),   rcsdiff(1L),
210       rcsmerge(1L), rlog(1L)
211       Walter F. Tichy, "Design, Implementation, and Evaluation of a  Revision
212       Control  System," in Proceedings of the 6th International Conference on
213       Software Engineering, IEEE, Tokyo, Sept. 1982.
214
215
216
217Purdue University                May 11, 1983                     RCSINTRO(1L)
Impressum