mergelock

mergelock

A git-native merge gate. mergelock check compares two branches before they meet and reports the conflicts git itself won't tell you about: a function whose signature changed on one branch while the other branch added calls to the old signature, a symbol deleted on one side but still used on the other, the same function written twice.

It never touches your working tree. Everything is computed from commits with git merge-tree and tree-sitter parsers, so it is safe to run in a pre-push hook, in CI, or from an AI coding agent over MCP.

What it detects

Rule	Reports	Severity
textual	Ordinary git content conflicts	error
add_add	Both branches add a file at the same path	error
modify_delete	One branch edits a file or symbol the other deletes, or still calls a deleted symbol	error
signature_caller	A signature changed on one branch; the other adds calls that no longer fit	error
duplicate_definition	Both branches add the same function, by name or by near-identical body	warning

Semantic rules understand TypeScript, JavaScript (incl. TSX/JSX) and Python. Files in other languages still get the textual, add/add and modify/delete checks.

Install

mergelock needs git 2.38 or newer (for git merge-tree --write-tree).

Homebrew (macOS and Linux):

brew install sadayamuthu/tap/mergelock

Debian / Ubuntu (.deb, amd64 and arm64; needs a distribution with git 2.38+, such as Debian 12 or 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 and 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 and linux/arm64; mount the repository at /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 (checks each pull request against its base branch; see In CI):

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

Prebuilt binary (macOS and Linux, amd64 and arm64): download the archive for your platform from the latest release, then put mergelock on your PATH:

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

On macOS, a binary from an archive downloaded in a browser is blocked by Gatekeeper because it isn't signed yet (Homebrew installs aren't affected). Clear the quarantine flag once:

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

With Go (needs Go 1.25 or newer and a C compiler, since cgo is used for tree-sitter; on macOS install the Xcode command-line tools, on Debian/Ubuntu build-essential):

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

Or build from source:

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

Check it works:

mergelock version

Quick start

Run inside any git repository:

# 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

Exit codes make it easy to script:

Code	Result
0	clean: no findings
1	warnings: only warnings
2	conflict: at least one error
3	operational error (bad branch name, not a git repo, invalid config…)

See USAGE.md for the full command reference, the .mergelock.yml config, the JSON output schema, CI and git-hook recipes, and how to connect it to an AI agent over MCP. To report a missed conflict or add a language, see CONTRIBUTING.md; for a security problem, see SECURITY.md.

Development

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

Rule behaviour is pinned by branch-pair fixtures in testdata/fixtures/*.txtar; each one is a tiny repo with a base, two branches and the expected findings.

License

Apache License 2.0