A small and simple terminal dashboard to monitor many Git repositories at once.

• Introduction
• At a glance
• Features
• Requirements
• Installation
• Configuration
• Usage
  • Non-interactive mode
  • Interactive mode
  • Keyboard shortcuts
• Output states
• Environment variables
• Recommendation
• Credits
• License

check-repo scans a configurable list of folders, detects Git repositories, fetches origin, and reports whether each repo is clean, dirty, missing, or out of sync with its tracked remote branch.

It can run either as:

• a single-shot report (good for scripts/cron), or
• a lightweight interactive TUI with keyboard actions for refresh, pull, push, add, and delete.

• Concurrent repo scanning for fast updates.
• Per-repo branch/ahead/behind indicators.
• Colorized terminal UI with grouped categories (default, linux, macos, wsl).
• Optional interactive mode with selection and actions.
• JSON-backed target list (repo_targets.json) with in-app add/remove.

• Python 3.9+ (tested on modern Python 3)
• git available in your PATH
• A Unix-like terminal for interactive mode (uses termios/tty)

Clone into a stable tools directory, then make the launcher executable.

Common location:

mkdir -p ~/.local/share
git clone https://github.com/Cartoone9/check-repo ~/.local/share/check-repo
cd ~/.local/share/check-repo
chmod +x check-repo.zsh

If you prefer another location (for example ~/scripts/check-repo), use that path consistently in the steps below.

Create a symlink in ~/.local/bin so you can run either check or check-repo:

mkdir -p ~/.local/bin
ln -sf "$HOME/.local/share/check-repo/check-repo.zsh" ~/.local/bin/check
# or
ln -sf "$HOME/.local/share/check-repo/check-repo.zsh" ~/.local/bin/check-repo

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

If you prefer aliases instead of symlinks:

alias check="$HOME/.local/share/check-repo/check-repo.zsh"
# or
alias check-repo="$HOME/.local/share/check-repo/check-repo.zsh"

Edit repo_targets.json to define what gets scanned.

{
  "default": ["~/dotfiles", "~/scripts"],
  "linux": ["~/.config/hypr"],
  "macos": ["~/.config/kitty"],
  "wsl": []
}

Category behavior:

• default: always included.
• linux: included on Linux (except WSL, which uses the wsl category).
• macos: included on macOS.
• wsl: included on WSL.

Run once and print dashboard output:

python3 check-repo.py

Alternative:

./check-repo.zsh

If aliased:

check

Start the interactive dashboard:

python3 check-repo.py --interactive

or if you have set an alias:

check -i

In interactive mode:

• j / ↓: next actionable repo
• k / ↑: previous actionable repo
• p: git pull --ff-only on selected repo
• P: git push on selected repo
• r: refresh all repos
• a: add a repo target to a category
• d: delete selected repo target
• t: toggle display mode (all categories ↔ current system categories)
• q: quit

• CHECK_REPOS_CONFIG: path to an alternate JSON config file.

Example:

CHECK_REPOS_CONFIG=~/my-repo-list.json python3 check-repo.py

check-repo works well after running system update tools such as topgrade.

For example, I use the following alias to update my system and then check the state of my repositories:

alias update='topgrade && echo && check'

Inspired by git-overview by David Bellot.

Similar projects:

• gita
• repocheck

MIT