1DIFFOSCOPE(1)                    User Commands                   DIFFOSCOPE(1)
2
3
4

NAME

6       diffoscope - in-depth comparison of files, archives, and directories
7

SYNOPSIS

9       diffoscope --help
10       diffoscope [OPTIONS] [--json output_diff] path1 path2
11       diffoscope [OPTIONS] diff
12       diffoscope [OPTIONS] < diff
13
14
15
16()                                                                          ()
17
18
19

DESCRIPTION

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
27       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
32       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
38       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
43       path1  First file or directory to compare.
44
45       path2  Second file or directory to compare.
46
47   options:
48       --debug
49              Display debug messages
50
51       --pdb  Open the Python pdb debugger in case of crashes
52
53       --status-fd FD
54              Send machine-readable status to file descriptor FD
55
56       --progress, --no-progress
57              Show  an  approximate  progress  bar. Default: yes if stdin is a
58              tty, otherwise no.
59
60       --no-default-limits
61              Disable most default output limits and diff calculation limits.
62
63       --load-existing-diff INPUT_FILE
64              Load existing diff from file. Specify "-" to read  a  diffoscope
65              diff from stdin.
66
67   output types:
68       --text OUTPUT_FILE
69              Write plain text output to given file (use - for stdout)
70
71       --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
76       --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
81       --html OUTPUT_FILE
82              Write HTML report to given file (use - for stdout)
83
84       --html-dir OUTPUT_DIR
85              Write multi-file HTML report to given directory
86
87       --css URL
88              Link to an extra CSS for the HTML report
89
90       --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
98       --json OUTPUT_FILE
99              Write JSON text output to given file (use - for stdout)
100
101       --markdown OUTPUT_FILE
102              Write Markdown text output to given file (use - for stdout)
103
104       --restructured-text OUTPUT_FILE
105              Write RsT text output to given file (use - for stdout)
106
107       --difftool TOOL
108              Compare differences one-by-one using the specified external com‐
109              mand similar to git-difftool(1)
110
111       --profile [OUTPUT_FILE]
112              Write profiling info to given file (use - for stdout)
113
114   output limits:
115       --diff-context LINES
116              Lines of unified diff context to show. (default: 7)
117
118       --max-text-report-size BYTES
119              Maximum  bytes written in --text report. (0 to disable, default:
120              0)
121
122       --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
128       --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
132       --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
137       --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
144   diff calculation:
145       --new-file
146              Treat absent files as empty
147
148       --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
153       --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
160       --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
172       --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
177       --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
182       --fuzzy-threshold FUZZY_THRESHOLD
183              Threshold  for fuzzy-matching (0 to disable, 110 is default, 400
184              is high fuzziness)
185
186       --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
190       --max-diff-input-lines LINES
191              Maximum  number  of lines fed to diff(1) (0 to disable, default:
192              4194304)
193
194       --max-container-depth DEPTH
195              Maximum depth to recurse into containers.  (Cannot  be  disabled
196              for security reasons, default: 50)
197
198       --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
204       --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
211       --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
217       --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
222   information commands:
223       --help, -h
224              Show this help and exit
225
226       --version
227              Show program's version number and exit
228
229       --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
235       --list-debian-substvars
236              List packages needed for Debian in 'substvar' format.
237
238       --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
244   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,  ISO
258              9660  CD  images,  Java  .class files, Java .jmod modules, Java‐
259              Script files, JPEG images, JSON files, Linux kernel images, LLVM
260              IR  bitcode  files,  local (UNIX domain) sockets and named pipes
261              (FIFOs), LZ4 compressed files, macOS binaries, Microsoft Windows
262              icon  files,  Microsoft  Word  .docx  files, Mono 'Portable Exe‐
263              cutable'  files,  Mozilla-optimized  .ZIP  archives,  Multimedia
264              metadata,  OCaml  interface files, Ogg Vorbis audio files, Open‐
265              Office .odt files, OpenSSH public keys, OpenWRT package archives
266              (.ipk),   PDF   documents,   PE32  files,  PGP  signatures,  PGP
267              signed/encrypted messages,  PNG  images,  PostScript  documents,
268              Public  Key  Cryptography  Standards  (PKCS) files (version #7),
269              Python .pyc files, RPM archives, Rust object  files  (.deflate),
270              Sphinx  inventory files, SQLite databases, SquashFS filesystems,
271              symlinks, tape archives (.tar), tcpdump capture  files  (.pcap),
272              text  files, TrueType font files, U-Boot legacy image files, We‐
273              bAssembly binary module, XML binary schemas (.xsb),  XML  files,
274              XMLB files, XZ compressed files, ZIP archives and Zstandard com‐
275              pressed files.
276
277   diffoscope homepage:
278              <https://diffoscope.org/>
279
280   bugs/issues:
281              <https://salsa.debian.org/reproducible-builds/diffoscope/issues>
282

EXIT STATUS

284       Exit status is 0 if inputs are the same, 1 if different, 2 if trouble.
285

COMMAND-LINE EXAMPLES

287       To compare two files in-depth and produce an HTML report, run something
288       like:
289
290          $ diffoscope --html output.html build1.changes build2.changes
291
292       diffoscope  will  exit  with 0 if there's no differences and 1 if there
293       are.
294
295       To get all possible options, run:
296
297          $ diffoscope --help
298
299       If you have enough RAM, you can improve performance by running:
300
301          $ TMPDIR=/run/shm diffoscope very-big-input-0/ very-big-input-1/
302
303       By default this allowed to use up half of RAM; for more  add  something
304       like:
305
306          tmpfs   /run/shm    tmpfs   size=80%    0   0
307
308       to your /etc/fstab; see man mount for details.
309

EXTERNAL DEPENDENCIES

311       diffoscope  requires  Python  3  and the following modules available on
312       PyPI: libarchive-c, python-magic.
313
314       The various comparators rely on external commands being  available.  To
315       get a list of them, please run:
316
317          $ diffoscope --list-tools
318

CONTRIBUTORS

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

CONTACT

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
331       For more instructions, see CONTRIBUTING.rst in this directory.
332
333       Join     the     users     and     developers     mailing-list:      <‐
334       https://lists.reproducible-builds.org/listinfo/diffoscope>
335
336       diffoscope website is at <https://diffoscope.org/>
337

LICENSE

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
344       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
349       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

SEE ALSO

353<https://diffoscope.org/>
354
355<https://wiki.debian.org/ReproducibleBuilds>
356
357
358
359
360                                                                            ()
Impressum