HEDDLE

Guide

Getting work back to Git

Your team's PR workflow, CI, and code-host integrations don't have to change. Which commands you use depends on one thing: whether Git is still the source authority. In Git Overlay it is, and the answer is two commands you already know. In Native Heddle it isn't, and Git becomes a projection you write out.

Which mode am I in?

heddle status answers it, and creates nothing while doing so. It reports the repository capability and storage model, and prints the next safe command.

The safe first question

bash$ heddle status# or, for the structured answer:$ heddle status --output json$ heddle doctor --output json

In Git Overlay — what heddle init gives you inside an existing checkout — the checkout's real .git owns commits, refs, packs, the index and worktree state, and .heddle holds captures, provenance, threads, readiness and review. In Native Heddle, reached deliberately via heddle adopt, Heddle owns source authority and the retained .git is an explicit projection.

Git Overlay: commit, then push

This is the common case, and it is short. heddle capture records the Heddle state; heddle commit publishes the captured tree into the authoritative Git checkout; heddle push sends it to your remote. From there the PR workflow is whatever your team already uses.

The whole Git Overlay round trip

bash$ heddle capture -m 'wire datalog scope rules'$ heddle commit$ heddle push

A normal push writes refs/heads/<thread> and refs/notes/heddle. --all-threads writes every thread branch and every local Git tag as well. The JSON output lists what moved in refs_written, which you can check against git ls-remote from any Git client.

Push declares its exit codes, and the distinction matters if you are scripting it: 75 means the remote was unreachable and the same call is safe to retry; 76 means the remote rejected the payload and retrying unchanged will fail identically. See Exit codes.

Native Heddle: export a bare Git repository

When Heddle owns source authority, you project history out rather than committing into a checkout. heddle export git -d <path> writes, verbatim from its own help, a complete bare Git repository at --destination containing every reachable Heddle state as a Git commit, with branches and tags mirroring Heddle's threads and markers. The destination must be writable, and is initialised as a bare repo if it does not already exist.

Project the whole reachable graph into a bare repo

bash$ heddle export git --destination /tmp/heddle-export.git

Importing history the other way

heddle import git brings Git commits into Heddle. It walks local branches and tags by default; to import remote-tracking refs you name them explicitly with --ref, which is repeatable. --lossy accepts Git tree entries Heddle cannot represent losslessly, rather than refusing them.

Import one branch from another checkout

bash$ heddle import git --path ../their-checkout --ref refs/heads/feature/auth

heddle sync git --path <path> does both directions in one step — export followed by import. It declares the same 75/76 exit contract as push.

What a Git-only collaborator does not get

This is the part that surprises teams. Context annotations and discussions are a native Heddle feature: they travel over heddle push and heddle pull to a Heddle remote, and they are not projected into Git. Someone who git clones the repository gets the source history and no Heddle store.

And the failure mode is quiet rather than loud: in that clone, heddle context list reports that no store is present — not that there are no annotations. Those are different answers, and an agent that treats them as the same will conclude the reasoning was never written.

When Git and Heddle disagree

Heddle never silently absorbs a Git-side rewrite; that would violate the immutability story. If it detects an externally-started Git sequencer operation — a git rebase or git merge begun with another client — it leaves Git metadata, refs, index and worktree files unchanged and reports a preservation command. Finish or abort that operation with the client that started it, then run heddle verify.

For projection metadata that has genuinely diverged, heddle fsck repair git --ref <branch> reconciles it, and --preview shows the authority-valid repair without moving anything. --prefer git or --prefer heddle asserts the intended direction.

Next