OS/2 Shareware BBS: 10 Tools/10-Tools.zip/rcstxi11.zip/rcstexi.110/rcs.tex

Text File | 1997-03-30 | 25KB | 703 lines

@c
@c ================================================================================
@c                               Edition 1.1
@c                      of the Texinfo-manuals for the
@c                      (R)evision (C)ontrol (S)ystem
@c                               Version 5.7
@c
@c                  (c) 1982, 1988, 1989 Walter F. Tichy.
@c           (c) 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert.
@c        (c) 1996, 1997 Karl Heinz Marbaise (doing converting job)
@c ================================================================================
@c
@c Discription:
@c    administrative tools of RCS
@c
@c Authors:
@c    Walter Tichy,
@c    Paul Eggert,
@c    Karl Heinz Marbaise (doing converting job)
@c
@c e-mail:
@c    Internet: [e-mail]
@c    Fido-net: 2:2452/117.69
@c
@c Bugs, question:
@c    to above e-mail adress.
@c
@c License:
@c    The "Texinfo Edition of the RCS V5.7 manuals" are free
@c    software; you can redistribute it and/or modify it under
@c    the terms of the GNU General Public License as published
@c    by the Free Software Foundation; either version 2, or (at
@c    your option) any later version.
@c
@c    The "Texinfo Edition of the RCS V5.7 manuals" are distributed
@c    in the hope that they will be useful, but WITHOUT ANY WARRANTY;
@c    without even the implied warranty of MERCHANTABILITY or
@c    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
@c    License for more details.
@c
@c    You should have received a copy of the GNU General Public License
@c    along with the "Texinfo Edition of the RCS V5.7 manuals"; see the
@c    file COPYING. If not, write to the:
@c    Free Software Foundation,
@c    59 Temple Place - Suite 330,
@c    Boston, MA 02111-1307, USA.
@c
@c    See \rcstxi.110\COPYING for details.
@c
@c ================================================================================
@c
@c
@c $Id: RCS.TEX 1.2 1997/03/30 22:53:14 KHM Exp $
@c
@c =============================================================================
@c rcs -- change RCS file attributes
@c -----------------------------------------------------------------------------
@node rcs,ident,CheckOut,Top
@chapter rcs -- change RCS file attributes
@cindex rcs
@cindex change RCS
@menu
* rcsIntro::            Introduction to @code{rcs}.

* rcsOptions::          command line options of @code{rcs}.
* rcsCompatibility::    Compatibility between RCS Versions.
* rcsFiles::            Files.
* rcsEnv::              The Environment which can change the
                        behaviour of much of the RCS commands.
* rcsDiag::             Diagnostic output of @code{rcs}.
* rcsBugs::             Bugs.
@end menu
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Description
@c -----------------------------------------------------------------------------
@node rcsIntro,rcsOptions,,rcs
@section Description
RCS  creates new RCS files or changes attributes of existing ones.
An RCS  file  contains  multiple  revisions  of
text,  an access list, a change log, descriptive text, and
some control attributes.  For rcs to  work,  the  caller's
login  name  must  be  on  the  access list, except if the
access list is empty, the caller is the owner of the  file
or the superuser, or the @code{-i} option is present.

Pathnames  matching  an  RCS  suffix denote RCS files; all
others  denote  working  files.   Names  are   paired   as
explained  in  @xref{ciIntro}.   Revision  numbers  use  the syntax
described in @xref{ciIntro}.


@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c -----------------------------------------------------------------------------
@node rcsOptions,rcsCompatibility,rcsIntro,rcs
@section Command line options of rcs
@ifinfo
Overview off all options which can be given to @code{rcs}

