Branches and remotes

Press 3 for the branches panel. The panel holds three tabs: local branches, remotes, and tags. Press ] or [ to change the tab.

Move between branches

Key	Action
space	Check out the branch under the cursor
c	Check out a branch by name
F	Check out, and throw away the local changes
-	Go back to the branch you came from

c searches the branch names while you type, so a long name needs only a few letters.

CAUTION: F deletes the changes in your working tree. Use space first, and read what git says when it refuses.

Make a branch

1. Move the cursor to the commit or the branch you want to start from.
2. Press n.
3. Type the name and press enter.

The new branch is created and checked out in one step.

Key	Action
n	New branch
R	Rename the branch
d	Delete the branch
N	Move commits onto a new branch

Before it deletes, stage asks git whether the branch is contained in HEAD. A branch that is not merged needs a second confirmation.

Bring branches together

Key	Action
M	Merge the branch under the cursor into the current one
r	Rebase the current branch onto the branch under the cursor
f	Fast-forward the branch under the cursor, without checking it out

A merge and a rebase can both stop on a conflict. Read Conflicts for the keys that finish them.

Push and pull

Key	Action
p	Pull
P	Push
u	Upstream menu for the branch under the cursor

The ahead marker in the status panel clears when the push lands.

P asks git where the branch pushes to. The answer obeys pushRemote and push.default, so a triangular setup pushes to the remote you configured and not to the one the upstream names.

A branch with no upstream has no answer to that question. stage asks you for the remote, and the push publishes the branch with -u. Choose “publish as…” to give the remote branch a different name. If push.default is current, stage asks nothing, because your configuration already answered.

When a force push is offered

stage offers a force push in two conditions, and never sends one without your answer:

• The branch is behind its tracking branch before the push starts. stage offers --force-with-lease, which refuses if the remote holds work you have not seen.
• git rejects the push and no tracking ref exists. A lease has nothing to read in this condition, so the offer is a plain --force.

If git rejects the push and the tracking ref does exist, your copy of the remote is stale. stage tells you to fetch, and offers no force. A force here discards commits you have never read.

Set Force push to disabled in the settings to remove both offers. stage then refuses the push and says why.

stage reads the result of a push from git push --porcelain, which marks a rejected ref with !. It does not read the message text, so a git in another language still gives the correct answer.

Set the tracking branch

u opens the upstream menu for the branch under the cursor. The menu shows the current tracking branch, or says that the branch is untracked.

Item	Result
set upstream	Type remote/branch. Completion offers the remote branches stage knows
unset upstream	The branch tracks nothing. The item is absent when there is nothing to unset

The menu also reports a tracking branch that is gone from the remote.

How pull integrates

pullMode in the configuration decides this:

Value	Result
auto	stage adds no flag. Your pull.rebase and pull.ff settings decide
merge	--no-rebase
rebase	--rebase
ff-only	--ff-only

auto is the default. Your git configuration already answers this question, and two answers in two places disagree sooner or later.

Remotes

Press ] from the branches tab for the remotes.

Key	Action
enter	Show the branches of the remote
space	Check out the remote branch
n	Add a remote
e	Change the URL of a remote
d	Delete a remote
f	Fetch

Pull requests

Key	Action
o	Create a pull request
O	Pull request options
G	Open the pull request in the browser
ctrl+y	Copy the URL of the pull request

The branches panel marks a branch that has an open pull request. A marked branch also shows the result of the checks on the pull request:

Marker	Meaning
✓	The checks passed
!	A check failed
·	The checks are running

A repository that runs no checks shows no marker. No marker is not a pass.

github.com and gitlab.com need no configuration. For a self-hosted forge, add the host to services in the configuration. Read Configuration.

Compare

Press W on a branch to mark it. Every branch you select after that is compared against the mark. Press ctrl+t to open your difftool.