Provided by: aegis_4.24.3-3_amd64 bug

NAME

        aepconf - aegis project configuration file

SYNOPSIS

        project/baseline/aegis.conf (default)
        project/baseline/config (obsolete)

DESCRIPTION

        A project configuration file is used to store information about a project.  This file is
        under source control, and is one of the project's source files.  Developers may thus
        modify this file as part of a change.

        As of aegis.4.17, it is possible to assign any arbitrary name to the project
        configuration file or files.  See aenf(1) for more information.

        This file contains a number of commands to be executed by Aegis.  There are times when
        the substitutions in these commands may contain shell special characters, which would
        change the meaning of the commands in unintended ways.  There are two main sources of
        these problems: file names and architecture names.  In order to have shell special
        characters in filenames, you must set the shell_safe_filenames field (see below) to
        false.  If you do this, you will need to use the quote substitution (see aesub(5)) to
        quote them, so that the shell does not abuse them.  Other things which may need quoting
        include architecture names if you get creative, and edit numbers if unusual ones are
        generated by your history tool.

   Getting Started
        Because the project aegis.conf file is under source control like any other file, you must
        create the project aegis.conf file in the very first change of your project.  Use the
                $ aenf aegis.conf
                $
        command and then editing the file to fill in the fields.  Subsequent Aegis commands in
        that change will use that file.  Once the change is completed (see aeipass(1) for more
        information) the file will be present in the baseline, and be used by all users and all
        changes.

        If you ever need to change one of the fields of the project aegis.conf file, you do this
        the same way as for any other source file, by copying it into a change using the
                $ aecp aegis.conf
                $
        command and then edit the file to make the desired changes.  While it's being developed
        your change will use it's copy of the project aegis.conf file, but once the change is
        completed (see aeipass(1) for more information), it becomes the new version used by all
        users and changes.

        If you would prefer a different name for the project configuration file, use the aenf
        -config option.  For example, the
                $ aenf -config project.configuration
                $
        command would create a file called project.configuration and Aegis would then proceed to
        use it to obtain project configuration information for the duration of the project.  This
        attribute will even be preserved across file renames (see the aemv(1) command).

