git-scope

README

git-scope

A fast TUI dashboard to view the git status of all your repositories in one place. Stop the cd -> git status loop.

---

🛡️ Trust & Safety

git-scope is designed to be safe to run frequently and safe to recommend.

• Safe by default — dashboard mode is read-only; write actions are explicit commands
• Local-first — no network access, no telemetry, no accounts
• Predictable — no background services or daemons
• Conservative scope — focused on visibility, not automation

These choices make git-scope suitable for daily use and work environments where reliability and transparency matter.

---

⚡ Installation

Get started in seconds.

Homebrew (macOS/Linux)

brew tap echaouchna/homebrew-tap && brew install --cask git-scope

Update

brew upgrade --cask git-scope

From Source (Windows)

go install github.com/echaouchna/git-scope/cmd/git-scope@latest

If you find this useful, please consider giving it a ⭐ star to help others find it!

---

🚀 Usage

Simply run it in any directory containing your projects:

git-scope

Commands

git-scope              # Launch TUI dashboard
git-scope init         # Create config file interactively
git-scope scan         # Scan and print repos (JSON)
git-scope scan-all     # Full system scan from home directory
git-scope standup      # Multi-repo standup summary (default: 24h, all branches)
git-scope standup 3d   # Multi-repo standup for last 3 days
git-scope standup 3d --current-branch # Limit commits to current branch only
git-scope standup 3d --author "Jane Doe" # Show commits for one author
git-scope pull-rebase  # Run git pull --rebase in all discovered repos
git-scope switch main  # Run git switch main in all discovered repos
git-scope create-branch feat/x # Run git switch -c feat/x in all discovered repos
git-scope merge-no-ff release/x # Run git merge --no-ff release/x in all discovered repos
git-scope issue        # Open GitHub issues page in browser
git-scope -h           # Show help

By default, it recursively scans the current directory. You can configure permanent root paths later.

---

🆚 git-scope vs. lazygit

