.\"
.\"	aegis - project change supervisor
.\"	Copyright (C) 1991-1996, 1998, 2001 Peter Miller;
.\"	All rights reserved.
.\"
.\"	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 2 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, write to the Free Software
.\"	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
.\"
.\" MANIFEST: User Guide, The History Tool, Using fhist
.\"
.bp
.nh 2 "Using fhist"
.LP
The
.I fhist
program was written by David I. Bell
and is admirably suited to providing a history mechanism
with out the "cruft" that SCCS and RCS impose.
.LP
Please note that the \f(CW[# edit #]\fP feature needs to be avoided,
or the
.I -Forced_Update
(-fu) flag needs to be used in addition to the
.I -Conditional_Update
(-cu) flag,
otherwise updates will complain that
``Input file "\fIXXX\fP" contains edit \fIA\fP
instead of \fIB\fP for module "\fIYYY\fP"''
.LP
The
.I history_create_command
and the
.I history_put_command
are intentionally identical.
This minimizes problems when using branches.
.nh 3 "history_create_command"
.LP
This command is used to create a new project history.
The command is always executed as the project owner.
.LP
The following substitutions are available:
.IP ${Input}
absolute path of the source file
.IP ${History}
absolute path of the history file
.LP
The entry in the
.I "config"
file looks like this:
.E(
history_create_command =
  "fhist ${b $i} -create -cu -i $i \e
   -p ${d $h} -r";
.E)
Note that the source file is left in the baseline.
.nh 3 "history_get_command"
.LP
This command is used to get a specific edit back from history.
The command may be executed by developers.
.LP
The following substitutions are available:
.IP ${History}
absolute path of the history file
.IP ${Edit}
edit number, as given by history_\%query_\%command
.IP ${Output}
absolute path of the destination file
.LP
The entry in the
.I "config"
file looks like this:
.E(
history_get_command =
  "fhist ${b $h} -e '$e' -o $o \e
   -p ${d $h}";
.E)
.LP
Note that the destination filename will
.I never
look anything like the history source filename,
so the -p is essential.
.nh 3 "history_put_command"
.LP
This command is used to add a new "top-most" entry to the
history file.
This command is always executed as the project owner.
.LP
The following substitutions are available:
.IP ${Input}
absolute path of source file
.IP ${History}
absolute path of history file
.LP
The entry in the
.I "config"
file looks like this:
.E(
history_put_command =
  "fhist ${b $i} -create -cu -i $i \e
   -p ${d $h} -r";
.E)
.LP
Note that the source file is left in the baseline.
.LP
.nh 3 "history_query_command"
.LP
This command is used to query what the history mechanism
calls the "top-most" edit of a history file.
The result may be any arbitrary string,
it need not be anything like a number,
just so long as it uniquely identifies the edit
for use by the
.I history_get_command
at a later date.
The edit number is to be printed on the standard output.
This command may be executed by developers.
.LP
The following substitutions are available:
.IP ${History}
absolute path of the history file
.LP
The entry in the
.I "config"
file looks like this:
.E(
history_query_command =
  "fhist ${b $h} -l 0 \e
   -p ${d $h} -q";
.E)
.nh 3 "Templates"
.LP
The
.I lib/config.example/fhist
file in the Aegis distribution
contains all of the above commands,
so that you may readily insert them into your project
.I config
file.
.nh 3 "Capabilities"
.LP
By default, FHist is unable to cope will NUL characters in its input
files, however this is the only limitation.  By default, Aegis expects
that history tools are only able to cope with printable ASCII text.
To tell it ontherwise, set
.E(
history_content_limitation = international_text;
.E)
in the project \fIconfig\fP file.
.PP
Aegis will transparently encode binary files (files which contain NUL
characters) on entry and exit from the history tool.  This means that
you may have binary files in your project without configuring anything
special.
.nh 3 "Binary Files"
.LP
FHist (version 1.7 and later) has support for binary files.  The \fIfhist
\-binary\fP option may be used to specify that the file is binary,
that it may contain NUL characters.  It is essential that you have
consistent presence or absence of the \-binary option for each file
when combined with the \-CReate, \-Update, \-Conditional_\%Update and
\-Extract options.  Failure to do so will produce inconsistent results.
is unable to cope with binary files.
.PP
This means that you have to \fIalways\fP use the \-binary option in the
\fIhistory_create_command\fP and \fIhistory_put_command\fP fields.  You
have to decide right at the very beginning if your project \fIhistory\fP
will ever have binary files, or will never have binary files.  You can't
change your mind later.  If you choose to use the \-binary option, set
.E(
history_content_limitation = binary_capable;
.E)
.PP
However, Aegis
will transparently encode all such files, if you leave the
\fIhistory_\%content_\%limitation\fP field set for international text.
In some cases, Aegis' encoding will be more efficient that fhist's.
And you have the advantage of being able to change your mind later.