Provided by: aegis_4.24.3-3_amd64 bug

NAME

        aesvt - simple version tool

SYNOPSIS

        aesvt -CHeck_Out -HIstory file -File output-file [ -e edit ]
        aesvt -CHeck_In -HIstory file -File input-file [ -e edit ] [ name=value ...]
        aesvt -List -HIstory file
        aesvt -Query -HIstory file
        aesvt -Version

DESCRIPTION

        The aesvt program may be used to manage history version files.  This is a minimalist
        history tool, which makes no provision for managing a work area.

        It is able to cope with binary files, and with reasonable efficiently if they are not too
        large.

        It has good end-to-end properties because it keeps a checksum for each file version, and
        a checksum for the whole history file.

        There is no provision for keyword substitution of any kind.  A check-out will exactly
        reproduce the input file.  A check-in will never alter the input file.

OPTIONS

        The following options are understood:

        -History history-file
                This option is used to specify the name of the history file.

        -File file-name
                This option is used to specify the name of the input or output file.  On check-
                out, the file name "-" is understood to mean the standard output.  There is no
                equivalent for check-in.

        -Edit edit-number
                This option is used to specify the edit number (version number).  On check-out,
                if no version number is specified, the most recent version is given.  On check-
                in, if no version number is specifiued (and it usually isn't), the previous
                version will have one added to it, or version 1 will be used if this is the first
                check-in.

        -CHeck_In
                This option is used to check a file into the history.

        -CHeck_Out
                This option is used to check-out a file from the history.

        -compression-algorithm name
                This option may be used to specify the compression to be used.  They are listed
                on order of compression effeciency.

                none    Use no compression (not always meaningful for all commands).

                gzip    Use the compression used by the gzip(1) program.

                bzip2   Use the compression used by the bzip2(1) program.

                More compression algorithms may be added in the future.

        -COMPress
                This option is deprecated in favour of the -comp-alg=gzip or -comp-alg=bzip2
                options.

        -No_COMPress
                This options is deprecated in favour of the -comp-alg=none option.

        -List   This option is used to list the file's history.

        -Query  This option is used to query edit number of most recent check-in.

        -Version
                This option is used to print version number.

        All other options will produce a diagnostic error.

        See also aegis(1) for options common to all aegis commands.

        All options may be abbreviated; the abbreviation is documented as the upper case letters,
        all lower case letters and underscores (_) are optional.  You must use consecutive
        sequences of optional letters.

        All options are case insensitive, you may type them in upper case or lower case or a
        combination of both, case is not important.

        For example: the arguments "-project, "-PROJ" and "-p" are all interpreted to mean the
        -Project option.  The argument "-prj" will not be understood, because consecutive
        optional characters were not supplied.

        Options and other command line arguments may be mixed arbitrarily on the command line,
        after the function selectors.

        The GNU long option names are understood.  Since all option names for aesvt are long,
        this means ignoring the extra leading '-'.  The "--option=value" convention is also
        understood.

EXIT STATUS

        The aesvt command will exit with a status of 1 on any error.  The aesvt command will only
        exit with a status of 0 if there are no errors.

ENVIRONMENT VARIABLES

        See aegis(1) for a list of environment variables which may affect this command.  See
        aepconf(5) for the project configuration file's project_specific field for how to set
        environment variables for all commands executed by Aegis.

FILE FORMAT

        Each version in the history file consists of an RFC822 header, plus the file contents.
        The header includes (at least) the Content-Length, used to remember the length of the
        file data in bytes; the Checksum, used to remember the Adler32 checksum of the file data;
        and Version, used to remember the version number.  The file data can be text or binary,
        because its length is determined by the header.  There is no quoting mechanism of any
        kind for the data.  Except for the mandatory fields, additional user-defined us-ascii
        meta-data may also be stored in the header.  There is no diff or delta of any kind for
        any version.

        This combination of header and data has good end-to-end behaviour, because there is a
        checksum to validate the file data against.  Bad blocks in the data will be detected then
        next time a check-in or check-out is attempted.

        The format of the history file consists of one or more file versions with the above
        layout, joined head-to-tail with no separators or boundary indicators of any kind.  The
        versions are in descending order, from most recent (greatest edit number) to least recent
        (version number one).  To determine where one version stops and the next version starts,
        use the Content-Length field in the header.  The entire history file is then compressed
        using the bunzip2 algorithm (via libbz2).  There is no diff or delta of any kind in the
        history file.

        The advantage of compressing the file is that there is usually a very high redundancy
        between file versions.  For example, if two identical versions are checked in (not
        necessarily sequentially) the second copy will compress to only a few bytes.  Unlike
        diff(1) style deltas, this also copes very will with moving blocks of data within the
        file.  The use of bunzip2 formatting means there is also a checksum for the whole history
        file, which allows you to detect bad blocks in the header portions; it also means there
        is a simple way to extract the data from a history file even without the aesvt program,
        or for testing, or because you are curious.

        You can actually choose from a number of compression algorithms, including GNU Zip and
        bunzip2, via the -compression-algorithm option.  More copmpresison algoritthms may be
        added in the future.  The best available comression is used, because this results in the
        most compact history files.  Future versions will always be able to access the
        compression used by earlier versions.

   End-To-End Issues
        See also Saltzer, J.H. et al (1981) End-to-end arguments in system design,
        http://web.mit.edu/Saltzer/www/publications/endtoend/endtoend.pdf

   Xdelta
        This style of history file was inspired by RFC 3284 - The VCDIFF Generic Differencing and
        Compression Data Format.  While the aesvt format does not use RFC3284 internally, the
        arguments for compression across file versions are just as relevant.

COPYRIGHT

        aesvt version 4.24.3.D001
        Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
        2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Peter Miller

        The aesvt program comes with ABSOLUTELY NO WARRANTY; for details use the 'aesvt -VERSion
        License' command.  This is free software and you are welcome to redistribute it under
        certain conditions; for details use the 'aesvt -VERSion License' command.

AUTHOR

        Peter Miller   E-Mail:   millerp@canb.auug.org.au
        /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/