Weave: entity-level merge for git when agents edit the same file
Entity-level git merge driver. Resolves false conflicts git invents when independent agents edit the same file. ~95% reduction vs. line-based merge.
At a glance
- What is it?
- Weave is a Rust merge driver that parses base, ours and theirs into functions, classes and JSON keys with tree-sitter, then merges those entities instead of lines. It removes the false conflicts git reports when two branches touch different code in the same file, and refuses the ones that are genuinely ambiguous.
- Who is it for?
- Adopt weave if your branches come from coding agents that keep adding separate functions, keys or properties to the same files, and you want git merge to stop halting on changes that never touched the same code. Do not adopt it if your conflicts are real edits to the same function body, or if your language is not among the 38 the README claims, because entity matching is the whole mechanism and it needs a parser.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The conflict weave is built to remove
Git compares lines. When two branches add code to the same file, even to functions that share nothing, the line ranges overlap and git writes conflict markers. The README shows the canonical example: one branch adds validateToken, the other adds formatDate, and git treats them as a collision because both insert near the same position. Nothing about those two functions interacts. A human still has to resolve it.
The problem gets worse with agents. If several coding agents work the same repository, each one appending a function, a JSON key or an object property, git produces conflicts at a rate that has nothing to do with how much the changes actually overlap. Weave targets exactly that gap: independent edits in a shared file. It is not aimed at two people rewriting the same function body, and it does not pretend to be.
Three-way merge over entities, not lines
Weave is a git merge driver. The README describes the algorithm as a three-way merge that compares base, ours and theirs at the level of functions, classes and keys. It parses all three revisions with tree-sitter, matches entities across versions by identity (name plus type plus scope), and includes renames in that matching.
The merge rules are stated plainly. Different entities changed on each side: auto-resolved. The same entity changed by both sides: weave attempts an intra-entity merge and only conflicts if the two versions are truly incompatible. One side modifies and the other deletes: weave reports a meaningful conflict with a description such as function 'validateToken' (modified in ours, deleted in theirs), instead of a raw diff hunk.
The README is explicit that this is deterministic and stateless, reading three file revisions and writing one result, the same shape as git merge-file. It is not a CRDT. The project does ship a separate CRDT-backed layer, weave-crdt, for coordinating live agent edits before they reach git, but that is a different component from the merge driver and the README does not describe how the two interact in a normal merge.
What weave refuses to merge, and why that is the point
The README's comparison against mergiraf includes 31 hand-crafted scenarios across 7 languages, and it states that two of them must not merge. When both sides add different decorators to the same Python or TypeScript function, decorator order is function composition, so the resulting stack order is a semantic decision neither branch made. The README's own example is @cache outside @auth, which serves cached responses without running the auth check. Weave refuses rather than pick an order, and the README argues that a tool merging those cleanly is wrong, not better.
Java, C# and Kotlin annotations are treated differently, because annotations there are unordered metadata, so weave set-unions them. That distinction between ordered decorators and unordered annotations is the kind of judgement a line-based merge cannot make at all, and it is the clearest signal of what entity-level parsing buys you.
Setup, CLI and the MCP server
The quickstart is four commands. weave setup installs the driver for the current repository; after that, git merge, git rebase and git cherry-pick behave as before but route through weave. Real conflicts still land as markers, with a refused_by: line stating why weave declined. weave explain <file> prints per-hunk detail for one conflicted file, read off the actual git stages. weave check verifies the working tree against the three merge stages and exits 1 on findings.
The README points to --global and --local variants of setup, without spelling out in the material available here which config file each one writes. Repository-level setup is the safer default when you are evaluating the tool, since it keeps the driver out of every other checkout on the machine. weave bench reproduces the 31-scenario comparison against mergiraf and git, and it is the command to run against your own code before trusting the 95% figure in the repository description.
The project also ships an MCP server, which is the integration point for agent frameworks. The README lists it as a section but the supplied text does not describe its tool surface, so how an agent actually calls weave during a merge is not something I can confirm from this material.
Where entity merge is the wrong tool
Weave does not remove conflicts on the same entity. If two agents edit the body of one function in incompatible ways, the README's own table says the result is still a conflict, now with entity-level context attached. That context is useful, but it is not a resolution, and teams whose work concentrates on a few large functions will see little change.
Language coverage is the harder constraint. The README claims 38 languages, and the mechanism depends on tree-sitter grammars for all of them. Any file weave cannot parse falls back to whatever the driver does with unparsed content, and the material here does not state what that fallback is. If your repository is mostly a language outside that set, the entity layer has nothing to match on.
The two decorator scenarios are a deliberate non-feature. A team that expects every independent-looking change to merge will find weave refusing in cases where the change is technically independent but semantically ordered. That is a design position, not a bug, and it means weave's refusal rate is not the metric to optimise.
How it differs from mergiraf and from plain git
Mergiraf is the closest comparison in the README, and it is also a tree-sitter based merge tool, so the difference is not parsing versus no parsing. The README's benchmark table reports weave at 29 of 29 mergeable scenarios and 31 of 31 correct outcomes, mergiraf at 26 of 29 and 28 of 31, and git at 15 of 29 and 17 of 31. All three correctly refuse the two decorator scenarios.
The stated failure modes for mergiraf are both-add-at-end-of-file and insert-between-existing, which weave resolves. That suggests the divergence is in how each tool decides whether two edits to the same region are compatible, not in whether they understand syntax. Git is the baseline the whole project exists to replace: it conflicts on independent changes because they land on the same line numbers, and it has no notion of an entity to match on.
The benchmark is 31 scenarios written by the weave authors, described as comparable to mergiraf's own corpus. It is a useful reproduction target via weave bench, not an independent evaluation, and the README does not report timings or memory use for either tool.
Licence, releases and what to verify first
The repository description states Apache-2.0 while the README badge says MIT OR Apache-2.0, and the badge links to a LICENSE-MIT file. Those two statements do not agree, and the licence files in the tree are what govern, not the badge. Anyone embedding weave in a product should read the actual LICENSE and LICENSE-MIT files rather than rely on either summary. I am not giving legal advice here, only flagging that the metadata conflicts.
Release cadence is visible from the supplied list: v0.5.2 on 2026-08-22, v0.5.3 on 2026-08-31, v0.5.4 on 2026-09-01, with the last push to main on 2026-09-10. That is a pre-1.0 project moving in small increments, so pinning a version and reading the release notes before upgrading is reasonable. The README does not describe a migration path between driver versions, which matters if weave has already written merge results into your history.
What to verify on your own repository, in order: run weave bench and see whether the scenario mix resembles your codebase; run weave setup --local rather than --global so the driver stays in one checkout; and merge two branches that both add functions to a shared file, then run weave check to confirm the working tree matches the three stages. If your conflicts are mostly within single functions, the benchmark will not tell you anything useful about your day-to-day.
Editorial conclusion
Adopt weave if your branches come from coding agents that keep adding separate functions, keys or properties to the same files, and you want git merge to stop halting on changes that never touched the same code. Do not adopt it if your conflicts are real edits to the same function body, or if your language is not among the 38 the README claims, because entity matching is the whole mechanism and it needs a parser. Before rolling it out, run weave bench on your own repository, check that weave setup --local writes the driver into .git/config rather than the global one, and confirm that the two decorator cases still land as refusals in your tree rather than as silent merges.
Community notes