'\" t
.\"	aegis - project change supervisor
.\"	Copyright (C) 2002-2004, 2006-2008 Peter Miller
.\"	Copyright (C) 2006 Walter Franzini;
.\"
.\"	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
.\"	<http://www.gnu.org/licenses/>.
.\"
.so z_name.so
.ds n) aetar
.TH "\*(n)" 1 \*(N) "Reference Manual" ""
.SH NAME
aetar \- remotely distribute a change via tar
.XX "aetar(1)" "remotely distribute a change via tar"
.SH SYNOPSIS
.B \*(n)
.B -Send
[
.IR option \&...
]
.br
.B \*(n)
.B -Receive
[
.IR option \&...
]
.br
.B \*(n)
.B -List
[
.IR option \&...
]
.br
.B \*(n)
.B -Help
.br
.B \*(n)
.B -VERSion
.SH DESCRIPTION
The
.I "\*(n)"
command is used to send and receive change sets via \fItar\fP(1) to
facilitate geographically distributed development.
.PP
The basic function is to reproduce a change, so a command like
.RS
\f(CWaetar -send | aetar -receive\fP
.RE
may be used to clone a change, though less efficiently than \fIaeclone\fP(1).
The file format used is an ordinary \fIgzip\fP(1) compressed \fItar\fP(1)
archive.
.SH SEND
The send variant takes a specified change, or baseline, and constructs
a distribution package containing all of the source file contents.
No change meta-data is included.
.PP
It is not necessary for the recipient to have the \fIaetar\fP(1) command.
It is possible to use the regular \fItar xzf\fP command to extract the
files from the archive.
.SS Options
The following options are understood by the send variant:
.TP 8n
\fB\-BaseLine\fP
This option may be used to specify the source of a project,
rather than a change.
.TP 8n
\fB\-Add_Path_Prefix\fP \fIstring\fP
This option may be used to specify a path prefix to be added to every
filename in the archive.  This means that when the archive is unpacked,
it will all be placed in the one directory.
.so o_change.so
.so o_compatibil.so
.so o_compress.so
.so o_delta.so
.TP 8n
\fB\-Entire_Source\fP
This option may be used to send the entire source of the project,
as well as the change source files.
This is the default.
.TP 8n
\fB\-Partial_Source\fP
This option may be used to send only source files of a change.
.TP 8n
\fB\-Include_Build\fP
This option may be used to send also build files.
.TP 8n
\fB\-Not_Include_Build\fP
This option may be used to send only source (source, test, config but not build)
files.
This is the default.
.so o_output.so
.so o_project.so
.SH RECEIVE
The receive variant takes a tarball and creates an Aegis change (see
\fIaenc\fP(1)) to implement the change within.  Files are added to the
change (see \fIaenf\fP(1), \fIaecp\fP(1), \fIaerm\fP(1), \fIaent\fP(1))
and then the file contents are unpackaged into the development directory.
.PP
It is not necessary for the sender to have the \fIaetar\fP(1) command.
It is possible to use the regular \fItar czf\fP command to create the
the tarball.  You may want to use the \fItardy\fP(1) command to manipulate
the filenames before extraction.
.SS File Names
It is common for tar files generated to distribute open source projects
to contain a path prefix.
.TP 8n
\fB\-Remove_Path_Prefix\fP \fIstring\fP
This option may be used to explicitly specify path prefixes to be removed,
if present.  It may be specified more than once.
.TP 8n
\fB\-Remove_Path_Prefix\fP \fInumber\fP
Strip the smallest prefix containing num leading slashes from each
file name found in the patch file.  A sequence of one or more adjacent
slashes is counted as a single slash.
.PP
If you have a complex project directory structure,
from time to time people may send you tarballs relative to a sub-directory,
rather than relative to the project root.
.TP 8n
\fB\-Add_Path_Prefix\fP \fIstring\fP
This option may be used to specify the path of a project sub-directory
in which to apply the tarball.
.SS Notification
The \fI\*(n)\fP command invokes various other Aegis commands.
The usual notifications that these commands would issue are issued.
.SS Options
The following options are understood by the receive variant:
.TP 8n
\fB\-Change\fP \fInumber\fP
This option may be used to choose the change number to be used,
otherwise one will be chosen automatically.
.TP 8n
\fB\-DELta\fP \fInumber\fP
.br
This option may be used to specify a particular
delta in the project's history to copy the file from,
just as for the \fIaecp\fP(1) command.
You may also use a delta name instead of a delta number.
.so o_dir.so
.TP 8n
\fB\-EXCLude\fP
.RS
This option may be used to exclude certain files in the tarball
from consideration.
.PP
You can also add more exclusions using the
\fIproject_\%specific\fP field of the project configuration, using the
\f[CW]aetar:exclude\fP attribute listing file names to exclude separated
by spaces.
.RE
.TP 8n
\fB\-Exclude_Auto_Tools\fP
.RS
This option may be used to exclude files common to tarballs of open
source projects which used GNU Autoconf or GNU Automake.  This is
triggered by the presence of \fIconfigure.ac\fP, \fIconfigure.in\fP or
\fIMakefile.am\fP files.  This only works for simple projects, more
complex projects will need to use the project exclude attributes.
.PP
You can set this automatically using the boolean
\f[CW]aetar:exclude-auto-tools\fP attribute in the
\fIproject_\%specific\fP field of the project configuration file.
.RE
.TP 8n
\fB\-Exclude_CVS\fP
.RS
This option may be used to exclude files common to CVS repositories,
which implement the repository functions, rather than contain source
code.  It will also look inside \f[CW].cvsignore\fP files for additional
files to ignore.
.PP
You can set this automatically using the boolean
\f[CW]aetar:exclude-cvs\fP attribute in the \fIproject_\%specific\fP
field of the project configuration file.
.RE
.so o_file_cs.so
.so o_project.so
.so o_trojan.so
.SS Security
Downloading a tarball and automatically committing it to the
baseline without checking it would be a recipe for disaster.
A number of safeguards are provided:
.TP 2n
\(bu
The file sare unpacked into a new change.
You need to edit the change description.
You need to uncopy unchanged files.
You need to difference the change.
You need to build and test the change.
This ensures that a local reviewer validates the change before it is
committed, preventing accidental or malicious damage.
.TP 2n
\(bu
The use of authentication and encryption systems, such as PGP and
GPG, are encouraged.  However, it is expected that this processing will
occur after \&\fIaetar --send\fP has constructed the package and before
\&\fIaetar --receive\fP examines and acts on the package.
Verification of the sender is the surest defense against trojan horses.
.TP 2n
\(bu
Automatic sending and receiving of packages is supported, but not
implemented within the \*(n) command.  It is expected that the \*(n)
command will be used within shell scripts customized for your site and
its unique security requirements.
See the Aegis User Guide for several different ways to do this.
.TP 2n
\(bu
The more you use Aegis' test management facilities (see \&\fIaent\fP(1)
and \&\fIaet\fP(1)) the harder it is for an inadequate change to get into
the baseline.
.SH LIST
The list variant can be used to list the contents of a tarball without
actually unpacking it first.
.SS Options
The following options are understood by the list variant:
.so o_file_cs.so
.so o_output.so
Only useful with the \-List option.
.SH OPTIONS
The following options to this command haven't been mentioned yet:
.so o_help.so
.so o__rules.so
.SH FILE FORMAT
The file format re-uses existing formats, rather than introduce anything
new.  This means it is possible to extract the contents of a package
even when \*(n) is unavailable.
.TP 2n
\(bu
The source files and other information is stored as a normal Unix
\fItar\fP(1) archive.
.TP 2n
\(bu
On sending, the tarball is compressed using the GNU gzip format.
Typically primary source files are ASCII text, resulting in significant
compression.  (This is optional.)
.br
On receiving, if the tarball is compressed it will be automagically
uncompressed, detection is automatic, you do not need to do this yourself.
.so z_exit.so
.so z_cr.so