Provided by: aegis_4.24.3-3_i386 bug

NAME

        aegis integrate begin - begin integrating a change

SYNOPSIS

        aegis -Integrate_Begin change-number [ option...  ]
        aegis -Integrate_Begin -List [ option...  ]
        aegis -Integrate_Begin -Help

DESCRIPTION

        The aegis -Integrate_Begin command is used to begin the integration of
        a change into the baseline of a project.

        The change will advance from the awaiting integration state to the
        being integrated state.  boxwid = 1 down S4: box "awaiting"
        "integration" arrow " integrate" ljust " begin" ljust S5: box "being"
        "integrated" T4: spline -> from S5.w then left 0.5 then up 1 then to
        S4.w " integrate" ljust " begin" ljust " undo" ljust at T4.c - (0.5,0)

        A (logical) copy of the baseline is created in an integration
        directory and the the files of the change are added to the integration
        directory.  The time stamps of files copied from the baseline are
        preserved, time stamps on the files copied from the development
        directory are all set to the time of the beginning of the integration.
        The 'aegis -Change_Directory' command may be used to locate the
        integration directory.  The change will be assigned to the current
        user.

        Please note that only regular files and symbolic links are copied
        (linked) from the baseline to the integration directory.  This has
        some implications:

        o Special files (devices, named pipes, etc) will not be reproduced in
          the integration directory; you will need to create these as part of
          the build.

        o If the case of the -minimum option (see below), only primary source
          files are copied (linked) across.  Derived files (including symbolic
          links) are expected to be created as part of the build.

        o If the case of the -minimum option, directories are only created
          when required to hold a file which satisfies the above criteria.  If
          you need special empty directories, or directories which contain
          only special files, or only contain derived files, you need to
          create them as part of the build.

        The link_integration_directory field of the project configuration file
        (see aepconf(5) for more information) controls whether the copy of the
        baseline is done by copying the files or by creating hard links to the
        files.  The hard links are just one of the constraints on the location
        of the integration directory.  The integrate begin will abort with an
        error if this copy operation fails, e.g. by running out of disk space.
        If this should happen, the change will remain in the awaiting
        integration state, and the integration directory will be removed.

        The change will be assigned a delta number.  Delta numbers are
        incremented once for each aegis -Integrate_Begin command for the
        project.  If an integration is subsequently aborted with either the
        aegis -Integrate_Begin_Undo or aegis -Integrate_FAIL command, the
        delta number will not be re-used.

        It is not possible to choose the integration directory, as there are
        many constraints upon it, including the fact that it must be on the
        same device as the baseline directory, and that many UNIX
        implementations don't allow renaming directories up and down the
        trees.  The integration directory will be in the project directory,
        and named for the delta number.

   Notification
        On successful completion of this command, the integration_begin_-
        command field of the project config file is run, if set.  See
        aepconf(5) for more information.

Minimum Integrations

        Aegis provides a minimum integration capability which may be used for
        various reasons.  The term minimum may be a bit counter intuitive.
        One might think it means to the minimum amount of work, however it
        actually means use a minimum of files from the baseline in populating
        the delta directory.  This normally leads to actually building
        everything in the project from sources and, as such, might be
        considered the most robust of builds.

        Note that any change which removes a file, whether by aerm, aemv or
        aemt, results in an implicit minimum integration.  This is intended to
        ensure nothing in the project references the removed file.

        A project may adopt a policy that a product release should be based on
        a minimum integration.  Such a policy may be a reflection of local
        confidence, or lack thereof, in the project's DMT (Dependency
        Maintenance Tool) or build system.  Or it may be based on a validation
        process wishing to make a simple statement on how the released package
        was produced.

        Another, more transient, reason a to require a minimum integration
        might be when upgrading a third party library, compiler or maybe even
        OS level.  Any of these events would signal the need for a minimum
        integration to ensure everything is rebuilt using the new resources.

        The cost of a minimum integration varies according to type and size of
        the project.  For very large projects, especially those building large
        numbers of binaries, the cost can be large.  However large projects
        also require significant time to fully populate the delta directory.
        A minimum integration only copies those files under Aegis control,
        skipping all "produced" files.  In the case where a file upon which
        everything depends is changed, everything will be built anyway so the
        copy of the already built files is a waste of time.  This means that
        sometimes a minimum can be as cheap as a normal integration.

   Change Set Attributes
        The follwoing user-defined change set attributes are understood:

        integrate-begin-hint
                If this is set to "minimum" or "maximum", it is as if these
                options appeared on the command line.  Only consulted if
                neither -minimum nor -maximum appear on the command line.

        All other user defined change set attributes are ignored.

