A lightweight, cross-platform CLI tool for discovering, organizing, and navigating git repositories on your local system.
Features
- Subcommand-Based CLI: Clean command structure with
list, init, add, refresh, cd, tag, user, parent, and worktree subcommands
- Compact Default View: Multi-column repository names at a glance, with verbose modes for detailed tables
- Repository Discovery: Automatically find all git repositories in a directory tree
- Automatic Classification: Detect repository type (GitHub, GitLab, Azure DevOps, Bitbucket) from remote URLs
- Dual-Purpose Filtering: Lowercase flags filter results; uppercase flags show columns with optional filtering
- Git Status Integration: View branch, clean/dirty state, and ahead/behind indicators with color output
- Smart Caching: Fast status display with configurable cache and concurrent workers (
--workers)
- Custom Tagging: Organize repositories with
omgw tag add / omgw tag remove
- Advanced Filtering: Search and filter repositories by type, tags, name, path, status, user, or remote URL
- User Profile Management: Manage git user profiles across repositories with
omgw user
- Repository Navigation: Jump to any repository instantly with
omgw <repo-name>
- Workspace Navigation: Jump to the workspace root with
omgw cd
- Parent Navigation: Navigate to a repository's parent directory with
omgw parent or omgw -p
- Worktree Management: Discover, navigate, create, and organize git worktrees with
omgw worktree
- XDG Layout: Config in
~/.config/gws/, worktrees in ~/.local/share/gws/projects/ — the same paths on Linux, macOS, and Windows
- Remote URL Display: View formatted or raw remote URLs with
--show-remote / --show-remote-raw
- External Repo Symlinks: Automatically creates workspace symlinks for repositories outside the workspace root
- Workspace Management: Track and organize repositories in a centralized configuration
- Cross-Platform: Works on Linux, macOS, and Windows
- Lightweight: Single binary with no external dependencies
Documentation
Full documentation is available at https://omgitworks.dev
Installation
Install via Homebrew
brew install daileyo/tap/omgitworks
Homebrew 7.0 refuses to load formulae from untrusted third-party taps. The command above is
unaffected — naming the tap explicitly trusts that formula. If you tap first and install by
bare name, run brew trust daileyo/tap in between.
See the Getting Started guide for additional installation options.
Development
One-Time Setup
Git hooks are provided in .githooks/ for pre-push checks and commit message formatting. Activate them once after cloning:
make setup-hooks
Build Commands
# Build the binary
make build
# Run tests
make test
# Run all CI checks (vet, lint, test with race detector)
make ci
# Clean build artifacts
make clean
# Install to GOPATH/bin
make install
Running Tests
# Run all tests
go test ./...
# Run tests with verbose output
go test -v ./...
# Run tests for a specific package
go test -v ./internal/config
Building the Documentation Site
# Install Python dependencies
pip install -r docs/requirements.txt
# Preview locally
python -m mkdocs serve
# Build static site
python -m mkdocs build
Project Structure
.
├── cmd/
│ └── omgitworks/ # Main application entry point
├── internal/
│ ├── classifier/ # Repository classification
│ ├── config/ # Configuration management
│ ├── discovery/ # Repository discovery
│ ├── filter/ # Repository filtering logic
│ ├── git/ # Git status integration
│ ├── user/ # Git user profile management
│ └── xdg/ # XDG base directory resolution
├── docs/
│ ├── site/ # MkDocs documentation source
│ ├── specs/ # Specification documents
│ └── requirements.txt # Python dependencies (MkDocs)
├── Makefile # Build automation
├── mkdocs.yml # Documentation site configuration
├── go.mod # Go module definition
└── README.md # This file
Contributing
This project is not currently open for external contributions. This may change in the future as the project matures.
If you're interested in contributing or have ideas to share, please open an issue or reach out directly — feedback is always welcome.
Commit Message Format
This project uses Conventional Commits for automated versioning:
<type>[optional scope]: <description>
Types:
feat: New feature (triggers MINOR version bump)fix: Bug fix (triggers PATCH version bump)docs: Documentation onlystyle: Code style (formatting, semicolons, etc.)refactor: Code refactoringperf: Performance improvementtest: Adding or updating testschore: Maintenance tasksci: CI/CD changes
Breaking Changes:
Add ! after the type or include BREAKING CHANGE: in the footer to trigger a MAJOR version bump:
feat!: remove deprecated API
License
Apache 2.0 — see LICENSE for details.
