.\"
.\"     aegis - project change supervisor
.\"     Copyright (C) 1993, 1994, 2002, 2004-2008, 2010, 2012 Peter Miller.
.\"
.\"     This program is free software; you can redistribute it and/or modify
.\"     it under the terms of the GNU General Public License as published by
.\"     the Free Software Foundation; either version 3 of the License, or
.\"     (at your option) any later version.
.\"
.\"     This program is distributed in the hope that it will be useful,
.\"     but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"     GNU General Public License for more details.
.\"
.\"     You should have received a copy of the GNU General Public License
.\"     along with this program. If not, see
.\"     <http://www.gnu.org/licenses/>.
.\"
.bp
.nh 2 "Using diff and merge"
.LP
These two tools are available with most flavours of UNIX,
but often in a very limited form.
One severe limitation is the
.I diff3 (1)
command,
which often can only cope with 200 lines of differences.
The best alternative is to use GNU diff,
which has context differences available,
and a far more robust \fIdiff3\fP(1) implementation.
.LP
See the earlier
.I Interfacing
section for substitution details.
.nh 3 "diff_command"
.LP
The entry in the
configuration
file looks like this:
.E(
diff_command =
  "set +e; diff \-c $original "
  "$input > $output; test $? \-le 1";
.E)
.LP
This needs a little explanation:
.br
\(bu
This command is always executed with the shell's
.B \-e
option enabled,
causing the shell to exit on the first error.
The "set +e" turns this off.
.br
\(bu
The
.I diff (1)
command exits with a status of 0 if the files are identical,
and a status of 1 if they differ.
Any other status means something horrible happened.
The "test" command is used to change this to the exit status aegis expects.
.LP
The \fB\-c\fP option says to produce a context diff.  You may choose
to use the \fB\-u\fP option, to produce uni\[hy]diffs, if your \fIdiff\fP
command supports it.
.LP
You may also wish to consider ignoring white space in comparisons,
as these tend to be cosmetic changes and not very interesting to code
reviewers.  The \fB\-b\fP option of GNU Diff will ignore changes to
the amount of white space, and the \fB\-w\fP option will ignore white
space altogether.
.LP
Binary files will often cause modern versions of GNU Diff to exit with
an exit status of 2, which is probably reasonable most of the time.
If your project contains binary files, you may want to treat all files
as text files.  Use the GNU Diff \fB\-a\fP option in this case.
.LP
A useful alternative, available with more recent versions of GNU Diff,
is the \fB\-U\fP option.  This is a more compact form than the \fB\-c\fP
option, and is able to give the whole file as context.
.E(
diff_command =
  "set +e; diff \-U999999 $original "
  "$input > $output; test $? \-le 1";
.E)
.LP
The exit status must once again be taylored, however the output will be
the whole source for context, with changes marked by `+' and `\-' in the
left margin.  This, reviewers need only search for \f[CW]/^[\-+]/\fP in
order to see all edit made to the file.
.nh 3 "merge_command"
.LP
Note: The \fImerge\fP(1) command is better than this use of the
\fIdiff3\fP(1) command.  See the RCS chapter for more details.
.LP
The entry in the
configuration
file looks like this:
.E(
merge_command =
  "(diff3 \-e $MostRecent $original  \e
   $input | sed \-e '/^w$$/d' \-e     \e
   '/^q$$/d'; echo '1,$$p' ) | ed \- \e
   $MostRecent > $output";
.E)
.LP
This needs a lot of explanation.
.br
\(bu
The
.I diff3 (1)
command is used to produce an edit script that will
incorporate into $MostRecent,
all the changes between $original and $input.
You may want the \fB\-a\fP option, to treat all files as ACSII.
.br
\(bu
The
.I sed (1)
command is used to remove the "write" and "quit" commands
from the generated edit script.
.br
\(bu
The
.I ed (1)
command is used to apply the generated edit script to
the $MostRecent file,
and print the results on the standard output,
which are redirected into the $output file.
.\" vim: set ts=8 sw=4 et :