\input texinfo    @c -*-texinfo-*-

@comment $Id: rcs.texi,v 1.23 1992/05/15 13:52:01 sk Exp $

@comment %**start of header (This is for running Texinfo on a region.)
@setfilename rcs.info
@settitle rcs
@c @setchapternewpage odd
@c Join all indices since this is a small manual
@synindex cp vr
@synindex fn vr
@synindex ky vr
@synindex pg vr
@synindex tp vr
@comment %**end of header (This is for running Texinfo on a region.)

@iftex
@finalout
@end iftex

@ifinfo
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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission notice
identical to this one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
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.
@end ifinfo

@titlepage
@sp 6
@center @titlefont{An}
@sp 1
@center @titlefont{RCS Interface}
@sp 1
@center @titlefont{for}
@sp 1
@center @titlefont{GNU Emacs}
@sp 15
@center Sebastian Kremer
@center sk@@thp.uni-koeln.de

@page
@noindent
$Date: 1992/05/15 13:52:01 $

@noindent
$Revision: 1.23 $

@vskip 0pt plus 1filll

Copyright @copyright{} 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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission notice
identical to this one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
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.
@end titlepage

@ifinfo

@node Top, A GNU Emacs RCS Interface, (dir), (dir)

@noindent
This manual documents @file{rcs.el}, a GNU Emacs interface to the RCS
revision control system.

@noindent
Revision of this manual:
@example
$Id: rcs.texi,v 1.23 1992/05/15 13:52:01 sk Exp $
@end example

