Skip to main content

Stage Changes

Choose changed files for the next commit, stage and unstage them, inspect individual CI checks, and send a failing check to an agent.

Updated
Reviewed

Header and chrome

The header runs left to right:

  • Branch pill: a monospace pill with the current branch, truncated with a tooltip for long names.
  • Protected chip: an amber "Protected" chip when the branch matches a protected-branch pattern. A heads-up that you probably want a pull request rather than a direct push.
  • PR chip: with a remote and a linked pull request (a merge request on GitLab), a chip shows the PR number, its state, and its CI status when that has resolved, such as passing or failing. Clicking it opens the CI checks popover. A "No PR" chip shows when there is a remote but no pull request. With no remote, the chip is hidden. A separate icon button beside it, View pull request #N, opens the PR in your system browser.
  • Diff mode toggle: Working tree or vs the main branch.
  • Refresh button: visible in working-tree mode. It spins during background refreshes.

When Review Hub is presented as a dialog, the dialog header supplies the title and the close control, so the panel does not draw its own: otherwise you would see two "Review & Commit" headings stacked.

The header names the branch, protection status, and review mode
Note
PR detection and CI status need a forge credential configured under Settings > Code forge. A switcher at the top of that tab selects the provider. See Connect and Authenticate for setup.

CI checks

Click the PR chip and a popover lists every check that reported on the pull request. It opens on a one-line verdict, such as 2 failing · 1 required, 3 in progress or All 5 checks passed, with a tally of the rest beneath it. Checks that need attention come first, failures before cancellations and checks waiting on approval, then anything still running. Passed and skipped checks fold behind a Show toggle whenever something else needs reading.

Each row names the check and its outcome, adds Required or Not required where the forge reports it, and carries a link to the check's details page, which is usually its log. The popover reads the checks fresh each time it opens, and Refresh reads them again. A pull request with no checks yet reads Refresh once CI starts.

When something is failing, Send N checks to agent opens the send-to-agent palette so you can pick an agent terminal. What it pastes asks the agent to investigate the failing checks, names the pull request and the worktree, and lists the failing checks as JSON marked as untrusted data rather than instructions. Logs are not included: the prompt tells the agent to fetch them itself, to check they still match the PR's current head, and not to commit, push, merge or rerun CI unless you ask. With no agent terminal open, the popover says to open one and try again.

The built-in GitHub provider supplies individual checks. The built-in GitLab provider supplies the head pipeline's overall status, so its popover offers Open pull request instead of listing checks. The shared view reads the active provider's checks capability, so another in-process plugin forge provider that implements it can supply the same detail.

Failing checks appear first. Refresh their results or send them to an agent.

The file list

The file list is expanded when Review Hub first opens. Hide files (N) collapses it, and Show files (N) restores it. Your choice is remembered per worktree for the session; a fresh launch starts expanded.

Large change sets stay responsive: once the staged and unstaged lists hold 80 files between them, they render only the rows in view. The base-branch list and the diff workspace's file sidebar do the same.

Files split into Staged and Changes. Each section's count chip also carries churn: a green +N for inserted lines and a red −N for deleted lines across that section.

Two staged files are ready for a commit message

File rows

Each row carries a colored status badge, the file path with the directory prefix muted and the filename in normal weight, that file's churn, a Viewed checkbox, and a stage toggle (+ to stage, − to unstage). Plain-click a row to open its diff.

BadgeMeaningColor
MModifiedAmber
AAddedGreen
DDeletedRed
RRenamedBlue
CCopiedBlue
?UntrackedGreen
!ConflictRed
IIgnoredDimmed

Staged files are identified by their section and stage toggle. Generated files are dimmed so they do not compete with hand-written changes for your attention: lockfiles, dist/ and build/ output, .min.js, snapshots, and anything else matching the generated patterns.

Right-clicking a row opens the same file-row menu the worktree card, the file browser, and the diff sidebar use: Open diff, Open file, Open in editor, reveal, a Copy submenu for paths and context, Insert file reference, and an Extensions submenu when plugins contribute items. One menu, four surfaces, so the gesture means the same thing everywhere.

Viewed markers

Tick the Viewed checkbox to mark a file read. The row dims so it recedes while the rest stay prominent.

The marker is shared with the diff workspace: check a file off in either surface and it reads as reviewed in both. Closing Review Hub does not clear them, but a successful commit does. The store, its namespacing and its lifetime are documented once, on the diff workspace.

Empty states are explicit: "Working tree clean", "Nothing staged", and "All changes staged." A filtered list that matches nothing offers a Clear filter action.

Staging files

Click the toggle on an unstaged file to stage it, or on a staged file to unstage it. Each section also has a bulk button that adapts to context. It reads Stage all (N) normally, Stage shown (N) when a filter or the hide-generated toggle is narrowing the list, and Stage selection (N) when you have multi-selected rows. The unstage variants mirror this in the Staged section.

Multi-select

To act on a subset, build a selection first. Command Control Control +click toggles individual rows, and Shift+click selects a contiguous range from the last anchor. Selection is scoped to one section at a time. Selected rows pick up a subtle overlay, and the bulk button switches to Stage selection (N). Press Escape to clear it.

Warning
If a stage or unstage fails, Review Hub shows a small inline error and keeps going. The failure does not block the rest of the list or the composer.

Filtering and view options

Each section header has a filter input. It is glob-aware (*, **, ?, and character classes all work) and falls back to a substring match otherwise, with a short debounce as you type.

Next to the filter is a view-options dropdown:

  • Sort by: Path, Status, or Churn. Pick the same key again to flip the direction.
  • View: Comfortable or Compact density.
  • Show generated files: include or exclude generated files entirely.

These are per session. They reset when you close Review Hub: empty filter, sort by Path ascending, Comfortable, generated files shown.

Reviewing diffs

Clicking a file row, or pressing Enter on a focused one, opens the diff workspace as a second dialog layered over the hub. It arrives seeded with the whole change set, so you can step between every changed file with [ and ] without coming back here.

The change set stays in step with the live poll while the diff is open, and the file the diff is showing follows Review Hub's own selection, including its status. Stage a file while its diff is up and the diff re-fetches under its new status rather than continuing to render the old one.

To read one file's diff without a change set around it, the File Viewer has a Diff view mode of its own, offered whenever the file it is showing has a local change. To compare two separate worktrees against each other, use the cross-worktree diff described in Comparing Worktrees.