OPTIONS

        The following options are understood:

        -Change number
                This option may be used to specify a particular change within
                a project.  See aegis(1) for a complete description of this
                option.

        -Help
                This option may be used to obtain more information about how
                to use the aegis program.

        -List
                This option may be used to obtain a list of suitable subjects
                for this command.  The list may be more general than expected.

        -MAXimum
                This option may be used to cause all files to be copied into
                the integration directory.  This is the default, unless the
                change requires the deletion of a file.

        -MINImum
                This option may be used to cause only the source files to be
                copied into the integration directory.  The default is to copy
                all files, unless the change requires the deletion of a file.

        -Project name
                This option may be used to select the project of interest.
                When no -Project option is specified, the AEGIS_PROJECT
                environment variable is consulted.  If that does not exist,
                the user's $HOME/.aegisrc file is examined for a default
                project field (see aeuconf(5) for more information).  If that
                does not exist, when the user is only working on changes
                within a single project, the project name defaults to that
                project.  Otherwise, it is an error.

        -REAson text
                This option may be used to attach a comment to the change
                history generated by this command.  You will need to use
                quotes to insulate the spaces from the shell.

        -TERse
                This option may be used to cause listings to produce the bare
                minimum of information.  It is usually useful for shell
                scripts.

        -Verbose
                This option may be used to cause aegis to produce more output.
                By default aegis only produces output on errors.  When used
                with the -List option this option causes column headings to be
                added.

        -Wait   This option may be used to require Aegis commands to wait for
                access locks, if they cannot be obtained immediately.
                Defaults to the user's lock_wait_preference if not specified,
                see aeuconf(5) for more information.

        -No_Wait
                This option may be used to require Aegis commands to emit a
                fatal error if access locks cannot be obtained immediately.
                Defaults to the user's lock_wait_preference if not specified,
                see aeuconf(5) for more information.

        See also aegis(1) for options common to all aegis commands.

        All options may be abbreviated; the abbreviation is documented as the
        upper case letters, all lower case letters and underscores (_) are
        optional.  You must use consecutive sequences of optional letters.

        All options are case insensitive, you may type them in upper case or
        lower case or a combination of both, case is not important.

        For example: the arguments "-project, "-PROJ" and "-p" are all
        interpreted to mean the -Project option.  The argument "-prj" will not
        be understood, because consecutive optional characters were not
        supplied.

        Options and other command line arguments may be mixed arbitrarily on
        the command line, after the function selectors.

        The GNU long option names are understood.  Since all option names for
        aegis are long, this means ignoring the extra leading '-'.  The
        "--option=value" convention is also understood.

RECOMMENDED ALIAS

        The recommended alias for this command is
        csh%    alias aeib 'aegis -ib \!* -v'
        sh$     aeib(){aegis -ib "$@" -v}

ERRORS

        It is an error if the change is not in the awaiting integration state.
        It is an error if the current user is not an integrator of the
        project.
        It is an error if there is an integration in progress for the project.
        It is an error if the current user developed the change and the
        project is configured to disallow developers to integrate their own
        changes (default).
        It is an error if the current user reviewed the change and the project
        is configured to disallow reviewers to integrate their such changes
        (default).

EXIT STATUS

        The aegis command will exit with a status of 1 on any error.  The
        aegis command will only exit with a status of 0 if there are no
        errors.

ENVIRONMENT VARIABLES

        See aegis(1) for a list of environment variables which may affect this
        command.  See aepconf(5) for the project configuration file's
        project_specific field for how to set environment variables for all
        commands executed by Aegis.

SEE ALSO

        aeb(1)  build a change

        aecd(1) change directory

        aeibu(1)
                reverse the aeib command

        aeifail(1)
                fail integration of a change

        aeintegratq(1)
                Automate the integration queue.

        aeipass(1)
                pass integration of a change

        aeni(1) add new integrators to a project

        aerpass(1)
                pass review of a change

        aet(1)  run tests

        aeuconf(5)
                user configuration file format

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/