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

FreeBSD Manual Pages

  
 
  

home | help
aerevml(1)							    aerevml(1)

NAME
	aerevml	- send and receive RevML change	sets

SYNOPSIS
	aerevml	-Send [	option... ]
	aerevml	-Receive [ option... ]
	aerevml	-Help
	aerevml	-VERSion

DESCRIPTION
	The aerevml command is used to send and	receive	change sets using the
	RevML format.  This format is independent of any particular VC/SCM
	tool or	vendor.	 It allows export from any RevML capable VC/SCM	system
	and import into	any other RevML	capable	VC/SCM system.

	The basic function is to reproduce a change, so	a command like
		aerevml	-send |	aerevml	-receive
	may be used to clone a change, though less efficiently than ae-
	clone(1).  The file format used	is designed to withstand mail servers,
	so activities such as
		aerevml	-send |	e-mail | aerevml -receive
	(where e-mail represents sending, transporting and receiving your e-
	mail) will reproduce the change	on a remote system.  With suitable
	tools (such as PGP) is it possible to
		aerevml	-send |	encrypt	| e-mail | decrypt | aerevml -receive
	The mechanism is also designed to allow	web-based distribution such as
		aerevml	-send |	web-server -_ web-browser | aerevml -receive
	by the use of appropriate CGI scripts and mailcap entries.

	It is possible to support both a "push"	model and a "pull" model using
	this command.  For suggestions and ideas for various ways to do	this,
	see the	Aegis Users Guide.

   RevML Project
	The RevML format is used for copying revision controlled files and
	change sets between various SCM	repositories.  The RevML project may
	be found at http://public.perforce.com/public/revml/index.html

	The latest RevML DTD may be found at http://public.perforce.com/-
	public/revml/revml.dtd

SEND
	The send variant takes a specified change, or baseline,	and constructs
	a distribution package containing all of the change attributes and
	source file attributes and source file contents.  The result is	com-
	pressed, and encoded into a text format	which can be sent as e-mail
	without	being corrupted	by the mail transfer agents along the way.

   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.  Implies the -Entire_Source option, un-
		less over-ridden.

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

	-Content_Transfer_Encoding name
		This option may	be used	to specify the content transfer	encod-
		ing to be used.	 It may	take one of the	following values:

		None	No content transfer encoding is	to be performed.

		Base64	The MIME base 64 encoding is to	be used.  This is the
			default.

		Quoted_Printable
			The MIME quoted	printable encoding is to be used.

		Unix_to_Unix_encode
			The ancient unix-to-unix encoding is to	be used.

		These encodings	may be abbreviated in the same way as comment
		line options.

	-Ascii_Armor
		This means the same as the "-cte=base64" option	above.

	-No_Ascii_Armor
		This means the same as the "-cte=none" option above.

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

	-Description_Header
		This option may	be used	to add an RFC 822 style	header to the
		change description being sent, with a From and Date line.
		This is	the default.

	-No_Description_Header
		This option suppresses the description header.

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

	-Mime_Headers
		This option may	be use to force	the presence of	mime headers
		in the output, in circumstances	they would usually be absent.

	-No_Mime_Headers
		This option may	be use to force	the absence of mime headers in
		the output, in circumstances where they	would usually be
		present.

	-Partial_Source
		This option may	be used	to send	only source files of a change.
		This is	the default, except for	the -BaseLine option.

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

	-Signed_Off_By
		This option may	be used	to have	a Signed-off-by: line appended
		to the change set description.

	-No_Signed_Off_By
		This option may	be used	to prevent a Signed-off-by: line from
		being appended to the change set description.

RECEIVE
	The receive variant takes a change package created by the send variant
	and creates an Aegis change (see aenc(1)) to implement the change
	within.	 Files are added to the	change (see aerm(1), aecp(1), aenf(1)
	and aent(1)) and then the file contents	are unpackaged into the	devel-
	opment directory.

	The change is then built (see aeb(1)), differenced (see	aed(1)), and
	tested (see aet(1)).  If all of	this is	successful, development	of the
	change is ended	(see aed(1)).  The automatic process stops at this
	point, so that a local reviewer	can confirm that the change is de-
	sired.

   Notification
	The aerevml command invokes various other Aegis	commands.  The usual
	notifications 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.

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

	-Ignore_UUID
		This option may	be used	to ignore the UUID, if present,	of the
		incoming change	set.

	-No_Ignore_UUID
		This option force the aerevml command to use the change	set's
		UUID.  This is the default.

	-Project name
		This option may	be used	to set the project name.  If not spec-
		ified, the project name	in the input package will be used,
		rather than the	usual project name defaulting mechanism.

	-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
	Receiving changes by e-mail, and automatically committing them to the
	baseline without checking them,	would be a recipe for disaster.	 A
	number of safeguards are provided:

	o The format of	the package is confirmed to be correct,	and the	pack-
	  age verified for internal consistency, before	it is unpacked and
	  acted	upon.

	o The automatic	portion	of the process stops when development ends.
	  This ensures that a local reviewer validates the change before it is
	  committed, preventing	accidental or malicious	damage.

	o If the change	seeks to update	the project config file, the automatic
	  process terminates before the	build or difference occurs.  This is
	  because this file could contain trojans for these operations,	so a
	  human	must examine the file before the change	proceeds any further.

	o There	is a potential_trojan_horse = [	string ]; field	in the pro-
	  jectconfig file.  Nominate build configuration files,	shell scripts,
	  code generators, etc here to specify files in	addition to the
	  project configuration	file which should cause	the automatic process-
	  ing to halt.

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

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

   Duplicate Storms
	In a distributed development environment, it is	common for change sets
	to eventually be propagated back to the	originator.  There are situa-
	tions (particularly in some star topologies) where several copies of
	the package will return	to the originator.

	If these change	sets are not detected at the review stage, and are
	propagated out yet again, there	is the possibility of an exponential
	explosion of redundant change sets being distributed again and again.

	To combat this,	changes	are checked after the files are	unpacked, but
	before and build or difference or test is performed.  The "aecpu -un-
	changed" command is used to exclude all	files that the local reposi-
	tory already has in the	desired	form.  If no change files remain after
	this, the change is dropped entirely (see aedbu(1) and aencu(1)).

LIST
	The list variant can be	used to	list the contents of a package without
	actually unpacking it first.  The output is reminiscent	of the aegis
	-list change-details output.

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

EXIT STATUS
	The aerevml command will exit with a status of 1 on any	error.	The
	aerevml	command	will only exit with a status of	0 if there are no er-
	rors.

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
	aerevml	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 aerevml program comes with ABSOLUTELY NO WARRANTY; for details use
	the 'aerevml -VERSion License' command.	 This is free software and you
	are welcome to redistribute it under certain conditions; for details
	use the	'aerevml -VERSion License' command.

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

Reference Manual		     Aegis			    aerevml(1)

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

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

home | help