Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
aetar(1)							      aetar(1)

NAME
	aetar -	remotely distribute a change via tar

SYNOPSIS
	aetar -Send [ option...	 ]
	aetar -Receive [ option...  ]
	aetar -List [ option...	 ]
	aetar -Help
	aetar -VERSion

DESCRIPTION
	The aetar command is used to send and receive change sets via tar(1)
	to facilitate geographically distributed development.

	The basic function is to reproduce a change, so	a command like
		aetar -send | aetar -receive
	may be used to clone a change, though less efficiently than ae-
	clone(1).  The file format used	is an ordinary gzip(1) compressed
	tar(1) archive.

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.

	It is not necessary for	the recipient to have the aetar(1) command.
	It is possible to use the regular tar xzf command to extract the files
	from the archive.

   Options
	The following options are understood by	the send variant:

	-BaseLine
		This option may	be used	to specify the source of a project,
		rather than a change.

	-Add_Path_Prefix string
		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 direc-
		tory.

	-Change	number
		This option may	be used	to specify a particular	change within
		a project.  See	aegis(1) for a complete	description of this
		option.

	-COMPATibility version-number
		This option may	be used	to specify the version of aetar(1)
		which will be receiving	this change set.  This information is
		used to	select which features to include in the	data, and
		which to omit.	By default, the	latest feature set will	be
		used.

	-compression-algorithm name
		This option may	be used	to specify the compression to be used.
		They are listed	on order of compression	effeciency.

		none	Use no compression (not	always meaningful for all com-
			mands).

		gzip	Use the	compression used by the	gzip(1)	program.

		bzip2	Use the	compression used by the	bzip2(1) program.

		More compression algorithms may	be added in the	future.

	-COMPress
		This option is deprecated in favour of the -comp-alg=gzip or
		-comp-alg=bzip2	options.

	-No_COMPress
		This options is	deprecated in favour of	the -comp-alg=none op-
		tion.

	-DELta number
		This option may	be used	to specify a particular	delta in the
		project's history to copy the file from, rather	than the most
		current	version.  If the delta has been	given a	name (see
		aedn(1)	for how) you may use a delta name instead of a delta
		number.	 It is an error	if the delta specified does not	exist.
		Delta numbers start from 1 and increase; delta 0 is a special
		case meaning "when the branch started".

	-DELta_Date string
		This option may	be used	to specify a particular	date and time
		in the project's history to copy the file from,	rather than
		the most current version.  It is an error if the string	speci-
		fied cannot be interpreted as a	valid date and time.  Quote
		the string if you need to use spaces.

	-DELta_From_Change number
		This option may	be used	to specify a particular	project	delta
		from its change	number.

	-Entire_Source
		This option may	be used	to send	the entire source of the
		project, as well as the	change source files.  This is the de-
		fault.

	-Partial_Source
		This option may	be used	to send	only source files of a change.

	-Include_Build
		This option may	be used	to send	also build files.

	-Not_Include_Build
		This option may	be used	to send	only source (source, test,
		config but not build) files.  This is the default.

	-Output	filename
		This option may	be used	to specify the output file.  The out-
		put is sent to the standard output by default.

	-Project name
		This option may	be used	to select the project of interest.
		When no	-Project option	is specified, the AEGIS_PROJECT	envi-
		ronment	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 sin-
		gle project, the project name defaults to that project.	 Oth-
		erwise,	it is an error.

