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 path1 First file or directory to compare.
39 path2 Second file or directory to compare.
41 options:
43 --debug
44 Display debug messages
45 --pdb Open the Python pdb debugger in case of crashes
47 --status-fd FD
49 Send machine-readable status to file descriptor FD
50 --progress, --no-progress
52 Show an approximate progress bar. Default: yes if stdin is a
53 tty, otherwise no.
54 --no-default-limits
56 Disable most default output limits and diff calculation limits.
57 --load-existing-diff INPUT_FILE
59 Load existing diff from file. Specify "-" to read a diffoscope
60 diff from stdin.
61 output types:
63 --text OUTPUT_FILE
64 Write plain text output to given file (use - for stdout)
65 --text-color WHEN
67 When to output color diff. WHEN is one of {never, auto, always}.
68 Default: auto, meaning yes if the output is a terminal, other‐
69 wise no.
70 --output-empty
72 If there was no difference, then output an empty diff for each
73 output type that was specified. In --text output, an empty file
74 is written.
75 --html OUTPUT_FILE
77 Write HTML report to given file (use - for stdout)
78 --html-dir OUTPUT_DIR
80 Write multi-file HTML report to given directory
81 --css URL
83 Link to an extra CSS for the HTML report
84 --jquery URL
86 URL link to jQuery, for --html and --html-dir output. If this
87 is a non-existent relative URL, diffoscope will create a symlink
88 to a system installation. (Paths searched: /usr/share/java‐
89 script/jquery/jquery.js.) If not given, --html output will not
90 use JS but --htmldir will if it can be found; give "disable" to
91 disable JS on all outputs.
92 --json OUTPUT_FILE
94 Write JSON text output to given file (use - for stdout)
95 --markdown OUTPUT_FILE
97 Write Markdown text output to given file (use - for stdout)
98 --restructured-text OUTPUT_FILE
100 Write RsT text output to given file (use - for stdout)
101 --difftool TOOL
103 Compare differences one-by-one using the specified external com‐
104 mand similar to git-difftool(1)
105 --profile [OUTPUT_FILE]
107 Write profiling info to given file (use - for stdout)
108 output limits:
110 --diff-context LINES
111 Lines of unified diff context to show. (default: 7)
112 --max-text-report-size BYTES
114 Maximum bytes written in --text report. (0 to disable, default:
115 0)
116 --max-report-size BYTES
118 Maximum bytes of a report in a given format, across all of its
119 pages. Note that some formats, such as --html, may be restricted
120 by even smaller limits such as --max-page-size. (0 to disable,
121 default: 41943040)
122 --max-diff-block-lines LINES
124 Maximum number of lines output per unified-diff block, across
125 all pages. (0 to disable, default: 1024)
126 --max-page-size BYTES
128 Maximum bytes of the top-level (--html-dir) or sole (--html)
129 page. (default: 41943040, remains in effect even with --no-de‐
130 fault-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 a child page (--html-dir) or skipping the rest of the diff
136 block. (default: 128, remains in effect even with --no-de‐
137 fault-limits)
138 diff calculation:
140 --new-file
141 Treat absent files as empty
142 --exclude GLOB_PATTERN
144 Exclude files whose names (including any directory part) match
145 GLOB_PATTERN. Use this option to ignore files based on their
146 names.
147 --exclude-command REGEX_PATTERN
149 Exclude commands that match REGEX_PATTERN. For example '^read‐
150 elf.*\s--debug-dump=info' and '^radare2.*' can takea long time
151 and differences here are likely secondary differences caused by
152 something represented elsewhere. Use this option to disable com‐
153 mands that use a lot of resources.
154 --exclude-directory-metadata {auto,yes,no,recursive}
156 Exclude directory metadata. Useful if comparing files whose
157 filesystem-level metadata is not intended to be distributed to
158 other systems. This is true for most distributions package
159 builders, but not true for the output of commands such as `make
160 install`. Metadata of archive members remain un-excluded except
161 if "recursive" choice is set. Use this option to ignore permis‐
162 sions, timestamps, xattrs etc. Default: 'no' if comparing two
163 directories, else 'yes'. Note that "file" metadata is actually a
164 property of its containing directory and is not relevant when
165 distributing the file across systems.
166 --extended-filesystem-attributes, --no-extended-filesystem-attributes
168 Check potentially-expensive filesystem extended attributes such
169 as POSIX ACLs, lsattr(1)/chattr(1) attributes etc. (default:
170 False)
171 --diff-mask REGEX_PATTERN
173 Replace/unify substrings that match regular expression
174 REGEX_PATTERN from output strings before applying diff. For ex‐
175 ample, to filter out a version number or changed path.
176 --fuzzy-threshold FUZZY_THRESHOLD
178 Threshold for fuzzy-matching (0 to disable, 110 is default, 400
179 is high fuzziness)
180 --tool-prefix-binutils PREFIX
182 Prefix for binutils program names, e.g. "aarch64-linux-gnu-"
183 for a foreign-arch binary or "g" if you're on a non-GNU system.
184 --max-diff-input-lines LINES
186 Maximum number of lines fed to diff(1) (0 to disable, default:
187 4194304)
188 --max-container-depth DEPTH
190 Maximum depth to recurse into containers. (Cannot be disabled
191 for security reasons, default: 50)
192 --max-diff-block-lines-saved LINES
194 Maximum number of lines saved per diff block. Most users should
195 not need this, unless you run out of memory. This truncates
196 diff(1) output before emitting it in a report, and affects all
197 types of output, including --text and --json. (0 to disable, de‐
198 fault: 0)
199 --use-dbgsym WHEN
201 When to automatically use corresponding -dbgsym packages when
202 comparing .deb files. WHEN is one of {no, auto, yes}. Default:
203 auto, meaning yes if two .changes or .buildinfo files are speci‐
204 fied, otherwise no.
205 --force-details
207 Force recursing into the depths of file formats even if files
208 have the same content, only really useful for debugging diffos‐
209 cope. Default: False
210 information commands:
212 --help, -h
213 Show this help and exit
214 --version
216 Show program's version number and exit
217 --list-tools [DISTRO]
219 Show external tools required and exit. DISTRO can be one of
220 {arch, debian, FreeBSD, guix}. If specified, the output will
221 list packages in that distribution that satisfy these dependen‐
222 cies.
223 --list-debian-substvars
225 List packages needed for Debian in 'substvar' format.
226 --list-missing-tools [DISTRO]
228 Show missing external tools and exit. DISTRO can be one of
229 {arch, debian, FreeBSD, guix}. If specified, the output will
230 list packages in that distribution that satisfy these dependen‐
231 cies.
232 file formats supported:
234 Android APK files, Android boot images, Apple Xcode
235 mobile provisioning files, ar(1) archives, ASM Function, Berke‐
236 ley DB database files, bzip2 archives, character/block devices,
237 ColorSync colour profiles (.icc), Coreboot CBFS filesystem im‐
238 ages, cpio archives, Dalvik .dex files, Debian .buildinfo files,
239 Debian .changes files, Debian source packages (.dsc), Device
240 Tree Compiler blob files, directories, ELF binaries,
241 ext2/ext3/ext4/btrfs/fat filesystems, Flattened Image Tree blob
242 files, FreeDesktop Fontconfig cache files, FreePascal files
243 (.ppu), Gettext message catalogues, GHC Haskell .hi files, GIF
244 image files, Git repositories, GNU R database files (.rdb), GNU
245 R Rscript files (.rds), Gnumeric spreadsheets, GPG keybox data‐
246 bases, Gzipped files, Hierarchical Data Format database, ISO
247 9660 CD images, Java .class files, Java .jmod modules, Java‐
248 Script files, JPEG images, JSON files, LLVM IR bitcode files,
249 LZ4 compressed files, macOS binaries, Microsoft Windows icon
250 files, Microsoft Word .docx files, Mono 'Portable Executable'
251 files, Mozilla-optimized .ZIP archives, Multimedia metadata,
252 OCaml interface files, Ogg Vorbis audio files, OpenOffice .odt
253 files, OpenSSH public keys, OpenWRT package archives (.ipk), PDF
254 documents, PE32 files, PGP signatures, PGP signed/encrypted mes‐
255 sages, PNG images, PostScript documents, Public Key Cryptography
256 Standards (PKCS) files (version #7), Python .pyc files, RPM ar‐
257 chives, Rust object files (.deflate), Sphinx inventory files,
258 SQLite databases, SquashFS filesystems, symlinks, tape archives
259 (.tar), tcpdump capture files (.pcap), text files, TrueType font
260 files, U-Boot legacy image files, WebAssembly binary module, XML
261 binary schemas (.xsb), XML files, XZ compressed files, ZIP ar‐
262 chives and Zstandard compressed files.
263 diffoscope homepage:
265 <https://diffoscope.org/>
266 bugs/issues:
268 <https://salsa.debian.org/reproducible-builds/diffoscope/issues>
269
271 Exit status is 0 if inputs are the same, 1 if different, 2 if trouble.
272
274 To compare two files in-depth and produce an HTML report, run something
275 like:
276 $ diffoscope --html output.html build1.changes build2.changes
278 diffoscope will exit with 0 if there's no differences and 1 if there
280 are.
281 diffoscope can also compare non-existent files:
283 $ diffoscope /nonexistent archive.zip
285 To get all possible options, run:
287 $ diffoscope --help
289 If you have enough RAM, you can improve performance by running:
291 $ TMPDIR=/run/shm diffoscope very-big-input-0/ very-big-input-1/
293 By default this allowed to use up half of RAM; for more add something
295 like:
296 tmpfs /run/shm tmpfs size=80% 0 0
298 to your /etc/fstab; see man mount for details.
300
302 diffoscope requires Python 3 and the following modules available on
303 PyPI: libarchive-c, python-magic.
304 The various comparators rely on external commands being available. To
306 get a list of them, please run:
307 $ diffoscope --list-tools
309
311 Lunar, Reiner Herrmann, Chris Lamb, Mattia Rizzolo, Ximin Luo, Helmut
312 Grohne, Holger Levsen, Daniel Kahn Gillmor, Paul Gevers, Peter De
313 Wachter, Yasushi SHOJI, Clemens Lang, Ed Maste, Joachim Breitner, Mike
314 McQuaid. Baptiste Daroussin, Levente Polyak.
315
317 The preferred way to report bugs about diffoscope, as well as suggest
318 fixes and requests for improvements is to submit reports to the issue
319 tracker at:
320 https://salsa.debian.org/reproducible-builds/diffoscope/issues
321 For more instructions, see CONTRIBUTING.rst in this directory.
323 Join the users and developers mailing-list: <‐
325 https://lists.reproducible-builds.org/listinfo/diffoscope>
326 diffoscope website is at <https://diffoscope.org/>
328
330 diffoscope is free software: you can redistribute it and/or modify it
331 under the terms of the GNU General Public License as published by the
332 Free Software Foundation, either version 3 of the License, or (at your
333 option) any later version.
334 diffoscope is distributed in the hope that it will be useful, but WITH‐
336 OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
337 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public Li‐
338 cense for more details.
339 You should have received a copy of the GNU General Public License along
341 with diffoscope. If not, see <https://www.gnu.org/licenses/>.
342
344 • <https://diffoscope.org/>
345 • <https://wiki.debian.org/ReproducibleBuilds>
347diffoscope 193 November 2021 DIFFOSCOPE(1)