Tags:
create new tag
, view all tags
RCS (Revision Control System) is the simplest system available in Linux to do revision control on program source code and other documents or files. (Text is handled well, binary data is cumbersome or worse.)

More complex / featureful alternatives include:

Not including a bunch of proprietary (not free) alternatives, like (to name just two): Microsoft SourceSafe, PCVS.

Revision control means keeping a record of all revisions to a particular document and allowing recovery of old versions.

I finally have a handle on how to use RCS (not all the details, but enough to start using it). There is at least one decision to make, see Where To Put the RCS Files.

Very shortly, I expect to start putting most files (ones I create or those I modify (like configuration files)) under RCS control — if I had done that already, I could at this point simply do a "checkpoint" checkin to save old text that I hate to see totally discarded while editing this page. (Aside, this is focused on my off line editing of TWiki pages and non-Twiki (or TWiki) configuration files, TWiki pages are already under RCS control, which works as long as I wait at least one hour between revisions (which I have not done so far for this page, nor will I preserve my offline drafts of this page, as I think I've incorporated all the salient points in this draft).

See:

Contents

Summary

In the directory containing (or to contain) the working file, e.g., <filename>.txt, issue:

rcs -i <filename>.txt

to create the repository (in the same directory). IIUC, you could issue rcs -i RCS/<filename>.txt to have the repository created in a subdirectory named RCS (oops, you'd probably have to create the directory first), and RCS would "automatically" find the repository in that subdirectory on subsequent commands (assuming, I guess, that there is not also a repository with the same name in the peer directory).

If not already created, create <filename>.txt and edit as desired. From that same directory, issue

ci <filename>.txt

to checkin the file (store a "copy" of the current version of the working file in the repository), note that this also deletes the current working file. If you want to continue to edit the working file, use ci -l instead, which will leave the working file (or do an immediate checkout (co -l). The -l (lock) option "locks" the file for editing.

<later:>

co <filename>.txt

to read the file, use co -l if you intend to edit the file, gives you rw permissions on the file (and "locks" it for editing (i.e., recheckin) only by you (the user that locked the file

Note on Nedit

The following is wrong, and not as easy as I thought, running ci from within Nedit is apparently what kept a copy of the working file and confused me. Need to revise after some more experimentation / learning.

AFAICT so far, it seems that commands run from Nedit's Shell | Execute Command menu option are run in the directory containing the file currently being edited, so rcs commands can be run from the menu option without needing to specify an absolute or relative directory (assuming the repository is in one of the default locations, i.e., the directory containing the file or a subdirectory named "RCS" of that directory).

Discussion

Terminology

working file
the file to be edited / version controlled

repository
another file, with the same name but (usually) with a ",v" suffix on the file extension, which contains the information necessary to reconstruct any previous version of the working file. The file is managed by RCS, and under normal circumstances you should not view or edit this file. It can be educational to view the file, and, during the course of a typical TWiki installation, there is a need to edit all the ",v" files for the TWiki content.

checkin
The act of saving a current copy of the working file to the repository with an automatically (or manual) assigned revision number.

checkout
The act of "creating" a copy of the working file at any particular revision level so that it can be viewed and possibly revised.

checkpoint (or checkpoint checkin)
The act of checking in a copy of the current working file with the intent of continuing to revise (work on) the file. You might do a checkpoint checkin when you have the file in a desirable state that you may wish to return to (maybe before or after some significant changes, just before testing, or similar). If the working file gets "destroyed" you can obtain a new working copy at the current state by doing a checkout.

revision number
The revision numbers in RCS are typically of the form 1.x, and normally start at revision 1.1. There are ways to adjust these revision numbers to some extent. See also CVS.#Tagging <ToDo: Correct this link, including the syntax>

Where To Put the RCS Files

The first thing to do is decide where to put the RCS files. The two easiest (i.e., default) locations are:

  • in the same directory as the working files
  • in a subdirectory of that directory named "RCS"

From man rcs:

-i
Create and initialize a new RCS file, but do not deposit any revision. If the RCS file has no path prefix, try to place it first into the subdirectory ./RCS, and then into the current directory. If the RCS file already exists, print an error message.

Alternatively, you can put them anywhere, but the syntax requires that you specify the paths (relative or absolute) to both the working and the ,v (RCS) file. Thus, you might need to type commands like:

ci /pfsetup/bin/rhksendmailq /pfsetup/rcs/rhksendmailq,v

If I did choose the latter approach, I would probably create a directory off the root named /rcs which would somewhat minimize the complexity of those commands. See next section.

Pros and Cons

Now, which approach do I want to follow? My initial thoughts were that, for example, by keeping the ,v files for all my revised configuration files in one directory (/RCS?), I would always have a centralized record of all the configuration changes I've made. An advantage of that is, by backing up the /RCS directory, I (hopefully, and yes, I know) have a record of all (file based) configuration changes to restore if necessary.

The problem is, it will require some self-discipline (and (personal) memory) to always specify the /rcs directory on a checkin, and to always be in (or at least specify) the correct directory for a checkout.

On the other hand (she wore a glove), maybe I can write a backup script that looks throughout, for example, the /etc hierarchy and backs up (one word?) any files ending in ,v (and/or, maybe the same files without the ,v).

The advantage of keeping the ,v files in the same directory as the "working" file is much easier syntax of the ci and co commands.

"Common" RCS Commands

A short summary of the common rcs commands (i.e., those I expect to use, at least initially):

ci [-r <major>.<minor] <working_file_name>

e.g., ci -r 1.5 rhksendmailq

co [-r <major>.<minor] <working_file_name>

e.g., co -r 1.5 rhksendmailq

rlog <working_file_name>

e.g., rlog rhksendmailq

Notes:

  • On checkin, a new RCS file starts at revision 1.1 unless otherwise specified (with the optional r argument)
  • On checkout, the latest working file is obtained unless an earlier version is specified (with the optional r argument)
  • On checkin, the working file is gone (incorporated in the RCS file), if you want to do a checkpoint checkin (i.e., checkin the revisions so far but continue editing), use the -l option (=ci -l ...).
  • If you checkout a file, it is read only unless you use the -l option.
  • I suspect (but don't know) that all of the commands listed above are aliases for variations of commands that start with "rcs" and various options. _Nope, not true. The rcs commands seem to do more esoteric things, like help create branches, name them, etc. See man rcs.

Source of My Learning about RCS

BTW, the initial "driving" source for my learning about RCS (besides seeing it used in TWiki) is "Linux: Programmer's Reference", 2nd Edition, by Richard Petersen, ISBN 0-07-212355-9, list $19.99, obtained for $2.99 at Ollie's (local closeout outlet). It was the first book that let me get a handle on make and RCS (and I'm working on tar and RPM), but, unfortunately, part of what I had to do was overcome some misleading statements in the book.

For example, the statement "To create an RCS file, you first create an RCS directory. ..." What might have been better (at the risk of using more words (and thereby turning me off)) would be to say that a first consideration in using RCS is deciding where to store the RCS (,v) files, here are the possibilities ..., some discussion of the advantages and disadvantages of each, and the command (variations) to do each.

And, even if he (they) didn't go that far, I got hung up on what an RCS directory is and where it needs to go. The book doesn't tell you, but:

  • a "default" RCS directory must be named "RCS"
  • the "default" version of the RCS commands look for an RCS file in the current working directory (or, more correctly, the directory containing the working file) or in a subdirectory (of that directory) named "RCS" -- see the quotation from the man page in Where To Put the RCS Files

I'm not really trying to denigrate this book or its author, at $2.99 it's an OK or better book, at $19.99 I would have been disappointed.

Contributors

  • () RandyKramer - 04 Dec 2003
  • If you edit this page: add your name here; move this to the next line; and if you've used a comment marker (your initials in parenthesis), include it before your WikiName.

Revision Comment

  • %DATE% —

Page Ratings

Edit | Attach | Watch | Print version | History: r6 < r5 < r4 < r3 < r2 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r6 - 2004-01-21 - RandyKramer
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by PerlCopyright 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding WikiLearn? WebBottomBar">Send feedback
See TWiki's New Look