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 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.

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 important names surface first: main or master at the top, then trunk, then 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