# Aura Is Not a Git Killer

*Aura works on top of Git, or without it. It does not replace Git, and it was never designed to.*

> "Every few years somebody announces the Git killer. Mercurial, Pijul, Fossil, jj, Sapling. Some are excellent tools. None of them killed Git. I'm tired of the genre."

This is the single most important page in the Aura documentation. If you read nothing else, read this.

## The Concern

The skeptic's argument is simple and correct: Git won because it solved distributed version control well enough that the switching cost for a working team is almost never worth the gain. Anyone who shows up claiming to replace Git is either ignoring that switching cost, ignoring the network effects of GitHub, or is about to spend five years rebuilding Git features and slowly become a worse Git.

The graveyard is long. Pijul has beautiful theory (patches as a commutative algebra) and a tiny user base. Fossil is used almost exclusively by the SQLite team that built it. jj is genuinely interesting but relies on a Git backend in practice. Sapling is Meta's internal tool that Meta happily admits sits on a Git-compatible storage layer for the parts that leave Meta.

If Aura is "the next one of those," you should close this tab.

## How Aura Handles It

Aura is not in that genre. Aura is a **semantic layer on top of Git**. The mental model we ask you to carry is:

- **tree-sitter is to text parsing** what
- **Aura is to version control.**

tree-sitter did not replace regex. It sits above the text and gives you a syntax tree, which unlocks capabilities that text tools cannot reach. Aura sits above Git and gives you a semantic graph of functions, types, intents, and relationships. Git still stores bytes. Aura understands what those bytes mean.

Concretely, here is what happens when you use Aura on a normal repository:

```bash
aura init              # initializes inside an existing git repo
aura save "fix: retry" # creates a snapshot + logs intent
                       # and calls `git commit` under the hood
aura push              # runs `git push` to your normal remote
```

`aura save` is a real `git commit`. `aura push` is a real `git push`. Your GitHub, your GitLab, your Gerrit, your internal git mirror — all of them keep working. A teammate who does not install Aura can still clone, branch, review, and merge your work using `git` alone. They will miss the semantic layer, but they will not be blocked.

This is a deliberate choice. We made it for three reasons.

### 1. Adoption cost dominates theoretical elegance

A tool that requires your entire company, your CI, your auditors, your GitHub Actions, your Dependabot, and your on-call engineer at 3 a.m. to all switch at once will not be adopted. Aura is designed so that one developer on a team can turn it on, benefit from it, and introduce it to their teammates gradually. Two weeks of observer mode, then opt-in hooks, then team-wide intent tracking. See [migration reality check](/migration-reality-check) for the actual timeline.

### 2. Git is correct for a lot of the stack

Git's content-addressed object database is excellent. Merkle DAGs for history are excellent. `git bisect` across a decade of commits is excellent. These are solved problems and we have no interest in resolving them. Aura reuses Git's storage when Git is present, and reimplements the subset it needs when Git is absent. We are not in a hurry to rewrite the parts of Git that already work.

### 3. The interesting problems are above the text layer

The problems we care about — function identity across renames, AST-aware three-way merge, intent-versus-diff verification, agent coordination, cross-branch impact alerts — are problems Git cannot see because Git is a text tool. Those problems are where Aura lives. They are complementary to what Git does, not competitive with it.

## Shadow Branches Mirror Git Branches

Inside an Aura-managed repo, every Git branch has a corresponding "shadow branch" in Aura's semantic store. When you `git checkout feature/auth`, Aura loads the semantic state for that branch. When you `git merge main`, Aura runs its AST-aware merge in parallel and surfaces any semantic conflicts that the textual merge would hide. See [AST merge](/ast-merge).

The shadow branch has no independent identity. It is strictly a function of the git branch it mirrors. If you delete the git branch, the shadow branch goes with it. If you rename the git branch, Aura follows. If a collaborator without Aura pushes new commits to the branch, the next developer with Aura installed backfills the shadow branch from those commits automatically.

This is what we mean by "on top of Git." Not adjacent. Not parallel. On top.

## Standalone Mode Exists, and It Is Opt-In

