Supporting additional structured merge tools — entity-level merge as complement to Mergiraf

[rs545837]

The Mergiraf integration in jj is great to see, it's a clear signal that the project values structured merge over Git's line-based approach. I've been working on a merge driver called weave that takes a different but complementary approach, and I wanted to ask about the integration path for additional structured merge tools via jj resolve --tool or the merge driver configuration.

Where Mergiraf operates on AST nodes (syntax-level merging), weave operates on semantic entities, functions, classes, methods, and imports extracted via tree-sitter. The practical difference shows up in a few places: class members merge as unordered sets (so two branches adding different methods to the same class merge cleanly regardless of insertion point), imports merge as sets rather than ordered lines, and entity renames are detected via structural content hashing. On a benchmark of 31 merge scenarios, weave resolves all 31 cleanly versus Git's 15/31. Mergiraf's AST approach has its own strengths, finer-grained handling of expression-level changes, for instance, so these feel like complementary tools rather than competing ones. The underlying extraction library (sem-core) supports 11 languages and is available as a Rust crate.

Is there a recommended path for integrating external merge tools beyond Mergiraf? I'm curious whether jj resolve --tool is the right entry point, or if there's a more structured merge driver interface that jj exposes. Also interested in whether the team has thoughts on the trade-offs between syntax-level and entity-level structured merge, the Mergiraf integration suggests you've already thought deeply about this space.

[scott2000]

Right now, I believe we only support this type of tool as a merge tool for jj resolve. You may have already seen this, but we have some documentation about the available config here: https://docs.jj-vcs.dev/latest/config/#3-way-merge-tools-for-conflict-resolution

You can also see all of the built-in merge tool configuration here (including Mergiraf): https://github.com/jj-vcs/jj/blob/main/cli/src/config/merge_tools.toml

I believe we didn't initially plan too deeply for structured merge tools actually, it's more than we already had interactive merge tools, and it seemed like it would be useful to support Mergiraf, so we just added some additional config options to support non-interactive merge tools as well (e.g. parsing Git diff3-style conflict markers to allow partial conflict resolution and allowing different exit codes to indicate conflicts). We use a similar interface to Git merge drivers right now, so it's nothing too unique IMO.

Some current issues that may be relevant are:

• Currently merge tools only support 2-sided conflicts (in the future we might want to support recursively merging pairs of sides to resolve many-sided conflicts)
• Currently merge tools are executed separately on each file always, there's no way to pass an entire directory to a merge tool to allow merging many files at once
• Merge tools currently can't process multiple files in parallel either; they always process the conflicted files in sequence one at a time
• We don't have rename detection yet for conflicts in general, and this also applies to merge tools I believe

Hopefully we can solve these in the future.

I think people have also talked about using merge tools automatically to resolve conflicts when merging/rebasing, but I'm not sure how feasible that would be.

[rs545837]

Thanks for the detailed breakdown and the links. The merge_tools.toml config and the non-interactive merge tool options (merge-tool-edits-conflict-markers, conflict-marker-style) are exactly what I needed to understand the integration path.

Interesting that rename detection is a known gap. That's one of the things weave handles via structural content hashing, matching entities across branches even when renamed. If that discussion ever moves forward, happy to share how we approach it.

The auto-invocation during merge/rebase discussion is the most relevant use case for us. If there's an issue tracking that, I'd like to follow along.

Would it make sense for me to open a PR adding weave to merge_tools.toml at some point, or is it better to wait until some of the limitations you mentioned are addressed first?

[scott2000]

If that discussion ever moves forward, happy to share how we approach it.

Here's the issue for rename and copy support for files: #47 (there's also #1112 for jj resolve specifically).

There's also a design doc for the current plan to implement this: https://docs.jj-vcs.dev/prerelease/design/copy-tracking/

The auto-invocation during merge/rebase discussion is the most relevant use case for us. If there's an issue tracking that, I'd like to follow along.

I remember this has been discussed a few times. The only one I can find currently is #7560, but there may be some other issue which is more relevant.

Would it make sense for me to open a PR adding weave to merge_tools.toml at some point, or is it better to wait until some of the limitations you mentioned are addressed first?

I'm not too familiar with weave so I'm not sure if the limitations would matter. If you have a working merge tool config for weave and you think it would be useful for others, opening a PR to contribute it could be good.

[rs545837]

Thanks for the detailed breakdown, this is really helpful. A few notes on the limitations you mentioned:

• 2-sided conflicts only: weave currently does standard 3-way merge (base, ours, theirs), so it fits the 2-sided model. Supporting many-sided conflicts through recursive pairwise merging would be interesting though. Since weave matches entities by identity (name + type + scope), the matching step should work across any number of sides as long as they're paired down.

• Per-file only, no directory-level: weave already operates per-file, so this is fine for now. Longer term, sem-core (the entity extraction library weave uses) can build cross-file dependency graphs, which could enable directory-level merge decisions like "function X was moved from file A to file B."

• Sequential file processing: Entity merges are independent per file, so parallel processing would be a pure performance win with no correctness concerns. Happy to support whatever interface jj exposes for this.

• No rename detection: weave does entity-level rename detection via structural hashing. If a function is renamed but its body is the same (or very similar), weave identifies it as a rename rather than a delete+add. This works within a file today. Cross-file rename detection would pair well with jj's native rename tracking once that lands.

I went ahead and added -o/--output flag support to weave-driver so it works with jj's merge tool interface (jj writes to a separate $output file, Git overwrites %A in place). I've opened a PR to add a weave entry to merge_tools.toml: #8833

[sloane-shark]

just wanted to register my interest in having weave as a readily usable tool out of the box; this seemed like a better place than #8833