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

FreeBSD Manual Pages

  
 
  

home | help
aegis -DIFFerence(1)	    General Commands Manual	  aegis	-DIFFerence(1)

NAME
	aegis difference - find	differences between a change and the baseline

SYNOPSIS
	aegis -DIFFerence [ filename...	 ] [ option...	]
	aegis -DIFFerence -List	[ option...  ]
	aegis -DIFFerence -Help

DESCRIPTION
	The aegis -DIFFerence command is used to generate difference listings
	between	source files in	the the	development directory and the base-
	line.  The purpose is to enable	reviewers to find each and every edit
	performed on the source	files.	The difference listings	will be	placed
	into files named for the sources files but with	an additional ",D"
	suffix.

	The command used to perform the	differences is specified in the
	diff_command field of the project configuration	file (see aepconf(5)
	for more information).

	It is possible to configure a project to omit the diff step as unnec-
	essary,	by the following setting:
		diff_command = "exit 0";
	This disables all generation, checking and validation of difference
	file for each change source file.  The merge functions of the aed-
	iff(1) command are unaffected by this setting.

	Please note that the history_content_limitation	field of the project
	configuration file does	not apply to the diff_command field.

	If no files are	named on the command line, all files in	the change
	will be	differenced.

	You may	name a directory on the	command	line, and all files in the
	change in that directory tree will be differenced.

   File	Name Interpretation
	The aegis program will attempt to determine the	project	file names
	from the file names given on the command line.	All file names are
	stored within aegis projects as	relative to the	root of	the baseline
	directory tree.	 The development directory and the integration direc-
	tory are shadows of this baseline directory, and so these relative
	names apply here, too.	Files named on the command line	are first con-
	verted to absolute paths if necessary.	They are then compared with
	the baseline path, the development directory path, and the integration
	directory path,	to determine a baseline-relative name.	It is an error
	if the file named is outside one of these directory trees.

	The -BAse_RElative option may be used to cause relative	filenames to
	be interpreted as relative to the baseline path; absolute filenames
	will still be compared with the	various	paths in order to determine a
	baseline-relative name.

	The relative_filename_preference in the	user configuration file	may be
	used to	modify this default behavior.  See aeuconf(5) for more infor-
	mation.

   Notification
	The actions of the command are controlled by the diff_command and
	merge_command fields of	the project config file.  See aepconf(5) for
	more information.

THE BASELINE LOCK
	The baseline lock is used to ensure that the baseline remains in a
	consistent state for the duration of commands which need to read the
	contents of files in the baseline.

	The commands which require the baseline	to be consistent (these	in-
	clude the aeb(1), aecp(1) and aed(1) commands) take a baseline read
	lock.  This is a non-exclusive lock, so	the concurrent development of
	changes	is not hindered.

	The command which modifies the baseline, aeipass(1), takes a baseline
	write lock.  This is an	exclusive lock,	forcing	aeipass(1) to block
	until there are	no active baseline read	locks.

	It is possible that one	of the above development commands will block
	until an in-progress aegis -Integrate_PASS completes.  This is usually
	of short duration while	the project history is updated.	 The delay is
	essential so that these	commands receive a consistent view of the
	baseline.  No other integration	command	will cause the above develop-
	ment commands to block.

	When aegis' branch functionality is in use, a read (non-exclusive)
	lock is	taken on the branch baseline and also each of the "parent"
	baselines.  However, a baseline	write (exclusive) lock is only taken
	on the branch baseline;	the "parent" baselines are only	read (non-ex-
	clusive) locked.

   File	Action Adjustment
	When this command runs,	it first checks	the change files against the
	projects files.	 If there are inconsistencies, the file	actions	will
	be adjusted as follows:

	create	If a file is being created, but	another	change set is inte-
		grated which also creates the file, the	file action in the
		change set still being developed will be adjusted to "modify".

	modify	If a file is being modified, but another change	set is inte-
		grated which removes the file, the file	action in the change
		set still being	developed will be adjusted to "create".

	remove	If a file is being removed, but	another	change set is inte-
		grated which removes the file, the file	will be	dropped	from
		the change set still being developed.

CONFLICT RESOLUTION
	If the version of a file in the	change is not the same as the version
	of the file in the baseline, it	is out-of-date;	some other change has
	altered	the file while this change was being developed.

	When a difference is requested for an out-of-date file,	a merge	is
	performed between the common ancestor, the version in the baseline,
	and the	version	in the development directory.  The command used	to
	perform	the merge is specified by the merge_command field of the
	project	configuration file (see	aepconf(5) for more information).

	Please note that the history_content_limitation	field of the project
	configuration file does	not apply to the merge_command field.

	After the merge	is performed the version of the	file will be changed
	to be the current version, marking the file as up to date, and a new
	build will be required.

	The original file in your development directory	is preserved with an
	",B" suffix (B for backup).  The source	file contains the result of
	the merge.  You	should edit the	source files, to make sure the auto-
	matic merge has	produced sensible results.

	This merge process works most of the time.  Usually two	changes	to two
	logically separate areas of functionality will alter two logically
	separate parts of any files they may have in common.  There are	patho-
	logical	cases where this merge process is spectacularly	useless, but
	these are surprisingly rare in practice.

	If you don't want the automatic	merge results, simply use the mv(1)
	command	to restore the contents	from the ",B" file.

	If any merges are required no differences will be performed.  An error
	message	and a non-zero exit status will	also result.  This is to en-
	sure that developers notice that merges	have been done,	and that they
	reconcile the sources and the merged ,D	files before the next differ-
	ence.  See the -No_Merge and -Only_Merge options, below, for exact
	control	of when	merging	is performed.

