.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3.
.TH DIFFOSCOPE "1" "April 2024" "diffoscope 265" "User Commands"
.SH NAME
diffoscope \- in-depth comparison of files, archives, and directories
.SH SYNOPSIS
.nf
\fBdiffoscope\fR \-\-help
\fBdiffoscope\fR [OPTIONS] [\-\-json \fIoutput_diff\fR] \fIpath1\fR \fIpath2\fR
\fBdiffoscope\fR [OPTIONS] \fIdiff\fR
\fBdiffoscope\fR [OPTIONS] < \fIdiff\fR
.fi
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "" "" ""
.SH DESCRIPTION
.sp
diffoscope will try to get to the bottom of what makes files or
directories different. It will recursively unpack archives of many kinds
and transform various binary formats into more human\-readable form to
compare them. It can compare two tarballs, ISO images, or PDF just as
easily.
.sp
It can be scripted through error codes, and a report can be produced
with the detected differences. The report can be text or HTML.
When no type of report has been selected, diffoscope defaults
to write a text report on the standard output.
.sp
diffoscope was initially started by the \(dqreproducible builds\(dq Debian
project and now being developed as part of the (wider) \fI\%???Reproducible
Builds??? initiative\fP\&. It is meant
to be able to quickly understand why two builds of the same package
produce different outputs. diffoscope was previously named debbindiff.
.sp
See the \fBCOMMAND\-LINE EXAMPLES\fP section further below to get you
started, as well as more detailed explanations of all the command\-line
options. The same information is also available in
\fB/usr/share/doc/diffoscope/README.rst\fP or similar.
.\" the below hack gets rid of the python "usage" message in favour of the the
.\" synopsis we manually defined in doc/$(PACKAGE).h2m.0
.\" .SS positional arguments:
.TP
path1
First file or directory to compare.
.TP
path2
Second file or directory to compare.
.SS "options:"
.TP
\fB\-\-debug\fR
Display debug messages
.TP
\fB\-\-pdb\fR
Open the Python pdb debugger in case of crashes
.TP
\fB\-\-status\-fd\fR FD
Send machine\-readable status to file descriptor FD
.TP
\fB\-\-progress\fR, \fB\-\-no\-progress\fR
Show an approximate progress bar. Default: yes if
stdin is a tty, otherwise no.
.TP
\fB\-\-no\-default\-limits\fR
Disable most default output limits and diff
calculation limits.
.TP
\fB\-\-load\-existing\-diff\fR INPUT_FILE
Load existing diff from file. Specify "\-" to read a
diffoscope diff from stdin.
.SS "output types:"
.TP
\fB\-\-text\fR OUTPUT_FILE
Write plain text output to given file (use \- for
stdout)
.TP
\fB\-\-text\-color\fR WHEN
When to output color diff. WHEN is one of {never,
auto, always}. Default: auto, meaning yes if the
output is a terminal, otherwise no.
.TP
\fB\-\-output\-empty\fR
If there was no difference, then output an empty diff
for each output type that was specified. In \fB\-\-text\fR
output, an empty file is written.
.TP
\fB\-\-html\fR OUTPUT_FILE
Write HTML report to given file (use \- for stdout)
.TP
\fB\-\-html\-dir\fR OUTPUT_DIR
Write multi\-file HTML report to given directory
.TP
\fB\-\-css\fR URL
Link to an extra CSS for the HTML report
.TP
\fB\-\-jquery\fR URL
URL link to jQuery, for \fB\-\-html\fR and \fB\-\-html\-dir\fR output.
If this is a non\-existent relative URL, diffoscope
will create a symlink to a system installation. (Paths
searched: \fI\,/usr/share/javascript/jquery/jquery.js\/\fP.) If
not given, \fB\-\-html\fR output will not use JS but \fB\-\-htmldir\fR will if it can be found; give "disable" to disable
JS on all outputs.
.TP
\fB\-\-json\fR OUTPUT_FILE
Write JSON text output to given file (use \- for
stdout)
.TP
\fB\-\-markdown\fR OUTPUT_FILE
Write Markdown text output to given file (use \- for
stdout)
.TP
\fB\-\-restructured\-text\fR OUTPUT_FILE
Write RsT text output to given file (use \- for stdout)
.TP
\fB\-\-difftool\fR TOOL
Compare differences one\-by\-one using the specified
external command similar to git\-difftool(1)
.TP
\fB\-\-profile\fR [OUTPUT_FILE]
Write profiling info to given file (use \- for stdout)
.SS "output limits:"
.TP
\fB\-\-diff\-context\fR LINES
Lines of unified diff context to show. (default: 7)
.TP
\fB\-\-max\-text\-report\-size\fR BYTES
Maximum bytes written in \fB\-\-text\fR report. (0 to disable,
default: 0)
.TP
\fB\-\-max\-report\-size\fR BYTES
Maximum bytes of a report in a given format, across
all of its pages. Note that some formats, such as
\fB\-\-html\fR, may be restricted by even smaller limits such
as \fB\-\-max\-page\-size\fR. (0 to disable, default: 41943040)
.TP
\fB\-\-max\-diff\-block\-lines\fR LINES
Maximum number of lines output per unified\-diff block,
across all pages. (0 to disable, default: 1024)
.TP
\fB\-\-max\-page\-size\fR BYTES
Maximum bytes of the top\-level (\fB\-\-html\-dir\fR) or sole
(\fB\-\-html\fR) page. (default: 41943040, remains in effect
even with \fB\-\-no\-default\-limits\fR)
.TP
\fB\-\-max\-page\-diff\-block\-lines\fR LINES
Maximum number of lines output per unified\-diff block
on the top\-level (\fB\-\-html\-dir\fR) or sole (\fB\-\-html\fR) page,
before spilling it into a child page (\fB\-\-html\-dir\fR) or
skipping the rest of the diff block. (default: 128,
remains in effect even with \fB\-\-no\-default\-limits\fR)
.SS "diff calculation:"
.TP
\fB\-\-new\-file\fR
Treat absent files as empty
.TP
\fB\-\-exclude\fR GLOB_PATTERN
Exclude files whose names (including any directory
part) match GLOB_PATTERN. Use this option to ignore
files based on their names.
.TP
\fB\-\-exclude\-command\fR REGEX_PATTERN
Exclude commands that match REGEX_PATTERN. For example
\&'^readelf.*\es\-\-debug\-dump=info' and '^radare2.*' can
takea long time and differences here are likely
secondary differences caused by something represented
elsewhere. Use this option to disable commands that
use a lot of resources.
.TP
\fB\-\-exclude\-directory\-metadata\fR {auto,yes,no,recursive}
Exclude directory metadata. Useful if comparing files
whose filesystem\-level metadata is not intended to be
distributed to other systems. This is true for most
distributions package builders, but not true for the
output of commands such as `make install`. Metadata of
archive members remain un\-excluded except if
"recursive" choice is set. Use this option to ignore
permissions, timestamps, xattrs etc. Default: 'no' if
comparing two directories, else 'yes'. Note that
"file" metadata is actually a property of its
containing directory and is not relevant when
distributing the file across systems.
.TP
\fB\-\-extended\-filesystem\-attributes\fR, \fB\-\-no\-extended\-filesystem\-attributes\fR
Check potentially\-expensive filesystem extended
attributes such as POSIX ACLs, lsattr(1)/chattr(1)
attributes etc. (default: False)
.TP
\fB\-\-diff\-mask\fR REGEX_PATTERN
Replace/unify substrings that match regular expression
REGEX_PATTERN from output strings before applying
diff. For example, to filter out a version number or
changed path.
.TP
\fB\-\-fuzzy\-threshold\fR FUZZY_THRESHOLD
Threshold for fuzzy\-matching (0 to disable, 110 is
default, 400 is high fuzziness)
.TP
\fB\-\-tool\-prefix\-binutils\fR PREFIX
Prefix for binutils program names, e.g.
"aarch64\-linux\-gnu\-" for a foreign\-arch binary or "g"
if you're on a non\-GNU system.
.TP
\fB\-\-max\-diff\-input\-lines\fR LINES
Maximum number of lines fed to diff(1) (0 to disable,
default: 4194304)
.TP
\fB\-\-max\-container\-depth\fR DEPTH
Maximum depth to recurse into containers. (Cannot be
disabled for security reasons, default: 50)
.TP
\fB\-\-timeout\fR SECONDS
Best\-effort attempt at a global timeout in seconds. If
enabled, diffoscope will not recurse into any further
sub\-archives after X seconds of total execution time.
(default: no timeout) [experimental]
.TP
\fB\-\-max\-diff\-block\-lines\-saved\fR LINES
Maximum number of lines saved per diff block. Most
users should not need this, unless you run out of
memory. This truncates diff(1) output before emitting
it in a report, and affects all types of output,
including \fB\-\-text\fR and \fB\-\-json\fR. (0 to disable, default:
0)
.TP
\fB\-\-use\-dbgsym\fR WHEN
When to automatically use corresponding \fB\-dbgsym\fR
packages when comparing .deb files. WHEN is one of
{no, auto, yes}. Default: auto, meaning yes if two
\&.changes or .buildinfo files are specified, otherwise
no.
.TP
\fB\-\-force\-details\fR
Force recursing into the depths of file formats even
if files have the same content, only really useful for
debugging diffoscope. Default: False
.SS "information commands:"
.TP
\fB\-\-help\fR, \fB\-h\fR
Show this help and exit
.TP
\fB\-\-version\fR
Show program's version number and exit
.TP
\fB\-\-list\-tools\fR [DISTRO]
Show external tools required and exit. DISTRO can be
one of {arch, debian, FreeBSD, guix}. If specified,
the output will list packages in that distribution
that satisfy these dependencies.
.TP
\fB\-\-list\-debian\-substvars\fR
List packages needed for Debian in 'substvar' format.
.TP
\fB\-\-list\-missing\-tools\fR [DISTRO]
Show missing external tools and exit. DISTRO can be
one of {arch, debian, FreeBSD, guix}. If specified,
the output will list packages in that distribution
that satisfy these dependencies.
.SS "file formats supported:"
.TP
Android APK files, Android boot images, Android
package resource table (ARSC), Apple Xcode mobile
provisioning files, ar(1) archives, ASM Function,
Berkeley DB database files, bzip2 archives,
character/block devices, ColorSync colour profiles
(.icc), Coreboot CBFS filesystem images, cpio
archives, Dalvik .dex files, Debian .buildinfo files,
Debian .changes files, Debian source packages (.dsc),
Device Tree Compiler blob files, directories, ELF
binaries, ext2/ext3/ext4/btrfs/fat filesystems,
eXtensible ARchive files, Filesystem image, Flattened
Image Tree blob files, FreeDesktop Fontconfig cache
files, FreePascal files (.ppu), Gettext message
catalogues, GHC Haskell .hi files, GIF image files,
Git repositories, GNU R database files (.rdb), GNU R
Rscript files (.rds), Gnumeric spreadsheets, GPG
keybox databases, Gzipped files, Hierarchical Data
Format database, HTML files (.html), ISO 9660 CD
images, Java .class files, Java .jmod modules,
JavaScript files, JPEG images, JSON files, Linux
kernel images, LLVM IR bitcode files, local (UNIX
domain) sockets and named pipes (FIFOs), LZ4
compressed files, lzip compressed files, macOS
binaries, Microsoft Windows icon files, Microsoft Word
\&.docx files, Mono 'Portable Executable' files,
Mozilla\-optimized .ZIP archives, Multimedia metadata,
OCaml interface files, Ogg Vorbis audio files,
OpenOffice .odt files, OpenSSH public keys, OpenWRT
package archives (.ipk), PDF documents, PE32 files,
PGP signatures, PGP signed/encrypted messages, PNG
images, PostScript documents, Public Key Cryptography
Standards (PKCS) files (version #7), Python .pyc
files, RPM archives, Rust object files (.deflate),
Sphinx inventory files, SQLite databases, SquashFS
filesystems, symlinks, tape archives (.tar), tcpdump
capture files (.pcap), text files, TrueType font
files, U\-Boot legacy image files, WebAssembly binary
module, XML binary schemas (.xsb), XML files, XMLB
files, XZ compressed files, ZIP archives and Zstandard
compressed files.
.SS "diffoscope homepage:"
.IP
.SS "bugs/issues:"
.IP
.SH "EXIT STATUS"
.sp
Exit status is 0 if inputs are the same, 1 if different, 2 if trouble.
.SH "COMMAND-LINE EXAMPLES"
.sp
To compare two files in\-depth and produce an HTML report, run something like:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ diffoscope \-\-html output.html build1.changes build2.changes
.EE
.UNINDENT
.UNINDENT
.sp
diffoscope will exit with 0 if there\(aqs no differences and 1 if there
are.
.sp
To get all possible options, run:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ diffoscope \-\-help
.EE
.UNINDENT
.UNINDENT
.sp
If you have enough RAM, you can improve performance by running:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ TMPDIR=/run/shm diffoscope very\-big\-input\-0/ very\-big\-input\-1/
.EE
.UNINDENT
.UNINDENT
.sp
By default this allowed to use up half of RAM; for more add something like:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
tmpfs /run/shm tmpfs size=80% 0 0
.EE
.UNINDENT
.UNINDENT
.sp
to your \fB/etc/fstab\fP; see \fBman mount\fP for details.
.SH "EXTERNAL DEPENDENCIES"
.sp
diffoscope requires Python 3 and the following modules available on PyPI:
\fI\%libarchive\-c\fP,
\fI\%python\-magic\fP\&.
.sp
The various comparators rely on external commands being available. To
get a list of them, please run:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ diffoscope \-\-list\-tools
.EE
.UNINDENT
.UNINDENT
.SH CONTRIBUTORS
.sp
Lunar, Reiner Herrmann, Chris Lamb, Mattia Rizzolo, Ximin Luo, Helmut Grohne,
Holger Levsen, Daniel Kahn Gillmor, Paul Gevers, Peter De Wachter, Yasushi
SHOJI, Clemens Lang, Ed Maste, Joachim Breitner, Mike McQuaid. Baptiste
Daroussin, Levente Polyak.
.SH CONTACT
.sp
The preferred way to report bugs about \fIdiffoscope\fP, as well as suggest
fixes and requests for improvements is to submit reports to the issue
tracker at:
.INDENT 0.0
.INDENT 3.5
\fI\%https://salsa.debian.org/reproducible\-builds/diffoscope/issues\fP
.UNINDENT
.UNINDENT
.sp
For more instructions, see \fBCONTRIBUTING.rst\fP in this directory.
.sp
Join the users and developers mailing\-list:
<\fI\%https://lists.reproducible\-builds.org/listinfo/diffoscope\fP>
.sp
diffoscope website is at <\fI\%https://diffoscope.org/\fP>
.SH LICENSE
.sp
diffoscope 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.
.sp
diffoscope 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.
.sp
You should have received a copy of the GNU General Public License
along with diffoscope. If not, see <\fI\%https://www.gnu.org/licenses/\fP>.
.SH "SEE ALSO"
.INDENT 0.0
.IP \(bu 2
\fI\fP
.IP \(bu 2
\fI\fP
.UNINDENT
.\" Generated by docutils manpage writer.
.