.\" 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 ] [\fB-hv\fP] [--] [\fB-e\fP ] [\fB-a\fP] [\fB-e\fP ] [\fB-x\fP] [\fB-e\fP ] \.\.\. .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)