Branches

Development reference · View source

Space g b opens one read-only list, Local first and Remote second:

Local
  feature [↑1] [worktree: /home/me/project-feature]
* main    [↑2 ↓1] [worktree: /home/me/project]
  spike

Remote
  origin/feature   [tracked by: feature]
  origin/main      [tracked by: main]
  origin/review/42 [not tracked locally]

Key	Action in the list
`Enter`	Check out this local or remote branch locally
`Tab n`	Start a new branch here and switch to it
`Tab w`	Create a worktree for this branch; attach in mux mode
`Tab d`	Compare committed tips with this branch
`Tab D`	Delete this local branch, with its worktree and session, after a confirmation
`Tab f`	Fetch this cached remote branch or this local branch’s upstream
`Tab m`	Review merging this selected branch into the current branch
`Tab p`	Fast-forward the current local branch onto what it tracks
`Tab P`	Publish this local branch to what it tracks

Reading the branch list

* marks the current local branch.
[worktree: ...] names the local path of each registered worktree that has the branch checked out.

Drift is shown in a dimmed column of its own:

Marker	Meaning
`↑N`	N commits the local branch has that its upstream lacks
`↓N`	N commits the upstream has that the local branch lacks
`[=]`	In step
`[gone]`	The upstream ref no longer exists
(nothing)	The branch tracks nothing

Remote rows are remote-tracking refs Git has already cached; opening the list and Space g r do not fetch.
A symbolic default such as origin/HEAD is not a row. Remote names containing / are kept exact.
Each remote row names every local branch whose configured upstream is that exact ref. Equal names or equal tips do not count as tracking; a remote row with no tracker says [not tracked locally].

Checking out

A local row: Enter checks it out.
A remote row: Enter checks out its one local tracking branch. With several, a picker opens. With none, Runyte creates and checks out a tracking branch named after the part after the remote: origin/feature/auth suggests feature/auth. If that name already exists, an editable name prompt opens instead of reusing the unrelated branch.

Refusals and confirmation:

A checkout (and Tab n) is refused while the index or working tree has staged, unstaged, or untracked changes, or an open file buffer in the repository has unsaved edits.
If this workspace owns any live terminal session — visible, hidden, or in another pane — Runyte asks you to type the exact target branch name. That acknowledges the terminal job keeps its directory while Git replaces files under it. Escape or Ctrl-c leaves the checkout unchanged. Exited terminals need no confirmation.
After a checkout, open files that still exist are reloaded from the new branch, and the Git status and gutter bases are refreshed.
Opening another worktree with Space g w is an attachment switch, not a checkout, and does not ask.

Creating and deleting branches

Tab n asks for a name, creates the branch at the selected one, and switches to it. The checkout refusals are reported before the name is asked for.

Tab D first reviews the exact branch tip.

If the tip is kept by the configured upstream or another local branch, Enter confirms, and the confirmation names those branches.
Otherwise you must type the exact branch name.
Upstream reachability uses the locally cached remote-tracking ref, and the confirmation says so. Fetch first if it must include newer remote state.
The final step rechecks the tip and the refs keeping it, so a branch changed after review is not deleted.

A branch checked out in a worktree is not refused. A worktree means nothing without its branch, and a session means nothing without its worktree, so deleting the branch offers to remove all three. The confirmation names every level and always requires the exact branch name:

Delete branch enh/render-space.
This also:
  · stops and forgets session 5 (runyte-enh-render-space)
  · removes worktree /home/me/code/runyte-enh-render-space
Type enh/render-space exactly to continue.
Escape keeps it.

It runs bottom-up: the session stops, the worktree is removed, then the branch is deleted. A failure at any level stops there.
The checkout’s own refusals — a dirty working tree, a lock, a session with unsaved buffers — are reported before you are asked anything.
A branch checked out in more than one worktree, or at the current Runyte root, is still refused before review.

Creating a worktree from a branch

Tab w asks for a destination and creates a checkout of the selected local branch.

A branch already checked out here or in another worktree is refused without forcing a duplicate; the message names the existing path and points to Space g w.
On an untracked remote row, it creates the suggested tracking branch directly in the new worktree. A remote with several trackers asks which to use.
In mux mode the new worktree is attached at once. In ide mode you stay in the current workspace.