Branches

This page covers the refs sidebar on the left of a repository tab and everything you do with branches: checking them out, creating, renaming and deleting them, tracking a remote branch, and cleaning up branches you no longer need.

The refs sidebar

The sidebar lists every reference of the repository in collapsible sections. Each section header shows a count.

Section	Contains	Collapsed by default
Local	Local branches, plus a HEAD row when HEAD is detached or the repository has no commit yet	No
Remote	One folder per remote, with its branches	No
Tags	Tags (an info icon marks annotated tags)	Yes
Stashes	Stashes, by message	No
Submodules	Submodules	Yes
Worktrees	Other worktrees	Yes

Section headers stay visible while you scroll. Expanded and collapsed sections and folders are saved per tab.

Tree or flat list

Branch names are grouped into folders by prefix: feat/graph-lanes sits in a feat folder. Click Flat list of branches at the top of the sidebar to show full names in a single list instead. The choice is saved per tab.

What a branch row shows

• The checked-out branch is highlighted.
• ↑2 ↓5: the branch has 2 commits its upstream does not have, and is 5 commits behind it. See git status for the concept.
• “upstream deleted”: the upstream branch no longer exists on the remote (Git reports it as [gone]).
• A worktree mark when the branch is checked out in another worktree, see Worktrees.
• An eye icon or a target icon when the branch is hidden from, or the only one shown in, the commit graph.

The row of the commit selected in the graph is highlighted too.

Filter the sidebar

Type in Filter refs at the top, or press ⌘⇧R (Ctrl+Shift+R on Windows and Linux) to jump there; it also reopens a collapsed sidebar.

• Separate words with spaces: every word must appear in the name, in any order, ignoring case.
• The filter also matches stash messages, submodule and worktree paths, and the SHA of a detached HEAD. Typing a remote’s name keeps all its branches.
• While filtering, all sections are expanded and the number of matches is shown. No match shows “Nothing matches “…””.
• ↓ or Enter moves to the list. Esc clears the filter.

Mouse and keyboard

Action	Effect
Click a branch, tag or stash	Selects its commit in the graph and scrolls to it. A stash also opens its details on the right.
Double-click a branch	Checks it out
Double-click a tag	Opens the tag checkout dialog
Right-click	Opens the context menu of the row
Drag a local or remote branch onto a local branch	Merge, rebase or fast-forward, see Merge and rebase

With the list focused: ↑ ↓, Home End, Page Up Page Down move; → expands or goes to the first child; ← collapses or goes to the parent; Enter or Space acts like a click (it does not check out); typing a letter starts filtering; ⌘C (Ctrl+C on Windows and Linux) copies the ref name; the context menu key or ⇧F10 opens the menu.

If the references cannot be read, the sidebar shows “Could not read the references” with Retry.

Local branch menu

Disabled items show why. In the labels, current is the checked-out branch (or “HEAD” when detached).

Item	Shown or available	What it does
Check out name	Not on the checked-out branch. Disabled when checked out in another worktree.	Check out the branch
Check out in a new worktree…	Disabled on a branch checked out here or in another worktree	See Worktrees
Create a branch here…	Always	Create a branch at its tip
Create a tag here…	Always	Create a tag at its tip
Reflog	Always	The branch’s reflog, see Reflog
Merge name into current…, Rebase name onto current, Fast-forward current to name	Not on the checked-out branch, and a branch is checked out. Disabled during an operation.	See Merge and rebase
Pull	The branch has an upstream. Works only on the checked-out branch: “Pull only applies to the checked-out branch”.	See Fetch, pull and push
Push	Always	Pushes this branch, see Fetch, pull and push
Rename…	Always	Rename the branch
Set upstream… / Change upstream…	Always	Upstream dialog
Remove upstream	The branch has an upstream	Removes it at once, without confirmation
Delete name…	Disabled on the checked-out branch: “Check out another branch first”	Delete the branch
Hide from the graph / Show in the graph	Disabled on the checked-out branch	See Commit graph
Show only this branch / Show every branch again	Always	See Commit graph
Compare with current	Disabled on the checked-out branch or when HEAD is detached: “Check out another branch to compare with”	See Compare
Compare with…	Always	See Compare
Clean up merged and gone branches…	Always	Branch cleanup
Copy name, Copy SHA	Always	Copies to the clipboard. Toast: “Name copied” or “SHA copied”.

Remote branch menu

Item	What it does
Create a local branch tracking it	Checks out a local tracking branch
Create a branch here…	Create a branch at its tip
Reflog	The remote-tracking branch’s reflog
Merge name into current…, Fast-forward current to name	See Merge and rebase. Rebase is disabled: “A remote branch cannot be rebased”.
Delete on the remote…	Deletes the branch on the remote
Hide from the graph, Show only this branch	See Commit graph
Compare with current, Compare with…	See Compare
Clean up merged and gone branches…	Branch cleanup
Copy name, Copy SHA	Copies to the clipboard

