NAME
aefstate - aegis file state file
SYNOPSIS
project/info/change/[0-9]/[0-9][0-9][0-9].fs
DESCRIPTION
A file state file is used to store information about the files in a
transaction. These files are created and maintained by aegis. These
files should not be edited by humans. These files is owned by the
project owner and group.
CONTENTS
src = [ { ... }, ... ];
This field is a list of all the files in the change. The
records have the form
file_name = string;
This file names the file. The name is relative to the
root of the baseline directory tree.
uuid = string;
This field uniquely identifies the file for its entire
lifetime. This field remains constant across file
renames. The value of this field shall be formatted as
a valid UUID, all in lower case.
action = (create, modify, remove, insulate, transparent);
This field describes what is being done with the file.
create The file is being created. Once integrated,
the edit fields record the file version created
and stored in the history.
modify The file is being created. Once integrated,
the edit fields record the file version stored
in the history.
remove The file is being created. The edit field is
only informational, and describes the file
version at the time it was removed from the
repository.
insulate
The file is insulating a development directory
from changes to the baseline, it shall be
uncopied before development may end. This
action shall only be present in changes. It
shall never be present in branch change state
files.
transparent
The file wasonce present in the branch, however
it is desired that the ancestor version "show
through". This is the equivalent of "uncopy"
for branches. When the branch is integrated,
this file will be omitted.
edit = { ... };
For a project or an active branch, this field records
the head revision of the file. For a completed change
or branch, this field records the revision number after
integrate pass.
revision = string;
This is the edit number, as reported by the
history_get_command in the project config file
at integrate pass time.
encoding = (none, quoted_printable, base64);
This field records the encoding used when the
file was added to the history at integrate pass
time, as configured by one of the history_put_
command or history_get_command and history_
content_limitation fields of the project config
file.
none No encoding was applied to the file.
Either it had no binary characters, or
the history tool is able to cope with
binary files.
quoted_printable
The MIME Quoted Printable encoding (see
RFC 1521) has been used to escape the
binary characters of the file content.
base64 The MIME Base 64 encoding (see RFC
1521) has been used to encode the file
content.
The history_content_limitation field of the
project config file is used to determine which
files need encoding. The size of the encoded
file is compared to determine which of quoted
printable and base 64 encodings is used; the
smaller is chosen.
edit_number = string;
This field is obsolescent. It is only present for
backwards compatibility. It has been replaced by the
edit field.
edit_origin = { ... };
This field records the edit number of the file when it
was added to the change or branch. In changes, this
field is not present for new files. (A change file is
out of date if it’s edit number_origin field does not
equal the edit_number field in the project.)
It has the same fields, with the same meaning, as the
edit field, above.
edit_number_origin = string;
This field is obsolescent. It is only present for
backwards compatibility. It has been replaced by the
edit_origin field.
edit_origin_new = { ... };
This field records the edit number of the file to
replace the edit_number_origin field in the branch at
integrate pass time. This is used to perform cross
branch merging. This field cleared at integrate pass
time.
It has the same fields, with the same meaning, as the
edit field, above.
edit_number_origin_new = string;
This field is obsolescent. It is only present for
backwards compatibility. It has been replaced by the
edit_origin_new field.
usage = (source, config, build, test, manual_test);
This field describes what function the file serves.
file_fp = fingerprint;
This field records the last time modified of the source
file. It is only present between the being_developed
and being_integrated states, inclusive (for both
changes and branches). It is not present for files
which are being deleted. This field is used to
determine if a difference has been done, or a test has
been done if the source file is a test, and if the file
has been tampered with before state transitions.
The fingerprint consists of the following fields:
youngest = time;
The youngest time see for this file with this
fingerprint.
oldest = time;
The oldest time see for this file with this
fingerprint.
crypto = string;
This field records a cryptographically strong
fingerprint for the file. There is no known
method of constructing a file to match a given
fingerprint, and there is less than 1 in 2**200
chance that two files will have the same
fingerprint. Thus if the fingerprint is the
same, the file can reliably assumed to be the
same.
diff_file_fp = fingerprint;
This field records the last time modified of the
difference file when the last aegis -DIFFerence command
was run. It is only present between the
being_developed and being_integrated states, inclusive
(for both changes and branches). This field is used to
determine if a difference has been done, and if the
difference file has been tampered with before state
transitions.
idiff_file_fp = fingerprint;
This field records the last time modified of the
integration difference file when the last aegis
-DIFFerence command was run. It is only present in the
being_integrated state. This field is used to
determine if a difference has been done.
architecture_times = [{ ... }];
This field records the time of various operations for
each variant named in the architecture field. It is
only present in the being_developed and
being_integrated states. This field is used to
determine if a test has been done, and thus optimize
test runs.
variant = string;
This field is one of the patterns named in the
architecture field.
test_time = time;
This field records the last time the last
successful aegis -Test command was run for this
specific pattern instance.
test_baseline_time = time;
This field records the last time the last
successful aegis -Test -BaseLine command was
run for this specific pattern instance.
move = string;
To change the name of a file, a combination of deleting
the old name and creating the new name is used. With
deleted files, this field is used to say where it went.
With new files, this field is used to say where it came
from.
locked_by = integer;
The change which locked this file.
Caveat: this field is redundant, you can figure it out
by scanning all of he change files. Having it here is
very convenient, even though it means multiple updates.
about_to_be_created_by = integer;
The change which is about to create this file for the
first time. Same caveat as above.
about_to_be_copied_by = integer;
For each change file that is acting on a project file
from a deeper baseline than the immediate parent
project’s baseline, the file needs to be added to the
immediate parent project. Note that this field says
that this file record is a place marker, so that it can
be deleted again should the change not be integrated
for some reason.
deleted_by = integer;
The change which last deleted this file. We never
throw them away, because (a) it may be created again,
and more important (b) we need it to recreate earlier
deltas.
test = [ string ];
This field is used to remember test correlations for source
files. This is used by aet(1) to suggest suitable tests.
metrics = [ { ... } ];
This field is used to describe various file metrics. It is
committed during aeipass(1), when the file is added to the
history. The name must be given, and exactly one value.
name = string;
This is the name of the metric. This field must be
set.
value = real;
This is the value of the metric. This field must be
set. (If you have an integer-valued metric, just use
integers, Aegis will cope. If you have a string-valued
metric, assign integers to the enumerands.)
executable = boolean;
This field is used to remember whether the source file had any
executable permission bits set at develop end time. This mode
will be restored (taking the project umask into account) when
the file is copied.
This field is only meaningful for changes in the completed
state, because this field is only set by aeip(1). Until then,
the mode if the file itself is the authority.
attribute = [ { ... } ];
This is a list of (name,value) pairs, defining user specified
attributes.
name = string;
The name of the attribute. By convention, names which
start with an upper-case letter will appear in
listings, and lower-case will not. Attribute names are
case-insensitive.
value = string;
The value of the attribute.
Arguably, most file properties which may be altered by the user
(and some that can’t) should be of this form. Due to an
accident of history, this is not the case.
WRITING REPORT SCRIPTS
When attempting to access these fields from within the report
generator, you need a code fragment similar to the following:
auto ps, pfs;
ps = project[project_name()].state;
fps = ps.src["somefile"];
auto cs, cfs;
cs = ps.branch.change[change_number()];
cfs = cs.src["somefile"];
Notice that the top-level fields of the file state are not available,
but instead are mapped onto the relevant project file and change file
src arrays.
All of the src member fields mentioned in the man page can now be
accessed as members of the pfs or cfs variables.
SEE ALSO
aegis(5)
aegis file format syntax
COPYRIGHT
aegis 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 aegis program comes with ABSOLUTELY NO WARRANTY; for details use
the ’aegis -VERSion License’ command. This is free software and you
are welcome to redistribute it under certain conditions; for details
use the ’aegis -VERSion License’ command.
AUTHOR
Peter Miller E-Mail: millerp@canb.auug.org.au
/\/\* WWW: http://www.canb.auug.org.au/~millerp/