stage binds 359 keys. You do not learn them, because the same few keys mean the right thing wherever you are. This page explains how that works.
The layout
Section titled “The layout”A sidebar on the left, one main pane on the right, and a footer that lists the keys you can press now. A window strip at the top of the sidebar names the two windows. The window you are in is filled with the accent color.
The sidebar starts on the left. The Sidebar side row of the settings moves it to the right, and the main pane takes the columns it leaves.
The two windows
Section titled “The two windows”A window is a sidebar. Only one window is on screen. The window that you open replaces the window that you see.
| Window | Key | Shows |
|---|---|---|
| Git | 1-5 |
The five git panels |
| Explorer | E, ctrl+g |
The working tree and a repository grep |
E opens the file tree. ctrl+g opens the grep. Press the same key again to go
back to the git panel that you used before.
The Git window holds these panels:
| Key | Panel |
|---|---|
1 |
Status |
2 |
Files |
3 |
Branches |
4 |
Commits |
5 |
Stash |
Three of those hold more than one panel. Press ] and [ to move between them:
| Slot | Panels |
|---|---|
| Files | Files, Worktrees, Submodules |
| Branches | Local branches, Remotes, Tags |
| Commits | Commits, Reflog |
The Explorer window has one slot with two panels: Explorer and Search. ] and
[ move between them, as they do in a git slot.
You can also click the name of a panel to go to it. A click on a window name in the window strip changes the window.
tab, h and l move between the panels of the window on screen. They do not
leave that window. The Explorer window has one slot, so tab does nothing in
it. In the Explorer, h and l collapse and expand the tree instead. Read
Finding code.
The panel and the pane
Section titled “The panel and the pane”Focus is in a panel or in the main pane. The main pane shows whatever the panel has under its cursor.
| Key | Action |
|---|---|
0 |
Move into the main pane |
esc |
Go back to the panel |
h / l |
Move to the previous or the next panel of this window |
tab |
Cycle the panels of this window |
J / K |
Scroll the main pane without leaving the panel |
J and K are the ones to learn. Reading a long diff while keeping the file
list under your cursor is most of what reviewing is.
In the Explorer window, h and l collapse and expand the tree. That window
has one panel to move between, so the keys are free for the tree.
Contexts
Section titled “Contexts”A context is a layer of keys. stage keeps a list of them, most specific first, and a keypress goes to the first layer that binds it.
That is why d discards a file in the files panel and discards lines in the
staging editor. They are two bindings in two contexts, not one binding that asks
where it is.
There are 29 contexts. Press ? for the ones you are in.
Modes take the keyboard
Section titled “Modes take the keyboard”Some contexts take the whole screen and almost the whole keyboard:
| Mode | Reached by |
|---|---|
| Staging editor | enter on a file |
| Resolve | enter on a conflicted file |
| Rebase plan | i on a commit |
| Patch builder | enter on a commit, then ctrl+p |
| Review list | # |
| Command log | @ |
The staging editor is the strictest of them. While it is open, almost nothing
global reaches through. Its own j, d and space collide with the panel
verbs underneath, so the panel verbs are gone.
One exception exists: while an operation is paused, m still opens the
continue and abort menu. The staging editor is exactly where a conflict gets
resolved, so the key that finishes the operation has to survive.
Inputs take the keyboard too
Section titled “Inputs take the keyboard too”Press / in a panel and the filter takes every printable key. The panel keys
are gone while you type, so a c types a letter instead of opening the commit
editor.
Press esc to leave the input. The filter stays until you clear it.
The footer never lies
Section titled “The footer never lies”The footer, the ? modal and the dispatcher read one table. A key cannot do one
thing and be advertised as another.
This holds after you rebind. stage drops the written hint for a binding you override, so the footer shows your key instead of the default it no longer uses. Read Keybindings.