'\" t
.\" aegis - project change supervisor
.\" Copyright (C) 2001, 2002, 2005-2008 Peter Miller
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see
.\" .
.\"
.\"
.\" aegis - project change supervisor
.\" Copyright (C) 1991-1993, 1997, 2006-2008 Peter Miller
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see
.\" .
.\"
.ds n) aegis
.ds N) Aegis
.if n .nr )M 8n
.if n .nr IN 8n
.if n .nr )I 8n
.if n .po 0
.hy 0
.if n .ad l
.de r)
.if !'\\*(R)'no' \{\
.PP
See also
.IR \*(n) (1)
for options common to all \*(n) commands.
.\}
..
.de eB
.RS
.nf
.ft CW
.ta 8n 16n 24n 32n
..
.de eE
.ft P
.fi
.RE
..
.ds n) aeimport
.TH "\*(n)" 1 \*(N) "Reference Manual" ""
.SH NAME
aeimport \- import foreign repository into Aegis
.XX "aeimport(1)" "import foreign repository into Aegis"
.SH SYNOPSIS
.B \*(n)
[
.IR option \&...
]
.IR dirname
.br
.B \*(n)
.B -Help
.br
.B \*(n)
.B -VERSion
.SH DESCRIPTION
The
.I "\*(n)"
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.
.PP
Please note: unless you specify a version (see the \fB\-version\fP 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
\fIaenbru\fP(1) command to get rid of the branches you didn't want.
.SS 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
\fB\-DIRectory\fP option is not given, the project directory will be
created in the directory specified by the default_\%project_\%directory
field of \fIaeuconf\fP(5), or if not set in current user's home directory;
in either case with the same name as the project.
.SS 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 \fIaena\fP(1) to add more).
.PP
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 \fIaerd\fP(1),
\fIaerrv\fP(1) and \fIaeri\fP(1) as appropriate to winnow this list.
.PP
If only one name is found, the project will be set to
\[lq]\f[CW]developers_may_review = true;\fP\[rq] otherwise it will be false
(see \fIaepattr\fP(5) for more information). Use \fIaepa\fP(1) to change
this if you want a different setting.
.PP
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 \fInot\fP owned by an account with any other role, as this
prevents a whole class of \[lq]oops, I thought I was somewhere else\[rq] errors.
.PP
The project's history commands (see \fIaepconf\fP(5) for more information)
are set to those suitable for RCS. The build command is set to \[lq]exit
0\[rq]; you need to set it to something suitable. The symbolic link farm
is turned on.
.SS Pointer
The project pointer will be added to the first element of the search
path, or \fI\*(S)\fP if no path is set. If this is inappropriate,
use the \fB\-LIBrary\fP option to explicitly set the desired location.
See the \fB\-LIBrary\fP option for more information.
.PP
Alternatively, unset the AEGIS_PATH environment variable to add the
project to the global project list.
.SS Version
You may specify the project version in two ways:
.TP 3n
1.
The version number may be implicit in the project name, in which
case the version numbers will be stripped off. For example, \[lq]\*(n)
-p example.1.2\[rq] will create a project called \[lq]example\[rq] with branch
number 1 created, and sub-branch 2 of branch 1 created.
.TP 3n
2.
The version number may be stated explicitly, in which case it will be
subdivided for branch numbers. For example, \[lq]\*(n) -p example -version
1.2\[rq] will create a project called \[lq]example\[rq] with branch number 1
created, and sub-branch 2 of branch 1 created.
.PP
In each case, these branches may be named wherever a project name may
be given, such as \[lq]-p example.1\[rq] and \[lq]-p example-1.2\[rq].
The actual
punctuation character is unimportant.
.PP
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 \fB\-version\fP with a single
dash as the argument, as in \[lq]\f(CW\-version \-\fP\[rq]
.PP
If no version number is given, either explicitly or implicitly, version
1.0 is used.
.SS Project Directory Location
.\"
.\" aegis - project change supervisor
.\" Copyright (C) 1998, 1999, 2006-2008 Peter Miller
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see
.\" .
.\"
\fBPlease Note:\fP 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 \fImaximum_filename_length\fP, 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 \fImaximum_filename_length\fP to 255 in these
cases does not alter the fact that the underlying file systems limits
are far smaller (12 and 14, respectively).
.PP
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 \fIconfig\fP 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.
.PP
If your development directories are routinely on a Linux
UMSDOS filesystem, you would probably be better off setting
\fIdos_filename_required = true\fP,
and also changing the \fIdevelopment_directory_template\fP field.
Heterogeneous development with various Windows environments may
also require this.
.SH THE PROCESS
Most file version systems do not operate using change sets. In order
to import such repositories into \*(N) it is necessary to \[lq]discover\[rq]
these change sets. The following steps are taken:
.TP 2n
1.
The directory (\fIdirpath\fP) given on the command line, and all
directories below it, are scanned for appropriate files (for example,
RCS and CVS use files with a \[lq]\f[CW],v\fP\[rq] suffix).
These files are read to obtain the file's history.
.sp 0.3
If you have been using a non-standard file suffix, \*(n) won't be able
to find the files.
.sp 0.3
If you have more than one module in your CVS repository, \*(n) doesn't
(yet) understand the CVSROOT/modules file. Pointing \*(n) at your whole
CVSROOT may produce an unexpectedly large result.
.TP 2n
2.
The history files discovered in the previous step are copied into the
location used by \*(N). Unlike some other tools, \*(N) has a repository
per project, rather than all projects sharing the same repository.
.sp 0.3
This also means that \*(N) will not modify the original history files.
In particular, if the import produces unexpected results, simply remove
the project (see \fIaermpr\fP(1) for more information) and start again.
.sp 0.3
It is not possible to leave all your history files under, say,
$CVSROOT and have Aegis point to them.
.TP 2n
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.
.sp 0.3
Files change within one minute, but by different users, are \fInot\fP
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.
.sp 0.3
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.
.TP 2n
4.
Groups of files are stored into the \*(N) database as completed changes
(i.e. as if \fIaeipass\fP(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.
.sp 0.3
There are times when small typographical errors between file comments
result in longer-than-expected change descriptions. This can be
corrected with \fIaeca\fP(1) or \fItkaeca\fP(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.
.TP 2n
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.
.sp 0.3
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.
.sp 0.3
Tags are used for other things too. The method given here is simply a
guess, but it's one which works reasonably well.
.PP
Once \*(n) has completed importing a project, you will be able to
examine the results using the \fIael project_history\fP and \fIael
change_details\fP commands.
(See \fIael\fP(1) for more information.)
.SS Limitations
The \*(n) program is far from perfect. There are a number of known
limitations.
.TP 2n
\(bu
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.)
.TP 2n
\(bu
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.
.TP 2n
\(bu
There is no support for CVS modules, and there needs to be.
.TP 2n
\(bu
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.
.TP 2n
\(bu
You can't import a CVS repository into an existing project.
You may only create a new project from a CVS repository.
.TP 2n
\(bu
You can't import a remote CVS repository.
.SH OPTIONS
The following options are understood:
.\"
.\" aegis - project change supervisor
.\" Copyright (C) 1991-1993, 2006-2008 Peter Miller.
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see
.\" .
.\"
.TP 8n
\fB-DIRectory\fP \fIpath\fP
.RS 8n
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.
.PP
Caution:
If you are using an automounter
do not use `pwd` to make an absolute path,
it usually gives the wrong answer.
.RE
.TP 8n
\fB\-FORmat\fP \fIname\fP
.RS
This option may be use to specify which history format is being imported.
The following formats are understood:
.TP 8n
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.
.br
\fBNote:\fP you \fImust\fP have RCS installed before you run \fI\*(n)\fP
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 \f[CW]ftp.gnu.org\fP, or a local mirror.
.TP 8n
SCCS
Source Code Control System is one of the earliest Unix version systems.
(I'm told this is the format underlying BitKeeper.)
.br
\fBNote:\fP you \fImust\fP have SCCS installed before you run \fI\*(n)\fP
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
\f[CW]ftp://alpha.gnu.org/gnu/CSSC/\fP
.RE
.\"
.\" aegis - project change supervisor
.\" Copyright (C) 1992, 1993, 2006-2008 Peter Miller.
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see
.\" .
.\"
.TP 8n
\fB-LIBrary\fP \fIabspath\fP
.br
This option may be used to
specify a directory to be searched for global state files and
user state files.
(See
.IR aegstate (5)
and
.IR 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
.I AEGIS_PATH
environment variable (colon separated),
and finally,
.I /usr/local/lib/aegis
is always searched.
All paths specified,
either on the command line or in the
.I AEGIS_PATH
environment variable,
must be absolute.
.\"
.\" aegis - project change supervisor
.\" Copyright (C) 1991-1993, 2006-2008 Peter Miller.
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see
.\" .
.\"
.TP 8n
.B -List
.br
This option may be used to obtain a list of suitable subjects for this
command.
The list may be more general than expected.
.\"
.\" aegis - project change supervisor
.\" Copyright (C) 1991-1993, 2006-2008 Peter Miller.
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see
.\" .
.\"
.TP 8n
\fB-Project\fP \fIname\fP
This option may be used to select the project of interest.
When no
.B -Project
option is specified,
the
.I AEGIS_PROJECT
environment variable is consulted.
If that does not exist,
the user's
.I $HOME/.aegisrc
file is examined for a default project field (see
.IR 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.
.\"
.\" aegis - project change supervisor
.\" Copyright (C) 1991-1993, 2006-2008 Peter Miller.
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see
.\" .
.\"
.TP 8n
.B -Help
.br
This option may be used to obtain more information about how to use the
.I \*(n)
program.
.TP 8n
\fB-VERSion\fP \fInumber\fP
This option may be used to specify the version number
for the project.
Version numbers are implemented as branches.
Use a single dash (\[lq]\f(CW\-\fP\[rq]) as the argument
if you want no version branches created.
.\"
.\" aegis - project change supervisor
.\" Copyright (C) 1991-1993, 2006-2008 Peter Miller.
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see
.\" .
.\"
.r)
.PP
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.
.PP
All options are case insensitive,
you may type them in upper case or lower case or a combination of both,
case is not important.
.PP
For example:
the arguments "-project, "-PROJ" and "-p" are
all interpreted to mean the \fB-Project\fP option.
The argument "-prj" will not be understood,
because consecutive optional characters were not supplied.
.PP
Options and other command line arguments may be
mixed arbitrarily on the command line,
after the function selectors.
.br
.ne 4
.PP
The GNU long option names are understood.
Since all option names for
.I \*(n)
are long,
this means ignoring the extra leading '-'.
The "\fB--\fIoption\fB=\fIvalue\fR" convention is also understood.
.\"
.\" aegis - project change supervisor
.\" Copyright (C) 1991-1993, 1995, 1997, 2004, 2006-2008 Peter Miller
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see
.\" .
.\"
.SH EXIT STATUS
The
.I \*(n)
command will exit with a status of 1 on any error.
The
.I \*(n)
command will only exit with a status of 0 if there are no errors.
.SH ENVIRONMENT VARIABLES
See \fIaegis\fP(1) for a list of environment variables which may affect
this command.
See \fIaepconf\fP(5) for the project configuration file's
\fIproject_\%specific\fP field for how to set environment variables for
all commands executed by Aegis.
.\"
.\" aegis - project change supervisor
.\" Copyright (C) 1991-1995, 1997, 2006-2008 Peter Miller
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see
.\" .
.\"
.br
.ne 2i
.SH COPYRIGHT
.ds v) 4.24.3
.ds V) 4.24.3.D001
.ds o) 0
.ds p) 4.25
.ds u) 4.24
.ds Y) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
\*(n) version \*(V)
.br
.if t .ds C) \(co
.if n .ds C) (C)
Copyright \*(C) \*(Y) Peter Miller
.PP
The \*(n) program comes with ABSOLUTELY NO WARRANTY;
for details use the '\fI\*(n) -VERSion License\fP' command.
This is free software
and you are welcome to redistribute it under certain conditions;
for details use the '\fI\*(n) -VERSion License\fP' command.
.br
.ne 1i
.SH AUTHOR
.TS
tab(;);
l r l.
Peter Miller;E-Mail:;millerp@canb.auug.org.au
\f(CW/\e/\e*\fR;WWW:;http://www.canb.auug.org.au/~millerp/
.TE