The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

magicrcs - automatically monitor directories & files and keep them under RCS

SYNOPSIS

Recommended usage:

magicrcs --dwim file | directory ...

OPTIONS

--cleanup OR -c

Try to clean up file permissions before script exits, assuming this is done with a polite SIGINT or SIGTERM. (See "SIGNALS".) Specifically, write permission is turned off RCS-controlled files, so that Emacs VC-mode will not subsequently be confused; RCS files are reverted to strict mode; and log files (under --log) are deleted.

--user=user OR -u user

Try to change ownership of modified working files back to user user. May fail unless run as root. File will be made user-writable whether this option is specified or not.

--group [ =group ] OR -g[group]

Like --user, but change group ownership, and also make sure file is group-writable. If group is omitted, just change the permission bit.

--recursive OR -r

Recursively monitor all subdirectories and files within specified directories. This flag only takes effect when this script starts up, and is analogous to something like:

  magicrcs `find dir1/ dir2/ ... -print` file1 file2 ...

except RCS subdirectories are excluded, &c.

--text OR -t

Only automatically start monitoring text files, not binary files. Useful if there are graphics, tar files, core dumps, &c. in the vicinity. Does not affect files explicitly mentioned on the command line.

--exclude=regex OR -x regex

Do not automatically start monitoring files or subdirectories whose names match this (Perl 5) regular expression. Should only be specified once, but that is what regex alternatives are for. Like --text.

You will almost certainly want this to include Emacs backup and autosave files; things like *.bak; etc.

--help OR -h

Show a synopsis.

--detach OR -d

Detach after starting, in daemon fashion. This is the recommended usage.

--syslog [ =level ] OR -s[level]

Log messages to SYSLOG rather than standard error. Only meaningful in daemon mode (--detach). Optional level (default INFO) sets logging level, which may affect visibility on the system log depending on its configuration (/etc/syslog.conf).

--log OR -l

Permit external-file log messages. See "Log Messages".

--verbose OR -v

Generate verbose messages about what is happening.

--wait=timeout OR -w timeout

Wait for timeout seconds of quiescence (default one second) before acknowledging further events on a file. This option may improve performance in some cases, though probably not dramatically. If it is too large, some changes to a file may not be noticed.

--dwim

Do What I Mean. Sets --cleanup, --log, --group, --recursive, --text, --exclude (to a reasonable value, as well as your own excludes if any), --detach, and --syslog.

DESCRIPTION

magicrcs is intended to run as a background process that will use the SGI File Access Monitor library to observe given files or directory trees and keep them transparently under RCS control. Files remain writable, but unlocked. Thus, the archival aspects of RCS can be retained in an environment where manual checkins and other operations are impractical.

Selecting the correct invoking user, and combination of --user and --group options, may require experimentation if this script is to be useful in a multiuser environment, due to complexities of permissions interactions. These two options will also attempt to set ownership of monitored directories and RCS control files.

You should be able to edit these files in Emacs even with VC Mode enabled (as it is by default); the RCS version at the time of first visitation will appear, and should be ignored as it will not stay in synch (unless you do a M-x revert-buffer). But do not try to check monitored files in or out explicitly with Emacs, or all hell will break loose; just save the buffer whenever you want (which should not be write-protected assuming you have user or group access to the file). Hopefully, there will not be problems. If you need to log a message, though, or perform any fancy RCS operations, you will want to shut down this script first (and probably wanted --cleanup specified to begin with).

For each file monitored...

Startup

The file is put under RCS if it is not already. This script expects the RCS file for foo to be named RCS/foo,v and may not work correctly if it is not.

File Changed

Each change event, i.e. each time the contents of the file are changed, will deposit a new RCS revision. The author and log message indicate that the checkin was automated.

Permissions on the file should be untouched, so you can continue editing freely.

File Deleted

Nothing happens to the RCS file. If the file is recreated, however, deposits will resume where they left off.

For each directory monitored...

Startup

This script will ensure the existence of an RCS subdirectory. Files currently in the directory, and subdirectories recursively, are also automatically monitored if you provide the --recursive flag, just as if they had been specified on the command line.

New File or Subdirectory

Monitoring begins on any new files or subdirectories (unless a file is binary and --text was specified, or it matches --exclude). Note that this happens whether --recursive was given or not. If you never want any new files to be put under RCS, you should not specify any directory names on the command line.

Subdirectory Deleted

Nothing special is done.

Log Messages

If --log is given, the script will permit external files to be used to create RCS log messages. For each file foo placed under RCS control, a separate file foo.log will be created. If you want to register a log message with an RCS deposit of foo, first write it into foo.log, save foo.log, then save foo. The contents of foo.log will be used for the RCS log message. If the first line is of the form:

-author

(a dash followed by some text) then author will be used as the RCS author, as well. The foo.log file is cleared (except for the author line, if present) after making the deposit.

You may save the log file at any time. It will only be used if the message has been re-entered since the last deposit.

SIGNALS

INT or TERM (Ctrl-C if undetached; else kill ...)

Stops the script, after cleaning up if requested.

TSTP and ALRM (kill -TSTP ... and kill -ALRM ...)

Suspend and resume (resp.); clean up and reinitialize as if the script were actually restarted. Handy if you need to do some special RCS operation but do not want to manually restart.

USR1 (kill -USR1 ...)

Log internal debugging information.

BUGS

Due to polling delays, monitoring NFS-mounted areas may be problematic if the NFS server is not also running Irix (or if it is just not running the FAM daemon). Try adjusting --wait to a larger amount according to the poll settings on your FAM daemon; this is typically set to six seconds to provide a balance of load minimization and accuracy, so --wait should be somewhat larger. See fam(1m).

There are probably a variety of miscellaneous bugs here and there.

The script is not as efficient as it could be; it sometimes invokes RCS gratuitously, usually at startup.

This should really use some RCS XSUB library.

SEE ALSO

See SGI::FAM(3) for the workings; for RCS, see rcsintro(1); for logging, syslog(3) and the resultant logfile, typically /var/adm/SYSLOG; regular expressions, see perlre(1).

AUTHORS

J. Glick jglick@sig.bsh.com.

REVISION

magicrcs last modified Thu, 25 Sep 1997 22:56:42 -0400 release 1.002. Copyright (c) 1997 Strategic Interactive Group. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.