aeimport(1) aeimport(1) NNAAMMEE aeimport - import foreign repository into Aegis SSYYNNOOPPSSIISS aaeeiimmppoorrtt [ _o_p_t_i_o_n... ] _d_i_r_n_a_m_e aaeeiimmppoorrtt --HHeellpp aaeeiimmppoorrtt --VVEERRSSiioonn DDEESSCCRRIIPPTTIIOONN The _a_e_i_m_p_o_r_t 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 --vveerrssiioonn option, below) this command will default to creating branches to support ver- sion 1.0. If you discovered this too late, all is not lost: you can use the _a_e_n_b_r_u(1) command to get rid of the branches you didn't want. DDiirreeccttoorryy 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 --DDIIRReeccttoorryy option is not given, the project directory will be cre- ated in the directory specified by the default_project_directory field of _a_e_u_c_o_n_f(5), or if not set in current user's home directory; in either case with the same name as the project. SSttaaffff 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 _a_e_n_a(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 _a_e_r_d(1), _a_e_r_r_v(1) and _a_e_r_i(1) as appropriate to winnow this list. If only one name is found, the project will be set to "develop- ers_may_review = true;" otherwise it will be false (see _a_e_p_a_t_t_r(5) for more information). Use _a_e_p_a(1) to change this if you want a different setting. The project's umask is derived from the current user's umask, but mod- ified 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 _n_o_t 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 _a_e_p_c_o_n_f(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. PPooiinntteerr 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 --LLIIBBrraarryy option to explicitly set the desired location. See the --LLIIBBrraarryy option for more information. Alternatively, unset the AEGIS_PATH environment variable to add the project to the global project list. VVeerrssiioonn 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, "aeim- port -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 exam- ple -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 --vveerrssiioonn with a single dash as the argument, as in "-version -" If no version number is given, either explicitly or implicitly, ver- sion 1.0 is used. PPrroojjeecctt DDiirreeccttoorryy LLooccaattiioonn PPlleeaassee NNoottee:: Aegis also consults the underlying file system, to deter- mine its notion of maximum file size. Where the file system's maximum file size is less than _m_a_x_i_m_u_m___f_i_l_e_n_a_m_e___l_e_n_g_t_h, 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 _m_a_x_i_m_u_m___f_i_l_e_n_a_m_e___l_e_n_g_t_h 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 filesys- tems 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 _c_o_n_f_i_g 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 _d_o_s___f_i_l_e_- _n_a_m_e___r_e_q_u_i_r_e_d _= _t_r_u_e, and also changing the _d_e_v_e_l_o_p_m_e_n_t___d_i_r_e_c_t_o_r_y___t_e_m_- _p_l_a_t_e field. Heterogeneous development with various Windows environ- ments may also require this. TTHHEE PPRROOCCEESSSS 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 (_d_i_r_p_a_t_h) given on the command line, and all directo- ries 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 aeim- port 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 _a_e_r_m_p_r(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 _n_o_t 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 _a_e_i_p_a_s_s(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 com- ments result in longer-than-expected change descriptions. This can be corrected with _a_e_c_a(1) or _t_k_a_e_c_a(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. How- ever, 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 sim- ply 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 _a_e_l _p_r_o_j_e_c_t___h_i_s_t_o_r_y and _a_e_l _c_h_a_n_g_e___d_e_t_a_i_l_s commands. (See _a_e_l(1) for more information.) LLiimmiittaattiioonnss The aeimport program is far from perfect. There are a number of known limitations. +o 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 cou- pled files, I'll implement it. Ideas and/or code contributions welcome.) +o 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. +o There is no support for CVS modules, and there needs to be. +o 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. +o You can't import a CVS repository into an existing project. You may only create a new project from a CVS repository. +o You can't import a remote CVS repository. OOPPTTIIOONNSS The following options are understood: --DDIIRReeccttoorryy _p_a_t_h This option may be used to specify which directory is to be used. It is an error if the current user does not have appro- priate 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. --FFOORRmmaatt _n_a_m_e 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 speci- fied. NNoottee:: you _m_u_s_t have RCS installed before you run _a_e_i_m_p_o_r_t 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 ver- sion systems. (I'm told this is the format underlying Bit- Keeper.) NNoottee:: you _m_u_s_t have SCCS installed before you run _a_e_i_m_p_o_r_t 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/ --LLIIBBrraarryy _a_b_s_p_a_t_h This option may be used to specify a directory to be searched for global state files and user state files. (See _a_e_g_s_t_a_t_e(5) and _a_e_u_s_t_a_t_e(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 _A_E_G_I_S___P_A_T_H environment vari- able (colon separated), and finally, _/_u_s_r_/_l_o_c_a_l_/_l_i_b_/_a_e_g_i_s is always searched. All paths specified, either on the command line or in the _A_E_G_I_S___P_A_T_H environment variable, must be abso- lute. --LLiisstt This option may be used to obtain a list of suitable subjects for this command. The list may be more general than expected. --PPrroojjeecctt _n_a_m_e This option may be used to select the project of interest. When no --PPrroojjeecctt option is specified, the _A_E_G_I_S___P_R_O_J_E_C_T envi- ronment variable is consulted. If that does not exist, the user's _$_H_O_M_E_/_._a_e_g_i_s_r_c file is examined for a default project field (see _a_e_u_c_o_n_f(5) for more information). If that does not exist, when the user is only working on changes within a sin- gle project, the project name defaults to that project. Oth- erwise, it is an error. --HHeellpp This option may be used to obtain more information about how to use the _a_e_i_m_p_o_r_t program. --VVEERRSSiioonn _n_u_m_b_e_r 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 _a_e_g_i_s(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 inter- preted to mean the --PPrroojjeecctt 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 _a_e_i_m_p_o_r_t are long, this means ignoring the extra leading '-'. The "----_o_p_t_i_o_n==_v_a_l_u_e" convention is also understood. EEXXIITT SSTTAATTUUSS The _a_e_i_m_p_o_r_t command will exit with a status of 1 on any error. The _a_e_i_m_p_o_r_t command will only exit with a status of 0 if there are no errors. EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS See _a_e_g_i_s(1) for a list of environment variables which may affect this command. See _a_e_p_c_o_n_f(5) for the project configuration file's _p_r_o_j_e_c_t___s_p_e_c_i_f_i_c field for how to set environment variables for all commands executed by Aegis. CCOOPPYYRRIIGGHHTT aeimport version 4.25.D611 Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller The aeimport program comes with ABSOLUTELY NO WARRANTY; for details use the '_a_e_i_m_p_o_r_t _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the '_a_e_i_m_p_o_r_t _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command. AAUUTTHHOORR Peter Miller E-Mail: pmiller@opensource.org.au /\/\* WWW: http://miller.emu.id.au/pmiller/ Reference Manual Aegis aeimport(1)