User Tools

Site Tools

Trace:
rcs_sample_session

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
rcs_sample_session [2025/03/05 15:19] – minor formatting tweaks zilogrcs_sample_session [2025/03/05 15:47] (current) – minor re-wording zilog
Line 1: Line 1:
 +==== Annotated RCS Practice Session ====
 +
 +<code diff>
 +## The Working Directory:
 +## To get started we first need to make a working directory as well as a
 +## RCS sub-directory.  Note if a ../RCS/ directory is not present RCS puts
 +## the delta files, ex. 'fubar,v', in the working directory; allowed but
 +## perhaps not really ideal.
 +#
 +$ mkdir -p rcs_test/RCS
 +$ cd rcs_test
 +
 +## Create a test file:
 +## RCS supports a handful of keyword tags which can be included in source
 +## files like so: "$Tag$".  These tags will then be expanded whenever RCS
 +## acts upon the file.
 +##
 +## fubar test file with 'Id' RCS keyword tag:
 +#
 +$ printf '$Id$\nThis is fubar line one.\n' >fubar
 +
 +
 +## Initial file check-in:
 +## When a file is first placed under RCS management the user is prompted
 +## for just the file's description.  This info can be multi-lined and is
 +## finalized with a "." on a new line.  The ci(1) command will be used for
 +## subsequent check-ins as well.  The '-u' option tells RCS to check the
 +## file in unlocked and place a read-only copy of the file in the working
 +## directory.  Keeping a read-only copy in the working directory is useful,
 +## especially for configuration files which need to be present.
 +#
 +$ ci -u fubar
 +RCS/fubar,v  <--  fubar
 +enter description, terminated with single '.' or end of file:
 +NOTE: This is NOT the log message!
 +>> The fubar RCS practice file
 +>> .
 +initial revision: 1.1
 +done
 +
 +## The current state of our working directory.  Note the special delta
 +## file under ../RCS/ which are used to track the changes:
 +#
 +$ ls -FR
 +RCS/       fubar
 +
 +./RCS:
 +fubar,v
 +
 +## Verifying the read-only status of fubar file:
 +#
 +$ ls -l fubar
 +-r--r--r--  1 sdfer  users  73 Mar  3 21:18 fubar
 +
 +
 +## Checking out RCS-managed files for editing:
 +## The co(1) command is used for check-outs.  Although not mandatory, locking
 +## the file via the '-l' option is a good idea as it helps prevent accidental
 +## over-writes or having to do a merge if previously checked out. In addition
 +## the lock state of a file can be polled via rlog(1) as a proxy to determine
 +## if it is liked check out.
 +#
 +$ co -l fubar
 +RCS/fubar,v  -->  fubar
 +revision 1.1 (locked)
 +done
 +
 +## Verifying the read-write status of working file:
 +#
 +$ ls -l fubar
 +-rw-r--r--  1 sdfer  users  101 Mar  3 21:20 fubar
 +
 +## Committing additional revisions:
 +## As with the initial check-in, the ci(1) command is used to commit changes made
 +## to our test file.  Below we add a second line to fubar then check it back in.
 +## This time RCS prompts for a description of our edit(s) followed by a "." on a
 +## new line:
 +#
 +$ echo 'This is fubar line two.' >> fubar
 +$ ci -u fubar
 +RCS/fubar,v  <--  fubar
 +new revision: 1.2; previous revision: 1.1
 +enter log message, terminated with single '.' or end of file:
 +>> added 2nd line
 +>> .
 +done
 +
 +
 +## Verifying RCS keyword Tag expansion:
 +## It's a small file so we'll use cat(1) to show current content of fubar.  Note
 +## the expansion of the "$Id$" keyword tag; similar tags are commonly used by the
 +## NetBSD project as can be seen at the top of various /etc/* config files:
 +#
 +$ cat fubar
 +# $Id: fubar,v 1.2 2025/03/04 04:19:48 sdfer Exp $
 +This is fubar line one.
 +This is fubar line two.
 +
 +
 +## The Art of Reversion:
 +## It's common for humans to have a change of heart in their endeavors
 +## and file editing is certainly not exempt.  Fortunately RCS is up to
 +## dealing with our indecisiveness.  To illustrate we'll check out our
 +## test file, make some edits to the working copy, then over-write the
 +## working copy with the latest checked in version, leaving us back at
 +## our starting point.
 +#
 +$ co -l fubar
 +RCS/fubar,v  -->  fubar
 +revision 1.2 (locked)
 +done
 +
 +## add a third line to test file:
 +#
 +$ echo 'This is fubar line 3.' >> fubar
 +
 +## We've changed our mind => revert back to latest checked-in version.
 +## We'll use the '-u' option with the co(1) command which will remove
 +## the lock on the latest checked-in version and over-write our edited
 +## working file with a read-only copy if we confirm the action:
 +#
 +$ co -u fubar
 +RCS/fubar,v  -->  fubar
 +revision 1.2 (unlocked)
 +writable fubar exists; remove it? [ny](n): y  # << type "y" to confirm
 +done
 +
 +## Verifying file state is read-only:
 +#
 +$ ls -l fubar
 +-r--r--r--  1 sdfer  users  73 Mar  3 21:18 fubar
 +
 +
 +## Comparing revisions with rcsdiff(1):
 +## The rcsdiff(1) command is similar to the standard Unix diff(1) and is
 +## used to compute the differences between two revisions. For ease of use
 +## The default reference point is the latest checked in revision and if 
 +## run without specifying an alternate revision the comparison is with
 +## the working copy.  Since our file is identical to the latest checked
 +## in version the rcsdiff(1) command reports just that:
 +#
 +$ rcsdiff fubar
 +===================================================================
 +RCS file: RCS/fubar,v
 +retrieving revision 1.2
 +diff -r1.2 fubar
 +
 +## Providing specific versions to rcsdiff(1) shows the differences; below
 +## r1.1 and r1.2 are compared.  Note that the same result is obtained if
 +## just '-r1.1' is given as the latest version is the default reference:
 +#
 +$ rcsdiff -r1.1 -r1.2 fubar
 +===================================================================
 +RCS file: RCS/fubar,v
 +retrieving revision 1.1
 +retrieving revision 1.2
 +diff -r1.1 -r1.2
 +1c1
 +< # $Id: fubar,v 1.1 2025/03/04 04:18:22 sdfer Exp $
 +---
 +> # $Id: fubar,v 1.2 2025/03/04 04:19:48 sdfer Exp $
 +2a3
 +> This is fubar line two.
 +
 +
 +## Similarly, if we do another check out, make some edits and run the
 +## rcsdiff(1) command again we can see how our working copy compares
 +## to the latest checked in revision:
 +#
 +$ co -l fubar
 +RCS/fubar,v  -->  fubar
 +revision 1.2 (locked)
 +done
 +
 +
 +## Re-add a third line to test file:
 +#
 +$ echo 'This is fubar line 3, again.' >> fubar
 +
 +## Compute diff between working file and r1.2:
 +#
 +$ rcsdiff fubar
 +RCS file: RCS/fubar,v
 +retrieving revision 1.2
 +diff -r1.2
 +3a4
 +> This is fubar line 3, again.
 +
 +## Toss line 3 again and revert back to RO r1.2:
 +#
 +$ co -u fubar
 +RCS/fubar,v  -->  fubar
 +revision 1.2 (unlocked)
 +writable fubar exists; remove it? [ny](n): y  # << type "y" to confirm
 +done
 +
 +
 +## Deleting versions:
 +## Oops -- we've changed our mind AGAIN and want to revert to r1.1 and
 +## DELETE r1.2 from the RCS record.  This requires the rcs(1) command
 +## with the '-o<ver_range>' option along with 'co -u' as before.  Note
 +## the order doesn't matter: 'co -r1.1 -u' + 'rcs -o1.2' works too.
 +#
 +$ rcs -o1.2 fubar
 +RCS file: RCS/fubar,v
 +deleting revision 1.2
 +done
 +
 +## rcs(1) left the RO copy which was still at r1.2..
 +#
 +$ ls -l fubar
 +#
 +-r--r--r--  1 sdfer  users  97 Mar  3 21:22 fubar
 +
 +## Just for fun, instead of using cat(1) lets use the ident(1) command
 +## to display the current state of our RCS keyword tag "$Id$":
 +#
 +$ ident fubar
 +fubar:
 +     $Id: fubar,v 1.2 2025/03/04 04:19:48 sdfer Exp $
 +
 +## As we can see above the RO copy in the working directory still shows
 +## the r1.2 edits; to fix this we'll need to check out latest checked in
 +## version (now 1.1) and UNLOCK it:
 +#
 +$ co -u fubar
 +RCS/fubar,v  -->  fubar
 +revision 1.1 (unlocked)
 +done
 +
 +## Re-running ident(1) shows our read-only copy now matches the latest
 +## checked revision which is now r1.1:
 +#
 +$ ident fubar
 +fubar:
 +     $Id: fubar,v 1.1 2025/03/04 04:18:22 sdfer Exp $
 +
 +
 +## Checking the logs:
 +## The rlog(1) command can show us the change comments for any checked in
 +## revision using '-r<ver>'.  Be default rlog(1) simply shows ALL changes:
 +#
 +$ rlog fubar
 +RCS file: RCS/fubar,v
 +Working file: fubar
 +head: 1.1
 +branch:
 +locks: strict
 +access list:
 +symbolic names:
 +keyword substitution: kv
 +total revisions: 1;     selected revisions: 1
 +description:
 +The fubar RCS practice file
 +----------------------------
 +revision 1.1
 +date: 2025/03/04 04:18:22;  author: sdfer;  state: Exp;
 +Initial revision
 +=============================================================================
 +
 +
 +## Checking lock states with rlog(1):
 +## As long as locking hasn't been disabled the rlog(1) command can be used
 +## to determine whether a file is currently locked and thus is a proxy for
 +## discerning whether a file is likely checked out. When the '-L' option is
 +## used rlog(1) will print the file name(s) of any files with active locks;
 +## files without locks are omitted, i.e. no output.  A simple lock checker
 +## can be made utilizing this behavior like so:
 +#
 +$ [ -z "$(rlog -L fubar)" ] && echo 'Unlocked' || echo 'Locked'
 +=> Unlocked
 +
 +## If we check out and lock our test file and re-run the above we can see
 +## change in lock status:
 +#
 +$ co -l fubar
 +RCS/fubar,v  -->  fubar
 +revision 1.1 (locked)
 +done
 +
 +$ [ -z "$(rlog -L fubar)" ] && echo 'Unlocked' || echo 'Locked'
 +=> Locked
 +
 +</code>
 +
 +This concludes our whirlwind tour of RCS -- you are now an expert! 8-)