Skip to content

Commit c502fc0

Browse files
Bharath-codeBharath-code
committed
docs: Significantly expand and restructure README with new sections, improved formatting, and detailed comparisons.
1 parent 1ccb053 commit c502fc0

File tree

1 file changed

+138
-49
lines changed

1 file changed

+138
-49
lines changed

‎README.md‎

Lines changed: 138 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,135 @@
11
# git-scope
22

3-
> A fast TUI to see the status of all git repositories on your machine.
3+
A **fast TUI dashboard** to view the git status of **all your repositories** in one place — no more `cd` → `git status` loops.
4+
5+
![demo](docs/git-scope-demo-1.webp)
6+
7+
<p align="left">
8+
<a href="https://github.com/Bharath-code/git-scope">
9+
<img src="https://img.shields.io/github/stars/Bharath-code/git-scope?style=flat-square" />
10+
</a>
11+
<a href="https://github.com/Bharath-code/git-scope/blob/main/LICENSE">
12+
<img src="https://img.shields.io/github/license/Bharath-code/git-scope?style=flat-square" />
13+
</a>
14+
<a href="https://goreportcard.com/report/github.com/Bharath-code/git-scope">
15+
<img src="https://goreportcard.com/badge/github.com/Bharath-code/git-scope?style=flat-square" />
16+
</a>
17+
<a href="https://pkg.go.dev/github.com/Bharath-code/git-scope">
18+
<img src="https://pkg.go.dev/badge/github.com/Bharath-code/git-scope.svg" />
19+
</a>
20+
</p>
421

