'\" t
.\"	aegis - project change supervisor
.\"	Copyright (C) 2005-2008 Peter Miller
.\"
.\"	This program is free software; you can redistribute it and/or modify
.\"	it under the terms of the GNU General Public License as published by
.\"	the Free Software Foundation; either version 3 of the License, or
.\"	(at your option) any later version.
.\"
.\"	This program is distributed in the hope that it will be useful,
.\"	but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"	GNU General Public License for more details.
.\"
.\"	You should have received a copy of the GNU General Public License
.\"	along with this program. If not, see
.\"	<http://www.gnu.org/licenses/>.
.\"
.\"
.\"	aegis - project change supervisor
.\"	Copyright (C) 1991-1993, 1997, 2006-2008 Peter Miller
.\"
.\"	This program is free software; you can redistribute it and/or modify
.\"	it under the terms of the GNU General Public License as published by
.\"	the Free Software Foundation; either version 3 of the License, or
.\"	(at your option) any later version.
.\"
.\"	This program is distributed in the hope that it will be useful,
.\"	but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"	GNU General Public License for more details.
.\"
.\"	You should have received a copy of the GNU General Public License
.\"	along with this program. If not, see
.\"	<http://www.gnu.org/licenses/>.
.\"
.ds n) aegis
.ds N) Aegis
.if n .nr )M 8n
.if n .nr IN 8n
.if n .nr )I 8n
.if n .po 0
.hy 0
.if n .ad l
.de r)
.if !'\\*(R)'no' \{\
.PP
See also
.IR \*(n) (1)
for options common to all \*(n) commands.
.\}
..
.de eB
.RS
.nf
.ft CW
.ta 8n 16n 24n 32n
..
.de eE
.ft P
.fi
.RE
..
.ds n) aesvt
.TH "aesvt" 1 \*(N) "Reference Manual" ""
.SH NAME
aesvt \- simple version tool
.XX "aesvt(1)" "simple vertion tool"
.SH SYNOPSIS
\fB\*(n) \-CHeck_Out \-HIstory\fP \fIfile\fP \fB\-File\fP \fIoutput-file\fP
[ \fB\-e\fP \fIedit\fP ]
.br
\fB\*(n) \-CHeck_In \-HIstory\fP \fIfile\fP \fB\-File\fP \fIinput-file\fP
[ \fB\-e\fP \fIedit\fP ]
[ \fIname\fP\fB=\fP\fIvalue\fP ...]
.br
\fB\*(n) \-List \-HIstory\fP \fIfile\fP
.br
\fB\*(n) \-Query \-HIstory\fP \fIfile\fP
.br
\fB\*(n) \-Version\fP
.SH DESCRIPTION
The \fI\*(n)\fP program may be used to manage history version files.
This is a minimalist history tool, which makes no provision for managing
a work area.
.PP
It is able to cope with binary files, and with reasonable efficiently if
they are not too large.
.PP
It has good end-to-end properties because it keeps a checksum for each
file version, and a checksum for the whole history file.
.PP
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.
.PP
.br
.ne 1i
.SH OPTIONS
The following options are understood:
.TP
\fB\-History\fP \fIhistory-file\fP
This option is used to specify the name of the history file.
.TP 8n
\fB\-File\fP \fIfile-name\fP
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 \fBno\fP equivalent for check-in.
.TP 8n
\fB\-Edit \fIedit-number\fP
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.
.TP 8n
\fB\-CHeck_In
This option is used to check a file into the history.
.TP 8n
\fB\-CHeck_Out
This option is used to check-out a file from the history.
.\"
.\"	aegis - project change supervisor
.\"	Copyright (C) 2006-2008 Peter Miller
.\"
.\"	This program is free software; you can redistribute it and/or modify
.\"	it under the terms of the GNU General Public License as published by
.\"	the Free Software Foundation; either version 3 of the License, or
.\"	(at your option) any later version.
.\"
.\"	This program is distributed in the hope that it will be useful,
.\"	but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"	GNU General Public License for more details.
.\"
.\"	You should have received a copy of the GNU General Public License
.\"	along with this program. If not, see
.\"	<http://www.gnu.org/licenses/>.
.\"
.TP 8n
\fB\-compression-algorithm\fP \fIname\fP
.RS
This option may be used to specify the compression to be used.
They are listed on order of compression effeciency.
.TP 8n
none
Use no compression (not always meaningful for all commands).
.TP 8n
gzip
Use the compression used by the \fIgzip\fP(1) program.
.TP 8n
bzip2
Use the compression used by the \fIbzip2\fP(1) program.
.PP
More compression algorithms may be added in the future.
.RE
.TP 8n
\fB\-COMPress\fP
This option is deprecated in favour of the \fB\-comp-alg=gzip\fP or
\fB\-comp-alg=bzip2\fP options.
.TP 8n
\fB\-No_COMPress\fP
This options is deprecated in favour of the \fB\-comp-alg=none\fP option.
.TP 8n
\fB\-List
This option is used to list the file's history.
.TP 8n
\fB\-Query
This option is used to query edit number of most recent check-in.
.TP 8n
\fB\-Version
This option is used to print version number.
.PP
All other options will produce a diagnostic error.
.\"
.\"	aegis - project change supervisor
.\"	Copyright (C) 1991-1993, 2006-2008 Peter Miller.
.\"
.\"	This program is free software; you can redistribute it and/or modify
.\"	it under the terms of the GNU General Public License as published by
.\"	the Free Software Foundation; either version 3 of the License, or
.\"	(at your option) any later version.
.\"
.\"	This program is distributed in the hope that it will be useful,
.\"	but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"	GNU General Public License for more details.
.\"
.\"	You should have received a copy of the GNU General Public License
.\"	along with this program. If not, see
.\"	<http://www.gnu.org/licenses/>.
.\"
.r)
.PP
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.
.PP
All options are case insensitive,
you may type them in upper case or lower case or a combination of both,
case is not important.
.PP
For example:
the arguments "-project, "-PROJ" and "-p" are
all interpreted to mean the \fB-Project\fP option.
The argument "-prj" will not be understood,
because consecutive optional characters were not supplied.
.PP
Options and other command line arguments may be
mixed arbitrarily on the command line,
after the function selectors.
.br
.ne 4
.PP
The GNU long option names are understood.
Since all option names for
.I \*(n)
are long,
this means ignoring the extra leading '-'.
The "\fB--\fIoption\fB=\fIvalue\fR" convention is also understood.
.\"
.\"	aegis - project change supervisor
.\"	Copyright (C) 1991-1993, 1995, 1997, 2004, 2006-2008 Peter Miller
.\"
.\"	This program is free software; you can redistribute it and/or modify
.\"	it under the terms of the GNU General Public License as published by
.\"	the Free Software Foundation; either version 3 of the License, or
.\"	(at your option) any later version.
.\"
.\"	This program is distributed in the hope that it will be useful,
.\"	but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"	GNU General Public License for more details.
.\"
.\"	You should have received a copy of the GNU General Public License
.\"	along with this program. If not, see
.\"	<http://www.gnu.org/licenses/>.
.\"
.SH EXIT STATUS
The
.I \*(n)
command will exit with a status of 1 on any error.
The
.I \*(n)
command will only exit with a status of 0 if there are no errors.
.SH ENVIRONMENT VARIABLES
See \fIaegis\fP(1) for a list of environment variables which may affect
this command.
See \fIaepconf\fP(5) for the project configuration file's
\fIproject_\%specific\fP field for how to set environment variables for
all commands executed by Aegis.
.SH 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.
.PP
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.
.PP
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.
.PP
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 \fIdiff\fP(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 \fI\*(n)\fP program, or for testing, or
because you are curious.
.PP
You can actually choose from a number of compression algorithms,
including GNU Zip and bunzip2, via the \f[CW]\-compression-algorithm\fP
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.
.SS End-To-End Issues
See also
Saltzer, J.H. \fIet al\fP (1981) \fIEnd-to-end arguments in system design\fP,
http://web.mit.edu/\%Saltzer/\%www/\%publications/\%endtoend/\%endtoend.pdf
.SS Xdelta
This style of history file was inspired by RFC 3284 \- \fIThe VCDIFF
Generic Differencing and Compression Data Format\fP.  While the
\fI\*(n)\fP format does not use RFC3284 internally, the arguments for
compression across file versions are just as relevant.
.\"
.\"	aegis - project change supervisor
.\"	Copyright (C) 1991-1995, 1997, 2006-2008 Peter Miller
.\"
.\"	This program is free software; you can redistribute it and/or modify
.\"	it under the terms of the GNU General Public License as published by
.\"	the Free Software Foundation; either version 3 of the License, or
.\"	(at your option) any later version.
.\"
.\"	This program is distributed in the hope that it will be useful,
.\"	but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"	GNU General Public License for more details.
.\"
.\"	You should have received a copy of the GNU General Public License
.\"	along with this program. If not, see
.\"	<http://www.gnu.org/licenses/>.
.\"
.br
.ne 2i
.SH COPYRIGHT
.ds v) 4.24.3
.ds V) 4.24.3.D001
.ds o) 0
.ds p) 4.25
.ds u) 4.24
.ds Y) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
\*(n) version \*(V)
.br
.if t .ds C) \(co
.if n .ds C) (C)
Copyright \*(C) \*(Y) Peter Miller
.PP
The \*(n) program comes with ABSOLUTELY NO WARRANTY;
for details use the '\fI\*(n) -VERSion License\fP' command.
This is free software
and you are welcome to redistribute it under certain conditions;
for details use the '\fI\*(n) -VERSion License\fP' command.
.br
.ne 1i
.SH AUTHOR
.TS
tab(;);
l r l.
Peter Miller;E-Mail:;millerp@canb.auug.org.au
\f(CW/\e/\e*\fR;WWW:;http://www.canb.auug.org.au/~millerp/
.TE