

How to use RCS on gldrocky?  
  by Lucky Vidmar  (February 2000)


First, make sure that /usr/local/bin is in your path. There, you
will find two shell scripts that should make your RCS experience 
a little easier:

checkout <filename> : checks out <filename> from RCS, sets a lock 
  with you as the owner, which means that no one else will be 
  able to write to the file, although the file will remain readable. 

checkin <filename> : checks the file back in, asks you to enter a log
  message describing what you did to the file while you had it checked
  out, and removes the lock so that others can check it out.


If you only need to look at a file, you do not need to check it out. However,
if you intend to make any changes, run checkout first. This will ensure two 
things: (1) that no one else has the file checked out,  and (2) lock the
file so that no one else can trample over your work later.


Here are some of the typical situations:

-- A file is properly checked in, and you want to check it out:

(gldrocky):/tmp> checkout test.c
RCS/test.c,v  -->  test.c
revision 1.1 (locked)
done

  ** Now you are free to modify test.c, while everyone else is locked out.


-- A file is already checked out by someone else, and you try to check it out:

gldrocky% checkout test.c
RCS/test.c,v  -->  test.c
co: RCS/test.c,v: Revision 1.1 is already locked by lucky.

  ** This is your hint that someone is working on this file. 


-- A file is ready to be checked back in:

(gldrocky):/tmp> checkin test.c 
RCS/test.c,v  <--  test.c
new revision: 1.2; previous revision: 1.1
enter log message, terminated with single '.' or end of file:
>> This is a log message       
done

  ** The file is now checked back in, so that anyone else can check it back out.


checkin and checkout are shell scripts that "hide" the actual RCS commands. The
man pages for the RCS commands (ci, co, rcs, rcslog, rcsdiff, ...) are 
in /usr/local/man, so you will want to make sure that /usr/local/man is in 
your MANPATH environment variable if you want to read up on the guts of 
RCS.

One more advanced operation that might come in handy in emergencies is 
breaking someone's lock. I would advise against using this approach
unless absolutely necessary, as it defeats the purpose of RCS. But, I've
seen situations where someone forgets to check a file back in for weeks, 
they leave for a monthlong vacation, and you need imediate access to the file.
In that situation, you can do the following:

gldrocky% rcs -u test.c
RCS file: RCS/test.c,v
Revision 1.2 is already locked by lucky.
Do you want to break the lock? [ny](n): y
State the reason for breaking the lock:
(terminate with single '.' or end of file)
>> Remember to check your stuff back in, you goof!
1.2 unlocked
done


This will send me email with the message "Remember to check your stuff back in, you
goof!", telling me that David broke the lock on the file that I had checked out.


That's about it for the basics. RCS can do all sorts of funky things with 
revisions, releases, etc, but I think that the basic checkout/checkin 
mechanism will provide us with the features that we need without too 
many headaches.


SPECIAL LINES TO BE PUT IN EACH FILE

RCS can add your log entry, i.e. the stuff that you type in when you
check in the file, to the file itself. This means that the file
would automatically be commented with a note about all modifications,
as well as their author and the time that they were made. In order for
this to work, each RCS-ed file should have the following header:

For .c and .h files:


/*
 *   THIS FILE IS UNDER RCS - DO NOT MODIFY UNLESS YOU HAVE
 *   CHECKED IT OUT USING THE COMMAND CHECKOUT.
 *
 *    $Id: $
 *
 *    Revision history:
 *     $Log: $
 */


For makefiles, .d, .desc, and any other files where # is comment

#
#   THIS FILE IS UNDER RCS - DO NOT MODIFY UNLESS YOU HAVE
#   CHECKED IT OUT USING THE COMMAND CHECKOUT.
#
#    $Id: $
#
#    Revision history:
#     $Log: $
#


This file is /home/earthworm/RCS_README.txt
