This file documents Rcs, a GNU Emacs RCS interface.

Copyright (C) 1991, 1992 Sebastian Kremer

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled "GNU General Public License" is included exactly as
in the original, and provided that the entire resulting derived work is
distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the section entitled "GNU General Public License" may be
included in a translation approved by the author instead of in the
original English.

This manual documents `rcs.el', a GNU Emacs interface to the RCS
revision control system.

Revision of this manual:
     $Id: rcs.texi,v 1.18 1992/02/10 10:30:35 sk Exp $

Report bugs to:
     sk@thp.uni-koeln.de (Sebastian Kremer)

Rcs, a GNU Emacs RCS interface
******************************

`rcs.el' provides a convenient, automated, often nearly transparent
way to use the Revision Control System (RCS) source-code management
utilities.

When the library is loaded and the variable `rcs-active' is
non-nil, Emacs will notice and respond appropriately to RCS files
associated with the files you visit.  These RCS files will be found
either in the same directory as the files you are working with, or
(preferentially, for organization's sake) in an `RCS' subdirectory
of that directory.

See the manual pages of rcs(1) for information about how RCS itself
works. `rcs.el' assumes that you are using strict locking in RCS,
which is necessary to derive the full benefits of its protection.
`rcs.el' is known to work with RCS 5.5 and 5.6, and should also
work with earlier versions of RCS.

ChangeLog and RCS log::	 * Rcs Customization Variables::	 * Hooks
Used by Rcs::		 * Installation of Rcs::		 *
Acknowledgement::

Overview of Rcs
===============

Editing RCS controlled files in Emacs works like this:

The minor mode part of the modeline displays the head revision number
`REV' if a file is RCS controlled, but currently unlocked, or
a list of lockers (in the format `LOCKER:REV') if it is
currently locked.  Usually you just use `C-x C-q' to start editing
an RCS controlled file (making it writable by checking out a locked
revision) and `C-c I' to check in a new (or initial) revision.

These two commands suffice for most day-to-day usage, but additional
commands exist to give info about RCS files (`C-c D' to `rcsdiff', `C-c
L' to show the RCS log), to unlock a file you have begun to edit (`C-c
U'), and to show all locked files in a directory (`C-c W').

If a working file you want to visit does not exist but can be created by
checking out an RCS file, Emacs automatically does that.  You are asked
if you want to lock the file for editing, i.e., if you intend to modify
that file.  If you answer `y' or `SPC', the file will be
RCS-locked and thus writable for editing. If you answer `n' or
`DEL' an unlocked read-only copy will be checked out.  If you abort
from the prompt by typing `C-g', no file will be checked out from
RCS.  You should probably kill the empty buffer that results from
aborting `find-file' in this case.

If any RCS operation initiated by rcs-mode fails or generates unexpected
output, an error is signalled, and the RCS output is displayed in a
buffer.

This is nearly everything you need to know to start using `rcs.el'.
The remaining sections give more detailed information about each
command, how `rcs.el' hooks itself into Emacs and the user options.

Rcs Commands
============

Most commands accept a prefix argument `C-u' to mean that the
switches passed to the underlying RCS program (`rcsdiff', `ci'
etc.) are to be edited.  You are prompted for the switches in the
minibuffer.  Multiple switches can be entered on the same line,
separated by whitespace.  The arguments are *not* passed to a
shell: the string is split on whitespace and each component is one
argument.

With this method, there is no way to include space in an argument.
Usually this is not important, but sometimes you want to be able to
include spaces, e.g., for the `rlog -t' command.  Therefore, there
is an escape to "line mode": if you enter a single space instead of a
switch, you are prompted for each switch separately, until you just
enter a `RET' by itself.

