."\ cmpd.1
."\ stored as cmpd rather than cmp to differentiate from standard unix command
.TH CMPD P "Manual V1.3 for Program V1.12" "Julian Stacey" "Julian Stacey, Vector Systems Ltd"
.\" A4 the cludgy way.
.pl 29.6c
.UC 4
.SH NAME
cmpd \- Compares files, (optionally deleting duplicates).

.SH SYNTAX
.B cmpd
[--] [-b] [-d] [-e] [-l[directory]] [-m] [-s] [-v] file_1 [file_2 file_3 file_4] last

.SH SUMMARY
.I cmpd
is a rewrite of the standard Unix like command, with extra functionality.

.SH DESCRIPTION

Compares one or more files, which may have local, relative, or rooted,
normal, hard linked, or symbolic linked names,
with a last element which may be a directory, or a file.
Where more than 2 arguments are given, the last must be a directory.
If a single argument is given reference file data is taken from <stdin>.
.I cmpd
can work with binary files.
.I cmpd
will not willingly delete the only copy of a file,
.I cmpd
detects and avoids deleting data for all the following
sequences (that might arise by human error &/or shell scripts failing):
.in +4
cmpd -d data data
.br
cmpd -d data .
.br
cmpd -d data ../datas_dir/data
.br
ln -s data symbolic_ptr ; cmpd -d data symbolic_ptr
.br
ln -s . symbolic_ptr ; cmpd -d data symbolic_ptr
.in -4
See Limitations Section Below.

Syntax such as
.ti +4
cmpd ../../same_name1 ../../same_name2 .
.br
is warned about, as it will always result in equality.
.br
.cmpd
does not convert it into
.ti +4
cmpd same_name1 same_name2 ../..
.br
Nor will such conversion be added later,
because its not at all agreeable to convert
.ti +4
cmpd -d ../../same_name1 ../../same_name2 .
.br
to
.ti +4
cmpd -d same_name1 same_name2 ../..

.SH OPTIONS

Option flags must precede file names.
Option flags may be used in any order.
Option flags available include :-

.TP
.B \--
Use stdin to provide reference file data.
.TP
.B \-m
Compare email (or news) articles, where compare of content is done,
but not fields preceeding a blank line.
If difference is detected the line number reported is the line number
for the body of the email, excluding header lines & seperator line(s).
.\" what about byte count ?
.TP
.B \-b
Reads are done in 512 byte blocks (to allow for raw unix
devices, or restricted msdos memory), rather than the normal larger 
buffer (0x2000 when writing this manual).
.TP
.B \-d
Causes deletion of first of 2 identical files (thus if last element
is a directory, individual files that have identical contents 
to 'reference_directory/individual_name', will be deleted).
Note: -d is used rather than -r, to avoid an unpleasant suprise to users used
to -r recursion/sub directory flags such as used in diff -r;
to be explicit, in case a user hopes cmpd -r will compare trees
(which it doesnt incidentaly!), we will not delete files instead!.
.TP
.B \-l[directory]
Creates a symbolic link, to replace the deleted file.
The symbolic link normally points to the unchanged reference file,
but if an optional directory is specified, 
.I cmpd
uses that to link via instead of the directory of the reference file.
This option includes action appropriate to option `-d',
(thus `-d' need not be invoked).
(Sigint is ignored between deletion & creation,
but other signals are not blocked).
.TP
.B \-e
Merge stderr to stdout.
.TP
.B \-s
Suppress complaints of not being able to stat reference files.
May be used to supplement the -d option.
When using
.ce
cmpd -d -s * ../some_reference_directory
.br
the -s is useful if you want to remove duplicates in the current directory,
but not want to know if some files cannot be found in the reference directory.
This option does not change the functionality, just suppresses warnings, (thus -s will not cause non-duplicated files to be deleted).
.TP
.B \-v
Verbose mode, announce files as processed (normal mode is silent).
.TP
.B \-M
Mode: NOT YET IMPLEMENTED. Only consider equal if mode bits on both files are identical.

.SH LIMITATIONS
.I cmpd
has no means of detecting
.ti +4
cat data | cmpd -d -- data
.br
as a dubious usage, if usage of
.I cmpd
is devious (as above), 
.I cmpd
can be forced to delete the only copy of a file.

.SH RESTRICTIONS
None

.SH EXAMPLES

How to prune out files that are unchanged between an old & new directory tree.
.br
cd old_tree ; find . -type f -exec ~local/bin/cmpd -d -v {} ../new_tree \\;

.SH EXIT CODE

.in +5
.ti -5
0
.br
All files are the same.
.ti -5
Positive integer
.br
Number of differing files.
.ti -5
Negative integer
.br
Number of differing files, plus system call failures such as open()
or unlink(); note such system call failures do not cause an immediate exit.
.ti -5
-32000
.br
User syntax or logical error.
.in -5

.SH FEATURES
.\" None known.
If two zero size files are encountered in different directories, of name typescript,
one will be delete, this is unfortunate, as of course when the 2 script commands exit, the files would then have held different contents. I don't really consider this a bug, merely unfortunate.

.SH POSSIBLE BUGS
.I cmpd does not recognise/analyse symbolic links over NFS between
multiple hosts, it IS possible to lose your only copy of a file,
doing NFS based compare & delete.

I have not yet considered the following possible bug:
Using 2 hosts & NFS, both files could by chance have same inode number,
& same major & minor, in which case the duplicate file wouldnt
be deleted when it should.

.SH HOST OP SYSTEM
This utility runs on Msdos 3.2 & Unix (inc All FreeBSD to 4.5 & BSD-4.2 on Symmetric S375).

.SH COPYRIGHT
Program Copyright Julian H. Stacey, Munich, 14th May 1987 to 2001.
.br
Document Copyright Julian H. Stacey, Munich, 11th Feb 1991 to 2001.
.so author.jhs

.SH ENHANCEMENTS PLANNED
Some day should add capability to compare & delete special devices,
if major & minor are same.

.SH FILES
No default filenames.

.SH SEE ALSO
diff(1), cmp(1).

.SH ANNEX

Test script to test 
.I cmpd
on a BSD Unix.
.nf
.in +5
echo Shell script for cmpd.c, run with sh -x

mkdir test_cmpd
cd test_cmpd
date > data
echo "different" > data2
cmpd=/usr/bin/local/cmpd

$cmpd -d -v data data2
ls -l dat*

$cmpd -d -v data data
ls -l data

$cmpd -d -v data .
ls -l data

$cmpd -d -v data ../test_cmpd/data
ls -l data

ln -s data symbolic_ptr 

$cmpd -d -v data symbolic_ptr
ls -l data symbolic_ptr

$cmpd -d -v symbolic_ptr data 
ls -l data symbolic_ptr

ln -s . symbolic_ptr ; $cmpd -d -v data symbolic_ptr
ls -l data symbolic_ptr

cat data | $cmpd -d -v -- data
ls -l data

rm data2 symbolic_ptr
cd .. 
rmdir test_cmpd
.in -5
.fi
.\ End of file