Guide

Adopting an existing repo

Start with heddle status. It observes the checkout and recommends the next command.

Keep Git as source authority

heddle init adds Heddle metadata to an existing Git checkout. In Git Overlay, heddle capture saves a Heddle state and writes the Git checkpoint in one operation. There is no separate publish step before heddle push.

The Git Overlay loop

bash$ heddle status$ heddle init$ heddle capture -m "why this changed"$ heddle push

Move source authority to Heddle

heddle import local imports selected Git history and switches the repository to Native Heddle. This is an explicit storage transition. Check the selected refs and get human approval before making the one-way change. Afterward, heddle capture saves native history; Git output is an explicit projection.

Explicit native import

bash$ heddle status$ heddle import local --ref main$ heddle verify