README.rst
1diffoscope
2==========
3
4.. image:: https://badge.fury.io/py/diffoscope.svg
5 :target: http://badge.fury.io/py/diffoscope
6
7.. image:: https://jenkins.debian.net/buildStatus/icon?job=reproducible_diffoscope_from_git_master&plastic=true
8 :target: https://jenkins.debian.net/job/reproducible_diffoscope_from_git
9
10diffoscope will try to get to the bottom of what makes files or
11directories different. It will recursively unpack archives of many kinds
12and transform various binary formats into more human-readable form to
13compare them. It can compare two tarballs, ISO images, or PDF just as
14easily.
15
16It can be scripted through error codes, and a report can be produced
17with the detected differences. The report can be text or HTML.
18When no type of report has been selected, diffoscope defaults
19to write a text report on the standard output.
20
21diffoscope was initially started by the "reproducible builds" Debian
22project and now being developed as part of the (wider) `“Reproducible
23Builds” initiative <https://reproducible-builds.org>`_. It is meant
24to be able to quickly understand why two builds of the same package
25produce different outputs. diffoscope was previously named debbindiff.
26
27See the ``COMMAND-LINE EXAMPLES`` section further below to get you
28started, as well as more detailed explanations of all the command-line
29options. The same information is also available in
30``/usr/share/doc/diffoscope/README.rst`` or similar.
31
32.. the below hack gets rid of the python "usage" message in favour of the the
33 synopsis we manually defined in doc/$(PACKAGE).h2m.0
34 .SS positional arguments:
35 .\" end_of_description_header
36
37Exit status
38===========
39
40Exit status is 0 if inputs are the same, 1 if different, 2 if trouble.
41
42Command-line examples
43=====================
44
45To compare two files in-depth and produce an HTML report, run something like::
46
47 $ bin/diffoscope --html output.html build1.changes build2.changes
48
49diffoscope will exit with 0 if there's no differences and 1 if there
50are.
51
52To get all possible options, run::
53
54 $ bin/diffoscope --help
55
56If you have enough RAM, you can improve performance by running::
57
58 $ TMPDIR=/run/shm bin/diffoscope very-big-input-0/ very-big-input-1/
59
60By default this allowed to use up half of RAM; for more add something like::
61
62 tmpfs /run/shm tmpfs size=80% 0 0
63
64to your ``/etc/fstab``; see ``man mount`` for details.
65
66External dependencies
67=====================
68
69diffoscope requires Python 3 and the following modules available on PyPI:
70`libarchive-c <https://pypi.python.org/pypi/libarchive-c>`_,
71`python-magic <https://pypi.python.org/pypi/python-magic>`_.
72
73The various comparators rely on external commands being available. To
74get a list of them, please run::
75
76 $ bin/diffoscope --list-tools
77
78Contributors
79============
80
81Lunar, Reiner Herrmann, Chris Lamb, Mattia Rizzolo, Ximin Luo, Helmut Grohne,
82Holger Levsen, Daniel Kahn Gillmor, Paul Gevers, Peter De Wachter, Yasushi
83SHOJI, Clemens Lang, Ed Maste, Joachim Breitner, Mike McQuaid. Baptiste
84Daroussin, Levente Polyak.
85
86Contact
87=======
88
89The preferred way to report bugs about *diffoscope*, as well as suggest
90fixes and requests for improvements is to submit reports to the issue
91tracker at:
92
93 https://salsa.debian.org/reproducible-builds/diffoscope/issues
94
95For more instructions, see ``CONTRIBUTING.rst`` in this directory.
96
97Join the users and developers mailing-list:
98<https://lists.reproducible-builds.org/listinfo/diffoscope>
99
100diffoscope website is at <https://diffoscope.org/>
101
102License
103=======
104
105diffoscope is free software: you can redistribute it and/or modify
106it under the terms of the GNU General Public License as published by
107the Free Software Foundation, either version 3 of the License, or
108(at your option) any later version.
109
110diffoscope is distributed in the hope that it will be useful,
111but WITHOUT ANY WARRANTY; without even the implied warranty of
112MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
113GNU General Public License for more details.
114
115You should have received a copy of the GNU General Public License
116along with diffoscope. If not, see <https://www.gnu.org/licenses/>.
117
118See also
119========
120
121* `<https://diffoscope.org/>`
122* `<https://wiki.debian.org/ReproducibleBuilds>`
123
