git-dirs

Executive Summary

git-dirs is a lightweight, cross-platform CLI utility that indexes Git repositories across your filesystem and exposes fast listing, navigation, and link-generation commands to simplify repository discovery. It reduces friction when working with many local repositories by providing a small, configurable index and shell-friendly navigation helpers.

Key Features

• Scans configured directories and indexes local Git repositories into a JSON-backed catalog.
• ls subcommand to list indexed repositories with sorting and simple/fuzzy search support.
• cd subcommand that integrates with a shell wrapper to change the active shell directory to a selected repo.
• track subcommand to add, remove, or list tracked repository paths.
• link subcommand to generate a directory of symlinks or shortcuts that point to tracked repositories.
• Cross-platform helpers for Windows and Unix-like systems (internal/*_windows.go, internal/*_unix.go).
• Simple, human-readable storage (file-based JSON) and layered configuration (config/app.yaml, internal/config/usercfg).
• Modular codebase using cobra for CLI structure and logrus for configurable logging.

Tech Stack

• Language: Go (primary)
• CLI framework: github.com/spf13/cobra
• Logging: github.com/sirupsen/logrus
• Storage: JSON file (user-configurable path)
• Shell integration: small shell wrapper (internal/shwrap)
• Installer helpers: shell and PowerShell scripts (cmd/installer/script)
• Tooling: Go toolchain, Git

Installation & Usage

Clone the repository, then build or run the CLI via the Go toolchain.

Build and run (development)

# Run directly (development)
go run ./cmd/app

# Build a binary
go build -o git-dirs ./cmd/app
./git-dirs --help

Installer (optional)

# Installer can register shell integration and place binaries; may require elevated privileges
go run ./cmd/installer -b -i

# On Unix-like systems:
sudo -E env "PATH=$PATH" go run ./cmd/installer -b -i

Common commands

# List tracked repositories
git-dirs ls

# Scan configured roots and update index
git-dirs index

# Add a repo path to tracking
git-dirs track /path/to/repo

# Generate/update a directory of links to tracked repos
git-dirs link

# Change directory into a repo (requires the shell wrapper)
git-dirs cd <repo-name-or-pattern>

Configuration

• Defaults are in config/app.yaml. User-specific settings are handled under internal/config/usercfg.
• Indexed repository data is stored in a JSON file (see internal/db/repos.go) — simple to inspect and migrate.

Project Status & Notes

• Early-stage prototype: the CLI surface, storage format, and internal implementation are subject to significant changes as the project evolves.
• Possible future directions include splitting the CLI into separate tools (for example: git-cd and git-ls / git-dirs) or a rewrite in a lower-level language for performance.
• The current code prioritizes clarity and maintainability over micro-optimizations; some parts are intentionally unoptimized to speed iteration and review.
• If you modify code that affects the on-disk index, include migration guidance in commits or documentation.

Where to Look (Developer Pointers)

• CLI entrypoint: cmd/app/main.go
• Subcommands: cmd/app/cmd (ls, cd, track, link, index)
• Storage & models: internal/db/repos.go
• Search helpers: internal/util/search
• Shell wrapper: internal/shwrap/shwrap.go
• Installer scripts: cmd/installer/script

License

This project is released under the MIT License. See LICENSE for details.