aboutsummaryrefslogtreecommitdiff
path: root/development/diffoscope/diffoscope.1
blob: 90fdb47848b5f530907501e1e15fccee4f012193 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
.TH DIFFOSCOPE "1" "September 2018" "diffoscope 100" "User Commands"
.SH NAME
diffoscope \- in-depth comparison of files, archives, and directories

.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.nf
\fBdiffoscope\fR \-\-help
\fBdiffoscope\fR [OPTIONS] [\-\-json \fIoutput_diff\fR] \fIpath1\fR \fIpath2\fR
\fBdiffoscope\fR [OPTIONS] \fIdiff\fR
\fBdiffoscope\fR [OPTIONS] < \fIdiff\fR
.fi
.\" Man page generated from reStructuredText.
.
.SH DESCRIPTION
.sp
diffoscope will try to get to the bottom of what makes files or
directories different. It will recursively unpack archives of many kinds
and transform various binary formats into more human readable form to
compare them. It can compare two tarballs, ISO images, or PDF just as
easily.
.sp
It can be scripted through error codes, and a report can be produced
with the detected differences. The report can be text or HTML.
When no type of report has been selected, diffoscope defaults
to write a text report on the standard output.
.sp
diffoscope was initially started by the "reproducible builds" Debian
project and now being developed as part of the (wider) \fI\%???Reproducible
Builds??? initiative\fP\&.  It is meant
to be able to quickly understand why two builds of the same package
produce different outputs. diffoscope was previously named debbindiff.
.sp
See the \fBCOMMAND\-LINE EXAMPLES\fP section further below to get you
started, as well as more detailed explanations of all the command\-line
options. The same information is also available in
\fB/usr/share/doc/diffoscope/README.rst\fP or similar.
.\" the below hack gets rid of the python "usage" message in favour of the
.\" the synopsis we manually defined in doc/$(PACKAGE).h2m.0
.SS positional arguments:
.TP
path1
First file or directory to compare. If omitted, tries
to read a diffoscope diff from stdin.
.TP
path2
Second file or directory to compare. If omitted, no
comparison is done but instead we read a diffoscope
diff from path1 and will output this in the formats
specified by the rest of the command line.
.SS "optional arguments:"
.TP
\fB\-\-debug\fR
Display debug messages
.TP
\fB\-\-debugger\fR
Open the Python debugger in case of crashes
.TP
\fB\-\-status\-fd\fR FD
Send machine\-readable status to file descriptor FD
.TP
\fB\-\-progress\fR, \fB\-\-no\-progress\fR
Show an approximate progress bar. Default: yes if
stdin is a tty, otherwise no.
.TP
\fB\-\-no\-default\-limits\fR
Disable most default output limits and diff
calculation limits.
.SS "output types:"
.TP
\fB\-\-text\fR OUTPUT_FILE
Write plain text output to given file (use \- for
stdout)
.TP
\fB\-\-text\-color\fR WHEN
When to output color diff. WHEN is one of {never,
auto, always}. Default: auto, meaning yes if the
output is a terminal, otherwise no.
.TP
\fB\-\-output\-empty\fR
If there was no difference, then output an empty diff
for each output type that was specified. In \fB\-\-text\fR
output, an empty file is written.
.TP
\fB\-\-html\fR OUTPUT_FILE
Write HTML report to given file (use \- for stdout)
.TP
\fB\-\-html\-dir\fR OUTPUT_DIR
Write multi\-file HTML report to given directory
.TP
\fB\-\-css\fR URL
Link to an extra CSS for the HTML report
.TP
\fB\-\-jquery\fR URL
URL link to jQuery, for \fB\-\-html\fR and \fB\-\-html\-dir\fR output.
If this is a non\-existent relative URL, diffoscope
will create a symlink to a system installation. (Paths
searched: \fI\,/usr/share/javascript/jquery/jquery.js\/\fP.) If
not given, \fB\-\-html\fR output will not use JS but \fB\-\-htmldir\fR will if it can be found; give "disable" to disable
JS on all outputs.
.TP
\fB\-\-json\fR OUTPUT_FILE
Write JSON text output to given file (use \- for
stdout)
.TP
\fB\-\-markdown\fR OUTPUT_FILE
Write Markdown text output to given file (use \- for
stdout)
.TP
\fB\-\-restructured\-text\fR OUTPUT_FILE
Write RsT text output to given file (use \- for stdout)
.TP
\fB\-\-profile\fR OUTPUT_FILE
Write profiling info to given file (use \- for stdout)
.SS "output limits:"
.TP
\fB\-\-max\-text\-report\-size\fR BYTES
Maximum bytes written in \fB\-\-text\fR report. (0 to disable,
default: 0)
.TP
\fB\-\-max\-report\-size\fR BYTES
Maximum bytes of a report in a given format, across
all of its pages. Note that some formats, such as
\fB\-\-html\fR, may be restricted by even smaller limits such
as \fB\-\-max\-page\-size\fR. (0 to disable, default: 41943040)
.TP
\fB\-\-max\-diff\-block\-lines\fR LINES
Maximum number of lines output per unified\-diff block,
across all pages. (0 to disable, default: 1024)
.TP
\fB\-\-max\-page\-size\fR BYTES
Maximum bytes of the top\-level (\fB\-\-html\-dir\fR) or sole
(\fB\-\-html\fR) page. (default: 409600, remains in effect
even with \fB\-\-no\-default\-limits\fR)
.TP
\fB\-\-max\-page\-size\-child\fR BYTES
In \fB\-\-html\-dir\fR output, this is the maximum bytes of
each child page (default: 204800, remains in effect
even with \fB\-\-no\-default\-limits\fR)
.TP
\fB\-\-max\-page\-diff\-block\-lines\fR LINES
Maximum number of lines output per unified\-diff block
on the top\-level (\fB\-\-html\-dir\fR) or sole (\fB\-\-html\fR) page,
before spilling it into child pages (\fB\-\-html\-dir\fR) or
skipping the rest of the diff block. Child pages are
limited instead by \fB\-\-max\-page\-size\-child\fR. (default:
128, remains in effect even with \fB\-\-no\-default\-limits\fR)
.SS "diff calculation:"
.TP
\fB\-\-new\-file\fR
Treat absent files as empty
.TP
\fB\-\-exclude\fR GLOB_PATTERN
Exclude files that match GLOB_PATTERN. Use this option
to ignore files based on their names.
.TP
\fB\-\-exclude\-command\fR REGEX_PATTERN
Exclude commands that match REGEX_PATTERN. For example
\&'^readelf.*\es\-\-debug\-dump=info' can take a long time
and differences here are likely secondary differences
caused by something represented elsewhere. Use this
option to disable commands that use a lot of
resources.
.TP
\fB\-\-exclude\-directory\-metadata\fR, \fB\-\-no\-exclude\-directory\-metadata\fR
Exclude directory metadata. Useful if comparing files
whose filesystem\-level metadata is not intended to be
distributed to other systems. This is true for most
distributions package builders, but not true for the
output of commands such as `make install`. Metadata of
archive members remain un\-excluded. Use this option to
ignore permissions, timestamps, xattrs etc. Default:
False if comparing two directories, else True. Note
that "file" metadata actually a property of its
containing directory, and is not relevant when
distributing the file across systems.
.TP
\fB\-\-fuzzy\-threshold\fR FUZZY_THRESHOLD
Threshold for fuzzy\-matching (0 to disable, 60 is
default, 400 is high fuzziness)
.TP
\fB\-\-tool\-prefix\-binutils\fR PREFIX
Prefix for binutils program names, e.g.
"aarch64\-linux\-gnu\-" for a foreign\-arch binary or "g"
if you're on a non\-GNU system.
.TP
\fB\-\-max\-diff\-input\-lines\fR LINES
Maximum number of lines fed to diff(1) (0 to disable,
default: 4194304)
.TP
\fB\-\-max\-container\-depth\fR DEPTH
Maximum depth to recurse into containers. (Cannot be
disabled for security reasons, default: 50)
.TP
\fB\-\-max\-diff\-block\-lines\-saved\fR LINES
Maximum number of lines saved per diff block. Most
users should not need this, unless you run out of
memory. This truncates diff(1) output before emitting
it in a report, and affects all types of output,
including \fB\-\-text\fR and \fB\-\-json\fR. (0 to disable, default:
0)
.TP
\fB\-\-force\-details\fR
Force recursing into the depths of file formats even
if files have the same content, only really useful for
debugging diffoscope. Default: False
.SS "information commands:"
.TP
\fB\-\-help\fR, \fB\-h\fR
Show this help and exit
.TP
\fB\-\-version\fR
Show program's version number and exit
.TP
\fB\-\-list\-tools\fR [DISTRO]
Show external tools required and exit. DISTRO can be
one of {arch, debian, FreeBSD}. If specified, the
output will list packages in that distribution that
satisfy these dependencies.
.TP
\fB\-\-list\-debian\-substvars\fR
List packages needed for Debian in 'substvar' format.
.PP
File renaming detection based on fuzzy\-matching is currently disabled. It can
be enabled by installing the "tlsh" module available at
https://github.com/trendmicro/tlsh
.SS "file formats supported:"
.IP
Android APK files, Android boot images, Berkeley DB database files, ColorSync colour profiles (.icc), Coreboot CBFS filesystem images, Dalvik .dex files, Device Tree Compiler blob files, ELF binaries, FreeDesktop Fontconfig cache files, FreePascal files (.ppu), GHC Haskell .hi files, GIF image files, GNU R Rscript files (.rds), GNU R database files (.rdb), Gettext message catalogues, Git repositories, Gnumeric spreadsheets, Gzipped files, ISO 9660 CD images, JPEG images, JSON files, Java .class files, JavaScript files, LLVM IR bitcode files, LZ4 compressed files, MacOS binaries, Microsoft Windows icon files, Microsoft Word .docx files, Mono 'Portable Executable' files, Ogg Vorbis audio files, OpenOffice .odt files, OpenSSH public keys, OpenWRT package archives (.ipk), PDF documents, PGP signed/encrypted messages, PNG images, PostScript documents, Rust object files (.deflate), SQLite databases, SquashFS filesystems, TrueType font files, XML binary schemas (.xsb), XML files, XZ compressed files, ar(1) archives, bzip2 archives, character/block devices, cpio archives, directories, ext2/ext3/ext4/btrfs filesystems, statically\-linked binaries, symlinks, tape archives (.tar), tcpdump capture files (.pcap), text files, text files, text files and text files.
.SH "EXIT STATUS"
.sp
Exit status is 0 if inputs are the same, 1 if different, 2 if trouble.
.SH "COMMAND-LINE EXAMPLES"
.sp
To compare two files in\-depth and produce an HTML report, run something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ diffoscope \-\-html output.html build1.changes build2.changes
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
diffoscope will exit with 0 if there\(aqs no differences and 1 if there
are.
.sp
\fIdiffoscope\fP can also compare non\-existent files:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ diffoscope /nonexistent archive.zip
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To get all possible options, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ diffoscope \-\-help
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you have enough RAM, you can improve performance by running:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ TMPDIR=/run/shm diffoscope very\-big\-input\-0/ very\-big\-input\-1/
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
By default this allowed to use up half of RAM; for more add something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tmpfs   /run/shm    tmpfs   size=80%    0   0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
to your \fB/etc/fstab\fP; see \fBman mount\fP for details.
.SH "EXTERNAL DEPENDENCIES"
.sp
diffoscope requires Python 3 and the following modules available on PyPI:
\fI\%libarchive\-c\fP,
\fI\%python\-magic\fP\&.
.sp
The various comparators rely on external commands being available. To
get a list of them, please run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ diffoscope \-\-list\-tools
.ft P
.fi
.UNINDENT
.UNINDENT
.SH CONTRIBUTORS
.sp
Lunar, Reiner Herrmann, Chris Lamb, Mattia Rizzolo, Ximin Luo, Helmut Grohne,
Holger Levsen, Daniel Kahn Gillmor, Paul Gevers, Peter De Wachter, Yasushi
SHOJI, Clemens Lang, Ed Maste, Joachim Breitner, Mike McQuaid. Baptiste
Daroussin, Levente Polyak.
.SH CONTACT
.sp
Please report bugs and send patches through the Debian bug tracking
system against the diffoscope package:
<\fI\%https://bugs.debian.org/src:diffoscope\fP>
.sp
For more instructions, see \fBCONTRIBUTING.rst\fP in this directory.
.sp
Join the users and developers mailing\-list:
<\fI\%https://lists.reproducible\-builds.org/listinfo/diffoscope\fP>
.sp
diffoscope website is at <\fI\%https://diffoscope.org/\fP>
.SH LICENSE
.sp
diffoscope is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
.sp
diffoscope is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
.sp
You should have received a copy of the GNU General Public License
along with diffoscope.  If not, see <\fI\%https://www.gnu.org/licenses/\fP>.
.SH "SEE ALSO"
.INDENT 0.0
.IP \(bu 2
\fI<https://diffoscope.org/>\fP
.IP \(bu 2
\fI<https://wiki.debian.org/ReproducibleBuilds>\fP
.UNINDENT
.\" Generated by docutils manpage writer.
.