https://github.com/darksworm/gitagrip
gitagrip is a lightning-fast terminal UI for managing many Git repositories: auto-discover from a directory, group by folder or custom sets, see branch/dirty/ahead-behind at a glance, run safe fetch and view logs, and persist setup via TOML.
https://github.com/darksworm/gitagrip
Last synced: 9 months ago
JSON representation
gitagrip is a lightning-fast terminal UI for managing many Git repositories: auto-discover from a directory, group by folder or custom sets, see branch/dirty/ahead-behind at a glance, run safe fetch and view logs, and persist setup via TOML.
- Host: GitHub
- URL: https://github.com/darksworm/gitagrip
- Owner: darksworm
- License: gpl-3.0
- Created: 2025-09-05T05:06:34.000Z (10 months ago)
- Default Branch: master
- Last Pushed: 2025-10-03T19:09:53.000Z (9 months ago)
- Last Synced: 2025-10-03T21:13:35.582Z (9 months ago)
- Language: Go
- Homepage:
- Size: 56 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# gitagrip
[](https://github.com/darksworm/gitagrip/releases/latest)
[](https://github.com/darksworm/gitagrip/releases/latest)
[](./LICENSE)
[](https://github.com/darksworm/gitagrip/actions/workflows/test.yml)
> [!IMPORTANT]
> This project is currently in DEVELOPMENT and is not stable
A fast, keyboard-driven terminal UI for discovering, grouping, and inspecting multiple Git repositories. Written in Go using Bubble Tea for a responsive, efficient experience.
## ✨ Features
- 🚀 **Fast Repository Discovery**: Automatically scans directories to find all Git repositories
- 📁 **Smart Grouping**: Organize repositories by directory structure or custom groups
- 📊 **Rich Git Status**: Shows branch names, dirty status, ahead/behind counts, and more
- 🎨 **Colored Branch Display**: Main/master branches in bold green, others get consistent colors
- ⚡ **Non-blocking UI**: Background operations keep the interface responsive
- 🔍 **Search & Filter**: Quickly find repositories with powerful search and filtering
- 📦 **Zero Dependencies**: Single binary with no runtime requirements except git
## 🚀 Installation
Quick Install (Linux/macOS)
```bash
curl -sSL https://raw.githubusercontent.com/darksworm/gitagrip/main/install.sh | sh
```
Install a specific version:
```bash
curl -sSL https://raw.githubusercontent.com/darksworm/gitagrip/main/install.sh | sh -s -- v0.1.0
```
Homebrew (macOS/Linux)
```bash
brew tap darksworm/homebrew-tap
brew install gitagrip
```
AUR (Arch Linux)
```bash
yay -S gitagrip-bin
# or
paru -S gitagrip-bin
```
Docker
```bash
# Run with current directory
docker run --rm -it -v $(pwd):/repos ghcr.io/darksworm/gitagrip:latest
# Run with specific directory
docker run --rm -it -v /path/to/repos:/repos ghcr.io/darksworm/gitagrip:latest
```
Go Install
```bash
go install github.com/darksworm/gitagrip@latest
```
Download Binary
Download the appropriate binary for your platform from the [releases page](https://github.com/darksworm/gitagrip/releases/latest).
**Linux/macOS:**
```bash
# Download (replace VERSION and PLATFORM)
curl -LO https://github.com/darksworm/gitagrip/releases/download/vVERSION/gitagrip-VERSION-PLATFORM.tar.gz
# Extract
tar -xzf gitagrip-VERSION-PLATFORM.tar.gz
# Install
sudo mv gitagrip /usr/local/bin/
```
**Windows:**
Download the `.zip` file, extract, and add to your PATH.
## 📖 Usage
```bash
# Scan current directory
gitagrip
# Scan specific directory (using flag)
gitagrip -dir /path/to/repos
gitagrip -d /path/to/repos # shorthand
# Scan specific directory (as argument)
gitagrip /path/to/repos
```
## ⌨️ Keyboard Shortcuts
### Navigation
- `↑/↓`, `j/k` - Navigate up/down
- `←/→`, `h/l` - Collapse/expand groups
- `PgUp/PgDn` - Page up/down
- `gg/G` - Go to top/bottom
### Selection
- `Space` - Toggle selection
- `a/A` - Select/deselect all
- `Esc` - Clear selection
### Repository Actions
Note: Enter integration requires lazygit to be installed and available in PATH.
- `Enter` - Open lazygit for the selected repository
- `H` - View git log
- `D` - View git diff
- `r` - Refresh repository status
- `f` - Fetch from remote
- `p` - Pull from remote
- `i` - Show repository info
- `I` - View repository command logs (pager)
### Group Management
- `z` - Toggle group expansion
- `N` - Create new group (with selection)
- `m` - Move repositories to group
- `Shift+R` - Rename group
- `Shift+J/K` - Move group up/down
- `d` - Delete group (when on group header)
### Search & Filter
- `/` - Search repositories
- `n` - Next search result
- `Shift+N` - Previous search result
- `F` - Filter repositories
- `s` - Sort options
### Other
- `?` - Show help
- `q` - Quit
### Filter Examples
- `status:dirty` - Show only repositories with uncommitted changes
- `status:clean` - Show only clean repositories
- `status:ahead` - Show repositories ahead of remote
## 🖥️ Interface
```
gitagrip ↻ Refreshing 2 ↓ Fetching 1
▼ Work (2)
● project-api (feature/auth ↑2↓1)
✓ project-web (main)
▼ Personal (3)
✓ dotfiles (master)
● blog (draft-post)
⚠ old-project (cleanup ⚠)
▶ Archived (5)
Press ? for help
```
### Status Indicators
- `✓` Clean repository
- `●` Dirty repository (uncommitted changes)
- `⚠` Repository with errors
- `⋯` Loading status
- `?` Unknown status
### Branch Colors
- **Bold Green**: main/master branches
- **Various Colors**: Other branches get consistent colors based on name
## Lazygit Integration
To enable Enter → lazygit, install lazygit:
- macOS (Homebrew): `brew install lazygit`
- Linux: `sudo pacman -S lazygit` (Arch) or see release binaries at https://github.com/jesseduffield/lazygit
- Go install (latest): `go install github.com/jesseduffield/lazygit@latest`
You can override the lazygit binary path via the `GITAGRIP_LAZYGIT_BIN` environment variable for testing.
## 🛠️ Development
### Prerequisites
- Go 1.21 or later
- Git
### Building from Source
```bash
# Clone the repository
git clone https://github.com/darksworm/gitagrip.git
cd gitagrip
# Build
go build
# Run tests
go test ./...
# Install locally
go install
```
### Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
Please follow conventional commits for your commit messages.
## 📄 License
This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
Built with:
- [Bubble Tea](https://github.com/charmbracelet/bubbletea) - Terminal UI framework
- [Lipgloss](https://github.com/charmbracelet/lipgloss) - Terminal styling
- [Bubble](https://github.com/charmbracelet/bubbles) - TUI components
- And the amazing Go community 💙