通过 tree-sitter 理解代码结构，解决 Git 无法处理的合并冲突。

问题所在

Git 是基于 行 来进行合并的。当两个分支同时向同一文件添加代码——即使是在完全不同的函数中——Git 会检测到行范围重叠，并标记为冲突：

<<<<<<< HEAD
export function validateToken(token: string): boolean {
    return token.length > 0 && token.startsWith("sk-");
}
=======
export function formatDate(date: Date): string {
    return date.toISOString().split('T')[0];
}
>>>>>>> feature-branch

这些其实是 完全独立的更改，并不存在真正的冲突。然而，仍然需要人工介入来解决这个问题。

这种情况在多个 AI 代理共同协作开发同一代码库时尤为常见：代理 A 添加了一个函数，代理 B 又在同一文件中添加了另一个不同的函数，结果 Git 就会暂停合并流程，等待人工干预。

Weave 如何解决这一问题

Weave 用 实体级合并 替代了 Git 的基于行的合并方式。它不再逐行对比差异，而是：

1. 使用 tree-sitter 将三个版本（基准、我们的、他们的）解析为语义实体——如函数、类、JSON 键等；
2. 通过实体的标识（名称 + 类型 + 作用域）匹配不同版本中的对应实体；
3. 在实体级别进行合并：
   • 如果是 不同实体被修改，则自动解决，无冲突；
   • 如果是 同一实体被双方修改，则尝试在实体内部进行合并，只有真正不兼容时才会产生冲突；
   • 如果一方修改而另一方删除了该实体，则会标记为有意义的冲突。

以刚才的例子为例，Weave 能够干净地完成合并，无需任何冲突处理——最终输出中会同时包含这两个函数。

Weave 与 Git 合并对比

场景	Git（基于行）	Weave（基于实体）
两个代理向同一文件添加不同函数	冲突	自动解决
代理 A 修改 foo()，代理 B 添加 bar()	冲突（相邻行）	自动解决
两代理分别以不同方式修改同一个函数	冲突	冲突（结合实体上下文）
一方修改，另一方删除同一函数	冲突（难以理解的差异）	冲突：function 'validateToken' (modified in ours, deleted in theirs)
两代理添加完全相同的函数	冲突	自动解决（检测到内容相同）
两代理向同一对象添加不同属性	冲突	自动解决
不同 JSON 键被修改	冲突	自动解决

关键区别在于：Git 会对 独立的更改 产生误报冲突，仅仅因为这些更改发生在同一文件中。而 Weave 只会在两个分支对同一实体进行了 不兼容的修改 时才会产生真正的冲突。

Weave 与 Mergiraf 对比

我们在 Python、TypeScript、Rust、Go、Java 和 C 语言的 31 个真实世界合并场景上进行了测试：

工具	干净合并数	分数
Weave	31/31	100%
Mergiraf (v0.16.3)	26/31	83%
Git	15/31	48%

Mergiraf 在“双方都在文件末尾添加”、“在现有代码之间插入”以及“装饰器冲突”等场景下均未能正确处理。而 Weave 由于其操作粒度更细（函数、类、方法），而非仅限于 AST 节点层面，因此能够完美解决这些问题。完整分析请参见 ataraxy-labs.github.io/weave。

实际应用基准测试

我们使用来自大型开源项目的实际合并提交进行了测试。对于每个合并提交，我们分别用 Git 和 Weave 重新执行合并操作，并与人工编写的最终结果进行对比。

• 胜出：指 Git 标记为冲突但 Weave 却能干净解决的合并提交；
• 退化：指 Weave 导致错误的情况（所有仓库中均为 0）；
• 与人工一致率：Weave 的输出与人工编写的内容完全一致的比例；
• 解决率：Weave 成功解决的合并提交占总尝试数量的百分比。

仓库	语言	合并提交数	胜出	退化	与人工一致率	解决率
git/git	C	1319	39	0	64%	13%
Flask	Python	56	14	0	57%	54%
CPython	C/Python	256	7	0	29%	13%
Go	Go	1247	19	0	58%	28%
TypeScript	TypeScript	2000	65	0	6%	23%

所有仓库中均未出现退化情况。每一次“胜出”都意味着开发者原本需要手动解决的误报冲突，现在都可以由 Weave 自动处理。

冲突标记

当确实发生冲突时，Weave 会提供 Git 所不具备的上下文信息：

<<<<<<< ours — function `process` (both modified)
export function process(data: any) {
    return JSON.stringify(data);
}
=======
export function process(data: any) {
    return data.toUpperCase();
}
>>>>>>> theirs — function `process` (both modified)

这样你就能立刻明白：是哪个实体发生了冲突、它属于什么类型，以及为什么会发生冲突。

支持的语言

TypeScript、TSX、JavaScript、Python、Go、Rust、Java、C、C++、Ruby、C#、PHP、Swift、Kotlin、Elixir、Bash、HCL/Terraform、Fortran、Vue、XML、ERB、JSON、YAML、TOML、CSV、Markdown。对于不支持的文件类型，将回退到标准的基于行的合并方式。

安装

brew install weave

或者从源码构建（需安装 Rust）：

git clone https://github.com/Ataraxy-Labs/weave
cd weave
cargo install --path crates/weave-cli
cargo install --path crates/weave-driver

