 -DIFFerence(1)

NAME
-DIFFerence - find differences between a change and the baseline

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

DESCRIPTION
The -DIFFerence command is used to generate difference listings between source files in the the development directory and the baseline. 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 unnecessary, 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 aediff(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.

  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.

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 automatic 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 pathological 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 ensure that developers notice that merges have been done, and that they reconcile the sources and the merged ,D files before the next difference. See the -No_Merge and -Only_Merge options, below, for exact control of when merging is performed.

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:

-No_Merge
    This option is used to cause only file differences to be generated, even when file versions are out-of-date. If not set, the default is to use the diff_preference field of the aeuconf(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_preference 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.

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

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

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