🆘 git-mistake

Describe your git disaster in plain English. Get exact fix commands instantly.

Why

Git has ~150 commands and error messages designed by a kernel hacker in 2005. Every developer — from interns to 10-year veterans — eventually types the wrong thing and freezes. git-mistake reads your actual repo state, understands what went wrong, and tells you exactly what to run.

No Stack Overflow rabbit hole. No guessing. Just the fix.

Install

pip install git-mistake

Or run without installing:

pipx run git-mistake "your problem here"

Usage

# Describe your problem directly
git-mistake "I accidentally ran git reset --hard and lost my commits"
git-mistake "I committed to the wrong branch"
git-mistake "I have a merge conflict and I don't know how to resolve it"
git-mistake "I accidentally pushed my API key to GitHub"
git-mistake "I'm in a detached HEAD state"

# Interactive mode — just run with no arguments
git-mistake

# Pattern matching only — no AI, works fully offline
git-mistake --no-ai "I did git reset --hard"

# Dump your current git state (useful for bug reports)
git-mistake --context

How It Works

Your repo state              Your problem description
      │                               │
      └──────────────┬────────────────┘
                     ▼
          ┌─────────────────────┐
          │  Pattern Matcher    │  ← Covers ~80% of cases instantly, offline
          └────────┬────────────┘
                   │ No match?
                   ▼
          ┌─────────────────────┐
          │  AI Engine          │  ← Handles complex/unusual situations
          └────────┬────────────┘
                   │
                   ▼
         Exact fix commands + explanation

Stage 1 — Offline pattern matching reads your git reflog, git status, and in-progress operation flags (merge, rebase, cherry-pick) to instantly resolve common disasters without any API call.

Stage 2 — AI fallback kicks in for complex or unusual situations. Supports 3 providers — set whichever key you have.

Covered Scenarios

AI Setup (Optional)

Works offline for common cases. For complex issues, set any one of these:

# Set whichever you have — only one needed
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENROUTER_API_KEY="sk-or-..."
export NVIDIA_API_KEY="nvapi-..."

# Make it permanent
echo 'export OPENROUTER_API_KEY="sk-or-..."' >> ~/.zshrc

# Override the default model
export OPENROUTER_MODEL="google/gemma-3-27b-it"
export NVIDIA_MODEL="meta/llama-3.3-70b-instruct"

OpenRouter and NVIDIA NIM both have free tiers — no credit card needed.

Architecture

git-mistake/
├── git_mistake/
│   ├── cli.py        # Entry point, argument parsing, orchestration
│   ├── context.py    # Reads all git state (reflog, status, flags)
│   ├── detector.py   # Fast offline pattern matching (~80% of cases)
│   ├── ai_helper.py  # Multi-provider AI fallback (Anthropic / OpenRouter / NVIDIA)
│   └── display.py    # Terminal colors and formatted output
├── tests/
│   └── test_detector.py   # 18 unit tests
├── .github/workflows/ci.yml
└── pyproject.toml

Design decisions:

• Zero dependencies — stdlib only (subprocess, urllib, json). No requests, no rich, no click.
• Offline-first — pattern matching runs before any API call is made.
• Context-aware — reads actual .git/ state, not just your description.
• Safe by default — always suggests a backup branch before destructive commands.

Contributing

Bug reports with git-mistake --context output are incredibly useful. PRs adding new patterns to detector.py are always welcome.

git clone https://github.com/thalha-a9/git-mistake
cd git-mistake
pip install -e .
python -m pytest tests/ -v

License

MIT — see LICENSE

Built for every developer who has typed git reset and immediately regretted it.