README.rst 4.23 KB
Newer Older
1 2
diffoscope
==========
Jérémy Bobbio's avatar
Jérémy Bobbio committed
3

4
.. only:: not manpage
5

6 7 8 9 10
   .. image:: https://badge.fury.io/py/diffoscope.svg
       :target: http://badge.fury.io/py/diffoscope

   .. image:: https://jenkins.debian.net/buildStatus/icon?job=reproducible_diffoscope_from_git_master&plastic=true
      :target: https://jenkins.debian.net/job/reproducible_diffoscope_from_git_master
11

Jérémy Bobbio's avatar
Jérémy Bobbio committed
12 13 14 15 16
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.
Jérémy Bobbio's avatar
Jérémy Bobbio committed
17

Jérémy Bobbio's avatar
Jérémy Bobbio committed
18 19 20 21 22
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.

23 24 25 26 27
diffoscope was initially started by the "reproducible builds" Debian
project and now being developed as part of the (wider) `“Reproducible
Builds” initiative <https://reproducible-builds.org>`_.  It is meant
to be able to quickly understand why two builds of the same package
produce different outputs. diffoscope was previously named debbindiff.
Jérémy Bobbio's avatar
Jérémy Bobbio committed
28

29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
See the ``COMMAND-LINE EXAMPLES`` 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
``/usr/share/doc/diffoscope/README.rst`` or similar.

.. raw:: manpage

   .\" 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:
   .\" end_of_description_header

Exit status
===========

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

Command-line examples
=====================
Jérémy Bobbio's avatar
Jérémy Bobbio committed
48

49 50
To compare two files in-depth and produce an HTML report, run something like::

51
    $ bin/diffoscope --html output.html build1.changes build2.changes
Jérémy Bobbio's avatar
Jérémy Bobbio committed
52

53 54 55
diffoscope will exit with 0 if there's no differences and 1 if there
are.

56 57 58 59 60 61 62
*diffoscope* can also compare non-existent files::

    $ bin/diffoscope /nonexistent archive.zip

To get all possible options, run::

    $ bin/diffoscope --help
Jérémy Bobbio's avatar
Jérémy Bobbio committed
63

64 65 66 67 68 69 70 71 72 73
If you have enough RAM, you can improve performance by running::

    $ TMPDIR=/run/shm bin/diffoscope very-big-input-0/ very-big-input-1/

By default this allowed to use up half of RAM; for more add something like::

    tmpfs   /run/shm    tmpfs   size=80%    0   0

to your ``/etc/fstab``; see ``man mount`` for details.

74
External dependencies
75
=====================
76

77 78
diffoscope requires Python 3 and the following modules available on PyPI:
`libarchive-c <https://pypi.python.org/pypi/libarchive-c>`_,
Jérémy Bobbio's avatar
Jérémy Bobbio committed
79
`python-magic <https://pypi.python.org/pypi/python-magic>`_.
80

81
The various comparators rely on external commands being available. To
82
get a list of them, please run::
83

84
    $ bin/diffoscope --list-tools
85

Jérémy Bobbio's avatar
Jérémy Bobbio committed
86
Contributors
87
============
Jérémy Bobbio's avatar
Jérémy Bobbio committed
88

89 90 91 92
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.
Jérémy Bobbio's avatar
Jérémy Bobbio committed
93

94
Contact
95
=======
96 97 98 99 100

Please report bugs and send patches through the Debian bug tracking
system against the diffoscope package:
<https://bugs.debian.org/src:diffoscope>

101 102
For more instructions, see ``CONTRIBUTING.rst`` in this directory.

103 104 105
Join the users and developers mailing-list:
<https://lists.reproducible-builds.org/listinfo/diffoscope>

106
diffoscope website is at <https://diffoscope.org/>
107

Jérémy Bobbio's avatar
Jérémy Bobbio committed
108
License
109
=======
Jérémy Bobbio's avatar
Jérémy Bobbio committed
110

Jérémy Bobbio's avatar
Jérémy Bobbio committed
111
diffoscope is free software: you can redistribute it and/or modify
Jérémy Bobbio's avatar
Jérémy Bobbio committed
112 113 114 115
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.

Jérémy Bobbio's avatar
Jérémy Bobbio committed
116
diffoscope is distributed in the hope that it will be useful,
Jérémy Bobbio's avatar
Jérémy Bobbio committed
117 118 119 120 121
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.

You should have received a copy of the GNU General Public License
122
along with diffoscope.  If not, see <https://www.gnu.org/licenses/>.
123 124 125 126 127 128

See also
========

* `<https://diffoscope.org/>`
* `<https://wiki.debian.org/ReproducibleBuilds>`