Mergiraf: Generic Structured Merge Tool

• Mergiraf is a language-agnostic structured merge tool that uses Tree Sitter CSTs and a thin configuration interface to enable accurate, per-language code merging.
• It employs a three-phase pipeline—auto-tuning, structured matching, and structured amalgamation—to efficiently handle both clean merges and conflict resolution.
• The tool demonstrates a trade-off by achieving 42% fewer false negatives than Spork while maintaining competitive runtime performance in real-world merge scenarios.

Searching arXiv for the primary Mergiraf paper and closely related merge-tool work to ground the article. Mergiraf is a generic structured merge tool intended to bring the accuracy of structured merge to any programming language with minimal per-language effort. In the evaluation reported in "LastMerge: A language-agnostic structured tool for code integration" (Duarte et al., 25 Jul 2025), it is presented as a generic re-implementation of Spork that operates over a language-independent Tree Sitter Concrete Syntax Tree (CST), uses a thin configuration interface for language adaptation, and combines unstructured fallback logic with structured matching and amalgamation.

1. Design objective and problem setting

Mergiraf is motivated by a long-standing limitation of unstructured, line-based merge tools such as diff3 and git-merge. These tools are fast and language-agnostic, but they report many spurious conflicts, described as false positives, and miss real conflicts, described as false negatives. Fully structured, AST-based merge tools reduce false positives and detect more real conflicts, but they are tightly coupled to a given language grammar or AST, expensive to implement and maintain per language, and therefore available for only a handful of languages (Duarte et al., 25 Jul 2025).

Against that background, Mergiraf targets a specific design point: a structured merge engine that remains language-agnostic at the core and delegates only a small amount of language-specific behavior to configuration. The stated goal is to bring the accuracy of structured merge to any programming language with minimal per-language effort. It does so by relying on Tree Sitter, described as an ecosystem of more than 350 language grammars that produce a generic CST, together with a thin configuration interface that specifies which nodes are unordered, how identifiers are extracted, and, optionally, how the CST is rewritten before merging (Duarte et al., 25 Jul 2025).

A central implication of this design is that Mergiraf is not merely a parser front-end wrapped around a line-based merge. Its purpose is to preserve the main advantages of structured merge while avoiding language-specific reimplementation of the full merge algorithm.

2. Merge pipeline and algorithmic structure

Mergiraf’s merge pipeline is adapted from Spork’s algorithms, but applied to a language-independent Tree Sitter CST. The pipeline has three major phases: auto-tuning, structured matching, and structured amalgamation (Duarte et al., 25 Jul 2025).

The first phase, auto-tuning, implements fallback logic. Mergiraf first attempts an unstructured, line-based merge, essentially diff3. Only if that pass produces a conflict does it fall back to the structured engine. This design serves two roles in the reported system: it speeds up common clean merges, and it also affects the distribution of added false positives and added false negatives observed in evaluation.

The second phase, structured matching, begins by building fictional paired trees only over the conflict hunks reported by the unstructured pass. This allows pre-assigning matches for large unchanged regions. For the remaining nodes, Mergiraf invokes the GumTree matching algorithm, which is reported as $O(n^3)$ in the worst case, to find a maximum bipartite matching between siblings (Duarte et al., 25 Jul 2025).

The third phase, structured amalgamation, reuses Spork’s amalgamation algorithm. The three trees—base, left, and right—are traversed in lockstep. Where one side deletes and the other edits, the system detects a delete/edit conflict. Otherwise, it weaves together non-conflicting edits and may reorder children of unordered nodes as needed. This amalgamation stage is the mechanism by which Mergiraf turns structural alignment into a merged output rather than merely a conflict detector.

3. Language adaptation through the thin configuration interface

All per-language decisions in Mergiraf are driven by a small configuration file plus optional parse-time handlers (Duarte et al., 25 Jul 2025). This configuration model is the principal mechanism that distinguishes Mergiraf from language-specific structured merge tools.

The configuration can declare which nonterminal node kinds are unordered. The Java example in the evaluation includes modifiers and import-lists. It can also specify, for each node kind, how to extract a unique identifier by means of a Tree Sitter S-expression query that binds method names, field names, and related symbols. In addition, an optional parsing handler may rewrite or group subtrees after parsing. The reported Java example merges all import-declaration nodes under a single imports parent so that import reordering is matched correctly.

This interface is deliberately thin: it does not replace the merge engine, but informs it about language-specific equivalence and ordering constraints. A plausible implication is that the engineering burden shifts from implementing a full language-specific structured merger to authoring a configuration layer over a generic engine. The paper’s framing is consistent with that interpretation, though the empirical evaluation itself is limited to Java (Duarte et al., 25 Jul 2025).

4. Evaluation methodology and conflict metrics

The reported evaluation compares Mergiraf to Spork on real merge scenarios and uses a relative notion of disagreement on conflict presence. The dataset contains 5,229 real merge scenarios drawn from 1,116 popular GitHub Java projects, following Schesch et al. 2024. Each scenario is a four-tuple $$(\text{base}, \text{left}, \text{right}, \text{merge-commit})$$ in which both sides made non-trivial changes to at least one file, and both parents build and pass tests (Duarte et al., 25 Jul 2025).

