fcomp(1)

📦
version 1.21.D001 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 fcomp — file compare 💖

okay bestie, gather round, because this is the manual page for fcomp, aka the file-compare girlie, and she is that program. let's get into it 🫶

✨ NAME ✨

fcomp — file compare 💅

🌸 SYNOPSIS 🌸

fcomp [ option...  ] filename1 filename2

fcomp -Help

fcomp -VERSion

🦋 DESCRIPTION 🦋

so the fcomp program is for comparing text files, and yeah, it's giving diff(1) energy, but hear me out. her advantage? she always produces minimal differences, which means she will literally never mis-sync when comparing files. periodt. 💅 her disadvantage? she runs slower, because producing optimal differences is extra work, no cap. but bestie, for files that differ by less than a few thousand lines, her performance is adequate, she ate. also the algorithms this utility uses are the same ones the fhist(1) program uses to produce the edit history, so you know they're iconic. ✨

to compare file old to file new, you'd run:

fcomp old new

and that gives you the differences involved in converting from file old to file new. it's analogous to how you'd use the cp(1) command. either the old or the new file may be a directory, and in that case the comparison is done to the file in the directory with the same name as the other file. and if old and new are both directories? error, sorry bestie, that's a no. 😭

🎀 OPTIONS 🎀

the following options are understood, bestie, and there are a lot of them, so let's go:

  • -BINary — this option may be used to compare binary files on a byte-for-byte basis. (each byte is treated as a "line" by the algorithm, she's flexible like that.) byte values are displayed in hexadecimal, as are the addresses. Note: this is different behaviour to the fhist(1) option of the same name, so don't get it twisted. 👑
  • -No_BINary — this option may be used to avoid comparing binary files. a warning will be printed on the standard error, but the program will report success without printing any other output. lowkey mysterious of her.
  • -Blank — ignore blank lines in the input files.
  • -Context number — 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. super useful for locating and identifying the line that's actually being changed, especially when there are many identical copies of the line in the file. like a little spotlight for your diff. 🔍
  • -Edit — output an edit script which is machine readable. for the robots. 🤖
  • -Failures number — 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're not interested in the results if the files are totally different, and it's also great for a quick check to see if two files are identical, by using a value of zero. zero = "are these even the same file bestie" ✨
  • -Help — give some help on how to use the fcomp program.
  • -Join number — this merges together lines which have changed, if they're separated by up to the specified number of unchanged lines. this makes a change look bigger, but it reduces the "choppiness" of the output by showing fewer regions being changed. it's 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. 💅
  • -Matching — output matching lines, rather than changed lines.
  • -Number — 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. and not outputting the line numbers prevents the terminal from needlessly scrolling for long lines. considerate queen. 🎀
  • -Output filename — send the output to this file, rather than the standard output.
  • -Quiet — output only a quick summary of changes needed.
  • -Spaces — 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. and spaces at the beginning or end of a line are totally ignored. gone. ghosted. 👻
  • -Upcase — uppercase lines before comparing.
  • -VERSion — show what version of fcomp is running.
  • -What — 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 |+, deleted lines begin with |−, and unchanged lines begin with spaces. the presence of the vertical bar makes it easy to search for the changed lines. iconic formatting honestly. 🔥

🧚 how the options work (the fine print, but make it cute)

all options may be abbreviated; the abbreviation is documented as the upper case letters, and all lower case letters and underscores (_) are optional. you must use consecutive sequences of optional letters, bestie, no skipping.

all options are case insensitive, you may type them in upper case or lower case or a combination of both, case is not important. slay.

for example: the arguments -help, -HELP and -h are all interpreted to mean the -Help option. the argument -hlp will not be understood, because consecutive optional characters were not supplied. she's strict about that one thing, we respect it. 🙈

options and other command line arguments may be mixed arbitrarily on the command line.

the GNU long option names are understood. since all option names for fcomp are long, this means ignoring the extra leading -. the -option=value convention is also understood.

🌈 FILE NAME EXPANSION 🌈

as a convenience, if a pathname begins with a period and an environment variable exists with that name, then the value of the environment variable will be used as the actual pathname.

for example, if an environment variable of .FOO has the value this.is.a.long.name, then the command

fcomp -o .FOO

is actually equivalent to the command

fcomp -o this.is.a.long.name

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:

fcomp -o ./.FOO

sneaky little workaround, love that for us. 💜

💀 BINARY FILES 💀

in general, fcomp can handle all text files you throw at it, even international text with unusual encodings. she's versatile like that. however, fcomp is unable to cope elegantly with files which contain the NUL character.

the fcomp(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.

the fmerge(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.

the fhist(1) program, however, generates a fatal error if any input file contains NUL characters. this is intended to protect your source files from unintentional corruption, which, honestly, valid of her. use -BINary for files which absolutely must contain NUL characters.

⚠️ seriously bestie, if your files have NUL characters, fhist(1) is gonna scream. know that going in.

⭐ EXIT STATUS ⭐

the fcomp program will exit with a status of 1 on any error. the fcomp program will only exit with a status of 0 if there are no errors. clean and simple, we stan a binary outcome. ✨

📚 REFERENCES 📚

this program is based on the algorithm in

An O(ND) Difference Algorithm and Its Variations, Eugene W.
Myers, TR 85-6, 10-April-1985, Department of Computer Science,
The University of Arizona, Tuscon, Arizona 85721.

see also:

A File Comparison Program, Webb Miller and Eugene W. Myers,
Software Practice and Experience, Volume 15, No. 11, November
1985.

fcomp version 1.21.D001

Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009, 2010, 2012 Peter Miller;

this program is derived from a work 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/>.

🫶 AUTHORS 🫶

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

David I. Bell      Web:   http://www.canb.auug.org.au/~dbell
                E-Mail:   dbell@canb.auug.org.au

and that's the whole page bestie!! this was the fcomp(1) manual, from the Reference Manual of FHist, version 1.21.D001 — go forth and diff your little heart out, you're gonna do amazing. mwah. 💖✨🎀🦋

📦 where this page comes from