rcs - Revision Control System

Table of Contents:

• Introduction
• Easy Guide
1. Create the RCS sub-directory for storing files
2. Check-In the 1st revision
3. Check-Out the file, and lock it for editing
4. Check the differences in what you have edited
5. Check-In most recent updates
• HOW TO
• Compare different revisions
• Check in without losing my file
• Revert to a previous version
• Author and Copyright

Introduction

[ref: rcsintro(1)]

Essentially, Revision Control System (RCS), provides an enhanced archiving/recording system for tracking changes you make to 'important' files.

I use it because I'm always fiddling with configuration files until I don't know what changes I've made and when things crash I don't recall how to get back to a working version.

Easy Guide

[ref: rcsintro(1)]

To create an RCS entry we first have to:

1. Create the RCS sub-directory for storing files
2. Check-In the 1st revision
3. Check-Out the file, and lock it for editing
4. Check the differences in what you have edited
5. Check-In most recent updates

Create RCS Sub-directory

[file: /etc/rc.conf.local]

Create the repository, place where the RCS is to be 'stored.' This is usually the directory RCS under the directory where your file is stored.

For example, if we are to edit the file /etc/rc.conf.local we would need to create the directory RCS under /etc

Check in 1st Revision

[file: /etc/rc.conf.local]
[ref: ci(1)]

ci (Check In RCS Revisions) stores new revisions of working files into RCS files. When a totally new file is 'checked-in' ci will:

1. create a new entry using the contents of the working file.
2. prompt for a descriptive text of the file and,
3. initialise the revision number as 1.1.

Let's begin our experiment by creating a skeleton of the /etc/rc.conf.local file.

File /etc/rc.conf.local:

We can now take a look at committing the 1st version of our file by using the command 'ci filename'

When you run 'ci' the displayed information tells you:

1. that rc.conf.local has now been committed the working file to an RCS entry: RCS/rc.conf.local,v

   RCS/rc.conf.local,v <-- rc.conf.local

   You can readily confirm this by listing the contents of the directory RCS, and the created file rc.conf.local,v

2. then 'ci' prompts you for a descriptive text of the file we are committing

   enter description, terminated with single '.' or end of file: NOTE: This is NOT the log message! >>

   In our example above, we have stated the value of the file we are editing.

   >> Contains Startup Configuration for initialising OpenBSD startup >> This file should be edited when customising Startup, and not /etc/rc.conf >> .

3. The . on the new line ended our input and RCS has initialised the revision at 1.1, we are done.
   

   initial revision 1.1 done

We have successfully created our RCS entry.

Check-Out the file, and lock it for editing

[file: /etc/rc.conf.local]
[ref: co(1)]

To make changes to our example file /etc/rc.conf.local, we need to 'check-it-out' from RCS, and to lock it using the 'co -l filename' command

The check-out command 'co' extracts the latest revision from the RCS file and writes it to 'rc.conf.local' We lock the file before editing to ensure that we are the only one editing the file, and the only one allowed to update the file.

From the program response above, we are told the existing revision is 1.1 and it is now locked.

If we take a look at the file, you will see that the $Id: rcs.htm,v 1.1.1.1 2002/06/10 02:09:57 samt Exp $ line at the very beginning of the file has now been expanded to provide some details about the RCS process on the file.

For more information on this, check the co(1) man pages.

Now, (a) we can make changes to the file, and (b) No other person has write privileges to the file.

Check the differences in what you have edited

[file: /etc/rc.conf.local]
[ref: rcsdiff(1)]

rcsdiff runs a diff to compare the differences between two versions of a file. By default it will compare the working file with the latest revision in the RCS tree.

TO look at how changes can be reported by RCS, we make the following modifications to SECTION 1 of the rc.conf.local file.

We save the changes to /etc/rc.conf.local and take a look at how rcs views our changes by using 'rcsdiff filename'

===================================================================
RCS file: RCS/rc.conf.local,v
retrieving revision 1.1
diff -r1.1 rc.conf.local
4a5,8
> xdm_flags = ""                   # use two double-quotes
> sendmail = "-bd q30m"            # for normal use: "-bd -q30m"
> ftpd_flags= "-DllUSA"            # for non-inetd use: ftpd_flags="-D"
>

rcsdiff reads our working file /etc/rc.conf.local and compares it to the current revision (1.1) in the RCS tree.

The default display outputs the changes we made.

Check-In most recent updates

[ref: ci(1)]
[file: /etc/rc.conf.local]

We can check-in the update above using (ci.) By using the unlock (-u) or lock (-l) option we tell ci not to delete the working file after checking it in.

In the situation of the /etc/rc.conf.local file, we are using RCS to maintain a trace log of changes so we can recover from any serious editorial faults. In such a scenario it is valid to keep the 'lock' on, or remove locking altogether (see the man pages.)

HOW TO

Compare Different Revisions

[ref: rcsdiff(1)]

You can compare different revisions of your file by using rcsdiff (releaseA) (releaseB) filename.

For example, to compare the differences between release 1.1 and release 1.3 we can use the following command-line.

Check In without losing my File

[ref: rcsintro, ci]

Checking in a file automatically removes the file from the current location and places it into the repository.

To prevent ci from deleting your working file, you can use either

These two commands implicitly check out the file after check-in.

Revert to a previous Revision

To revert to a previous edit, you simply check-out the version you wish to be the 'current' release, and then check it in again.

For example, if I wish to revert to the original file (release 1.1) and I am current up to release 1.4.

Author and Copyright

Copyright (c) 2000/1/2 Samiuela LV Taufa. All Rights Reserved.

I reserve the right to be totally incorrect even at the best advice of betters. In other words, I'm probably wrong in enough places for you to call me an idiot, but don't 'cause you'll hurt my sensibilities, just tell me where I went wrong and I'll try again.

You are permitted and encouraged to use this guide for fun or for profit as you see fit. If you republish this work in what-ever form, it would be nice (though not enforceable) to be credited.

Copyright  © 2000/1/2 NoMoa Publishers All rights reserved. Caveat Emptor