Every developer has experienced the cold dread of a git merge conflict on a Friday afternoon. You open the file, and there it is: a chaotic mess of <<<<<<< HEAD, =======, and >>>>>>> branch-name. You stare at the screen, trying to figure out if your teammate’s new helper function is supposed to go before or after your modified error handler.
For decades, we’ve accepted this friction as the cost of doing business. But why? The tools we use to collaborate—namely Git and the diff engine under its hood—treat our beautifully structured code as nothing more than a sequence of flat, dumb lines of text. Our compilers and interpreters understand that code is a rich, multi-dimensional tree of syntax, but our version control tools are still stuck in the 1970s.
Enter Weave, an open-source project that is turning heads on Hacker News. Weave represents a paradigm shift: merging code based on language structure (Abstract Syntax Trees) rather than raw lines of text. Today, we’re going to dive deep into why line-based merging is failing us, how AST-based merging works under the hood, and how tools like Weave are about to make merge conflicts a relic of the past.
The Fundamental Flaw of Line-Based Merging
To understand why Weave is a big deal, we first need to look at how Git currently handles merges. Git relies on algorithms like Myers' diff algorithm. At its core, this algorithm looks at two versions of a file and finds the longest common subsequence of lines. It calculates the minimum number of line insertions and deletions to turn File A into File B.
This is incredibly efficient, but it is completely blind to the semantics of programming languages. To Git, a JavaScript function declaration, a Python indentation block, and a CSS rule are all just arbitrary strings of characters ending in a newline character.
A Real-World Example of a "Dumb" Merge
Consider a simple scenario where we have a module exporting a configuration object. Here is our original code on the main branch:
const config = {
port: 8080,
host: 'localhost'
};Developer Alice creates a branch to add a logging flag. She adds it to the end of the object:
const config = {
port: 8080,
host: 'localhost',
enableLogging: true
};Meanwhile, Developer Bob creates a branch to add an API key. He also adds it to the end of the object:
const config = {
port: 8080,
host: 'localhost',
apiKey: 'secret_123'
};When Git tries to merge Alice and Bob's branches, it looks at the exact lines that changed. Because both developers appended a line to the same block, Git flags a merge conflict. It doesn't realize that in JavaScript, properties inside an object literal can generally be defined in any order. The structural intent of both developers is perfectly compatible, yet human intervention is required to resolve it.
Enter Weave: Merging by Language Structure
Weave approaches this problem by replacing the traditional line-based diff engine with a semantic, syntax-aware engine. Instead of comparing lines of text, Weave parses the source code into an Abstract Syntax Tree (AST).
An AST is a tree representation of the abstract syntactic structure of source code. Each node in the tree denotes a construct occurring in the source code. For example, a variable declaration, an if statement, or a function argument are all represented as nodes.
How the AST Merge Pipeline Works
When you merge with Weave, the process looks radically different from a standard git merge:
- Parsing: Weave uses language-specific parsers (often leveraging robust tools like Tree-sitter) to convert the base file, source branch file, and target branch file into three separate ASTs.
- Diffing the Trees: Instead of comparing lines, Weave runs a tree-differencing algorithm. It identifies which nodes have been added, deleted, moved, or modified relative to the parent nodes.
- Three-Way Semantic Merge: The engine applies the structural changes from both branches to the base AST. Because the engine knows that
apiKeyandenableLoggingare simply independent sibling nodes inside anObjectExpressionnode, it merges them seamlessly without causing a conflict. - Serialization (Code Generation): The merged AST is printed back into source code text, preserving format and style guide rules.
Here is a conceptual diagram of how Weave processes a merge compared to traditional Git:
Traditional Git:
[File A (Lines)] \
--> [Line-by-Line Diff] --> [Manual Merge Conflict]
[File B (Lines)] /
Weave Engine:
[File A] -> [Parser] -> [AST A] \
--> [AST Diff & Merge] -> [Merged AST] -> [Code Generator] -> [Merged File]
[File B] -> [Parser] -> [AST B] /
Why This Changes Everything for Developer Velocity
The benefits of structural merging extend far beyond avoiding simple comma placement conflicts. It unlocks a whole new level of developer tooling capabilities.
1. Fearless Refactoring and Code Reordering
Have you ever spent hours refactoring a codebase, moving helper functions to the bottom of a file to improve readability, only to have your merge request blocked by massive, unresolvable conflicts because someone else modified one of those functions in the meantime?
With line-based diffs, moving a block of code looks like a massive deletion in one place and a massive insertion in another. Git loses the connection between the old location and the new one. Weave, however, recognizes that the function node was simply relocated. If another developer modified the internal logic of that function, Weave can apply those logic changes directly to the function node at its new location.
2. Eliminating Formatting Conflicts
We've all been there: Developer A uses Prettier, Developer B's editor auto-formats on save with slightly different rules, and suddenly a merge request shows 300 changed lines when only one line of actual logic changed. Because Weave operates on the AST level, purely aesthetic changes—like double quotes vs. single quotes, or trailing commas—do not affect the logical tree structure. Weave can ignore formatting noise entirely and output the merged file according to your project's defined style guide.
3. Intention-Preserving Merges
Let's look at a classic semantic bug that line-based merges easily permit. Imagine we have a critical safety check in a function:
function processPayment(user, amount) {
if (!user.isVerified) {
throw new Error("Unauthorized");
}
gateway.charge(amount);
}Developer A optimizes the check, changing it to a faster inline validation. Developer B, working on a different feature, adds a new logging statement right below the original check. A line-based merge might successfully auto-merge these changes because they happened on adjacent lines. However, the resulting code could easily end up executing the charge before the validation is run, or bypassing the validation entirely due to misaligned braces.
An AST-based merger understands the execution block boundaries. It ensures that the dependency of the payment charge on the validation block is structurally preserved.
The Technical Challenges of AST Merging
If structural merging is so superior, why hasn't it been the default for the last twenty years? The truth is, building a robust AST-based merge engine is incredibly difficult. Weave has had to solve several major computer science and engineering challenges to make this viable.
1. Language Heterogeneity
For Git to work, it only needs to know how to read text. It works identically for Rust, Python, HTML, and Markdown. An AST-based merge engine, however, must understand the syntax rules of every language in your repository.
Weave tackles this by leveraging Tree-sitter, an incremental parsing library that can build concrete syntax trees for almost any programming language quickly and robustly. By building on top of Tree-sitter, Weave gains out-of-the-box support for dozens of languages, ensuring that the tool isn't locked into a single ecosystem like JavaScript or Go.
2. Syntax Errors and Incomplete Code
What happens if a developer commits code that has a syntax error? A traditional compiler will fail to build an AST and throw an error. If your merge tool can't parse the code, it can't merge it.
Weave’s parser is designed to be highly fault-tolerant. When encountering invalid syntax, it doesn't crash; instead, it performs local recovery, parsing the valid parts of the file into AST nodes and falling back to line-based raw text representations for the broken sections. This ensures that even during chaotic, broken-state refactoring phases, the merge tool remains functional.
How to Try Weave in Your Current Workflow
One of the best design choices of Weave is that it doesn't require you to abandon Git. It is designed to integrate directly into Git as a custom merge driver.
You can configure Git to use Weave for specific file types by editing your .gitattributes and local .git/config files. Here is a quick look at how you can set it up once Weave is installed on your system:
First, register the driver in your global or project-specific Git config:
[merge "weave"]
name = Weave AST-based merge driver
driver = weave merge %O %A %B %LThen, tell Git to use Weave for your JavaScript and TypeScript files by adding the following to your project's .gitattributes file:
*.js merge=weave
*.ts merge=weave
*.tsx merge=weaveWith this configuration, whenever you run git merge or git rebase, Git will automatically defer to Weave to resolve conflicts in your JS/TS files using syntax-tree analysis, falling back to its default Myers algorithm only if Weave encounters an unparseable file.
Conclusion: The Semantic Developer Toolchain
Weave represents a broader trend in developer tooling: the transition from text-based processing to semantic-based processing. We are seeing this shift in our IDEs, our security scanners, and now, our version control systems. By treating code as the structured, logical tree that it is, rather than flat text on a screen, we eliminate an entire class of human error and workflow friction.
The next time you're stuck resolving a tedious merge conflict that your computer should have been smart enough to handle, remember that the era of the text-only diff is coming to an end. Projects like Weave are paving the way for a more intelligent, collaborative, and developer-friendly future.
What do you think?
Are you ready to hand over your merge resolutions to an AST parser, or do you prefer the predictable simplicity of line-by-line diffs? Have you tried integrating custom merge drivers in your CI/CD pipelines? Let's discuss in the comments below!