mergelock

mergelock

一款原生基于 git 的合并门禁。mergelock check 会在两个分支合并前进行比较，并报告 git 本身不会告知你的冲突：一个分支更改了函数签名，而另一个分支仍添加了对旧签名的调用；某个符号在一侧被删除，但另一侧仍在使用；同一个函数被编写了两次。

它绝不会触碰你的工作树。所有计算都基于提交，使用 git merge-tree 和 tree-sitter 解析器，因此可安全用于 pre-push 钩子、CI，或通过 MCP 由 AI 编码 Agent 运行。

检测内容

规则	报告内容	严重性
textual	普通的 git 内容冲突	错误
add_add	两个分支在同一路径添加了文件	错误
modify_delete	一个分支编辑了另一个分支删除的文件或符号，或仍调用已删除的符号	错误
signature_caller	一个分支更改了签名；另一个分支添加了与新签名不兼容的调用	错误
duplicate_definition	两个分支添加了同一个函数，按名称或近乎相同的函数体判定	警告

语义规则支持 TypeScript、JavaScript（包括 TSX/JSX）和 Python。其他语言的文件仍会进行文本冲突、同时添加和修改后删除检查。

安装

mergelock 需要 git 2.38 或更高版本（用于 git merge-tree --write-tree）。

Homebrew（macOS 和 Linux）：

brew install sadayamuthu/tap/mergelock

Debian / Ubuntu（.deb，amd64 和 arm64；需要使用 git 2.38+ 的发行版，例如 Debian 12 或 Ubuntu 24.04）：

VERSION=0.1.5   # latest release, without the v
curl -fLO "https://github.com/sadayamuthu/mergelock/releases/download/v${VERSION}/mergelock_${VERSION}_$(dpkg --print-architecture).deb"
sudo apt install "./mergelock_${VERSION}_$(dpkg --print-architecture).deb"

Fedora / RHEL（.rpm，x86_64 和 aarch64）：

VERSION=0.1.5
sudo dnf install "https://github.com/sadayamuthu/mergelock/releases/download/v${VERSION}/mergelock-${VERSION}-1.$(uname -m).rpm"

Docker（linux/amd64 和 linux/arm64；将仓库挂载到 /repo）：

docker run --rm -v "$PWD":/repo ghcr.io/sadayamuthu/mergelock check my-branch main --format text
docker run -i --rm -v "$PWD":/repo ghcr.io/sadayamuthu/mergelock   # MCP server on stdio

GitHub Actions（对照基分支检查每个拉取请求；参见 在 CI 中）：

- uses: actions/checkout@v4
  with:
    fetch-depth: 0
- uses: sadayamuthu/mergelock@v0

预编译二进制文件（macOS 和 Linux，amd64 和 arm64）：从 最新版本 下载适用于你平台的压缩包，然后将 mergelock 放入 PATH：

tar -xzf mergelock_*_$(uname -s | tr A-Z a-z)_*.tar.gz
sudo mv mergelock /usr/local/bin/

在 macOS 上，从浏览器下载的压缩包中的二进制文件会被 Gatekeeper 拦截，因为它尚未签名（Homebrew 安装不受影响）。只需清除一次隔离标记：

xattr -d com.apple.quarantine /usr/local/bin/mergelock

使用 Go（需要 Go 1.25 或更高版本以及 C 编译器，因为 tree-sitter 使用 cgo；在 macOS 上安装 Xcode 命令行工具，在 Debian/Ubuntu 上安装 build-essential）：

go install github.com/sadayamuthu/mergelock/cmd/mergelock@latest

或从源代码构建：

git clone https://github.com/sadayamuthu/mergelock.git
cd mergelock
go build -ldflags "-X main.version=$(git describe --tags --always)" -o mergelock ./cmd/mergelock

检查是否运行正常：

mergelock version

快速开始

在任意 Git 仓库中运行：

# Is my branch safe to merge into main?
mergelock check my-feature main

# Compare against the configured target (main by default)
mergelock check my-feature

# Will two in-flight branches collide with each other?
mergelock check feat-a feat-b --format text

退出码便于编写脚本：

代码	结果
0	clean：未发现问题
1	warnings：只有警告
2	conflict：至少有一个错误
3	操作错误（分支名称无效、不是 Git 仓库、配置无效……）

完整的命令参考、.mergelock.yml 配置、JSON 输出架构、CI 和 Git 钩子示例，以及如何通过 MCP 将其连接到 AI Agent，请参阅 USAGE.md。 如需报告未检测到的冲突或添加语言，请参阅 CONTRIBUTING.md；如遇到安全问题，请参阅 SECURITY.md。

开发

go test ./...          # full suite, incl. fixture gate and 5,000-file perf test
go test -short ./...   # skips the perf test
go vet ./...
gofmt -l .

规则行为由 testdata/fixtures/*.txtar 中的分支对测试夹具固定；每个夹具都是一个精简的仓库，包含一个基础分支、两个分支和预期的检测结果。

许可证

Apache License 2.0