diff options
Diffstat (limited to 'development/diffoscope/diffoscope.1')
| -rw-r--r-- | development/diffoscope/diffoscope.1 | 358 |
1 files changed, 315 insertions, 43 deletions
diff --git a/development/diffoscope/diffoscope.1 b/development/diffoscope/diffoscope.1 index a816cd5171df4..cb97fb0f778d4 100644 --- a/development/diffoscope/diffoscope.1 +++ b/development/diffoscope/diffoscope.1 @@ -1,8 +1,8 @@ -.\" Man page generated from reStructuredText. -. -.TH DIFFOSCOPE 1 "" "" "Debian" +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.6. +.TH DIFFOSCOPE "1" "May 2018" "diffoscope 95" "User Commands" .SH NAME diffoscope \- in-depth comparison of files, archives, and directories + . .nr rst2man-indent-level 0 . @@ -31,11 +31,14 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH SYNOPSIS -.INDENT 0.0 -.INDENT 3.5 -diffoscope [\-h] [\-\-version] [\-\-debug] [\-\-html output] [\-\-text output] [\-\-max\-report\-size bytes] [\-\-css url] file1 file2 -.UNINDENT -.UNINDENT +.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 @@ -49,60 +52,329 @@ 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 is developed as part of the “reproducible builds” Debian -project and was formerly known as “debbindiff”. -.SH OPTIONS -.INDENT 0.0 +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 -.B \-h\fP,\fB \-\-help -show this help message and exit +\fB\-\-css\fR URL +Link to an extra CSS for the HTML report .TP -.B \-\-version -show program\(aqs version number and exit +\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 -.B \-\-debug -display debug messages +\fB\-\-json\fR OUTPUT_FILE +Write JSON text output to given file (use \- for +stdout) .TP -.BI \-\-html \ output -write HTML report to given file -(use \- for standard output) +\fB\-\-markdown\fR OUTPUT_FILE +Write Markdown text output to given file (use \- for +stdout) .TP -.BI \-\-text \ output -write plain text report to given file -(use \- for standard output) +\fB\-\-restructured\-text\fR OUTPUT_FILE +Write RsT text output to given file (use \- for stdout) .TP -.BI \-\-max\-report\-size \ BYTES -maximum bytes written in report (default: 2048000) +\fB\-\-profile\fR OUTPUT_FILE +Write profiling info to given file (use \- for stdout) +.SS "output limits:" .TP -.BI \-\-max\-diff\-block\-lines \ MAX_DIFF_BLOCK_LINES -maximum number of lines per diff block (default: 50) +\fB\-\-max\-text\-report\-size\fR BYTES +Maximum bytes written in \fB\-\-text\fR report. (0 to disable, +default: 0) .TP -.BI \-\-max\-diff\-input\-lines \ MAX_DIFF_INPUT_LINES -maximum number of lines fed to diff (default: 100000) +\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 -.BI \-\-fuzzy\-threshold \ FUZZY_THRESHOLD -threshold for fuzzy\-matching (0 to disable, 60 is +\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 -.B \-\-new\-file -treat absent files as empty +\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 -.BI \-\-css \ url -link to an extra CSS for the HTML report -.UNINDENT -.SH EXIT STATUS +\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. +.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, Debian .buildinfo files, Debian .changes files, Debian source packages (.dsc), 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, 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, RPM archives, 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) and text files. +.SH "EXIT STATUS" .sp Exit status is 0 if inputs are the same, 1 if different, 2 if trouble. -.SH SEE ALSO +.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 -.SH AUTHOR -Debian "Reproducible Builds" Team -.SH COPYRIGHT -GPL-3+ .\" Generated by docutils manpage writer. . |