/git-audit - Git Repository Health Audit

Scan directory trees for Git repositories (including submodules), collect metadata, and produce actionable audit reports.

System Prompt

EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

1. Determine scan root — Use the provided path, or default to current working directory
2. Run the audit script — Execute python3 scripts/git_audit.py [ROOT] [OPTIONS]
3. Display results — Show the summary table and key findings
4. Highlight critical issues — Flag repos with uncommitted changes, missing remotes, or stale activity
5. Suggest remediation — Offer specific git commands for each flagged repo

Script location: scripts/git_audit.py (stdlib only, no external deps)

---

Usage

/git-audit                           # Scan current directory
/git-audit ~/PROJECTS                # Scan specific root
/git-audit . --days 60               # Custom stale threshold (60 days)
/git-audit . --output report.md      # Save report to file
/git-audit . --json                  # JSON output
/git-audit . --json --output a.json  # JSON to file

Options

Option	Description	Default
root	Directory to scan	. (current)
-o, --output FILE	Write report to file	stdout
--days N	Stale threshold in days	30
--json	Output JSON instead of Markdown	Markdown

What It Detects

Issue	Description
UNSTAGED(n)	Modified/deleted files not yet staged
UNTRACKED(n)	New files not added to git
STAGED_UNCOMMITTED(n)	Staged files not yet committed
NO_REMOTE	No origin remote configured
STALE(Nd)	No activity in N days
EMPTY_REPO	Repository has zero commits

Output

Markdown (default)

• Summary table with counts
• Per-repo detail table (path, branch, activity, status, issues)
• Grouped opportunities (dirty, no-remote, stale)
• Recommended actions

JSON

• Array of RepoInfo objects with all metadata fields
• Suitable for piping to jq or programmatic processing

Examples

# Quick health check of submodules
/git-audit submodules/

# Find repos stale for 2+ weeks
/git-audit ~/PROJECTS --days 14

# Export JSON for dashboarding
/git-audit ~/PROJECTS --json --output audit.json

Safety

• Read-only — never modifies repos, only reads state
• Symlink-safe — followlinks=False prevents loops
• Timeout-protected — 15s per git command
• No dependencies — Python stdlib only

Related

• /git-sync — Push/pull coditect-core between dev and protected
• skills/git-audit-patterns — Full skill with workflow patterns
• hooks/git-audit-scheduled.md — Periodic audit trigger
• hooks/git-audit-pre-push.md — Pre-push dirty repo warning