Core Concepts
Diff Modes
A “mode” is simply which set of changes er is showing you. There are six built-in modes
plus a pull-request mode and an AI-generated guided tour. In the terminal you switch with the number keys; in
the desktop app you switch from the branch context bar.
The six modes at a glance
| Key | Mode | Shows |
|---|---|---|
| 1 | Branch | Everything that differs between your branch and its detected base branch. |
| 2 | Unstaged | Working-tree changes you have not staged yet (git diff). |
| 3 | Staged | Changes in the index, ready to commit (git diff --cached). |
| 4 | History | Commit-by-commit view of your branch's history. |
| 5 | Conflicts | Files with unresolved merge conflicts. |
| 6 | Hidden | Watched git-ignored files that er can still surface (appears when [watched] paths are configured). |
Tab numbers are assigned dynamically to the modes that are enabled. If you disable a mode in configuration, the remaining modes renumber so there are no gaps — and a tab that knows its PR number, or has a guided tour, adds a numbered tab of its own.
Branch both
The default mode and the one you will use most. It answers “what does this branch change?” by diffing against the auto-detected base branch (see base branch detection). This is the right mode for reviewing a feature branch or a pull request's worth of work.
Unstaged both
Your in-progress edits that have not been git add-ed. Pairs naturally with watch mode while an AI
assistant is actively editing — you see changes appear as they are written.
Staged both
What is in the index and would go into your next commit. From the terminal you can stage or unstage
the current file with s, and in staged mode you can commit and push without leaving er
(c writes the commit, Ctrl+P pushes). After you commit, er
automatically switches to a view of exactly what you just committed (git diff HEAD~1 HEAD) so you can
confirm it before moving on.
History both
A commit log for your branch. Selecting a commit loads its full diff (the parser runs git log plus a
git diff per commit). Recent commits are cached so scrolling back through history stays fast. Use this
to review work commit by commit rather than as one big squashed diff.
Conflicts both
Surfaces files with unresolved merge conflicts so you can find and work through them quickly during a merge or rebase.
Hidden / watched files both
Files git normally hides: the git-ignored paths you listed in the [watched] config (agent sync
folders, generated docs, and the like). The tab only appears when watched paths are configured. In other
modes you can also toggle a watched-files section into the file tree with W.
See Watched files.
Pull request mode both
You enter it by opening a PR. From the terminal:
er --pr 42
er https://github.com/owner/repo/pull/42
In PR mode the right-hand panel shows CI checks and reviewer decisions, and comment sync targets that pull request. The desktop app's PR card also shows labels; the terminal panel does not. In the terminal the PR diff is one of the numbered tabs too: a tab that knows its PR number carries a PR Diff tab — after Staged when there is a working tree to review, and on its own when there is not. The desktop app has a “PR Diff” toggle and a paste-a-URL modal. PR review can be done against remote refs without checking out the branch. See GitHub & Pull Requests.
Guided tour both
When a guided tour exists for the branch (generated from the AI Hub in either app — in the terminal press a and pick Generate guided tour; see AI Hub Actions → Generate guided tour), a Tour tab appears next to the working-tree modes. It presents the same branch diff reordered and grouped into narrative pillars, so you can walk the change story-first. In the terminal, k/j move between pillars, n/N between files, Space marks a file reviewed, and b marks the whole pillar reviewed. The desktop app presents the tour in its Guide tab.
Sorting by recency
In any mode, press m to toggle sorting files by modification time. When an AI tool just touched a handful of files, this floats them to the top of the list so you review the freshest changes first.
Performance with large diffs
er is built to stay fast even on enormous diffs. Three mechanisms do the heavy lifting:
- Auto-compaction — lock files, generated code, minified assets, and files whose diff runs past ~2,000 lines are compacted automatically: their hunks are cleared from memory and shown as a single collapsed entry. Press Enter to expand one on demand.
- Two-phase lazy parsing — diffs above roughly 200 KB get a header-only scan for the file list, and individual files are parsed only when you navigate to them.
- Viewport rendering — only the rows visible on screen (plus a small buffer) are ever built, so a 5,000-line file renders like a 60-line one.
You rarely have to think about any of this — it just keeps scrolling smooth.