Gitm

A fast C17 multi-repo Git registry manager. Maintains a list of Git repositories and provides commands to inspect, manage, and operate on them.

Zero third-party dependencies. Uses a custom argument parser, system Git, and POSIX APIs.

Features

• Registry of Git repositories — register repos with aliases, tags, and groups
• Batch operations — run status, branch, log, and remote queries across all repos
• Tag and group filtering — filter any command by tag or group
• Tabular output — --table flag for aligned, pipe-separated columns
• Orphan cleanup — find and remove repos that no longer exist on disk
• Health checks — verify all registered repos are valid Git repositories
• Per-repo exec — run arbitrary Git commands on a specific repo
• Clone and register — clone a Git repo and add it to the registry in one step
• Stale detection — find repos with no commits in the last N days
• Batch stash — stash dirty working trees across multiple repos at once
• Parallel execution — pthread thread pool for fast per-repo data collection
• Shell completion — built-in bash, zsh, and fish completion generation
• Coloured output — Rust clap-style coloured help and status output
• Structured logging — 7 severity levels (off, fatal, error, warn, info, debug, trace)

Requirements

• C17 compiler (gcc or clang)
• POSIX system (macOS, Linux)
• Git installed and available in $PATH
• pthreads (POSIX threads, included in libc on macOS/Linux)

Build

make help       # show available targets
make            # release build (-O3), outputs ./gitm
make debug -B   # debug build (-g3, ASan, UBSan)
make clean      # remove build artifacts
make install    # install to /usr/local/bin
make install PREFIX="$HOME/.local"  # custom prefix

Quick Start

# Register a repository
gitm add /path/to/repo my-alias

# Register with tags and groups
gitm add --tag c,project --group learning /path/to/repo my-alias

# List all registered repos
gitm list

# List repos in tabular format
gitm list --table

# Filter by tag or group
gitm list --tag c
gitm list --group learning

# Show status of all repos
gitm status
gitm status --table

# Run a git command on a specific repo
gitm exec my-alias log --oneline -10

# Health check
gitm doctor --table

# Tag and group frequency summary
gitm stats --table

# Clone a repo and register it
gitm clone https://github.com/user/repo

# Find stale repos (no commits in 30+ days)
gitm stale --table
gitm stale -d 60 --table

# Stash dirty working trees across repos
gitm stash
gitm stash --table

# Open config file in $EDITOR
gitm --edit-entry

Status Output

gitm status --table shows a compact summary of each repo's working tree:

Name         | Path                   | Status   | Branch
------------ + ---------------------- + -------- + ------
project-a    | /Users/dev/project-a   | clean    | main
project-b    | /Users/dev/project-b   | 3u       | dev
project-c    | /Users/dev/project-c   | 2m 1u    | main
project-d    | /Users/dev/project-d   | 1m 1d 3u | fix
project-e    | /Users/dev/project-e   | 1a       | main

Status tokens (space-separated):

Token	Meaning
m	Modified files
a	Staged (added)
d	Deleted files
u	Untracked files
o	Other changes

Each token is prefixed with a count. clean means no changes at all.

Commands

Command	Aliases	Description	--table
list	ls	List registered repositories	Yes
add	—	Register a Git repository	—
remove	rm	Unregister a repository	—
rename	—	Rename a repository alias	—
status	st, s	Show status of all registered repos	Yes
info	i	Show repository metadata	—
exec	x	Run a git command on a registered repo	—
open	o	Open a repository in $EDITOR	—
doctor	doc, d	Health check all registered repositories	Yes
recent	r	List repos sorted by last commit date	Yes
summary	sum	Total repos, branches, and size	—
search	find, f	Search repos by name or path pattern	—
list-tag	tags, lt	Show git tags with messages	Yes
remote	rem	Show remote settings	Yes
last	log, l	Show last commit log for each repo	Yes
branch	br, b	Show local branches	Yes
clean	prune	Remove repos that no longer exist on disk	—
stats	ts	Show tag and group frequency summary	Yes
stale	old	Show repos with no commits in N days	Yes
stash	sh	Stash dirty working trees across repos	Yes
clone	—	Clone a repository and register it	—

All commands that iterate repositories support --tag and --group filters.

Global Options

Flag	Short	Description
--log-level=LEVEL	-L	Set log verbosity: off, fatal, error, warn, info, debug, trace
--log-file=FILE	-F	Set logging file
--edit-entry	-E	Open registered_repos.txt in $EDITOR
--help	-h	Show help message
--version	-v	Show version
--shell-completion=SHELL	-S	Output completion script (bash, zsh, fish)

Configuration

Config file resolution order:

1. $XDG_DATA_HOME/gitm/registered_repos.txt (if XDG_DATA_HOME is set)
2. macOS: ~/Library/Application Support/gitm/registered_repos.txt
3. Linux: ~/.local/share/gitm/registered_repos.txt

Format (one entry per line):

/path:name:tag1,tag2:group1,group2

Fields after name are optional. Example:

/Users/dev/project-a:project-a:c,makefile:work,backend
/Users/dev/project-b:project-b:rust:learning

Lines starting with # are comments. Empty lines are ignored.

Platform Support

Platform	Status
macOS	Supported
Linux	Supported
Windows	Not supported (requires POSIX APIs)

License

MIT — see LICENSE.

Documentation

• DEV.md — architecture, build system, and developer guide
• DEV_IN_DEPTH.md — complete source walkthrough and internals