Other rows have their own menus: tags in Tags, stashes in Stash, remotes in Remotes, submodules and worktrees in Submodules and Worktrees. The detached HEAD row offers Create a branch here…, Create a tag here…, Reflog and Copy name.

Check out a branch

To switch to a local branch, do one of:

• Double-click it in the sidebar.
• Double-click its label in the graph.
• Right-click it in the sidebar, then Check out name.
• Pick it in the toolbar’s branch selector.

yaggui runs git switch --no-guess <branch> and shows “Switched to name”. The branch is added to the tab’s recent branches.

• Double-clicking the checked-out branch in the sidebar only shows “name is already checked out”; in the graph it does nothing.
• A branch checked out in another worktree cannot be checked out here; yaggui tells you which worktree has it.
• If files are still in conflict, the checkout is refused: “Some files are still in conflict: resolve them (and stage them) first.” See Conflicts.

Checkout can be undone with Undo (⌘Z, Ctrl+Z on Windows and Linux): yaggui switches back to the previous branch and keeps your local changes. See Undo and redo.

Check out a commit or a remote branch

• A remote branch: double-click it in the sidebar or its label in the graph, or use Create a local branch tracking it. For origin/feat/x, yaggui checks out a local feat/x that tracks it, creating it if needed: git switch --create feat/x --track refs/remotes/origin/feat/x. The toast reads “Created feat/x and switched to it”. If a local feat/x already exists, yaggui checks it out as it is, whatever it tracks.
• A commit: right-click it in the graph, then Checkout this commit. yaggui runs git switch --detach <sha> with no warning and shows “HEAD is now detached at abc1234”. New commits made there belong to no branch: create a branch to keep them.
• A tag: see Check out a tag.

When you have local changes

If you have uncommitted changes to tracked files, yaggui asks what to do with them before switching. Untracked files alone do not trigger the dialog, unless the target branch has files at the same paths.

The Local changes in the way of name dialog lists your changed files (up to 100). Files marked with ! also differ on the target branch: the checkout would overwrite them.

Choice	What yaggui runs
Stash, check out, then pop (default)	git stash push --include-untracked --message="yaggui: before checkout of <name>", then git switch …, then git stash pop --index stash@{0}. If the switch fails, your changes are popped back and the error is shown.
Bring the changes along	git switch …, keeping your changes in the working tree as they are. Unavailable when a marked file differs on the target: “Unavailable: some of your changes touch files that differ on name.”
Cancel	Nothing

When the stash conflicts

If your stashed changes conflict with the new branch after Stash, check out, then pop, the The stash conflicts dialog appears: “The checkout is done, but your stashed changes conflict with this branch. The stash is kept: nothing is lost.” It lists the conflicted files and what to do:

1. Open the conflicted files in the Changes panel and resolve the conflict markers.
2. Stage the resolved files.
3. Once everything is right, drop the stash from the sidebar: it is not dropped automatically.

Click Understood to close it. See Conflicts and Stash.

Switch branches from the toolbar

The branch selector sits at the right end of the toolbar. It shows the current branch, its ↑/↓ counts and upstream, “Detached HEAD at abc1234” when detached, or the branch being rebased during a rebase.

Click it to open a list of all local and remote branches (remote ones have a cloud icon):

• Type in Find a branch… to filter with fuzzy matching.
• Without a query, recent branches come first (badge “recent”), then other local branches, then remote ones. The checked-out branch has the badge “current”.
• Up to 100 branches are listed; beyond, “N more, keep typing to narrow down”.
• ↑ ↓ move, Enter picks, Esc closes.

Picking a branch checks it out; a remote branch gets a local tracking branch. Picking the current branch selects its commit in the graph. The last 12 picked branches are remembered per tab. The selector has no default shortcut.

Create a branch

Open the Create a branch dialog from:

• The toolbar button Branch, the palette action Create a branch…, or ⌘B (Ctrl+B on Windows and Linux): starts from HEAD.
• Create branch here… in the graph’s commit menu: starts from that commit.
• Create a branch here… in the sidebar menu of a local branch, remote branch, tag, stash or detached HEAD.

The dialog shows Starting from and the start point (branch, tag, short SHA or stash@{n}).

