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   positional arguments:
39       path1  First  file or directory to compare. If omitted, tries to read a
40              diffoscope diff from stdin.
41
42       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
47   optional arguments:
48       --debug
49              Display debug messages
50
51       --debugger
52              Open the Python debugger in case of crashes
53
54       --status-fd FD
55              Send machine-readable status to file descriptor FD
56
57       --progress, --no-progress
58              Show  an  approximate  progress  bar. Default: yes if stdin is a
59              tty, otherwise no.
60
61       --no-default-limits
62              Disable most default output limits and diff calculation limits.
63
64   output types:
65       --text OUTPUT_FILE
66              Write plain text output to given file (use - for stdout)
67
68       --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
73       --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
78       --html OUTPUT_FILE
79              Write HTML report to given file (use - for stdout)
80
81       --html-dir OUTPUT_DIR
82              Write multi-file HTML report to given directory
83
84       --css URL
85              Link to an extra CSS for the HTML report
86
87       --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
95       --json OUTPUT_FILE
96              Write JSON text output to given file (use - for stdout)
97
98       --markdown OUTPUT_FILE
99              Write Markdown text output to given file (use - for stdout)
100
101       --restructured-text OUTPUT_FILE
102              Write RsT text output to given file (use - for stdout)
103
104       --profile OUTPUT_FILE
105              Write profiling info to given file (use - for stdout)
106
107   output limits:
108       --max-text-report-size BYTES
109              Maximum  bytes written in --text report. (0 to disable, default:
110              0)
111
112       --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
118       --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
122       --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
127       --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
132       --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
139   diff calculation:
140       --new-file
141              Treat absent files as empty
142
143       --exclude GLOB_PATTERN
144              Exclude files that match GLOB_PATTERN. Use this option to ignore
145              files based on their names.
146
147       --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
154       --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
166       --fuzzy-threshold FUZZY_THRESHOLD
167              Threshold for fuzzy-matching (0 to disable, 60 is  default,  400
168              is high fuzziness)
169
170       --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
174       --max-diff-input-lines LINES
175              Maximum number of lines fed to diff(1) (0 to  disable,  default:
176              4194304)
177
178       --max-container-depth DEPTH
179              Maximum  depth  to  recurse into containers. (Cannot be disabled
180              for security reasons, default: 50)
181
182       --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
189       --use-dbgsym
190              Automatically use corresponding -dbgsym  packageswhen  comparing
191              .deb files. (default: False)
192
193       --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
198   information commands:
199       --help, -h
200              Show this help and exit
201
202       --version
203              Show program's version number and exit
204
205       --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
210       --list-debian-substvars
211              List packages needed for Debian in 'substvar' format.
212
213       --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
218       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
222   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

EXIT STATUS

248       Exit status is 0 if inputs are the same, 1 if different, 2 if trouble.
249

COMMAND-LINE EXAMPLES

251       To compare two files in-depth and produce an HTML report, run something
252       like:
253
254          $ diffoscope --html output.html build1.changes build2.changes
255
256       diffoscope will exit with 0 if there's no differences and  1  if  there
257       are.
258
259       diffoscope can also compare non-existent files:
260
261          $ diffoscope /nonexistent archive.zip
262
263       To get all possible options, run:
264
265          $ diffoscope --help
266
267       If you have enough RAM, you can improve performance by running:
268
269          $ TMPDIR=/run/shm diffoscope very-big-input-0/ very-big-input-1/
270
271       By  default  this allowed to use up half of RAM; for more add something
272       like:
273
274          tmpfs   /run/shm    tmpfs   size=80%    0   0
275
276       to your /etc/fstab; see man mount for details.
277

EXTERNAL DEPENDENCIES

279       diffoscope requires Python 3 and the  following  modules  available  on
280       PyPI: libarchive-c, python-magic.
281
282       The  various  comparators rely on external commands being available. To
283       get a list of them, please run:
284
285          $ diffoscope --list-tools
286

CONTRIBUTORS

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

CONTACT

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
298       For more instructions, see CONTRIBUTING.rst in this directory.
299
300       Join      the     users     and     developers     mailing-list:     <‐
301       https://lists.reproducible-builds.org/listinfo/diffoscope>
302
303       diffoscope website is at <https://diffoscope.org/>
304

LICENSE

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
311       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
316       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

SEE ALSO

320       · <https://diffoscope.org/>
321
322       · <https://wiki.debian.org/ReproducibleBuilds>
323
324
325
326
327diffoscope 111                   February 2019                   DIFFOSCOPE(1)
Impressum