1DIFFOSCOPE(1) User Commands DIFFOSCOPE(1)
2
6 diffoscope - in-depth comparison of files, archives, and directories
7
9 diffoscope --help
10 diffoscope [OPTIONS] [--json output_diff] path1 path2
11 diffoscope [OPTIONS] diff
12 diffoscope [OPTIONS] < diff
13() ()
17
21 diffoscope will try to get to the bottom of what makes files or direc‐
22 tories different. It will recursively unpack archives of many kinds and
23 transform various binary formats into more human-readable form to com‐
24 pare them. It can compare two tarballs, ISO images, or PDF just as eas‐
25 ily.
26 It can be scripted through error codes, and a report can be produced
28 with the detected differences. The report can be text or HTML. When no
29 type of report has been selected, diffoscope defaults to write a text
30 report on the standard output.
31 diffoscope was initially started by the "reproducible builds" Debian
33 project and now being developed as part of the (wider) â.Reproducible
34 Buildsâ. initiative. It is meant to be able to quickly understand why
35 two builds of the same package produce different outputs. diffoscope
36 was previously named debbindiff.
37 See the COMMAND-LINE EXAMPLES section further below to get you started,
39 as well as more detailed explanations of all the command-line options.
40 The same information is also available in /usr/share/doc/diffos‐
41 cope/README.rst or similar.
42 path1 First file or directory to compare.
44 path2 Second file or directory to compare.
46 options:
48 --debug
49 Display debug messages
50 --pdb Open the Python pdb debugger in case of crashes
52 --status-fd FD
54 Send machine-readable status to file descriptor FD
55 --progress, --no-progress
57 Show an approximate progress bar. Default: yes if stdin is a
58 tty, otherwise no.
59 --no-default-limits
61 Disable most default output limits and diff calculation limits.
62 --load-existing-diff INPUT_FILE
64 Load existing diff from file. Specify "-" to read a diffoscope
65 diff from stdin.
66 output types:
68 --text OUTPUT_FILE
69 Write plain text output to given file (use - for stdout)
70 --text-color WHEN
72 When to output color diff. WHEN is one of {never, auto, always}.
73 Default: auto, meaning yes if the output is a terminal, other‐
74 wise no.
75 --output-empty
77 If there was no difference, then output an empty diff for each
78 output type that was specified. In --text output, an empty file
79 is written.
80 --html OUTPUT_FILE
82 Write HTML report to given file (use - for stdout)
83 --html-dir OUTPUT_DIR
85 Write multi-file HTML report to given directory
86 --css URL
88 Link to an extra CSS for the HTML report
89 --jquery URL
91 URL link to jQuery, for --html and --html-dir output. If this
92 is a non-existent relative URL, diffoscope will create a symlink
93 to a system installation. (Paths searched: /usr/share/java‐
94 script/jquery/jquery.js.) If not given, --html output will not
95 use JS but --htmldir will if it can be found; give "disable" to
96 disable JS on all outputs.
97 --json OUTPUT_FILE
99 Write JSON text output to given file (use - for stdout)
100 --markdown OUTPUT_FILE
102 Write Markdown text output to given file (use - for stdout)
103 --restructured-text OUTPUT_FILE
105 Write RsT text output to given file (use - for stdout)
106 --difftool TOOL
108 Compare differences one-by-one using the specified external com‐
109 mand similar to git-difftool(1)
110 --profile [OUTPUT_FILE]
112 Write profiling info to given file (use - for stdout)
113 output limits:
115 --diff-context LINES
116 Lines of unified diff context to show. (default: 7)
117 --max-text-report-size BYTES
119 Maximum bytes written in --text report. (0 to disable, default:
120 0)
121 --max-report-size BYTES
123 Maximum bytes of a report in a given format, across all of its
124 pages. Note that some formats, such as --html, may be restricted
125 by even smaller limits such as --max-page-size. (0 to disable,
126 default: 41943040)
127 --max-diff-block-lines LINES
129 Maximum number of lines output per unified-diff block, across
130 all pages. (0 to disable, default: 1024)
131 --max-page-size BYTES
133 Maximum bytes of the top-level (--html-dir) or sole (--html)
134 page. (default: 41943040, remains in effect even with --no-de‐
135 fault-limits)
136 --max-page-diff-block-lines LINES
138 Maximum number of lines output per unified-diff block on the
139 top-level (--html-dir) or sole (--html) page, before spilling it
140 into a child page (--html-dir) or skipping the rest of the diff
141 block. (default: 128, remains in effect even with --no-de‐
142 fault-limits)
143 diff calculation:
145 --new-file
146 Treat absent files as empty
147 --exclude GLOB_PATTERN
149 Exclude files whose names (including any directory part) match
150 GLOB_PATTERN. Use this option to ignore files based on their
151 names.
152 --exclude-command REGEX_PATTERN
154 Exclude commands that match REGEX_PATTERN. For example '^read‐
155 elf.*\s--debug-dump=info' and '^radare2.*' can takea long time
156 and differences here are likely secondary differences caused by
157 something represented elsewhere. Use this option to disable com‐
158 mands that use a lot of resources.
159 --exclude-directory-metadata {auto,yes,no,recursive}
161 Exclude directory metadata. Useful if comparing files whose
162 filesystem-level metadata is not intended to be distributed to
163 other systems. This is true for most distributions package
164 builders, but not true for the output of commands such as `make
165 install`. Metadata of archive members remain un-excluded except
166 if "recursive" choice is set. Use this option to ignore permis‐
167 sions, timestamps, xattrs etc. Default: 'no' if comparing two
168 directories, else 'yes'. Note that "file" metadata is actually a
169 property of its containing directory and is not relevant when
170 distributing the file across systems.
171 --extended-filesystem-attributes, --no-extended-filesystem-attributes
173 Check potentially-expensive filesystem extended attributes such
174 as POSIX ACLs, lsattr(1)/chattr(1) attributes etc. (default:
175 False)
176 --diff-mask REGEX_PATTERN
178 Replace/unify substrings that match regular expression
179 REGEX_PATTERN from output strings before applying diff. For ex‐
180 ample, to filter out a version number or changed path.
181 --fuzzy-threshold FUZZY_THRESHOLD
183 Threshold for fuzzy-matching (0 to disable, 110 is default, 400
184 is high fuzziness)
185 --tool-prefix-binutils PREFIX
187 Prefix for binutils program names, e.g. "aarch64-linux-gnu-"
188 for a foreign-arch binary or "g" if you're on a non-GNU system.
189 --max-diff-input-lines LINES
191 Maximum number of lines fed to diff(1) (0 to disable, default:
192 4194304)
193 --max-container-depth DEPTH
195 Maximum depth to recurse into containers. (Cannot be disabled
196 for security reasons, default: 50)
197 --timeout SECONDS
199 Best-effort attempt at a global timeout in seconds. If enabled,
200 diffoscope will not recurse into any further sub-archives after
201 X seconds of total execution time. (default: no timeout) [ex‐
202 perimental]
203 --max-diff-block-lines-saved LINES
205 Maximum number of lines saved per diff block. Most users should
206 not need this, unless you run out of memory. This truncates
207 diff(1) output before emitting it in a report, and affects all
208 types of output, including --text and --json. (0 to disable, de‐
209 fault: 0)
210 --use-dbgsym WHEN
212 When to automatically use corresponding -dbgsym packages when
213 comparing .deb files. WHEN is one of {no, auto, yes}. Default:
214 auto, meaning yes if two .changes or .buildinfo files are speci‐
215 fied, otherwise no.
216 --force-details
218 Force recursing into the depths of file formats even if files
219 have the same content, only really useful for debugging diffos‐
220 cope. Default: False
221 information commands:
223 --help, -h
224 Show this help and exit
225 --version
227 Show program's version number and exit
228 --list-tools [DISTRO]
230 Show external tools required and exit. DISTRO can be one of
231 {arch, debian, FreeBSD, guix}. If specified, the output will
232 list packages in that distribution that satisfy these dependen‐
233 cies.
234 --list-debian-substvars
236 List packages needed for Debian in 'substvar' format.
237 --list-missing-tools [DISTRO]
239 Show missing external tools and exit. DISTRO can be one of
240 {arch, debian, FreeBSD, guix}. If specified, the output will
241 list packages in that distribution that satisfy these dependen‐
242 cies.
243 file formats supported:
245 Android APK files, Android boot images, Android
246 package resource table (ARSC), Apple Xcode mobile provisioning
247 files, ar(1) archives, ASM Function, Berkeley DB database files,
248 bzip2 archives, character/block devices, ColorSync colour pro‐
249 files (.icc), Coreboot CBFS filesystem images, cpio archives,
250 Dalvik .dex files, Debian .buildinfo files, Debian .changes
251 files, Debian source packages (.dsc), Device Tree Compiler blob
252 files, directories, ELF binaries, ext2/ext3/ext4/btrfs/fat
253 filesystems, Flattened Image Tree blob files, FreeDesktop Font‐
254 config cache files, FreePascal files (.ppu), Gettext message
255 catalogues, GHC Haskell .hi files, GIF image files, Git reposi‐
256 tories, GNU R database files (.rdb), GNU R Rscript files (.rds),
257 Gnumeric spreadsheets, GPG keybox databases, Gzipped files, Hi‐
258 erarchical Data Format database, HTML files (.html), ISO 9660 CD
259 images, Java .class files, Java .jmod modules, JavaScript files,
260 JPEG images, JSON files, Linux kernel images, LLVM IR bitcode
261 files, local (UNIX domain) sockets and named pipes (FIFOs), LZ4
262 compressed files, lzip compressed files, macOS binaries, Micro‐
263 soft Windows icon files, Microsoft Word .docx files, Mono 'Por‐
264 table Executable' files, Mozilla-optimized .ZIP archives, Multi‐
265 media metadata, OCaml interface files, Ogg Vorbis audio files,
266 OpenOffice .odt files, OpenSSH public keys, OpenWRT package ar‐
267 chives (.ipk), PDF documents, PE32 files, PGP signatures, PGP
268 signed/encrypted messages, PNG images, PostScript documents,
269 Public Key Cryptography Standards (PKCS) files (version #7),
270 Python .pyc files, RPM archives, Rust object files (.deflate),
271 Sphinx inventory files, SQLite databases, SquashFS filesystems,
272 symlinks, tape archives (.tar), tcpdump capture files (.pcap),
273 text files, TrueType font files, U-Boot legacy image files, We‐
274 bAssembly binary module, XML binary schemas (.xsb), XML files,
275 XMLB files, XZ compressed files, ZIP archives and Zstandard com‐
276 pressed files.
277 diffoscope homepage:
279 <https://diffoscope.org/>
280 bugs/issues:
282 <https://salsa.debian.org/reproducible-builds/diffoscope/issues>
283
285 Exit status is 0 if inputs are the same, 1 if different, 2 if trouble.
286
288 To compare two files in-depth and produce an HTML report, run something
289 like:
290 $ diffoscope --html output.html build1.changes build2.changes
292 diffoscope will exit with 0 if there's no differences and 1 if there
294 are.
295 To get all possible options, run:
297 $ diffoscope --help
299 If you have enough RAM, you can improve performance by running:
301 $ TMPDIR=/run/shm diffoscope very-big-input-0/ very-big-input-1/
303 By default this allowed to use up half of RAM; for more add something
305 like:
306 tmpfs /run/shm tmpfs size=80% 0 0
308 to your /etc/fstab; see man mount for details.
310
312 diffoscope requires Python 3 and the following modules available on
313 PyPI: libarchive-c, python-magic.
314 The various comparators rely on external commands being available. To
316 get a list of them, please run:
317 $ diffoscope --list-tools
319
321 Lunar, Reiner Herrmann, Chris Lamb, Mattia Rizzolo, Ximin Luo, Helmut
322 Grohne, Holger Levsen, Daniel Kahn Gillmor, Paul Gevers, Peter De
323 Wachter, Yasushi SHOJI, Clemens Lang, Ed Maste, Joachim Breitner, Mike
324 McQuaid. Baptiste Daroussin, Levente Polyak.
325
327 The preferred way to report bugs about diffoscope, as well as suggest
328 fixes and requests for improvements is to submit reports to the issue
329 tracker at:
330 https://salsa.debian.org/reproducible-builds/diffoscope/issues
331 For more instructions, see CONTRIBUTING.rst in this directory.
333 Join the users and developers mailing-list: <‐
335 https://lists.reproducible-builds.org/listinfo/diffoscope>
336 diffoscope website is at <https://diffoscope.org/>
338
340 diffoscope is free software: you can redistribute it and/or modify it
341 under the terms of the GNU General Public License as published by the
342 Free Software Foundation, either version 3 of the License, or (at your
343 option) any later version.
344 diffoscope is distributed in the hope that it will be useful, but WITH‐
346 OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
347 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public Li‐
348 cense for more details.
349 You should have received a copy of the GNU General Public License along
351 with diffoscope. If not, see <https://www.gnu.org/licenses/>.
352
354 • <https://diffoscope.org/>
355 • <https://wiki.debian.org/ReproducibleBuilds>
357 ()