设置

在任何 Git 仓库中：

weave setup

这会配置 Git，使其对所有支持的文件类型使用 weave 进行合并。之后即可像平常一样使用 git merge。

若要恢复为普通的 Git 合并方式：

weave unsetup

如果只想为自己设置（而不修改 .gitattributes 文件），可以使用 .git/info/attributes 文件：

git config merge.weave.name "实体级语义合并"
git config merge.weave.driver "weave-driver %O %A %B %L %P"
cat >> .git/info/attributes << 'EOF'
*.ts merge=weave
*.tsx merge=weave
*.js merge=weave
*.py merge=weave
*.go merge=weave
*.rs merge=weave
*.java merge=weave
*.c merge=weave
*.cpp merge=weave
*.rb merge=weave
*.cs merge=weave
EOF

Jujutsu (jj)

将以下内容添加到你的 jj 配置文件中（运行 jj config edit --user）：

[merge-tools.weave]
program = "weave-driver"
merge-args = ["$base", "$left", "$right", "-o", "$output", "-l", "$marker_length", "-p", "$path"]
merge-conflict-exit-codes = [1]
merge-tool-edits-conflict-markers = true
conflict-marker-style = "git"

使用 jj resolve --tool weave 解决冲突，或者将其设置为默认工具：

jj config set --user ui.merge-editor "weave"

预览

通过干运行合并来查看 weave 将会如何操作：

weave-cli preview feature-branch

  src/utils.ts — 自动解决
    未更改：2 处，我们新增：1 处，他们新增：1 处
  src/api.ts — 1 处冲突
    ✗ 函数 `process`：双方均进行了修改

✓ 合并结果干净（1 个文件已由 weave 自动解决）

架构

weave-core       # 库：实体提取、三路合并算法、重构
weave-driver     # Git 合并驱动程序二进制文件（由 Git 通过 %O %A %B %L %P 调用）
weave-cli        # 命令行工具：`weave setup` 和 `weave preview`

它使用 sem-core 通过 tree-sitter 语法解析器进行实体提取。

工作原理

         base
        /    \
     ours    theirs
        \    /
       weave merge

1. 解析：通过 tree-sitter 将三个版本解析为语义实体。
2. 提取区域：交替提取实体和间隙（如导入语句、空白字符）段落。
3. 匹配实体：根据 ID（文件:类型:名称:父节点）在不同版本之间匹配实体。
4. 解决冲突：单方修改的实体优先保留；双方均修改的实体则尝试进行实体内部的三路合并。
5. 重构文件：根据合并后的区域重建文件，并保持我们侧的顺序。
6. 回退机制：对于大于 1MB 的文件、二进制文件或不支持的文件类型，回退到行级合并。

星标历史

Weave 快速上手指南

Weave 是一款基于语义理解的 Git 合并工具，利用 tree-sitter 解析代码结构（如函数、类、JSON 键等），自动解决传统 Git 因“行级对比”而产生的误报冲突。特别适用于多 AI Agent 协作或多人开发场景。

环境准备

• 操作系统：macOS, Linux, Windows (WSL)
• 前置依赖：
  • Git：已安装并配置好基础环境。
  • Rust（仅源码编译时需要）：若使用包管理器安装则无需手动安装。
• 支持语言：TypeScript, JavaScript, Python, Go, Rust, Java, C/C++, Ruby, C#, PHP, Swift, Kotlin, JSON, YAML 等 21 种主流语言及配置文件。不支持的语言将自动回退到标准行级合并。

安装步骤

方式一：使用 Homebrew（推荐 macOS/Linux 用户）

brew install weave

方式二：从源码构建（需 Rust 环境）

git clone https://github.com/Ataraxy-Labs/weave
cd weave
cargo install --path crates/weave-cli
cargo install --path crates/weave-driver

注意：目前官方未提供国内镜像源，如遇网络问题，请配置 Rust/Cargo 国内镜像加速构建过程。

基本使用

1. 初始化配置

在任意 Git 仓库根目录下运行以下命令，Weave 会自动配置 Git 以对其支持的文件类型启用语义合并：

weave setup

此操作会修改 .gitattributes 文件。若仅需当前用户生效而不修改仓库配置，可参考 README 中的 .git/info/attributes 手动配置方案。

2. 执行合并

配置完成后，正常使用 Git 合并命令即可，Weave 会自动介入处理：

git merge feature-branch

• 无冲突场景：若两个分支修改了同一文件的不同函数或对象属性，Weave 将自动合并，无需人工干预。
• 真实冲突场景：若同一实体（如同一个函数）被双方不同地修改，Weave 会生成带有明确语义上下文的冲突标记（例如注明 function 'process' (both modified)），便于快速定位。

3. 预览合并结果（可选）

在实际合并前，可先干跑（dry-run）查看 Weave 的处理预期：

weave-cli preview feature-branch

输出示例：

  src/utils.ts — auto-resolved
    unchanged: 2, added-ours: 1, added-theirs: 1
  src/api.ts — 1 conflict(s)
    ✗ function `process`: both modified

✓ Merge would be clean (1 file(s) auto-resolved by weave)

4. 撤销配置

如需恢复为原生 Git 合并行为：

weave unsetup