The history model: HEAD, checkout, and forks
Merget's history is a graph you can stand anywhere inside. This page explains the small set of ideas that make time-travel predictable: where you're standing (HEAD), how you move (checkout), what happens when paths split (forks and merges), and how you name places you want to come back to (bookmarks).
HEAD: where you're standing
HEAD is your current position in history — the point your working files reflect. It's always in exactly one of four states, and the Map shows you which:
| State | Meaning | What committing new work does |
|---|---|---|
| Active | You're at the tip of a prompt. The normal state. | Extends the line: the new step becomes the new tip. |
| Initial | You're on a brand-new prompt with no steps yet. | Creates the prompt's first step. |
| Detached | You're standing on a specific step - after checking out a bookmark, an old step, or a fork point. | Starts a fork: a new line of work growing from that step. |
| Empty | A fresh repo with no active goal yet. | Nothing commits until a goal exists (your first session creates one). |
On the map: Active is the filled indicator on a goal's tip; Detached is the hollow checkout marker sitting mid-edge.
Checkout: moving through time
Checking out (right-click on the Map, or merget checkout in the CLI — including merget checkout <bookmark>) rewrites your working files to match the chosen
point.
Two rules keep it safe:
- Uncommitted changes block checkout. If tracked files have been modified since the last step, checkout refuses with a "worktree dirty" error instead of overwriting your work.
- Untracked files survive. Files Merget has never committed are left alone.
Checking out a goal's tip puts you in Active; checking out anything else — a bookmark, an old step, a fork point — puts you in Detached.
Forks and merges
History doesn't have to be a straight line. If you (or a teammate, or a second agent) commit work from a detached position, a fork begins — two lines of work growing from the same step. The map marks these split-and-rejoin points with fork nodes.
Forks rejoin through a merge: pick two goals, combine their work, resolve any conflicts, and the map shows the lines converging again.
Bookmarks: names for places
A bookmark is a name pointing at a step -
"before-the-big-refactor", "demo-friday". The bookmarks you create are passive: they stay where you put them until you move them. Two are built in: latest follows the newest prompt automatically, while main/trunk marks your
stable point and moves only when you move it. Checking out a bookmark detaches
you at its step; it's a teleport, not a subscription.
If you're coming from Git: a bookmark is like a branch ref that doesn't follow you. You move it deliberately ("set bookmark to this goal's latest step") rather than it advancing on every commit.
Under the hood
Every step references its parent step, which makes history a directed acyclic
graph of steps; goals and prompts are the human-meaningful grouping drawn over
it. All objects (file contents, trees, goals, prompts, steps) are
content-addressed - each ID is derived from the object's own content. Bookmarks and
goal tips are named references stored inside the repo's .merget/ folder, each
just a name pointing at an object ID. That's the entire trick: immutable
content-addressed objects, plus a handful of movable names.
Next: Merget and Git | Related: Navigating history | Bookmarks | Merging goals