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¶