![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to rcsintro.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / rcs / man|
Return to rcsintro.1 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / rcs / man |
1.1 ! root 1: .TH RCSINTRO 1L "May 11, 1983" "Purdue University" ! 2: .SH NAME ! 3: rcsintro - introduction to RCS commands ! 4: .SH DESCRIPTION ! 5: The Revision Control System (RCS) manages multiple revisions of text files. ! 6: RCS automates the storing, retrieval, logging, identification, and merging ! 7: of revisions. RCS is useful for text that is revised frequently, for example ! 8: programs, documentation, graphics, papers, form letters, etc. ! 9: .PP ! 10: The basic user interface is extremely simple. The novice only needs ! 11: to learn two commands: ! 12: .IR ci (1L) ! 13: and ! 14: .IR co (1L). ! 15: \fICi\fR, short for "check in", deposits the contents of a ! 16: text file into an archival file called an RCS file. An RCS file ! 17: contains all revisions of a particular text file. ! 18: \fICo\fR, short for "check out", retrieves revisions from an RCS file. ! 19: .PP ! 20: .B "Functions of RCS" ! 21: .PP ! 22: .IP \(bu ! 23: Storage and retrieval of multiple revisions of text. RCS saves all old ! 24: revisions in a space efficient way. ! 25: Changes no longer destroy the original, because the ! 26: previous revisions remain accessible. Revisions can be retrieved according to ! 27: ranges of revision numbers, symbolic names, dates, authors, and ! 28: states. ! 29: .IP \(bu ! 30: Maintenance of a complete history of changes. RCS logs all changes automatically. ! 31: Besides the text of each revision, RCS stores the author, the date and time of ! 32: check-in, and a log message summarizing the change. ! 33: The logging makes it easy to find out ! 34: what happened to a module, without having to compare ! 35: source listings or having to track down colleagues. ! 36: .IP \(bu ! 37: Resolution of access conflicts. When two or more programmers wish to ! 38: modify the same revision, RCS alerts the programmers and prevents one ! 39: modification from corrupting the other. ! 40: .IP \(bu ! 41: Maintenance of a tree of Revisions. RCS can maintain separate lines of development ! 42: for each module. It stores a tree structure that represents the ! 43: ancestral relationships among revisions. ! 44: .IP \(bu ! 45: Merging of revisions and resolution of conflicts. ! 46: Two separate lines of development of a module can be coalesced by merging. ! 47: If the revisions to be merged affect the same sections of code, RCS alerts the ! 48: user about the overlapping changes. ! 49: .IP \(bu ! 50: Release and configuration control. Revisions can be assigned symbolic names ! 51: and marked as released, stable, experimental, etc. ! 52: With these facilities, configurations of modules can be ! 53: described simply and directly. ! 54: .IP \(bu ! 55: Automatic identification of each revision with name, revision number, ! 56: creation time, author, etc. ! 57: The identification is like a stamp that can be embedded at an appropriate place ! 58: in the text of a revision. ! 59: The identification makes it simple to determine which ! 60: revisions of which modules make up a given configuration. ! 61: .IP \(bu ! 62: Minimization of secondary storage. RCS needs little extra space for ! 63: the revisions (only the differences). If intermediate revisions are ! 64: deleted, the corresponding deltas are compressed accordingly. ! 65: .sp ! 66: .PP ! 67: .B "Getting Started with RCS" ! 68: .PP ! 69: Suppose you have a file f.c that you wish to put under control of RCS. ! 70: Invoke the check-in command ! 71: .PP ! 72: .ti 1.5i ! 73: .B "ci f.c ! 74: .PP ! 75: This command creates the RCS file f.c,v, stores f.c into it as revision 1.1, and ! 76: deletes f.c. It also asks you for a description. The description ! 77: should be a synopsis of the contents of the file. All later check-in ! 78: commands will ask you for a log entry, which should summarize the ! 79: changes that you made. ! 80: .PP ! 81: Files ending in ,v are called RCS files (`v' stands for `versions'), ! 82: the others are called working files. ! 83: To get back the working file f.c in the previous example, use the check-out ! 84: command ! 85: .PP ! 86: .ti 1.5i ! 87: .B "co f.c ! 88: .PP ! 89: This command extracts the latest revision from f.c,v and writes ! 90: it into f.c. You can now edit f.c and check it back in by invoking ! 91: .PP ! 92: .ti 1.5i ! 93: .B "ci f.c ! 94: .PP ! 95: \fICi\fR increments the revision number properly. ! 96: If \fIci\fR complains with the message ! 97: .PP ! 98: ci error: no lock set by <your login> ! 99: .PP ! 100: then your system administrator has decided to create all RCS files ! 101: with the locking attribute set to `strict'. In this case, you should ! 102: have locked the revision during the previous check-out. Your last check-out ! 103: should have been ! 104: .PP ! 105: .ti 1.5i ! 106: .B "co \-l f.c ! 107: .PP ! 108: Of course, it is too late now to do the check-out with locking, because you ! 109: probably modified f.c already, and a second check-out would ! 110: overwrite your modifications. Instead, invoke ! 111: .PP ! 112: .ti 1.5i ! 113: .B "rcs \-l f.c ! 114: .PP ! 115: This command will lock the latest revision for you, unless somebody ! 116: else got ahead of you already. In this case, you'll have to negotiate with ! 117: that person. ! 118: .PP ! 119: Locking assures that you, and only you, can check in the next update, and ! 120: avoids nasty problems if several people work on the same file. ! 121: Even if a revision is locked, it can still be checked out for ! 122: reading, compiling, etc. All that locking ! 123: prevents is a CHECK-IN by anybody but the locker. ! 124: .PP ! 125: If your RCS file is private, i.e., if you are the only person who is going ! 126: to deposit revisions into it, strict locking is not needed and you ! 127: can turn it off. ! 128: If strict locking is turned off, ! 129: the owner of the RCS file need not have a lock for check-in; all others ! 130: still do. Turning strict locking off and on is done with the commands ! 131: .PP ! 132: .ti 1.5i ! 133: .BR "rcs \-U f.c" " and " "rcs \-L f.c" ! 134: .PP ! 135: If you don't want to clutter your working directory with RCS files, create ! 136: a subdirectory called RCS in your working directory, and move all your RCS ! 137: files there. RCS commands will look first into that directory to find ! 138: needed files. All the commands discussed above will still work, without any ! 139: modification. ! 140: (Actually, pairs of RCS and working files can be specified in 3 ways: ! 141: (a) both are given, (b) only the working file is given, (c) only the ! 142: RCS file is given. Both RCS and working files may have arbitrary path prefixes; ! 143: RCS commands pair them up intelligently). ! 144: .PP ! 145: To avoid the deletion of the working file during check-in (in case you want to ! 146: continue editing), invoke ! 147: .PP ! 148: .ti 1.5i ! 149: .BR "ci \-l f.c" " or " "ci \-u f.c" ! 150: .PP ! 151: These commands check in f.c as usual, but perform an implicit ! 152: check-out. The first form also locks the checked in revision, the second one ! 153: doesn't. Thus, these options save you one check-out operation. ! 154: The first form is useful if locking is strict, the second one if not strict. ! 155: Both update the identification markers in your working file (see below). ! 156: .PP ! 157: You can give \fIci\fR the number you want assigned to a checked in ! 158: revision. Assume all your revisions were numbered 1.1, 1.2, 1.3, etc., ! 159: and you would like to start release 2. ! 160: The command ! 161: .PP ! 162: .ti 1.5i ! 163: .BR "ci \-r2 f.c" " or " "ci \-r2.1 f.c" ! 164: .PP ! 165: assigns the number 2.1 to the new revision. ! 166: From then on, \fIci\fR will number the subsequent revisions ! 167: with 2.2, 2.3, etc. The corresponding \fIco\fR commands ! 168: .PP ! 169: .ti 1.5i ! 170: .BR "co \-r2 f.c" " and " "co \-r2.1 f.c" ! 171: .PP ! 172: retrieve the latest revision numbered 2.x and the revision 2.1, ! 173: respectively. \fICo\fR without a revision number selects ! 174: the latest revision on the "trunk", i.e., the highest ! 175: revision with a number consisting of 2 fields. Numbers with more than 2 ! 176: fields are needed for branches. ! 177: For example, to start a branch at revision 1.3, invoke ! 178: .PP ! 179: .ti 1.5i ! 180: .B "ci \-r1.3.1 f.c ! 181: .PP ! 182: This command starts a branch numbered 1 at revision 1.3, and assigns ! 183: the number 1.3.1.1 to the new revision. For more information about ! 184: branches, see \fIrcsfile\fR(5L). ! 185: .sp ! 186: .PP ! 187: .B "Automatic Identification" ! 188: .PP ! 189: RCS can put special strings for identification into your source and object ! 190: code. To obtain such identification, place the marker ! 191: .PP ! 192: .ti 1.5i ! 193: $\&Header$ ! 194: .PP ! 195: into your text, for instance inside a comment. ! 196: RCS will replace this marker with a string of the form ! 197: .PP ! 198: .ti 1.5i ! 199: $\&Header: filename revision_number date time author state $ ! 200: .PP ! 201: With such a marker on the first page of each module, you can ! 202: always see with which revision you are working. ! 203: RCS keeps the markers up to date automatically. ! 204: To propagate the markers into your object code, simply put ! 205: them into literal character strings. In C, this is done as follows: ! 206: .PP ! 207: .ti 1.5i ! 208: static char rcsid[] = "$\&Header$"; ! 209: .PP ! 210: The command \fIident\fR extracts such markers from any file, even object code ! 211: and dumps. ! 212: Thus, \fIident\fR lets you find out ! 213: which revisions of which modules were used in a given program. ! 214: .PP ! 215: You may also find it useful to put the marker $\&Log$ ! 216: into your text, inside a comment. This marker accumulates ! 217: the log messages that are requested during check-in. ! 218: Thus, you can maintain the complete history of your file directly inside it. ! 219: There are several additional identification markers; see \fIco\fR(1L) for ! 220: details. ! 221: .SH IDENTIFICATION ! 222: .de VL ! 223: \\$2 ! 224: .. ! 225: Author: Walter F. Tichy, ! 226: Purdue University, West Lafayette, IN, 47907. ! 227: .br ! 228: Revision Number: ! 229: .VL $Revision: 1.2 $ ! 230: ; Release Date: ! 231: .VL $Date: 89/05/02 11:17:54 $ ! 232: \&. ! 233: .br ! 234: Copyright \(co 1982, 1988, 1989 by Walter F. Tichy. ! 235: .SH SEE ALSO ! 236: ci(1L), co(1L), ident(1L), merge(1L), rcs(1L), rcsdiff(1L), rcsmerge(1L), rlog(1L), ! 237: rcsfile(5L), ! 238: .br ! 239: Walter F. Tichy, "Design, Implementation, and Evaluation of a Revision Control ! 240: System," in \fIProceedings of the 6th International Conference on Software ! 241: Engineering\fR, IEEE, Tokyo, Sept. 1982.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.