@code{Synopsis}: rcs [options] file @dots{}
@end ifinfo
@menu
* rcsOpti::        -i Initialize.
* rcsOpta::        -a Login names.
* rcsOptAu::       -A Append access list.
* rcsOpte::        -e Erase login names.
* rcsOptb::        -b Set default branch.
* rcsOptc::        -c Set comment leader.
* rcsOptk::        -k Keyword substitution.
* rcsOptl::        -l Lock revision.
* rcsOptu::        -u unlock revision.
* rcsOptLu::       -L Set strict locking.
* rcsOptUu::        -U set non-strict locking.
* rcsOptm::        -m Replace message.
* rcsOptMu::       -M Do not send mail.
* rcsOptn::        -n Associate symbolic name(tag).
* rcsOptNu::       -N Override symbolic name.
* rcsOpto::        -o Delete revisions.
* rcsOptq::        -q Quiet mode.
* rcsOptIu::       -I Interactive mode.
* rcsOpts::        -s Set state.
* rcsOptt::        -t Discription.
* rcsOptTu::       -T Modification time.
* rcsOptV::        -V Version; Emulation of RCS Version.
* rcsOptx::        -x Suffixes.
* rcsOptz::        -z Time zone.
@end menu
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option -i
@c -----------------------------------------------------------------------------
@node rcsOpti,rcsOpta,,rcsOptions
@subsection Initialize RCS File
@cindex -i
@cindex Initialize
@table @code
@item -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
@code{./RCS}, and then into the current directory.  If the
RCS file already exists, print an error message.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option -a
@c -----------------------------------------------------------------------------
@node rcsOpta,rcsOptAu,rcsOpti,rcsOptions
@subsection Append Login names
@cindex -a
@cindex Login names
@cindex Access
@table @code
@item -a@file{logins}

Append the login  names  appearing  in  the  comma-separated
list @file{logins} to the access list of the RCS
file.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option -A
@c -----------------------------------------------------------------------------
@node rcsOptAu,rcsOpte,rcsOpta,rcsOptions
@subsection Append Access list
@cindex -A
@cindex Access Liste
@table @code
@item -A@file{oldfile}

Append the access list of  @file{oldfile} to  the  access
list of the RCS file.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option -e
@c -----------------------------------------------------------------------------
@node rcsOpte,rcsOptb,rcsOptAu,rcsOptions
@subsection Erase Login names
@cindex -e
@cindex Erase Login names
@table @code
@item -e@file{logins}

Erase  the  login  names  appearing  in  the comma-
separated list @file{logins} from the access list  of  the
RCS  file.   If @file{logins} is omitted, erase the entire
access list.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option -b
@c -----------------------------------------------------------------------------
@node rcsOptb,rcsOptc,rcsOpte,rcsOptions
@subsection Default branch
@cindex -b
@cindex branch
@cindex set branch
@table @code
@item -b@file{rev}

Set the default branch to @file{rev}.  If @file{rev} is  omitted,
the  default  branch  is reset to the (dynamically)
highest branch on the trunk.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option -c
@c -----------------------------------------------------------------------------
@node rcsOptc,rcsOptk,rcsOptb,rcsOptions
@subsection Coment leader
@cindex -c
@cindex comment leader
@table @code
@item -c@file{string}

Set the comment leader to @file{string}.  An  initial
@code{ci}, or an @code{rcs -i} without @code{-c},
guesses the comment leader from the suffix of the
working filename.


This option is obsolescent, since RCS normally uses
the  preceding  @code{@value{RCSLOG}} line's prefix
when inserting log lines during checkout
(@xref{coIntro}).
However, older  versions  of  RCS  use  the  comment  leader
instead of the @code{@value{RCSLOG}} line's prefix,
so if you  plan to  access a file with both old and
new versions of RCS, make sure its comment leader
matches its @code{@value{RCSLOG}} line prefix.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option -k
@c -----------------------------------------------------------------------------
@node rcsOptk,rcsOptl,rcsOptc,rcsOptions
@subsection Keyword substitution
@cindex -k
@cindex Keyword
@table @code
@item -k@file{subst}

