Git overlay

Why an overlay

The honest answer: because Git won and we know it. Replacing Git is a 10-year project even if your protocol is better; Heddle's bet is that you don't have to replace Git to add what Git is missing. The overlay sits underneath your existing workflow (your GitHub PRs, your CI, your code-host integrations) and adds the agent-work record on top.

Concretely: a repo with Heddle initialised is still a Git repo. git status works. git push works. Your team members who haven't installed Heddle keep working in Git, none the wiser. The Heddle data is in .heddle/: additive, opt-in, ignorable.

Adopt mode

The default. heddle init in an existing Git repo enters adopt mode: Heddle reads the current branch, treats it as the main thread, and starts recording captures from here forward. The Git history before this point is preserved untouched and visible from Heddle as a single starting state.

Adopt an existing Git repo

bash$ cd my-repo$ heddle initInitialized Heddle data in /path/to/my-repo/.heddle for Git-overlay workflowsSide effects:  - created Heddle sidecar for the existing Git repository  - updated .git/info/exclude for Heddle metadata  - left Git-tracked files untouched

Standalone mode

For new repos that don't need Git, run heddle init in a directory without a .git/ beside it: Heddle detects the absence of Git and initialises a standalone Heddle repository. No .git/ directory is created, no Git semantics apply. The repo can be bridged to Git later if needed: heddle bridge git init initialises a Git mirror, optionally against an existing Git repository with --path.

The bridge

Day-to-day you don't reach for it; heddle commit already writes through to .git/. heddle bridge git is the explicit surface for the bigger moves: materialise a full bare mirror somewhere else, pull external Git history in, or reconcile a divergence. It's two-way:

• Export. heddle bridge git export -d <path> writes a complete bare Git repository at the destination: every reachable Heddle state becomes a Git commit, threads map to branches, and markers map to tags. It's a full mirror, not a single commit; the single reviewable-commit boundary is heddle commit / heddle land.
• Import. heddle bridge git import brings external Git commits in as adopted captures. Useful when a teammate without Heddle pushes work to the same branch.
• Status. heddle bridge git status shows the relationship between Heddle's threads and the bridged Git refs: what's exported, what's pending, what's diverged.

What lives where

The honest mental model:

• .git/: Git's storage. Commits, refs, packed objects. In Git-overlay mode Heddle writes through here: heddle commit lands a real Git commit and advances .git/HEAD (atomically), so a plain git log shows your work with no export step. What Heddle keeps out of .git/ is its own metadata, so your Git history stays clean.
• .heddle/: Heddle's storage. Captures, states, threads, contexts, the oplog. It also holds .heddle/git/, a Heddle-managed Git mirror that carries the extra fidelity (state-metadata commits, managed refs) that would otherwise pollute your real .git/. Self-contained; you can blow it away with rm -rf .heddle and Git keeps working (you lose the Heddle record, not the code).
• The working tree: shared. Both Git and Heddle see the same files. A capture and a commit can both be taken from the same working tree; they record different things about it.

Round-trip semantics

The normal loop never needs an explicit export: heddle commit already wrote the Git commit into .git/, so you just heddle push to GitHub, merge the PR, and pull back. Because Heddle states are content-addressed, a tree that round-trips through Git and back lands on the same underlying content; the round-trip is stable. (Heddle's hd- state IDs are minted fresh per capture and aren't the thing that's preserved; the content address is.) Git ↔ remote ↔ Git can cycle without drift.

Drift can happen if a Git-side rebase rewrites history that Heddle had already exported. The bridge detects this and surfaces it via heddle bridge git status with a recommended action. The recommended action is almost always "import the rewritten history as a new branch and pick what you want from each."

The commands

• heddle init: adopts an existing Git repo, or initialises standalone when no .git/ is present.
• heddle bridge git: status, init, export, import, sync, and reconcile, among others.

Next: the oplog for what Heddle records about the bridge operations themselves, or namespaces for how multiple bridged repos compose into one organisational structure.