Bookmarks: name the places that matter

A bookmark is a name you attach to a step — "the release we demoed," "last known good," "before the big refactor." Once a place in history has a name, you can find it in one click instead of scrolling the Map trying to remember which goal it was.

If you know Git: a bookmark is like a branch ref that doesn't follow you around. A Git branch moves forward every time you commit on it. A Merget bookmark you create stays exactly where you put it while the committing daemon keeps adding new steps; it only moves when you move it deliberately. That makes bookmarks good at the thing branch names are bad at: marking a moment and trusting it to still mean the same thing next month.

Two bookmarks come built in

Every repo starts with two special bookmarks:

• latest points at the newest prompt and advances on its own as you commit, so it always tracks the tip of your current work.
• main (also shown as trunk) marks the stable, production-ready point. It never moves on its own; you advance it deliberately when you decide a point is ready. That manual step is the safeguard, so auto-generated work is never silently marked as production.

Every other bookmark is one you create, and those stay put until you move them.

Creating a bookmark

Right-click a goal on the Map and hover Set bookmark:

• The submenu lists your existing bookmarks. Click one to move it to that goal's latest step — a small "Bookmark moved" confirmation appears.
• Click Add Bookmark to create a new one. A dialog asks for a name and shows the goal's steps in a searchable list; pick the exact step you want the bookmark to point at.

Bookmark names can use letters, numbers, dashes, underscores, dots, and slashes (so release/1.2 works). Each name must be unique — if the name is already taken, the dialog tells you.

The Bookmarks list

The Bookmarks button in the toolbar opens a list of every bookmark in the repo, with a count badge and a search box. Each row shows the bookmark's name and a summary of the step it points to.

• View jumps the Map to the bookmarked step and opens its details, so you can read the diff and transcript or check it out from there.
• The trash icon deletes the bookmark. Deleting a bookmark only removes the name — the step it pointed to stays in history untouched.

The list is sorted so the built-in names surface first - latest, then main/trunk - followed by everything else alphabetically.

Going back to a bookmark

A bookmark is a passive pointer — checking it out is how you actually travel. Use View to jump to the step, then check it out like any other point in history (see Navigating history). Checking out a bookmarked step puts you in the detached state unless that step happens to be the newest one on its line: you're standing at a fixed point rather than on a moving tip, which is exactly what a bookmark is for. New work from there is still committed safely; nothing is overwritten.

Next: Merging goals | Related: Navigating history | The history model