NAME

       rcs2atfs - convert RCS archives to AtFS format

SYNOPSIS

       rcs2atfs [-o outputfile] [ -q] archive ...
       rcs2atfs [-o outputfile] [ -q] -R directory ...

DESCRIPTION

       Rcs2atfs  converts version histories from RCS archives to ShapeTools' AtFS format. It uses
       rlog(1) to get information about an RCS archive and issues shell commands (usually through
       a  pipe directly to /bin/sh) to check out the RCS revisions and check the files in as AtFS
       versions, trying to keep as many attributes as possible.

       The RCS archives are left unchanged.

       It is recommended to create a special directory with the name RCS for  the  RCS  archives,
       but AtFS histories are always kept in a special directory AtFS.

       Rcs2atfs  treats  its  arguments  as names of RCS archives.  These can be the names of the
       archive files themselves, ending with ,v,  or  the  names  of  the  files  stored  in  the
       archives.

       If  the  -R  option  is given, the arguments are interpreted as directory names.  Rcs2atfs
       recursively descends each directory tree (symbolic links are followed)  and  converts  the
       RCS  archives  it finds. The correspondig AtFS archives are created where the RCS archives
       are found.

       Rcs2atfs tries to keep the revision numbers of  the  RCS  history  also  as  AtFS  version
       numbers.  This  is  impossible  if  an  RCS  history  contains  branches. In this case the
       revisions are saved as AtFS versions in the order of their check-in date. In  either  case
       the  RCS  revision  number  is kept as a symbolic name for the corresponding AtFS version,
       e.g. the AtFS version of RCS revision 1.2 will have the symbolic name ``r1.2''.

   Attributes that don't change:
       •
        author

       •
        log message

       •
        comment leader

       •
        description

       •
        symbolic names (with the exception of the additional symbolic name derived from  the  RCS
        revision number)

   Other attributes:
       mtime  set to the check-in date of the RCS revision

       state  The value of this attribute is given to the AtFS attribute RCSstate.  If it has the
              value Exp, the state of the AtFS version  will  be  saved,  if  Stab,  it  will  be
              proposed, if Rel, it will be published.

OPTIONS

       -R     (recursive)
              The  arguments  are  treated  as  directories.   Rcs2atfs  recursively descends the
              directory tree (symbolic links are followed) and builds an AtFS  archive  for  each
              RCS archive it finds.

       -o outputfile
              rcs2atfs  writes  shell  commands  to  outputfile,  not directly to /bin/sh, and no
              conversion is done.  If this shell script is  executed  from  the  directory  where
              rcs2atfs  was  invoked,  the archives are converted as if rcs2atfs had been invoked
              without -o.
              The main use of this option is to  investigate  problems  with  the  conversion  of
              archives.

       -q     (quiet)
              The  names  and  revision  numbers of converted archives are not echoed on standard
              output.

EXAMPLES

       The command

              rcs2atfs -R $HOME/development

       traverses the directory tree $HOME/development and converts every RCS archive in  it  into
       an  AtFS  archive. During the conversion, the name of every RCS archive and every revision
       number is echoed on standard output.

              rcs2atfs -q RCS/*

       Each archive in the RCS directory is converted to an AtFS history. The names and  revision
       numbers of the converted archives are not echoed.

SEE ALSO

       sh(1), rcsintro(1), rcs(1), rlog(1), co(1), vcintro(1), save(1), vadm(1), utime(1)

DIAGNOSTICS

   Warnings
       -R flag not set, directory skipped
              If  the  -R flag is not set, directories given as arguments in the command line are
              ignored.

       locked version(s) exist
              A revision of the specified RCS history is locked. This is not  really  a  problem,
              but perhaps rcs2atfs does not convert the most recent version of the file.

       branches exist, can't keep revision numbers
              If  the  RCS  history contains branches, the numbers of AtFS versions cannot be the
              same as those of the corresponding RCS revisions.

       symbolic name to non-existent revision
              rlog has reported a symbolic name of  a  revision  that  does  not  exist  in  this
              archive.  Probably  this never happens (I don't know), but if, the symbolic name is
              ignored.

   Errors
       ATFS history exists, file skipped
              The specified file is already known to AtFS as a history or a  busy  version.  This
              file will nor be converted.

       colon after symbolic name missing, file skipped
       revision not found, file skipped
       date not found, file skipped
       author not found, file skipped
       status not found, file skipped
       rlog information missing, file skipped

              These  messages indicate problems with the rlog output, perhaps an old rlog version
              is used.  (rcs2atfs works correctly with rlog version 5.5.)
              The specified file will not be converted.

       rlog command failed, file skipped
              For some unknown reason rlog returned a non-zero exit  status.   rlog  should  have
              provided an explanatory message.

   Fatal Errors
       popen to rlog command failed
              The rlog command could not be invoked.

       popen to shell failed
              The shell could not be invoked.

       no more core
              Rcs2atfs  could  not  allocate  enough memory. The amount of memory in your machine
              should be increased.

   Internal Errors
       Oops? Unknown reader state in readin_rcsfile!
       revision numbers corrupted
       number of revisions is wrong!

              You should never see these error messages.

CAVEATS

       If rcs2atfs visits the same RCS archive twice (e.g. because a symbolic link is followed to
       a  directory which is also accessed directly), the check for existing AtFS archives may be
       done a second time before the conversion commands from the first visit are executed by the
       shell.  This  results  in  lots  of  annoying  messages and duplicate AtFS versions of RCS
       revisions. To avoid this, make sure that rcs2atfs doesn't reach a directory twice.

BUGS

       Rcs2atfs is rather slow since it invokes a shell command for every action.

       Attribute citations in files are not translated from RCS to AtFS (e.g.  ``$Header: ... $''
       to ``$__Header$'').

       Rcs2atfs strongly relies on the format of rlog's output. Since I don't know any other rlog
       than our version (5.5), it may fail to work with other versions.

       Due to the lack of serious RCS archives, rcs2atfs isn't thoroughly tested yet.  (Well,  we
       use ShapeTools. :-)

AUTHOR

       Juergen.Nickelsen@cs.tu-berlin.de