CONTENTS

        This file contains the following fields:

        configuration_directory = string;
                This field names a directory which will be searched for additional configuration
                files.  (This directive is only legal or meaningful in the master project
                aegis.conf file.)

                All source files (change source files and project source files) present in this
                directory will be read in as if they were added to the end of the project
                "aegis.conf" file.

                The usual priority of files (development directory, branch baseline, etc, project
                trunk baseline) is observed when these files are read.

                Please note that the physical directories are never searched, only the Aegis
                concept of the change and project files is consulted (i.e.  files created and
                modified in the usual way with aenf(1) and aecp(1) commands).  Placing additional
                files in the physical directories will have no effect.

                It is recommended that if you use this field at all, that your top level project
                aegis.conf file should only contain this one field.  This is to avoid overly-
                large re-reading of this file when it is joined to all the others.

        build_command = string;
                This field describes how to build the project (actually, how to do an integration
                build).  This field is mandatory.  Used by the aeb(1) command.  All of the
                substitutions described by aesub(5) are available.

                Executed as: the integrator (for integration builds) or the developer (for
                development builds).  Current directory: the integration directory of the change
                (for integration builds) the development directory of the change (for development
                builds).  Exit status: zero is considered success, non-zero is a failure and a
                subsequent successful (exit zero) build will be required.

                If this field is set to "exit 0" then no integration build will be required, and
                will not be checked for by the aeipass(1) command.

        development_build_command = string;
                This field describes how to do a development build.  If this field is absent, it
                defaults to the above.  Used by the aeb(1) command.  All of the substitutions
                described by aesub(5) are available.

                Executed as: the developer.  Current directory: the development directory of the
                change.  Exit status: zero is considered success, non-zero is a failure and a
                subsequent successful (exit zero) build will be required.

                If this field is set to "exit 0" then no development build will be required, and
                will not be checked for by the aede(1) command.

        development_directory_style = { ... };
                This field encapsulates a set of parameters controlling the appearance of the
                development directory.  It has significant implications for the way the DMT is
                used, and the directory appearance presented to the DMT.

                source_file_link = boolean;
                        This field is true if hard links are to be used for project source files
                        (which are not part of the change) so that the work area has a complete
                        set of source files.

                        Defaults to false if not set.

                        If the host system does not have hard links, this field will be ignored.

                        Maintaining the hard links can be time consuming for large projects, and
                        add quite a noticeable delay before builds start doing anything.  If
                        possible, change your build system to use the $search_path substitution
                        instead and avoid links.

                source_file_symlink = boolean;
                        This field is true if symbolic links are to be used for project source
                        files (which are not part of the change) so that the work area has a
                        complete set of source files.

                        Defaults to false if not set.  [If the obsolete create_symlinks_before_‐
                        build field is set, defaults to the value of that field, with a warning.]

                        If (source_file_link == true and hard links are available) this field
                        will be ignored.  If the host system does not have symbolic links, this
                        field will be ignored.

                        Maintaining the symbolic links can be time consuming for large projects,
                        and add quite a noticeable delay before builds start doing anything.  If
                        possible, change your build system to use the $search_path substitution
                        instead and avoid symbolic links.

                source_file_copy = boolean;
                        This field is true if copies are to be used for project source files
                        (which are not part of the change) so that the work area has a complete
                        set of source files.  File modification time attributes will be
                        preserved.

                        Defaults to false if not set.

                        If ((source_file_link == true and hard links are available) OR
                        (source_file_symlink == true and symbolic links are available)) this
                        field will be ignored.

                        Maintaining the copies can be time consuming (and space consuming) for
                        large projects, and add quite a noticeable delay before builds start
                        doing anything.  If possible, change your build system to use the
                        $search_path substitution instead and avoid file copies.

                source_file_whiteout = boolean;
                        The source_file_whiteout field mat be used to specify the presence (true)
                        or absence (false) of white-out files, used to "cover up" files being
                        removed by a change set.  These files contain 1kB of random data,
                        intended to cause a syntax error should be build reference them.

                        It is rarely necessary to explicitly set this field.  It defaults to
                        false if you set any of the source_file_link, source_file_symlink or
                        source_file_copy to true; it defaults to true only if none of them are
                        true.

                        Not meaningful (always false) for integration builds.

                derived_file_link = boolean;
                        This field is true if hard links are to be used for non-source files
                        which are present in the project baseline(s) but which are not present in
                        the work area, so that the work area has a complete set of derived files.
                        This allows work areas to take advantage of "precompiled" object files
                        (etc) in the baseline(s).

                        Defaults to false if not set.

                        If the host system does not have hard links, this field will be ignored.

                        Maintaining the links can be time consuming for large projects, and add
                        quite a noticeable delay before builds start doing anything.  If
                        possible, change your build system to use the $search_path substitution
                        instead and avoid hard links.  Alternatively, set derived_at_start_only =
                        true; and your work area will get a "head start" but the derived files
                        will not be checked for every build, but this will occasionally result in
                        long build times after integrations.

                        See also the integrate_begin_exceptions and symlink_exceptions fields
                        (they apply to hard links as well as symbolic links).

                derived_file_symlink = boolean;
                        This field is true if symbolic links are to be used for non-source files
                        which are present in the project baseline(s) but which are not present in
                        the work area, so that the work area has a complete set of derived files.
                        This allows work areas to take advantage of "precompiled" object files
                        (etc) in the baseline(s).

                        Defaults to false if not set.  [If the obsolete create_symlinks_before_‐
                        build field is set, defaults to the value of that field, with a warning.]

                        If (derived_file_link == true and hard links are available) this field
                        will be ignored.  If the host system does not have symbolic links, this
                        field will be ignored.

                        Maintaining the symbolic links can be time consuming for large projects,
                        and add quite a noticeable delay before builds start doing anything.  If
                        possible, change your build system to use the $search_path substitution
                        instead and avoid symbolic links.  Alternatively, set
                        derived_at_start_only = true; and your work area will get a "head start"
                        but the derived files will not be checked for every build, occasionally
                        resulting in long build times after integrations.

                        See also the integrate_begin_exceptions and symlink_exceptions fields.

                derived_file_copy = boolean;
                        This field is true if copies are to be used for non-source files which
                        are present in the project baseline(s) but which are not present in the
                        work area, so that the work area has a complete set of derived files.
                        This allows work areas to take advantage of "precompiled" object files
                        (etc) in the baseline(s).

                        Defaults to false if not set.

                        If ((derived_file_link == true and hard links are available) or
                        (derived_file_symlink == true and symbolic links are available)) this
                        field will be ignored.

                        Maintaining the copies can be time consuming (and space consuming) for
                        large projects, and add quite a noticeable delay before builds start
                        doing anything.  If possible, change your build system to use the
                        $search_path substitution instead and avoid symbolic links.
                        Alternatively, set derived_at_start_only = true; and your work area will
                        get a "head start" but the derived files will not be checked for every
                        build, occasionally resulting in long build times after integrations.

                        See also the integrate_begin_exceptions and symlink_exceptions fields
                        (they apply to copies as well as symbolic links).

                during_build_only = boolean;
                        This field is set to true if you want the symbolic links, hard links
                        and/or copies removed again after each build.  This allows the user to
                        maintain the illusion of using a search path, without actually doing so.
                        This option is not especially efficient.

                        Defaults to false if not set.  [If the obsolete remove_symlinks_after_‐
                        build field is set, defaults to the value of that field, with a warning.]

                        If this field is false, the development directory will be populated by
                        the develop begin (aedb) command, and the integration directory will be
                        populated by the integrate begin (aeib) command.

                derived_at_start_only = boolean;
                        This field controls whether the above fields controlling the appearance
                        of derived files are acted upon before every build (false) or only when
                        the work area is created (true).

                        Defaults to false if not set.

                        This field is ignored if the during_build_only field is true.

                This field can be complex.  Here are a few examples; but much, much more is
                possible.  The first example will get you a development directory very similar to
                one presented by CVS:
                        development_directory_style =
                        {
                            source_file_copy = true;
                        };
                Note that this is hugely space inefficient, and can be quite slow.  The second
                example will get you a development directory very similar to one presented by Tom
                Lord's arch:
                        development_directory_style =
                        {
                            source_file_link = true;
                            source_file_symlink = true;
                            source_file_copy = true;
                        };
                Ideally, however, you should use the $search_path substitution of the
                build_command field.  This is because the view path scales better than any other
                method.  On the other hand, you need a DMT with an excellent view path
                implementation (and GNU make doesn't).

        integration_directory_style = { ... };
                This field encapsulates a set of parameters controlling the appearance of the
                integration directory.  It has significant implications for the way the DMT is
                used, and the directory appearance presented to the DMT.

                Defaults to the value of the development_directory_style field if not set.  Note
                that the obsolete create_symlinks_before_integration_build and remove_symlinks_‐
                after_integration_build fields affect this default (with a warning) but only if
                they are explicitly set.

                Note that the link_integration_directory field is still relevant.  That field
                controls how the baseline is cloned to form the integration directory.  This
                field operates after that operation.

        build_time_adjust_notify_command = string;
                This command is run when Aegis adjusts the last-time-modified time-stamp on files
                in the integration directory.  If the build tool uses additional information to
                supplement file modification times, this command gives you the opportunity to re-
                sync the associated database.

                Executed as: the project owner.

                Current directory: the integration directory.  This is what is about to be come
                the new baseline.

                Exit status: NOT ignored. Note that a failure here puts the change in a partial
                state from which recovery may be difficult. Best to define this command with a
                set+e so that errors are ignored at the command level.

        build_covers_all_architectures = boolean;
                This field is set to true if the build command, when executed on any
                architecture, results in all architectures being built.  This may be
                accomplished, for example, by using cross-compilation techniques, or Cook's
                ability to nominate hosts on which to execute each build rule.

        test_covers_all_architectures = boolean;
                This field is set to true if the test command, when executed on any architecture,
                results in all architectures being tested.  This may be accomplished, for
                example, by using Cook's ability to nominate hosts on which to execute each test
                rule.

        symlink_exceptions = [ string ];
                This field is used to list filename patterns for which symbolic links must not be
                made between the development directory and the baseline.  These are usually state
                files for various tools.  The patterns are matched against the whole filename;
                naming only the last filename path element will not work (unless the pattern
                starts with “*”).

        change_file_command = string;
                This field contains a command to be executed whenever a ´aegis -CoPy_file´,
                ´aegis -New_File´ ´aegis -New_Test´ ´aegis -MoVe_file´ or ´aegis -ReMove_file´
                command is successful.  See also command-specific overrides.  If this field is
                absent, nothing is done.  Used by the aecp(1), aenv(1), aenf(1), aerm(1), and
                aemv(1) commands.  All of the substitutions described by aesub(5) are available;
                in addition,

                ${File_List}
                        Space separated list of files named.

                Executed as: the developer.  Current directory: the development directory of the
                change.  Exit status: ignored.

        change_file_undo_command = string;
                This field contains a command to be executed whenever a ´aegis -CoPy_file_Undo',
                ´aegis -MoVe_file_Undo' ´aegis -New_File_Undo', ´aegis -New_Test_Undo', or ´aegis
                -ReMove_file_Undo' command is successful.  Default to change_file_command if
                absent.  See also command-specific overrides.  If both fields are absent, nothing
                is done.  Used by the aecpu(1), aemvu(1), aenfu(1), aentu(1) or aermu(1),
                commands.  All of the substitutions described by aesub(5) are available; in
                addition,

                ${File_List}
                        Space separated list of files named.

                Executed as: the developer.  Current directory: the development directory of the
                change.  Exit status: ignored.

        new_file_command = string;
                Executed whenever the aegis -new_file command is run successfully.  Defaults to
                `change_file_command' if not set.

                All of the substitutions described in aesub(5) are available.  In addition:

                ${File_List}
                        Space separated list of files named (at times, can be empty).

                Executed as: the developer.  Current directory: the development directory of the
                change.  Exit status: ignored.

        new_test_command = string;
                Executed whenever the aegis -new_test command is run successfully.  Defaults to
                `change_file_command' if not set.

                All of the substitutions described in aesub(5) are available.  In addition:

                ${File_List}
                        Space separated list of files named (at times, can be empty).

                Executed as: the developer.  Current directory: the development directory of the
                change.  Exit status: ignored.

        copy_file_command = string;
                Executed whenever the aegis -copy_file command is run successfully.  Defaults to
                `change_file_command' if not set.

                All of the substitutions described in aesub(5) are available.  In addition:

                ${File_List}
                        Space separated list of files named (at times, can be empty).

                Executed as: the developer.  Current directory: the development directory of the
                change.  Exit status: ignored.

        remove_file_command = string;
                Executed whenever the aegis -remove_file command is run successfully.  Defaults
                to `change_file_command' if not set.

                All of the substitutions described in aesub(5) are available.  In addition:

                ${File_List}
                        Space separated list of files named (at times, can be empty).

                Executed as: the developer.  Current directory: the development directory of the
                change.  Exit status: ignored.

        new_file_undo_command = string;
                Executed whenever the aegis -new_file_undo command is run successfully.  Defaults
                to change_file_undo_command if not set.

                All of the substitutions described in aesub(5) are available.  In addition:

                ${File_List}
                        Space separated list of files named (at times, can be empty).

                Executed as: the developer.  Current directory: the development directory of the
                change.  Exit status: ignored.

        new_test_undo_command = string;
                Executed whenever the aegis -new_test_undo command is run successfully.  Defaults
                to change_file_undo_command if not set.

                All of the substitutions described in aesub(5) are available.  In addition:

                ${File_List}
                        Space separated list of files named (at times, can be empty).

                Executed as: the developer Current directory: the development directory of the
                change Exit status: ignored

        copy_file_undo_command = string;
                Executed whenever the aegis -copy_file_undo command is run successfully.
                Defaults to change_file_undo_command if not set.

                All of the substitutions described in aesub(5) are available.  In addition:

                ${File_List}
                        Space separated list of files named (at times, can be empty).

                Executed as: the developer Current directory: the development directory of the
                change Exit status: ignored

        remove_file_undo_command = string;
                Executed whenever the aegis -remove_file_undo command is run successfully.
                Defaults to change_file_undo_command if not set.

                All of the substitutions described in aesub(5) are available.  In addition:

                ${File_List}
                        Space separated list of files named (at times, can be empty).

                Executed as: the developer Current directory: the development directory of the
                change Exit status: ignored

        make_transparent_command = string;
                The make_transparent_command is executed whenever the aegis -make_transparent
                command is run successfully.  Defaults to change_file_command if not set.

                All of the substitutions described in aesub(5) are available.  In addition:

                ${File_List}
                        Space separated list of files named (at times, can be empty).

                Executed as: the developer Current directory: the development directory of the
                change Exit status: ignored

        make_transparent_undo_command = string;
                The make_transparent_undo_command is executed whenever the aegis
                -make_transparent_undo command is run successfully.  Defaults to
                change_file_undo_command if not set.

                All of the substitutions described in aesub(5) are available.  In addition:

                ${File_List}
                        Space separated list of files named (at times, can be empty).

                Executed as: the developer Current directory: the development directory of the
                change Exit status: ignored

        project_file_command = string;
                This field contains a command to be executed during a development build before
                the development build command above, when (a) it is the first build after a
                develop begin, or (b) some other change has been integrated into the baseline
                since the last build.  If this field is absent, nothing is done.  Used by the
                aeb(1) command.  All of the substitutions described by aesub(5) are available.

        develop_begin_command = string;
                This field contains a command to be executed whenever a 'aegis -Develop_Begin'
                command is successful.  If this field is absent, nothing is done.  Used by the
                aedb(1) command.  All of the substitutions described by aesub(5) are available.

                Executed as: the developer.  Current directory: the development directory of the
                change.  Exit status: ignored.

        develop_begin_undo_command = string;
                This field contains a command to be executed whenever a 'aegis
                -Develop_Begin_Undo' command is successful.  If this field is absent, nothing is
                done.  Used by the aedbu(1) command.  All of the substitutions described by
                aesub(5) are available.

                Executed as: the developer.  Current directory: wherever the command was executed
                from.  Exit status: ignored.

        integrate_begin_command = string;
                This field contains a command to be executed whenever a 'aegis -Integrate_Begin'
                command is successful.  If this field is absent, nothing is done.  Used by the
                aeib(1) command.  All of the substitutions described by aesub(5) are available.

                Executed as: the project owner.  Current directory: the integration directory.
                Exit status: ignored.

        link_integration_directory = boolean;
                This flag is true if Aegis should link the files from the baseline into the
                integration directory, rather than copy them (the default).  This has risks, as
                the build script (e.g.  Howto.cook or Makefile, etc) must unlink targets before
                rebuilding them; if this is not done the baseline will be corrupted.  Used by the
                aeib(1) command.

        integrate_begin_exceptions = [ string ];
                This field may be used to specify a list of file names (and file name patterns)
                which are to be omitted from the copy (link) of the baseline when creating the
                integration directory.  Used by the aeib(1) command.  This field only applies to
                derived files, it does not apply to source files.  The patterns are matched
                against the whole filename; naming only the last filename path element will not
                work (unless the pattern starts with “*”).

        history_create_command = string;
                This field is used to create a new history.  The command is always executed as
                the project owner.  Used by the aeipass(1) command.

                It is strongly recommended that the history_create_command and history_put_‐
                command fields are identical.  If not set, the history_create_command field
                defaults to the same value as the history_put_command field.

                All of the substitutions described by aesub(5) are available; in addition,

                ${Input}
                        Absolute path of the source file.

                ${History}
                        Absolute path of the history file.  This may need to be reworked with the
                        Dirname and Basename substitutions to yield a string suitable for the
                        history tool in question.

                ${File_Name}
                        The base relative file name of the file for this check-in.  Note that the
                        file name can vary over the lifetime of the file as it is renamed, but
                        the history file name (above) never varies.  Do not use this as the name
                        of the history file.  (Optional)

                ${UUID} The universally unique identifier of the source file.  This is invariant
                        for the lifetime of the file.  Do not use use this as the name of the
                        history file.  (Optional)

                See also the history_put_trashes_file field, below.

                Executed as: the project owner.  Current directory: the base of the history tree.
                Exit status: zero indicates success, all non-zero exits indicate failure (the
                integrate pass will fail).

        history_get_command = string;
                This field is used to get a file from history.  The command may be executed by
                developers.  Used by the aeipass(1) and aecp(1) commands.  All of the
                substitutions described by aesub(5) are available; in addition,

                ${History}
                        The absolute path of the history file.  This may need to be reworked with
                        the Dirname and Basename substitutions to yield a string suitable for the
                        history tool in question.

                ${Edit}
                        The edit number to be extracted.  It may be an arbitrary string, varying
                        on the particular history tool.

                ${Output}
                        The absolute path of the destination file.

                Executed as: the developer (or the executing user, in the case of the
                -independent option).  Current directory: the base of the history tree Exit
                status: zero indicates success, all non-zero exits indicate failure (the aecp
                will fail).

        history_put_command = string;
                This field is used to add a new change to the history.  The command is always
                executed as the project owner.  Used by the aeipass(1) command.

                It is strongly recommended that the history_put_command and history_create__
                command fields are identical.  If not set, the history_put_command field defaults
                to the same value as the history_create_command field.

                All of the substitutions described by aesub(5) are available; in addition,

                ${Input}
                        The absolute path of the source file.

                ${History}
                        The absolute path of the history file.  This may need to be reworked with
                        the Dirname and Basename substitutions to yield a string suitable for the
                        history tool in question.

                ${File_Name}
                        The base relative file name of the file for this check-in.  Note that the
                        file name can vary over the lifetime of the file as it is renamed, but
                        the history file name (above) never varies.  Do not use this as the name
                        of the history file.  (Optional)

                ${UUID} The universally unique identifier of the source file.  This is invariant
                        for the lifetime of the file.  Do not use use this as the name of the
                        history file.  (Optional)

                See also the history_put_trashes_file field, below.

                Executed as: the project owner.  Current directory: the base of the history tree.
                Exit status: zero indicates success, all non-zero exits indicate failure (the
                integrate pass will fail).

        history_transaction_begin_command = string;
                The history_transaction_begin_command field is used to specify a command to be
                run by aeipass(1) before any history create or history put commands are run.  The
                default is to do nothing.

                All of the substitutions described in aesub(5) are available.  If you need a
                transaction ID, use the $version substitution.

                Executed as: the project owner.  Current directory: the base of the history tree.
                Exit status: zero indicates success, all non-zero exits indicate failure (the
                integrate pass will fail).

        history_transaction_end_command = string;
                The history_transaction_end_command field is used to specify a command to be run
                by aeipass(1) after any history create or history put commands are run, but
                before any history query commands are run.  The default is to do nothing.

                All of the substitutions described in aesub(5) are available.  If you need a
                transaction ID, use the $version substitution.

                Executed as: the project owner.  Current directory: the base of the history tree.
                Exit status: zero indicates success, all non-zero exits indicate failure (the
                integrate pass will fail).

        history_transaction_abort_command = string;
                The history_transaction_abort_command field is used to specify a command to be
                run by aeipass(1) to indicate that a transaction has been abandoned.  The default
                is to do nothing.

                All of the substitutions described in aesub(5) are available.  If you need a
                transaction ID, use the $version substitution.

                Executed as: the project owner.  Current directory: the base of the history tree.
                Exit status: ignored (the integrate pass has already failed).

        history_query_command = string;
                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.
                Used by the aeipass(1) and aecp(1) commands.  All of the substitutions described
                by aesub(5) are available; in addition,

                ${History}
                        The absolute path of the history file.  This may need to be reworked with
                        the Dirname and Basename substitutions to yield a string suitable for the
                        history tool in question.

                Executed as: the project owner.  Current directory: the base of the history tree.
                Exit status: zero indicates success, all non-zero exits indicate failure (the
                integrate pass will fail).

        history_label_command = string;
                This field contains a command to be executed whenever a aeipass(1) or aedn(1)
                command is successful.  This command is invoked for every file in the project.
                So using it incurs a performance penalty.  If this field is absent, nothing is
                done.  All of the substitutions described by aesub(5) are available; in addition,

                ${History}
                        The absolute path of the history file.

                ${Edit}
                        The edit number to be labeled.  It may be an arbitrary string, varying on
                        the particular history tool.

                ${Label}
                        The label to  be attached to the history.  When executed from aeipass(1)
                        this value is the same as ${Version}, which may need to be reworked with
                        the ${Subst} substitutions to yield a string suitable for the history
                        tool in question.  When executed from aedn(1) it is set to the value
                        passed in from the command line.

                Executed as: the project owner.  Current directory: the base of the history tree.
                Exit status: zero indicates success, all non-zero exits indicate failure (a
                warning will be issued).

                Labeling does not scale, so the use of this command is not encouraged.  If you
                have a project with 10,000 files, and a change modified exactly one of them, only
                one history_put_command execution is required, which operates on one history
                file.  If you have labeling turned on, it will also be necessary to execute
                10,000 history_label_commands, to add information Aegis will never use.

        history_put_trashes_file = (fatal, warn, ignore);
                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 - i.e. the
                history tool has compromised the referential integrity of the repository.

                fatal
                    Emit a fatal error if one or more source files are modified by a
                    history_put_command or history_create_command.  This is the default.

                warn
                    Emit a warning if a source file is modified.

                ignore
                    Ignore a source file changing.  You sure better hope it was only in a
                    comment!

        history_content_limitation = (ascii_text, international_text, binary_capable);
                This field describes the content style which the history tool is capable of
                working with.

                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.

                international_text
                        The history tool can only cope with files which do not contain the NUL
                        character.  The file must end with a newline.

                binary_capable
                        The history tool can cope with all files without any limitation on the
                        form of the contents.

                When a file is added to the history (by either the history_create_command or the
                history_put_command field) it is examined for conformance to this limitation.  If
                there is a problem, the file is encoded in either quoted printable for MIME64,
                whichever is smaller, before being given to the history tool.  This encoding is
                transparent, the file in the baseline is unchanged.

                On extract (the history_get_command 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).

                Please note that this field does not apply to the diff_command or merge_command
                fields.

        diff_command = string;
                This field is used to difference of 2 files.  The command is always executed by
                developers.  Used by the aed(1) command.  All of the substitutions described by
                aesub(5) are available; in addition,

                ${ORiginal}
                        The absolute path of the original file copied into the change.  Usually
                        in the baseline, but not always.

                ${Input}
                        The absolute path of the file in the development directory.

                ${Output}
                        The absolute path of the file in which to write the difference listing.

                Executed as: the project owner (for integration diffs), or the developer (for
                development diffs).  Current directory: the integration directory (for
                integration diffs), or the development directory (for development diffs).  Exit
                status: zero indicates success, all non-zero exits indicate failure (the aed will
                fail).

                Note: It is possible to configure a project to omit the diff step as unnecessary,
                by the following setting:
                        diff_command = "exit 0";
                This disables all generation, checking and validation of difference file for each
                change source file.  The merge functions of the aediff(1) command are unaffected
                by this setting.

        merge_command = string;
                This field is used to merge two competing edits to a file.  The command is always
                executed by developers.  The current directory will be the development directory.
                This field is used by the aed(1) command.  All of the substitutions described by
                aesub(5) are available; in addition,

                ${ORiginal}
                        The absolute path of the original file copied into the change.  Usually
                        not in the baseline, often a temporary file.

                ${Most_Recent}
                        The absolute path of the competing edit, usually in the baseline.

                ${Input}
                        The absolute path of the file in the development directory.  This is the
                        “preferred” edit, if the tool has this concept when highlighting
                        conflicting edits.

                ${Output}
                        The absolute path of the file in which to write the merged result.  This
                        will usually be the name if a change source file in the development
                        directory.

                It is important that this command does not move files around.  (See the obsolete
                diff3_command field, below, for some history.)

                Executed as: the project owner (for integration diffs), or the developer (for
                development diffs).  Current directory: the integration directory (for
                integration diffs), or the development directory (for development diffs).  Exit
                status: zero indicates success, all non-zero exits indicate failure (the aed will
                fail).

        patch_diff_command = string;
                The difference of 2 files, to send around as a patch.  (This isn't the same as
                diff_command, because it's aimed at GNU Patch, not at humans.)  The command is
                always executed by developers.  Used by the aepatch(1) command.

                Defaults to "set +e; diff -c -L $index -L $index $original $input > $output; test
                $? -le 1" if not set.

                All of the substitutions described by aesub(5) are available; in addition,

                ${ORiginal}
                        The absolute path of the original file copied into the change.  Usually
                        in the baseline, but not always.

                ${Input}
                        The absolute path of the file in the development directory.

                ${Output}
                        The absolute path of the file in which to write the difference listing.

                ${INDex}
                        The project-relative name of the file, for use when the file name is
                        embedded in the output.  (Optional.)

                Executed as: the project owner (for integration diffs), or the developer (for
                development diffs).  Current directory: the integration directory (for
                integration diffs), or the development directory (for development diffs).  Exit
                status: zero indicates success, all non-zero exits indicate failure (the aed will
                fail).

        annotate_diff_command = string;
                The difference of 2 files, for the use of the aeannotate(1) command.  (This isn't
                the same as the diff_command field, because it's aimed at aeannotate(1), not at
                humans.)  The command is always executed by developers.  Used by the
                aeannotate(1) command.

                Extreme care should be taken if you are considering setting this field, otherwise
                the result reported by aeannotate(1) may bear little relation to reality.  The
                most useful option is GNU diff's --ignore-all-space option, which will have the
                effect of ignoring the majority of indenting and code formatting changes.  The
                --ignore-case option could also be useful for case insensitive languages such as
                FORTRAN or PL/1.  Avoid options which would alter the number of lines, such as -
                -ignore-blank-lines or --context as these will produce misleading results.

                Defaults to "set +e; diff $option $original $input > $output; test $? -le 1" if
                not set.

                All of the substitutions described by aesub(5) are available; in addition,

                ${ORiginal}
                        The absolute path of the original file copied into the change.  Usually
                        in the baseline, but not always.

                ${Input}
                        The absolute path of the file in the development directory.

                ${Output}
                        The absolute path of the file in which to write the difference listing.

                ${INDex}
                        The project-relative name of the file, for use when the file name is
                        embedded in the output.  (Optional.)

                ${OPTion}
                        Extra options to be passed to the diff command, as set by the
                        aeannotate(1) -diff-option command line option.  Use with extreme care.

                Executed as: the project owner (for integration diffs), or the developer (for
                development diffs).  Current directory: the integration directory (for
                integration diffs), or the development directory (for development diffs).  Exit
                status: zero indicates success, all non-zero exits indicate failure (the aed will
                fail).

        review_policy_command = string;
                This field is used to set the command to be executed by the aerpass(1) command.
                This command is useful in cases where the enterprise has determined that more
                than one review is necessary or that the reviewer must be senior to the
                developer, etc.  Defaults to "exit 0" if not set.

                The exit status is examined.  An zero exit status (success) means that the change
                will proceed to the awaiting integration state; a non-zero exit status (failure)
                means that the change requires further review state, and the develop_end_action
                is consulted to determine the appropriate state (awaiting_review or being_‐
                reviewed) for the change to move to.

                All of the substitutions described by aesub(5) are available.  Of particular
                interest are ${Change_Developer_List} and ${Change_Reviewer_List} for passing the
                specific staff involved with the change.

                Executed as: the current reviewer.  Current directory: the development directory.
                Exit status: zero indicates success, non-zero indicates failure.

                For example, to have a script which is a project source file to be used to gate
                the code review process, a setting such as the following may be used:
                        review_policy_command =
                            "$sh ${source script/reviewpolicy.sh} "
                            "-p $project -c $change "
                            "-d ${developer_list} "
                            "-r ${reviewer_list}"
                            ;
                This is only one of many ways to implement a project specific review policy.

        develop_end_policy_command = string;
                This field is used to set the command to be executed by the aede(1) command.
                This command is useful in cases where the enterprise has determined that
                additional pre-conditions must be met (in addition to those already imposed by
                the aede(1) command) before a change may leave the being developed state.
                Defaults to "exit 0" if not set.

                The exit status is examined.  An zero exit status (success) means that the change
                may leave to the being developed state; a non-zero exit status (failure) means
                that the change requires further development.

                All of the substitutions described by aesub(5) are available.

                Executed as: the developer.  Current directory: the development directory.  Exit
                status: zero indicates success, non-zero indicates failure.

                There are some common validations available in the aede-policy(1) command; you
                may choose all or only some of them, or you may choose to write a policy command
                specific to your project.

        unchanged_file_develop_end_policy = (...);
                This field may be used to control what happens when development of a change is
                ended, and the change contains files which have not had their contents or their
                attributes changed.

                ignore  Does not look for or warn about unchanged files.  This the default.

                warning If the change sets contains unchanged files, a warning will be issued for
                        each one.

                error   If the change set contains unchanged files, an error will be issued for
                        each one, and develop end will not complete (the change will remain in
                        the being developed state).

        unchanged_file_integrate_pass_policy = (...);
                This field may be used to control what happens when a change is completed, and
                the change contains files which have not had their contents or their attributes
                changed.

                ignore  Does not look for or warn about unchanged files.  The file version will
                        be added to the history.  This the default.

                warning If the change sets contains unchanged files, a warning will be issued for
                        each one.  The file version will be added to the history.

                remove  If the change set contains an unchanged file, it will be silently removed
                        from the change set.  The file version will not be added to the history.
                        The project file is unaffected.

        test_command = string;
                This field is used to set the command to be executed by the aet(1) command.
                Defaults to "$shell $file_name" if not set.

                All of the substitutions described in aesub(5) are available.  In addition:

                ${File_Name}
                        The absolute path of the test to be executed.

                ${Search_Path}
                        Colon separated list of directories to search for tests and test support
                        files.  (This is a normal aesub(5) substitution.)

                ${Search_Path_Executable}
                        Colon separated list of directories to search for executable files and
                        executable support files.  Usually it is the same as the above, except
                        during an “aet -bl” command.

                ${VARiables}
                        The text of name=value variable settings from the command line, suitably
                        quoted to protect special character from the shell.  Will be appended to
                        the end of the command if not used explicitly.

                Note that tests are source files, and thus never have the execute bit set.

                Executed as: the project owner (for integration tests) or the developer (for
                development tests), or the executing user (for -independent tests).  Current
                directory: the integration directory (for integration tests), the development
                directory (for development tests), the project baseline (for -bl tests), or the
                current directory (for -independent tests).  Exit status: zero indicates success,
                one indicates failure, anything else indicates "no result".

        development_test_command = string;
                This field is used to set the command to be executed by the aet(1) command when a
                change is in the being developed state.  Defaults to be the same as the
                test_command field if not set.

                Note: It is a significantly bad idea to make tests behave differently in being
                development and being integrated states; avoid this at all costs.

                All of the substitutions described in aesub(5) are available.  In addition:

                ${File_Name}
                        The absolute path of the test to be executed.

                ${File_Name}
                        The absolute path of the test to be executed.

                ${Search_Path}
                        Colon separated list of directories to search for tests and test support
                        files.  (This is a normal aesub(5) substitution.)

                ${Search_Path_Executable}
                        Colon separated list of directories to search for executable files and
                        executable support files.  Usually it is the same as the above, except
                        during an “aet -bl” command.

                ${VARiables}
                        The text of name=value variable settings from the command line, suitably
                        quoted to protect special character from the shell.  Will be appended to
                        the end of the command if not used explicitly.

                Note that tests are source files, and thus never have the execute bit set.

                Executed as: the developer.  Current directory: the development directory (for
                development tests), the project baseline (for -bl tests).  Exit status: zero
                indicates success, one indicates failure, anything else indicates "no result".

        batch_test_command = string;
                This field is used to set the command to be executed by the aet(1) command, in
                preference to the test_command or development_test_command, if set.  It is
                capable of running more than one test at once.

                All of the substitutions described in aesub(5) are available.  In addition:

                ${Output}
                        This is the name of the file to be generated to hold the test results.
                        See aetest(5) for the format of this file.
                        A space separated list of absolute paths of the tests to be executed.

                ${File_Names}
                        The absolute path of the tests to be executed.

                ${File_Name}
                        The absolute path of the test to be executed.

                ${Search_Path}
                        Colon separated list of directories to search for tests and test support
                        files.  (This is a normal aesub(5) substitution.)

                ${Search_Path_Executable}
                        Colon separated list of directories to search for executable files and
                        executable support files.  Usually it is the same as the above, except
                        during an “aet -bl” command.

                ${Current}
                        Number of first test in the batch.

                ${Total}
                        Total number of tests. If this is 0 then no progress messages should be
                        issued.

                ${VARiables}
                        The text of name=value variable settings from the command line, suitably
                        quoted to protect special character from the shell.  Will be appended to
                        the end of the command if not used explicitly.

                Note that tests are source files, and thus never have the execute bit set.

                It is strongly recommended that you design your test scripts so that they may be
                executed by either batch or non-batch methods.  This permits simple migration
                when your environment changes.

                Executed as: the project owner (for integration tests) or the developer (for
                development tests), or the executing user (for -independent tests).  Current
                directory: the integration directory (for integration tests), the development
                directory (for development tests), the project baseline (for -bl tests), or the
                current directory (for -independent tests).  Exit status: zero indicates success,
                one indicates failure, anything else indicates "no result".

        architecture_discriminator_command = string;
                If this field is present it is used as a command to be executed in order to
                further identify the platform architecture (see below).  All of the substitutions
                described by aesub(5) are available;
                Executed as: the developer.  Current directory: the development directory of the
                change.  Exit status: zero indicates success, all non-zero exits indicate
                failure.

        architecture = [{ ... }];
                This field is a list of system and machine architectures on which each change
                must successfully build and test.  May be assigned more than once.  The
                structures listed have fields as follows:

                name = string;
                        The name of the architecture.  This name is available in the
                        ${ARCHitecture} substitution (see aesub(5) for more information), as well
                        as being used internally by Aegis.  You may use almost any name for your
                        architecture, but it is best to avoid shell special characters and white
                        space, because it may be substituted into commands to be executed by
                        Aegis.

                pattern = string;
                        The system and machine architecture are determined by using the uname(2)
                        system call.  The uname(2) return value is assembled into a string of the
                        form "sysname-release-version-machine", or "sysname-release-version-
                        machine-disc" if architecture_discriminator_command is used.

                        The pattern field must match this uname result string.  The first match
                        found is used.  The pattern is a shell file name pattern, see sh(1) for
                        more information.

                        For example, the pattern SunOS-4.1*-*-sun4* matches a machine the author
                        commonly uses, which returns SunOS-4.1.3-8-sun4m from the uname(2) system
                        call.

                mode = (required, optional, forbidden);
                        The mode field is used to control how the architecture information is
                        used.

                        required
                                Architectures of thus mode will be copied into changes as their
                                required architectures when the change is created.  This is the
                                default.

                        optional
                                Architectures of thus mode will not be copied into changes as
                                their required architectures when the change is created.
                                However, if you add them subsequently, they become required for
                                that change.

                        forbidden
                                Aegis will refuse to build or test on architectures of this mode.

                        When a change is created, the required architecture names are copied into
                        the change's architecture list.  Once names are in this list, they are
                        required for the change, and the project attributes are less relevant.

                If the architecture field is not set, it defaults to
                        architecture =
                        [
                                {
                                        name = "unspecified";
                                        pattern = "*";
                                        mode = required;
                                }
                        ];

        file_template = [ { ... } ];
                The file template is consulted whenever a new file is created, by one of the
                aenf(1) or aent(1) commands.  May be assigned more than once.  Each list item has
                the form:

                pattern = [ string ];
                        The name of the file, relative to the development directory.  Each string
                        is a shell file name pattern; see sh(1) for more information.  The
                        patterns are matched against the whole filename; naming only the last
                        filename path element will not work (unless the pattern starts with “*”).

                body_command = string;
                        Command to run to initialize the body of the file.
                        Executed as: the developer.  Current directory: the development directory
                        of the change.  Exit status: ignored.

                body = string;
                        What to initialize the body of the file to.

                All of the substitutions described in aesub(5) are available for the body and
                body_command strings.  (Only specify one of them.)  In addition:

                ${File_Name}
                        will be replaced by the name of the new file.

        whiteout_template = [ { ... } ];
                The file template is consulted whenever a file is removed, by one of the aerm(1)
                or aemv(1) commands.  It is used to place a “whiteout” entry in the development
                directory, in order to induce compile errors of the removed file is referenced
                during the build.  Each list item has the form:

                pattern = [ string ];
                        The name of the file, relative to the development directory.  Each string
                        is a shell file name pattern; see sh(1) for more information.  The
                        patterns are matched against the whole filename; naming only the last
                        filename path element will not work (unless the pattern starts with “*”).

                body = string;
                        What to initialize the body of the file to.  If not present, no whiteout
                        file will be created; if the empty string, a zero-length whiteout file
                        will be created.

                All of the substitutions described in aesub(5) are available for the body string.
                In addition:

                ${File_Name}
                        will be replaced by the name of the removed file.

                If the name of the file being removed does not match any of the filename
                patterns, a file consisting of 1KB of very ugly garbage will be generated.  The
                idea is that it will produce a syntax error for most languages if you try to run
                it, compile it, or include it.

        maximum_filename_length = integer;
                This field is used to limit the length of file names.  All new files may not have
                path components longer than this.  Existing files are not affected.  The last
                component must also allow for the ",D" suffix of difference files.  Where this
                value is larger than the file system allows, the file system limit will be
                imposed.  Defaults to 255 if not set.  Legal values range from 9 to 255.

                The file name lengths of project files will be checked at develop end if the
                project aegis.conf file is in the change.  See aede (1) for more information.

        posix_filename_charset = boolean;
                This field may be used to limit the characters allowed in file names to only
                those explicitly allowed by POSIX.  Defaults to false if not set.

                For a filename to be portable across conforming implementations of IEEE Std
                1003.1-1988, it shall consist only of alphanumeric characters, dot, hyphen or
                underscore.  Hyphen shall not be used as the first character of a portable
                filename.

                If this field is false, all characters are allowed except non-printing
                characters, space characters and leading hyphens.

        dos_filename_required = boolean;
                This field may be used to limit file names so that they conform to the DOS 8+3
                filename limits and to the DOS filename character set.  Also denies file names
                which look like devices (AUX, etc).  Defaults to false if not set.  This field is
                used in combination with the other filename fields, it does not replace them.

        windows_filename_required = boolean;
                This field may be used to limit file names so that they conform to the Windows98
                and WindowsNT filename limits and character set.  Also denies file names which
                look like devices (AUX, etc).  Defaults to false if not set.  This field is used
                in combination with the other filename fields, it does not replace them.

        shell_safe_filenames = boolean;
                This field may be used to limit file names so that they may not contain shell
                special characters.  If you do not set this to true, you will need to use the
                ${quote} substitution around file names in commands, or risk unexpected errors.

                This field defaults to true if not set.

                The white space characters (space, tab, newline, etc) are considered shell
                special characters.

        allow_white_space_in_filenames = boolean;
                This field may be used to allow white space characters in file names.  This will
                allow the following characters to appear in filenames: backspace (BS, \b, 0x08),
                horizontal tab (HT, \t, 0x09), new line (NL, \n, 0x0A), vertical tab (VT, \v,
                0x0B), form feed (FF, \f, 0x0C), and carriage return (CR, \r, 0x0D).

                Defaults to false if not set.

                Note that this field does not override other file name filters.  It will be
                necessary to explicitly set shell_safe_filenames = false as well.  It will be
                necessary to set dos_filename_required = false (the default) as well.  It will be
                necessary to set posix_filename_charset = false (the default) as well.

                The user must take great care to use the ${quote} substitution around all file
                names in commands in the project configuration.  And even then, substitutions
                which expect a space separated list of file names will have undefined results.

        allow_non_ascii_filenames = boolean;
                This field may be used to allow file names with non-ascii-printable characters in
                them.  Usually this would mean a UTF8 or international charset of some kind.

                Defaults to false if not set.

                Note that this field does not override other file name filters.  It will be
                necessary to explicitly set shell_safe_filenames = false as well.  It will be
                necessary to set dos_filename_required = false (the default) as well.  It will be
                necessary to set posix_filename_charset = false (the default) as well.

        filename_pattern_accept = [ string ];
                This field is used to specify a list of patterns of acceptable file names.  The
                patterns are matched against each filename path element.  The patterns are
                constructed from the usual shell filename wild-cards.  Defaults to "*" if not
                set.

        filename_pattern_reject = [ string ];
                This field is used to specify a list of patterns of unacceptable file names.  The
                patterns are matched against each filename path element.  The patterns are
                constructed from the usual shell filename wild-cards.  Defaults to "*,D" if not
                set.  The pattern "*,D" is always appended.  Where the filename_pattern_accept
                and filename_pattern_reject fields conflict, the reject takes precedence.

        new_test_filename = string;
                This field is used to form the filename of new tests, where the filename is not
                specified on the aent command line.  Defaults to "test/${zpad $hundred 2}/t${zpad
                $number 4}${left $type 1}.sh" if not set.

                All of the substitutions defined in aesub(5) are available.  The following three
                substitutions are also available:

                $Hundred
                        The test number divided by 100, optional

                $Number The test number, mandatory

                $Type   The test type: "automatic" or "manual", optional

        development_directory_template = string;
                This field is used to determine the name of the development directory at develop
                begin.  All of the substitutions defined in aesub(5) are available.  The
                following substitutions is also available:

                Default_Development_Directory
                        The directory within which the development directory is to be created.

                Magic   A single letter, starting from “C”, which can be inserted.  This must be
                        used, as it allows Aegis to try different names should there be a
                        conflict.

                If not set, defaults to "$ddd/${left $p ${expr ${namemax $ddd} - ${length
                .$magic$c}}}.$magic$c".

                For DOS compatibility (8+3 file names), a useful setting is "$ddd/${downcase
                ${left ${id $p} 8}.$magic${right 0$c 2}}".  This ensures that the filename is
                always a valid 8.3 filename, that it is always lowercase, and it translates any
                punctuation in the project name into underscores.

        metrics_filename_pattern = string;
                This field is used to form the name of the metrics file, given a source file.
                All of the substitutions defined in aesub(5) are available.  The following
                substitutions is also available:

                File_Name
                        The absolute path name of the source file.

                Defaults to "$filename,S" if not set.

        trojan_horse_suspect = [ string ];
                This list of filename patterns is consulted by aedist --receive when it is
                checking for files which could be used to host Trojan horse attacks.  This will
                be different for different projects, so you will need to update this yourself.
                The patterns are matched against the whole filename; naming only the last
                filename path element will not work (unless the pattern starts with “*”).

        project_specific = [ { ... } ];
                This is a list of name and value pairs for use within the ${project-specific}
                substitution (see aesub(5) for more information).  May be assigned more than
                once.  The sub-fields are

                name = string;
                        The name of the value.  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 to be substituted.

                There are almost no limitations on the strings which may appear in either of
                these fields.

                There are several attribute names which are known to and used by Aegis, these
                include:

                aede-policy
                        This attribute is used when no policy names are listed on the aede-
                        policy(1) command line.

                aetar:exclude
                        This attribute is used by he aetar(1) receive command to exclude files in
                        tarballs from consideration.  This is a space separated list of file
                        names.

                html:meta
                        This attribute is used by the aeget(1) command to customize generated web
                        pages.  See aeget(1) for more information.

                html:body-begin
                        This attribute is used by the aeget(1) command to customize generated web
                        pages.  See aeget(1) for more information.

                html:body-end
                        This attribute is used by the aeget(1) command to customize generated web
                        pages.  See aeget(1) for more information.

                copyright-owner
                        This string is available via the ${copyright-owner} substitution, and is
                        the one checked by the aede-policy(1) command.  Only set this attribute
                        if your project is a work-for-hire under copyright law.  It defaults to
                        the value of ${user name} if not set, this is almost always correct for
                        Open Source projects.

                When commands are executed by Aegis, it ensures that the AEGIS_PROJECT,
                AEGIS_CHANGE, AEGIS_ARCH, LINES and COLS environment variables are set
                appropriately.  The project configuration file's project_specific field is also
                consulted, looking for value's whose name starts with "setenv:" and sets the
                corresponding environment variable.  All of the substitutions described by
                aesub(5) are available.  For example: specifying a PATH and a SEARCH_PATH to be
                used for all commands may be set as follows:
                        project_specific =
                        [
                          {
                            name = "setenv:PATH";
                            value = "/usr/bin:/bin";
                          },
                          {
                            name = "setenv:SEARCH_PATH";
                            value = "${search_path}";
                          },
                        ];
                As many environment variables as desired may be specified in this way.

        build_time_adjust = (...);
                This field controls the adjustment of file modification times at the end of
                integrate-pass.  File times are adjusted so that development directories are, in
                the main, out of date with respect to the baseline.  The idea is that, at the
                very least, programs need to be re-linked so that aet -reg does not give false
                negatives.

                Combining this with the project_file_command (above) can alleviate the vast
                majority of file modification time inconsistencies experienced as a result of a
                project integration and the subsequent changes in the baseline's file
                modification times.

                Unless you are a masochist, do not set this field.  Leave it as the default.

                adjust_and_sleep
                        Causes the file times to be adjusted, and if the file times would extend
                        into the future, aeipass will sleep until that time has passed.  This is
                        the default.

                adjust_only
                        Causes the file times to be adjusted.  If the file time extend into the
                        future, a warning is issued.

                dont_adjust
                        File modification times are not adjusted.  This is a really bad idea.
                        Really.  Make sure that, at the very minimum, project_file_command
                        touches all of the change's files, otherwise the build problems which
                        ensue are going to take you weeks to track down and lose you much
                        productivity.  You have been warned.

                See also the build_time_adjust_notify_command field.

        signed_off_by = boolean;
                If this field is set each aedb(1), aechown(1), aede(1) and aerpass(1) will append
                a Signed-off-by line to the change description.  This field should only be set to
                true for open source projects.

                For a description of Signed-off-by see
                http://www.ussg.iu.edu/hypermail/linux/kernel/0405.2/1301.html and
                http://www.osdl.org/newsroom/press_releases/2004/2004_05_24_dco.html

        cache_project_file_list_for_each_delta = boolean;
                It is possible to have Aegis cache the list of project files that were present at
                integrate pass for each delta (integrated change set).  This is used to optimize
                all project-history-based operations, such as aecp -delta or aepatch(1).

                This cache will optimize many operations which would otherwise require time to
                reconstruct the project state using the roll-forward data available in each
                change set.  However, it comes at the cost of disk space, and not everyone can
                afford more and more disk.

                This field defaults to true if not set.

        clean_exceptions = [ string ];
                It is possible to have Aegis exclude from the clean process any file that match
                one of the pattern listed in the clean_exceptions list.

                This field default to an empty list if not set.

        cache_project_file_list_for_each_delta = boolean;
                It is possible to have Aegis cache the list of project files that were present at
                integrate pass for each delta (integrated change set).  This is used to optimize
                all project-history-based operations, such as aecp -delta or aepatch(1).

                This cache will optimize many operations which would otherwise require time to
                reconstruct the project state using the roll-forward data available in each
                change set.  However, it comes at the cost of disk space, and not everyone can
                afford more and more disk.

                This field defaults to true if not set.

