SaneGit

🌐 Visit the website →

SaneGit is a CLI assistant that makes git usable by predicting problems, fixing them automatically, and explaining everything in plain English.

Stop struggling with cryptic git errors. SaneGit helps you understand repository state, avoid risky pushes, recover from failures, and commit with confidence.

Features

• 🔍 Understand state — sg status shows repository health in plain language
• 📝 Smart commits — sg commit proposes a message and file list; confirms before writing (requires a configured AI provider)
• 🛡️ Safe pushes — sg push predicts risks and blocks unsafe operations
• 🔧 Auto-recovery — sg fix guides you through merge conflicts, detached HEAD, and more
• 📊 What's the Fault? — sg wtf diagnoses urgent problems; optional --learn (record fault signals) and --fix-ci (CI-focused remediation)
• 🤖 AI-powered — OpenAI, Anthropic, Google (Gemini), Mistral, or a custom HTTP endpoint
• 📖 Plain English — Structured output (summary, risk, recommendation, detail) across commands
• 💾 Degrades gracefully — Rule-based fallbacks when AI is unavailable or not configured

📖 Full documentation

Quick Start

# Install from npm
npm install -g sanegit

# Check your repository state
cd my-project
sg status

# Configure AI provider (optional; needed for AI-heavy commands like explain/commit)
sg ai-configure --provider openai --credential-ref OPENAI_API_KEY

# Explore commands
sg explain        # Explain current changes (needs AI)
sg commit         # Proposed commit from staged changes (needs AI)
sg push           # Pre-push safety checks
sg check          # Merge readiness assessment
sg fix            # Recover from failures
sg undo           # List and apply safe rollbacks
sg wtf            # Diagnose problems; add --learn or --fix-ci as needed
sg ship           # Delivery flow; use sg ship --status to resume/track

Install

From npm (recommended):

npm install -g sanegit

From source:

git clone https://github.com/ntufar/sanegit.git
cd sanegit
npm install
npm run build
npm link

Commands at a Glance

Command	Purpose
sg status	Repository state and next actions
sg explain	Plain-English change explanation (AI)
sg commit	Guided commit plan from staged changes (AI)
sg push	Pre-push risk evaluation
sg check	Merge readiness assessment
sg fix	Guided recovery from common git failures
sg undo	Safe rollback options with consequences
sg wtf	Urgent diagnosis; --learn, --fix-ci
sg sync	Preserve local work and synchronize with mainline
sg ship	One-command delivery flow; --status for workflow state
sg split	Propose logical commit groups from staged changes
sg who	Collaborator ownership; optional --file (file or directory)
sg queue --team	Merge queue impact and risk hints
sg blame --file <path> --line <n> --explain	Line history with hosted context
sg time-travel --to <ref>	Resolve refs safely, including natural-language targets
sg pair	Pair sessions: --action start, status, or handoff (use --session with the latter two)
sg doctor	Deep repository health diagnostics
sg ai-configure	AI provider, --url for custom base URL, --credential-ref

Configuration

SaneGit stores configuration in .sanegit/config.json (intended to be gitignored). Secrets are not stored in the file: pass a credential reference (environment variable name or keychain entry) via sg ai-configure --credential-ref …. Use --url with --provider custom for a custom API base URL.

sg ai-configure --provider openai --credential-ref OPENAI_API_KEY

# Add to .gitignore:
.sanegit/

Commands that depend on AI exit early with a clear message when no provider is configured; others use rule-based or hosted-context data where applicable.

Requirements

• Node.js 22+ (see engines in package.json)
• Git (any recent version)
• Optional: API access for your chosen AI provider

Development

git clone https://github.com/ntufar/sanegit.git
cd sanegit
npm install

npm run build       # Compile TypeScript to dist/
npm run dev         # Run CLI via tsx (src/cli.ts)
npm run lint        # ESLint
npm run typecheck   # TypeScript --noEmit
npm run test        # Vitest (36 test files, 54 tests)
npm run format      # Prettier

# Focused suites (see package.json for more)
npm run test:unit
npm run test:integration
npm run test:contract

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit with descriptive messages
4. Push and open a pull request

License

MIT — See LICENSE for details

Changelog

See CHANGELOG.md for release history.

Resources

• Full documentation: doc/guide.md
• GitHub Pages: docs/index.html (published site: ntufar.github.io/sanegit)
• API specification: specs/001-sanegit-cli/contracts/cli-contract.md
• Feature spec: specs/001-sanegit-cli/spec.md
• GitHub: github.com/ntufar/sanegit
• npm: npmjs.com/package/sanegit

---

Made with ❤️ to make git less frustrating.