@noindent
Report bugs (please include variable @code{rcs-version}'s value) to:
@example
sk@@thp.uni-koeln.de (Sebastian Kremer)
@end example

@end ifinfo

@menu
* A GNU Emacs RCS Interface::	
* Index::			

 --- The Detailed Node Listing ---

Rcs, a GNU Emacs RCS interface

* Overview of Rcs::		
* Rcs Commands::		
* ChangeLog and RCS log::	
* Rcs Customization::		
* Hooks Used by Rcs::		
* Installation of Rcs::		
* Acknowledgement::		
* Bugs::			Bugs, and a wish list

Rcs Customization

* Rcs Customization Variables::	 
* Default Switches for RCS Commands::  
* Hooks provided by Rcs::	

Hooks Used by Rcs

* Automatic Checkout of Working Files::	 
* Rcs Modeline Display::	
@end menu

@node A GNU Emacs RCS Interface, Index, Top, Top
@chapter Rcs, a GNU Emacs RCS interface

@vindex rcs-active
@noindent
@file{rcs.el} provides a convenient, automated, often nearly transparent
way to use the Revision Control System (RCS) source-code management
utilities.

@vindex rcs-active
When the library is loaded and the variable @code{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 @file{RCS} subdirectory
of that directory.  For example, in

@example
  /home/sk/lib/emacs/lisp:
  total 4973
  drwxr-sr-x   2 sk       users        2048 Feb  6 11:07 RCS
  -r--r--r--   1 sk       users      141389 Feb  6 10:45 dired.el
  -r--r--r--   1 sk       users      113033 Feb  5 16:21 dired.texi
  @dots{}

  /home/sk/lib/emacs/lisp/RCS:
  total 4798
  -r--r--r--   1 sk       users      231748 Feb  6 16:59 dired.texi,v
  -r--r--r--   1 sk       users      763898 Feb  6 10:45 dired.el,v
  @dots{}
@end example

@cindex working file
@cindex RCS file
there are two RCS controlled so-called @dfn{working files}
(@file{dired.el} and @file{dired.texi}) and their associated @dfn{RCS
files} (@file{dired.el,v} and @file{dired.texi,v}) in the @file{RCS}
subdirectory.

@cindex Strict RCS locking
@cindex Locks in RCS
@cindex RCS locks
See the manual pages of rcs(1) for information about how RCS itself
works. @file{rcs.el} assumes that you have a basic understanding of RCS
itself and are using strict locking in RCS, which is necessary to derive
the full benefits of its protection.

@file{rcs.el} is known to work with RCS 5.5 and 5.6, and should also
work with earlier versions of RCS.
@refill

@menu
* Overview of Rcs::		
* Rcs Commands::		
* ChangeLog and RCS log::	
* Rcs Customization::		
* Hooks Used by Rcs::		
* Installation of Rcs::		
* Acknowledgement::		
* Bugs::			Bugs, and a wish list
@end menu

@node Overview of Rcs, Rcs Commands, A GNU Emacs RCS Interface, A GNU Emacs RCS Interface
@section Overview of Rcs

@noindent
Editing RCS controlled files in Emacs works like this:

@cindex Modeline
The minor mode part of the modeline displays the head revision
number @samp{@var{rev}} if a file is RCS controlled, but currently
unlocked, or a list of lockers (in the format
@samp{@var{locker}:@var{rev}}) if it is currently locked.  Usually you
just use @kbd{C-x C-q} to start editing an RCS controlled file (making
it writable by checking out a locked revision) and @kbd{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 (@kbd{C-c D} to @samp{rcsdiff},
@kbd{C-c L} to show the RCS log), to unlock a file you have begun to
edit (@kbd{C-c U}), and to show all locked files in a directory
(@kbd{C-c W}).@refill

@cindex Working file, automatic check-out of in RCS
@cindex Automatic Checkout of Working Files
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 @kbd{y} or @kbd{SPC}, the file will be
RCS-locked and thus writable for editing. If you answer @kbd{n} or
@kbd{DEL} an unlocked read-only copy will be checked out.  If you abort
from the prompt by typing @kbd{C-g}, no file will be checked out from
RCS.  You should probably kill the empty buffer that results from
aborting @code{find-file} in this case.

@cindex Failures of RCS
@cindex Errors in RCS operations
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.  The buffer's modeline is updated.@refill

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

@node Rcs Commands, ChangeLog and RCS log, Overview of Rcs, A GNU Emacs RCS Interface
@section Rcs Commands

@noindent
@cindex Prefix for Rcs Commands
@cindex Switches for Rcs Commands
Most commands accept a prefix argument @kbd{C-u} to mean that the
switches passed to the underlying RCS program (@samp{rcsdiff}, @samp{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 @emph{not} passed to a
shell: the string is split on whitespace and each component is one
argument.

@cindex Line Mode
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 @samp{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 @kbd{RET} by itself.
@refill

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 @samp{rcs}, @samp{ci} or @samp{co} commands, which (unlike the
@samp{rcsdiff} or @samp{rlog} commands) can affect your files.

@vindex rcs-bind-keys
Unless you set the variable @code{rcs-bind-keys} to @code{nil} before
loading @file{rcs.el}, the following keys will be bound:

@table @kbd

@item C-x C-q
@kindex C-x C-q
@findex rcs-toggle-read-only
@cindex Check in
@cindex RCS check in
(@code{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.
@refill

@findex toggle-read-only
In non-RCS buffers this behaves like the usual @kbd{C-x C-q}
(@code{toggle-read-only}) command.
@refill

@item C-c I
@kindex C-c I
@findex rcs-check-in
@cindex Check in
@cindex RCS check in
(@code{rcs-check-in}) lets you check in a file.  The file is usually
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.

@cindex Log messages for RCS, entering them
@cindex RCS log messages, entering them
@cindex Recursive edits in @file{rcs.el}
The log message is prompted for in the minibuffer.  Since the string is
passed directly to the @samp{ci} program, no shell quoting is necessary
and multiline messages are possible.  You can use @kbd{C-x ^} to enlarge
the minibuffer, or @code{yank} (@kbd{C-y}) previously edited text into
the minibuffer, e.g., from a @samp{ChangeLog} buffer.  It is also
possible to use a separate buffer to edit the log by setting
@code{rcs-read-log-function} to
@code{rcs-read-log-string-with-recursive-edit},
@xref{Rcs Customization Variables}.
@refill

@cindex Initial RCS check-in
@cindex RCS check-in, initial
@cindex Check-in, initial
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.

@cindex Major RCS revision, how make a new
@cindex Forced RCS checkin
@cindex RCS checkin, forced
If @code{rcs-check-in} is given a prefix argument, it will first let you
edit the switches used, with @samp{-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 @samp{-u3.0} to check in as revision 3.0, unlocked.

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

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

@item C-c D
@kindex C-c D
@findex rcs-diff
@vindex rcsdiff-switches
@cindex Diff
@cindex Rcsdiff
(@code{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 @code{rcsdiff-switches}, @xref{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.@refill

@item C-c U
@kindex C-c U
@findex rcs-unlock
@cindex Unlock an RCS file
(@code{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 @emph{discarded}.
If you have not actually made any changes, this operation is completed
silently.  However, if you @emph{have} made changes, @file{rcs.el} will
present you with a buffer showing you the changes that you have made
(much as does @code{rcs-diff}) and ask you to confirm that you want to
discard the changes.@refill

Currently it is not possible to break someone else's lock with
@file{rcs.el} since @samp{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.

@item C-c L
@kindex C-c L
@findex rcs-log
@cindex Log of an RCS file
@cindex RCS Log
@cindex rlog
(@code{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 @samp{rlog} program (e.g. @samp{-h} to
just show the head revision).@refill

@item C-c S
@kindex C-c S
@findex rcs-status
@cindex Status of an RCS file
@cindex RCS status
(@code{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 @file{,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.
@refill

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 @samp{rcs}
program.  Multiple switches can be entered separated by whitespace.
@xref{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 @samp{-b@var{branch}} to the prompt.  The command
executed will be @samp{rcs -b@var{branch} -q @var{filename}}.  If
@samp{rcs} makes output in spite of the @samp{-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.
@refill

@cindex Line Mode
@cindex Descriptive text for RCS file
If you want to give a description to a file , type @kbd{C-u C-c S},
enter the filename and @kbd{RET}, and enter a single @kbd{SPC} to the
prompt for the switches.  This puts you into ``line mode'', allowing you
to enter @samp{-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 @kbd{C-q C-j} to do a
quoted insert of a newline, since @kbd{RET} would finish your input.

@item C-c W
@kindex C-c W
@findex rcs-who
@cindex Rcswho
@cindex Directory, RCS locks in a
(@code{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.@refill

@end table

@node ChangeLog and RCS log, Rcs Customization, Rcs Commands, A GNU Emacs RCS Interface
@section ChangeLog and RCS log

The @file{ChangeLog} files records changes for all files in a directory,
while RCS logs are per file.  For full documentation, @xref{Change
Log,,Change Logs,emacs,The GNU Emacs Manual}.  Emacs commands from the
package @file{add-log.el} help making change logs.

Accompanying @file{rcs.el}, an enhanced version of @file{add-log.el} is
shipped.  It was modified from the Emacs 18.55 version to endorse the
GNU coding standards and work together with @file{rcs.el}.  (It will
also work without @file{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:

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

You just have to enter the descriptive text, everything else is already
there.  If the guessed defun is not appropriate, @kbd{C-w}
(@code{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

@itemize @bullet

@item
all the entries for one day make up a page (use @kbd{C-x [}
(@code{backward-page}) and @kbd{C-x ]} (@code{forward-page}) to move to
next day)@refill

@item
each entry for one file is a separate paragraph (use @kbd{M-[}
(@code{backward-paragraph}) and @kbd{M-]} (@code{forward-paragraph}) to
move by entries and @kbd{ESC h} (@code{mark-paragraph}) to mark an
entry)@refill
@end itemize

You can use either @kbd{C-x a} or @kbd{C-x 4 a} to add a ChangeLog for
the current file and defun:

@table @kbd

@item C-x a
@kindex C-x a
(@code{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 @samp{*}) 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 @kbd{C-x a} (@code{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 @var{other-window} non-nil means visit in other window.

@item C-x 4 a
@kindex C-x 4 a
(@code{add-change-log-entry-other-window})
Like @code{add-change-log-entry}, but in other window.

@end table

This variable determines RCS revision level formatting in ChangeLogs:

@table @code

@item add-change-log-entry-rcs-format
@vindex add-change-log-entry-rcs-format
Default: @code{",v %s"}

Format used by @code{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 @file{rcs.el} (but
it does not hurt if you do not, you just do not get any revision levels
inserted).
@end table

@file{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:

@table @code

@item add-log-current-defun-header-regexp
@vindex add-log-current-defun-header-regexp
Default: @code{"^\\([A-Z][A-Z_ ]+\\|[a-z_---A-Z]+\\)[ 	]*[:=]"}

Heuristic regexp used by @code{add-log-current-defun} for unknown major
modes.

@item add-log-current-defun
@findex add-log-current-defun
Return name of function definition point is in, or nil.

Understands Lisp, LaTeX (``defuns'' are chapters, sections, @dots{}),
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 @samp{:} or @kbd{=}.

Has a preference of looking backwards.
@end table

Here is one way of combining ChangeLogs and RCS logs: After doing
changes to an RCS locked file, while it is still locked, use @kbd{C-x 4
a} to insert an entry.  Compose the log message describing your changes.
You might want to do @kbd{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
@example

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

	* rcs.texi,v 1.17
	(ChangeLog and RCS log): 
@end example
Since @file{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 @kbd{M-w} (@code{copy-region-as-kill}), do the check-in
using @kbd{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.

@node Rcs Customization, Hooks Used by Rcs, ChangeLog and RCS log, A GNU Emacs RCS Interface
@section Rcs Customization

Customization can be done with simple variables, default switches, and hooks.

@menu
* Rcs Customization Variables::	 
* Default Switches for RCS Commands::  
* Hooks provided by Rcs::	
@end menu

@node Rcs Customization Variables, Default Switches for RCS Commands, Rcs Customization, Rcs Customization
@subsection Rcs Customization Variables

@noindent
@cindex Customization of @file{rcs.el}
@cindex User options of @file{rcs.el}
@cindex Options for @file{rcs.el}
The following variables can be used to customize @file{rcs.el}:

@table @code

@item rcsdiff-switches
@vindex rcsdiff-switches
Default: nil

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

@item rcs-bind-keys
@vindex rcs-bind-keys
Default: t

If nil, @file{rcs.el} will not bind any keys.  This variable has to be
set before rcs.el is loaded, @xref{Installation of Rcs}, for an example.

@item rcs-active
@vindex rcs-active
Default: t

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

@item rcs-ange-ftp-ignore
@vindex 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.

Even if nil, only the modeline display will work for remote RCS
controlled files, since the @file{,v} file is parsed directly.  All RCS
commands for checkin, diffing etc. will fail since no provision for
using a remote shell has been made in @file{rcs.el}.

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

@c ftp.gnu.ai.mit.edu:ange-ftp/ange-ftp.el.Z
@example
alpha.gnu.ai.mit.edu:ange-ftp/
@end example

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

@item rcs-read-log-function
@vindex rcs-read-log-function
Default: nil

@cindex Recursive edits in @file{rcs.el}
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

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

@noindent
in your @file{~/.emacs}.  The function
@code{rcs-read-log-string-with-recursive-edit} is predefined for this
purpose.
@refill

@item rcs-modeline-branch
@vindex rcs-modeline-branch
Default: "_"

If non-nil, the modeline will display a branch number (if there is one)
instead of the head.  As a special case, if a string, this string will
be appended to the branch, to distinguish branches from head revision
levels in the modeline display.

If there is no branch (other than the trunk) associated with the RCS
file, the head revision will be displayed as usual.
@end table

@node Default Switches for RCS Commands, Hooks provided by Rcs, Rcs Customization Variables, Rcs Customization
@subsection Default switches for RCS Commands

Default switches are for special purpose customization (such as passing
a backward compatibility @samp{-V3} switch to all RCS commands).  You
should know what you do when using them.  Remember these are supposed to
be @emph{lists} of strings, not just strings.

@table @code

@item rcs-default-co-switches
@vindex rcs-default-co-switches
Default: nil

List of switches (strings) for co(1) to use on every @code{rcs-check-out}.

@item rcs-default-ci-switches
@vindex rcs-default-ci-switches
Default: nil

List of switches (strings) for ci(1) to use on every @code{rcs-check-in}.

You can use the @samp{-f} switch to force new revision with RCS 5.6 even
if the file did not change:
@example
(setq rcs-default-ci-switches '("-f"))
@end example

@item rcs-default-rlog-switches
@vindex rcs-default-rlog-switches
Default: nil

List of switches (strings) for rlog(1) to use on every @code{rcs-log}.

@end table

@node Hooks provided by Rcs,  , Default Switches for RCS Commands, Rcs Customization
@subsection Hooks provided by Rcs

Hook variables can contain functions that are run at certain times, by
function @code{run-hooks}.  You will have to study the code in
@file{rcs.el} to make good use of them.  They can be used, e.g., to
prefrobnicate RCS output before @file{rcs.el} sees it, or to put RCS
output buffers in special browsing modes.

Here is an example (for inclusion in your @file{~/.emacs}) to put rlog
and rcsdiff buffers into @code{more-mode}:

@example
(setq rcs-log-buffer-hook 'more-mode)
(setq rcs-diff-buffer-hook 'more-mode)
@end example

@table @code

@item rcs-set-status-buffer-hook
@vindex rcs-set-status-buffer-hook
Default: nil

Hook run in @code{rcs-status} after setting a new RCS status.
The buffer contains output from the rcs(1) command.

@item rcs-status-pre-hook
@vindex rcs-status-pre-hook
Default: nil

Hook run in @code{rcs-status} before a @file{,v} file is analysed.
The buffer contains the contents of the @file{,v} file.

@item rcs-status-post-hook
@vindex rcs-status-post-hook
Default: nil

Hook run in @code{rcs-status} after a @file{,v} file has been analysed.
The buffer contains the contents of the @file{,v} file.

@item rcs-check-out-buffer-hook
@vindex rcs-check-out-buffer-hook
Default: nil

Hook run in @code{rcs-check-out} after co(1) has been run.
The buffer contains the co(1) output.

@item rcs-check-in-buffer-hook
@vindex rcs-check-in-buffer-hook
Default: nil

Hook run in @code{rcs-check-in} after ci(1) has been run.
The buffer contains the ci(1) output.

@item rcs-log-buffer-hook
@vindex rcs-log-buffer-hook
Default: nil

Hook run after @code{rcs-log}.
The buffer contains rlog(1) output.

@item rcs-diff-buffer-hook
@vindex rcs-diff-buffer-hook
Default: nil

Hook run after @code{rcs-diff}.
The buffer contains rcsdiff(1) output.
@end table

@node Hooks Used by Rcs, Installation of Rcs, Rcs Customization, A GNU Emacs RCS Interface
@section Hooks Used by Rcs

@noindent
This section explains how RCS hooks itself into Emacs. It is not
necessary to read it to be able to use @file{rcs.el}.

@cindex Hooks used by @file{rcs.el}
@file{rcs.el} installs itself in two hooks that customize Emacs'
file-manipulation behavior: @code{find-file-not-found-hooks} and
@code{find-file-hooks}.
@refill

@menu
* Automatic Checkout of Working Files::	 
* Rcs Modeline Display::	
@end menu

@node Automatic Checkout of Working Files, Rcs Modeline Display, Hooks Used by Rcs, Hooks Used by Rcs
@subsection Automatic Checkout of Working Files

@vindex find-file-not-found-hooks
@findex rcs-file-not-found
@cindex Automatic Checkout of Working Files
The first hook (@code{rcs-file-not-found}, installed in
@code{find-file-not-found-hooks}) is called when a @code{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.).  @file{rcs.el} will install its own hook at the beginning of this
list.  If you use other packages that also use this hook you should
either make sure that they @file{rcs.el} append their own hooks to the
@emph{end} of the list, or you should load them before @file{rcs.el}.
@refill

@node Rcs Modeline Display,  , Automatic Checkout of Working Files, Hooks Used by Rcs
@subsection Rcs Modeline Display

@findex rcs-load-postprocessor
@vindex find-file-hooks
The second hook (@code{rcs-load-postprocessor}, installed in
@code{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 @code{rcs-mode} and displays either the
head revision level or the current locker and locked revision in the
format @samp{@var{locker}:@var{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 @code{find-file-hooks} list.  (There is an exception: if you
are using Ashwin Ram's @code{infer-file-mode} code, which also hooks
into @code{find-file-hooks}, just make sure that @code{infer-file-mode}
occurs first in the list of hooks by loading @file{rcs.el} before
pushing @code{infer-file-mode} onto the hooks list.  Otherwise a major
mode change in @code{infer-file-mode} will kill all local variables,
including the RCS modeline variables.)
@refill

You may also call @code{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 @kbd{C-c S} (@code{rcs-status}) will also update its modeline.
@refill

@cindex Read-only status of RCS controlled files
When @file{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.@refill

@findex toggle-read-only
@findex rcs-toggle-read-only
The key sequence @kbd{C-x C-q} (@code{toggle-read-only}) is remapped to
call @code{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.@refill

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.@refill

@node Installation of Rcs, Acknowledgement, Hooks Used by Rcs, A GNU Emacs RCS Interface
@section Installation of Rcs

@cindex Installation of @file{rcs.el}
@noindent
Your system manager should have installed the package and the manual in
the correct place, as described in the @file{rcs.README} file that comes
with the distribution.
@refill

To use @file{rcs.el}, simply load it from your @file{~/.emacs}:

@example
(load "rcs")
@end example

Additionally, you can customize variable by adding a line like

@example
(setq rcsdiff-switches "-u") ; or whatever you prefer, e.g. "-c2"
;; you can change key bindings here or set some other variables
@end example
(the @samp{-u} switch may only work with GNU diff).

@cindex Key bindings of @file{rcs.el}, how to change them
@cindex Bindings of @file{rcs.el}, how to change them
If you do not like the key bindings established by default, here is an
example of how to chose your own bindings:
@example
(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)
@end example

@cindex Autoloading of @file{rcs.el} not possible
@file{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.

@node Acknowledgement, Bugs, Installation of Rcs, A GNU Emacs RCS Interface
@section Acknowledgement

@file{rcs.el} was originally written in 1990 by James Elliott
<elliott@@cs.wisc.edu>.  He invented the overloading of @kbd{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 @samp{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, implemented the possibility to add switches to all RCS
commands, and wrote the manual.

My thanks go to James Elliott for writing the original @file{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.

@node Bugs,  , Acknowledgement, A GNU Emacs RCS Interface
@section Bugs, and a wish list

@itemize @bullet

@item
Once you start adding switches to RCS commands or use hooks, you are on
your own.  Depending on what you do, it may confuse @file{rcs.el}
completely.  The examples given in the manual should be safe, though.

@item
Filename completion should work on currently nonexistent RCS files.

@end itemize

@node Index,  , A GNU Emacs RCS Interface, Top
@unnumbered Index

Index of variables, functions, keys and concepts used in @file{rcs.el}:

@printindex vr

@contents
@bye
