path: root/dev-util/difffilter/files/difffilter-0.3.3.man1

.\" Text automatically generated by txt2man
.TH difffilter 1 "04 November 2018" "difffilter 0.3.3" ""
.SH NAME
\fBdifffilter \fP- Filter diffs out of multi-file patches
.SH SYNOPSIS
.nf
.fam C
\fBdifffilter\fP [\fB-U\fP <lines>] [\fB-hv\fP] [--] [\fB-e\fP <regex>] [\fB-a\fP] [\fB-e\fP <regex>] [\fB-x\fP] [\fB-e\fP <regex>] \.\.\.
.fam T
.fi
.fam T
.fi
.SH DESCRIPTION
\fBdifffilter\fP reads in a series of unified-diffs and filters out any file
which matches one of the passed extended regular expressions. The remaining
diffs are written to standard out. \fBdifffilter\fP is a traditional unix filter,
reading input from standard input and writing the results to standard
output.
.PP
If \fBdifffilter\fP encounters a parsing or input reading error, it will exit
after writing an error message to standard output. In such a case,
\fBdifffilter\fP's return value is non-zero. As the parser is not guaranteed to
be perfect and badly-formatted input may be accepted by commands like
\fBpatch\fP(1), it is advised that scripts use error checking on \fBdifffilter\fP.
.SH OPTIONS
.TP
.B
\fB-h\fP
Displays some amount of helpful or unhelpful information which is intended
to be helpful. \fBdifffilter\fP will exit without performing any filtering.
.TP
.B
\fB-v\fP
Displays \fBdifffilter\fP's version information.
.TP
.B
\fB-e\fP BRE
A POSIX Basic Regular Expression which a filename in the input
diff may be matched against. The default action for a matched regex
is to exclude that portion of the diff from the output.
.TP
.B
\fB-E\fP ERE
Like \fB-e\fP but uses a POSIX Extended Regular Expression.
.TP
.B
\fB-a\fP
Any following \fB-e\fP options will cause files which match the regex to
be included in the output diff. This allows one to preserve selected files
which later patterns will exclude. See EXAMPLE for an application.
.TP
.B
\fB-x\fP
Any following \fB-e\fP options will cause files matching the regex to be excluded
from the output diff. This is the default state of difffilter. I.e.,
$ \fBdifffilter\fP \fB-e\fP 'configure$'
has the same functionality of
$ \fBdifffilter\fP \fB-x\fP \fB-e\fP 'configure$' .
.TP
.B
\fB-b\fP
Attempt to make the patch appear as if it were generated using \fBdiff\fP(1)'s \fB-b\fP
option. This is similar to \fB-w\fP but only removes changes involving changes
in the amount of whitespace. This means that completely removing a block of
whitespace or inserting whitespace between two non-whitespace characters
will still be seen as a change. See \fBdiff\fP(1) for more details.
.TP
.B
\fB-k\fP BRE
A POSIX Basic Regular Expression which will be matched against
the name of a CVS keyword whose effect is to be nullified. For example, if
the CVS keyword looks like $Pizza: I'm hungry$, a regex of `hungry' would
not match but a regex of `Pi.*a$' would.
.TP
.B
\fB-K\fP ERE
Like \fB-k\fP but uses a POSIX Extended Regular Expression.
.TP
.B
\fB-R\fP
Reverse the patch. This is intended to recover from accidents when the
sources used to generate a diff are not available but the reverse diff
is.
.TP
.B
\fB-U\fP lines
Reduce the number of lines of context of the diff to the specified
number of lines. Specify \fB-1\fP or a high number to avoid reducing the number
of lines of context. This is set to \fB-1\fP by default. You should set it to 3 in
most cases so that the effects of \fB-k\fP, \fB-b\fP, \fB-w\fP, and other flags can be more useful.
.TP
.B
\fB-w\fP
Attempt to make the patch as if it had been created by \fBdiff\fP(1) with the
\fB-w\fP option. This removes changes from the input diff for which only whitespace
was added or removed.
.SH EXAMPLES
This command should be adequate to filter out many auto-generated
files that don't belong in a Version Control System. This will
filter out files like config.log, config.status, Makefile, and
Makefile.in. It preserves Makefile.am and sourcecode files. Not that
\fB-E\fP is used instead of \fB-e\fP because the command utilizes Extended
Regular Expressions.
.PP
.nf
.fam C
    $ difffilter -E '(^|/)config\.(log|status|guess|rpath|sub)$' -E '(^|/)(install-sh|configure|ac(include|local)\.m4|ltmain\.sh|lt[^/]*\.m4)$' -a -E '(^|/)Makefile\.am$' -x -E '(^|/)Makefile' < dirty.patch > clean.patch

.fam T
.fi
If a dirty patch is submitted to a bugtracker with random whitespace
changes which should be ignored, the patch may be feed through
\fBdifffilter\fP with the \fB-b\fP or \fB-w\fP options. For most cases, \fB-b\fP is more
reasonable -- and is definitely safer than \fB-w\fP. See the CVS keyword
removal example for information on how \fB-U\fP might apply to this
situation.
.PP
.nf
.fam C
    $ difffilter -w < bug-34567-dirty.patch > bug-34567-clean.patch

.fam T
.fi
If you want to see only changes made to a particular file in a
multifile patch, such as README.txt, you may use the \fB-a\fP and \fB-x\fP flags
to effectively invert the normal filtering convention. Any files
which match expressions following an \fB-a\fP will be accepted if that
rule is processed. To revert \fBdifffilter\fP back to its normal mode of
treating expressions as files to discard, use \fB-x\fP. We use an empty
regular expression after the \fB-x\fP because the empty regular expression
matches everything and we want to discard everything but
README.txt. One can also easily modify this example to extract all
changes to \.c$ or \.h$ files.
.PP
.nf
.fam C
    $ difffilter -a -e 'README\.txt$' -x -e '' < changes-bigpatch.patch > README.txt-changes.patch

.fam T
.fi
To nullify diff lines which are caused by changes in CVS keywords'
content, use the \fB-k\fP and \fB-K\fP options. For example, a diff might catch
changes in an $Id: $ line, which is likely to happen when creating
diffs from tarballs, where CVS control files are not available. If
the $Id: $ line has change in the diff meaning that there are two
versions of the $Id: $, the user is likely going to be applying the
diff to the same file which would have a third value for the $Id: $
line. Thus, applying such a patch would be troublesome (depending on
the method of applying it). With \fB-k\fP and \fB-K\fP, we can get
.PP
.nf
.fam C
    $ difffilter -k Id < not-from-cvs.patch > not-from-cvs-fixed.patch

    - /* $Id: binki /var/test/etc/rc.conf.RCS 1.1$ */
    + /* $Id: mgorny /var/test/etc/rc.conf.RCS 2.1.5.3$ */

.fam T
.fi
to be nullified. This means that we end up getting rid of the '+'
and '-' lines and end up with a ' ' line:
.PP
.nf
.fam C
     /* $Id: binki /var/test/etc/rc.conf.RCS 1.1$ */

.fam T
.fi
To most effectively avoid such problems, the change should be first
nullified with \fB-k\fP or \fB-K\fP. Then the \fB-U\fP option should be used. The \fB-U\fP
option is used to reduce the number of lines of context a diff may
have. It would be customary to pass the value 3 to this option. If a
certain block or a portion of the diff has a series of 3 or more
null or noop lines, then \fBdifffilter\fP starts removing these. If a
whole block (or chunk, as \fBpatch\fP(1) calls it) contains no changes,
then \fBdifffilter\fP will completely drop that block from the diff. In
many cases, this may completely remove the block, especially when
(as is often the case) the CVS keyword being nullified is a line in
the header comments of a file where actual edits occur infrequently.
.PP
.nf
.fam C
    $ difffilter -k Id -U 3 < not-from-cvs.patch > not-from-cvs-fixed.patch

.fam T
.fi
.SH SEE ALSO
\fBcolordiff\fP(1), \fBdiff\fP(1), \fBpatch\fP(1), \fBhg\fP(1)
.SH BUGS
There are no known bugs.
.PP
There is a bug tracker at http://ohnopub.net/bugzilla/ .
.SH AUTHOR
Nathan Phillip Brink (binki) <ohnobinki@ohnopublishing.net>