Penguin
Recent Changes
Annotated edit history of rcsintro(1) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 RCSINTRO
2 !!!RCSINTRO
3 NAME
4 DESCRIPTION
5 IDENTIFICATION
6 SEE ALSO
7 ----
8 !!NAME
9
10
11 rcsintro - introduction to RCS commands
12 !!DESCRIPTION
13
14
15 The Revision Control System ( RCS ) manages
16 multiple revisions of files. RCS automates
17 the storing, retrieval, logging, identification, and merging
18 of revisions. RCS is useful for text that is
19 revised frequently, for example programs, documentation,
20 graphics, papers, and form letters.
21
22
23 The basic user interface is extremely simple. The novice
24 only needs to learn two commands: ci(1) and
25 co(1). __ci__, short for ``check in'', deposits
26 the contents of a file into an archival file called an
27 RCS file. An RCS file contains
28 all revisions of a particular file. __co__, short for
29 ``check out'', retrieves revisions from an
30 RCS file.
31
32
33 __Functions of RCS__
34
35
36 Store and retrieve multiple revisions of text.
37 RCS saves all old revisions in a space
38 efficient way. Changes no longer destroy the original,
39 because the previous revisions remain accessible. Revisions
40 can be retrieved according to ranges of revision numbers,
41 symbolic names, dates, authors, and states.
42
43
44 Maintain a complete history of changes. RCS
45 logs all changes automatically. Besides the text of each
46 revision, RCS stores the author, the date and
47 time of check-in, and a log message summarizing the change.
48 The logging makes it easy to find out what happened to a
49 module, without having to compare source listings or having
50 to track down colleagues.
51
52
53 Resolve access conflicts. When two or more programmers wish
54 to modify the same revision, RCS alerts the
55 programmers and prevents one modification from corrupting
56 the other.
57
58
59 Maintain a tree of revisions. RCS can
60 maintain separate lines of development for each module. It
61 stores a tree structure that represents the ancestral
62 relationships among revisions.
63
64
65 Merge revisions and resolve conflicts. Two separate lines of
66 development of a module can be coalesced by merging. If the
67 revisions to be merged affect the same sections of code,
68 RCS alerts the user about the overlapping
69 changes.
70
71
72 Control releases and configurations. Revisions can be
73 assigned symbolic names and marked as released, stable,
74 experimental, etc. With these facilities, configurations of
75 modules can be described simply and directly.
76
77
78 Automatically identify each revision with name, revision
79 number, creation time, author, etc. The identification is
80 like a stamp that can be embedded at an appropriate place in
81 the text of a revision. The identification makes it simple
82 to determine which revisions of which modules make up a
83 given configuration.
84
85
86 Minimize secondary storage. RCS needs little
87 extra space for the revisions (only the differences). If
88 intermediate revisions are deleted, the corresponding deltas
89 are compressed accordingly.
90
91
92 __Getting Started with RCS__
93
94
95 Suppose you have a file __f.c__ that you wish to put
96 under control of RCS . If you have not
97 already done so, make an RCS directory with
98 the command
99
100
101 __mkdir RCS__
102
103
104 Then invoke the check-in command
105
106
107 __ci f.c__
108
109
110 This command creates an RCS file in the
111 __RCS__ directory, stores __f.c__ into it as revision
112 1.1, and deletes __f.c__. It also asks you for a
113 description. The description should be a synopsis of the
114 contents of the file. All later check-in commands will ask
115 you for a log entry, which should summarize the changes that
116 you made.
117
118
119 Files in the RCS directory are called
120 RCS files; the others are called working
121 files. To get back the working file __f.c__ in the
122 previous example, use the check-out command
123
124
125 __co f.c__
126
127
128 This command extracts the latest revision from the
129 RCS file and writes it into __f.c__. If
130 you want to edit __f.c__, you must lock it as you check
131 it out with the command
132
133
134 __co -l f.c__
135
136
137 You can now edit __f.c__.
138
139
140 Suppose after some editing you want to know what changes
141 that you have made. The command
142
143
144 __rcsdiff f.c__
145
146
147 tells you the difference between the most recently
148 checked-in version and the working file. You can check the
149 file back in by invoking
150
151
152 __ci f.c__
153
154
155 This increments the revision number properly.
156
157
158 If __ci__ complains with the message
159
160
161 __ci error: no lock set by__ ''your
162 name''
163
164
165 then you have tried to check in a file even though you did
166 not lock it when you checked it out. Of course, it is too
167 late now to do the check-out with locking, because another
168 check-out would overwrite your modifications. Instead,
169 invoke
170
171
172 __rcs -l f.c__
173
174
175 This command will lock the latest revision for you, unless
176 somebody else got ahead of you already. In this case, you'll
177 have to negotiate with that person.
178
179
180 Locking assures that you, and only you, can check in the
181 next update, and avoids nasty problems if several people
182 work on the same file. Even if a revision is locked, it can
183 still be checked out for reading, compiling, etc. All that
184 locking prevents is a ''check-in'' by anybody but the
185 locker.
186
187
188 If your RCS file is private, i.e., if you are
189 the only person who is going to deposit revisions into it,
190 strict locking is not needed and you can turn it off. If
191 strict locking is turned off, the owner of the
192 RCS file need not have a lock for check-in;
193 all others still do. Turning strict locking off and on is
194 done with the commands
195
196
197 __rcs -U f.c__ and __rcs -L f.c__
198
199
200 If you don't want to clutter your working directory with
201 RCS files, create a subdirectory called
202 __RCS__ in your working directory, and move all your
203 RCS files there. RCS commands
204 will look first into that directory to find needed files.
205 All the commands discussed above will still work, without
206 any modification. (Actually, pairs of RCS and
207 working files can be specified in three ways: (a) both are
208 given, (b) only the working file is given, (c) only the
209 RCS file is given. Both RCS
210 and working files may have arbitrary path prefixes;
211 RCS commands pair them up
212 intelligently.)
213
214
215 To avoid the deletion of the working file during check-in
216 (in case you want to continue editing or compiling),
217 invoke
218
219
220 __ci -l f.c__ or __ci -u f.c__
221
222
223 These commands check in __f.c__ as usual, but perform an
224 implicit check-out. The first form also locks the checked in
225 revision, the second one doesn't. Thus, these options save
226 you one check-out operation. The first form is useful if you
227 want to continue editing, the second one if you just want to
228 read the file. Both update the identification markers in
229 your working file (see below).
230
231
232 You can give __ci__ the number you want assigned to a
233 checked in revision. Assume all your revisions were numbered
234 1.1, 1.2, 1.3, etc., and you would like to start release 2.
235 The command
236
237
238 __ci -r2 f.c__ or __ci -r2.1 f.c__
239
240
241 assigns the number 2.1 to the new revision. From then on,
242 __ci__ will number the subsequent revisions with 2.2,
243 2.3, etc. The corresponding __co__ commands
244
245
246 __co -r2 f.c__ and __co -r2.1 f.c__
247
248
249 retrieve the latest revision numbered 2.''x'' and the
250 revision 2.1, respectively. __co__ without a revision
251 number selects the latest revision on the ''trunk'', i.e.
252 the highest revision with a number consisting of two fields.
253 Numbers with more than two fields are needed for branches.
254 For example, to start a branch at revision 1.3,
255 invoke
256
257
258 __ci -r1.3.1 f.c__
259
260
261 This command starts a branch numbered 1 at revision 1.3, and
262 assigns the number 1.3.1.1 to the new revision. For more
263 information about branches, see
264 rcsfile(5).
265
266
267 __Automatic Identification__
268
269
270 RCS can put special strings for
271 identification into your source and object code. To obtain
272 such identification, place the marker
273
274
275 __$Id$__
276
277
278 into your text, for instance inside a comment.
279 RCS will replace this marker with a string of
280 the form
281
282
283 __$Id:__ ''filename revision date time author state''
284 __$__
285
286
287 With such a marker on the first page of each module, you can
288 always see with which revision you are working.
289 RCS keeps the markers up to date
290 automatically. To propagate the markers into your object
291 code, simply put them into literal character strings. In C,
292 this is done as follows:
293
294
295 __static char rcsid[[] = __
296
297
298 The command __ident__ extracts such markers from any
299 file, even object code and dumps. Thus, __ident__ lets
300 you find out which revisions of which modules were used in a
301 given program.
302
303
304 You may also find it useful to put the marker __$Log$__
305 into your text, inside a comment. This marker accumulates
306 the log messages that are requested during check-in. Thus,
307 you can maintain the complete history of your file directly
308 inside it. There are several additional identification
309 markers; see co(1) for details.
310 !!IDENTIFICATION
311
312
313 Author: Walter F. Tichy.
314 Manual Page Revision: 5.3; Release Date: 1993/11/03.
315 Copyright 1982, 1988, 1989 Walter F. Tichy.
316 Copyright 1990, 1991, 1992, 1993 Paul Eggert.
317 !!SEE ALSO
318
319
320 ci(1), co(1), ident(1), rcs(1), rcsdiff(1), rcsintro(1),
321 rcsmerge(1), rlog(1)
322 Walter F. Tichy, RCS --A System for Version
323 Control, ''Software--Practice ''
324 __15__, 7 (July 1985), 637-654.
325 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.