@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    information about an RCS archive.
@c
@c Authors:
@c    Walter Tichy,
@c    Paul Eggert,
@c    Karl Heinz Marbaise (doing converting job)
@c
@c e-mail:
@c    Internet: KHMarbaise@p69.ks.fido.de
@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: RLOG.TEX 1.2 1997/03/30 22:53:21 KHM Exp $
@c
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c -----------------------------------------------------------------------------
@node rlog,merge,rcsmerge,Top
@chapter rlog -- print log messages
@cindex rlog
@cindex log messages
@cindex Information
@menu
* rlogIntro::        Introduction to @code{rlog}.

* rlogOptions::      command line options of @code{rlog}.
* rlogExamples::     Examples.
* rlogEnv::          The Environment which can change the
                     behaviour of much of the RCS commands.
* rlogDiag::         Diagnostic output of @code{rlog}.
* rlogBugs::         Bugs.

@end menu
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Description
@c -----------------------------------------------------------------------------
@node rlogIntro, rlogOptions,,rlog
@section Description
@code{rlog} prints information about RCS files.

Pathnames matching an RCS suffix  denote  RCS  files;  all
others   denote   working  files.   Names  are  paired  as
explained in @ref{ciFiles}.

@code{rlog} prints the following information for each  RCS  file:
RCS  pathname, working pathname, head (i.e., the number of
the latest revision on the trunk), default branch,  access
list, locks, symbolic names, suffix, total number of revisions,
number of  revisions  selected  for  printing,  and
descriptive  text.   This  is  followed by entries for the
selected revisions in reverse chronological order for each
branch.   For  each revision, rlog prints revision number,
author, date/time, state, number  of  lines  added/deleted
(with  respect  to  the  previous revision), locker of the
revision (if any), and log message.  All  times  are  displayed
in  Coordinated  Universal  Time (UTC) by default;
this can be overridden with  @code{-z}.   Without  options,
@code{rlog} prints  complete  information.
The options below restrict this output.


@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Options
@c -----------------------------------------------------------------------------
@node rlogOptions,rlogExamples,rlogIntro,rlog
@section Command line options of rlog
@cindex Command line options
@ifinfo
Overview off all options which can be given to @code{rlog}

@code{Synopsis}: rlog [options] file @dots{}
@end ifinfo
@menu
* rlogOptLu::      -L Ignore RCS files.
* rlogOptRu::      -R Only names of RCS files.
* rlogOpth::       -h Only path names.
* rlogOptt::       -t Path and discriptive text.
* rlogOptN::       -N Do not print symbolic names..
* rlogOptb::       -b Information about revisions on default branch.
* rlogOptd::       -d Info about revisions with ci-date.
* rlogOptl::       -l Print locked revisions only.
* rlogOptr::       -r Informations about specified revisions.
* rlogOpts::       -s Informations about revisions with state.
* rlogOptw::       -w Informations about revisions with user.
* rlogOptTu::      -T no effect.
* rlogOptV::       -V Version; Emulation of RCS version.
* rlogOptx::       -x Suffixes.
* rlogOptz::       -z Time zone.
@end menu
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Options
@c         option -L
@c -----------------------------------------------------------------------------
@node rlogOptLu,rlogOptRu,,rlogOptions
@subsection Ignore RCS files without locks
@cindex -L
@cindex no lock
@cindex Ignore
@table @code
@item -L

Ignore RCS files that have no locks set.  This is convenient
in combination with @code{-h}, @code{-l}, and @code{-R}.
@end table
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Options
@c         option -R
@c -----------------------------------------------------------------------------
@node rlogOptRu,rlogOpth,rlogOptLu,rlogOptions
@subsection Only names of RCS files
@cindex -R
@cindex Names
@table @code
@item -R

Print  only  the name of the RCS file.  This is convenient
for translating a working pathname into  an  RCS
pathname.
@end table
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Options
@c         option -h
@c -----------------------------------------------------------------------------
@node rlogOpth,rlogOptt,rlogOptRu,rlogOptions
@subsection Only pathname
@cindex -h
@cindex pathname
@table @code
@item -h

