A real-time, glanceable git status monitor for the terminal
Gitst shows in real-time what is happening to a git repository (local as well as remote) as it happens: changed files, commits, pushes, fetches, merges, and rebases.
Gitst typically sits in one pane of a multi-pane terminal setup (using tools like Dantty, tmux, screen, herdr, WezTerm, iTerm2, etc.) next to your editor, coding agent, and shells.
By design, Gitst monitors git, it doesn't manipulate it. This comes with a few benefits, especially for team work scenarios when there's a lot of team activity on the repo, and also for personal use in conjunction with coding agents. Being a git monitor, Gitst never changes your git repository (apart from git fetch), and it never takes over git's index.lock, so it cannot (by design) get in the way or obstruct git commands run elsewhere. This is useful for at least two scenarios: 1) when you might want the coding agent to control git but still see what's going on, or 2), like me, you just want to control git manually.
If you want Gitst to stage, commit, push, pull, and stash for you too, there is an opt-in write mode (gitst --write, see Write mode). Everything above holds unless you turn it on.
With Homebrew (macOS and Linux):
brew install dfallman/tap/gitstPrebuilt binaries for macOS, Linux, and Windows are on the releases page. Or build from source with Cargo:
cargo install --git https://github.com/dfallman/gitstRequires git 2.31 or newer on your PATH.
Run gitst inside a repository, or gitst <path>. If the directory is not a
repository yet, Gitst waits and picks it up once git init or git clone has
run there.
It does its best to adapt to the terminal window it operates in: sections collapse, borders give way to rules, and columns
drop out as the pane shrinks, down to a single branch ↑1 ● line. A diff or list you open is still shown in full at any width. Mouse support is enabled by default, so you can easily click around in the interface, collapse and expand panels, and view details by clicking on items. Gitst is also entirely operable using its keyboard shortcuts (see below).
The dashboard has five sections:
- Changes: staged, unstaged, untracked, and conflicted files, with
+/−line counts. A•marks a file that just changed. - Activity: a timeline of commits, amends, checkouts, merges, rebases, resets, pulls, cherry-picks, pushes, fetches, staging, stashes, and file edits. Edits that come within a minute of each other merge into one row.
- Commits: recent history, with
↑on commits not yet pushed. - Branches and Stashes: folded by default.
Warnings appear under the header for possible secrets, conflicts, an
index.lock held for more than 10 seconds, failed fetches, config errors, and,
in write mode, failed actions.
A long warning wraps onto up to three rows when there is room. When there are
more than fit, the last row lists the rest.
Press c, or click a warning, to clear it. A cleared warning shows again if
it changes, or goes away and comes back. The secrets band cannot be cleared,
and neither can a failed refresh, which explains why the panes below are
dimmed.
Gitst looks for things that should not be pushed: .env files, SSH and other
private keys, key stores, credentials files, Terraform state, and tokens with a
recognisable prefix (AWS, GitHub, GitLab, Slack, Stripe, Google, Anthropic,
OpenAI, npm, and SendGrid). It checks:
- untracked files, by name and by content;
- staged and unstaged changes: the lines they add, and the names of files they add, rename, or copy;
- commits on any local branch that no remote has yet (the newest 50), in a repository without a remote too;
- commits pushed from this clone in the last day, so that a push made before Gitst saw the commit is still reported.
It shows what it finds in a red band under the header. Click the band, or press
s, to list each finding with a masked snippet; a finding opens its diff. A
finding in a commit that reaches a remote stays listed, as pushed, until Gitst
quits, so that you know which key to rotate.
Gitst only warns. It never blocks a commit or a push and never changes a file,
and it checks everything offline. To silence a false alarm, add gitst:allow
(or gitleaks:allow) to the line, or list paths in leak_allow.
What it does not see: files over 1 MiB and binary files are not read. An edit to
a file that is already tracked is checked by what it adds, not by its name, so a
new value in a tracked .env is caught only if it has a recognisable prefix.
Above numstat_max_files changes, only file names are checked. When part of the
scan cannot run, for example because git timed out, a secret scan incomplete
warning says so, and the last findings stay.
- Click a file, commit, branch, stash, or activity row to open it full-pane
(diffs, commit details, ahead/behind lists). Click
‹ back, pressEsc, or right-click to return. - Click
↑N(in the header or on the Commits border), or pressr, to list the commits and files a push would send. This works in read-only mode too. In write mode,Push nowin its header pushes them. - Click a section title to fold it. The wheel scrolls what is under the pointer.
- Click
↻(or pressf) to fetch now. - Click a warning to clear it.
| Key | Dashboard | Detail view |
|---|---|---|
j k / ↓ ↑ |
move | move / scroll |
Enter / l / → |
open, or fold a section title | open |
Esc / h / ← / Backspace |
clear selection | back |
Tab / Shift-Tab |
next / previous section | |
Space |
fold section | page down |
PgDn / PgUp |
page down / up | |
g / G / Home / End |
top / bottom | top / bottom |
w |
wrap long lines | |
f |
fetch now | fetch now |
r |
outgoing commits and files | outgoing commits and files |
s |
possible secrets | possible secrets |
c |
clear warnings | clear warnings |
? |
help | help |
q / Ctrl-C |
quit | quit |
Ctrl-Z |
suspend (fg resumes; not on Windows) |
suspend |
Off by default. Turn it on with gitst -w (or --write), or write = true in the config. Without it, the keys below do nothing and show nothing, apart from ] and [, which also move between hunks in a read-only diff.
| Key | Where | Action |
|---|---|---|
a |
a file in Changes | stage or unstage the file |
a |
a file's diff | stage or unstage the current hunk |
] / [ |
a file's diff | next / previous hunk |
A |
dashboard | stage all, or unstage all when everything is staged |
C |
anywhere | commit what is staged, or amend the last commit when nothing is |
P |
anywhere | push, or review first when something needs a look |
U |
anywhere | pull, fast-forward only |
S |
anywhere | stash, including untracked files |
p / o / D |
a stash, or its view | pop / apply / drop |
! |
anywhere | open the last failed action's output |
Tab |
commit prompt | amend the last commit |
Ctrl-E |
commit prompt | write the message in your editor |
With the mouse, the header offers Push · Write ▾, so write mode fits in a
narrow pane. Push is dimmed when there is nothing to push. Write ▾ opens a
menu with Stage all, Commit, Pull, and Stash, each with the key that
does the same. Stage all reads Unstage all when everything is staged, and
appears on the dashboard only. Commit reads Amend when the tree is clean.
An item that cannot run is dimmed, and clicking it says why. When the pane is
too narrow for both, Push moves into the menu, and Write ▾ keeps its place
before the repository's name. A click outside the menu, or any key, closes it,
and a confirm that comes up closes it too.
Each file in Changes has a + at the right edge that stages it, or a − when
it is fully staged. A file's diff has + stage file in the header and
+ stage on each hunk, and a stash's view has pop, apply, and drop.
The keys that change the repository are capitals, so they are hard to hit by
accident. Each action asks first when it needs to: before it stages everything,
amends a pushed commit, or pushes something that needs a look (see below). A
confirm that names a possible secret, and stash drop, accept y only. n or
Esc declines. Commit and push re-scan what they are about to change, so the
secret check covers exactly that, not the last snapshot.
P, Push, and Push now push at once, unless the secret re-scan found
something, the scan was partial, or the push creates the branch on the remote:
a new branch, or one deleted there since this clone last fetched. Then Gitst
opens the Outgoing view, which lists exactly the commits and files that are
pushed, and asks before it pushes. To look before any push, press r or click
↑N.
You can browse the Outgoing view while the question waits: Enter opens a
commit or file, and Esc goes back, cancelling the push at the Outgoing view
itself. n cancels from anywhere. y is the only key that pushes, at every
step of the confirm. In the Outgoing view the header offers only Push now,
and clicking it answers the confirm as y does. Clicking ‹ back goes back
as Esc does, and a click anywhere else cancels the push.
A push sends the current branch, as it was when you pushed (commits made while
it runs stay behind), to the remote and branch that git's own push config names. With no push target set, a
repository with a single remote, or with origin, pushes there. On a detached
HEAD, with several remotes and none of them origin, or when the config names a
target that is not a branch, Gitst says so and leaves the push to your shell.
Prompts, confirms, and results show black on yellow in the row under the
header, so they are hard to miss. A refusal, such as HEAD moved, review again, shows there too. An action that fails, for example a push that times
out or a hook that exits with an error, stays in the warning band until you
clear it. When git printed something, the warning ends in ! for output, and
! or a click opens it.
Quitting while an action runs waits for it to finish. Press q again to quit
at once.
Ctrl-E suspends Gitst, runs git commit -e in your terminal with the text
typed so far, and resumes when git exits. It suits long messages, and hooks or
signing that need a terminal. With amend, it starts from the subject you typed,
not the previous message's body. As on the other commit path, the editor only
opens if the staged changes and HEAD are still what you confirmed, and Gitst
warns afterwards if the commit includes changes staged after your review.
Files with a git filter attribute (for example LFS or nbstripout) stage as
whole files only. Hunk staging matches what the view shows, so a change the view
cannot show, such as tabs against spaces or a CR, is staged as it is on disk.
gitst [PATH] [--no-fetch] [--interval <DURATION>] [-w | --write]
gitst --version
--no-fetchturns off background fetching.↻andfstill fetch. It wins over--interval.--interval 10msets the time between background fetches (30s,5m,1h).-w,--writeturns on write mode. With--write, the actions you choose run as ordinary git commands, with your hooks and the repository's config, as if you ran them in your shell. Reads stay guarded.-V/--versionprints the version.
Optional. Gitst reads the first of these that exists:
$XDG_CONFIG_HOME/gitst/config.toml (when that is set),
%APPDATA%\gitst\config.toml (Windows), and ~/.config/gitst/config.toml.
All keys are optional; these are the defaults:
fetch_interval = "5m" # "0" turns the timer off; ↻ and f still work
fetch_prune = false # pass --prune to background fetches
collapsed = ["branches", "stashes"] # sections that start folded
icons = "none" # "nerd" for Nerd Font icons
pulse_seconds = 10 # how long a changed file stays marked; 0: never
max_changes = 1000 # most changed files to list
numstat_max_files = 500 # skip +/− counts above this many changes
leak_scan = true # warn about possible secrets
leak_allow = [] # paths never warned about (.gitignore syntax)
write = false # allow commit, push, pull, stash, and stagingSection names for collapsed are changes, activity, commits, branches,
and stashes. Unknown keys, unknown section names, and invalid values are named
in the UI and keep their defaults; the rest of the file still applies.
- Colours come from your terminal's own palette, so Gitst follows light and dark themes. When the terminal reports its background colour, Gitst uses it for subtle tints.
- Gitst follows
status.showUntrackedFiles. When it is not set, untracked directories are listed file by file. - Diffs are always read plain, whatever your
color.*,diff.external, diff driver, or pager settings. Untracked symlinks show their target, and FIFOs and devices are never read. A diff over 16 MB is not shown. - Gitst never runs a program that the repository's own config names. Whatever
writes a repository, such as a coding agent or an unpacked archive, can write
its
.git/configand its submodules' config too, so Gitst replaces the settings that git would run from there (core.fsmonitorhooks, filter and diff drivers,gpg.program,core.sshCommand, credential and remote helpers, and hooks during a fetch) with your own global or system settings, or turns them off. A fetch also keeps your own TLS verification, proxy, and cookie settings, so the repository cannot route it through someone else. Background fetches also skip submodules and automatic maintenance. - Background fetches run without a terminal, so they can never prompt for a
password. If a fetch fails, Gitst shows
fetch failed: auth(oroffline,timeout, or git's message) and retries with backoff, doubling from the fetch interval up to an hour (5, 10, 20, then 60 minutes by default). A fetch that runs longer than a minute is stopped. - With
--write, the actions you choose run as ordinary git commands, with your hooks and the repository's config, as if you ran them in your shell. Reads stay guarded. - Pushes appear in Activity when they were made from this clone. Git only records them in the remote-tracking reflog.
- Changes are picked up by watching the working tree and
.git, skipping ignored paths. If the watcher cannot start, Gitst polls every 3 seconds.
Gitst is written in Rust, with help from tools like Anthropic's Claude Code. I've been writing code for over 30 years, and working with coding agents has rekindled my sense of awe at what code can do. They let me move faster, try more ideas, and test them more thoroughly than I would on my own.
