DEV Community

Cover image for Git-Scope User Guide
Bharathkumar
Bharathkumar

Posted on

Git-Scope User Guide

#git #cli #guide #productivity

Git-Scope User Guide 🔭

Git-Scope is a terminal dashboard for your local git repositories.

Stop cd-ing into folders to check status. Scan your projects and see a real-time dashboard of your entire workload.

📦 Installation

Run these commands:

macOS / Linux (Homebrew) 

brew tap Bharath-code/tap
brew install git-scope
Enter fullscreen mode Exit fullscreen mode

Go Install 

go install github.com/Bharath-code/git-scope/cmd/git-scope@latest
Enter fullscreen mode Exit fullscreen mode

💻 CLI Commands

Use these commands to control the tool:

git-scope                    # Launch dashboard (default)
git-scope scan               # Print repos as JSON
git-scope scan-all           # Scan entire system from home dir
git-scope init               # Create config file
git-scope -h                 # Show help
Enter fullscreen mode Exit fullscreen mode

Flags:

  • -config: path to config file (default: ~/.config/git-scope/config.yml)

🖥️ The Dashboard

When you run git-scope:

Dashboard Preview

Columns

  • Status: ● Dirty (Uncommitted/Unpushed) or ✓ Clean.
  • Repository: Project folder name.
  • Branch: Active branch (e.g., main).
  • Staged: Files ready to commit.
  • Modified: Changed files.
  • Untracked: New files.
  • Last Commit: Time since last commit.

🎮 Controls

Git-Scope is keyboard-first.

Movement

Key Action
k / ↑ Up
j / ↓ Down
q Quit

🔍 Search

Press / to search.

  • Types fuzzy match (gscope finds git-scope).
  • Enter confirms, Esc cancels.

🛡️ Filter (Dirty)

Press f to toggle the Dirty Filter.

  • ON: Shows only repos with uncommitted or unpushed changes.
  • Use Case: Find unfinished work instantly.

🔃 Sort

Press s to cycle sort:

  1. Dirty First (Default)
  2. Name
  3. Last Modified

🚀 Actions

Key Action
Enter Open repo in $EDITOR
r Rescan text system
c Clear search

⚙️ Configuration

Git-Scope works instantly. It finds git repos recursively in your current directory.

  • Run from ~/projects for best results.
  • Ignores node_modules automatically.

Caching: Git-Scope caches results for speed (<10ms). Press r to refresh if needed.

⚡️ Workflow: Monday Morning Triage

  1. Run git-scope.
  2. Check Sync column for ↓ (behind origin).
  3. Press f to see Dirty repos.
  4. Press Enter to fix them.

Get Started
Star on GitHub | Website

Top comments (1)

Collapse
 
iam_pbk profile image
Bharathkumar •

v1.0.1 Release Contents
✨ Animated spinner during scanning
📝 Improved error messages with config path
⚡ Smart ignore patterns for faster scans
🔧 Performance fix for home directory scanning