There is one exception: `aura init --no-git`. This creates a repository that does not have a `.git` directory and does not shell out to `git`. Aura runs its own content-addressed store, its own branching, its own push/pull to a [Mothership](/mothership-overview).

We ship this mode because a small number of users have asked for it: greenfield projects with no legacy, teams building agent-heavy codebases where the AST is the primary artifact, and a few research groups who want to experiment with a Git-free world. It is a legitimate mode, but it is not the default and we do not recommend it for production codebases today. Tooling, hosting, code review integrations, auditor familiarity — everything outside Aura assumes Git. Standalone mode is a research frontier, not a drop-in replacement.

If you are reading this page to decide whether to adopt Aura, adopt the Git-compatible mode. Do not adopt standalone mode unless you have a specific reason and a tolerance for roughness.

## The Tagline, Carefully

> Aura works on top of Git, or without it.

Notice what that sentence does not say. It does not say Aura replaces Git. It does not say Aura is better than Git. It says Aura works on top of Git (the default) or without it (the opt-in). Both are true statements about the software. Neither is a claim of superiority over the substrate.

We have been deliberate about this because the "Git killer" framing costs trust with exactly the engineers we want using Aura: senior developers, platform teams, people who have survived migrations. If that framing is anywhere in our copy, please open an issue and we will fix it.

## What Aura Does Not Solve

Aura does not solve any of the things people actually use GitHub for: pull requests as a social artifact, code review UI, issue tracking, org-level permissions, SSO, Dependabot, GitHub Actions. Those are features of GitHub-the-platform, not of Git-the-tool, and Aura is not in the platform business. If your team's workflow is "open a PR, get two reviews, merge via the GitHub web UI," your workflow does not change when you adopt Aura. Aura adds a semantic layer; it does not remove the layers you already have.

Aura also does not solve the problem of history that predates Aura. A repo with ten years of Git commits gets a semantic backfill when you run `aura init`, but function identity for heavily renamed or refactored code from 2016 will be ambiguous. See [migration reality check](/migration-reality-check) for what that looks like in practice.

And Aura does not solve the problem of a team that simply does not want another tool. We will not pretend otherwise. If your team is productive on plain Git and your pain points are elsewhere, Aura is not obligatory. See [when not to use Aura](/when-not-to-use-aura).

## A Note on the Other Good Tools

Pijul, jj, Sapling, Fossil, Spork, astii, mergiraf — these are legitimate tools solving legitimate problems, and several of them have ideas we learned from. jj's operation log influenced how we think about undo. Sapling's stacked diffs shaped how we think about dependent changes. mergiraf's tree-sitter-based merge is adjacent to work we do in [AST merge](/ast-merge).

None of these tools are Aura's competitors in the strict sense, because Aura is not trying to replace the version control layer. We sit above it. If you are already happy on jj or Sapling, Aura can sit on top of those too — anything that exposes a git-compatible interface works.

## The Honest Tradeoff

The tradeoff of being a layer on top of Git is that we inherit Git's limitations. We cannot fix Git's weirdness around large binary files (LFS helps, LFS is also a known pain). We cannot make `git rebase` less dangerous on shared branches. We cannot replace Git's text-based conflict markers with something nicer without either intercepting the merge driver (which we do, carefully) or asking users to run `aura merge` instead of `git merge` (which we also do, opt-in). Every layered architecture has this tax. We pay it in exchange for the ability to be adopted.

If you want a version control system designed from scratch with modern theory, use Pijul. It is a better system in several narrow ways and we respect it. If you want a version control system that your auditor, your CI provider, your GitHub org, your IDE, your new hire, and your bash muscle memory all already understand — use Git, and put Aura on top of it.

## See Also

- [Code is not Figma](/code-is-not-figma) — why character-level real-time editing is wrong for code
- [AST merge](/ast-merge) — the semantic merge layer that sits above Git's 3-way merge
- [CRDT vs AST merge](/crdt-vs-ast-merge) — the architectural choice in detail
- [Offline and reproducibility](/offline-and-reproducibility) — what Git gives you and what Aura preserves
- [When not to use Aura](/when-not-to-use-aura) — the honest list
- [Migration reality check](/migration-reality-check) — adopting Aura on a legacy repo