比较两个版本改了什么,不修改文件,不依赖 Git。直接在 Autos 中 return 结果表:
import textkit.diff;
return textkit.diff.files(oldPath, newPath);
已有文本字符串时,调用 textkit.diff(oldText, newText, options?);文件路径只传给 textkit.diff.files(oldPath, newPath, options?)。以下两个例子也说明如何指定选项:
import textkit.diff;
// 内存文本,只看变动行。
return textkit.diff('var x = 1;\n', 'var x = 2;\n', {context=0});
import textkit.diff;
// 比较打 Aider 补丁之前的备份和当前文件,生成 Unified Diff。
var r = textkit.diff.files(oldPath, newPath, {format="unified"; label="src/main.aardio"});
if(r.error) return r;
// 原样保存,以免编辑器把补丁行尾全部转换为 CRLF。
if(#r.diff) string.save("/change.patch", r.diff);
return r.summary;
options 字段 |
用途 |
|---|---|
format |
"autos"(默认)用于查看;"unified" 用于生成标准补丁。 |
context |
每侧上下文行数,默认 3。0 只显示改动。上下文相交或相接时合并块。 |
maxBytes |
可选的 diff 字节预算。Autos 默认 8000,超出则截断,0 只看统计。Unified 默认不截断;显式设置预算且不足时返回 error,不会返回半个补丁。 |
label |
仅用于 Unified。目标相对路径,如 "src/main.aardio",分隔符用 /。两边的表头分别为 a/<label>、b/<label>。省略时 .files 用新文件的文件名,无目录;内存文本用 text。 |
@@ -120,3 +120,4 @@
120|var a = 1;
-var b = 2;
121+var b = 20;
122+var c = 30;
123|return a + b;
| 是不变行,+ 是新增行,- 是删除行。行号从 1 起,只对应第二个输入;要看旧文件行号,交换两参数。删除行用空格对齐,不显示行号。修饰符和正文之间没有额外空格。
预览把 CRLF、LF 和 CR 都视为换行,不因换行符种类不同而重复显示整份文件。末尾有没有换行仍然算差异。 单行正文最多显示 240 个字节,安全截在 UTF-8 字符边界;替换时尽量保留第一个差异附近。任意裁剪都会设置 truncated=true,但统计不受预览预算影响。这个格式不能用来打补丁。
标准 ---、+++ 文件头和 @@ 变更块。按 LF 分隔补丁记录,逐字节保留输入行里的 CR,没有末尾 LF 时写标准的 \ No newline at end of file 标记。只改变行尾也会生成补丁。没有差异时返回 ""。用 context=0 时,git apply 需要 --unidiff-zero。
.files 的 Unified 补丁针对去掉 BOM、解码后的 UTF-8 文本,不描述编码或 BOM 的变化,不用于直接修改带 BOM 的原始文件。它比较的是同一目标的两个版本,不生成重命名或文件权限变更。
始终只返回一个表。失败有 error 和 code;文件读取或解码失败时,还可用 side("old" / "new")和 path 定位输入。成功没有 error,常用字段如下:
| 字段 | 含义 |
|---|---|
diff |
所选格式的差异文本。为空也可能是仅编码/换行样式变化,或预览预算为零。 |
summary |
简短摘要。 |
identical |
原输入字节是否完全一致(包括 BOM、换行符)。 |
contentIdentical |
解码后,忽略换行符种类,正文是否一致(末尾有无换行仍比较)。 |
added、removed、hunks |
所选格式的新增行数、删除行数和完整块数。 |
有对应情况才返回额外字段:
charset:文件有明确 BOM 时识别 utf-8-sig、utf-16(小端)、utf-16be(大端),转为 UTF-8。按 旧->新 报告,如 "utf-8->utf-16be"。两文件都没有 BOM 时按 UTF-8 读,不返回此字段;无编码参数,不猜测 ANSI。eol:换行样式摘要,如 "CRLF->LF";当正文相同、两侧都是混合换行且分布变化时,报告 "mixed->mixed"。none 表示没有换行符。trailingNewline:"added" 或 "removed",表示文件末尾换行的有无变化。truncated:Autos 预览有裁剪,不代表算法只计算了部分文件。approximate:差异太大或重复行太多,部分对齐退化为整块替换。操作仍能准确地从旧文本变成新文本;不保证最少增删行。输入必须是有效文本(拒绝 NUL、非法 UTF-8 及畸形 UTF-16)。每个输入最多 16 MiB(原始字节及解码后),需要计算行差异时每侧最多 250,000 行。适合对比同一文件的版本,不支持二进制或目录。