A modern Go-based CLI tool for managing Git projects and directories, replacing legacy shell scripts with better performance and native database storage.
- Project Discovery: Automatically scan and catalog Git repositories
- Locate Integration: 34x faster discovery using system locate database
- GitHub Sync: Daily sync of repository metadata (topics, languages, activity)
- Directory Management: Track frequently accessed directories
- GitHub Integration: Discover and manage GitHub repositories
- Database Storage: SQLite-based persistent storage with XDG compliance
- Performance: Fast, native Go implementation with intelligent caching
Gum delivers exceptional performance through multiple optimization strategies:
- 34x Speed Improvement: Project discovery in 0.125s vs 4.3s with file system scanning
- Automatic Detection: Works with plocate, GNU locate, and BSD locate
- Smart Fallback: Graceful degradation when locate is unavailable
- Database Monitoring: Warns users about stale locate databases
- Native Go: Compiled binary with no runtime dependencies
- Cron-Based Updates: Background processes keep data fresh without user delays
- Database Optimization: SQLite with WAL mode for concurrent access
- Parallel Processing: Concurrent directory scanning
- Hybrid Approach: Combines locate bulk discovery with file system accuracy
- Instant Response: Always returns cached data immediately
- Go 1.21+: Required for building from source
- SQLite3: Required for database operations (usually pre-installed on most systems)
git clone https://github.com/shalomb/gum.git
cd gum
make install
# Verify installation
gum versionThis automatically:
- Builds gum from source
- Installs to
~/.local/bin/gum(user location) - Sets proper permissions
- Provides PATH configuration guidance
User Installation (Recommended)
make install-user
# Creates ~/.local/bin if needed
# No sudo requiredSystem Installation
make install
# Tries user location first, falls back to system
# May require sudo for system-wide installationManual Installation
make build
cp gum ~/.local/bin/
chmod +x ~/.local/bin/gumIf ~/.local/bin is not in your PATH, add this to your shell profile:
export PATH="$HOME/.local/bin:$PATH"Gum uses SQLite3 for persistent storage. The database is stored in:
- Location:
~/.cache/gum/gum.db(XDG compliant) - Driver:
github.com/mattn/go-sqlite3
# List all discovered Git projects
gum projects
# List projects with different output formats
gum projects --format json
gum projects --format fzf
gum projects --format simple
# Force refresh project cache
gum projects --refresh
# Clear project cache
gum projects --clear-cache# List frequently accessed directories
gum dirs
# List directories with verbose output
gum dirs --verbose
# Force refresh directory cache
gum dirs --refresh# List GitHub repositories
gum github
# Clone a GitHub repository
gum clone <repository-url>Gum automatically discovers project directories by scanning:
~/projects/(default)~/projects-*(glob pattern)~/code/(default)
Gum uses SQLite with the following main tables:
projects: Git repositories found in project directoriesproject_dirs: Directories that contain projectsgithub_repos: Repositories discovered via GitHub APIdir_usage: Directory usage tracking for frequency scoring
See internal/database/schema.sql for the complete schema.
Gum follows XDG Base Directory specification:
- Config:
~/.config/(for configuration files) - Cache:
~/.cache/gum/(for database and temporary data) - State:
~/.local/state/gum/(for runtime state, planned)
For optimal performance, set up cron jobs to keep data fresh:
# Add to crontab (crontab -e)
0 */6 * * * gum projects --refresh # Refresh projects every 6 hours
0 * * * * gum dirs --refresh # Refresh directories every hourThis ensures data is always fresh without impacting user response times.
go build -o gumgo test ./...The database is automatically initialized on first run. You can inspect it directly:
sqlite3 ~/.cache/gum/gum.dbCommand not found
# Check if gum is installed
which gum
# If not found, check PATH
echo $PATH | grep -q ".local/bin" || echo "~/.local/bin not in PATH"
# Add to PATH if needed
export PATH="$HOME/.local/bin:$PATH"Permission denied
# Check permissions
ls -la ~/.local/bin/gum
# Fix permissions if needed
chmod +x ~/.local/bin/gumSQLite not found
# Install SQLite3
sudo apt-get install sqlite3 # Ubuntu/Debian
brew install sqlite3 # macOSNo projects found
# Check if directories exist
ls -la ~/projects ~/code ~/dev
# Force refresh discovery
gum projects --refreshConfig generation issues
# Check config directory
ls -la ~/.config/gum/
# Manually create if needed
mkdir -p ~/.config/gumGum replaces the following legacy shell scripts:
projects-list→gum projectscwds-list→gum dirs
The tool automatically migrates existing ~/.config/projects-dirs.list configuration.
See LICENSE file for details.
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
- CLI: Cobra-based command structure
- Database: SQLite with WAL mode for concurrency
- Caching: Intelligent TTL-based caching system
- XDG: Full XDG Base Directory compliance
- Performance: Native Go with optimized database queries