comp.software-eng archive file "blurb/rcs" last changed 5 Oct 1992 This file contains information on the following subjects. Numbers in column 1 count distinct messages with the corresponding subject. 1 LaTeX handout on RCS 1 course handout with example ------------------------------------------------------------------------ In early 1992, Arun Lakhotia asked for references on How does one learn to use RCS? Walter Tichy recommended the following report: Dan Ligett, RCS Revision Control System on Unix, School of Information Technology, Wang Institute of Graduate Studies, TR-85-20, Nov 21, 1985. Unfortunately WIGS no longer exists. Other recommendations include: - The manual that comes with the Mortice Kern Systems commercial version of RCS (see FAQ vendor list). - ``Software Configuration Management'', Wayne A. Babich (Addison-Wesley, 1986, ISBN 0-201-10161-0) ------------------------------------------------------------------------ Date: Fri, 10 Jan 92 12:45:28 -0500 From: ofut@hubcap.clemson.edu (A. Jeff Offutt) Subject: LaTeX handout on RCS Newsgroups: comp.software-eng I regularly require my senior SE students to use RCS ... here is the handout I give them ... with this, they have successfully used RCS without asking me any additional questions. \documentstyle[11pt]{article} \textheight=9in \evensidemargin=-0.5in \oddsidemargin=-0.5in \textwidth=7.5in \topmargin=-0.3in \topskip=0pt \baselineskip=12pt \parskip=12pt \begin{document} \vspace*{12pt} \begin{center} {\Large\bf RCS (Revision Control System)} {\bf Jeff Offutt} \end{center} \vspace{24pt} {\tt RCS} is a {\tt R}evision {\tt C}ontrol {\tt S}ystem for managing multiple revisions of text files. {\tt RCS} automates the storing, retrieval, logging, identification, and merging of revisions. {\tt RCS} is useful for text that is revised frequently; for example programs, documentation, graphics, papers, form letters, etc. The two functions that are the most commonly used are {\tt ci} (checkin) and {\tt co} (checkout). {\tt ci} checks a file into {\tt RCS} by adding revision control information to a copy of the file, which is placed into the local subdirectory {\tt RCS}. If there is no local subdirectory {\tt RCS}, the file is copied to the current directory with the extension {\tt ,v}. {\tt co} checks a file out of {\tt RCS} by copying the file from the {\tt RCS} subdirectory and removing the revision control information. {\tt co -l} checks the file out with a {\it lock}, which gives the user permission to modify the file. Files checked out without a lock cannot be checked back in. For more information, see the man pages (man {\tt rcsintro, man rcs, man co, man ci}, etc.). \centerline{Functions of RCS} \begin{enumerate} \item {\tt RCS} provides the following functions. {\tt RCS} stores and retrieves multiple revisions of program and other text. Thus, one can maintain one or more releases while developing the next release, with a minimum of space overhead. Changes no longer destroy the original -- previous revisions remain accessible. \begin{enumerate} \item Maintains each module as a tree of revisions. \item Project libraries can be organized centrally, decentralized, or any way you like. \item {\tt RCS} works for any type of text: programs, documentation, memos, papers, graphics, VLSI layouts, form letters, etc. \end{enumerate} \item {\tt RCS} maintains a complete history of changes. Thus, one can find out what happened to a module easily and quickly, without having to compare source listings or having to track down colleagues. \begin{enumerate} \item {\tt RCS} performs automatic record keeping. \item {\tt RCS} logs all changes automatically. \item {\tt RCS} guarantees project continuity. \end{enumerate} \item {\tt RCS} manages multiple lines of development. \item {\tt RCS} can merge multiple lines of development. Thus, when several parallel lines of development must be consolidated into one line, the merging of changes is automatic. \item {\tt RCS} flags coding conflicts. If two or more lines of development modify the same section of code, {\tt RCS} can alert programmers about overlapping changes. \item {\tt RCS} resolves access conflicts. When two or more programmers wish to modify the same revision, {\tt RCS} alerts the programmers and makes sure that one modification won't wipe out the other one. \item {\tt RCS} provides high-level retrieval functions. Revisions can be retrieved according to ranges of revision numbers, symbolic names, dates, authors, and states. \item {\tt RCS} provides release and configuration control. Revisions can be marked as released, stable, experimental, etc. Configurations of modules can be described simply and directly. \item {\tt RCS} performs automatic identification of modules with name, revision number, creation time, author, etc. Thus, it is always possible to determine which revisions of which modules make up a given configuration. \item Provides high-level management visibility. Thus, it is easy to track the status of a software project. \begin{enumerate} \item {\tt RCS} provides a complete change history. \item {\tt RCS} records who did what when to which revision of which module. \end{enumerate} \item {\tt RCS} is fully compatible with existing software development tools. {\tt RCS} is unobtrusive -- its interface to the file system is such that all your existing software tools can be used as before. \item {\tt RCS}' basic user interface is extremely simple. The novice needs to learn only two commands. Its more sophisticated features have been tuned towards advanced software development environments and the experienced software professional. \item {\tt RCS} simplifies software distribution if customers maintain sources with {\tt RCS} also. This technique assures proper identification of versions and configurations, and tracking of customer modifications. Customer modifications can be merged into distributed versions locally or by the development group. \item {\tt RCS} needs little extra space for the revisions (only the differences). If intermediate revisions are deleted, the corresponding differences are compressed into the shortest possible form. \item {\tt RCS} is implemented with reverse deltas. This means that the latest revision, which is the one that is accessed most often, is stored intact. All others are regenerated from the latest one by applying reverse deltas (backward differences). This results in fast access time for the revision needed most often. \end{enumerate} \end{document} ------------------------------------------------------------------------ Date: Sat, 11 Jan 92 23:42:06 -0500 From: vogel@c17igpb.wpafb.af.mil (Contr Karl Vogel) Subject: course handout with example Organization: Control Data Corporation #!/bin/sh # This is a shell archive (produced by shar 3.49 90/09/12) # To extract the files from this archive, save it to a file, remove # everything above the "!/bin/sh" line above, and type "sh file_name". # # made 01/12/1992 04:41 UTC by vogel@c17igpb # Source directory /tmp/work # # existing files will NOT be overwritten unless -c is specified # # This shar contains: # length mode name # ------ ---------- ------------------------------------------ # 2325 -rw-r--r-- example # 1284 -rw-r--r-- key # 16567 -rw-r--r-- rcs.tutorial # # ============= example ============== if test -f 'example' -a X"$1" != X"-c"; then echo 'x - skipping example (File already exists)' else echo 'x - extracting example (Text)' sed 's/^X//' << 'SHAR_EOF' > 'example' && X X Nose rebuttals from the movie "Roxanne" X 1. Obvious: "Excuse me, is that your nose, X or did a bus park on your face?" X 2. Meteorological: "Everybody take cover, she's X going to blow!" X 3. Fashionable: "You know, you could de-emphasize X your nose if you wore something X larger, like Wyoming." X 4. Personal: "Well, here we are, just the X three of us." X 5. Punctual: "All right Dellman, your nose X was on time, but you were fifteen X minutes late." X 6. Envious: "Ooh, I wish I were you, to be X able to smell your own ear." X 7. Naughty: "Pardon me sir, some of the X ladies have asked if you wouldn't X mind putting that thing away." X 8. Philosophical: "You know, it's not the size of X a nose that's important, it's X what's in it what matters." X 9. Humorous: "Laugh and the world laughs with X you; sneeze and it's goodbye Seattle." X 10. Commercial: "Hi, I'm Earl Scheib, and I can X paint that nose for Thirty-Nine X Ninety-Five." X 11. Polite: "Ah, would you mind not bobbing X your head? The, ah, orchestra X keeps changing tempo." X 12. Melodic: (Everybody) "He's got the whole X world.. in his nose." X 13. Sympathetic: "Ooh, what happened, did your X parents lose a bet with God?" X 14. Complimentary: "You must love the little X birdies to give them this X to perch on." X 15. Scientific: "Say, does that thing there X influence the tides?" X 16. Obscure: "Hoo, I'd hate to see the X grindstone." X 17. Enquiry: "When you stop and smell the X flowers, are they afraid?" X 18. French: "Sir, ze pigs have refused to X find any more truffles until X you leave." X 19. Pornographic: "Finally, a man who can satisfy X two women at once." X 20. Religious: "The Lord giveth, and he just X kept on giving, didn't he?" X 21. Disgusting: "Say, who mows your nose hair?" X 22. Paranoid: "Keep that guy away from my X cocaine." X 23. Romantic: "It must be wonderful to wake up X in the morning and smell the X coffee ... in Brazil." X 24. Appreciative: "Ooh how original, most people X have their teeth capped." X 25. Dirty: "Your name wouldn't be ... Dick, X would it?" SHAR_EOF chmod 0644 example || echo 'restore of example failed' Wc_c="`wc -c < 'example'`" test 2325 -eq "$Wc_c" || echo 'example: original size 2325, current size' "$Wc_c" fi # ============= key ============== if test -f 'key' -a X"$1" != X"-c"; then echo 'x - skipping key (File already exists)' else echo 'x - extracting key (Text)' sed 's/^X//' << 'SHAR_EOF' > 'key' && KEYWORD SUBSTITUTION X X Initially, the user enters strings of the form $keyword$. On checkout, X co replaces these strings with strings of the form $keyword: value $. X If a revision containing strings of the latter form is checked back in, X the value fields will be replaced during the next checkout. Thus, the X keyword values are automatically updated on checkout. X X Here are the keywords and their corresponding values: X X $Author$ X X The login name of the user who checked in the revision. X X X $Date$ X X The date and time the revision was checked in. X X X $Header$ X X A standard header containing the RCS file name, the revision X number, the date, the author, and the state. X X X $Locker$ X X The login name of the user who locked the revision (empty X if not locked). X X X $Log$ X X The log message supplied during checkin, preceded by a X header containing the RCS file name, the revision number, X the author, and the date. Existing log messages are NOT X replaced. Instead, the new log message is inserted after X $Log:...$. This is useful for accumulating a complete X change log in a source file. X X X $Revision$ X X The revision number assigned to the revision. X X X $Source$ X X The full pathname of the RCS file. X X X $State$ X X The state assigned to the revision with rcs -s or ci -s. SHAR_EOF chmod 0644 key || echo 'restore of key failed' Wc_c="`wc -c < 'key'`" test 1284 -eq "$Wc_c" || echo 'key: original size 1284, current size' "$Wc_c" fi # ============= rcs.tutorial ============== if test -f 'rcs.tutorial' -a X"$1" != X"-c"; then echo 'x - skipping rcs.tutorial (File already exists)' else echo 'x - extracting rcs.tutorial (Text)' sed 's/^X//' << 'SHAR_EOF' > 'rcs.tutorial' && X X RCS Tutorial $Revision: 1.4 $ X INTRODUCTION X X Have you ever been working on a letter or a text file of any X kind, and suddenly wished that you could get back the copy of X the letter you had 2 or 3 edits ago? X X You can save multiple copies of the file, i.e. X X letter.1 X letter.2 X etc. X X but then you have to go thru them to see which one you want X back, and it's very wasteful of storage if the file is big. X X Unix provides a way to do this which is quick and fairly easy X to use. RCS (Revision Control System) is a program which: X X 1. saves only the most recent copy of the file, plus the X changes needed to get back any previous version. X X 2. lets you recover any one version at any time. X X 3. lets you compare and comment versions. X X 4. is good for backup purposes, because you can always get X back a previous version even if you destroy the current X one. X X 5. acts like a public library. X X HOW TO CREATE AN RCS FILE X X Let's get to the rcs directory: X X unix % pwd X /c/lessons/student/vi X X unix % cd rcs X ~/rcs X X use cdpath variable to take us immediately X to the RCS directory. X X unix % pwd X /c/lessons/student/rcs X X unix % ls -lF X total 6 X -rw-r--r-- 1 user 2325 Nov 15 14:59 example X -rw-r--r-- 1 user 1284 Nov 15 14:44 key X X unix % head example X X Nose rebuttals from the movie "Roxanne" X X 1. Obvious: "Excuse me, is that your nose, X or did a bus park on your face?" X X 2. Meteorological: "Everybody take cover, she's X going to blow!" X X We want to check in (make an RCS file for) the file example, so X we use the "ci" (check in) command: X X unix % ci example X example,v <-- example X initial revision: 1.1 X enter description, terminated with ^D or '.': X NOTE: This is NOT the log message! X >> X X RCS is now waiting for an initial description of some kind. X Type something, hit return, and then type Control-D. X X >> test for ci X >> ^D X done X X Now, do "ls -lF" and see what happened. X X unix % ls -lF X total 6 X -r--r--r-- 1 user 2531 Nov 15 15:03 example,v X -rw-r--r-- 1 user 1284 Nov 15 14:44 key X X Your "example" file has gone away, and a file "example,v" has X been left in its place. You have just created an initial X revision for the file "example" in the current directory. X This is just like checking in a book at the library. If you X want to read the book, you have to check it back out again. X X Notice that write permissions have been turned off for the file. X DO NOT try to edit the ,v file: this is the file which stores X the history of changes for "example". You can use other X commands to get back a working copy of "example". X X HOW TO CHECK OUT A FILE X X Use the "co" (check out) command to check out your latest X revision: X X unix % co example X example,v --> example X revision 1.1 X done X X unix % ls -lF X total 12 X -rw-r--r-- 1 user 2325 Nov 15 15:10 example X -r--r--r-- 1 user 2531 Nov 15 15:03 example,v X -rw-r--r-- 1 user 54 Nov 15 15:10 in X -rw-r--r-- 1 user 1284 Nov 15 14:44 key X X You have just told RCS that you want to get the latest copy of X the "example" file back. Notice that write permissions have X been turned back on for "example". X X Now, let's make some changes to the file, and use RCS to save X them. X X unix % vi example X X VI -- 8dd delete first 2 insults X VI -- ZZ X X unix % ci example X example,v <-- example X new revision: 1.2; previous revision: 1.1 X enter log message: X (terminate with ^D or single '.') X >> X X Notice that the revision number has been bumped up to 1.2, and X you're being asked for a log message instead of a description. X RCS wants to have some kind of a description for the changes X that were made for the file. X X >> deleted 8 lines X >> ^D X done X X Notice that the "example" file is gone again, and the X "example,v" file is bigger than it was before. This is X because it now has a current copy of the file, and all X changes needed to recover the first version of the file, too. X X unix % ls -lF X total 6 X -r--r--r-- 1 user 2657 Nov 15 15:14 example,v X -rw-r--r-- 1 user 1284 Nov 15 14:44 key X X Let's get back the latest version: X X unix % co example X example,v --> example X revision 1.2 X done X X unix % ls -lF X total 8 X -rw-r--r-- 1 user 2117 Nov 15 15:18 example X -r--r--r-- 1 user 2657 Nov 15 15:14 example,v X -rw-r--r-- 1 user 1284 Nov 15 14:44 key X X unix % head example X X 3. Fashionable: "You know, you could de-emphasize X your nose if you wore something X larger, like Wyoming." X X 4. Personal: "Well, here we are, just the X three of us." X X 5. Punctual: "All right Dellman, your nose X was on time, but you were fifteen X X Let's get back version 1.1: X X unix % co -r1.1 example X example,v --> example X revision 1.1 X writable example exists; overwrite? [ny](n): y X done X X Notice how RCS asked you if you want to overwrite the file? X This is because a file by that name already existed in the X current directory. X X unix % head example X X Nose rebuttals from the movie "Roxanne" X X 1. Obvious: "Excuse me, is that your nose, X or did a bus park on your face?" X X 2. Meteorological: "Everybody take cover, she's X going to blow!" X X 3. Fashionable: "You know, you could de-emphasize X X As you can see, we do have the original version back. Let's X get back the most recent version: X X unix % co example X example,v --> example X revision 1.2 X writable example exists; overwrite? [ny](n): y X done X X The whole point of RCS is that it lets you make a set of X changes to a document, check in those changes, and then make X more changes while knowing that you can get the original back X again. X X What happens when you check in a revision without changing X anything? X X unix % ci example X example,v <-- example X new revision: 1.3; previous revision: 1.2 X File example is unchanged with respect to revision 1.2 X checkin anyway? [ny](n): n X checkin aborted; example deleted. X X HOW TO DISPLAY A HISTORY OF CHANGES X X At some point, you may have several revisions of a file and X lots of changes to remember. RCS lets you display a history X of changes by using the rlog command: X X unix % rlog example X RCS file: example,v; Working file: example X head: 1.2 X locks: X access list: X symbolic names: X comment leader: "# " X total revisions: 2; selected revisions: 2 X description: X test for ci X ---------------------------- X revision 1.2 X date: 89/11/15 15:14:43; author: user; state: Exp; X lines added/del: 0/8 X deleted 8 lines X ---------------------------- X revision 1.1 X date: 89/11/15 15:03:07; author: user; state: Exp; X Initial revision X ======================================================= X X Notice the "author" field, the date of each revision, and the X comments underneath each revision entry. Also, rlog tells you X what revision you are on now (1.2) at the top of the output. X X What if you want to see the revision history for just one X version? X X unix % rlog -r1.1 example X RCS file: example,v; Working file: example X head: 1.2 X locks: X access list: X symbolic names: X comment leader: "# " X total revisions: 2; selected revisions: 1 X description: X test for ci X ---------------------------- X revision 1.1 X date: 89/11/15 15:03:07; author: user; state: Exp; X Initial revision X ==================================================== X X There is a limit of about 512 characters for any one log X message or description. This is about 6 full 80-character X lines. X X HOW TO DISPLAY DIFFERENCES BETWEEN REVISIONS X X Let's get back the latest revision. X X unix % co example X example,v --> example X revision 1.2 X done X X The "rcsdiff" command will show you any differences between the X working copy and the latest checked-in revision, or between any X two revisions: X X unix % rcsdiff example X RCS file: example,v X retrieving revision 1.2 X diff -r1.2 example X X Notice that there are no differences. This makes sense, X because we just checked out the file. Make some changes: X X unix % vi example X X VI -- 8dd X VI -- ZZ X X Now, items 3 and 4 are gone, and there will be some differences X between the working file and the latest checked-in revision: X X unix % rcsdiff example X RCS file: example,v X retrieving revision 1.2 X diff -r1.2 example X 1,8d0 X < X < 3. Fashionable: "You know, you could de-emphasize X < your nose if you wore something X < larger, like Wyoming." X < X < 4. Personal: "Well, here we are, just the X < three of us." X < X X Let's see what the differences are between the working copy and X revision 1.1: X X unix % rcsdiff -r1.1 example X RCS file: example,v X retrieving revision 1.1 X diff -r1.1 example X 1,16d0 X < X < Nose rebuttals from the movie "Roxanne" X < X < 1. Obvious: "Excuse me, is that your nose, X < or did a bus park on your face?" X < X < 2. Meteorological: "Everybody take cover, she's X < going to blow!" X < X < 3. Fashionable: "You know, you could de-emphasize X < your nose if you wore something X < larger, like Wyoming." X < X < 4. Personal: "Well, here we are, just the X < three of us." X < X X We have deleted a total of 16 lines since we started making X changes. You can see the missing lines. Let's see what the X difference is between revisions 1.1 and 1.2: X X unix % rcsdiff -r1.1 -r1.2 example X RCS file: example,v X retrieving revision 1.1 X retrieving revision 1.2 X diff -r1.1 -r1.2 X 2,9d1 X < Nose rebuttals from the movie "Roxanne" X < X < 1. Obvious: "Excuse me, is that your nose, X < or did a bus park on your face?" X < X < 2. Meteorological: "Everybody take cover, she's X < going to blow!" X < X X HOW DO YOU KNOW WHICH VERSION IS WHICH? X X RCS lets you put "keywords" into your document, which RCS uses X to store information about the version. These come in handy, X because they tell you what version of a file you have just by X looking at the working copy you have checked out. X X The file "key" has a list of these keywords. X X unix % less key X ... X X Let's see what RCS does with those keywords: X X unix % ci key X key,v <-- key X initial revision: 1.1 X enter description, terminated with ^D or '.': X NOTE: This is NOT the log message! X >> keyword list X >> ^D X done X X unix % co key X key,v --> key X revision 1.1 X done X X unix % less key X ... X X As you can see, RCS replaced the keywords with some potentially X useful information. RCS does this automatically every time you X check out a revision of a file. X X The most useful keywords are probably "Header" and "Source". X Between the 2 of them, you have most of the information you X need. For example, you could put header strings into "nroff" X files as comments. X X You can find RCS keywords in any kind of a file by using the X RCS command "ident": X X unix % ident key X key: X $ Author: user $ X $ Date: 89/11/15 16:01:29 $ X $ Header: key,v 1.1 89/11/15 16:01:29 user Exp $ X $ Locker: $ X $ Log: key,v $ Revision 1.1 89/11/15 16:01:29 user Initial revision X X $ Log: key,v $ Revision 1.1 89/11/15 16:01:29 user Initial revision X X $ Revision: 1.1 $ X $ Source: /d/cdc/user/training/teacher/RCS/key,v $ X $ State: Exp $ X X HOW TO AVOID CLUTTERING UP YOUR DIRECTORY X X If you use RCS a lot, you can end up with a lot of ",v" files X in your directory. If you are using RCS correctly, then you X don't directly edit or change those files, so why have to look X at them? X X If you create a directory called RCS in your current directory, X then all of the revision files you create will be stored in X that directory, and everything that we've done will work X exactly the same way. X X SUMMARY OF RCS COMMANDS X X Command Manual Description X Section ====================================================================== X ci 1 - check in RCS revisions X co 1 - check out RCS revisions X ident 1 - identify files X rcs 1 - change RCS file attributes X rcsdiff 1 - compare RCS revisions X rcsintro 1 - introduction to RCS commands X rcsmerge 1 - merge RCS revisions X rlog 1 - print log messages and information about RCS X files X X END OF CLASS SHAR_EOF chmod 0644 rcs.tutorial || echo 'restore of rcs.tutorial failed' Wc_c="`wc -c < 'rcs.tutorial'`" test 16567 -eq "$Wc_c" || echo 'rcs.tutorial: original size 16567, current size' "$Wc_c" fi exit 0