• git-scope is for your workspace (bird's-eye view).
• lazygit is for a specific repository (deep dive).

Feature	git-scope	lazygit
Scope	All repos at once	One repo at a time
Primary Goal	Find what needs attention	Stage/Commit/Diff
Search	Find repo by name/branch	❌
Integration	Press Enter to open editor	Press Enter to stage files
Performance	~10ms startup (cached)	Slower on large monorepos

---

✨ Features

• 📁 Workspace Switch — Switch root directories without quitting (w). Supports ~, relative paths, and symlinks.
• 🔍 Fast Search — Find repos by name or branch (/).
• 🛡️ Dirty Filter — Instantly show only repos with uncommitted changes (f).
• 📄 Pagination — Navigate large repo lists with page-by-page browsing ([ / ]). Shows 15 repos per page with a dynamic page indicator.
• 🚀 Open Project Menu — Open the selected repo with Neovim, GitUI, Tig, Tig (--all), or VS Code (tools shown only when installed).
• 🔎 Searchable Open Menu — Open options can be filtered by typing and are scrollable (↑/↓, PgUp/PgDn).
• ☑ Selection Workflow — Select/deselect repos inline (Space), with select/deselect-all (Ctrl+A) for filtered results.
• ⚙️ In-TUI Git Actions — Action menu with keyboard navigation and branch autocomplete (a).
• 📦 Batch Actions — Run actions on selected repos; if none are selected, runs on the highlighted repo.
• 🌿 Common Branch Suggestions — For switch (and merge suggestions), branch autocomplete only suggests branches common across targets.
• 📜 Action Logs On Demand — Logs are available through the l shortcut from the dashboard or Git Actions modal.
• 👀 Background File Watcher — Real-time status refresh updates dirty/staged/untracked signals as files change.
• ⚡ Blazing Fast — JSON caching ensures ~10ms launch time even with 50+ repos.
• 📊 Dashboard Stats — See branch name, staged/unstaged counts, and last commit time.
• 🔗 Symlink Support — Symlinked directories resolve transparently (great for Codespaces/devcontainers).

---

🎯 Use Cases

git-scope excels in environments where multi-repo complexity is a daily burden:

• Microservices Management — Quickly verify if all your services are on the correct branch and have no unpushed changes.
• OSS Contribution Tracking — Keep tabs on various upstream forks and personal branches in one view.
• Infrastructure as Code (IaC) — Monitor multiple Terraform/CloudFormation repos for configuration drift or uncommitted edits.
• Context Recovery — Instantly see where you left off after a weekend or a holiday without running git status 20 times.

---

🏆 The git-scope Advantage

While many Git tools focus on the micro (committing, staging, diffing), git-scope is built for the macro.

Typical git workflows involve "tunnel vision"—working deep inside one repository. git-scope provides the "command center" view. It is local-first and blazing fast (<10ms), with optional explicit batch git commands when you want to take action across repositories.

---

⌨️ Keyboard Shortcuts

Key	Action
w	Switch Workspace (with Tab completion)
/	Search repositories (name/branch)
f	Filter (Cycle: All / Dirty / Clean)
s	Cycle Sort Mode
1–4	Sort by: Dirty / Name / Branch / Recent
Space	Select/Deselect current repo
Ctrl+A	Select/Deselect all filtered repos
[ / ]	Page Navigation (Previous / Next)
Enter	Open Project Menu
a	Open Git Actions modal (supports batch run)
l	Open Last Action Logs (from dashboard or actions modal)
Ctrl+P	Open Command Palette (search + run commands)
?	Show All Shortcuts overlay
c	Clear search & filters
r	Rescan directories
q	Quit

---

⚙️ Configuration

Edit workspace location and code editor of your choice in ~/.config/git-scope/config.yml:

# ~/.config/git-scope/config.yml
roots:
  - ~/code
  - ~/work/microservices
  - ~/personal/experiments

ignore:
  - node_modules
  - glob:*.cache
  - path:vendor/github.com
  - regex:^tmp-
  - .venv
  - dist
  - .terraform

editor: code # any executable command available in PATH

Notes:

• ignore supports explicit rule types and defaults to exact name matching:
• node_modules or exact:node_modules -> exact directory-name match.
• glob:*.cache -> directory-name glob match.
• path:vendor/github.com -> root-relative path/subtree match.
• regex:^tmp- or /^tmp-/ -> regular expression match.
• Invalid regex rules are ignored safely.
• Open-project tools (Neovim, GitUI, Tig) appear only if installed on your machine.
• standup checks recent commits across all local branches by default; add --current-branch to limit to current branch only.
• standup supports --author "<name>" to filter commit output to a specific contributor.
• Use Ctrl+P (Command Palette) and run Standup (..., all branches) by default, or choose current branch variants.
• Command Palette also autocompletes Standup ... by <author> entries from active users (last 24h, all branches).
• In the open-project menu: type to filter options, use ↑/↓ and PgUp/PgDn to scroll, Enter to run.

---

💡 Why I Built This

I work across dozens of small repositories—microservices, dotfiles, and side projects. I kept forgetting which repos had uncommitted changes or unpushed commits.

My mornings used to look like this:

cd repo-1 && git status
cd ../repo-2 && git status
# ... repeat for 20 repos

I built git-scope to solve the "Multi-Repo Blindness" problem. It gives me a single screen to see what is dirty, what is ahead/behind, and where I left off yesterday.

---

🗺️ Roadmap

• In-app workspace switching with Tab completion
• Symlink resolution for devcontainers/Codespaces
• Background file watcher (real-time updates)
• Quick actions (pull --rebase, switch, create branch, merge --no-ff)

❓ FAQ

How do you manage multiple Git repositories locally?

git-scope provides a fast terminal dashboard that shows the status of many local Git repositories at once. It helps developers regain context across projects without switching directories or running commands repeatedly.

What problem does git-scope solve?

git-scope reduces context switching when working across many Git repositories, such as microservices, tools, or configuration repos. It gives a single overview of repository state so developers can quickly see what needs attention.

Is git-scope safe to use at work?

Yes. git-scope runs entirely locally, has no telemetry, and dashboard mode is read-only. Write operations are only executed when you explicitly run action commands.

Does git-scope replace git commands?

Not entirely. The TUI focuses on visibility and orientation, and there are optional batch commands for standup, pull --rebase, switch, create-branch, and merge --no-ff.

Is git-scope suitable for monorepos?

git-scope is designed for multi-repo (polyrepo) workflows. It is not intended to manage monorepos.

What platforms does git-scope support?

git-scope runs on macOS, Linux, and Windows.

How does Homebrew publishing work?

Releases are built with GoReleaser and the formula is published to echaouchna/homebrew-tap.

How is git-scope different from other git TUIs?

Most git TUIs focus on interacting with a single repository. git-scope focuses on visibility across many repositories with optional explicit multi-repo actions.

---

📄 License

MIT © echaouchna

---

🙏 Acknowledgements

Built with these amazing open-source projects:

• Bubble Tea — The TUI framework
• Lip Gloss — Style definitions
• Bubbles — TUI components (table, spinner, text input)

---

⭐ Star History

---

👥 Contributors

Made with contrib.rocks.