Provided by: aegis_4.24.3-3_amd64 bug

NAME

        aeimport - import foreign repository into Aegis

SYNOPSIS

        aeimport [ option...  ] dirname
        aeimport -Help
        aeimport -VERSion

DESCRIPTION

        The aeimport command is used to create a new project, and populate it by importing a
        foreign repository (such as RCS or CVS) without loss of project history.

        Please note: unless you specify a version (see the -version option, below) this command
        will default to creating branches to support version 1.0.  If you discovered this too
        late, all is not lost: you can use the aenbru(1) command to get rid of the branches you
        didn't want.

   Directory
        The project directory, under which the project baseline and history and state and change
        data are kept, will be created at this time.  If the -DIRectory option is not given, the
        project directory will be created in the directory specified by the default_project_‐
        directory field of aeuconf(5), or if not set in current user's home directory; in either
        case with the same name as the project.

   Staff
        The project is created with the current user and group as the owning user and group.  The
        current user is an administrator for the project.  The project has no other
        administrators (use aena(1) to add more).

        The project will have all user names found in the history files (see blow) installed as
        developers, reviewers and integrators.  This is probably too broad, but fairly accurately
        reproduces the wide-open permissions found in most repositories, and you will want to use
        aerd(1), aerrv(1) and aeri(1) as appropriate to winnow this list.

        If only one name is found, the project will be set to “developers_may_review = true;”
        otherwise it will be false (see aepattr(5) for more information).  Use aepa(1) to change
        this if you want a different setting.

        The project's umask is derived from the current user's umask, but modified to guarantee
        that group members will have access and that only the project owner will have write
        access.  In general, it's best of the project is not owned by an account with any other
        role, as this prevents a whole class of “oops, I thought I was somewhere else” errors.

        The project's history commands (see aepconf(5) for more information) are set to those
        suitable for RCS.  The build command is set to “exit 0”; you need to set it to something
        suitable.  The symbolic link farm is turned on.

   Pointer
        The project pointer will be added to the first element of the search path, or  if no path
        is set.  If this is inappropriate, use the -LIBrary option to explicitly set the desired
        location.  See the -LIBrary option for more information.

        Alternatively, unset the AEGIS_PATH environment variable to add the project to the global
        project list.

   Version
        You may specify the project version in two ways:

        1. The version number may be implicit in the project name, in which case the version
           numbers will be stripped off.  For example, “aeimport -p example.1.2” will create a
           project called “example” with branch number 1 created, and sub-branch 2 of branch 1
           created.

        2. The version number may be stated explicitly, in which case it will be subdivided for
           branch numbers.  For example, “aeimport -p example -version 1.2” will create a project
           called “example” with branch number 1 created, and sub-branch 2 of branch 1 created.

        In each case, these branches may be named wherever a project name may be given, such as
        “-p example.1” and “-p example-1.2”.  The actual punctuation character is unimportant.

        You may have any depth of version numbers you like.  Both methods of specifying version
        numbers may be used, and they will be combined.  If you want no version numbers at all,
        use -version with a single dash as the argument, as in “-version -”

        If no version number is given, either explicitly or implicitly, version 1.0 is used.

   Project Directory Location
        Please Note: Aegis also consults the underlying file system, to determine its notion of
        maximum file size.  Where the file system's maximum file size is less than
        maximum_filename_length, the filesystem wins.  This can happen, for example, when you are
        using the Linux UMSDOS file system, or when you have an NFS mounted an ancient V7
        filesystem.  Setting maximum_filename_length to 255 in these cases does not alter the
        fact that the underlying file systems limits are far smaller (12 and 14, respectively).

        If your development directories (or your whole project) is on filesystems with filename
        limitations, or a portion of the heterogeneous builds take place in such an environment,
        it helps to tell Aegis what they are (using the project config file's fields) so that you
        don't run into the situation where the project builds on the more permissive
        environments, but fails with mysterious errors in the more limited environments.

        If your development directories are routinely on a Linux UMSDOS filesystem, you would
        probably be better off setting dos_filename_required = true, and also changing the
        development_directory_template field.  Heterogeneous development with various Windows
        environments may also require this.

THE PROCESS

        Most file version systems do not operate using change sets.  In order to import such
        repositories into Aegis it is necessary to “discover” these change sets.  The following
        steps are taken:

        1.
          The directory (dirpath) given on the command line, and all directories below it, are
          scanned for appropriate files (for example, RCS and CVS use files with a “,v” suffix).
          These files are read to obtain the file's history.
          If you have been using a non-standard file suffix, aeimport won't be able to find the
          files.
          If you have more than one module in your CVS repository, aeimport doesn't (yet)
          understand the CVSROOT/modules file.  Pointing aeimport at your whole CVSROOT may
          produce an unexpectedly large result.

        2.
          The history files discovered in the previous step are copied into the location used by
          Aegis.  Unlike some other tools, Aegis has a repository per project, rather than all
          projects sharing the same repository.
          This also means that Aegis will not modify the original history files.  In particular,
          if the import produces unexpected results, simply remove the project (see aermpr(1) for
          more information) and start again.
          It is not possible to leave all your history files under, say, $CVSROOT and have Aegis
          point to them.

        3.
          For each user mentioned in the various file histories, the time stamps are examined to
          find groups of files which were committed at around the same time.  Files changed
          within 1 minute of each other are considered a group.
          Files change within one minute, but by different users, are not considered a group.
          This does not usually present a problem as developers mostly work alone.  In rare cases
          where developers work together, only one of them does the commit.
          In some cases the time window may be too large, and several very small changes may be
          seen as one larger change set.  In practice, this isn't very common.

        4.
          Groups of files are stored into the Aegis database as completed changes (i.e. as if
          aeipass(1) has already run).  The description of the change is the concatenation of all
          the unique comments found attached to the relevant file versions.  The time stamp used
          for the change is the latest time stamp of any file in the group.
          There are times when small typographical errors between file comments result in longer-
          than-expected change descriptions.  This can be corrected with aeca(1) or tkaeca(1) if
          desired.  There are also times when the reverse is true: some files have no comments at
          all, and the resulting description is less than useful.

        5.
          Tags are turned into delta names by transferring delta names from the files they are
          attached to, to the change sets they are attached to.  When a tag would appear to be
          attached to more than one change, it is attached only to the latest change.
          In common usage, the tags serve a similar purpose as Aegis' delta numbers.  They are
          all (typically) applied in a single CVS command, in order that a particular release may
          be recreated later.  However, because each file will be at a different version, and
          each will have had its latest version included in various random change sets.
          Tags are used for other things too.  The method given here is simply a guess, but it's
          one which works reasonably well.

        Once aeimport has completed importing a project, you will be able to examine the results
        using the ael project_history and ael change_details commands.  (See ael(1) for more
        information.)

   Limitations
        The aeimport program is far from perfect.  There are a number of known limitations.

        · At this time, there is no support for branching.  (As soon as I figure out how to
          discern the root of a branch across loosely coupled files, I'll implement it.  Ideas
          and/or code contributions welcome.)

        · Only RCS and SCCS formats are understood at present.  It should be straight forward to
          add support for additional formats in the future.  Only step 1 of the above process
          requires attention, the rest is file format neutral.

        · There is no support for CVS modules, and there needs to be.

        · You can't specify the time window size used to determine change sets.  Time will tell
          whether this is necessary, but it begs the question: how will you know what window size
          you need in order to use the option at all.

        · You can't import a CVS repository into an existing project.  You may only create a new
          project from a CVS repository.

        · You can't import a remote CVS repository.

OPTIONS

        The following options are understood:

        -DIRectory path
                This option may be used to specify which directory is to be used.  It is an error
                if the current user does not have appropriate permissions to create the directory
                path given.  This must be an absolute path.

                Caution: If you are using an automounter do not use `pwd` to make an absolute
                path, it usually gives the wrong answer.

        -FORmat name
                This option may be use to specify which history format is being imported.  The
                following formats are understood:

                RCS     Release Control System format has been around for quite a while.  It is
                        the format underlying CVS (Concurrent Version System).  This is the
                        default if no format name is specified.
                        Note: you must have RCS installed before you run aeimport if you use this
                        format, because RCS commands will be run during the import process.  The
                        import will fail if RCS is not installed.  You can find a freeware
                        implementation at ftp.gnu.org, or a local mirror.

                SCCS    Source Code Control System is one of the earliest Unix version systems.
                        (I'm told this is the format underlying BitKeeper.)
                        Note: you must have SCCS installed before you run aeimport if you use
                        this format, because SCCS commands will be run during the import process.
                        The import will fail if SCCS is not installed.  The GNU Compatibly Stupid
                        Source Control (CSSC) is a freeware implementation of SCCS, and it may be
                        found at ftp://alpha.gnu.org/gnu/CSSC/

        -LIBrary abspath
                This option may be used to specify a directory to be searched for global state
                files and user state files.  (See aegstate(5) and aeustate(5) for more
                information.)  Several library options may be present on the command line, and
                are search in the order given.  Appended to this explicit search path are the
                directories specified by the AEGIS_PATH environment variable (colon separated),
                and finally, /usr/local/lib/aegis is always searched.  All paths specified,
                either on the command line or in the AEGIS_PATH environment variable, must be
                absolute.

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

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

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

        -VERSion number
                This option may be used to specify the version number for the project.  Version
                numbers are implemented as branches.  Use a single dash (“-”) as the argument if
                you want no version branches created.

        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 aeimport are long,
        this means ignoring the extra leading '-'.  The "--option=value" convention is also
        understood.

EXIT STATUS

        The aeimport command will exit with a status of 1 on any error.  The aeimport 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.

COPYRIGHT

        aeimport 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 aeimport program comes with ABSOLUTELY NO WARRANTY; for details use the 'aeimport
        -VERSion License' command.  This is free software and you are welcome to redistribute it
        under certain conditions; for details use the 'aeimport -VERSion License' command.

AUTHOR

        Peter Miller   E-Mail:   millerp@canb.auug.org.au
        /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/