Man Linux: Main Page and Category List

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/