RECEIVE
	The receive variant takes a tarball and	creates	an Aegis change	(see
	aenc(1)) to implement the change within.  Files	are added to the
	change (see aenf(1), aecp(1), aerm(1), aent(1))	and then the file con-
	tents are unpackaged into the development directory.

	It is not necessary for	the sender to have the aetar(1)	command.  It
	is possible to use the regular tar czf command to create the the tar-
	ball.  You may want to use the tardy(1)	command	to manipulate the
	filenames before extraction.

   File	Names
	It is common for tar files generated to	distribute open	source
	projects to contain a path prefix.

	-Remove_Path_Prefix string
		This option may	be used	to explicitly specify path prefixes to
		be removed, if present.	 It may	be specified more than once.

	-Remove_Path_Prefix number
		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.

	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.

	-Add_Path_Prefix string
		This option may	be used	to specify the path of a project sub-
		directory in which to apply the	tarball.

   Notification
	The aetar command invokes various other	Aegis commands.	 The usual no-
	tifications that these commands	would issue are	issued.

   Options
	The following options are understood by	the receive variant:

	-Change	number
		This option may	be used	to choose the change number to be
		used, otherwise	one will be chosen automatically.

	-DELta number
		This option may	be used	to specify a particular	delta in the
		project's history to copy the file from, just as for the
		aecp(1)	command.  You may also use a delta name	instead	of a
		delta number.

	-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	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.

	-EXCLude
		This option may	be used	to exclude certain files in the	tar-
		ball from consideration.

		You can	also add more exclusions using the project_specific
		field of the project configuration, using the aetar:exclude
		attribute listing file names to	exclude	separated by spaces.

	-Exclude_Auto_Tools
		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 configure.ac, config-
		ure.in or Makefile.am files.  This only	works for simple
		projects, more complex projects	will need to use the project
		exclude	attributes.

		You can	set this automatically using the boolean aetar:ex-
		clude-auto-tools attribute in the project_specific field of
		the project configuration file.

	-Exclude_CVS
		This option may	be used	to exclude files common	to CVS reposi-
		tories,	which implement	the repository functions, rather than
		contain	source code.  It will also look	inside .cvsignore
		files for additional files to ignore.

		You can	set this automatically using the boolean aetar:ex-
		clude-cvs attribute in the project_specific field of the
		project	configuration file.

	-File filename
		Read the change	set from the specified file.  The default is
		to read	it from	the standard input.  The filename `-' is un-
		derstood to mean the standard input.

		If your	system has libcurl(3), and Aegis was configured	to use
		it at compile time (this is the	default	if it is available)
		you will also be able to specify a Uniform Resource Locator
		(URL) in place of the file name.  The relevant data will be
		downloaded.  (The -Verbose option will provide a progress
		bar.)

	-Project name
		This option may	be used	to select the project of interest.
		When no	-Project option	is specified, the AEGIS_PROJECT	envi-
		ronment	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 sin-
		gle project, the project name defaults to that project.	 Oth-
		erwise,	it is an error.

	-Trojan	This option may	be used	to treat the change set	as if it had a
		Trojan horse attack in it.

	-No_Trojan
		This option may	be used	to treat the change set	as if it defi-
		nitely does not	have a Trojan horse attack in it.  Use with
		extreme	care.  You need	to have	authenticated the message with
		something like PGP first and know the the author well.

   Security
	Downloading a tarball and automatically	committing it to the baseline
	without	checking it would be a recipe for disaster.  A number of safe-
	guards are provided:

	o 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.

	o The use of authentication and	encryption systems, such as PGP	and
	  GPG, are encouraged.	However, it is expected	that this processing
	  will occur after aetar -send has constructed the package and before
	  aetar	-receive examines and acts on the package.  Verification of
	  the sender is	the surest defense against trojan horses.

	o Automatic sending and	receiving of packages is supported, but	not
	  implemented within the aetar command.	 It is expected	that the aetar
	  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.

	o The more you use Aegis' test management facilities (see aent(1) and
	  aet(1)) the harder it	is for an inadequate change to get into	the
	  baseline.

LIST
	The list variant can be	used to	list the contents of a tarball without
	actually unpacking it first.

   Options
	The following options are understood by	the list variant:

	-File filename
		Read the change	set from the specified file.  The default is
		to read	it from	the standard input.  The filename `-' is un-
		derstood to mean the standard input.

		If your	system has libcurl(3), and Aegis was configured	to use
		it at compile time (this is the	default	if it is available)
		you will also be able to specify a Uniform Resource Locator
		(URL) in place of the file name.  The relevant data will be
		downloaded.  (The -Verbose option will provide a progress
		bar.)

	-Output	filename
		This option may	be used	to specify the output file.  The out-
		put is sent to the standard output by default.	Only useful
		with the -List option.

OPTIONS
	The following options to this command haven't been mentioned yet:

	-Help
		This option may	be used	to obtain more information about how
		to use the aetar program.

	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 op-
	tional.	 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 -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
	aetar are long,	this means ignoring the	extra leading '-'.  The	"--op-
	tion=value" convention is also understood.

FILE FORMAT
	The file format	re-uses	existing formats, rather than introduce	any-
	thing new.  This means it is possible to extract the contents of a
	package	even when aetar	is unavailable.

	o The source files and other information is stored as a	normal Unix
	  tar(1) archive.

	o On sending, the tarball is compressed	using the GNU gzip format.
	  Typically primary source files are ASCII text, resulting in signifi-
	  cant compression.  (This is optional.)
	  On receiving,	if the tarball is compressed it	will be	automagically
	  uncompressed,	detection is automatic,	you do not need	to do this
	  yourself.

EXIT STATUS
	The aetar command will exit with a status of 1 on any error.  The ae-
	tar 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
	aetar version 4.25.D510
	Copyright (C) 1991, 1992, 1993,	1994, 1995, 1996, 1997,	1998, 1999,
	2000, 2001, 2002, 2003,	2004, 2005, 2006, 2007,	2008, 2009, 2010,
	2011, 2012 Peter Miller

	The aetar program comes	with ABSOLUTELY	NO WARRANTY; for details use
	the 'aetar -VERSion License' command.  This is free software and you
	are welcome to redistribute it under certain conditions; for details
	use the	'aetar -VERSion	License' command.

AUTHOR
	Peter Miller   E-Mail:	 pmiller@opensource.org.au
	/\/\*		  WWW:	 http://miller.emu.id.au/pmiller/

Reference Manual		     Aegis			      aetar(1)

NAME | SYNOPSIS | DESCRIPTION | SEND | RECEIVE | LIST | OPTIONS | FILE FORMAT | EXIT STATUS | ENVIRONMENT VARIABLES | COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=aetar&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help