For each scenario and each tool pair, the merge is replayed and the evaluation records whether a conflict was reported, the merged result, and runtime as the average of 9 warm-started runs per file. For each disagreement on conflict presence, the classification of added false positives and added false negatives is performed using syntax-tree matching, with LastMerge’s matcher, and, if needed, test suite execution. The study also manually inspects a random sample of 5 added-false-positive and 5 added-false-negative scenarios per tool to diagnose root causes (Duarte et al., 25 Jul 2025).

The paper defines the usual false-positive and false-negative rates as follows:

$$\text{False Positive Rate} = \frac{\#\,\mathrm{false\ positives}}{\#\,\mathrm{total\ non\text{-}conflicting\ changes}} = \frac{\mathrm{FP}}{N_{nc}}.$$

$$\text{False Negative Rate} = \frac{\#\,\mathrm{false\ negatives}}{\#\,\mathrm{total\ conflicting\ changes}} = \frac{\mathrm{FN}}{N_c}.$$

In the relative setting used for tool-vs-tool comparison, the normalization may instead be restricted to the subset of scenarios where tools disagree on conflict presence. The paper reports absolute added-false-positive and added-false-negative counts and derives percentages over the sample size or over the subset of disagreements. This is important for interpreting the results: the reported percentages are comparative diagnostics between tools, not global estimates of conflict-detection quality over all possible merges.

5. Quantitative results and comparative behavior

In the reported experiment, Spork and Mergiraf disagreed on conflict presence in 601 of 5,229 scenarios, or approximately 12.22% (Duarte et al., 25 Jul 2025). Over those disagreements, the paper reports the following added-false-positive and added-false-negative counts.

Tool	aFP	aFN
Spork	150	107
Mergiraf	290	62

From these counts, the paper derives relative rates over the 601 disagreements. Spork’s relative false-positive rate is approximately $150/601 \approx 25.0\%$, and its relative false-negative rate is approximately $107/601 \approx 17.8\%$. Mergiraf’s relative false-positive rate is approximately $290/601 \approx 48.3\%$, while its relative false-negative rate is approximately $62/601 \approx 10.3\%$ (Duarte et al., 25 Jul 2025).

The result emphasized in the paper is that Mergiraf misses 42% fewer false negatives than Spork, computed as

$\frac{107 - 62}{107} \approx 0.42.$

This identifies the principal comparative strength of Mergiraf in the reported study: relative to Spork, it is less likely to miss real conflicts, even though it incurs more added false positives (Duarte et al., 25 Jul 2025).

The broader paper-level conclusion is correspondingly cautious. It states that there is no evidence that generic structured merge significantly impacts merge accuracy. Although a difference rate of approximately 10% is observed between Java-specific tools and their generic counterparts, most of the differences are attributed to implementation details and are described as avoidable. Within that framing, Mergiraf’s behavior is best understood not as uniformly superior to Spork, but as exhibiting a distinct error trade-off that favors fewer missed real conflicts (Duarte et al., 25 Jul 2025).

6. Runtime, implementation, limitations, and future directions

Mergiraf is implemented in Rust, builds atop Tree Sitter grammars, and reuses Spork’s amalgamation logic together with GumTree’s matching (Duarte et al., 25 Jul 2025). In runtime measurements presented as a raincloud plot over all scenarios on a log scale, Mergiraf and LastMerge have median runtime at less than or equal to 1 second, whereas Spork has median runtime of a few seconds and jDime has median runtime of tens of seconds per scenario. The paper states that both generic tools, written in Rust, run at least $10\times$ faster on average than their Java counterparts; even allowing for a conservative $$(\text{base}, \text{left}, \text{right}, \text{merge-commit})$$0 speed penalty when comparing Rust and Java, LastMerge and Mergiraf still solve approximately 80% of scenarios in under 3 seconds, which the paper characterizes as comparable to state of the art (Duarte et al., 25 Jul 2025).

The paper also highlights a design-specific performance consideration: auto-tuning, meaning the unstructured-to-structured fallback, both speeds up common clean merges and influences the observed difference in added false positives and added false negatives. This indicates that Mergiraf’s performance profile depends not only on the structured engine itself but also on when the structured engine is invoked.

The main limitations stated in the evaluation are that empirical results are reported only on Java, because Spork and jDime support only Java, and that the relative conflict metric depends on test suites and normalization heuristics (Duarte et al., 25 Jul 2025). These constraints matter for interpretation. The claim that the approach is generic rests on the architecture and the Tree Sitter-based configuration model, whereas the quantitative validation is still language-specific.

The future directions listed for Mergiraf include extending the thin configuration interface to other languages, which is described as theoretically immediate for any Tree Sitter grammar; refining matching heuristics, for example to handle renames or generic-argument reorderings via custom parse handlers; and integrating Mergiraf into mainstream version-control workflows for multi-language polyglot codebases (Duarte et al., 25 Jul 2025). This suggests that the research contribution is as much infrastructural as algorithmic: a reusable structured-merge substrate that can be specialized cheaply across languages while preserving the semantics of structured amalgamation.