Rcs(3pm)

📦

version 1.05 · 2 versions

1.05 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
1.05 · ubuntu jammy

, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

Rcs(3pm) — from the User Contributed Perl Documentation, bestie 💖

✨ NAME ✨

Rcs — Perl Object Class for Revision Control System (RCS).

🌸 SYNOPSIS 🌸

okay so here's how you pull it in:

use Rcs;

# Use tags to control how the rcs programs handle errors
# and the use of the rcs -q (quiet) flag.
use Rcs qw(nonFatal Verbose);

default behavior? it runs rcs programs with the -q (quiet) flag, and it will die if any rcs program returns an error. that's the vibe.

💖 DESCRIPTION 💖

This Perl module gives you an object oriented interface to access Revision Control System (RCS) utilities. RCS must be installed on the system prior to using this module. This module should simplify the creation of an RCS front-end. slay.

🎀 OBJECT CONSTRUCTOR 🎀

The new method may be used as either a class method or an object method to create a new object.

# called as class method
$obj = Rcs->new;

# called as object method
$newobj = $obj->new;

Note: You may now set the pathname of the working file through the object constructor. This is the same as calling the pathname method after calling the new method.

Thus

$obj = Rcs->new($pathname);

is the same as

$obj = Rcs->new;
$obj->pathname($pathname);

See pathname method for additional details.

🧚 CLASS METHODS 🧚

Besides the object constructor, there are three class methods provided which effect any newly created objects.

arcext — sets the RCS archive extension, which is ',v' by default.

# set/unset RCS archive extension
Rcs->arcext('');            # set no archive extension
Rcs->arcext(',v');          # set archive extension to ',v'
$arc_ext = Rcs->arcext();   # get current archive extension

bindir — sets the directory path where the RCS executables (i.e. rcs, ci, co) are located. The default location is '/usr/local/bin'.

# set RCS bin directory
Rcs->bindir('/usr/bin');

# access RCS bin directory
$bin_dir = Rcs->bindir;

quiet — sets/unsets the quiet mode for the RCS executables. Quiet mode is set by default.

# set/unset RCS quiet mode
Rcs->quiet(0);      # unset quiet mode
Rcs->quiet(1);      # set quiet mode

# access RCS quiet mode
$quiet_mode = Rcs->quiet;

These methods may also be called as object methods.

$obj->arcext('');
$obj->bindir('/usr/bin');
$obj->quiet(0);

💅 OBJECT ATTRIBUTE METHODS 💅

These methods set the attributes of the RCS object.

file — used to set the name of the RCS working file. The filename must be set before invoking any access of modifier methods on the object.

$obj->file('mr_anderson.pl');

arcfile — used to set the name of the RCS archive file. Using this method is optional, as the other methods will assume the archive filename is the same as the working file unless specified otherwise. The RCS archive extension (default ',v') is automatically added to the filename.

$obj->arcfile('principle_mcvicker.pl');

workdir — sets the path of the RCS working directory. If not specified, default path is '.' (current working directory).

$obj->workdir('/usr/local/source');

rcsdir — sets the path of the RCS archive directory. If not specified, default path is './RCS'.

$obj->rcsdir('/usr/local/archive');

pathname — will set both the working filename and archive directory.

$obj->pathname($RCS_DIR . '/' . 'butthead.c');

and

$obj->pathname($RCS_DIR . '/' . 'butthead.c,v');

are the same as

$obj->rcsdir($RCS_DIR);
$obj->file('butthead.c');

🔥 RCS PARSE METHODS 🔥

This class provides methods to directly parse the RCS archive file.

access — returns a list of all user on the access list.

@access_list = $obj->access;

author — returns the author of the revision. The head revision is used if no revision argument is passed to method.

# returns the author of revision '1.3'
$author = $obj->author('1.3');

# returns the authos of the head revision
$author = $obj->author;

(ngl the original comment says authos — we keep code verbatim, periodt.)

head — returns the head revision.

$head = $obj->head;

lock — returns the locker of the revision. The method returns null if the revision is unlocked. The head revision is used if no revision argument is passed to method. When called in list context the lock method returns a hash of all locks.

# returns locker of revision '1.3'
$locker = $obj->lock('1.3');

# returns locker of head revision
$locker = $obj->lock;

# return hash of all locks
%locks = $obj->lock;    # called in list context
foreach $rev (keys %locks) {
    $locker = $locks{$rev};
    print "User $locker has revision $rev locked\n";
}

revisions — returns a list of all revisions of archive file.

@revisions = $obj->revisions;

state — returns the state of the revision. The head revision is used if no revision argument is passed to method.

# returns state of revision '1.3'
$state = $obj->state('1.3');

# returns state of head revision
$state = $obj->state;

symbol — returns the symbol(s) associated with a revision. If called in list context, method returns all symbols associated with revision. If called in scalar context, method returns last symbol associated with a revision. The head revision is used if no revision argument is passed to method.

# list context, returns all symbols associated with revision 1.3
@symbols = $obj->symbol('1.3');

