Graphtage

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将以第一个输入文件的相同文件格式格式化输出diff。但例如，可以比较两个JSON文件并将输出格式化为YAML。有多个命令行参数可以指定这些转换，例如--format；请查看--help输出以获取更多信息。

默认情况下，Graphtage尽可能使用尽可能多的换行符和缩进进行美化打印。

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

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

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

同样，使用--join-dict-items或-jd选项来抑制字典中键/值对后的换行符

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

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

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

--only-edits或-e选项将打印出编辑列表而不是将编辑应用到输入文件中

--edit-digest或-d选项类似于--only-edits，但为每个编辑打印出更简洁的上下文，更易于人类阅读。

匹配选项

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

匹配两个字典是困难的。尽管在计算上是可处理的，但这有时对于具有巨大字典的输入文件来说可能是繁重的。Graphtage有三种不同的策略来匹配字典

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

请参阅拉取请求#51以了解这些策略如何影响输出。

--no-list-edits或-l选项在比较两个列表时不会考虑中间插入和删除。 --no-list-edits-when-same-length或-ll选项是-l的一个较不激进版本，对于长度不同的列表将正常行为，但对于长度相同的列表则行为类似于-l。

ANSI颜色

默认情况下，如果从TTY运行，Graphtage将仅在输出中使用ANSI颜色。例如，如果您希望从脚本或管道中发出Graphtage的颜色化输出，请使用--color或-c参数。要禁用颜色，即使在TTY上运行，也请使用--no-color。

HTML输出

使用--html选项，Graphtage可以可选地以HTML格式输出diff。

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

状态和日志

默认情况下，Graphtage将状态消息和进度条打印到STDERR。要抑制此操作，请使用--no-status选项。要进一步抑制除关键日志消息之外的所有日志消息，请使用--quiet。通过--log-level选项进行日志消息的精细控制。

为什么Graphtage存在？

比较具有无序元素的树形结构很困难。例如，如果您想比较两个JSON文件，可用的工具有限，实际上等同于规范化JSON（例如，按键对字典元素进行排序）然后执行标准diff。这并不总是足够的。例如，如果字典中的一个键已更改但它的值没有，传统的diff将得出结论，整个键/值对被新的一个替换，尽管唯一的变化只是键本身。有关更多信息，请参阅我们的文档。

将Graphtage用作库

Graphtage 提供了一套完整的 API，可以用于程序化操作其比较功能。当将 Graphtage 作为库使用时，它还可以比较内存中的 Python 对象。这可以用于调试 Python 代码，例如，确定两个对象之间的差异。更多信息请参阅我们的文档。

扩展 Graphtage

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

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

许可和致谢

这项研究由 Trail of Bits 开发，部分资金来自国防高级研究计划局（DARPA）的 SafeDocs 计划，作为 Galois 的分包商。它许可在GNU Lesser General Public License v3.0下。如需对条款的例外情况，请联系我们联系我们。© 2020–2023，Trail of Bits。