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 --use-dbgsym
190 Automatically use corresponding -dbgsym packageswhen comparing
191 .deb files. (default: False)
192 --force-details
194 Force recursing into the depths of file formats even if files
195 have the same content, only really useful for debugging diffos‐
196 cope. Default: False
197 information commands:
199 --help, -h
200 Show this help and exit
201 --version
203 Show program's version number and exit
204 --list-tools [DISTRO]
206 Show external tools required and exit. DISTRO can be one of
207 {arch, debian, FreeBSD}. If specified, the output will list
208 packages in that distribution that satisfy these dependencies.
209 --list-debian-substvars
211 List packages needed for Debian in 'substvar' format.
212 --list-missing-tools [DISTRO]
214 Show missing external tools and exit. DISTRO can be one of
215 {arch, debian, FreeBSD}. If specified, the output will list
216 packages in that distribution that satisfy these dependencies.
217 File renaming detection based on fuzzy-matching is currently disabled.
219 It can be enabled by installing the "tlsh" module available at
220 https://github.com/trendmicro/tlsh
221 file formats supported:
223 Android APK files, Android boot images, Berkeley DB database
224 files, ColorSync colour profiles (.icc), Coreboot CBFS filesys‐
225 tem images, Dalvik .dex files, Debian .buildinfo files, Debian
226 .changes files, Debian source packages (.dsc), Device Tree Com‐
227 piler blob files, ELF binaries, FreeDesktop Fontconfig cache
228 files, FreePascal files (.ppu), GHC Haskell .hi files, GIF image
229 files, GNU R Rscript files (.rds), GNU R database files (.rdb),
230 Gettext message catalogues, Git repositories, Gnumeric spread‐
231 sheets, Gzipped files, ISO 9660 CD images, JPEG images, JSON
232 files, Java .class files, JavaScript files, LLVM IR bitcode
233 files, LZ4 compressed files, MacOS binaries, Microsoft Windows
234 icon files, Microsoft Word .docx files, Mono 'Portable Exe‐
235 cutable' files, OCaml interface files, Ogg Vorbis audio files,
236 OpenOffice .odt files, OpenSSH public keys, OpenWRT package ar‐
237 chives (.ipk), PDF documents, PGP signed/encrypted messages, PNG
238 images, PostScript documents, RPM archives, Rust object files
239 (.deflate), SQLite databases, SquashFS filesystems, TrueType
240 font files, WebAssembly binary module, XML binary schemas
241 (.xsb), XML files, XZ compressed files, ar(1) archives, bzip2
242 archives, character/block devices, cpio archives, directories,
243 ext2/ext3/ext4/btrfs/fat filesystems, statically-linked bina‐
244 ries, symlinks, tape archives (.tar), tcpdump capture files
245 (.pcap) and text files.
246
248 Exit status is 0 if inputs are the same, 1 if different, 2 if trouble.
249
251 To compare two files in-depth and produce an HTML report, run something
252 like:
253 $ diffoscope --html output.html build1.changes build2.changes
255 diffoscope will exit with 0 if there's no differences and 1 if there
257 are.
258 diffoscope can also compare non-existent files:
260 $ diffoscope /nonexistent archive.zip
262 To get all possible options, run:
264 $ diffoscope --help
266 If you have enough RAM, you can improve performance by running:
268 $ TMPDIR=/run/shm diffoscope very-big-input-0/ very-big-input-1/
270 By default this allowed to use up half of RAM; for more add something
272 like:
273 tmpfs /run/shm tmpfs size=80% 0 0
275 to your /etc/fstab; see man mount for details.
277
279 diffoscope requires Python 3 and the following modules available on
280 PyPI: libarchive-c, python-magic.
281 The various comparators rely on external commands being available. To
283 get a list of them, please run:
284 $ diffoscope --list-tools
286
288 Lunar, Reiner Herrmann, Chris Lamb, Mattia Rizzolo, Ximin Luo, Helmut
289 Grohne, Holger Levsen, Daniel Kahn Gillmor, Paul Gevers, Peter De
290 Wachter, Yasushi SHOJI, Clemens Lang, Ed Maste, Joachim Breitner, Mike
291 McQuaid. Baptiste Daroussin, Levente Polyak.
292
294 Please report bugs and send patches through the Debian bug tracking
295 system against the diffoscope package: <‐
296 https://bugs.debian.org/src:diffoscope>
297 For more instructions, see CONTRIBUTING.rst in this directory.
299 Join the users and developers mailing-list: <‐
301 https://lists.reproducible-builds.org/listinfo/diffoscope>
302 diffoscope website is at <https://diffoscope.org/>
304
306 diffoscope is free software: you can redistribute it and/or modify it
307 under the terms of the GNU General Public License as published by the
308 Free Software Foundation, either version 3 of the License, or (at your
309 option) any later version.
310 diffoscope is distributed in the hope that it will be useful, but WITH‐
312 OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
313 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
314 License for more details.
315 You should have received a copy of the GNU General Public License along
317 with diffoscope. If not, see <https://www.gnu.org/licenses/>.
318
320 · <https://diffoscope.org/>
321 · <https://wiki.debian.org/ReproducibleBuilds>
323diffoscope 111 July 2019 DIFFOSCOPE(1)