weave

Entity-level semantic merge driver for Git. Resolves false conflicts that Git's line-based merge creates when multiple agents (or humans) edit the same file on different branches.

The Problem

Git merges by comparing lines. When two branches both add code to the same file — even to completely different functions — Git sees overlapping line ranges and declares a conflict:

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

These are completely independent changes. There's no real conflict. But someone has to manually resolve it anyway.

This happens constantly when multiple AI agents work on the same codebase. Agent A adds a function, Agent B adds a different function to the same file, and Git halts everything for a human to intervene.

How Weave Fixes This

Weave replaces Git's line-based merge with entity-level merge. Instead of diffing lines, it:

1. Parses all three versions (base, ours, theirs) into semantic entities — functions, classes, JSON keys, etc. — using tree-sitter
2. Matches entities across versions by identity (name + type + scope)
3. Merges at the entity level:
   • Different entities changed → auto-resolved, no conflict
   • Same entity changed by both → attempts intra-entity merge, conflicts only if truly incompatible
   • One side modifies, other deletes → flags a meaningful conflict

The same scenario above? Weave merges it cleanly with zero conflicts — both functions end up in the output.

Weave vs Git Merge

The key difference: Git produces false conflicts on independent changes because they happen to be in the same file. Weave only conflicts on actual semantic collisions — when two branches change the same entity incompatibly.

Conflict Markers

When a real conflict occurs, weave gives you context that Git doesn't:

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

You immediately know: what entity conflicted, what type it is, and why it conflicted.

Supported Languages

TypeScript, JavaScript, Python, Go, Rust, JSON, YAML, TOML, Markdown. Falls back to standard line-level merge for unsupported file types.

Setup

# Install
brew install ataraxy-labs/tap/weave

# In your repo:
weave setup

# Or manually:
git config merge.weave.name "Entity-level semantic merge"
git config merge.weave.driver "/path/to/weave-driver %O %A %B %L %P"
echo "*.ts *.tsx *.js *.py *.go *.rs *.json *.yaml *.toml *.md merge=weave" >> .gitattributes

Then use Git normally. git merge will use weave automatically for configured file types.

Preview

Dry-run a merge to see what weave would do:

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)

Architecture

weave-core       # Library: entity extraction, 3-way merge algorithm, reconstruction
weave-driver     # Git merge driver binary (called by git via %O %A %B %L %P)
weave-cli        # CLI: `weave setup` and `weave preview`
weave-crdt       # Automerge-backed CRDT coordination state
weave-mcp        # MCP server (9 tools for AI agent integration)

Uses sem-core for entity extraction via tree-sitter grammars.

How It Works

         base
        /    \
     ours    theirs
        \    /
       weave merge

1. Parse all three versions into semantic entities via tree-sitter
2. Extract regions — alternating entity and interstitial (imports, whitespace) segments
3. Match entities across versions by ID (file:type:name:parent)
4. Resolve each entity: one-side-only changes win, both-changed attempts intra-entity 3-way merge
5. Reconstruct file from merged regions, preserving ours-side ordering
6. Fallback to line-level merge for files >1MB, binary files, or unsupported types

View on GitHub | Read the technical deep dive | MIT License