Entity-level merge drivers for virtual branches — reducing false conflicts

[rs545837]

Virtual branches are one of the most compelling workflows I've seen for parallel feature development, and I've been thinking about how entity-level merge could make them even better. When you're constantly applying and unapplying branches, Git's line-based 3-way merge hits false conflicts surprisingly often, two branches that each add a function to the same file, imports that both branches modify, class members added in different spots. These aren't real conflicts, but Git can't tell the difference.

I've been working on a structured merge driver called weave that uses tree-sitter to extract functions, classes, and methods as discrete entities, then merges at that level. On a benchmark suite of 31 merge scenarios, it resolves all 31 cleanly versus Git's 15/31 (48%). The gains come from three things: concurrent function additions to the same file merge without conflict, imports merge as unordered sets (so ordering differences don't cause conflicts), and class members merge independently. The underlying entity extraction library (sem-core) is a Rust crate that could also enable smarter hunk splitting, grouping changes by semantic entity rather than by diff proximity, which seems relevant to how GitButler assigns hunks to virtual branches.

Has the team considered structured merge approaches for the virtual branch workflow? It seems like a case where the payoff would be especially high, since merges happen so frequently and users aren't expecting to resolve conflicts every time they switch context. Happy to discuss the technical details or trade-offs, the approach draws on ideas from the LastMerge, Mergiraf, ConGra, and Sesame papers if any of those are familiar.

[Byron]

That sounds super interesting, thanks for sharing. Let me reel in @krlvi as well.

Regarding merge-drivers, these are already used when merging, so weave could be used with GitButler today.
And showing diffs differently would of course also be interesting, while clearly being a second step.

[rs545837]

Wanted to share some follow-up context. This direction has gotten significant traction publicly since I posted here.

The original tweet explaining the merge algorithm hit 41K impressions. A lot of the interest came from people running multiple AI agents (Cursor, Claude Code) on the same repo and hitting constant false conflicts.

For GitButler specifically, I think the highest-value integration beyond the merge driver would be entity-aware hunk assignment. Happy to pair on a prototype if there's interest from @krlvi or the team.

[rs545837]

Thanks for confirming that GitButler already picks up merge drivers through gitattributes. For anyone wanting to try weave with GitButler:

brew install ataraxy-labs/tap/weave
weave setup   # configures .gitattributes + merge driver

That's it. GitButler's virtual branch merges will use weave automatically for configured file types (TypeScript, JavaScript, Python, Go, Rust, JSON, YAML, TOML, Markdown).

On the "showing diffs differently" angle, that's where it gets interesting. The entity extraction comes from sem-core, which is a Rust library (not just a CLI). It uses tree-sitter to parse code into semantic entities (functions, classes, interfaces, types, etc.) with identity matching across versions.

For GitButler specifically, this could help with:

• Hunk assignment: Instead of grouping changes by line proximity, group them by which entity they belong to. A change to function foo and a change to function bar in the same file are clearly separate hunks, even if they're adjacent lines.
• Entity-level diffs in the UI: Show "function validateToken was modified" rather than "@@ -42,7 +42,9 @@".
• Smarter branch assignment: If an entity's dependency graph is known, changes that affect related entities could be auto-grouped into the same virtual branch.

Since GitButler's backend is Rust and uses gix, sem-core could be added as a direct crate dependency rather than shelling out to a CLI. Happy to help explore what that integration would look like if @krlvi is interested.

[as29062008]

I tried it out, it definitely makes so much more sense to use entity level diffs with agents, not sure why people have not researched enough in this direction, and made this a standard.

[nshcr]

This is absolutely a killer merge driver!
However, after doing a quick test, I noticed a potential issue, and I'm not sure whether this behavior is expected.

I randomly picked a Rust enum and simulated a conflict scenario where two branches rename the same enum on the same line.

Original:

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub enum Source {
  // ...
}

Modification on main:

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub enum Source1 {
  // ...
}

Modification on branch-1:

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub enum BSource {
  // ...
}

Final merge result (git merge branch-1):

pub enum BSource {
  // ...
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub enum Source1 {
  // ...
}

So although Git did not report a conflict and completed the merge successfully, the merge state produced by weave appears to be incorrect - both renames of the same enum from the two branches were preserved.

Please forgive me for not having fully read the weave documentation yet. I would have expected this kind of case to fall back to the original line-by-line conflict resolution. Did I misunderstand or misuse something here?

Or does weave treat the function / enum as a different entity once the signature changes, even if both function B and function C are just renames of the same original function A? Is tracking changes across such derived functions within weave's intended scope?

I feel this kind of "apparently successful but actually incorrect" merge could be more dangerous, as it may allow faulty code to slip into commits unintentionally.

I haven't done any research in this area and am only raising this from a practical engineering perspective. If I misunderstood anything, please feel free to correct me!

[rs545837]

Thanks for testing this, and thanks for the kind words. You found a real bug, now fixed in v0.1.2 (824109a). Let me address each point.

The behavior was incorrect. Both renames should not have been preserved. You didn't misunderstand or misuse anything.

What was happening: weave's rename detection used structural_hash, an AST-normalized hash that includes the entity name. Renaming Source to Source1 changed the hash, breaking the identity match. Without that match, the merge saw three unrelated events: Source deleted by both branches (clean), Source1 added by ours (clean), BSource added by theirs (clean). Each resolved independently. No conflict. That's also why the #[derive(...)] attribute was only preserved on one copy: the attribute was bound to one entity's region, and the other was treated as a brand new addition without its surrounding context.

On falling back to line-by-line: weave falls back when entity extraction fails (wrong file type, 0 entities, file > 1MB). Here the Rust parser successfully extracted the enum from all three versions, and the entity merge completed without hitting any failure condition. The merge didn't fail. It succeeded with the wrong answer.

But here's the thing: line-level merge would have caught this, not because it understood the rename, but because both branches happened to touch line 2. That's accidental correctness. The same line-level merge also flags two branches adding different functions at the end of the same file as a conflict, which isn't a real conflict at all. Line-level merge conflates textual proximity with semantic relationship. Sometimes that accidentally catches real problems. Most of the time it creates noise.

Is rename tracking in scope? Absolutely. This is core to entity-level merge. weave already tracked single-branch renames (one side renames, other side modifies the body). The gap was both-sides-rename, which the body hash fix now handles. The new body_hash strips the entity name at word boundaries before hashing, so pub enum Source { ... } and pub enum Source1 { ... } produce the same hash.

The fix (v0.1.2):

• Body hash rename detection (name-stripped, word-boundary-aware) catches pure renames across all languages
• New RenameRename conflict kind with clear markers: both renamed: 'Source' → ours 'Source1', theirs 'BSource'

You found a real gap and your instinct about why it matters was exactly right. This is the kind of feedback that pushes the tool forward.

Thanks!

[nshcr]

Thank you for the detailed explanation and for fixing this so quickly! I tested v0.1.2, and the merge behavior now matches my expectations — it correctly marks this situation as a merge conflict that requires manual resolution.

In fact, I think we all know that even when Git completes a merge without conflicts, it doesn't guarantee the correctness of the result (which is why CI checks are necessary). What surprised me before was that weave handled this case by fully duplicating an entity to resolve the conflict, which is something I've never seen a default merge algorithm do automatically. That kind of result is usually caused by incorrect manual conflict resolution.

So I'm very glad to see that this was just a bug and that weave now handles this scenario appropriately! I guess I was lucky to encounter this issue in my very first test scenario. I'll continue trying this merge driver in my personal work repositories (and will report any related issues directly to the weave repository in the future).

I'm also really looking forward to seeing GitButler potentially incorporate weave's merge conflict handling strategy and take another step toward becoming a more modern Git tool. GitButler's fearless rebase feature already does a great job of marking commits with conflicts, but it simply leaves the conflict resolution to the user in its original, manual form. Weave is undoubtedly a very promising direction and could help solve real collaboration pain points in multi-user and multi-agent workflows.

Let's shift the discussion back to the main topic and leave this for the GitButler team to carefully evaluate internally — I believe they've already taken notice of this project.

[slarse]

Hello @rs545837!

I want to preface my post by the fact that I think what you're doing is amazing, and I'd love to keep chatting about this to see if there's room for some collaboration on this topic. Line-based merge is so very limited, yet persists simply because more involved merge algorithms are so much effort, and few have been willing to chip in.

Also, your tool actually came up in a discussion in the GitButler team just before you posted this.

For some context on why I'm at least moderately qualified to comment on this topic, I worked on prototyping structured merge back in 2019-2021. Initially with a focus on move-enabled merge (i.e. allowing an AST subtree be moved in one revision and edited in another without causing a conflict), and then with a focus on not having the printing of the merged AST to source code absolutely butcher the original formatting of the code. If you're curious, the (now long abandoned) merge tool is over at https://github.com/ASSERT-KTH/spork, and the resulting whitepaper can be found here. I honestly do not remember half of my work there, but at some point in time I was fairly in-the-know on this topic.

Largely unnecessary flexing out of the way, let's get back to the topic at hand. There are several team members at GitButler that are intrigued by this. We have at least one avid user of Mergiraff, a tool we unfortunately cannot incorporate due to it being under a GPLv3 license. Speaking of license, weave does not appear to have one, meaning that it falls under the default copyright rules that prohibit pretty much everything. What license do you intend to put weave under?

On a benchmark suite of 31 merge scenarios, it resolves all 31 cleanly versus Git's 15/31 (48%).

This is cool, but really only shows the potential of the tool, and does not tell us about its performance or reliability. It's just too small a sample set. Possibly the largest takeaway I had from my own work is that, while textual merge is very limited, it's also very simple. You really don't hear of bugs in textual merge, while a bug in weave has been uncovered in this very thread. AST-based merge is rather complex.

The gains come from three things: concurrent function additions to the same file merge without conflict, imports merge as unordered sets (so ordering differences don't cause conflicts), and class members merge independently.

This surprises me a little bit. I added these exact optimizations myself, but even without them I had a significantly lowered rate of merge conflicts than with a textual merge. For example, if one revision adds a parameter and another revision adds something else to the method signature (return value, modifier, etc), a line-based merge conflicts while a fully structured merge does not. weave appears to perform poorly in such a scenario, see example in spoilers below.

weave vs line-based merge on single scenario

Scenario source

Produced with weave-driver Base.java Left.java Right.java

<<<<<<< ours — class `Main` (F, confidence: medium)
diff --git a/src/test/resources/clean/both_modified/add_parameters_and_thrown_types/Left.java b/src/test/resources/clean/both_modified/add_parameters_and_thrown_types/Left.java
index 963c829..5554564 100644
--- a/src/test/resources/clean/both_modified/add_parameters_and_thrown_types/Left.java
+++ b/src/test/resources/clean/both_modified/add_parameters_and_thrown_types/Left.java
@@ -1,5 +1,14 @@
+<<<<<<< ours — class `Main` (F, confidence: medium)
+// hint: Logic changed on both sides. Requires understanding intent of each change.
 public class Main {
     public int add(int a, int b) throws IllegalArgumentException {
         return a + b;
     }
 }
+=======
+public class Main {
+    public int add(int a, int b, int c) {
+        return a + b + c;
+    }
+}
+>>>>>>> theirs — class `Main` (F, confidence: medium)

Produced with `git merge-file Left.java Base.java Right.java

 public class Main {
+<<<<<<< Left.java
     public int add(int a, int b) throws IllegalArgumentException {
         return a + b;
+=======
+    public int add(int a, int b, int c) {
+        return a + b + c;
+>>>>>>> Right.java
     }
 }

I can easily engineer this scenario to be even more in favor of the line-based merge by separating the signature and the return statement with a blank line in all revisions (or, really, any line), and increasing the size of the class with other methods, fields etc. Then, the line-based merge conflicts only on the method header, while weave still conflicts on the entire class.

This single scenario is of course of very little importance, but I think it illustrates the point that there's a need for a larger scale evaluation of weave as a merge tool. I think it also doesn't really do what I consider a fully structured merge, but more akin to a semi-structured merge. I'd be very interested in learning more about the diff and merge algorithms that are employed.

Perhaps we can hop on a call sometime in the near future and you can tell me more about weave?

[rs545837]

Hey @slarse, thanks for the detailed feedback. Genuinely appreciate the depth here, and Spork's work is super interesting and might be useful as well.

Let me go through your points:

License: We're going MIT/Apache-2.0 dual license (Rust ecosystem convention). Will push that shortly. We're aware Mergiraf's GPLv3 is a blocker for you, and we want weave to be embeddable.

Benchmark size: You're right that 31 hand-crafted scenarios only show potential. We've since run real-world benchmarks on actual merge commits from git/git (500 merges, 1319 files), CPython, Flask, the TypeScript compiler, and Go. Zero regressions across all repos. On git/git, weave resolved 39 of 310 git conflicts (13%), with 64% matching the human resolution. Full results are in the README.

"You don't hear of bugs in textual merge": Actually every false conflict is kinda like a bug that everyone has normalized. Git conflicting when two branches modify different functions in the same file is incorrect behavior. We also have a floor mechanism: weave never produces more conflict markers than git merge-file would, so it literally cannot be worse.

The class scoping issue you found: Your test case was extremely useful. It exposed a real bug in how we decomposed class members. Previously we used an indentation heuristic to find method boundaries inside classes. We've replaced that with tree-sitter child entity extraction, so method boundaries are now exact across all 13 supported languages.

With the fix, when two branches modify the same class but touch different methods, it resolves cleanly now. When they collide on the same method, the conflict wraps only that method:

public class UserService {
<<<<<<< ours
    public User getUser(String id) throws NotFoundException {
        return db.findOrThrow(id);
    }
=======
    public User getUser(String id, boolean includeDeleted) {
        return db.find(id, includeDeleted);
    }
>>>>>>> theirs

    public void createUser(User user) {
        validate(user);
        db.save(user);
    }

    public void deleteUser(String id) {
        db.remove(id);
    }
}

Only getUser conflicts. createUser and deleteUser merge cleanly regardless of whether they were modified or not. The same works for TypeScript classes, Python classes, Rust impl blocks, and everything else.

We also tested a case where one branch changes a method parameter and another adds an annotation to a different method in the same class. That merges cleanly with zero conflicts as well, which git would conflict on.

Semi-structured vs fully structured: That's accurate and somewhat intentional from our side. A fully structured merge needs a language-specific pretty-printer to round-trip the AST back to source without destroying formatting (which you might have experienced firsthand with Spork). That approach doesn't scale with multiple languages. Weave uses tree-sitter for entity extraction and operates on source text directly, falling back to line-level for unsupported file types. The tradeoff is that intra-method signature changes (your parameter + throws example) still conflict when they're on the same method, but the conflict is now scoped to just that method instead of the whole class.

On connecting: Would love to chat more about this. My email is on my GitHub profile, feel free to reach out and we can set something up, currently I am heads down and coming up with interesting ideas, extend some ideas of weave.

[slarse]

License: We're going MIT/Apache-2.0 dual license (Rust ecosystem convention). Will push that shortly. We're aware Mergiraf's GPLv3 is a blocker for you, and we want weave to be embeddable.

Fantastic!

Benchmark

Very cool, would be very interested in hearing about the testing methodology employed here! The results look very promising.

Bugs

I don't want to get bogged down into discussing "what a bug is", my point was just that in developing Spork there were many bugs along the way that were significantly worse than false conflicts. Not to mention that the core merge algorithm has a teeny weeny limitation in that it doesn't detect a conflict if one revision deletes a subtree, and another revision makes edits inside of that same subtree (result is just that the subtree goes poof!) :)

The class scoping issue you found

Cool!

We also tested a case where one branch changes a method parameter and another adds an annotation to a different method in the same class. That merges cleanly with zero conflicts as well, which git would conflict on.

I honestly don't understand how a Myers-based textual merge would conflict in this scenario, could you point me to this test case?

A fully structured merge needs a language-specific pretty-printer to round-trip the AST back to source without destroying formatting

Haha, yes this ended up being the sole focus of my first and only IEEE journal paper :). In the end I made a very fine-grained copy-paste engine that just didn't feel worth the effort. I think it's a positive thing that weave is semi-structured, it's a much more viable approach than fully structured merge while still providing many of the benefits. Bugs are a significantly smaller issue with semi-structured merge as it's vastly less complicated than fully structured.

I'll hit you up with an email later this week to try to schedule a chat! There are several of us that are really excited about what we could do with this kind of tech and I really want to have a chat about it as soon as possible. I've got some high-prio tasks to take care of first, but expect to hear from me before the end of the week.