gitdeck

gitdeck is a dependency-free terminal UI for managing multiple Git repositories under a folder.

It scans a root directory, lists every Git working tree it finds, and lets you refresh status, check remotes, pull, push, commit, fetch, and inspect status/logs for one repository or all repositories.

Run

Recommended from a checkout:

uv run gitdeck /path/to/projects

For example:

uv run gitdeck ~/git

You can also run the module directly:

python -m gitdeck /path/to/projects

From a checkout:

PYTHONPATH=src python -m gitdeck ~/git

Or install it locally:

python -m pip install -e .
gitdeck ~/git

Keys

Key	Action
q	Quit
j / Down	Move selection down
k / Up	Move selection up
g	Jump to first repository
G	Jump to last repository
r	Refresh status for all repositories
n	Check selected repository remote reachability
N	Check all repository remotes
s	Show git status --short --branch for selected repository
:	Run a custom Git command in the selected repository
Enter / v	View changed files for selected repository
i	Create or edit selected repository .gitignore
l	Show recent commits for selected repository
f	Fetch selected repository
F	Fetch all repositories
p	Pull selected repository
P	Pull all repositories
u	Push selected repository
U	Push all repositories
c	Commit selected repository with git add -A; press p on the result screen to push
C	Commit all dirty repositories with git add -A; press p on the result screen to push successful commits
?	Show help

File View Keys

Press Enter on a repository to inspect its changed files. v also works.

Key	Action
j / Down	Move selection down
k / Up	Move selection up
g	Jump to first file
G	Jump to last file
Space / a	Stage selected file
A	Stage all files in the repository immediately
x	Unstage selected file
X	Unstage all files in the repository
c	Commit this repository with git add -A; press p on the result screen to push
p	Pull this repository
u	Push this repository
:	Run a custom Git command in this repository
b / r	Return to repository list

Bulk commands run sequentially and keep going if one repository fails. The final output is shown in a scrollable detail panel.

Custom Git Commands

Press : on a repository to run an ad-hoc Git command in that repository. You can type either the arguments or a full git ... command:

status --short
git log --oneline -n 20
diff --stat

The command output opens in gitdeck's scrollable detail view.

Configuration

Gitdeck reads an optional config file from $GITDECK_CONFIG, or from:

~/.config/gitdeck/config

Create a starter config:

uv run gitdeck --write-config

Example:

[keys]
# Uncomment a line to override that action. Values are comma-separated aliases.
# Main view:
# quit = q, Esc
# help = ?
# open-files = Enter, v
# refresh = r
# check-net = n
# check-net-all = N
# status = s
# log = l
# edit-gitignore = i
# fetch = f
# fetch-all = F
# pull = p
# pull-all = P
# push = u
# push-all = U
# commit = c
# commit-all = C
# custom-git-command = :

# Detail/file views:
# back = b, r, Enter
# stage-file = Space, a
# stage-all = A
# unstage-file = x
# unstage-all = X

[colors]
# selected_fg = black
# selected_bg = cyan
# clean = green
# dirty = yellow
# error = red
# title = cyan
# staged = cyan

[scan]
# Empty means unlimited recursive scanning.
# max_depth =
# ignore_dirs = .git, .hg, .svn, node_modules, .venv, venv

Key names are comma-separated aliases. Setting an action replaces that action's defaults, so include every key you want to keep. For example, push = o changes selected-repository push to o; push-all = U stays separate unless changed. Common special names are Enter, Esc, Space, Up, Down, Left, Right, PgUp, and PgDn.

Gitdeck warns about key conflicts within the same screen context. Reusing a key across different screens is allowed, such as r for refresh in the main view and back in a detail view.

Available color names are black, red, green, yellow, blue, magenta, cyan, white, and default. default uses the terminal's current default color.

Status Legend

Indicator	Meaning
green row	Clean and in sync with upstream
yellow row	Has local changes, commits ahead, or commits behind
red row	Status error or merge conflicts
S<n>	Staged file count
M<n>	Modified but unstaged file count
?<n>	Untracked file count
!<n>	Conflicted file count
+a/-b	Commits ahead of / behind upstream
net ?	Remote reachability has not been checked yet; press n or N
<branch> (unborn)	Repository has no first commit yet

Notes

• Remote reachability uses git ls-remote --exit-code <remote> HEAD with a short timeout. It is only checked when you press n or N to avoid slowing normal refreshes.
• Commit commands stage all changes in the target repository before committing.
• The .gitignore editor uses $VISUAL, then $EDITOR, then vi. If the selected repository has no .gitignore, gitdeck creates one from its built-in starter template first.
• Nested repositories below a discovered working tree are skipped deliberately; this avoids descending into submodules or vendored repositories unless you run gitdeck from a narrower root.