Print  only  the RCS pathname, working pathname, head,
default branch, access list,  locks,  symbolic  names,
and suffix.
@end table
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Options
@c         option -t
@c -----------------------------------------------------------------------------
@node rlogOptt,rlogOptN,rlogOpth,rlogOptions
@subsection Descriptive text
@cindex -t
@cindex Descriptive text
@table @code
@item -t

Print the same as @code{-h}, plus the descriptive text.
@end table
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Options
@c         option -N
@c -----------------------------------------------------------------------------
@node rlogOptN,rlogOptb,rlogOptt,rlogOptions
@subsection No symbolic name
@cindex -N
@cindex no Symbolic name
@table @code
@item -N

Do not print the symbolic names.
@end table
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Options
@c         option -b
@c -----------------------------------------------------------------------------
@node rlogOptb,rlogOptd,rlogOptN,rlogOptions
@subsection Default branch
@cindex -b
@cindex Default branch
@table @code
@item -b

Print  information  about the revisions on the default
branch, normally the highest branch on the trunk.
@end table
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Options
@c         option -d
@c -----------------------------------------------------------------------------
@node rlogOptd,rlogOptl,rlogOptb,rlogOptions
@subsection Checkin date/time
@cindex -d
@cindex Checkin date/time
@table @code
@item -d@file{dates}

Print  information  about  revisions  with  a  checkin date/time
in  the  ranges  given  by  the  semicolon-separated list of
@file{dates}.  A range of the form @file{d1}<@file{d2} or
@file{d2}>@file{d1} selects  the  revisions  that  were
deposited between @file{d1} and @file{d2} exclusive.  A range of
the  form <@file{d} or  @file{d}>  selects all revisions earlier
than @file{d}. A range of the form @file{d}< or >@file{d} selects
all revisions dated later than  @file{d}.   If  @code{<} or
@code{>} is followed by @code{=} then the ranges are inclusive,
not exclusive.  A range of the  form  @file{d} selects  the
single,  latest revision dated @file{d} or earlier.  The date/time
strings @file{d}, @file{d1}, and @file{d2} are in  the free
format  explained in @ref{coOptd}. Quoting is normally necessary,
especially for @code{<} and @code{>}. Note that the separator is
a semicolon.

@end table
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Options
@c         option -l
@c -----------------------------------------------------------------------------
@node rlogOptl,rlogOptr,rlogOptd,rlogOptions
@subsection Locked revisions
@cindex -l
@cindex Locked revisions
@table @code
@item -l@file{lockers}

Print  information  about  locked  revisions only.  In
addition, if the comma-separated list @file{lockers} of login
names is given, ignore all locks other than those held
by the @file{lockers}.  For  example,