5-
![Status](https://img.shields.io/badge/status-v2.0_Released-green)
6-
![Go Version](https://img.shields.io/badge/go-1.20+-00ADD8)
7-
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
22+
---
823

9-
<p align="center">
10-
<img src="docs/git-scope-demo-1.webp" alt="git-scope demo" width="600">
11-
</p>
24+
## 🚀 Overview
25+
26+
`git-scope` helps you manage *many* git repositories from a single terminal UI.
27+
28+
It auto-discovers repos, shows which ones are dirty/ahead/behind, and lets you jump into your editor instantly — ideal for multi-repo workflows, microservices, dotfiles, OSS contributions, and experimentation folders.
29+
30+
🌐 **Landing Page:** https://bharath-code.github.io/git-scope/
1231

13-
**[🌐 Visit the Landing Page](https://bharath-code.github.io/git-scope/)**
32+
---
1433

15-
## Overview
34+
## ✨ Features
1635

17-
**git-scope** is a terminal-based dashboard that helps you manage multiple git repositories. It scans your configured directories, shows you which repos have uncommitted changes, and lets you jump into your editor with a single keystroke.
36+
- 🔍 **Fuzzy Search** — find any repo by name, path, or branch (`/`)
37+
- 🛡️ **Dirty Filter** — show only repos with uncommitted changes (`f`)
38+
- ⚡ **Fast Startup** — JSON caching → ~10ms launch time
39+
- 📊 **Dashboard** — branch, staged/unstaged counts, last commit time
40+
- ⌨️ **Keyboard-Driven** — Vim navigation (`j/k`), sorting (`s`, `1–4`)
41+
- 🚀 **Editor Jump** — open in VSCode, nvim, vim, helix (`Enter`)
42+
- 🌿 **Contribution Graph** — GitHub-style local heatmap (`g`)
43+
- 💾 **Disk Usage View** — `.git` + `node_modules` sizes (`d`)
44+
- ⏰ **Timeline View** — see recent repo activity (`t`)
45+
- 🔄 **Rescan Anytime** (`r`)
1846

19-
### Features
47+
---
2048

21-
- 🔍 **Fuzzy Search**: Find any repo by name, path, or branch with `/`
22-
- 🛡️ **Dirty Filter**: Press `f` to see only repos with uncommitted changes
23-
- ⚡ **Fast caching**: Instant startup using JSON caching
24-
- 📊 **Dashboard**: Shows branch, staged/unstaged counts, and last commit
25-
- ⌨️ **Keyboard-driven**: Vim-like navigation (`j`/`k`) and sorting (`s`)
26-
- 🚀 **Quick Jump**: Open any repo in your editor (VSCode, nvim, etc.) with `Enter`
27-
- 🌿 **Contribution Graph**: GitHub-style heatmap of your local commits (`g`)
28-
- 💾 **Disk Usage**: See `.git` and `node_modules` sizes at a glance (`d`)
29-
- ⏰ **Timeline**: What were you working on? See recent activity (`t`)
49+
## 💡 Why I Built This
3050

31-
## Installation
51+
I work across many small repositories — experiments, configs, microservices, side projects — and I kept forgetting which repos had uncommitted changes.
52+
53+
Every morning started like this:
3254

33-
### Homebrew (macOS/Linux)
3455
```bash
56+
cd repo-1 && git status
57+
cd repo-2 && git status
58+
cd repo-3 && git status
59+
# ...repeat for 20+ repos
60+
```
61+
62+
It was slow, repetitive, and easy to miss dirty repos.
63+
64+
I wanted a **single screen** that showed:
65+
66+
- which repos were dirty
67+
- which were ahead/behind
68+
- which had recent changes
69+
- which needed attention
70+
71+
No existing tool solved this well, especially for *many* repos.
72+
So I built `git-scope` to reduce friction and keep everything visible at a glance.
73+
74+
---
75+
76+
## 🆚 Comparison: git-scope vs lazygit
77+
78+
| Feature | git-scope | lazygit |
79+
|---------|-----------|---------|
80+
| **Scope** | Many repos at once | One repo at a time |
81+
| **Purpose** | Workspace overview | Deep repo interaction |
82+
| **Dirty status across repos** | ✔ Yes | ❌ No |
83+
| **Fuzzy repo search** | ✔ Yes | ❌ No |
84+
| **Jump to repo/editor** | ✔ Yes | ❌ No |
85+
| **Commit graph / diffs** | ❌ No | ✔ Yes |
86+
| **Disk usage** | ✔ Yes | ❌ No |
87+
| **Activity timeline** | ✔ Yes | ❌ No |
88+
| **Ideal for** | Multi-repo devs, microservices, config folders | Single-repo workflows |
89+
90+
**Summary:**
91+
`git-scope` = overview of all repos
92+
`lazygit` = powerful UI for one repo
93+
Most developers use both.
94+
95+
---
96+
97+
## 📦 Installation
98+
99+
### **Homebrew (macOS/Linux)**
100+
101+
```sh
35102
brew tap Bharath-code/tap
36103
brew install git-scope
37104
```
38105

39-
**To Update:**
40-
```bash
106+
**Upgrade:**
107+
108+
```sh
41109
brew upgrade git-scope
42110
```
43111

44-
### From Source
45-
```bash
112+
### **From Source**
113+
114+
```sh
46115
go install github.com/Bharath-code/git-scope/cmd/git-scope@latest
47116
```
48117

49-
**To Update:**
50-
Run the install command again to fetch the latest version.
118+
Upgrade by running the install command again.
51119

52-
## Usage
120+
---
53121

54-
### Launch TUI
55-
```bash
122+
## 🖥️ Usage
123+
124+
```sh
56125
git-scope
57126
```
58127

59-
### Configuration
60-
On first run, `git-scope` will auto-detect your directories. To customize, edit `~/.config/git-scope/config.yml`:
128+
---
129+
130+
## ⚙️ Configuration
131+
132+
Edit `~/.config/git-scope/config.yml`:
61133

62134
```yaml
63135
roots:
@@ -68,32 +140,49 @@ ignore:
68140
- node_modules
69141
- .venv
70142

71-
editor: code # or nvim, vim, helix
143+
editor: code # or nvim, vim, helix
72144
```
73145
74-
## Keyboard Shortcuts
146+
---
147+
148+
## ⌨️ Keyboard Shortcuts
75149
76150
| Key | Action |
77151
|-----|--------|
78-
| `/` | **Search** repos |
79-
| `f` | Toggle **Filter** (All/Dirty/Clean) |
80-
| `s` | Cycle **Sort** mode |
81-
| `1-4` | Sort by Dirty/Name/Branch/Recent |
82-
| `c` | **Clear** search & filters |
83-
| `Enter` | **Open** repo in editor |
84-
| `r` | **Rescan** directories |
85-
| `g` | Toggle **Grass** (contribution graph) |
86-
| `d` | Toggle **Disk** usage panel |
87-
| `t` | Toggle **Timeline** panel |
152+
| `/` | Search repos |
153+
| `f` | Filter (All / Dirty / Clean) |
154+
| `s` | Cycle sort mode |
155+
| `1–4` | Sort by Dirty / Name / Branch / Recent |
156+
| `Enter` | Open repo in editor |
157+
| `c` | Clear search & filters |
158+
| `r` | Rescan directories |
159+
| `g` | Toggle contribution graph |
160+
| `d` | Toggle disk usage view |
161+
| `t` | Toggle timeline |
88162
| `Esc` | Close panel |
89-
| `q` | **Quit** |
163+
| `q` | Quit |
164+
165+
---
90166

91-
## Roadmap
167+
## 🗺️ Roadmap
92168

93169
- [ ] Background file watcher
94-
- [ ] Quick actions (pull, push)
170+
- [ ] Quick actions (pull/push)
171+
- [ ] Repo grouping (service/team/workspace)
95172
- [ ] Team dashboards
96173

97-
## License
174+
---
175+
176+
## 🔎 Related Keywords (SEO)
177+
178+
git workspace manager, git dashboard, git repository monitor, git repo viewer, multi-repo git tool, git status all repos, git TUI, terminal UI git manager, TUI dashboard for git, Bubble Tea TUI example, Go TUI application, Go CLI tool, git productivity tools, developer workflow tools, microservices repo management, local git analytics, contribution graph terminal, disk usage analyzer TUI, git repo activity timeline, fast TUI for git, Go project for beginners, open source Go tools, devops git utilities, multi-folder git scanner, git monorepo alternative
179+
180+
---
181+
182+
## 📄 License
98183

99184
MIT
185+
186+
---
187+
188+
If you find this useful, a ⭐ star means a lot!

0 commit comments

Comments
 (0)