Set the default keyword substitution to @file{subst}.  The
effect of  keyword  substitution  is  described  in
@ref{coKeyword}. Giving  an explicit @code{-k} option to co,
@code{rcsdiff}, and @code{rcsmerge} overrides this  default.
Beware @code{rcs -kv},  because  @code{-kv}  is incompatible with
@code{co -l}. Use @code{rcs -kkv} to restore the normal default  keyword
substitution.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option -l
@c -----------------------------------------------------------------------------
@node rcsOptl,rcsOptu,rcsOptk,rcsOptions
@subsection Lock revision
@cindex -l
@cindex Lock revsion
@table @code
@item -l@file{rev}

Lock  the revision with number @file{rev}.  If a branch is
given, lock the latest revision on that branch.  If
@file{rev} is  omitted,  lock  the latest revision on the
default  branch.   Locking   prevents   overlapping
changes.   If  someone else already holds the lock,
the lock is broken as with @code{rcs -u} (see below).

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option -u
@c -----------------------------------------------------------------------------
@node rcsOptu,rcsOptLu,rcsOptl,rcsOptions
@subsection Unlock revisions
@cindex -u
@cindex Unlock revsion
@table @code
@item -u@file{rev}

Unlock the revision with number @file{rev}. If  a  branch is
given,  unlock  the  latest  revision  on  that branch.  If
@file{rev} is omitted, remove the latest  lock held by the
caller.  Normally, only the locker of a revision can unlock it.
Somebody else unlocking  a revision  breaks the lock. This causes
a mail message to be sent to the original locker. The  message
contains  a  commentary  solicited  from  the breaker.  The
commentary is terminated  by  end-of-file or by a line containing
@code{.} by itself.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option -L
@c -----------------------------------------------------------------------------
@node rcsOptLu,rcsOptUu,rcsOptu,rcsOptions
@subsection Strict Locking
@cindex -L
@cindex Strict Locking
@table @code
@item -L

Set  locking  to @code{strict}.  Strict locking means that
the owner of an RCS file is not exempt from locking
for  checkin.  This option should be used for files
that are shared.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option -U
@c -----------------------------------------------------------------------------
@node rcsOptUu,rcsOptm,rcsOptLu,rcsOptions
@subsection Locking non-strict
@cindex -U
@cindex non-Strict Locking
@table @code
@item -U

Set  locking  to  non-strict.   Non-strict  locking
means  that  the  owner  of  a file need not lock a
revision for checkin.  This option  should  @code{not} be
used  for  files  that are shared.  Whether default
locking is strict  is  determined  by  your  system
administrator, but it is normally strict.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option -m
@c -----------------------------------------------------------------------------
@node rcsOptm,rcsOptMu,rcsOptUu,rcsOptions
@subsection Replace log message
@cindex -m
@cindex Revision message
@cindex Log message
@table @code
@item -m@file{rev}:@file{msg}

Replace revision @file{rev}'s log message with @file{msg}.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option -M
@c -----------------------------------------------------------------------------
@node rcsOptMu,rcsOptn,rcsOptm,rcsOptions
@subsection Do not send Mail
@cindex -M
@cindex Mail
@cindex Lock breaking
@table @code
@item -M

Do  not  send  mail  when  breaking somebody else's
lock.  This option is not meant for casual use;  it
is  meant  for  programs  that  warn users by other
means, and invoke @code{rcs -u} only as a low-level
lock-breaking operation.


@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option-n
@c -----------------------------------------------------------------------------
@node rcsOptn,rcsOptNu,rcsOptMu,rcsOptions
@subsection Symbolic name
@cindex -n
@cindex Symbolic
@cindex name
@cindex tag
@table @code
@item -n@file{name}[:[@file{rev}]]

