.ig
 Copyright (C) 1993,1994 by the author(s).
 
 This software is published in the hope that it will be useful, but
 WITHOUT ANY WARRANTY for any part of this software to work correctly
 or as described in the manuals. See the ShapeTools Public License
 for details.

 Permission is granted to use, copy, modify, or distribute any part of
 this software but only under the conditions described in the ShapeTools 
 Public License. A copy of this license is supposed to have been given
 to you along with ShapeTools in a file named LICENSE. Among other
 things, this copyright notice and the Public License must be
 preserved on all copies.


Authors: Uli.Pralle@cs.tu-berlin.de, Axel.Mahler@cs.tu-berlin.de
   and Andreas.Lampen@cs.tu-berlin.de

$Header: vl.1[8.0] Fri Dec 17 18:55:05 1993 andy@cs.tu-berlin.de frozen $
..
.TH vl 1 "Fri Dec 17 18:55:05 1993" "vl-5.8" "ShapeTools"
.SH NAME
vl \- list version information
.SH SYNOPSIS
.na
.ta 1c
\fBvl\fR	[ \fIversion binding options\fP ] [ \fIoptions\fR ] [ names \.\|. ]
.br
\fBvlog\fR	[ \fIversion binding options\fP ] [ \fIoptions\fR ] [
names \.\|. ]
.IP \fIOptions:\fP \w'\fIOptions:\0\fP'u
[\ \fB\-?1aAcCdFghlLOqQrRStuvx\fR\ ]
[\ \fB\-help\fP\ ]
[\ \fB\-all\fP\ ]
[\ \fB\-attr\fP\ \fIattribute\fP\ ]
[\ \fB\-cache\fP\ ]
[\ \fB\-expand\fP\ (or\ \fB\-xpon\fP)\ ]
[\ \fB\-fast\fP\ ]
[\ \fB\-format\fP\ \fIformat\ string\fP\ ]
[\ \fB\-intent\fP\ ]
[\ \fB\-locked\fP\ ]
[\ \fB\-locker\fP\ ]
[\ \fB\-log\fP\ ]
[\ \fB\-noexpand\fP\ (or\ \fB\-xpoff\fP)\ ]
[\ \fB\-p\fP\ all\||\|\fIattribute\ name\fP\ ]
[\ \fB\-version\fP\ ]
.ad
.SH DESCRIPTION
.PP
\fBvl\fR prints various information about an AtFS object repository.
While its main operation is to list the contents of an object
repository in a manner similar to ls(1), \fBvl\fR knows about many
options that extract additional information about individual versions
or version histories.
.PP
If \fBvl\fR is invoked without any name arguments, it simply 
prints the contents of the object repository, including files (\fIbusy
versions\fR) and directories in the current directory. Version objects
in the object repository are represented as filenames with a bracketed
\fIversion identification extension\fR. 
Generally, \fBvl\fR tries to give the illusion, as were all the
versions in the object repository regular files in the current 
directory. While busy versions \- which are regular files \- may be 
manipulated by all commands and tools that operate on files, version
objects can only be manipulated by special tools (ShapeTools) that
operate on the object repository. The tools that operate on the object
repository, however, can also access regular files because these are
also part of the object repository.
.PP
With the \fB\-h\fP option given, vl prints out one information item
per history rather than per version. Default output in this case is a
list of history and directory names with the range(s) of available
versions following in brackets.
.PP
If filenames are given as arguments to \fBvl\fR, similarly to ls(1)
only information about these object histories will be printed.
Object names may also be given in \fIbound version notation\fR,
i.e. a notation that identifies a particular version of an object (e.g.
\fCmkattr.c[2.4]\fR). It is also possible to use a previously assigned
\fIsymbolic name\fR rather than a numerical 
version identification (e.g. \fCmkattr.c[tools-V4R3]\fR). Make sure
to escape the bracket symbols as these usually have meaning to the
shell. For further version binding possibilities (the \fIversion
binding options\fP) see the vbind(1) manual page.
.PP
The program \fBvlog\fR prints the log-entry for specified objects.
Log-entries usually describe the reason for a particular change
to the design object that led to the creation of the specified
revision(s).
.SH OPTIONS
All options also available in the ls(1) programs are marked on the
following list.
.IP "\fB\-?, \-help\fP" 2c
Print short information about usage of this command.
.IP "\fB\-1\fP (ls)"
Force single column output.
.IP "\fB\-a\fP (ls)"
List all entries, even those with a name beginning with a '.' and
the 'AtFS' entry. This option is default when vl is called by the super
user.
.IP "\fB\-all\fP"
List all available information.
.IP "\fB\-attr\fP\ \fIattribute\fP"
Print only information about objects that have the specified
attribute with the given values. The attribute value match is done
without attribute expansion, even if -expand is set. \fIattribute\fP
may also be a standard attribute. For a complete list of standard
attributes names see the vadm(1) manual page.
.IP "\fB\-A\fP (ls)"
Same as \fB-a\fP, but '.', '..', and 'AtFS' are not listed.
.IP "\fB\-c\fP (ls)"
Sort the list of printed entries by the time of last status change.
.IP "\fB\-cache\fP"
List entries from the derived object cache too.
.IP "\fB\-C\fP (ls)"
Force multi column output. This is default when printing just the
entry names (no \fB-l\fP and no \fB-p\fP option) and output goes to a
terminal.
.IP "\fB\-d\fP (ls)"
With a directory name given as argument, list the directory itself
rather than its contents.
.IP "\fB\-expand, \-xpon\fP "
Expand attribute values before printing. Attribute values may contain
citations of other attributes, or they may start with a special
character ('^', '!' or '*') indicating that they need some kind of
processing to determine the real attribute value (see vattr(1) for
details). With the \fB-expand\fP option given, all citations will be
evaluated and the attribute will be evaluated if necessary.
.IP "\fB\-fast\fP"
Fast operation. Suppresses reader/writer synchronisation on AtFS
archive files and ignores non-standard attributes. In combination with
\fI-h\fP (histories), a short output is generated, that lists only the
names of all histories and not their version ranges.
.IP "\fB\-format\fP\ \fIformat\ string\fP"
Specify custom-format for information printed about objects. This is a
simple report generation facility for the \fIshapeTools\fR toolkit.
The \fIformat string\fR can be any string, but typically contains
\fIattribute citations\fR (see \fBretrv\fR). As \fIshapeTools\fR
attribute citations use a syntax that contains dollar-characters, it
is advisable, to specify \fIformat strings\fR in single-quotes to
prevent shell from trying to apply variable substitution.
.RS
.LP
\fIFormat strings\fR can contain simple layout specifications (`\fC\en\fP'
for newline characters, and `\fC\et\fP' for tabs. `\fC\e\e\fP' is a single
backslash.)
.LP
The format of the output of \fBvl \-l\fP could for example be
specified as follows:
.sp 0.2c
.ce 2
\fCvl -format \'$_\|_mode$ $_\|_state$\t$_\|_author$\t \e
$_\|_size$\t $_\|_mtime$ $_\|_self$\\n\'\fP
.LP
While the example only illustrates use of standard attributes, it is
in fact possible to use any object attribute (i.e. user-defined
attributes) in the format specification.
.RE
.IP "\fB\-F\fP (ls)"
Append a symbolic file type character to each name. Directories are
marked with a `/', sockets with a `=', symbolic links with a `@',
executable files with `*', and derived objects with a `$'. If the file
is locked a `^' is additionally appended.
.IP "\fB\-g\fP (ls)"
Print the group of the entry owner (...) .
.IP "\fB\-h\fP"
Print \fIhistories\fP instead of versions. All versions with the same
name are folded together to one printed entry.
All version binding options (see vbind(1)) are ignored, when displaying
histories.
.IP "\fB\-intent\fP"
Print message of intention for change. An intention message can be set
while retrieving a version using \fBretrv\fR with option -lock.
.IP "\fB\-l\fP (ls)"
List in long format, giving mode, version state, author, size in bytes,
the save date, and version identification. 
For busy versions the date field will contain the time of last
modification rather than the save date. The \fIstatus\fR of a version is
printed as: \fBb\fR for busy, \fBs\fR for saved, \fBp\fR for
proposed, \fBP\fR for published, \fBa\fP for accessed, \fBf\fR for frozen,
and \fB$\fR for derived.
.IP "\fB\-lll\fP"
Same as \fB-l -locked -locker\fP.
.IP "\fB\-locked\fP"
Print only locked versions.
.IP "\fB\-locker\fP"
Print the locker instead of the author and last locking date instead of
last modification or save date.
.IP "\fB\-log\fP"
Print the log entry for each version.
.IP "\fB\-L\fP (ls)"
Follow symbolic links. If a given name is a symbolic link, list the
object referenced by the link rather than the link itself.
.IP "\fB\-noexpand, \-xpoff\fP "
Do not expand attribute values. This is the default, except when the
\fB-format\fP option is set. Check \fB-expand\fP or vattr(1) for
more information on attribute expansion.
.IP "\fB\-O\fP"
Print the version owner instead of the author.
.IP "\fB\-p\fP\ \fI""all""\fP\ |\ \fIattribute\ name\fP"
Print the value of the given attribute. With the string 'all' given as
argument to the \fB-p\fP option, print all non standard attributes.
.IP "\fB\-q\fP (ls)"
Replace all non graphic character by '?' before printing. This is the
default when output goes to a terminal.
.IP "\fB\-Q\fP"
Quiet Flag. Suppress any output to standard output. Only error
messages will be printed to standard error.
.IP "\fB\-r\fP (ls)"
Reverse the order of the entries printed.
.IP "\fB\-R\fP (ls)"
Operate recursively visiting all subdirectories encountered.
.IP "\fB\-S\fP"
Print version states verbosely.
.IP "\fB\-t\fP (ls)"
Sort the list of printed entries by the modification time.
.IP "\fB\-u\fP (ls)"
Sort the list of printed entries by time of last access.
.IP "\fB\-U\fP"
Show user identifications as \fIuser@domain\fP rather than just the
user name.
.IP "\fB\-v\fP"
Print versions. This is the default (counterpart to 
.IP "\fB\-version\fP"
Print only the version identification of this program.
.IP "\fB\-x\fP (ls)"
Do multi-column output with the entries sorted across rather than down
the page.
.SH SEE ALSO
vattr(1), vbind(1)
.SH BUGS
When using the version binding options \fI\-since\fP and \fI\-before\fP,
the vl output may look confusing. \fI\-since\fP and \fI\-before\fP
define a time interval for save dates but \fIvl\fP displays the date
of last modification, which may be older than the save date.
.LP
\&'.' and '..' are always ignored when displaying versions.
.LP
Several Options are not available when displaying histories (\fI\-h\fP
option). These are: \fI\-all\fP, \fI\-attr\fP, \fI\-c\fP, \fI\-format\fP,
\fI\-intent\fP, \fI\-locked\fP, \fI\-log\fP, \fI\-n\fP, \fI\-p\fP,
\fI\-R\fP, \fI\-t\fP, and \fI\-u\fP.
.LP
The displayed group name (\fI\-g\fP option) may be wrong for busy versions.
.LP
\&\-noexpand does not work together with \-format.
.LP
\fI\-q\fP, and \fI\-F\fP are not implemented.
.SH AUTHOR
Original version by Uli.Pralle@cs.tu-berlin.de and
Axel.Mahler@cs.tu-berlin.de.
.br
Totally reimplemented by Andreas.Lampen@cs.tu-berlin.de.