图形

Graphtage 是一个命令行实用程序和底层库 ，用于在语义上比较和合并树状结构，例如 JSON、XML、HTML、YAML、plist 和 CSS 文件。它的名字是“graph”和“graftage”的组合——后者是将两棵树连接在一起的园艺实践，使它们成为一棵树。

$ echo Original: && cat original.json && echo Modified: && cat modified.json

Original:
{
    "foo": [1, 2, 3, 4],
    "bar": "testing"
}
Modified:
{
    "foo": [2, 3, 4, 5],
    "zab": "testing",
    "woo": ["foobar"]
}

$ graphtage original.json modified.json

{
    "z̟b̶ab̟r̶": "testing",
    "foo": [
        1̶,̶
        2,
        3,
        4,̟
        5̟
    ],̟
    "̟w̟o̟o̟"̟:̟ ̟[̟
        "̟f̟o̟o̟b̟a̟r̟"̟
    ]̟
}

安装

$ pip3 install graphtage

命令行用法

输出格式

Graphtage 对与输入文件的文件类型分离的树的中间表示进行分析。例如，这意味着您可以将 JSON 文件与 YAML 文件进行比较。此外，输出格式可以不同于输入格式。默认情况下，Graphtage 会将输出差异格式化为与第一个输入文件相同的文件格式。但是，例如，可以比较两个 JSON 文件并将输出格式化为 YAML。有几个命令行参数可以指定这些转换，例如--format; 请检查--help输出以获取更多信息。

默认情况下，Graphtage 会使用尽可能多的换行符和缩进来漂亮地打印其输出。

{
    "foo": [
        1,
        2,
        3
    ],
    "bar": "baz"
}

使用--join-listsor-jl选项来抑制列表项后的换行符：

{
    "foo": [1, 2, 3],
    "bar": "baz"
}

同样，使用--join-dict-itemsor-jd选项在 dict 中的键/值对之后禁止换行：

{"foo": [
    1,
    2,
    3
], "bar":  "baz"}

使用--condensed或-j应用这两个选项：

{"foo": [1, 2, 3], "bar": "baz"}

--only-editsor选项将-e打印出编辑列表，而不是将它们应用到输入文件中。

匹配选项

默认情况下，Graphtage 尝试匹配字典中所有可能的元素对。

将两个字典相互匹配是很困难的。尽管在计算上易于处理，但对于具有庞大字典的输入文件来说，这有时会很麻烦。Graphtage 具有三种不同的字典匹配策略：

1. --dict-strategy match（计算成本最高的）尝试匹配两个字典之间的所有键和值对，从而匹配最小编辑距离；
2. --dict-strategy none（计算成本最低）不会尝试匹配任何键/值对，除非它们具有完全相同的键；和
3. --dict-strategy auto（默认）将自动匹配具有相同键的任何键值对的值，然后match对其余键/值对使用该策略。

有关这些策略如何影响输出的一些示例，请参阅Pull Request #51。

--no-list-editsor选项在-l比较两个列表时不会考虑插页式插入和删除。--no-list-edits-when-same-lengthor-ll选项是一个不太激烈的版本，对于-l不同长度的列表，它的行为正常，但对于长度-l相同的列表，行为类似。

ANSI 颜色

默认情况下，如果 Graphtage 从 TTY 运行，它只会在其输出中使用 ANSI 颜色。例如，如果您想让 Graphtage 从脚本或管道发出彩色输出，请使用--coloror-c参数。即使在 TTY 上运行时也要禁用颜色，请使用--no-color.

HTML 输出

Graphtage 可以选择使用该--html选项发出 HTML 中的差异。

$ graphtage --html original.json modified.json > diff.html

状态和日志记录

默认情况下，Graphtage 将状态消息和进度条打印到 STDERR。要抑制这种情况，请使用该--no-status 选项。要另外抑制除关键日志消息之外的所有日志消息，请使用--quiet. --log-level通过该选项对日志消息进行细粒度控制。

为什么Graphtage存在？

用无序元素区分树状结构是很困难的。假设您要比较两个 JSON 文件。可用的工具有限，它们实际上等同于规范化 JSON（例如，按键排序字典元素）和执行标准差异。这并不总是足够的。例如，如果字典中的一个键发生了变化，但它的值没有变化，传统的 diff 会得出结论，整个键/值对都被新的替换了，即使唯一的变化是键本身。有关更多信息，请参阅我们的文档。

使用 Graphtage 作为库

有关更多信息，请参阅我们的文档。

扩展图形

Graphtage 设计为可扩展的：可以轻松定义新的文件类型，以及新的节点类型、编辑类型、格式化程序和打印机。有关更多信息，请参阅我们的文档。

完整的 API 文档可在此处获得。

许可和致谢

这项研究由Trail of Bits开发，部分资金来自作为Galois的分包商的 SafeDocs 计划下的国防高级研究计划局 (DARPA) 。它是根据GNU Lesser General Public License v3.0获得许可的。 如果您正在寻找条款的例外情况，请联系我们。© 2020，比特的踪迹。