Associate the symbolic name @file{name} with the branch or
revision @file{rev}.  Delete the symbolic name if  both:
and @file{rev} are omitted; otherwise, print an error message
if @file{name} is  already  associated  with  another
number.   If @file{rev} is symbolic, it is expanded before
association.  A @file{rev} consisting of a  branch  number
followed by a . stands for the current latest revision
in the branch.  A : with an empty  @file{rev} stands
for  the  current  latest  revision  on the default
branch,   normally   the   trunk.    For   example,
@example
@group
rcs -n@code{name}: RCS/*
@end group
@end example
associates @code{name} with the current
latest revision of all the named  RCS  files;  this
contrasts  with
@example
@group
rcs -n@code{name}:@value{RCSD} RCS/*
@end group
@end example
which associates
@code{name} with the revision numbers extracted from  keyword
strings in the corresponding working files.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option-N
@c -----------------------------------------------------------------------------
@node rcsOptNu,rcsOpto,rcsOptn,rcsOptions
@subsection Override Symbolic name
@cindex -N
@cindex Symbolic
@cindex name
@cindex tag
@cindex override Symbolic name
@table @code
@item -N@file{name}[:[@file{rev}]]

Act  like  @code{-n}, except override any previous assignment of
@file{name}.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option-o
@c -----------------------------------------------------------------------------
@node rcsOpto,rcsOptq,rcsOptNu,rcsOptions
@subsection Delete revisions
@cindex -o
@cindex Delete revision
@table @code
@item -o@file{range}

deletes ("outdates") the revisions given by  @file{range}.
A  range  consisting  of  a  single revision number
means that  revision.   A  range  consisting  of  a
branch  number  means  the  latest revision on that
branch.  A range of the form @code{@file{rev1}:@file{rev2}} means
revisions @code{rev1} to @code{rev2} on the same branch,
@code{:@file{rev}} means from the beginning of the branch
containing @file{rev} up to  and including @file{rev},
and @code{rev:} means from revision @code{rev} to the
end of the branch containing @code{rev} . None of  the
outdated  revisions  can  have branches or locks.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option-q
@c -----------------------------------------------------------------------------
@node rcsOptq,rcsOptIu,rcsOpto,rcsOptions
@subsection Quiet mode
@cindex -q
@cindex Quiete mode
@table @code
@item -q

Run quietly; do not print diagnostics.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option-I
@c -----------------------------------------------------------------------------
@node rcsOptIu,rcsOpts,rcsOptq,rcsOptions
@subsection Interactive
@cindex -I
@cindex Interactiv
@table @code
@item -I

Run interactively, even if the  standard  input  is
not a terminal.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option-s
@c -----------------------------------------------------------------------------
@node rcsOpts,rcsOptt,rcsOptIu,rcsOptions
@subsection States
@cindex -s
@cindex States
@table @code
@item -s@file{state}:[@file{rev}]

Set  the  state  attribute  of  the revision @file{rev} to
@file{state}.  If @file{rev} is a branch number, assume the  latest
revision  on  that branch.  If @file{rev} is omitted,
assume the latest revision on the  default  branch.
Any  identifier  is acceptable for @file{state} .  A useful
set of states is Exp (for experimental), Stab  (for
stable), and Rel (for released).  By default, @ref{ciOpts}
sets the state of a revision to Exp.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option-t
@c -----------------------------------------------------------------------------
@node rcsOptt,rcsOptTu,rcsOpts,rcsOptions
@subsection Descriptive Text
@cindex -t
@cindex Descriptive
@table @code
@item -t@file{file}

Write descriptive text from  the  contents  of  the
named @file{file} into the RCS file, deleting the existing
text.  The @file{file} pathname cannot begin with  @code{-}.
If @file{file} is  omitted,  obtain  the  text from standard
input, terminated by end-of-file or by a line  containing.
by itself.  Prompt for the text if interaction is possible;
see @code{-I} @ref{rcsOptIu}.  With  @code{-i},  descriptive
text is obtained even if @code{-t} is not given.

@item -t-@file{string}

Write descriptive text from the @file{string} into the RCS
file, deleting the existing text.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option-T
@c -----------------------------------------------------------------------------
@node rcsOptTu,rcsOptV,rcsOptt,rcsOptions
@subsection Modification Time
@cindex -T
@cindex Modification Time
@table @code
@item -T

Preserve the modification  time  on  the  RCS  file
unless a revision is removed.  This option can sup-
press extensive recompilation caused by  a  @code{make}
dependency  of some copy of the working file on the
RCS file.  Use this option with care; it  can  suppress
recompilation  even  when it is needed, i.e.
when a change to the RCS file would mean  a  change
to keyword strings in the working file.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option-V
@c -----------------------------------------------------------------------------
@node rcsOptV,rcsOptx,rcsOptTu,rcsOptions
@subsection Version
@cindex -V
@cindex Version
@cindex Emulation of RCS
@table @code
@item -V

Print RCS's version number.

@item -V@file{n}

Emulate RCS version @file{n}.  See @ref{coOptV} for details.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option-x
@c -----------------------------------------------------------------------------
@node rcsOptx,rcsOptz,rcsOptV,rcsOptions
@subsection Suffixes
@cindex -x
@cindex Suffixes
@table @code
@item -x@file{suffixes}

Use @file{suffixes} to characterize RCS files. See @ref{ciOptx}.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Options
@c         option-z
@c -----------------------------------------------------------------------------
@node rcsOptz,,rcsOptx,rcsOptions
@subsection Time Zone
@cindex -z
@cindex Time Zone
@table @code
@item -z@file{zone}

Use @file{zone} as the default time zone.  This option has
no  effect;  it  is  present for compatibility with
other RCS commands.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Compatibility
@c -----------------------------------------------------------------------------
@node rcsCompatibility,rcsFiles,rcsOptions,rcs
@subsection Compatibility
@cindex Compatibility

The @code{-b@file{rev}} option generates an  RCS  file  that  cannot  be
parsed by RCS version 3 or earlier.

The  @code{-k@file{subst}} options  (except  @code{-kkv}) generate an RCS file
that cannot be parsed by RCS version 4 or earlier.

Use rcs @code{-V@file{n}} to make an RCS file acceptable to RCS  version
@file{n}  by discarding information that would confuse version @file{n}.

RCS version 5.5  and  earlier  does  not  support  the  @code{-x}
option, and requires a @code{,v} suffix on an RCS pathname.

@c =============================================================================
@c rcs -- change RCS file attributes
@c     Files
@c -----------------------------------------------------------------------------
@node rcsFiles,rcsEnv,rcsCompatibility,rcs
@subsection Files
@cindex Files

rcs accesses files much as @code{ci} does, except that it uses
the effective user for all accesses, it does not write the
working  file  or its directory, and it does not even read
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Envrionment
@c -----------------------------------------------------------------------------
@node rcsEnv,rcsDiag,rcsFiles,rcs
@section Environment
@cindex Environment
@table @code
@item RCSINIT
options prepended to the argument list, separated by spaces.
See @ref{ciEnv} for details.

@end table
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Diagnostics
@c -----------------------------------------------------------------------------
@node rcsDiag,rcsBugs,rcsEnv,rcs
@section Diagnostics
The RCS pathname and the revisions outdated are written to
the  diagnostic  output.   The  exit status is zero if and
only if all operations were successful.
@c =============================================================================
@c rcs -- change RCS file attributes
@c     Bugs
@c -----------------------------------------------------------------------------
@node rcsBugs,,rcsDiag,rcs
@section Bugs
A catastrophe (e.g. a system crash) can cause RCS to leave
behind  a  semaphore file that causes later invocations of
RCS to claim that the RCS file is in use.   To  fix  this,
remove  the semaphore file.  A semaphore file's name typically
begins with @file{,} or ends with @file{_}.

The separator for revision ranges in the @code{-o} option used to
be  @file{-}  instead of @file{:}, but this leads to confusion when
symbolic names contain @file{-}.  For backwards compatibility
@code{rcs -o} still  supports  the  old  - separator, but it warns about
this obsolete use.

Symbolic names need not refer  to  existing  revisions  or
branches.  For example, the @code{-o} option does not remove symbolic
names for the outdated revisions; you must use @code{-n} to
remove the names.