HEDDLE

Guide

Bridging back to Git

Your team's PR workflow, CI, and code-host integrations don't have to change. The Heddle bridge takes resolved states and writes them as Git commits in a bare repo; push that to your code host and the rest of your team sees ordinary Git history. The Heddle thread is the underlying truth; the Git commit is what GitHub renders.

1. Check the bridge state

heddle bridge git status reports the repository mode, the mirror state, and whether any Git branches are live only on the Git side and need import.

First look at the bridge

bash$ heddle bridge git statusRepository mode: git-overlay (git+heddle-sidecar)Mirror: .heddle/git (not initialized — run `heddle bridge init`)Git import: in sync

On a freshly adopted repo the mirror isn't initialised yet. Initialise it before the first export:

Initialise the local Git mirror

bash$ heddle bridge git initInitialized Git mirror at: /Users/me/my-repo/.heddle/git

2. Export to a bare Git repo

heddle bridge git export --destination <path> writes every reachable state into a bare Git repo at the destination. Threads become branches; markers become tags. Sign the work you intend to ship before exporting — the signature lands in the commit trailer.

Export to a bare repo

bash$ heddle bridge git export --destination /tmp/heddle-export.git[ok] exported 47 states to /tmp/heddle-export.git  threads: 12 synced to branches  markers: 3 synced to tags

3. Push to your code host

Once the bare repo at the destination contains the branches and tags you want, push them to your real Git remote with heddle bridge git push. The default remote is origin; pass a different remote as a positional argument if needed.

Push the bridged branches to origin

bash$ heddle bridge git pushPushing to origin: refs/heads/task/biscuit-authzPushing to origin: refs/tags/v0.4.2Pushed: 1 branch, 1 tag

From here the PR workflow is whatever your team already uses — open a PR against the Heddle-exported branch, reviewers see the diff, CI runs against the Git ref. The fact that the work was done in Heddle is invisible to a Git-only viewer; reviewers who want the messy middle can open the linked Heddle thread.

4. Bidirectional sync

If your repo is collaborated on by both Heddle and Git-only users, the bridge can sync both directions in one step. heddle bridge git sync --path <path> exports Heddle states then imports any new Git commits the other side has made.

One-shot bidirectional sync

bash$ heddle bridge git sync --path /tmp/heddle-export.git[ok] synced Git overlay  exported: 4 states  imported: 2 commits  threads: 14 synced with branches  markers: 3 synced with tags

5. Importing teammates' branches

When a teammate pushes Git history that wasn't produced by Heddle, you'll want to bring it into Heddle as adopted captures. heddle bridge git import walks local branches and tags from a source path or URL; scope to specific refs with --ref.

Import a specific branch from a teammate's checkout

bash$ heddle bridge git import --path ../their-checkout --ref refs/heads/feature/auth[ok] imported Git history from ../their-checkout  commits: 18 commits  states: 18 states created  branches: 1 synced to threads

A note on drift

If a Git-side rebase rewrites history that Heddle had already exported, the bridge detects it on the next status and surfaces a recommended action. The recommended action is almost always "import the rewritten history as a new branch and pick what you want from each." Heddle never silently absorbs a rewrite — that would violate the immutability story.

Next

  • Git overlay — the conceptual model: repo layer not tool layer, what lives in .heddle vs .git.
  • heddle bridge git — the full 9-subcommand reference.
  • Reviewing a task — what comes before bridging: sign the resolved state.