Commit | Line | Data |
---|---|---|
98fdbb40 C |
1 | This directory contains complete sources for RCS version 5.6. |
2 | ||
3 | RCS, the Revision Control System, manages multiple revisions of files. | |
4 | RCS can store, retrieve, log, identify, and merge revisions. | |
5 | It is useful for files that are revised frequently, | |
6 | e.g. programs, documentation, graphics, and papers. | |
7 | ||
8 | /* Copyright (C) 1982, 1988, 1989 Walter Tichy | |
9 | Copyright 1990, 1991 by Paul Eggert | |
10 | Distributed under license by the Free Software Foundation, Inc. | |
11 | ||
12 | This file is part of RCS. | |
13 | ||
14 | RCS is free software; you can redistribute it and/or modify | |
15 | it under the terms of the GNU General Public License as published by | |
16 | the Free Software Foundation; either version 2, or (at your option) | |
17 | any later version. | |
18 | ||
19 | RCS is distributed in the hope that it will be useful, | |
20 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
21 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
22 | GNU General Public License for more details. | |
23 | ||
24 | You should have received a copy of the GNU General Public License | |
25 | along with RCS; see the file COPYING. If not, write to | |
26 | the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. | |
27 | ||
28 | Report problems and direct all questions to: | |
29 | ||
30 | rcs-bugs@cs.purdue.edu | |
31 | ||
32 | */ | |
33 | ||
34 | $Id: README,v 5.16 1991/11/03 01:09:19 eggert Exp $ | |
35 | ||
36 | ||
37 | Installation notes: | |
38 | ||
39 | RCS requires a diff that supports the -n option. | |
40 | Get GNU diff (version 1.15 or later) if your diff lacks -n. | |
41 | ||
42 | RCS works best with a diff that supports -a and -L, | |
43 | and a diff3 that supports -E and -m. | |
44 | GNU diff supports these options. | |
45 | ||
46 | Sources for RCS are in the src directory. | |
47 | Read the directions in src/README to build RCS on your system. | |
48 | ||
49 | Manual entries reside in man. | |
50 | ||
51 | Troff source for the paper `RCS--A System for Version Control', which | |
52 | appeared in _Software--Practice & Experience_, is in rcs.ms. | |
53 | ||
54 | If you don't have troff, you can get GNU groff to format the documentation. | |
55 | ||
56 | ||
57 | RCS compatibility notes: | |
58 | ||
59 | RCS version 5 reads RCS files written by any RCS version released since 1982. | |
60 | It also writes RCS files that these older versions of RCS can read, | |
61 | unless you use one of the following new features: | |
62 | ||
63 | checkin times after 1999/12/31 23:59:59 GMT | |
64 | checking in non-text files | |
65 | non-Ascii symbolic names | |
66 | rcs -bX, where X is nonempty | |
67 | rcs -kX, where X is not `kv' | |
68 | RCS files that exceed hardcoded limits in older RCS versions | |
69 | ||
70 | A working file written by RCS 5.5 or later contains four-digit years in its | |
71 | keyword strings. If you check out a working file with RCS 5.5 or later, | |
72 | an older RCS version's `ci -k' may insist on two-digit years. | |
73 | Fix this with `co -V4', or by editing the working file. | |
74 | ||
75 | ||
76 | Features new to RCS version 5.6 include: | |
77 | ||
78 | Security holes have been plugged; setgid use is no longer supported. | |
79 | ||
80 | co can retrieve old revisions much more efficiently. | |
81 | To generate the Nth youngest revision on the trunk, | |
82 | the old method used up to N passes through copies of the working file; | |
83 | the new method uses a piece table to generate the working file in one pass. | |
84 | ||
85 | When ci finds no changes in the working file, | |
86 | it automatically reverts to the previous revision unless -f is given. | |
87 | ||
88 | RCS follows symbolic links to RCS files instead of breaking them, | |
89 | and warns when it breaks hard links to RCS files. | |
90 | ||
91 | `$' stands for the revision number taken from working file keyword strings. | |
92 | E.g. if F contains an Id keyword string, | |
93 | `rcsdiff -r$ F' compares F to its checked-in revision, and | |
94 | `rcs -nL:$ F' gives the symbolic name L to F's revision. | |
95 | ||
96 | co and ci's new -M option sets the modification time | |
97 | of the working file to be that of the revision. | |
98 | Without -M, ci now tries to avoid changing the working file's | |
99 | modification time if its contents are unchanged. | |
100 | ||
101 | rcs's new -m option changes the log message of an old revision. | |
102 | ||
103 | RCS is portable to hosts that do not permit `,' in filenames. | |
104 | (`,' is not part of the Posix portable filename character set.) | |
105 | A new -x option specifies extensions other than `,v' for RCS files. | |
106 | The Unix default is `-x,v/', so that the working file `w' corresponds | |
107 | to the first file in the list `RCS/w,v', `w,v', `RCS/w' that works. | |
108 | The non-Unix default is `-x', so that only `RCS/w' is tried. | |
109 | Eventually, the Unix default should change to `-x/,v' | |
110 | to encourage interoperability among all Posix hosts. | |
111 | ||
112 | A new RCSINIT environment variable specifies defaults for options like -x. | |
113 | ||
114 | The separator for revision ranges has been changed from `-' to `:', because | |
115 | the range `A-B' is ambiguous if `A', `B' and `A-B' are all symbolic names. | |
116 | E.g. the old `rlog -r1.5-1.7' is now `rlog -r1.5:1.7'; ditto for `rcs -o'. | |
117 | For a while RCS will still support (but warn about) the old `-' separator. | |
118 | ||
119 | RCS manipulates its lock files using a method that is more reliable under NFS. | |
120 | ||
121 | Experimental support for MS-DOS and OS/2 is available as part of a separate | |
122 | software distribution. | |
123 | ||
124 | ||
125 | Features new to RCS version 5 include: | |
126 | ||
127 | RCS can check in arbitrary files, not just text files, if diff -a works. | |
128 | RCS can merge lines containing just a single `.' if diff3 -m works. | |
129 | GNU diff supports the -a and -m options. | |
130 | ||
131 | RCS can now be used as a setuid program. | |
132 | See ci(1) for how users can employ setuid copies of ci, co, and rcsclean. | |
133 | Setuid privileges yield extra security if the effective user owns RCS files | |
134 | and directories, and if only the effective user can write RCS directories. | |
135 | RCS uses the real user for all accesses other than writing RCS directories. | |
136 | As described in ci(1), there are three levels of setuid support. | |
137 | ||
138 | 1. Setuid works fully if the seteuid() system call lets any | |
139 | process switch back and forth between real and effective users, | |
140 | as specified in Posix 1003.1a Draft 5. | |
141 | ||
142 | 2. On hosts with saved setuids (a Posix 1003.1-1990 option) and without | |
143 | a modern seteuid(), setuid works unless the real or effective user is root. | |
144 | ||
145 | 3. On hosts that lack both modern seteuid() and saved setuids, | |
146 | setuid does not work, and RCS uses the effective user for all accesses; | |
147 | formerly it was inconsistent. | |
148 | ||
149 | New options to co, rcsdiff, and rcsmerge give more flexibility to keyword | |
150 | substitution. | |
151 | ||
152 | -kkv substitutes the default `$Keyword: value $' for keyword strings. | |
153 | However, a locker's name is inserted only as a file is being locked, | |
154 | i.e. by `ci -l' and `co -l'. This is normally the default. | |
155 | ||
156 | -kkvl acts like -kkv, except that a locker's name is always inserted | |
157 | if the given revision is currently locked. This was the default in | |
158 | version 4. It is now the default only with when using rcsdiff to | |
159 | compare a revision to a working file whose mode is that of a file | |
160 | checked out for changes. | |
161 | ||
162 | -kk substitutes just `$Keyword$', which helps to ignore keyword values | |
163 | when comparing revisions. | |
164 | ||
165 | -ko retrieves the old revision's keyword string, thus bypassing keyword | |
166 | substitution. | |
167 | ||
168 | -kv retrieves just `value'. This can ease the use of keyword values, but | |
169 | it is dangerous because it causes RCS to lose track of where the keywords | |
170 | are, so for safety the owner write permission of the working file is | |
171 | turned off when -kv is used; to edit the file later, check it out again | |
172 | without -kv. | |
173 | ||
174 | rcs -ko sets the default keyword substitution to be in the style of co -ko, | |
175 | and similarly for the other -k options. This can be useful with binary file | |
176 | formats that cannot tolerate changing the lengths of keyword strings. | |
177 | However it also renders a RCS file readable only by RCS version 5 or later. | |
178 | Use rcs -kkv to restore the usual default substitution. | |
179 | ||
180 | RCS can now be used by development groups that span timezone boundaries. | |
181 | All times are now displayed in GMT, and GMT is the default timezone. | |
182 | To use local time with co -d, append ` LT' to the time. | |
183 | When interchanging RCS files with sites running older versions of RCS, | |
184 | time stamp discrepancies may prevent checkins; to work around this, | |
185 | use `ci -d' with a time slightly in the future. | |
186 | ||
187 | Dates are now displayed using four-digit years, not two-digit years. | |
188 | Years given in -d options must now have four digits. | |
189 | This change is required for RCS to continue to work after 1999/12/31. | |
190 | The form of dates in version 5 RCS files will not change until 2000/01/01, | |
191 | so in the meantime RCS files can still be interchanged with sites | |
192 | running older versions of RCS. To make room for the longer dates, | |
193 | rlog now outputs `lines: +A -D' instead of `lines added/del: A/D'. | |
194 | ||
195 | To help prevent diff programs that are broken or have run out of memory | |
196 | from trashing an RCS file, ci now checks diff output more carefully. | |
197 | ||
198 | ci -k now handles the Log keyword, so that checking in a file | |
199 | with -k does not normally alter the file's contents. | |
200 | ||
201 | RCS no longer outputs white space at the ends of lines | |
202 | unless the original working file had it. | |
203 | For consistency with other keywords, | |
204 | a space, not a tab, is now output after `$Log:'. | |
205 | Rlog now puts lockers and symbolic names on separate lines in the output | |
206 | to avoid generating lines that are too long. | |
207 | A similar fix has been made to lists in the RCS files themselves. | |
208 | ||
209 | RCS no longer outputs the string `Locker: ' when expanding Header or Id | |
210 | keywords. This saves space and reverts back to version 3 behavior. | |
211 | ||
212 | The default branch is not put into the RCS file unless it is nonempty. | |
213 | Therefore, files generated by RCS version 5 can be read by RCS version 3 | |
214 | unless they use the default branch feature introduced in version 4. | |
215 | This fixes a compatibility problem introduced by version 4. | |
216 | ||
217 | RCS can now emulate older versions of RCS; see `co -V'. | |
218 | This may be useful to overcome compatibility problems | |
219 | due to the above changes. | |
220 | ||
221 | Programs like Emacs can now interact with RCS commands via a pipe: | |
222 | the new -I option causes ci, co, and rcs to run interactively, | |
223 | even if standard input is not a terminal. | |
224 | These commands now accept multiple inputs from stdin separated by `.' lines. | |
225 | ||
226 | ci now silently ignores the -t option if the RCS file already exists. | |
227 | This simplifies some shell scripts and improves security in setuid sites. | |
228 | ||
229 | Descriptive text may be given directly in an argument of the form -t-string. | |
230 | ||
231 | The character set for symbolic names has been upgraded | |
232 | from Ascii to ISO 8859. | |
233 | ||
234 | rcsdiff now passes through all options used by GNU diff; | |
235 | this is a longer list than 4.3BSD diff. | |
236 | ||
237 | merge's new -L option gives tags for merge's overlap report lines. | |
238 | This ability used to be present in a different, undocumented form; | |
239 | the new form is chosen for compatibility with GNU diff3's -L option. | |
240 | ||
241 | rcsmerge and merge now have a -q option, just like their siblings do. | |
242 | ||
243 | RCS now attempts to ignore parts of an RCS file that look like they come | |
244 | from a future version of RCS. | |
245 | ||
246 | When properly configured, RCS now strictly conforms with Posix 1003.1-1990. | |
247 | RCS can still be compiled in non-Posix traditional Unix environments, | |
248 | and can use common BSD and USG extensions to Posix. | |
249 | RCS is a conforming Standard C program, and also compiles under traditional C. | |
250 | ||
251 | Arbitrary limits on internal table sizes have been removed. | |
252 | The only limit now is the amount of memory available via malloc(). | |
253 | ||
254 | File temporaries, lock files, signals, and system call return codes | |
255 | are now handled more cleanly, portably, and quickly. | |
256 | Some race conditions have been removed. | |
257 | ||
258 | A new compile-time option RCSPREFIX lets administrators avoid absolute path | |
259 | names for subsidiary programs, trading speed for flexibility. | |
260 | ||
261 | The configuration procedure is now more automatic. | |
262 | ||
263 | Snooping has been removed. | |
264 | ||
265 | ||
266 | Version 4 was the first version distributed by FSF. | |
267 | Beside bug fixes, features new to RCS version 4 include: | |
268 | ||
269 | The notion of default branch has been added; see rcs -b. | |
270 | ||
271 | ||
272 | Version 3 was included in the 4.3BSD distribution. | |
273 | ||
274 | ||
275 | Further projects: | |
276 | ||
277 | Add format options for finer control over the output of ident and rlog. | |
278 | ||
279 | Be able to redo the most recent checkin with minor changes. | |
280 | ||
281 | Add a `-' option to take the list of pathnames from standard input. | |
282 | Perhaps the pathnames should be null-terminated, not newline-terminated, | |
283 | so that pathnames that contain newlines are handled properly. | |
284 | ||
285 | Add general options so that rcsdiff and rcsmerge can pass arbitrary options | |
286 | to its subsidiary co and diff processes. E.g. | |
287 | ||
288 | -.OPTION to pass OPTION to the subsidiary `co' | |
289 | -/OPTION to pass OPTION to the subsidiary `diff' (for rcsdiff only) | |
290 | ||
291 | For example: | |
292 | ||
293 | rcsdiff -.-d"1991/02/09 18:09" -.-sRel -/+unified -/-C -/5 -/-d foo.c | |
294 | ||
295 | invokes `co -d"1991/02/09 18:09" -sRel ...' and `diff +unified -C 5 -d ...'. | |
296 | To pass an option to just one subsidiary `co', put the -. option | |
297 | after the corresponding -r option. For example: | |
298 | ||
299 | rcsmerge -r1.4 -.-ko -r1.8 -.-kkv foo.c | |
300 | ||
301 | passes `-ko' to the first subsidiary `co', and `-kkv' to the second one. | |
302 | ||
303 | ||
304 | Permit multiple option-pathname pairs, e.g. co -r1.4 a -r1.5 b. | |
305 | ||
306 | Add ways to specify the earliest revision, the most recent revision, | |
307 | the earliest or latest revision on a particular branch, and | |
308 | the parent or child of some other revision. | |
309 | ||
310 | If a user has multiple locks, perhaps ci should fall back on ci -k's | |
311 | method to figure out which revision to use. | |
312 | ||
313 | Symbolic names need not refer to existing branches and revisions. | |
314 | rcs(1)'s BUGS section says this is a bug. Is it? If so, it should be fixed. | |
315 | ||
316 | Write an rcsck program that repairs corrupted RCS files, | |
317 | much as fsck repairs corrupted file systems. | |
318 | ||
319 | Clean up the source code with a consistent indenting style. | |
320 | ||
321 | Update the date parser to use the more modern getdate.y by Bellovin, | |
322 | Salz, and Berets, or the even more modern getdate by Moraes. None of | |
323 | these getdate implementations are as robust as RCS's old warhorse in | |
324 | avoiding problems like arithmetic overflow, so they'll have to be | |
325 | fixed first. | |
326 | ||
327 | Break up the code into a library so that it's easier to write new programs | |
328 | that manipulate RCS files, and so that useless code is removed from the | |
329 | existing programs. For example, the rcs command contains unnecessary | |
330 | keyword substitution baggage, and the merge command can be greatly pruned. | |
331 | ||
332 | Make it easier to use your favorite text editor to edit log messages, | |
333 | etc. instead of having to type them in irretrievably at the terminal. | |
334 | ||
335 | The following projects require a change to RCS file format, | |
336 | and thus must wait until at least RCS version 6. | |
337 | ||
338 | Be able to store RCS files in compressed format. | |
339 | Don't bother to use a .Z extension that would exceed file name length limits; | |
340 | just look at the magic number. | |
341 | ||
342 | Add locker commentary, e.g. `co -l -m"checkout to fix merge bug" foo' | |
343 | to tell others why you checked out `foo'. | |
344 | Also record the time when the revision was locked, | |
345 | and perhaps the working pathname (if applicable). | |
346 | ||
347 | Let the user mark an RCS revision as deleted; checking out such a revision | |
348 | would result in no working file. Similarly, using `co -d' with a date either | |
349 | before the initial revision or after the file was marked deleted should | |
350 | remove the working file. For extra credit, extend the notion of `deleted' to | |
351 | include `renamed'. RCS should support arbitrary combinations of renaming and | |
352 | deletion, e.g. renaming A to B and B to A, checking in new revisions to both | |
353 | files, and then renaming them back. | |
354 | ||
355 | Use a better scheme for locking revisions; the current scheme requires | |
356 | changing the RCS file just to lock or unlock a revision. | |
357 | The new scheme should coexist as well as possible with older versions of RCS, | |
358 | and should avoid the rare NFS bugs mentioned in rcsedit.c. | |
359 | ||
360 | Add rcs options for changing keyword names, e.g. XConsortium instead of Id. | |
361 | ||
362 | Add frozen branches a la SCCS. In general, be able to emulate all of | |
363 | SCCS, so that an SCCS-to-RCS program can be practical. | |
364 | ||
365 | Add support for distributed RCS, where widely separated | |
366 | users cannot easily access each others' RCS files, | |
367 | and must periodically distribute and reconcile new revisions. | |
368 | ||
369 | Be able to create empty branches. | |
370 | ||
371 | Improve RCS's method for storing binary files. | |
372 | Although it is more efficient than SCCS's, | |
373 | the diff algorithm is still line oriented, | |
374 | and often generates long output for minor changes to an executable file. | |
375 | ||
376 | Add a new `-kb' expansion for binary files on non-Posix hosts | |
377 | that distinguish between text and binary I/O. | |
378 | The current `text_work_stdio' compile-time switch is too inflexible. | |
379 | This fix either requires nonstandard primitives like DOS's setmode(), | |
380 | or requires that `-kb' be specified on initial checkin and never changed. | |
381 | From the user's point of view, it would be best if | |
382 | RCS detected and handled binary files without human intervention, | |
383 | switching expansion methods as needed from revision to revision. | |
384 | ||
385 | Extend the grammar of RCS files so that keywords need not be in a fixed order. | |
386 | ||
387 | Internationalize messages; unfortunately, there's no common standard yet. | |
388 | This requires a change in RCS file format because of the | |
389 | `empty log message' and `checked in with -k' hacks inside RCS files. | |
390 | ||
391 | ||
392 | Credits: | |
393 | ||
394 | RCS was designed and built by Walter F. Tichy of Purdue University. | |
395 | RCS version 3 was released in 1983. | |
396 | ||
397 | Adam Hammer, Thomas Narten, and Dan Trinkle of Purdue supported RCS through | |
398 | version 4.3, released in 1990. Guy Harris of Sun contributed many porting | |
399 | fixes. Paul Eggert of System Development Corporation contributed bug fixes | |
400 | and tuneups. Jay Lepreau contributed 4.3BSD support. | |
401 | ||
402 | Paul Eggert of Twin Sun wrote the changes for RCS version 5, released in 1991. | |
403 | Rich Braun of Kronos and Andy Glew of Intel contributed ideas for new options. | |
404 | Bill Hahn of Stratus contributed ideas for setuid support. | |
405 | Ideas for piece tables came from Joe Berkovitz of Stratus and Walter F. Tichy. | |
406 | Matt Cross of Stratus contributed test case ideas. | |
407 | Adam Hammer of Purdue QAed. |