1DIFFOSCOPE(1) User Commands DIFFOSCOPE(1)
2
6 diffoscope - in-depth comparison of files, archives, and directories
7
10 diffoscope --help
11 diffoscope [OPTIONS] [--json output_diff] path1 path2
12 diffoscope [OPTIONS] diff
13 diffoscope [OPTIONS] < diff
14
16 diffoscope will try to get to the bottom of what makes files or direc‐
17 tories different. It will recursively unpack archives of many kinds and
18 transform various binary formats into more human readable form to com‐
19 pare them. It can compare two tarballs, ISO images, or PDF just as eas‐
20 ily.
21 It can be scripted through error codes, and a report can be produced
23 with the detected differences. The report can be text or HTML. When no
24 type of report has been selected, diffoscope defaults to write a text
25 report on the standard output.
26 diffoscope was initially started by the "reproducible builds" Debian
28 project and now being developed as part of the (wider) â.Reproducible
29 Buildsâ. initiative. It is meant to be able to quickly understand why
30 two builds of the same package produce different outputs. diffoscope
31 was previously named debbindiff.
32 See the COMMAND-LINE EXAMPLES section further below to get you started,
34 as well as more detailed explanations of all the command-line options.
35 The same information is also available in /usr/share/doc/diffos‐
36 cope/README.rst or similar.
37 positional arguments:
39 path1 First file or directory to compare. If omitted, tries to read a
40 diffoscope diff from stdin.
41 path2 Second file or directory to compare. If omitted, no comparison
43 is done but instead we read a diffoscope diff from path1 and
44 will output this in the formats specified by the rest of the
45 command line.
46 optional arguments:
48 --debug
49 Display debug messages
50 --debugger
52 Open the Python debugger in case of crashes
53 --status-fd FD
55 Send machine-readable status to file descriptor FD
56 --progress, --no-progress
58 Show an approximate progress bar. Default: yes if stdin is a
59 tty, otherwise no.
60 --no-default-limits
62 Disable most default output limits and diff calculation limits.
63 output types:
65 --text OUTPUT_FILE
66 Write plain text output to given file (use - for stdout)
67 --text-color WHEN
69 When to output color diff. WHEN is one of {never, auto, always}.
70 Default: auto, meaning yes if the output is a terminal, other‐
71 wise no.
72 --output-empty
74 If there was no difference, then output an empty diff for each
75 output type that was specified. In --text output, an empty file
76 is written.
77 --html OUTPUT_FILE
79 Write HTML report to given file (use - for stdout)
80 --html-dir OUTPUT_DIR
82 Write multi-file HTML report to given directory
83 --css URL
85 Link to an extra CSS for the HTML report
86 --jquery URL
88 URL link to jQuery, for --html and --html-dir output. If this
89 is a non-existent relative URL, diffoscope will create a symlink
90 to a system installation. (Paths searched:
91 /usr/share/javascript/jquery/jquery.js.) If not given, --html
92 output will not use JS but --htmldir will if it can be found;
93 give "disable" to disable JS on all outputs.
94 --json OUTPUT_FILE
96 Write JSON text output to given file (use - for stdout)
97 --markdown OUTPUT_FILE
99 Write Markdown text output to given file (use - for stdout)
100 --restructured-text OUTPUT_FILE
102 Write RsT text output to given file (use - for stdout)
103 --profile OUTPUT_FILE
105 Write profiling info to given file (use - for stdout)
106 output limits:
108 --max-text-report-size BYTES
109 Maximum bytes written in --text report. (0 to disable, default:
110 0)
111 --max-report-size BYTES
113 Maximum bytes of a report in a given format, across all of its
114 pages. Note that some formats, such as --html, may be restricted
115 by even smaller limits such as --max-page-size. (0 to disable,
116 default: 41943040)
117 --max-diff-block-lines LINES
119 Maximum number of lines output per unified-diff block, across
120 all pages. (0 to disable, default: 1024)
121 --max-page-size BYTES
123 Maximum bytes of the top-level (--html-dir) or sole (--html)
124 page. (default: 409600, remains in effect even with
125 --no-default-limits)
126 --max-page-size-child BYTES
128 In --html-dir output, this is the maximum bytes of each child
129 page (default: 204800, remains in effect even with
130 --no-default-limits)
131 --max-page-diff-block-lines LINES
133 Maximum number of lines output per unified-diff block on the
134 top-level (--html-dir) or sole (--html) page, before spilling it
135 into child pages (--html-dir) or skipping the rest of the diff
136 block. Child pages are limited instead by --max-page-size-child.
137 (default: 128, remains in effect even with --no-default-limits)
138 diff calculation:
140 --new-file
141 Treat absent files as empty
142 --exclude GLOB_PATTERN
144 Exclude files that match GLOB_PATTERN. Use this option to ignore
145 files based on their names.
146 --exclude-command REGEX_PATTERN
148 Exclude commands that match REGEX_PATTERN. For example '^read‐
149 elf.*\s--debug-dump=info' can take a long time and differences
150 here are likely secondary differences caused by something repre‐
151 sented elsewhere. Use this option to disable commands that use a
152 lot of resources.
153 --exclude-directory-metadata, --no-exclude-directory-metadata
155 Exclude directory metadata. Useful if comparing files whose
156 filesystem-level metadata is not intended to be distributed to
157 other systems. This is true for most distributions package
158 builders, but not true for the output of commands such as `make
159 install`. Metadata of archive members remain un-excluded. Use
160 this option to ignore permissions, timestamps, xattrs etc.
161 Default: False if comparing two directories, else True. Note
162 that "file" metadata actually a property of its containing
163 directory, and is not relevant when distributing the file across
164 systems.
165 --fuzzy-threshold FUZZY_THRESHOLD
167 Threshold for fuzzy-matching (0 to disable, 60 is default, 400
168 is high fuzziness)
169 --tool-prefix-binutils PREFIX
171 Prefix for binutils program names, e.g. "aarch64-linux-gnu-"
172 for a foreign-arch binary or "g" if you're on a non-GNU system.
173 --max-diff-input-lines LINES
175 Maximum number of lines fed to diff(1) (0 to disable, default:
176 4194304)
177 --max-container-depth DEPTH
179 Maximum depth to recurse into containers. (Cannot be disabled
180 for security reasons, default: 50)
181 --max-diff-block-lines-saved LINES
183 Maximum number of lines saved per diff block. Most users should
184 not need this, unless you run out of memory. This truncates
185 diff(1) output before emitting it in a report, and affects all
186 types of output, including --text and --json. (0 to disable,
187 default: 0)
188 --force-details
190 Force recursing into the depths of file formats even if files
191 have the same content, only really useful for debugging diffos‐
192 cope. Default: False
193 information commands:
195 --help, -h
196 Show this help and exit
197 --version
199 Show program's version number and exit
200 --list-tools [DISTRO]
202 Show external tools required and exit. DISTRO can be one of
203 {arch, debian, FreeBSD}. If specified, the output will list
204 packages in that distribution that satisfy these dependencies.
205 --list-debian-substvars
207 List packages needed for Debian in 'substvar' format.
208 --list-missing-tools [DISTRO]
210 Show missing external tools and exit. DISTRO can be one of
211 {arch, debian, FreeBSD}. If specified, the output will list
212 packages in that distribution that satisfy these dependencies.
213 File renaming detection based on fuzzy-matching is currently disabled.
215 It can be enabled by installing the "tlsh" module available at
216 https://github.com/trendmicro/tlsh
217 file formats supported:
219 Android APK files, Android boot images, Berkeley DB database
220 files, ColorSync colour profiles (.icc), Coreboot CBFS filesys‐
221 tem images, Dalvik .dex files, Debian .buildinfo files, Debian
222 .changes files, Debian source packages (.dsc), Device Tree Com‐
223 piler blob files, ELF binaries, FreeDesktop Fontconfig cache
224 files, FreePascal files (.ppu), GHC Haskell .hi files, GIF image
225 files, GNU R Rscript files (.rds), GNU R database files (.rdb),
226 Gettext message catalogues, Git repositories, Gnumeric spread‐
227 sheets, Gzipped files, ISO 9660 CD images, JPEG images, JSON
228 files, Java .class files, JavaScript files, LLVM IR bitcode
229 files, LZ4 compressed files, MacOS binaries, Microsoft Windows
230 icon files, Microsoft Word .docx files, Mono 'Portable Exe‐
231 cutable' files, OCaml interface files, Ogg Vorbis audio files,
232 OpenOffice .odt files, OpenSSH public keys, OpenWRT package ar‐
233 chives (.ipk), PDF documents, PGP signed/encrypted messages, PNG
234 images, PostScript documents, RPM archives, Rust object files
235 (.deflate), SQLite databases, SquashFS filesystems, TrueType
236 font files, XML binary schemas (.xsb), XML files, XZ compressed
237 files, ar(1) archives, bzip2 archives, character/block devices,
238 cpio archives, directories, ext2/ext3/ext4/btrfs/fat filesys‐
239 tems, statically-linked binaries, symlinks, tape archives
240 (.tar), tcpdump capture files (.pcap) and text files.
241
243 Exit status is 0 if inputs are the same, 1 if different, 2 if trouble.
244
246 To compare two files in-depth and produce an HTML report, run something
247 like:
248 $ diffoscope --html output.html build1.changes build2.changes
250 diffoscope will exit with 0 if there's no differences and 1 if there
252 are.
253 diffoscope can also compare non-existent files:
255 $ diffoscope /nonexistent archive.zip
257 To get all possible options, run:
259 $ diffoscope --help
261 If you have enough RAM, you can improve performance by running:
263 $ TMPDIR=/run/shm diffoscope very-big-input-0/ very-big-input-1/
265 By default this allowed to use up half of RAM; for more add something
267 like:
268 tmpfs /run/shm tmpfs size=80% 0 0
270 to your /etc/fstab; see man mount for details.
272
274 diffoscope requires Python 3 and the following modules available on
275 PyPI: libarchive-c, python-magic.
276 The various comparators rely on external commands being available. To
278 get a list of them, please run:
279 $ diffoscope --list-tools
281
283 Lunar, Reiner Herrmann, Chris Lamb, Mattia Rizzolo, Ximin Luo, Helmut
284 Grohne, Holger Levsen, Daniel Kahn Gillmor, Paul Gevers, Peter De
285 Wachter, Yasushi SHOJI, Clemens Lang, Ed Maste, Joachim Breitner, Mike
286 McQuaid. Baptiste Daroussin, Levente Polyak.
287
289 Please report bugs and send patches through the Debian bug tracking
290 system against the diffoscope package: <‐
291 https://bugs.debian.org/src:diffoscope>
292 For more instructions, see CONTRIBUTING.rst in this directory.
294 Join the users and developers mailing-list: <‐
296 https://lists.reproducible-builds.org/listinfo/diffoscope>
297 diffoscope website is at <https://diffoscope.org/>
299
301 diffoscope is free software: you can redistribute it and/or modify it
302 under the terms of the GNU General Public License as published by the
303 Free Software Foundation, either version 3 of the License, or (at your
304 option) any later version.
305 diffoscope is distributed in the hope that it will be useful, but WITH‐
307 OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
308 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
309 License for more details.
310 You should have received a copy of the GNU General Public License along
312 with diffoscope. If not, see <https://www.gnu.org/licenses/>.
313
315 · <https://diffoscope.org/>
316 · <https://wiki.debian.org/ReproducibleBuilds>
318diffoscope 105 November 2018 DIFFOSCOPE(1)