# list context, returns all symbols associated with head revision
@symbols = $obj->symbol;

# scalar context, returns last symbol associated with revision 1.3
$symbol = $obj->symbol('1.3');

# scalar context, returns last symbol associated with head revision
$symbol = $obj->symbol;

symbols — returns a hash, keyed by symbol, of all of the revisions associated with the file.

%symbols = $obj->symbols;
foreach $sym (keys %symbols) {
    $rev = $symbols{$sym};
}

revdate — returns the date of a revision. The returned date format is the same as the localtime format. When called as a scalar, it returns the system date number. If called in list context, the list ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) is returned.

# scalar mode
$scalar_date = $obj->revdate;
print "Scalar date number = $scalar_date\n";
$date_str = localtime($scalar_date);
print "Scalar date string = $date_str\n";

# list mode
@list_date = $obj->revdate;
print "List date = @list_date\n";

dates — returns a hash of revision dates, keyed on revision. The hash values are system date numbers. When called in scalar mode, the method returns the most recent revision date.

# list mode
%DatesHash = obj->dates;
@dates_list = sort {$b<=>$a} values %DatesHash;
$MostRecent = $dates_list[0];

# scalar mode
$most_recent = $obj->dates;
print "Most recent date = $most_recent\n";
$most_recent_str = localtime($most_recent);
print "Most recent date string = $most_recent_str\n";

