weave - entity-level git merge driver for agents

If you've ever run two agents on the same repo and watched them fight git over an "obvious" merge - agent A added a function at the top, agent B added a different function at the bottom, and git declared a conflict because they both edited the same file - Weave is the fix. It's a git merge driver written in Rust that operates on entities (functions, classes, declarations) rather than lines.

The README's claim is roughly a 95% reduction in false conflicts versus line-based merge. That figure depends entirely on your workflow, but the mechanism is real: tree-sitter parses base / ours / theirs into ASTs, matches entities by name + type + scope across all three, and merges at the entity level. Two agents adding two independent functions never collide.

What it solves with one example

Line-based merge on a file where each branch added a different function:

<<<<<<< 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

Weave sees two distinct entities, each present on exactly one side, and concatenates them cleanly - no conflict markers, no human intervention. When the entities do overlap (two branches modifying the same function in incompatible ways), Weave still flags a conflict, but with the entity itself as the unit of context instead of arbitrary line ranges.

Quick start

brew install weave
weave setup

weave setup writes the global git config and the .gitattributes patterns it needs. To remove it cleanly:

weave unsetup

If you don't want global setup, configure it per-repo:

git config merge.weave.name "Entity-level semantic merge"
git config merge.weave.driver "weave-driver %O %A %B %L %P"

Then add the patterns you want covered to .gitattributes.

Languages it understands

Tree-sitter coverage is broad: TypeScript / TSX, JavaScript, Python, Go, Rust, Java, C / C++, Ruby, C#, PHP, Swift, Kotlin, Elixir, Bash, Fortran, Dart, Perl, OCaml, Scala, Zig, Vue, Svelte, plus the structured-data set - XML, ERB, JSON, YAML, TOML, CSV, Markdown, HCL/Terraform.

Anything outside that list falls back to standard line-level merge. Files larger than 1 MB also fall back, as do binaries. The fallback is silent and safe - Weave never makes the merge worse than git's default.

How it actually works

1. Parse BASE, OURS, THEIRS with tree-sitter into a list of semantic entities (functions, classes, type declarations, etc.).
2. Match entities across the three trees by identity - name + type + scope. A renamed function is treated as a delete + add, which is the conservative call.
3. For each matched triple, decide:
   • Unchanged on one side → take the other side.
   • Changed on both sides → check if the diffs are compatible; if not, emit a conflict scoped to the entity.
   • Added on one side only → include it.
4. Re-emit the merged file in source order, preserving whitespace and comments where possible.

There's no LLM in this pipeline. It runs entirely offline, doesn't need an API key, and the binary is small enough to vendor into CI without thinking about it.

When to reach for it

• You routinely run multiple agents in parallel against the same branch (or the same file).
• You have long-lived feature branches that touch shared utility files and keep colliding on imports and helper functions.
• You're building agent infrastructure where merges are part of the loop and human conflict resolution is a bottleneck.

When not to

• Single-developer, single-agent workflows. The 95% reduction is moot if you weren't getting many conflicts to begin with.
• Languages outside the supported list. The fallback is safe but you get no benefit.
• Repos where most "conflicts" are actually intentional incompatible edits. Weave will surface those just fine, but it can't make a real conflict go away.

Limits worth knowing

The 1 MB file ceiling is the most likely thing to bite you - generated TypeScript bundles, lock files, and giant fixture JSON all sit above it and silently fall back. That's usually fine, but check .gitattributes if you expect entity-level behaviour and aren't getting it.

Whitespace-only or comment-only changes aren't considered entity changes, which is mostly what you want - but means a comment-only change to a function on one branch can be silently dropped if the other branch modifies the function. Worth keeping in mind on codebases where comments carry contractual weight (license headers, doc strings consumed by tooling).

For agent workflows specifically, this is one of the most leverage-per-line-of-config tools currently shipping. Five minutes to install, no ongoing cost.