.lf 1 ./lib/en/man1/fcomp.1
'\" t
.\" fhist - file history and comparison tools
.\" Copyright (C) 1992-1994, 1998-2000, 2008, 2009 Peter Miller
.\"
.\" Portions of this file are
.\" Copyright (C) 1990 David I. Bell
.\"
.\" 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/>.
.\"
.ds n) fcomp
.TH \*(n) 1 FHist "Reference Manual"
.SH NAME
\*(n) \- file compare
.if require_index \{
.XX "fcomp(1)" "compare two files"
.\}
.SH SYNOPSIS
.B \*(n)
[
.IR option ...
]
.I filename1
.I filename2
.sp
.B \*(n)
.B \-Help
.sp
.B \*(n)
.B \-VERSion
.SH DESCRIPTION
The
.I \*(n)
program is used to
compare text files,
similar to the
.IR diff (1)
program.
Its advantage is that it always produces minimal differences,
and so will never mis\[hy]sync when comparing files.
Its disadvantage is that
it runs slower due to the extra work required to produce optimal
differences.
However,
for files differing by less than a few thousand lines,
its performance is adequate.
The algorithms used by this utility are also
used by the
.IR fhist (1)
program in order to produce the edit history.
.PP
To compare file
.I "old"
to file
.IR "new" ,
the command:
.RS
.nf
\*(n) old new
.fi
.RE
would be used.
This gives the differences involved in converting
.B from
file
.I "old"
.B to
file
.IR "new" .
This is analogous to the use of the
.IR cp (1)
command.
Either the
.I old
or
.I new
file may be a directory,
in which case the comparison is done to the file in the directory with
the same name as the other file.
An error is given if
.I old
and
.I new
are both directories.
.SH OPTIONS
The following options are understood:
.TP 8n
.B \-BINary
This option may be used to compare binary files on a
byte\[hy]for\[hy]byte basis.
(Each byte is treated as a \[lq]line\[rq] by the algorithm.)
Byte values are displayed in hexadecimal, as are the addresses.
Note: this is different behaviour to the \fIfhist\fP(1) option of the
same name.
.TP 8n
.B \-No_BINary
This option may be used to avoid comparing binary files.  A warnign will
be prointed on the standard error, but the program will report success
without printing andy other output.
.br
.TP 8n
.B \-Blank
.br
Ignore blank lines in the input files.
.TP 8n
\fB\-Context\fP \fInumber\fP
.br
This specifies the number of lines of "context" which is
displayed.
This shows the specified number of lines before
and after the actual lines being changed.
This is useful to locate and identify the line which is actually
being changed,
when there are many identical copies of the line in the file.
.TP 8n
.B \-Edit
.br
Output an edit script which is machine readable.
.TP 8n
\fB\-Failures\fP \fInumber\fP
.br
This stops the comparison if the number of changes exceeds the
specified number.
Each change is a delete or insert of a single line.
This is useful when you are not interested in the results
when the files are totally different.
Another use is a quick check to see if two files are identical,
by using a value of zero.
.lf 1 lib/en/man1/o_help.so
.\"
.\"     fhist - file history and comparison tools
.\"     Copyright (C) 1994, 1998, 2008, 2009 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/>.
.\"
.TP 8n
.B \-Help
.br
Give some help on how to use the
.I \*(n)
program.
.lf 140 ./lib/en/man1/fcomp.1
.TP 8n
\fB\-Join\fP \fInumber\fP
.br
This merges together lines which have changed,
if they are separated by up to the specified number of unchanged lines.
This makes a change look bigger,
but reduces the "choppiness" of the output by showing fewer
regions being changed.
This is particularly effective to suppress worthless matchings
of single blank lines or comment beginning and ending lines.
A useful value for this option is 3 or so.
.TP 8n
.B \-Matching
.br
Output matching lines,
rather then changed lines.
.TP 8n
.B \-Number
.br
This outputs the line numbers at the left edge of the output.
This isn't normally needed,
since the line numbers are displayed in the comment line
preceding the lines being displayed.
Not outputting the line numbers prevents the terminal from
needlessly scrolling for long lines.
.TP 8n
\fB\-Output\fP \fIfilename\fP
.br
Send the output to this file,
rather than the standard output.
.TP
.B \-Quiet
.br
Output only a quick summary of changes needed.
.TP 8n
.B \-Spaces
.br
This option ignores differences in the number of spaces in the two
lines.
That is,
two or more adjacent spaces are handled as a single space.
Spaces at the beginning or end of a line are totally ignored.
.TP 8n
.B \-Upcase
.br
Uppercase lines before comparing.
.lf 1 lib/en/man1/o_version.so
.\"
.\"     fhist - file history and comparison tools
.\"     Copyright (C) 1994, 1998, 2008, 2009 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/>.
.\"
.TP 8n
.B \-VERSion
.br
Show what version of
.I \*(n)
is running.
.lf 187 ./lib/en/man1/fcomp.1
.TP 8n
.B \-What
.br
This outputs all of both files together,
showing what happened to each line of the first file in order
to change to the line in the second file.
This output is in "change bar" format,
where inserted lines begin with
.BR "|+" ,
deleted lines begin with
.BR "|\[mi]" ,
and unchanged lines begin with spaces.
The presence of the vertical bar makes it easy to search for the
changed lines.
.lf 1 lib/en/man1/o__rules.so
.\"
.\"     fhist - file history and comparison tools
.\"     Copyright (C) 1991-1994, 1998, 2008, 2009 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/>.
.\"
.PP
All options may be abbreviated;
the abbreviation is documented as the upper case letters,
all lower case letters and underscores (_) are optional.
You must use consecutive sequences of optional letters.
.PP
All options are case insensitive,
you may type them in upper case or lower case or a combination of both,
case is not important.
.PP
For example:
the arguments "\-help, "\-HELP" and "\-h" are
all interpreted to mean the \fB\-Help\fP option.
The argument "\-hlp" will not be understood,
because consecutive optional characters were not supplied.
.PP
Options and other command line arguments may be
mixed arbitrarily on the command line.
.br
.ne 4
.PP
The GNU long option names are understood.
Since all option names for
.I \*(n)
are long,
this means ignoring the extra leading '\-'.
The "\fB\-\fIoption\fB=\fIvalue\fR" convention is also understood.
.lf 202 ./lib/en/man1/fcomp.1
.lf 1 lib/en/man1/z_fne.so
.\"
.\"     fhist - file history and comparison tools
.\"     Copyright (C) 1994, 1998, 2008, 2009 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/>.
.\"
.br
.ne 1i
.SH FILE NAME EXPANSION
As a convenience,
if a pathname begins with a period and a environment variable
exists with that name,
then the value of the environment variable will be used
as the actual pathname.
For example,
if a environment variable of
.I ".FOO"
has the value
.IR "this.is.a.long.name" ,
then the command
.RS
.nf
\*(n) \-o .FOO
.fi
.RE
is actually equivilant to the command
.RS
.nf
\*(n) \-o this.is.a.long.name
.fi
.RE
If you want to prevent the expansion of a
pathname which begins with a period,
then you can use an alternate form for the pathname, as in:
.RS
.nf
\*(n) \-o ./.FOO
.fi
.RE
.lf 203 ./lib/en/man1/fcomp.1
.lf 1 lib/en/man1/z_binary.so
.\"
.\"     fhist - file history and comparison tools
.\"     Copyright (C) 1999, 2000, 2008, 2009 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/>.
.\"
.br
.ne 2i
.SH BINARY FILES
In general, \*(n) can handle all text files you throw at it, even
international text with unusual encodings.  However, \*(n) is \fIunable\fP
to cope elegantly with files which contain the NUL character.
.PP
The \fIfcomp\fP(1) program simply prints a warning, and continues,
you need to know that it converts NUL characters into an 0x80 value
before performing the comparison.
.PP
The \fIfmerge\fP(1) program also converts the NUL character to an 0x80
value before merging, after a warning, and any output file will contain
this value, rather than the original NUL character.
.PP
The \fIfhist\fP(1) program, however, generates a fatal error if any input
file contains NUL characters.  This is intended to protect your source
files for unintentional corruption.  Use \fB\-BINary\fP for files which
absolutely must contain NUL characters.
.lf 204 ./lib/en/man1/fcomp.1
.lf 1 lib/en/man1/z_exit.so
.\"
.\"     fhist - file history and comparison tools
.\"     Copyright (C) 1994, 1998, 2008 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/>.
.\"
.br
.ne 1i
.SH EXIT STATUS
The
.I \*(n)
program will exit with a status of 1 on any error.
The
.I \*(n)
program will only exit with a status of 0 if there are no errors.
.lf 205 ./lib/en/man1/fcomp.1
.lf 1 lib/en/man1/z_ref.so
.\"
.\"     fhist - file history and comparison tools
.\"     Copyright (C) 1994, 1998, 2008, 2009 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/>.
.\"
.br
.ne 1i
.SH REFERENCES
This program is based on the algorithm in
.RS
.IR "An O(ND) Difference Algorithm and Its Variations" ,
Eugene W. Myers,
TR 85\[hy]6, 10\[hy]April\[hy]1985,
Department of Computer Science,
The University of Arizona,
Tuscon, Arizona 85721.
.RE
See also:
.RS
.IR "A File Comparison Program" ,
Webb Miller and Eugene W. Myers,
Software Practice and Experience,
Volume 15, No. 11, November 1985.
.RE
.lf 206 ./lib/en/man1/fcomp.1
.lf 1 lib/en/man1/z_cr.so
.\"
.\"     fhist - file history and comparison tools
.\"     Copyright (C) 1994, 1995, 1998, 2000, 2008, 2009 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/>.
.\"
.br
.ne 2i
.SH COPYRIGHT
.lf 1 etc/version.so
.ds V) 1.18.D001
.ds v) 1.18
.ds Y) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009
.lf 23 lib/en/man1/z_cr.so
.if t .ds C) \(co
.if n .ds C) (C)
\*(n) version \*(V)
.br
Copyright \*(C)
.nr d) \n(.d
\*(Y) Peter Miller;
.if '\n(d)'\n(.d' .br
.PP
This program is derived from a work
.br
Copyright \*(C) 1990 David I. Bell.
.PP
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.
.PP
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.
.PP
You should have received a copy of the GNU General Public License along
with this program. If not, see <http://www.gnu.org/licenses/>.
.br
.ne 1i
.SH AUTHORS
.TS
tab(;);
l r l.
Peter Miller;Web:;http://miller.emu.id.au/pmiller/
/\e/\e*;E\[hy]Mail:;pmiller@opensource.org.au
.sp
David I. Bell;Web:;http://www.canb.auug.org.au/~dbell
;E\[hy]Mail:;dbell@canb.auug.org.au
.TE
.lf 207 ./lib/en/man1/fcomp.1