(yes bestie that's obj->dates not $obj->dates — keep it exactly as the manpage says, no cap.)

symrev — returns the revision against which a specified symbol was defined. If the symbol was not defined against any version of this file, 0 is returned.

# gets revision that has 'MY_SYMBOL' defined against it
$rev = $obj->symrev('MY_SYMBOL');

daterev — returns revisions which were created before a specified date. Method may take one or six arguments. If one arguments is passed, then the argument is a date number. If six arguments are passed, then they represent a date string.

# one argument, date number
# gets revisions created before Sun Sep  6 22:23:47 1998
@revs = $obj->daterev(841436420);

# six argument
# gets revisions created before 25th June 1998 16:45:30
@revs = $obj->daterev(1998, 6, 25, 16, 45, 30);

comments — returns a hash of revision comments, keyed on revision. A key value of 0 returns the description.

%comments = $obj->comments;
$description = $comments{0};
$comment_1_3 = $comments{'1.3'};

👑 RCS SYSTEM METHODS 👑

These methods invoke the RCS system utilities.

ci — calls the RCS ci program.

# check in, and then check out in unlocked state
$obj->ci('-u');

co — calls the RCS co program.

# check out in locked state
$obj->co('-l');

rcs — calls the RCS rcs program.

# lock file
$obj->rcs('-l');

rcsdiff — calls the RCS rcsdiff program. When called in list context, this method returns the output of the rcsdiff program. When called in scalar context, this method returns the return status of the rcsdiff program. The return status is 0 for the same, 1 for some differences, and 2 for error condition.

When called without parameters, rcsdiff does a diff between the current working file, and the last revision checked in.

# call in list context
@diff_output = $obj->rcsdiff;

# call in scalar context
$changed = $obj->rcsdiff;
if ($changed) {
    print "Working file has changed\n";
}

Call rcsdiff with parameters to do a diff between any two revisions.

@diff_output = $obj->rcsdiff('-r1.2', '-r1.1');

rlog — calls the RCS rlog program. This method returns the output of the rlog program.

# get complete log output
@rlog_complete = $obj->rlog;

# called with '-h' switch outputs only header information
@rlog_header = $obj->rlog('-h');
print @rlog_header;

rcsclean — calls the RCS rcsclean program.

# remove working file
$obj->rcsclean;

✨ EXAMPLES ✨

okay bestie, this is the part where it all comes together, like the montage scene in a movie where the main character finally figures out the choreography 💅 every single one of these is a real, runnable little vibe, so grab your snack and let's go.

🌸 CREATE ACCESS LIST

Using method rcs with the -a switch allows you to add users to the access list of an RCS archive file. yes, literally, it's giving "let me in" but consensual and version-controlled 🫶

use Rcs;
$obj = Rcs->new;

$obj->rcsdir("./project_tree/archive");
$obj->workdir("./project_tree/src");
$obj->file("cornholio.pl");

Method rcs invokes the RCS utility rcs with the same parameters. it's not doing anything sneaky, it's just relaying the message like the world's most reliable group chat admin ✨

@users = qw(beavis butthead);
$obj->rcs("-a@users");

Calling method access returns list of users on access list. the guest list, basically 👑

$filename = $obj->file;
@access_list = $obj->access;
print "Users @access_list are on the access list of $filename\n";

📖 PARSE RCS ARCHIVE FILE

Set class variables and create 'RCS' object. Set bin directory where RCS programs (e.g. rcs, ci, co) reside. The default is '/usr/local/bin'. This sets the bin directory for all objects. no cap, all of them 🫠

use Rcs;
Rcs->bindir('/usr/bin');
$obj = Rcs->new;

Set information regarding RCS object. This information includes name of the working file, directory of working file ('.' by default), and RCS archive directory ('./RCS' by default). look at those defaults just doing their little jobs 💖

$obj->rcsdir("./project_tree/archive");
$obj->workdir("./project_tree/src");
$obj->file("cornholio.pl");

$head_rev = $obj->head;
$locker = $obj->lock;
$author = $obj->author;
@access = $obj->access;
@revisions = $obj->revisions;

$filename = $obj->file;

if ($locker) {
    print "Head revision $head_rev is locked by $locker\n";
}
else {
    print "Head revision $head_rev is unlocked\n";
}

if (@access) {
    print "\nThe following users are on the access list of file $filename\n";
    map { print "User: $_\n"} @access;
}

print "\nList of all revisions of $filename\n";
foreach $rev (@revisions) {
    print "Revision: $rev\n";
}

it's giving detective energy honestly, pulling every fact out of the archive one method at a time 🔍

✅ CHECK-IN FILE

Set class variables and create 'RCS' object. Set bin directory where RCS programs (e.g. rcs, ci, co) reside. The default is '/usr/local/bin'. This sets the bin directory for all objects.

use Rcs;
Rcs->bindir('/usr/bin');
Rcs->quiet(0);      # turn off quiet mode
$obj = Rcs->new;

Set information regarding RCS object. This information includes name of the working file, directory of working file ('.' by default), and RCS archive directory ('./RCS' by default).

$obj->file('cornholio.pl');

# Set RCS archive directory, is './RCS' by default
$obj->rcsdir("./project_tree/archive");

# Set working directory, is '.' by default
$obj->workdir("./project_tree/src");

Check in file using -u switch. This will check in the file, and will then check out the file in an unlocked state. The -m switch is used to set the revision comment. it's giving "drop it off and immediately take it back but unbothered" energy 😌

Command:

$obj->ci('-u', '-mRevision Comment');

is equivalent to commands:

$obj->ci('-mRevision Comment');
$obj->co;

same outcome, two paths, both iconic 🌈

🎀 CHECK-OUT FILE

Set class variables and create 'RCS' object. Set bin directory where RCS programs (e.g. rcs, ci, co) reside. The default is '/usr/local/bin'. This sets the bin directory for all objects.

use Rcs;
Rcs->bindir('/usr/bin');
Rcs->quiet(0);      # turn off quiet mode
$obj = Rcs->new;

Set information regarding RCS object. This information includes name of the working file, directory of working file ('.' by default), and RCS archive directory ('./RCS' by default).

$obj->file('cornholio.pl');

# Set RCS archive directory, is './RCS' by default
$obj->rcsdir("./project_tree/archive");

# Set working directory, is '.' by default
$obj->workdir("./project_tree/src");

Check out file read-only:

$obj->co;

or check out and lock file:

$obj->co('-l');

read-only is the "look but don't touch" and -l is the "mine, actually" 🔒 both valid, bestie, pick your moment.

🔍 RCSDIFF

Method rcsdiff does an diff between revisions. ngl it's the little spot-the-difference game but for your files 👀

$obj = Rcs->new;
$obj->bindir('/usr/bin');

$obj->rcsdir("./project_tree/archive");
$obj->workdir("./project_tree/src");
$obj->file("cornholio.pl");

print "Diff of current working file\n";
if ($obj->rcsdiff) {       # scalar context
    print $obj->rcsdiff;   # list context
}
else {
   print "Versions are Equal\n";
}

print "\n\nDiff of revisions 1.2 and 1.1\n";
print $obj->rcsdiff('-r1.2', '-r1.1');

note the whole scalar-context vs list-context thing, it's literally switching personalities depending on how you call it 😭

🧹 RCSCLEAN

Method rcsclean will remove an unlocked working file. bye bestie, you were unlocked so you gotta go 💀

use Rcs;
Rcs->bindir('/usr/bin');
Rcs->quiet(0);      # turn off quiet mode
$obj = Rcs->new;

$obj->rcsdir("./project_tree/archive");
$obj->workdir("./project_tree/src");
$obj->file("cornholio.pl");

print "Quiet mode NOT set\n" unless Rcs->quiet;

$obj->rcsclean;

👑 AUTHOR

Craig Freter, <craig@freter.com>

🫶 CONTRIBUTORS

David Green, <greendjf@cvhp152.gpt.marconicomms.com>

Jamie O'Shaughnessy, <jamie@thanatar.demon.co.uk>

Raju Krishnamurthy, <raju_k@iname.com>

⭐ COPYRIGHT

and that's the whole page, bestie 💖 this one's from perl v5.34.0, dated 2022-06-17, and it's the Rcs(3pm) page — go forth and version-control your little heart out, you've got this 🌸✨

📦 where this page comes from

debian bookworm: librcs-perl 1.05-6 · Artistic-1.0-Perl OR GPL-1.0-or-later
debian trixie: librcs-perl 1.05-6 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu noble: librcs-perl 1.05-6 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu resolute: librcs-perl 1.05-6 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: librcs-perl 1.05-6 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms