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