Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
aefstate(5)		      File Formats Manual		   aefstate(5)

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 re-
			names.	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 un-
				copied before development may end.  This ac-
				tion 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 in-
				tegrated, 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 af-
			ter 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 con-
					tent.

				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.

			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
			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 re-
			place 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_de-
			veloped	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 dif-
			ference	file when the last aegis -DIFFerence command
			was run.  It is	only present between the being_devel-
			oped and being_integrated 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 aegis -DIFFer-
			ence command was run.  It is only present in the be-
			ing_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_inte-
			grated 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 suc-
				cessful	aegis -Test command was	run for	this
				specific pattern instance.

			test_baseline_time = time;
				This field records the last time the last suc-
				cessful	aegis -Test -BaseLine 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 up-
			dates.

		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	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-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 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 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.

WRITING	REPORT SCRIPTS
	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
	src arrays.

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

SEE ALSO
	aegis(5)
		aegis file format syntax

COPYRIGHT
	aegis version 4.25.D510
	Copyright (C) 1991, 1992, 1993,	1994, 1995, 1996, 1997,	1998, 1999,
	2000, 2001, 2002, 2003,	2004, 2005, 2006, 2007,	2008, 2009, 2010,
	2011, 2012 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:	 pmiller@opensource.org.au
	/\/\*		  WWW:	 http://miller.emu.id.au/pmiller/

Reference Manual		     Aegis			   aefstate(5)

NAME | SYNOPSIS | DESCRIPTION | CONTENTS | WRITING REPORT SCRIPTS | SEE ALSO | COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=aefstate&sektion=5&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help