Return to rcs.ms CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps1 / 13.rcs

Annotation of 43BSDReno/share/doc/ps1/13.rcs/rcs.ms, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1986 Regents of the University of California.
        !             2: .\" All rights reserved.  The Berkeley software License Agreement
        !             3: .\" specifies the terms and conditions for redistribution.
        !             4: .\"
        !             5: .\"    @(#)rcs.ms      6.1 (Berkeley) 5/7/86
        !             6: .\"
        !             7: .OH 'Introduction to RCS''PS1:13-%'
        !             8: .EH 'PS1:13-%''Introduction to RCS'
        !             9: .TL
        !            10: An Introduction to the Revision Control System
        !            11: .AU
        !            12: Walter F. Tichy
        !            13: .AI
        !            14: Department of Computer Sciences
        !            15: Purdue University
        !            16: West Lafayette, IN 47907
        !            17: .AB
        !            18: The Revision Control System (RCS) manages software libraries.
        !            19: It greatly increases programmer productivity
        !            20: by centralizing and cataloging changes to a software project.
        !            21: This document describes the benefits of using a source code control system.
        !            22: It then gives a tutorial introduction to the use of RCS.
        !            23: .AE
        !            24: .SH
        !            25: Functions of RCS
        !            26: .PP
        !            27: The Revision Control System (RCS) manages multiple revisions of text files.
        !            28: RCS automates the storing, retrieval, logging, identification, and merging
        !            29: of revisions. RCS is useful for text that is revised frequently, for example
        !            30: programs, documentation, graphics, papers, form letters, etc.
        !            31: It greatly increases programmer productivity
        !            32: by providing the following functions.
        !            33: .IP 1.
        !            34: RCS stores and retrieves multiple revisions of program and other text.
        !            35: Thus, one can maintain one or more releases while developing the next
        !            36: release, with a minimum of space overhead. Changes no longer destroy the
        !            37: original -- previous revisions remain accessible.
        !            38: .RS
        !            39: .IP a.
        !            40: Maintains each module as a tree of revisions.
        !            41: .IP b.
        !            42: Project libraries can
        !            43: be organized centrally, decentralized, or any way you like.
        !            44: .IP c.
        !            45: RCS works for any type of text: programs, documentation, memos, papers,
        !            46: graphics, VLSI layouts, form letters, etc.
        !            47: .RE
        !            48: .IP 2.
        !            49: RCS maintains a complete history of changes.
        !            50: Thus, one can find out what happened to a module easily
        !            51: and quickly, without having to compare source listings or
        !            52: having to track down colleagues.
        !            53: .RS
        !            54: .IP a.
        !            55: RCS performs automatic record keeping.
        !            56: .IP b.
        !            57: RCS logs all changes automatically.
        !            58: .IP c.
        !            59: RCS guarantees project continuity.
        !            60: .RE
        !            61: .IP 3.
        !            62: RCS manages multiple lines of development.
        !            63: .IP 4.
        !            64: RCS can merge multiple lines of development.
        !            65: Thus, when several parallel lines of development must be consolidated
        !            66: into one line, the merging of changes is automatic.
        !            67: .IP 5.
        !            68: RCS flags coding conflicts.
        !            69: If two or more lines of development modify the same section of code,
        !            70: RCS can alert programmers about overlapping changes.
        !            71: .IP 6.
        !            72: RCS resolves access conflicts.
        !            73: When two or more programmers wish to modify the same revision,
        !            74: RCS alerts the programmers and makes sure that one change will not wipe
        !            75: out the other one.
        !            76: .IP 7.
        !            77: RCS provides high-level retrieval functions.
        !            78: Revisions can be retrieved according to ranges of revision numbers,
        !            79: symbolic names, dates, authors, and states.
        !            80: .IP 8.
        !            81: RCS provides release and configuration control.
        !            82: Revisions can be marked as released, stable, experimental, etc.
        !            83: Configurations of modules can be described simply and directly.
        !            84: .IP 9.
        !            85: RCS performs automatic identification of modules with name, revision
        !            86: number, creation time, author, etc.
        !            87: Thus, it is always possible to determine which revisions of which
        !            88: modules make up a given configuration.
        !            89: .IP 10.
        !            90: Provides high-level management visibility.
        !            91: Thus, it is easy to track the status of a software project.
        !            92: .RS
        !            93: .IP a.
        !            94: RCS provides a complete change history.
        !            95: .IP b.
        !            96: RCS records who did what when to which revision of which module.
        !            97: .RE
        !            98: .IP 11.
        !            99: RCS is fully compatible with existing software development tools.
        !           100: RCS is unobtrusive -- its interface to the file system is such that
        !           101: all your existing software tools can be used as before.
        !           102: .IP 12.
        !           103: RCS' basic user interface is extremely simple. The novice only
        !           104: needs to learn two commands. Its more sophisticated features have been
        !           105: tuned towards advanced software development environments and the
        !           106: experienced software professional.
        !           107: .IP 13.
        !           108: RCS simplifies software distribution if customers
        !           109: also maintain sources with RCS. This technique assures proper
        !           110: identification of versions and configurations, and tracking of customer
        !           111: changes. Customer changes can be merged into distributed
        !           112: versions locally or by the development group.
        !           113: .IP 14.
        !           114: RCS needs little extra space for the revisions (only the differences).
        !           115: If intermediate revisions are deleted, the corresponding
        !           116: differences are compressed into the shortest possible form.
        !           117: .SH
        !           118: Getting Started with RCS
        !           119: .PP
        !           120: Suppose you have a file f.c that you wish to put under control of RCS. 
        !           121: Invoke the checkin command:
        !           122: .DS
        !           123: ci  f.c 
        !           124: .DE
        !           125: This command creates f.c,v, stores f.c into it as revision 1.1, and
        !           126: deletes f.c.
        !           127: It also asks you for a description. The description should be
        !           128: a synopsis of the contents of the file.
        !           129: All later checkin commands will ask you for a log entry,
        !           130: which should summarize the changes that you made.
        !           131: .PP
        !           132: Files ending in ,v are called RCS files ("v" stands for "versions"),
        !           133: the others are called working files.
        !           134: To get back the working file f.c in the previous example, use the checkout
        !           135: command:
        !           136: .DS
        !           137: co  f.c
        !           138: .DE
        !           139: This command extracts the latest revision from f.c,v and writes
        !           140: it into f.c.
        !           141: You can now edit f.c and check it in back in by invoking:
        !           142: .DS
        !           143: ci  f.c
        !           144: .DE
        !           145: \fICi\fR increments the revision number properly. 
        !           146: If \fIci\fR complains with the message
        !           147: .DS
        !           148:         ci error: no lock set by <your login>
        !           149: .DE
        !           150: then your system administrator has decided to create all RCS files
        !           151: with the locking attribute set to ``strict''.
        !           152: With strict locking, you you must lock the revision during
        !           153: the previous checkout. 
        !           154: Thus, your last checkout should have been
        !           155: .DS
        !           156: co  -l  f.c
        !           157: .DE
        !           158: Locking assures that you, and only you, can check in the next update, and
        !           159: avoids nasty problems if several people work on the same file.
        !           160: Of course, it is too late now to do the checkout with locking, because you
        !           161: probably modified f.c already, and a second checkout would
        !           162: overwrite your changes. Instead, invoke
        !           163: .DS
        !           164: rcs  -l  f.c
        !           165: .DE
        !           166: This command will lock the latest revision for you, unless somebody
        !           167: else got ahead of you already.
        !           168: If someone else has the lock you will have to negotiate your changes
        !           169: with them.
        !           170: .PP
        !           171: If your RCS file is private, i.e., if you are the only person who is going
        !           172: to deposit revisions into it, strict locking is not needed and you
        !           173: can turn it off.
        !           174: If strict locking is turned off,
        !           175: the owner off the RCS file need not have a lock for checkin; all others
        !           176: still do. Turning strict locking off and on is done with the commands:
        !           177: .DS
        !           178: rcs  -U  f.c       and         rcs  -L  f.c
        !           179: .DE
        !           180: You can set the locking to strict or non-strict on every RCS file.
        !           181: .PP
        !           182: If you do not want to clutter your working directory with RCS files, create 
        !           183: a subdirectory called RCS in your working directory, and move all your RCS 
        !           184: files there. RCS commands will look first into that directory to find 
        !           185: needed files. All the commands discussed above will still work, without any 
        !           186: change*. 
        !           187: .FS
        !           188: * Pairs of RCS and working files can really be specified in 3 ways: 
        !           189: a) both are given, b) only the working file is given, c) only the
        !           190: RCS file is given. Both files may have arbitrary path prefixes;
        !           191: RCS commands pair them up intelligently.
        !           192: .FE
        !           193: .PP
        !           194: To avoid the deletion of the working file during checkin (should you want to
        !           195: continue editing), invoke
        !           196: .DS
        !           197: ci  -l  f.c
        !           198: .DE
        !           199: This command checks in f.c as usual, but performs an additional
        !           200: checkout with locking.
        !           201: Thus, it saves you one checkout operation.
        !           202: There is also an option
        !           203: \fB-u\fR for \fIci\fR that does a checkin followed by a checkout without
        !           204: locking. This is useful if you want to compile the file after the checkin.
        !           205: Both options also update the identification markers in your file (see below).
        !           206: .PP
        !           207: You can give \fIci\fR the number you want assigned to a checked in
        !           208: revision. Assume all your revisions were numbered 1.1, 1.2, 1.3, etc.,
        !           209: and you would like to start release 2.
        !           210: The command
        !           211: .DS
        !           212: ci  -r2  f.c       or          ci  -r2.1  f.c
        !           213: .DE
        !           214: assigns the number 2.1 to the new revision.
        !           215: From then on, \fIci\fR will number the subsequent revisions
        !           216: with 2.2, 2.3, etc. The corresponding \fIco\fR commands
        !           217: .DS
        !           218: co  -r2  f.c       and         co  -r2.1  f.c
        !           219: .DE
        !           220: retrieve the latest revision numbered 2.x and the revision 2.1,
        !           221: respectively. \fICo\fR without a revision number selects
        !           222: the latest revision on the "trunk", i.e., the highest
        !           223: revision with a number consisting of 2 fields. Numbers with more than 2
        !           224: fields are needed for branches.
        !           225: For example, to start a branch at revision 1.3, invoke
        !           226: .DS
        !           227:                ci  -r1.3.1  f.c
        !           228: .DE
        !           229: This command starts a branch numbered 1 at revision 1.3, and assigns
        !           230: the number 1.3.1.1 to the new revision. For more information about
        !           231: branches, see \fIrcsfile\fR(5).
        !           232: .SH
        !           233: Automatic Identification
        !           234: .PP
        !           235: RCS can put special strings for identification into your source and object
        !           236: code. To obtain such identification, place the marker
        !           237: .DS
        !           238: $Header$
        !           239: .DE
        !           240: into your text, for instance inside a comment.
        !           241: RCS will replace this marker with a string of the form
        !           242: .DS
        !           243: $Header:  filename  revisionnumber  date  time  author  state $
        !           244: .DE
        !           245: You never need to touch this string, because RCS keeps it
        !           246: up to date automatically.
        !           247: To propagate the marker into your object code, simply put
        !           248: it into a literal character string. In C, this is done as follows:
        !           249: .DS
        !           250: static char rcsid[] = "$Header$";
        !           251: .DE
        !           252: The command \fIident\fR extracts such markers from any file, even object code.
        !           253: Thus, \fIident\fR helps you to find out 
        !           254: which revisions of which modules were used in a given program. 
        !           255: .PP
        !           256: You may also find it useful to put the marker
        !           257: .DS
        !           258: $Log$
        !           259: .DE
        !           260: into your text, inside a comment. This marker accumulates
        !           261: the log messages that are requested during checkin.
        !           262: Thus, you can maintain the complete history of your file directly inside it.
        !           263: There are several additional identification markers; see \fIco\fR (1) for
        !           264: details.
        !           265: .SH
        !           266: How to combine MAKE and RCS
        !           267: .PP
        !           268: If your RCS files are in the same directory as your working files,
        !           269: you can put a default rule into your makefile. Do not use a rule
        !           270: of the form .c,v.c, because such a rule keeps a copy of every
        !           271: working file checked out, even those you are not working on. Instead, use this:
        !           272: .DS
        !           273: 
        !           274:  .SUFFIXES: .c,v
        !           275: 
        !           276:  .c,v.o:
        !           277:            co -q $*.c
        !           278:            cc $(CFLAGS) -c $*.c
        !           279:            rm -f $*.c
        !           280: 
        !           281:  prog:   f1.o f2.o .....
        !           282:            cc f1.o f2.o ..... -o prog
        !           283: .DE
        !           284: This rule has the following effect. If a file f.c does not exist, and f.o 
        !           285: is older than f.c,v, MAKE checks out f.c, compiles f.c into f.o, and then 
        !           286: deletes f.c. 
        !           287: From then on, MAKE will use f.o until you change f.c,v.
        !           288: .PP
        !           289: If f.c exists (presumably because you are working on it), the default
        !           290: rule .c.o takes precedence, and f.c is compiled into f.o, but not deleted.
        !           291: .PP
        !           292: If you keep your RCS file in the directory ./RCS, all this will not work
        !           293: and you have to write explicit checkout rules for every file, like
        !           294: .DS
        !           295: f1.c:   RCS/f1.c,v; co -q f1.c
        !           296: .DE
        !           297: Unfortunately, these rules do not
        !           298: have the property of removing unneeded .c-files.
        !           299: .SH
        !           300: Additional Information on RCS
        !           301: .PP
        !           302: If you want to know more about RCS, for example how to work
        !           303: with a tree of revisions and how to use symbolic revision numbers, read
        !           304: the following paper:
        !           305: .sp 1
        !           306: Walter F. Tichy, ``Design, Implementation, and Evaluation of a
        !           307: Revision Control System,'' in \fIProceedings of the 6th International
        !           308: Conference on Software Engineering\fR, IEEE, Tokyo, Sept. 1982.
        !           309: .PP
        !           310: Taking a look at the manual page \fIRCSFILE\fP(5)
        !           311: should also help to understand the revision tree permitted by RCS.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.