aefstate(5)		      File Formats Manual		   aefstate(5)


NNAAMMEE
	aefstate - aegis file state file

SSYYNNOOPPSSIISS
	_p_r_o_j_e_c_t/info/change/_[_0_-_9_]/_[_0_-_9_]_[_0_-_9_]_[_0_-_9_].fs

DDEESSCCRRIIPPTTIIOONN
	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.

CCOONNTTEENNTTSS
	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	cre-
				ated 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,	how-
				ever 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
				_h_i_s_t_o_r_y___g_e_t___c_o_m_m_a_n_d in the project _c_o_n_f_i_g 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
				_h_i_s_t_o_r_y___p_u_t___c_o_m_m_a_n_d or _h_i_s_t_o_r_y___g_e_t___c_o_m_m_a_n_d and
				_h_i_s_t_o_r_y___c_o_n_t_e_n_t___l_i_m_i_t_a_t_i_o_n fields of the
				project	_c_o_n_f_i_g 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 con-
					tent.

				base64	The MIME Base 64 encoding (see RFC
					1521) has been used to encode the file
					content.

				The _h_i_s_t_o_r_y___c_o_n_t_e_n_t___l_i_m_i_t_a_t_i_o_n field of	the
				project	_c_o_n_f_i_g 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.

			uuid = string;
				This is	the UUID of the	change responsible for
				the edit.

		edit_number = string;
			This field is obsolescent.  It is only present for
			backwards compatibility.  It has been replaced by the
			_e_d_i_t 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
			_e_d_i_t field, above.

		edit_number_origin = string;
			This field is obsolescent.  It is only present for
			backwards compatibility.  It has been replaced by the
			_e_d_i_t___o_r_i_g_i_n 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
			_e_d_i_t field, above.

		edit_number_origin_new = string;
			This field is obsolescent.  It is only present for
			backwards compatibility.  It has been replaced by the
			_e_d_i_t___o_r_i_g_i_n___n_e_w	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
			_b_e_i_n_g___d_e_v_e_l_o_p_e_d	and _b_e_i_n_g___i_n_t_e_g_r_a_t_e_d 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 dif-
			ference	file when the last _a_e_g_i_s _-_D_I_F_F_e_r_e_n_c_e command
			was run.  It is	only present between the _b_e_i_n_g___d_e_v_e_l_-
			_o_p_e_d and _b_e_i_n_g___i_n_t_e_g_r_a_t_e_d states, inclusive (for both
			changes	and branches).	This field is used to deter-
			mine if	a difference has been done, and	if the differ-
			ence file has been tampered with before	state transi-
			tions.

		idiff_file_fp =	fingerprint;
			This field records the last time modified of the inte-
			gration	difference file	when the last _a_e_g_i_s _-_D_I_F_F_e_r_-
			_e_n_c_e command was run.  It is only present in the
			_b_e_i_n_g___i_n_t_e_g_r_a_t_e_d state.	 This field is used to deter-
			mine if	a difference has been done.

		architecture_times = [{	... }];
			This field records the time of various operations for
			each variant named in the _a_r_c_h_i_t_e_c_t_u_r_e field.  It is
			only present in	the _b_e_i_n_g___d_e_v_e_l_o_p_e_d and	_b_e_i_n_g___i_n_t_e_-
			_g_r_a_t_e_d 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
				_a_r_c_h_i_t_e_c_t_u_r_e field.

			test_time = time;
				This field records the last time the last suc-
				cessful	_a_e_g_i_s _-_T_e_s_t command was	run for	this
				specific pattern instance.

			test_baseline_time = time;
				This field records the last time the last suc-
				cessful	_a_e_g_i_s _-_T_e_s_t _-_B_a_s_e_L_i_n_e command was run
				for this specific pattern instance.

		move = string;
			To change the name of a	file, a	combination of delet-
			ing 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 inte-
			grated 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	_a_e_t(1) to suggest suitable tests.

	metrics	= [ { ... } ];
		This field is used to describe various file metrics.  It is
		committed during _a_e_i_p_a_s_s(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-val-
			ued 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 _d_e_v_e_l_o_p _e_n_d 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 _c_o_m_p_l_e_t_e_d
		state, because this field is only set by _a_e_i_p(1).  Until then,
		the mode if the	file itself is the authority.

	attribute = [ {	... } ];
		This is	a list of _(_n_a_m_e_,_v_a_l_u_e_) 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 list-
			ings, 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.

WWRRIITTIINNGG	RREEPPOORRTT SSCCRRIIPPTTSS
	When attempting	to access these	fields from within the report genera-
	tor, 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
	_s_r_c arrays.

	All of the src member fields mentioned in the man page can now be
	accessed as members of the pfs or cfs variables.

SSEEEE AALLSSOO
	_a_e_g_i_s(5)
		aegis file format syntax

CCOOPPYYRRIIGGHHTT
	aegis version 4.25.D611
	Copyright (C) 1991, 1992, 1993,	1994, 1995, 1996, 1997,	1998, 1999,
	2000, 2001, 2002, 2003,	2004, 2005, 2006, 2007,	2008, 2009, 2010,
	2011, 2012, 2013, 2014 Peter Miller

	The aegis program comes	with ABSOLUTELY	NO WARRANTY; for details use
	the '_a_e_g_i_s _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command.  This is free software and you
	are welcome to redistribute it under certain conditions; for details
	use the	'_a_e_g_i_s _-_V_E_R_S_i_o_n	_L_i_c_e_n_s_e' command.

AAUUTTHHOORR
	Peter Miller   E-Mail:	 pmiller@opensource.org.au
	/\/\*		  WWW:	 http://miller.emu.id.au/pmiller/


Reference Manual		     Aegis			   aefstate(5)