1. Type the Branch name (for example feature/my-branch). yaggui checks it as you type:
   • “This name is available.”
   • “A branch named “name” already exists.”
   • “name is not a valid branch name: no spaces, no ~ ^ : ? * [ \, no .., and it cannot start with - or end with /, . or .lock.”
2. Leave Check it out after creating it checked to switch to the new branch, or uncheck it.
3. Click Create and check out (or Create branch).

yaggui validates the name with git check-ref-format --branch, then runs git switch --create <name> <start> or git branch -- <name> <start>. The toast reads “Branch name created and checked out” or “Branch name created”. If you have local changes in the way, the local changes dialog appears.

From a stash, yaggui runs git stash branch <name> stash@{n}: the branch is always checked out, the stash is applied to it, then dropped. If the stash list changed meanwhile, you see “The list changed” and can try again.

Undo deletes the new branch (and switches back if it was checked out). A branch created from a stash cannot be undone.

Rename a branch

1. Right-click a local branch in the sidebar, then Rename….
2. Edit New name. The name is checked as you type, as when creating a branch.
3. Click Rename.

yaggui runs git branch -m -- <old> <new>: “old renamed to new”. Only the local branch is renamed; its upstream on the remote is not touched. Changing only the case of the name is allowed. Undo renames it back.

Delete a branch

1. Right-click a local branch in the sidebar, then Delete name…. You cannot delete the checked-out branch: check out another one first.
2. The Delete name? dialog shows the command that will run, git branch -d <name>.
3. If the branch has an upstream, you can check Also delete the remote branch origin/name (unchecked by default). The preview then adds git push <remote> --delete <branch>.
4. Click Delete the branch.

If the branch has commits that are not merged, Git refuses and the dialog shows “name is not merged”: its commits exist nowhere else and deleting it makes them unreachable. The button becomes Delete anyway, which runs git branch -D.

The toast reads “Branch name deleted. It pointed at abc1234; the commit stays in the reflog for now.” If the remote deletion fails, the local branch is still deleted and a warning shows the reason. A branch checked out in a worktree cannot be deleted.

Caution

Undo restores a branch deleted locally only, including its upstream setting. If you also deleted the remote branch, the operation cannot be undone in yaggui. A force-deleted branch’s commits can still be found in the reflog for a while.

Delete a branch on the remote

Right-click a remote branch in the sidebar, then Delete on the remote…. The Delete origin/name? dialog warns that the branch will be deleted on the remote for everyone and that local branches are not touched, and shows:

git push origin --delete refs/heads/<name>

Click Delete on the remote. The toast reads “origin/name deleted”. If the branch was already gone on the remote, yaggui just removes the remote-tracking branch. You can cancel it from the status bar while it runs. This cannot be undone. Authentication problems are covered in Authentication.

Set, change or remove the upstream

The upstream is the remote branch that pull and push use by default (Git book).

1. Right-click a local branch in the sidebar, then Set upstream… (or Change upstream…).
2. In Remote branch, pick a branch, grouped by remote, or No upstream.
3. Click Set upstream (or Remove upstream if you picked No upstream). The button is disabled until you change the choice.

Action	Git command	Toast
Set or change	git branch --set-upstream-to=refs/remotes/<remote>/<branch> -- <name>	“name now tracks origin/branch”
Remove	git branch --unset-upstream -- <name>	“name no longer tracks a remote branch”

Remove upstream in the sidebar menu removes it at once. Upstream changes are not recorded for undo: set the previous upstream again by hand if needed. To create the upstream while pushing a new branch, see Fetch, pull and push.

Clean up merged and gone branches

Open the Clean up branches dialog with Clean up merged and gone branches… in the sidebar menu of any branch, or in the command palette.

It lists local branches that are either:

• merged: their tip is HEAD or an ancestor of HEAD;
• gone: their upstream was deleted on the remote. A gone branch may have “N commits not merged”.

The checked-out branch and branches checked out in a worktree are never listed (“Checked out, left alone: …”). Protected branches are never offered (“Protected, never offered: …”). The protected list is set in Preferences › Behavior › Protected branches, default main, master, develop, release/*. See Preferences.

1. Check the branches to delete. Merged branches, and gone branches with no unmerged commit, are checked by default. All (N) checks or unchecks everything.
2. Read the effect box: how many branches will be deleted, and either “Their commits stay in the history of the current branch.” or a warning that some commits are on no other branch and only the reflog keeps them. Remote branches are not touched.
3. Click Delete N branches.

yaggui checks every branch first and deletes nothing if one is refused, then runs one command:

git branch -D -- <branch> <branch> …

The toast reads “N branches deleted. Undo restores them all.” One Undo restores every deleted branch. If nothing qualifies, the dialog says “Nothing to clean up: no merged branch, no branch whose remote is gone.”

Undo

Operation	Undo
Check out a branch, remote branch or commit	Yes: switches back, keeping local changes
Create a branch	Yes, except from a stash
Rename a branch	Yes
Delete a local branch	Yes, with its upstream setting
Delete a local branch and its remote branch	No
Delete a branch on the remote	No
Clean up branches	Yes, all branches in one step
Set or remove an upstream	No (not recorded)

Undo is refused if the branches moved since, for example after a commit from a terminal. See Undo and redo. Every command above appears in the command log, and error messages are explained in Error messages.