.\"
.\"	aegis - project change supervisor
.\"	Copyright (C) 1991-1994, 1998, 2001, 2002, 2004-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/>.
.\"
.bp
.if t .2C
.nh 1 "The History Tool"
.LP
Aegis is decoupled from the history mechanism.
This allows you to use the history mechanism of your choice,
SCCS or RCS, for example.
You may even wish to write your own.
.LP
The intention of this is that you may use a history mechanism which
suits your special needs,
or the one that comes free with your flavour of
.UX
operating system.
.LP
Aegis uses the history mechanism for file
.I history
and so does not require many of the features of SCCS or RCS.
This simplistic approach can sometimes make the interface to these
utilities look a little strange.
.nh 2 "History File Names"
.LP
In order to track project source file renames and yet preserve a
continuous history, the name of each source file and the name of each
corresponding history file have nothing in common.  The history file
will have the same name (both on the local repository and any remote
repository it is in) no matter how many times the source file is
renamed.
.LP
Each source file is assigned universally unique identifier (UUID) when
it is first created.  This attribute, unlike the source file's name,
is immutable and thus is suitable for use when forming the name of the
history file.
.nh 2 "Interfacing"
.LP
The history mechanism interface is found in the
project configuration file called
.I "aegis.conf" ,
relative to the root of the baseline.
It is a source file and subject to the same controls
as any other source file.
The history fields of the file are described as follows
.nh 3 "history_create_command"
.LP
This field is used to create a new history.
The command is always executed as the project owner.
Substitutions available for the command string are:
.IP ${Input}
absolute path of source file
.IP ${History}
absolute path of history file
.LP
In addition, all substitutions described in \fIaesub\fP(5) are available.
.LP
This command should be identical to the \fIhistory_\%put_\%command\fP
otherwise mysterious things can happen when branches are ended.
.nh 3 "history_get_command"
.LP
This field is used to get a file from history.
The command may be executed by developers.
Substitutions available for the command string are:
.IP ${History}
absolute path of history file
.IP ${Edit}
edit number, as given by the history_\%query_\%command.
.IP ${Output}
absolute path of destination file
.LP
In addition, all substitutions described in \fIaesub\fP(5) are available.
.nh 3 "history_put_command"
.LP
This field is used to add a new change to the history.
The command is always executed as the project owner.
Substitutions available for the command string are:
.IP ${Input}
absolute path of source file
.IP ${History}
absolute path of history file
.LP
In addition, all substitutions described in \fIaesub\fP(5) are available.
.LP
This command should be identical to the \fIhistory_\%create_\%command\fP
otherwise mysterious things can happen when branches are ended.
.nh 3 "history_query_command"
.LP
This field is used to query the topmost edit of a history file.
Result to be printed on the standard output.
This command may be executed by developers.
Substitutions available for the command string are:
.IP ${History}
absolute path of history file
.LP
In addition, all substitutions described in \fIaesub\fP(5) are available.
.nh 3 "history_content_limitation"
.LP
This field describes the content style which the history tool is
capable of working with.
.IP ascii_text
The history tool can only cope with files which contain printable
ASCII characters, plus space, tab and newline.	The file must
end with a newline.  This is the default.
.IP international_text
The history tool can only cope with files which do not contain
the NUL character.  The file must end with a newline.
.IP binary_capable
The history tool can cope with files without any limitation on
the form of the contents.
.LP
When a file is added to the history (by either the
\fIhistory_\%create_\%command\fP or the \fIhistory_\%put_\%command\fP
field) it is examined for conformance to this limitation.  If there is
a problem, the file is encoded in either the MIME quoted printable or
the MIME Base 64 encoding (see RFC 1521), whichever is smaller, before
being given to the history tool.  The file in the baseline is unchanged.
.LP
On extract (the \fIhistory_get_command\fP field) the encoding is reversed,
using information attached to the change file information.  This is
because each put could use a different encoding (although in practice,
file contents rarely change that dramatically, and the same encoding is
likely to be deduced every time).
.nh 3 "history_tool_trashes_file"
.LP
Many history tools (e.g. RCS) can modify the contents of the file
when it is committed.  While there are usually options to turn this
off, they are seldom used.  The problem is: if the commit changes the
file, the source in the repository now no longer matches the object
file in the repository - \fIi.e.\fP the history tool has compromised the
referential integrity of the repository.
.LP
By default, when this happens Aegis issues a fatal error (at \fIintergate
pass\fP time).  You can turn this into a warning if you are convinced
this is irrelevant.  This would only make sense if the substition only
ever occurs in comments.  See \fIaepconf\fP(5) for more information
on the values for this field.
.nh 3 "Quoting Filenames"
.LP
The default setting is for Aegis to reject filenames which contain shell
special characters.  This ensures that filenames may be substituted
into the commands without worrying about whether this is safe.  If you
set the \fIshell_safe_filenames\fP field of the project \fIaegis.conf\fP
file to \f(CWfalse\fP, you will need to surround filenames with the
\f[CW]${quote\fP \fIfilename\fP\f[CW]}\fP substitution.  This will only
quote filenames which actually need to be quoted, so users usually will
not notice.  This applies to all of the various filenames in
the commands in the sections which follow.
.nh 3 "Templates"
.LP
The source distribution contains numerous configuration examples in
a directory called \fIlib/config.example/\fP which is installed into
\fI\*(D)/config.example/\fP by default.  In the interests of accuracy,
it may be best to copy configurations from there, rather than copy-type
the ones below.
.so c3.5.so
.so c3.1.so
.so c3.2.so
.so c3.3.so
.so c3.4.so