NAME

       retrv - retrieve a revision of a file

SYNOPSIS

       retrv [ version binding options ] [ options ] files ..

       Options: [ -?cfilq ] [ -help ] [ -copy ] [ -dest path ] [ -fix ] [ -force ] [ -intent message ] [ -lock ]
                [ -quiet ] [ -stdin ] [ -version ] [ -xpoff ]

       vcat [ version binding options ] [ options ] files ..

       Options: [ -?q ] [ -help ] [ -quiet ] [ -version ] [ -xpoff ]

DESCRIPTION

       Retrv retrieves a specified, previously saved version of a file from the version object base. The version
       archive  is  expected to reside in the AtFS subdirectory. A selected version will by default be retrieved
       into a file in the directory where it was originally saved.  If just a copy of a file  version  shall  be
       retrieved,  this  behavior can be overridden with the -dest option. If a busy version is created with the
       -lock option, it must be created in the directory from where it was saved. This is necessary to  maintain
       the  spatial relationship between the busy version and the corresponding history archive, residing in the
       AtFS subdirectory.

       Retrieve tries to be careful if an attempt is made to  overwrite  an  existing  busy-version:  unless  -f
       (-force)  is  specified,  retrv  will  ask  the caller for permission.  If no busy version exists, one is
       created with the same modes as the formerly saved version. If  a  busy  version  exists,  its  modes  are
       preserved.

       If the program is invoked as vcat, the specified version(s) will be printed on standard output. No status
       change of the object base will occur in this case.  vcat behaves similar to the cat(1) command: if just a
       filename  is given, vcat displays the most recent status of the referenced object. If a busy version does
       exist it will be selected as most recent status. If no  busy  version  exists,  vcat  displays  the  most
       recently saved version.

ATTRIBUTE CITATIONS

       It is possible to cite any of a file-version's attributes within the the body of the version. This can be
       done by using attribute citation  expressions.  These  expressions  have  the  form  "$__attributename$".
       Version  attributes  that are cited within the text of a stored revision are expanded by default. In this
       case, the citation expression will be  substituted  by  the  cited  attribute's  value.  For  a  list  of
       predefined attribute names, check the vadm(1) manual page.

       There  are three basic kinds of attribute values: genuine values, reference values, and execution values.
       Genuine values are simply strings that are assigned to an attribute.  Reference values  are  pointers  to
       files  or  AtFS-versions whose contents will be substituted in place of an attribute-citation.  Reference
       values are strings  that  begin  with  a  circumflex-character,  typically  followed  by  pathname,  e.g.
       ^/usr/local/lib/std-header[2.4]. Execution values are names of executable programs, whose standard output
       is substituted in place of an attribute-citation.  Execution  values  are  strings  that  begin  with  an
       exclamation-mark  character,  typically  followed  by the name of the program, e.g. !/bin/date. Execution
       values can be used to generate highly dynamic attributes or a primitive form of event-triggers.

       When expanding an attribute citation, retrv first looks for an attribute of the mentioned name within the
       version's  set  of  associated  attributes. If no attribute of that name can be found, the environment is
       searched for a variable of that name. In case the cited attribute exists and has a value,  the  value  is
       itself  searched  for  attribute-citations that are expanded recursively.  If neither an attribute nor an
       environment variable of the cited name can be found, no substitution takes place and the expression  will
       be  left  unchanged.  The  same is true if a referenced object of a reference value does not exist, or an
       execution value happens to not be executable.  Attribute citation expressions are also left unchanged  if
       a  revision  is retrieved with the -lock option.  Expansion of attribute citation within documents can be
       controlled by the pseudo-attribute citations "$__xpoff$" and "$__xpon$".

OPTIONS

       For version selection, any version binding option, as described on  the  vbind(1)  manual  page,  may  be
       given, or a version bind directive may be given in brackets added to the file name.

       Additional options are:

       -?, -help
              print brief instructions about using this program.

       -c, -copy
              Do not check for equality. Usually, retrv checks whether an existing destination file is identical
              to the version to be retrieved and suppresses copying in this case. This behaviour is  mainly  for
              efficiency reasons and may be disabled by the -c switch.

       -dest path
              retrieve the specified version from the object base and install a copy it in the directory denoted
              by path. As this directory may be a  long  way  apart  from  the  directory  containing  the  AtFS
              archives,  this  copy  of  the  retrieved  version  is separated from its history and subsequently
              unrelated to the object history it came from. Proper object histories require a  constant  spatial
              relationship  of  any busy versions and the corresponding archives. This relationship requires the
              archives to reside in a subdirectory named AtFS.

       -fix   attempt to reserve the privilege to add a new version to an old generation  (insert  a  new  minor
              revision into an old major revision) within the object history. If successful, the user who issued
              the command holds a generation lock. There  can  be  only  one  lock  per  generation,  preventing
              simultaneous  updates  of  the  generation. The generation lock is, by convention, a revision lock
              (see vadm -lock) attached to the version with the highest version number within a generation.

              The -fix switch is intended to support concurrency of the main development process and maintenance
              activities  (such  as bug fixing) for older releases. When a version is retrieved with the purpose
              to fix it, it is called the fixpoint version. The fixpoint version accumulates all  fixes  applied
              to  a  baseline  version  within  a  generation.  One  important  advantage  of this policy is the
              elimination of the need to create a branch for each  fix  that  must  later  be  merged  with  the
              ``mainline''  version,  containing  previous  fixes. So, if retrv is invoked with ``-fix'' it will
              restore the fixpoint version (the most recent minor revision within the implied generation) rather
              than  the explicitly referenced version. However, retrv issues a warning, if the baseline- and the
              fixpoint version are not identical.

              To insert a fix into an old generation, use the -fix option of the save command.  When  setting  a
              lock  on  a generation, the requesting user is prompted for an optional description of the planned
              changes.  The -fix switch is incompatible with -lock.

       -f, -force
              force the reinstallation of the specified version as busy version without asking the user, even if
              a writable (possibly unsaved) busy version exists.

       -i message
              set  message  as  intent  text  describing  the  changes that are intended to be applied to a busy
              version that is installed by retrv. When message starts with an at sign (@), it is interpreted  as
              filename  and  the  text  contained  in the file is takes as intent text. If message is ``-'', the
              change intent is read from standard input. The latter case is identical to specifying the  command
              line switch -stdin. This option requires the -lock switch to be set in order to be effective.

       -l, -lock
              attempt  to  reserve  the privilege to add a new version to the main development line of an object
              history, thus preventing multiple programmers working upon the same object base  from  interfering
              with  each  other  by  saving  concurrent  updates.  When setting a new lock on an object history,
              prompt the requesting user for an optional description of the planned changes.  The  -lock  switch
              is incompatible with -fix.

       -q, -quiet
              quiet operation. No messages are printed on standard output.  If a current busy version exists, it
              will not be overwritten by the specified version unless -f is set. This option is useful for batch
              operation.

       -stdin force  retrv  to  read  the  message  describing  the change intent from stdin rather than fork an
              editor.

       -version
              print version identification for this program.

       -xpoff Do not expand attribute citations in the restored file.

FILES

       All revisions of documents are retrieved from archive files located in the subdirectory AtFS.

SEE ALSO

       vbind(1), save(1), vadm(1)

BUGS

       Redirection of stdin in conjunction with option -stdin doesn't work.

AUTHOR

       Axel.Mahler@cs.tu-berlin.de