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

FreeBSD Manual Pages

  
 
  

home | help
aepatch(1)							    aepatch(1)

NAME
	aepatch	- send and receive changes as patches

SYNOPSIS
	aepatch	-send [	option...  ]
	aepatch	-receive [ option...  ]
	aepatch	-list [	option...  ]
	aepatch	-Help
	aepatch	-VERSion

DESCRIPTION
	The aepatch command is used to send Aegis changes as patches, or re-
	ceive patches and turn them into Aegis changes.

	Please note that this only works for text files.  If your project uses
	binary files, the aepatch program will not be useful because the
	diff(1)	and patch(1) commands only work	on text	files.	Also, this
	only works for files with names	which do not contain white space.

	If you need to merge matches together, you could use the GNU patch
	utils, which include a tool to merge patches together.

SEND
	The send variant takes a specified change and constructs a patch con-
	taining	all of the changes to all of the files in that change.	The
	result is compressed, and encoded into a text format which can be sent
	as e-mail without being	corrupted by the mail transfer agents along
	the way.

	The output of the aepatch -send	command	is a normal Unix patch,	as you
	would produce using diff(1), bzip2(1) and a MIME encoder such as
	mpack(1).  There are no	special	formats.  The output can be uncom-
	pressed	with the normal	bunzip2(1) command and applied with the	normal
	patch(1) command.

	The compression	algorithm is selectable	via the	-compression-algorithm
	option,	see the	OPTIONS	section, below,	for details.  The -compatibil-
	ity option also	understands compression	needs.

   Generating Traditional Patches
	If you wish to send "traditional" patches to developers	who are	not
	using Aegis to manage the sources at their end,	you can	use the	fol-
	lowing options:
		aepatch	-send -cte=none	-comp-alg=none
	This says to use no Content Transfer Encoding, and no compression.  If
	you wish to also omit the Aegis	meta data, you can use the following
	options:
		aepatch	-send -cte=none	-nocomp	-compat=4.16
	This setting for the -compatibility option omits all Aegis extensions.

	By default, a context diff is generated.  Some projects	prefer to use
	the unified diff format.  This is controlled by	the patch_diff_command
	field of the project configuration file	(see aepconf(5)	for more in-
	formation).  If	you have GNU diff, use the following command:
		patch_diff_command = "set +e; "
		    "diff -u --text "
		    "-L	${quote	$index}	-L ${quote $index} "
		    "${quote $original}	${quote	$input}	> ${quote $output}; "
		    "test $? -le 1"";
	This setting will cause	the aepatch(1) command to produce unified diff
	patches	instead	of context diff	patches.  As you can see from this
	command, the aepatch(1)	command	is onlu	of use if you have text	source
	files; it produces less	than ideal results for binary files.

   Options
	The following options are understood by	the send variant:

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

	-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 patch 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 patch
	contents are unpackaged	into the development directory,	and the
	changes	applied	to the files.

	The patch does not have	to be produced by the aepatch(1) command.
	Normal patches produced	by diff(1) command are also valid input.  The
	intent is that you can particicate in normal open source development,
	and also use Aegis, even if your fellow	developers are not.

	Once unpacked, the change is then built	(see aeb(1)), differenced (see
	aed(1)), and tested (see aet(1)).  The automatic process stops at this
	point, so that you can confirm that the	change is desired.

   File	Names
	It is common for patch files generated using the usual diff -r mecha-
	nism to	contain	extra path prefixes.  The aepatch(1) command attempts
	to remove these	automagically.	This is	usually	possible because
	patches	usually	modify files within the	project, so the	patch file
	names are compared with	project	file names to guess which and how much
	path prefixes to remove.

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

	If you have a complex project directory	structure, from	time to	time
	people may send	you patches relative to	a sub-directory, rather	than
	relative to the	project	root.  The aepatch(1) program can't guess this
	by itself.

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

   Notification
	The aepatch 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	the change number in the patch (if present)
		will be	used if	it is available, 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.)

	-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 (if
		present), otherwise the	usual project name default will	be
		used.

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

	-Output	filename
		This option may	be used	to specify a filename which is to be
		written	with the automatically determined change number.  Use-
		ful for	writing	scripts.

   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 before development	ends.
	  This ensures that the	receiver validates the change before it	is
	  committed, and then it must also be reviewed,	preventing accidental
	  or malicious damage.

	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 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 aepatch 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
	aepatch	are long, this means ignoring the extra	leading	'-'.  The
	"--option=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 aepatch is unavailable.

	o On sending, the source files are generated using the diff(1) pro-
	  gram,	in the same way	a normal Unix patch  is	generated.
	  On receiving,	the differences	are applied to the source files, in
	  the same manner as the normal	patch(1) program.

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

	o On sending, the compressed patch is encoded using the	MIME base64
	  encoding.  This makes	the result approximately 33% larger than the
	  compressed binary would be, but still	smaller	than the primary
	  sources.  (This is optional.)
	  On receiving,	if the patch is	MIME64 encoded it will be automati-
	  cally	decoded, detetcion is automatic, you do	not need to do this
	  yourself.

EXIT STATUS
	The aepatch command will exit with a status of 1 on any	error.	The
	aepatch	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
	aepatch	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 aepatch program comes with ABSOLUTELY NO WARRANTY; for details use
	the 'aepatch -VERSion License' command.	 This is free software and you
	are welcome to redistribute it under certain conditions; for details
	use the	'aepatch -VERSion License' command.

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

Reference Manual		     Aegis			    aepatch(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=aepatch&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help