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

NAME

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

SYNOPSIS

10       diffoscope --help
11       diffoscope [OPTIONS] [--json output_diff] path1 path2
12       diffoscope [OPTIONS] diff
13       diffoscope [OPTIONS] < diff
14

DESCRIPTION

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

EXIT STATUS

268       Exit status is 0 if inputs are the same, 1 if different, 2 if trouble.
269

COMMAND-LINE EXAMPLES

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

EXTERNAL DEPENDENCIES

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

CONTRIBUTORS

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

CONTACT

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

LICENSE

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

SEE ALSO

341       · <https://diffoscope.org/>
342
343       · <https://wiki.debian.org/ReproducibleBuilds>
344
345
346
347
348diffoscope 166                   February 2021                   DIFFOSCOPE(1)
Impressum