Branch Map
A full-width visual git graph that turns branches, commits, switches, merges, and syncing into plain-language buttons — with a safety dialog in front of anything destructive.
Overview
The Branch Map is a full-width visual git graph that makes branches approachable even if you have never used git from a terminal. It draws your project's history as labelled lanes — main as the trunk, every other branch as its own lane — and wraps the git commands (branch, commit, switch, merge, push/pull) in plain-language buttons, with a safety dialog in front of anything destructive. Like the Project Log and Session History views, opening it swaps the center panel for the graph.
What You See
A header bar carries a Waypoints icon and the title "Branch Map", a pill showing your current branch, and — when you have uncommitted work — a yellow "N unsaved changes" badge. To the right sit Back (returns to your session) and Refresh buttons.
Below the header are two main areas:
| Area | What it shows |
|---|---|
| Graph canvas (left) | Each branch is a coloured lane. main is the trunk; newer branches split off it as stub lanes. Commits appear as nodes along each lane, newest toward the centre. A commit that has a matching Project Log (changelog) entry shows that summary, so you can read history in plain English instead of hashes. |
| Commit detail rail (right) | Click any commit node to see its message, author, time, and a link to open the full Project Log entry when one exists. Checkpoint rows carry a compact "+a −d" badge summarizing the diff, and the inspector's Changes tab shows the full picture for the selected checkpoint — an "N files · +A −D" summary, a per-file added/removed list, and a side-by-side Monaco diff. A pop-out button opens the same diff in a full-screen modal. |
The map also surfaces a few contextual elements:
- First-visit coaching tip — the first time you open the Branch Map on a repo, a one-time card explains the idea behind branching.
- Conflict banner — if a merge or pull stops part-way on a conflict, a banner appears at the top with guidance to resolve it.
- "Hide Dependabot branches (N)" toggle — repositories with automated dependency-update branches can drown the graph. This per-project toggle (off by default, remembered per project) prunes Dependabot branches and their lanes from the map.
The coaching card sums up the whole idea: "A branch is a safe space to try changes without touching main — the version you're happy to ship. When an experiment works, hover its lane and choose 'Make it official' to bring it into main."
How to Open
Click the Branch Map tab (Waypoints icon) at the right end of the session sub-tab bar, after the spacer. It is available for any open project. If the project is not a git repository (or has no commits yet), the Branch Map shows a friendly empty state explaining what to do instead.
User Actions
The action buttons in the header lead with plain language and show the git term in a tooltip:
| Action | What it does |
|---|---|
| New safe space (tooltip "Create a new branch") | Creates a new branch — "a safe space to try changes." Opens a dialog to name it. |
| Save a checkpoint (Save icon, tooltip "Save a checkpoint (commit)") | Opens a commit dialog and can pre-fill a suggested message from your latest changelog headline. Shows the changed-file count, takes accent styling when there is unsaved work, and is disabled with "Nothing to save yet" when there is nothing to save. |
| Sync (Cloud icon) | "Sync with your online backup (push / pull)." Pushes your commits to and pulls updates from the remote. |
Per-branch actions appear when you hover a branch lane in the graph:
| Action | What it does |
|---|---|
| Switch | Move onto that branch. If you have unsaved changes, a dialog offers to save them first instead of losing them. |
| Make it official (merge) | Merge that branch into your current branch. A confirmation dialog names both branches before anything happens. |
| Delete | Remove a branch you no longer need, behind a confirmation dialog. |
Click a commit node to inspect it in the detail rail; click Open in Project Log there to jump to the full changelog entry, or open the Changes tab to review the checkpoint's per-file diff.
Commit, merge & close
For sessions working on their own branch, the session footer offers a purple Merge action that finishes the whole branch in one step. Its dialog — Finish '{branch}' and close? — explains exactly what happens: it commits any unsaved work, merges it into the base branch, then deletes the branch and closes the session. A merge preview runs first; if the merge would conflict or fails, everything aborts safely — nothing is deleted and the session stays open. On success a toast confirms Merged and closed — branch {x} deleted.
States
| State | What you see |
|---|---|
| Loading | "Reading your branches…" with a spinner. |
| Not a git repository | An empty state explaining the project isn't version-controlled yet. |
| No commits | An empty state prompting you to make your first checkpoint. |
| Error | An empty state with the underlying git error detail. |
| Ready | The graph, detail rail, and action bar are shown. |
| Conflict in progress | The conflict banner stays above the graph until you resolve it. |
Configuration
There are no dedicated settings. The Branch Map reads the same git state as the sidebar Git Status Card and links commits to the changelog entries shown in the Project Log. Commit-to-changelog linking is most useful with the changelog feature enabled (Settings → Changelog).
Keyboard Shortcuts
There is no dedicated keyboard shortcut (on either macOS or Windows). Open the Branch Map from its sub-tab button in the session sub-tab bar.
Tips
- Branching is the safe way to experiment. Make a branch, let your coding agent try a risky change there, and if it doesn't work out you can delete the branch without ever touching
main. - "Make it official" is just a merge. Use it once an experiment on a branch is working and you want it to become part of the shippable version.
- The destructive actions are all guarded. Switch with unsaved work, delete, and merge each sit behind a confirmation dialog, so it is hard to lose work by accident — but saving a checkpoint (committing) regularly is still the best safety net.
Related Articles
- Git Status & Version Control — The sidebar card that reads the same git state
- Project Log — The changelog entries the Branch Map links commits to
- Sessions & Session Management — A sibling center-panel view you can swap back to
- Settings Reference — Enable the changelog that powers commit summaries