RSS FEEDS

        Aegis has the ability to feed RSS channels when change sets transition states.  See the
        User Guide for full details.  Following is a brief description of the project-specific
        attributes used to control this process.

        Create / Add to a channel
                An RSS channel is specified with the rss:feedfilename project_specific attribute:

                project_specific =
                        [
                          {
                            name = "rss:feedfilename-<filename>";
                            value = "<space-separated list of states>";
                          }
                        ]

        Specify the Description of an RSS channel
                The description of an RSS channel is specified with the rss:feeddescription
                project_specific attribute:

                project_specific =
                        [
                          {
                            name = "rss:feeddescription-<filename>";
                            value = "<description>";
                          }
                        ]

        Specify the Title of an RSS channel
                The title of an RSS channel is specified with the rss:feedtitle project_specific
                attribute:

                project_specific =
                        [
                          {
                            name = "rss:feedtitle-<filename>";
                            value = "<title>";
                          }
                        ]

        Specify the Language of an RSS channel
                The language of an RSS channel is specified with the rss:feedlanguage
                project_specific attribute:

                project_specific =
                        [
                          {
                            name = "rss:feedlanguage-<filename>";
                            value = "<language";
                          }
                        ]

OBSOLETE FIELDS

        There are some obsolete fields in the file.  They are provided for backwards
        compatibility only, and should not be used.

        diff3_command = string;
                This field is used to difference 3 files.  The command is always executed by
                developers.  Used by the aed(1) command.  All of the substitutions described by
                aesub(5) are available; in addition,

                ${ORiginal}
                        The absolute path of the original file copied into the change.  Usually
                        not in the baseline.

                ${Most_Recent}
                        The absolute path of the competing edit, usually in the baseline.

                ${Input}
                        The absolute path of the file in the development directory.

                ${Output}
                        The absolute path of the file in which to write the difference listing.

                Executed as: the project owner (for integration diffs), or the developer (for
                development diffs).  Current directory: the integration directory (for
                integration diffs), or the development directory (for development diffs).  Exit
                status: zero indicates success, all non-zero exits indicate failure (the aed will
                fail).

                The problem with this field was that the default usage placed the merged source
                in a strange place.  And subsequent aed(1) commands would over-write it.  This
                meant that merges would be lost, causing a number of nasty problems.  Some sites
                overcame this by adding “mv” commands to put the output back where the input came
                from, but this meant that Aegis' commentary was misleading.  Use the
                “merge_command” field instead.  It is almost identical, but Aegis will move the
                files around for you - so you get the good behavior by default (no lost merges)
                and the error message is consistent.

        create_symlinks_before_build = boolean;
                This flag is true if Aegis should create symlinks from the development directory
                to the baseline for all files in the baseline not in the development directory
                immediately before a development_build_command is issued.  Usually used to trick
                dumb DMTs into believing the development directory contains an entire copy of the
                project, though sometimes the DMT is smart enough, the tools it must work with
                are not.  Symlinks in the development directory which point to nonexistent files
                will be removed.

                Defaults to false if not set.

        create_symlinks_before_integration_build = boolean;
                This flag is true if Aegis should create symlinks from the integration directory
                to the ancestral baseline for all files in the ancestral not in the integration
                directory immediately before a build_command is issued.  Usually used to trick
                dumb DMTs into believing the integration directory contains an entire copy of the
                project, though sometimes the DMT is smart enough, the tools it must work with
                are not.  Symlinks in the integration directory which point to nonexistent files
                will be removed.

                Defaults to the same value as create_symlinks_before_build if not set.

        remove_symlinks_after_build = boolean;
                This flag is true if Aegis should remove symlinks which point from the
                development directory to the baseline directory immediately after a development_‐
                build_command is issued.  Only consulted if the create_symlinks_before_build
                field is true, for the purpose of reversing the actions of the create_symlinks_‐
                before_build field.

                Defaults to false if not set.

        remove_symlinks_after_integration_build = boolean;
                This flag is true if Aegis should remove symlinks which point from the
                integration directory to the ancestral baseline directory immediately after a
                build_command is issued.  Only consulted if the create_symlinks_before_‐
                integration_build field is true, for the purpose of reversing the actions of the
                create_symlinks_before_integration_build field.

                Defaults to true if not set.  This default is intentional.  It is important that
                there are no symlinks in the (new) baseline, because they could go stale between
                integrations.  If you set this field to false, caveat emptor.

SEE ALSO

        aeb(1)  build a change

        aecp(1) copy a file into a change

        aecpu(1)
                reverse action of aecp

        aed(1)  find differences between a change and the baseline

        aede(1) end development of a change aede-policy(1) check things about a change

        aerpass(1)
                pass a review of a change

        aeib(1) begin integration of a change

        aeipass(1)
                pass integration of a change

        aemv(1) rename a file as part of a change

        aenf(1) add new files to be created by a change

        aenfu(1)
                remove new files from a change

        aent(1) add a new test to be created by a change

        aentu(1)
                remove new tests from a change

        aet(1)  run tests

        aegis(5)
                aegis file format syntax

        aesub(5)
                available command substitutions

        aetest(5)
                batch test results file

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/