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. Specify "-" to read a diffo‐
39 scope diff from stdin.
40 path2 Second file or directory to compare. If omitted, no comparison
42 is done but instead we read a diffoscope diff from path1 and
43 will output this in the formats specified by the rest of the
44 command line.
45 optional arguments:
47 --debug
48 Display debug messages
49 --debugger
51 Open the Python 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 output types:
64 --text OUTPUT_FILE
65 Write plain text output to given file (use - for stdout)
66 --text-color WHEN
68 When to output color diff. WHEN is one of {never, auto, always}.
69 Default: auto, meaning yes if the output is a terminal, other‐
70 wise no.
71 --output-empty
73 If there was no difference, then output an empty diff for each
74 output type that was specified. In --text output, an empty file
75 is written.
76 --html OUTPUT_FILE
78 Write HTML report to given file (use - for stdout)
79 --html-dir OUTPUT_DIR
81 Write multi-file HTML report to given directory
82 --css URL
84 Link to an extra CSS for the HTML report
85 --jquery URL
87 URL link to jQuery, for --html and --html-dir output. If this
88 is a non-existent relative URL, diffoscope will create a symlink
89 to a system installation. (Paths searched:
90 /usr/share/javascript/jquery/jquery.js.) If not given, --html
91 output will not use JS but --htmldir will if it can be found;
92 give "disable" to disable JS on all outputs.
93 --json OUTPUT_FILE
95 Write JSON text output to given file (use - for stdout)
96 --markdown OUTPUT_FILE
98 Write Markdown text output to given file (use - for stdout)
99 --restructured-text OUTPUT_FILE
101 Write RsT text output to given file (use - for stdout)
102 --difftool TOOL
104 Compare differences one-by-one using the specified external com‐
105 mand similar to git-difftool(1)
106 --profile OUTPUT_FILE
108 Write profiling info to given file (use - for stdout)
109 output limits:
111 --max-text-report-size BYTES
112 Maximum bytes written in --text report. (0 to disable, default:
113 0)
114 --max-report-size BYTES
116 Maximum bytes of a report in a given format, across all of its
117 pages. Note that some formats, such as --html, may be restricted
118 by even smaller limits such as --max-page-size. (0 to disable,
119 default: 41943040)
120 --max-diff-block-lines LINES
122 Maximum number of lines output per unified-diff block, across
123 all pages. (0 to disable, default: 1024)
124 --max-page-size BYTES
126 Maximum bytes of the top-level (--html-dir) or sole (--html)
127 page. (default: 41943040, remains in effect even with
128 --no-default-limits)
129 --max-page-size-child BYTES
131 In --html-dir output, this is the maximum bytes of each child
132 page (default: 204800, remains in effect even with
133 --no-default-limits)
134 --max-page-diff-block-lines LINES
136 Maximum number of lines output per unified-diff block on the
137 top-level (--html-dir) or sole (--html) page, before spilling it
138 into child pages (--html-dir) or skipping the rest of the diff
139 block. Child pages are limited instead by --max-page-size-child.
140 (default: 128, remains in effect even with --no-default-limits)
141 diff calculation:
143 --new-file
144 Treat absent files as empty
145 --exclude GLOB_PATTERN
147 Exclude files that match GLOB_PATTERN. Use this option to ignore
148 files based on their names.
149 --exclude-command REGEX_PATTERN
151 Exclude commands that match REGEX_PATTERN. For example '^read‐
152 elf.*\s--debug-dump=info' can take a long time and differences
153 here are likely secondary differences caused by something repre‐
154 sented elsewhere. Use this option to disable commands that use a
155 lot of resources.
156 --exclude-directory-metadata {auto,yes,no,recursive}
158 Exclude directory metadata. Useful if comparing files whose
159 filesystem-level metadata is not intended to be distributed to
160 other systems. This is true for most distributions package
161 builders, but not true for the output of commands such as `make
162 install`. Metadata of archive members remain un-excluded except
163 if "recursive" choice is set. Use this option to ignore permis‐
164 sions, timestamps, xattrs etc. Default: False if comparing two
165 directories, else True. Note that "file" metadata actually a
166 property of its containing directory, and is not relevant when
167 distributing the file across systems.
168 --fuzzy-threshold FUZZY_THRESHOLD
170 Threshold for fuzzy-matching (0 to disable, 60 is default, 400
171 is high fuzziness)
172 --tool-prefix-binutils PREFIX
174 Prefix for binutils program names, e.g. "aarch64-linux-gnu-"
175 for a foreign-arch binary or "g" if you're on a non-GNU system.
176 --max-diff-input-lines LINES
178 Maximum number of lines fed to diff(1) (0 to disable, default:
179 4194304)
180 --max-container-depth DEPTH
182 Maximum depth to recurse into containers. (Cannot be disabled
183 for security reasons, default: 50)
184 --max-diff-block-lines-saved LINES
186 Maximum number of lines saved per diff block. Most users should
187 not need this, unless you run out of memory. This truncates
188 diff(1) output before emitting it in a report, and affects all
189 types of output, including --text and --json. (0 to disable,
190 default: 0)
191 --use-dbgsym WHEN
193 When to automatically use corresponding -dbgsym packages when
194 comparing .deb files. WHEN is one of {no, auto, yes}. Default:
195 auto, meaning yes if two .changes or .buildinfo files are speci‐
196 fied, otherwise no.
197 --force-details
199 Force recursing into the depths of file formats even if files
200 have the same content, only really useful for debugging diffos‐
201 cope. Default: False
202 information commands:
204 --help, -h
205 Show this help and exit
206 --version
208 Show program's version number and exit
209 --list-tools [DISTRO]
211 Show external tools required and exit. DISTRO can be one of
212 {arch, debian, FreeBSD, guix}. If specified, the output will
213 list packages in that distribution that satisfy these dependen‐
214 cies.
215 --list-debian-substvars
217 List packages needed for Debian in 'substvar' format.
218 --list-missing-tools [DISTRO]
220 Show missing external tools and exit. DISTRO can be one of
221 {arch, debian, FreeBSD, guix}. If specified, the output will
222 list packages in that distribution that satisfy these dependen‐
223 cies.
224 file formats supported:
226 Android APK files, Android boot images, Berkeley DB
227 database files, ColorSync colour profiles (.icc), Coreboot CBFS
228 filesystem images, Dalvik .dex files, Debian .buildinfo files,
229 Debian .changes files, Debian source packages (.dsc), Device
230 Tree Compiler blob files, ELF binaries, FreeDesktop Fontconfig
231 cache files, FreePascal files (.ppu), GHC Haskell .hi files, GIF
232 image files, GNU R Rscript files (.rds), GNU R database files
233 (.rdb), GPG keybox databases, Gettext message catalogues, Git
234 repositories, Gnumeric spreadsheets, Gzipped files, ISO 9660 CD
235 images, JPEG images, JSON files, Java .class files, Java .jmod
236 modules, JavaScript files, LLVM IR bitcode files, LZ4 compressed
237 files, MacOS binaries, Microsoft Windows icon files, Microsoft
238 Word .docx files, Mono 'Portable Executable' files,
239 Mozilla-optimized .ZIP archives, Multimedia metadata, OCaml
240 interface files, Ogg Vorbis audio files, OpenOffice .odt files,
241 OpenSSH public keys, OpenWRT package archives (.ipk), PDF docu‐
242 ments, PGP signatures, PGP signed/encrypted messages, PNG
243 images, PostScript documents, Rust object files (.deflate),
244 SQLite databases, SquashFS filesystems, TrueType font files,
245 WebAssembly binary module, XML binary schemas (.xsb), XML files,
246 XZ compressed files, ZIP archives, Zstandard compressed files,
247 ar(1) archives, bzip2 archives, character/block devices, cpio
248 archives, directories, ext2/ext3/ext4/btrfs/fat filesystems,
249 symlinks, tape archives (.tar), tcpdump capture files (.pcap)
250 and text files.
251 diffoscope homepage:
253 <https://diffoscope.org/>
254 bugs/issues:
256 <https://salsa.debian.org/reproducible-builds/diffoscope/issues>
257
259 Exit status is 0 if inputs are the same, 1 if different, 2 if trouble.
260
262 To compare two files in-depth and produce an HTML report, run something
263 like:
264 $ diffoscope --html output.html build1.changes build2.changes
266 diffoscope will exit with 0 if there's no differences and 1 if there
268 are.
269 diffoscope can also compare non-existent files:
271 $ diffoscope /nonexistent archive.zip
273 To get all possible options, run:
275 $ diffoscope --help
277 If you have enough RAM, you can improve performance by running:
279 $ TMPDIR=/run/shm diffoscope very-big-input-0/ very-big-input-1/
281 By default this allowed to use up half of RAM; for more add something
283 like:
284 tmpfs /run/shm tmpfs size=80% 0 0
286 to your /etc/fstab; see man mount for details.
288
290 diffoscope requires Python 3 and the following modules available on
291 PyPI: libarchive-c, python-magic.
292 The various comparators rely on external commands being available. To
294 get a list of them, please run:
295 $ diffoscope --list-tools
297
299 Lunar, Reiner Herrmann, Chris Lamb, Mattia Rizzolo, Ximin Luo, Helmut
300 Grohne, Holger Levsen, Daniel Kahn Gillmor, Paul Gevers, Peter De
301 Wachter, Yasushi SHOJI, Clemens Lang, Ed Maste, Joachim Breitner, Mike
302 McQuaid. Baptiste Daroussin, Levente Polyak.
303
305 Please report bugs and send patches through the Debian bug tracking
306 system against the diffoscope package: <‐
307 https://bugs.debian.org/src:diffoscope>
308 For more instructions, see CONTRIBUTING.rst in this directory.
310 Join the users and developers mailing-list: <‐
312 https://lists.reproducible-builds.org/listinfo/diffoscope>
313 diffoscope website is at <https://diffoscope.org/>
315
317 diffoscope is free software: you can redistribute it and/or modify it
318 under the terms of the GNU General Public License as published by the
319 Free Software Foundation, either version 3 of the License, or (at your
320 option) any later version.
321 diffoscope is distributed in the hope that it will be useful, but WITH‐
323 OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
324 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
325 License for more details.
326 You should have received a copy of the GNU General Public License along
328 with diffoscope. If not, see <https://www.gnu.org/licenses/>.
329
331 · <https://diffoscope.org/>
332 · <https://wiki.debian.org/ReproducibleBuilds>
334diffoscope 137 March 2020 DIFFOSCOPE(1)