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, Apple Xcode
246 mobile provisioning files, ar(1) archives, ASM Function, Berke‐
247 ley DB database files, bzip2 archives, character/block devices,
248 ColorSync colour profiles (.icc), Coreboot CBFS filesystem im‐
249 ages, cpio archives, Dalvik .dex files, Debian .buildinfo files,
250 Debian .changes files, Debian source packages (.dsc), Device
251 Tree Compiler blob files, directories, ELF binaries,
252 ext2/ext3/ext4/btrfs/fat filesystems, Flattened Image Tree blob
253 files, FreeDesktop Fontconfig cache files, FreePascal files
254 (.ppu), Gettext message catalogues, GHC Haskell .hi files, GIF
255 image files, Git repositories, GNU R database files (.rdb), GNU
256 R Rscript files (.rds), Gnumeric spreadsheets, GPG keybox data‐
257 bases, Gzipped files, Hierarchical Data Format database, HTML
258 files (.html), ISO 9660 CD images, Java .class files, Java .jmod
259 modules, JavaScript files, JPEG images, JSON files, Linux kernel
260 images, LLVM IR bitcode files, local (UNIX domain) sockets and
261 named pipes (FIFOs), LZ4 compressed files, lzip compressed
262 files, macOS binaries, Microsoft Windows icon files, Microsoft
263 Word .docx files, Mono 'Portable Executable' files, Mozilla-op‐
264 timized .ZIP archives, Multimedia metadata, OCaml interface
265 files, Ogg Vorbis audio files, OpenOffice .odt files, OpenSSH
266 public keys, OpenWRT package archives (.ipk), PDF documents,
267 PE32 files, PGP signatures, PGP signed/encrypted messages, PNG
268 images, PostScript documents, Public Key Cryptography Standards
269 (PKCS) files (version #7), Python .pyc files, RPM archives, Rust
270 object files (.deflate), Sphinx inventory files, SQLite data‐
271 bases, SquashFS filesystems, symlinks, tape archives (.tar),
272 tcpdump capture files (.pcap), text files, TrueType font files,
273 U-Boot legacy image files, WebAssembly binary module, XML binary
274 schemas (.xsb), XML files, XMLB files, XZ compressed files, ZIP
275 archives and Zstandard compressed files.
276 diffoscope homepage:
278 <https://diffoscope.org/>
279 bugs/issues:
281 <https://salsa.debian.org/reproducible-builds/diffoscope/issues>
282
284 Exit status is 0 if inputs are the same, 1 if different, 2 if trouble.
285
287 To compare two files in-depth and produce an HTML report, run something
288 like:
289 $ diffoscope --html output.html build1.changes build2.changes
291 diffoscope will exit with 0 if there's no differences and 1 if there
293 are.
294 To get all possible options, run:
296 $ diffoscope --help
298 If you have enough RAM, you can improve performance by running:
300 $ TMPDIR=/run/shm diffoscope very-big-input-0/ very-big-input-1/
302 By default this allowed to use up half of RAM; for more add something
304 like:
305 tmpfs /run/shm tmpfs size=80% 0 0
307 to your /etc/fstab; see man mount for details.
309
311 diffoscope requires Python 3 and the following modules available on
312 PyPI: libarchive-c, python-magic.
313 The various comparators rely on external commands being available. To
315 get a list of them, please run:
316 $ diffoscope --list-tools
318
320 Lunar, Reiner Herrmann, Chris Lamb, Mattia Rizzolo, Ximin Luo, Helmut
321 Grohne, Holger Levsen, Daniel Kahn Gillmor, Paul Gevers, Peter De
322 Wachter, Yasushi SHOJI, Clemens Lang, Ed Maste, Joachim Breitner, Mike
323 McQuaid. Baptiste Daroussin, Levente Polyak.
324
326 The preferred way to report bugs about diffoscope, as well as suggest
327 fixes and requests for improvements is to submit reports to the issue
328 tracker at:
329 https://salsa.debian.org/reproducible-builds/diffoscope/issues
330 For more instructions, see CONTRIBUTING.rst in this directory.
332 Join the users and developers mailing-list: <‐
334 https://lists.reproducible-builds.org/listinfo/diffoscope>
335 diffoscope website is at <https://diffoscope.org/>
337
339 diffoscope is free software: you can redistribute it and/or modify it
340 under the terms of the GNU General Public License as published by the
341 Free Software Foundation, either version 3 of the License, or (at your
342 option) any later version.
343 diffoscope is distributed in the hope that it will be useful, but WITH‐
345 OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
346 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public Li‐
347 cense for more details.
348 You should have received a copy of the GNU General Public License along
350 with diffoscope. If not, see <https://www.gnu.org/licenses/>.
351
353 • <https://diffoscope.org/>
354 • <https://wiki.debian.org/ReproducibleBuilds>
356 ()