However, be warned that adding arbitrary switches to commands is a very
powerful, but also potentially dangerous feature.  You should always
know what your are doing when adding switches of your own, especially
for the `rcs', `ci' or `co' commands, which (unlike the
`rcsdiff' or `rlog' commands) can affect your files.

Unless you set the variable `rcs-bind-keys' to `nil' before
loading `rcs.el', the following keys will be bound:

`C-x C-q'
     (`rcs-toggle-read-only') If the buffer being changed is under RCS
     control, prompt if you want to perform the corresponding RCS action,
     namely, checking out a locked version of the file to make it writable.
     Once a file is locked, you can toggle its read-only status without
     affecting its RCS status.

     In non-RCS buffers this behaves like the usual `C-x C-q'
     (`toggle-read-only') command.

`C-c I'
     (`rcs-check-in') lets you check in a file.  The file is
     unlocked unless a prefix argument is given, see below.  It prompts
     you for the name of the file, defaulting to the current buffer's
     file.  But you can also check in any other file.

     The log message is prompted for in the minibuffer.  Since the string is
     passed directly to the `ci' program, no shell quoting is necessary
     and multiline messages are possible.  You can use `C-x ^' to enlarge
     the minibuffer, or `yank' (`C-y') previously edited text into
     the minibuffer, e.g., from a `ChangeLog' buffer.  It is also
     possible to use a separate buffer to edit the log by setting
     `rcs-read-log-function' to
     `rcs-read-log-string-with-recursive-edit',
     see Rcs Customization Variables.

     If you have just created a file, and it has not yet been put under
     RCS control, this command is the only way you can do so.

     If `rcs-check-in' is given a prefix argument, it will first let you
     edit the switches used, with `-l' as default to retain your lock.
     Use this to check in a version but continue editing the file.  You can
     also specify the revision number here to create a new major revision
     level, e.g., use `-u3.0' to check in as revision 3.0, unlocked.

     If you want to force a checkin even if the file did not change, add
     `-f' to the switches.  You could also do
          (setq rcs-default-ci-switches '("-f"))
     in your `~/.emacs' if you always wanted this behaviour.

`C-c O'
     (`rcs-check-out') retrieves the current version of a file from
     RCS.  With a prefix argument you can specify the `co'
     switches, defaulting to `-l' to lock it for edit.  Mostly
     `C-x C-q' is used to check out a file, but `C-c O' is
     useful if you have an older version of the file present in your
     directory, since `find-file' will just load that.  The prefix
     argument can also be used to specify a version to check out, using
     the `-r' switch of the `co' program, e.g., use
     `-r2.5' to check out revision 2.5.

`C-c D'
     (`rcs-diff') creates a buffer showing the differences between the
     version of a file you are editing and the last version that was
     checked in to RCS.  With a prefix argument you can specify the diff
     switches used, see also variable `rcsdiff-switches', see Rcs Customization Variables.
     Useful if you do not remember what you
     changed, and want to provide a descriptive log entry when you check
     it back in.

`C-c U'
     (`rcs-unlock') releases your RCS write lock on a given file; this
     is different from checking the file in because no new version of
     the file is created, and any changes that you have made will be
     *discarded*.  If you have not actually made any changes, this
     operation is completed silently.  However, if you *have* made
     changes, `rcs.el' will present you with a buffer showing you the
     changes that you have made (much as does `rcs-diff') and ask you to
     confirm that you want to discard the changes.

     Currently it is not possible to break someone else's lock with
     `rcs.el' since `rcs -u' requires you to interactively compose
     a mail message for this.  RCS 5.7 may offer a possibility to suppress
     the mail or take it from a file or from the commandline.

`C-c L'
     (`rcs-log') presents you with a buffer showing the log information
     for all versions of a given RCS file.  You may use a prefix
     argument to give additional switches to the `rlog' program (e.g.
     `-h' to just show the head revision).

`C-c S'
     (`rcs-status') displays a brief message in the mode-line showing
     the lock status of a given file.  If the file is not under RCS
     supervision (i.e., no RCS control `,v' file for it exists) or the
     file is not locked, this is stated.  If the file has been locked by
     someone, their username and the version they have locked are displayed.
     As a side effect, the file has its modeline updated if it is currently
     visited in Emacs.

     Usually you just look at the modeline to find out the RCS status,
     but this command can also be used to describe files not currently
     visited in Emacs.

     With a prefix argument, this command changes instead of queries the RCS
     status.  It prompts for arguments to be passed to the `rcs'
     program.  Multiple switches can be entered separated by whitespace.
     See Overview of Rcs, for how to include whitespace in a switch.

     For example, if you want to start using a different branch for a file,
     you would enter `-bBRANCH' to the prompt.  The command
     executed will be `rcs -bBRANCH -q FILENAME'.  If
     `rcs' makes output in spite of the `-q' flag this means an
     error has occurred, which is reported in the usual way.  The modeline is
     not automatically updated, thus you might want to do a status query
     right afterwards, depending on the sort of status change you requested.

     If you want to give a description to a file , type `C-u C-c S',
     enter the filename and `RET', and enter a single `SPC' to
     the prompt for the switches.  This puts you into "line mode",
     allowing you to enter `-t-Descriptive Text', where there may
     be spaces in the descriptive text (something not possible if you
     had not escaped to line mode).  You can even enter multiline text
     by using `C-q C-j' to do a quoted insert of a newline, since
     `RET' would finish your input.

`C-c W'
     (`rcs-who') presents a buffer showing the status of each locked
     file in a directory, showing who the locker is, and what version is
     locked.  If no files are locked or there are no RCS controlled
     files at all, this is stated.

ChangeLog and RCS log
=====================

Accompanying `rcs.el', an enhanced version of `add-log.el' is
shipped.  It was modified from the Emacs 18.55 version to endorse the
GNU coding standards and work together with `rcs.el'.  (It will
also work without `rcs.el'.)  The advantage over the old version is
that it automatically adds the filename, the current defun and the RCS
level to the entry, like this:

     	* rcs.el,v 1.52
     	(rcs-unlock):

You just have to enter the descriptive text, everything else is already
there.  If the guessed defun is not appropriate, `C-w'
(`kill-region') will wipe it out, since the mark was dropped at the
beginning of the inserted defun.

The ChangeLog is set up so that

   * all the entries for one day make up a page (use `C-x ['
     (`backward-page') and `C-x ]' (`forward-page') to move to next day)

   * each entry for one file is a separate paragraph (use `M-['
     (`backward-paragraph') and `M-]' (`forward-paragraph') to move by
     entries and `ESC h' (`mark-paragraph') to mark an entry)

You can use either `C-x a' or `C-x 4 a' to add a ChangeLog for
the current file and defun:

`C-x a'
     (`add-change-log-entry')
     Find change log file and add an entry for current day, file and defun.

     First argument (interactive prefix) non-nil means prompt for user, site and
     log file.

     If there is an empty entry (just a `*') it is used and filled in
     with the current filename and defun.  Else, if there is an entry of
     today for the same file, it is used and a new line for the current defun
     is added at the beginning.  Else, a new entry is created.

     Thus you can force using a new entry by first creating an empty entry
     with `C-x a' (`add-change-log-entry') from the ChangeLog buffer
     itself, even if there is already an entry from today for the current
     file.  This is useful if you check in two RCS revisions on the same day.

     When called from a lisp, second arg is file name of change log.
     Optional third arg OTHER-WINDOW non-nil means visit in other window.

`C-x 4 a'
     (`add-change-log-entry-other-window')
     Like `add-change-log-entry', but in other window.

This variable determines RCS revision level formatting in ChangeLogs:

`add-change-log-entry-rcs-format'
     Default: `",v %s"'

     Format used by `add-change-log-entry' to insert RCS revision levels.

     Besides a format string, it can also be a function of zero arguments
     to return the formatted revision level of the current buffer's file or
     nil.  This can be used to hook in arbitrary RCS packages.

     If it is a string, it is assumed you are using sk's `rcs.el' (but
     it does not hurt if you do not, you just do not get any revision levels
     inserted).

`add-log.el' tries to guess the name of the "defun" (or more
generally speaking, the section of a document) the cursor was in before
you made the ChangeLog entry:

`add-log-current-defun-header-regexp'
     Default: `"^\\([A-Z][A-Z_ ]+\\|[a-z_---A-Z]+\\)[ 	]*[:=]"'

     Heuristic regexp used by `add-log-current-defun' for unknown major
     modes.

`add-log-current-defun'
     Return name of function definition point is in, or nil.

     Understands Lisp, LaTeX ("defuns" are chapters, sections, ...),
     texinfo (@node titles), and C.

     Other modes are handled by a heuristic that looks in the 10K before
     point for uppercase headings starting in the first column or identifiers
     followed by `:' or `='.

     Has a preference of looking backwards.

Here is one way of combining ChangeLogs and RCS logs: After doing
changes to an RCS locked file, while it is still locked, use `C-x 4
a' to insert an entry.  Compose the log message describing your changes.
You might want to do `C-c D' to look at the diffs to the last
checked-in version for this.  Update the inserted revision level.
Usually this just means incrementing it by one, but you might want to
check it in with a new major revision number.  For example, the log might
look like

     	* rcs.texi,v 1.16
     	(ChangeLog and RCS log):
and you would change it to

     	* rcs.texi,v 1.17
     	(ChangeLog and RCS log):
Since `add-log.el' cannot know whether you are going to check in
with a new major revision number (or whether you do ChangeLogs after or
before RCS check in), this is not done automatically.
When you are finished with composing your log message, put it into the
kill ring using `M-w' (`copy-region-as-kill'), do the check-in
using `C-c I' and yank the log message into the minibuffer.

That way, by doing the ChangeLog before the RCS log, you can compose
your log message in the ChangeLog buffer without having to worry about
recursive edits or having to cope with multiline minibuffer editing.

Rcs Customization Variables
===========================

The following variables can be used to customize `rcs.el':

`rcs-bind-keys'
     Default: t

     If nil, `rcs.el' will not bind any keys.  This variable has to be
     set before rcs.el is loaded, see Installation of Rcs, for an example.

`rcs-active'
     Default: t

     If non-nil, RCS controlled files are treated specially by Emacs.  You
     can set this to nil to disable `rcs.el' completely, even after it
     has already been loaded.

`rcs-ange-ftp-ignore'
     Default: t

     If non-nil, remote ange-ftp files are never considered RCS controlled.
     This saves a lot of time for slow connections.

     Ange-ftp is package for transparent FTP access within GNU Emacs.  The
     latest version of ange-ftp can always be obtained via anonymous ftp from

          ftp.gnu.ai.mit.edu:ange-ftp/ange-ftp.el.Z

     or by email from its author, ange@hplb.hpl.hp.com (Andy Norman).

`rcsdiff-switches'
     Default: nil

     If non-nil, a string specifying switches to be be passed to `rcsdiff'.
     A list of strings (or nil) means that the commandline can be edited
     after inserting those strings.

`rcs-default-co-switches'
     Default: nil

     List of switches (strings) for co(1) to use on every `rcs-check-out'.

`rcs-default-ci-switches'
     Default: nil

     List of switches (strings) for ci(1) to use on every `rcs-check-in'.

`rcs-default-rlog-switches'
     Default: nil

     List of switches (strings) for rlog(1) to use on every `rcs-log'.

`rcs-read-log-function'
     Default: nil

     If non-nil, function of zero args to read an RCS log message.  If nil,
     log messages are read from the minibuffer.  To be able to enter and edit
     log strings in a separate buffer, put

          (setq rcs-read-log-function
                'rcs-read-log-string-with-recursive-edit)

     in your `~/.emacs'.  The function
     `rcs-read-log-string-with-recursive-edit' is predefined for this
     purpose.

Hooks Used by Rcs
=================

This section explains how RCS hooks itself into Emacs. It is not
necessary to read it to be able to use `rcs.el'.

`rcs.el' installs itself in two hooks that customize Emacs'
file-manipulation behavior: `find-file-not-found-hooks' and
`find-file-hooks'.

Automatic Checkout of Working Files
-----------------------------------

The first hook (`rcs-file-not-found', installed in
`find-file-not-found-hooks') is called when a `find-file'
request fails because the file is not found.  It checks to see if there
is an RCS file corresponding to the file requested, and offers to check
that file out for you.  It makes sense for this to be the first hook
that Emacs tries, since it will only prompt you if the RCS file actually
exists, and you will usually want to check it out in those instances.
If you reply negatively, the remaining file-not-found hooks you may have
installed will be tried until one succeeds (these may, for example,
offer to create a default header for the file based on a boilerplate,
etc.).  `rcs.el' will install its own hook at the beginning of this
list; you should make sure that any other libraries you load after
`rcs.el' append their own hooks to the *end* of the list.

The Modeline
------------

The second hook (`rcs-load-postprocessor', installed in
`find-file-hooks') is a very simple routine which is called once a
file has been loaded.  It checks to see whether that file is under RCS'
supervision, and whether you currently have a lock on the file (that is,
you are the person who checked it out for editing).  If so, it puts the
buffer into the minor mode `rcs-mode' and displays either the head
revision level or the current locker and locked revision in the format
`LOCKER:REV' in the mode line.  If there are several
locks, they will be displayed with a space between each of them.  For
similar reasons to those outlined above, this should be the first hook
in the `find-file-hooks' list.  (There is an exception: if you are
using Ashwin Ram's `infer-file-mode' code, which also hooks into
`find-file-hooks', just make sure that `infer-file-mode'
occurs first in the list of hooks by loading `rcs.el' before
pushing `infer-file-mode' onto the hooks list.  Otherwise a major
mode change in `infer-file-mode' will kill all local variables,
including the RCS modeline variables.)

You may also call `rcs-load-postprocessor' interactively to refresh
the modeline, e.g., after a major mode change that killed all local
variables.  Alternatively, just requesting the RCS status of a file
using `C-c S' (`rcs-status') will also update its modeline.

When `rcs.el' is active, and you are editing RCS-controlled files, the
read-only status of the file buffer is synonymous with the file's locked
status within RCS.  That is, if you have a file locked for edit, it will
be writable.  Otherwise, it will be read-only.  Buffers not associated
with RCS files continue to behave as they used to.

The key sequence `C-x C-q' (`toggle-read-only') is remapped to call
`rcs-toggle-read-only', which will ask if you want to check out an
RCS-controlled file if its buffer was read-only and you do not presently
have a lock on that file.  Once you have checked a file out for edit,
you can toggle the read-only status of the buffer repeatedly without
changing its RCS status, but there is probably no pressing reason why
you would want to do this.

The automatic behavior outlined above---noticing files are available
from RCS and offering to check them out, and locking them for edit when
you hit the toggle-read-only key, will address most of the needs of RCS
users in day-to-day development.

Installation of Rcs
===================

Your system manager should have installed the package and the manual in
the correct place, as described in the `rcs.README' file that comes
with the distribution.

To use `rcs.el', simply load it from your `~/.emacs':

     (load "rcs")

Additionally, you can customize variable by adding a line like

     (setq rcsdiff-switches "-u") ; or whatever you prefer
     ;; you can change key bindings here or set some other variables

If you do not like the key bindings established by default, here is an
example of how to chose your own bindings:
     (setq rcs-bind-keys nil)     ; prevent rcs.el from binding any keys
     (load "rcs")
     ;; chose your own key bindings
     ;; here with lower instead of upper case keys:
     (global-set-key "\C-cd" 'rcs-diff)
     (global-set-key "\C-ci" 'rcs-check-in)
     (global-set-key "\C-cl" 'rcs-log)
     (global-set-key "\C-co" 'rcs-check-out)
     (global-set-key "\C-cs" 'rcs-status)
     (global-set-key "\C-cu" 'rcs-unlock)
     (global-set-key "\C-cw" 'rcs-who)
     ;; you will almost always want to bind this:
     (global-set-key "\C-x\C-q" 'rcs-toggle-read-only)

`rcs.el' cannot be autoloaded since it must be present in the
various find-file hooks before the first potentially RCS controlled file
is visited in Emacs.

Acknowledgement
===============

`rcs.el' was originally written in 1990 by James Elliott
<elliott@cs.wisc.edu>.  I think he invented the overloading of `C-x
C-q' to check out a locked file.

Around November 1990 I started to modify it to display the lockers
(instead of just `RCS') in the modeline, to fix some bugs, and to
make it work with newer versions of RCS.  In 1991 I systematically
rewrote the code, added the possibility to add switches to all RCS
commands, and wrote the manual.

My thanks go to James Elliott for writing the original `rcs.el',
Paul Eggert <eggert@twinsun.com> (Author of RCS 5) for helpful comments
and advance notes about new RCS releases, and all those who reported
bugs or suggested features.

Index
*****

Index of variables, functions, keys and concepts used in `rcs.el':