@example
rlog -L -R -lwft RCS/*
@end example

prints the name of RCS files locked by the user @code{wft}.

@end table
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Options
@c         option -r
@c -----------------------------------------------------------------------------
@node rlogOptr,rlogOpts,rlogOptl,rlogOptions
@subsection Informations about revisions
@cindex -r
@cindex Information about Revisions
@table @code
@item -r@file{revisions}

prints information about revisions given in the commaseparated
list @code{revisions} of revisions and  ranges. A range
@code{@file{rev1}:@file{rev2}} means  revisions @file{rev1} to
@file{rev2} on the same branch, @code{:@file{rev}} means
revisions from  the  beginning of  the branch up to and including
@file{rev} , and @code{@file{rev}:}  means revisions starting
with @file{rev} to the end of  the  branch containing @file{rev}.
An  argument that is a branch means all revisions on that branch.
A  range  of  branches means  all revisions on the branches in
that range.  A branch followed by a . means the  latest  revision
in that  branch. A  bare @code{-r} with no @file{revisions} means
the latest revision on the default  branch,  normally  the trunk.

@end table
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Options
@c         option -s
@c -----------------------------------------------------------------------------
@node rlogOpts,rlogOptw,rlogOptr,rlogOptions
@subsection Information about Rev. with given state
@cindex -s
@cindex Information Rev. given state
@table @code
@item -s@file{states}

prints   information   about   revisions  whose  state
attributes match one of the states given in the commaseparated
list @file{states}.

@end table
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Options
@c         option -w
@c -----------------------------------------------------------------------------
@node rlogOptw,rlogOptTu,rlogOpts,rlogOptions
@subsection Revisons checked in by user
@cindex -w
@cindex Checked in by user
@table @code
@item -w@file{logins}

prints information about revisions checked in by users
with login names appearing in the comma-separated list
@file{logins}.   If  @file{logins} is  omitted, the user's login is
assumed.
@end table
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Options
@c         option -T
@c -----------------------------------------------------------------------------
@node rlogOptTu,rlogOptV,rlogOptw,rlogOptions
@subsection Modification Time
@cindex -T
@cindex Modification time
@table @code
@item -T

This option has no effect; it is present for  compatibility
with other RCS commands.
@end table
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Options
@c         option -V
@c -----------------------------------------------------------------------------
@node rlogOptV,rlogOptx,rlogOptTu,rlogOptions
@subsection Version and Emulation
@cindex -V
@cindex Version
@cindex Emulation
@table @code
@item -V

Print RCS's version number.


@item -V@file{n}

Emulate RCS version @file{n} when generating logs.  See
@ref{coOptV} for more.
@end table
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Options
@c         option -x
@c -----------------------------------------------------------------------------
@node rlogOptx,rlogOptz,rlogOptV,rlogOptions
@subsection Suffixes
@cindex -x
@cindex Suffixes
@table @code
@item -x@file{suffixes}

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

@end table
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Options
@c         option -z
@c -----------------------------------------------------------------------------
@node rlogOptz,,rlogOptx,rlogOptions
@subsection Time zone
@cindex -z
@cindex Time zone
Rlog  prints  the  intersection  of the revisions selected
with the options @code{-d}, @code{-l}, @code{-s}, and @code{-w},
intersected with  the union of the revisions selected by
@code{-b} and @code{-r}.

@table @code
@item -z@file{zone}
specifies the date output format, and specifies the
default time zone for @file{date} in the  @code{-d@file{dates}} option.
The  @file{zone} should be empty, a numeric UTC offset, or
the special string @code{LT} for local time.  The  default
is  an  empty  @file{zone} , which uses the traditional RCS
format of UTC without any time zone indication  and
with slashes separating the parts of the date; oth-
erwise, times are output in ISO  8601  format  with
time  zone  indication.  For example, if local time
is January 11, 1990,  8pm  Pacific  Standard  Time,
eight hours west of UTC, then the time is output as
follows:

@example
@group
option    time output
-z        1990/01/12 04:00:00       (default)
-zLT      1990-01-11 20:00:00-08
-z+05:30  1990-01-12 09:30:00+05:30
@end group
@end example

@end table
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Examples
@c -----------------------------------------------------------------------------
@node rlogExamples,rlogEnv,rlogOptions,rlog
@subsection Examples
@cindex Examples
@example
@group
rlog  -L  -R  RCS/*
rlog  -L  -h  RCS/*
rlog  -L  -l  RCS/*
rlog  RCS/*
@end group
@end example

The first command prints the names of all RCS files in the
subdirectory  RCS  that  have  locks.   The second command
prints the headers of those files, and  the  third  prints
the headers plus the log messages of the locked revisions.
The last command prints complete information.

@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Environment
@c -----------------------------------------------------------------------------
@node rlogEnv,rlogDiag,rlogExamples,rlog
@subsection 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 rlog -- print log messages and other information about RCS files
@c     Diagnostics
@c -----------------------------------------------------------------------------
@node rlogDiag,rlogBugs,rlogEnv,rlog
@section Diagnostics
The exit status is zero if and only if all operations were
successful.
@c =============================================================================
@c rlog -- print log messages and other information about RCS files
@c     Bugs
@c -----------------------------------------------------------------------------
@node rlogBugs,,rlogDiag,rlog
@section Bugs
@cindex Bugs
The separator for revision ranges in the @code{-r} option used to
be  @code{-}  instead of @code{:}, but this leads to confusion when symbolic
names contain @code{-}.  For backwards  compatibility
@code{rlog -r}  still supports the old @code{-} separator, but it warns about
this obsolete use.