Cloning	and Merging
	When you use aeclone(1)	to clone a change set, and then	integrate one
	of the two change sets,	you will observe that Aegis says that the
	files of the un-integrated change are now out-of-date.

	If you run aem(1) to bring the out-of-date files back up-to-date,
	fmerge(1) and some (but	not) all other merging tools, it signals just
	about everything as a conflict,	even though both alternatives are
	identical.

	The problem is that two	changes	making identical edits to the same
	place in the same file are a logical conflict, even if not an actual
	conflict, and it takes a human to figure out the difference.  Think of
	a shopping list: the ensuite needs more	soap, and so does the main
	bathroom.  The second "soap" on	the merge of the two shopping lists
	isn't a	duplicate, you really do need two boxes	of soap.  Sometimes
	edits of source	files are the same: sometimes the logical conflict is
	resolved by applying both identical edits, not just one.

	This is	just the fmerge(1) command being more conservative than	RCS's
	merge(1) command.

	The easiest way	to deal	with this common situation it to run an
		aecpu -unchanged
	command	before you run the aem(1) merge	command, and you will have
	less grief.  It's also worth remembering that Aegis stashes the	origi-
	nal file with a	,B suffix (B for backup) so you	can simply
		mv fubar,B fubar
	if you know that all of	the conflicts are logical conflicts.

INTEGRATION
	During integration, it is also necessary to difference a change.  This
	provides the difference	between	the branch and its parent, for when
	development on a branch	is completed and it is to be reviewed.	The
	baseline of a branch is	the development	directory of the composite
	change it represents.

OPTIONS
	The following options are understood:

	-ANticipate change-number
		This option is used to nominate	a source for the reference
		files, rather than the baseline.  This may be used to synchro-
		nize with a change without having to wait for it to arrive in
		the baseline.  It is an	error if the anticipated change	is not
		in one of the 'being reviewed' or 'awaiting integration' or
		'being integrated' states.  A merge is always performed, be-
		cause the anticipated change is	"about"	to make	any common
		file out-of-date.  You will still have to perform a "real"
		merge later.

	-BRanch	number
		This option may	be used	to specify a different branch for the
		origin file, rather than the baseline.	(See also -TRunk op-
		tion.  Please Note: the	-BRanch	option does not	take a project
		name, just the branch number suffix.

	-GrandParent
		This option may	be used	to specify the grandparent branch (one
		up from	the current branch) for	the origin file, rather	than
		the baseline.  (The -grandparent option	is the same as the
		"-branch .." option.)

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

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

	-List
		This option may	be used	to obtain a list of suitable subjects
		for this command.  The list may	be more	general	than expected.

	-Not_Logging
		This option may	be used	to disable the automatic logging of
		output and errors to a file.  This is often useful when	sev-
		eral aegis commands are	combined in a shell script.

	-TRunk
		This option may	be used	to specify the project trunk for the
		origin file, rather than the baseline.	(See also -BRanch op-
		tion, the -trunk option	is the same as the "-branch -" op-
		tion.)

	-No_Merge
		This option is used to cause only file differences to be gen-
		erated,	even when file versions	are out-of-date.  If not set,
		the default is to use the diff_preference field	of the aeu-
		conf(5)	file.

	-Only_Merge
		This option is used to cause only file merges to be performed
		on files with out-of-date versions.  Other source files	are
		ignored.  If not set, the default is to	use the	diff_prefer-
		ence field of the aeuconf(5) file.

	-Automatic_Merge
		This option is used to perform -Only_Merge if any source files
		have out-of-date versions, otherwise -No_Merge is performed.
		Only merges or differences will	be performed, it will never
		use a mixture.	If not set, the	default	is to use the
		diff_preference	field of the aeuconf(5)	file.

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

	-TERse
		This option may	be used	to cause listings to produce the bare
		minimum	of information.	 It is usually useful for shell
		scripts.

	-Verbose
		This option may	be used	to cause aegis to produce more output.
		By default aegis only produces output on errors.  When used
		with the -List option this option causes column	headings to be
		added.

	-Wait	This option may	be used	to require Aegis commands to wait for
		access locks, if they cannot be	obtained immediately.  De-
		faults to the user's lock_wait_preference if not specified,
		see aeuconf(5) for more	information.

	-No_Wait
		This option may	be used	to require Aegis commands to emit a
		fatal error if access locks cannot be obtained immediately.
		Defaults to the	user's lock_wait_preference if not specified,
		see aeuconf(5) for more	information.

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

RECOMMENDED ALIAS
	The recommended	alias for this command is
	csh%	alias aed 'aegis -diff \!* -v'
	sh$	aed(){aegis -diff "$@" -v}
	For user's convenience,	particularly when they have selected the "no
	merge" preference, there is also a merge alias:
	csh%	alias aem 'aegis -diff -only_merge \!* -v'
	sh$	aem(){aegis -diff -only_merge $* -v}

ERRORS
	It is an error if the change is	not in the being developed or being
	integrated states.

EXIT STATUS
	The aegis command will exit with a status of 1 on any error.  The
	aegis 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.

SEE ALSO
	aeb(1)	build also takes a baseline read lock (non-exclusive)

	aecp(1)	copy file also takes a baseline	read lock (non-exclusive)

	aedb(1)	begin development of a change

	aeipass(1)
		integrate pass takes a baseline	write lock (exclusive)

	aepconf(5)
		project	configuration file format

	aeuconf(5)
		user configuration file	format

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

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

Reference Manual		     Aegis		  aegis	-DIFFerence(1)

NAME | SYNOPSIS | DESCRIPTION | THE BASELINE LOCK | CONFLICT RESOLUTION | Cloning and Merging | INTEGRATION | OPTIONS | RECOMMENDED ALIAS | ERRORS | EXIT STATUS | ENVIRONMENT VARIABLES | SEE ALSO | COPYRIGHT | AUTHOR

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

home | help