README.rst
1xmldiff
2========
3
4.. image:: https://travis-ci.org/Shoobx/xmldiff.svg?branch=master
5 :target: https://travis-ci.org/Shoobx/xmldiff
6
7.. image:: https://coveralls.io/repos/github/Shoobx/xmldiff/badge.svg
8 :target: https://coveralls.io/github/Shoobx/xmldiff
9
10``xmldiff`` is a library and a command-line utility for making diffs out of XML.
11This may seem like something that doesn't need a dedicated utility,
12but change detection in hierarchical data is very different from change detection in flat data.
13XML type formats are also not only used for computer readable data,
14it is also often used as a format for hierarchical data that can be rendered into human readable formats.
15A traditional diff on such a format would tell you line by line the differences,
16but this would not be be readable by a human.
17``xmldiff`` provides tools to make human readable diffs in those situations.
18
19Full documentation is on `xmldiff.readthedocs.io <https://xmldiff.readthedocs.io>`_
20
21``xmldiff`` is still under rapid development,
22and no guarantees are done that the output of one version will be the same as the output of any previous version.
23
24
25Quick usage
26-----------
27
28``xmldiff`` is both a command-line tool and a Python library.
29To use it from the command-line, just run ``xmldiff`` with two input files::
30
31 $ xmldiff file1.xml file2.xml
32
33There is also a command to patch a file with the output from the ``xmldiff`` command::
34
35 $ xmlpatch file.diff file1.xml
36
37There is a simple API for using ``xmldiff`` as a library::
38
39 from lxml import etree
40 from xmldiff import main, formatting
41
42 diff = main.diff_files('file1.xml', 'file2.xml',
43 formatter=formatting.XMLFormatter())
44
45There is also a method ``diff_trees()`` that take two lxml trees,
46and a method ``diff_texts()`` that will take strings containing XML.
47Similarly, there is ``patch_file()`` ``patch_text()`` and ``patch_tree()``::
48
49 result = main.patch_file('file.diff', 'file1.xml')
50
51
52Changes from ``xmldiff`` 0.6/1.x
53--------------------------------
54
55 * A complete, ground up, pure-Python rewrite
56
57 * Easier to maintain, the code is less complex and more Pythonic,
58 and uses more custom classes instead of just nesting lists and dicts.
59
60 * Fixes the problems with certain large files and solves the memory leaks.
61
62 * A nice, easy to use Python API for using it as a library.
63
64 * Adds support for showing the diffs in different formats,
65 mainly one where differences are marked up in the XML,
66 useful for making human readable diffs.
67
68 These formats can show text differences in a semantically meaningful way.
69
70 * An output format compatible with 0.6/1.x is also available.
71
72 * 2.0 is currently significantly slower than ``xmldiff`` 0.6/1.x,
73 but this will change in the future.
74 Currently we make no effort to make ``xmldiff`` 2.0 fast,
75 we concentrate on making it correct and usable.
76
77
78Contributors
79------------
80
81 * Lennart Regebro, regebro@gmail.com (main author)
82
83 * Stephan Richter, srichter@shoobx.com
84
85 * Albertas Agejevas, alga@shoobx.com
86
87The diff algorithm is based on "`Change Detection in Hierarchically Structured Information <http://ilpubs.stanford.edu/115/1/1995-46.pdf>`_",
88and the text diff is using Google's ``diff_match_patch`` algorithm.
89
