SaneGit — Smart Git Command Assistant

Features

Every command prints the same four-part structure—summary, risk, recommendation, and optional detail—so you can scan output quickly or pipe it to tooling.

Repository health

sg status summarizes branch position, working tree, and what to do next without reading raw git porcelain.

Smart commits (AI)

sg commit builds a commit plan from staged changes and asks before writing. Requires a configured provider.

Change explanation (AI)

sg explain turns diffs into plain-language intent and next steps. Requires a configured provider.

Safe pushes

sg push evaluates divergence, conflicts, and hosted signals before you publish.

Merge readiness

sg check scores integration risk against your target branch—not generic “commit linting.”

Guided recovery

sg fix walks common failure modes (conflicts, detached HEAD, interrupted rebase) with safe, confirmable steps.

Panic diagnostics

sg wtf runs urgent checks. Add --learn to record fault signals or --fix-ci for CI-focused remediation hints.

Delivery & history

sg sync, sg ship / sg ship --status, sg split, and sg time-travel --to … cover sync, ship pipelines, splitting commits, and safe navigation—including natural-language refs.

Team & ownership

sg who (optional --file for a file or directory), sg queue --team, and sg blame --file … --line … --explain add hosted and local context.

Deep checks

sg doctor reports repository health signals; sg pair --action … supports lightweight pair handoffs.

Provider choice

OpenAI, Anthropic, Google (Gemini), Mistral, or a custom HTTP endpoint via sg ai-configure (use --url for custom bases).

Degraded mode

When AI is missing or unreachable, commands that do not strictly need a model fall back to deterministic rules. AI-only commands exit with a clear message.

Commands

Install the sanegit package globally; invoke everything as sg <command>.

Core loop

sg status

Plain-English repository state and recommended next action.

sg explain

Explain current changes (requires AI).

sg commit

Proposed commit from staged files; confirms before git commit (requires AI).

sg push

Pre-push risk checks and safer publish flow.

sg check

Merge and integration readiness vs. a target branch.

Recovery & undo

sg fix

Guided recovery from common broken git states.

sg undo

List reversible rollbacks with explicit consequences.

sg wtf

Urgent diagnosis; --learn, --fix-ci.

Sync, ship, split

sg sync

Preserve local work while updating from mainline.

sg ship

One-command delivery; use sg ship --status for workflow state.

sg split

Propose logical commit groups from staged changes.

Team, hosting, history

sg who [--file <path>]

Ownership and collaborator context; path may be a file or directory.

sg queue --team

Merge queue visibility and risk hints.

sg blame --file <path> --line <n> --explain

Line history with rationale (hosted context when available).

sg time-travel --to <ref>

Resolve revisions safely, including natural-language references.

sg pair --action <start|status|handoff>

Pair sessions; use --session with status and handoff.

Diagnostics & AI setup

sg doctor

Deep repository health signals (HEAD, objects, working tree, etc.).

sg ai-configure

Set provider, --credential-ref, optional --url for custom APIs.

Summary: 2 files staged; branch even with origin/main.
Risk: low
Recommendation: Review diff, then commit or push when ready.
Detail: …

Typical workflow

You can stay entirely in rule-based commands, add AI only where it helps, and use hosted features when gh or remotes are available.

Orient. Run sg status after switching branches or pulling.
Review. Use sg explain (with AI) or read diffs; use sg check before a big merge.
Commit. Stage files, run sg commit when you want an AI-assisted message, or commit normally.
Publish. Use sg push or your team’s sg ship flow; follow sg ship --status if delivery is multi-step.
When something breaks, sg wtf first, then sg fix or sg undo as suggested.

Install & requirements

SaneGit is distributed as an npm package and runs on modern Node with git available on your PATH.

Requirements

Node.js 22+ (ESM; see package engines)
Git (any recent version)
Optional: API credentials for your AI provider
Optional: GitHub CLI (gh) for richer hosted context

From npm

                        Global CLI
                        npm install -g sanegit
                    

From source

                        git clone https://github.com/ntufar/sanegit.git

                        cd sanegit && npm install

                        npm run build && npm link

Configuration

Per-repository settings live under .sanegit/. Treat that directory as local-only and add it to .gitignore.

AI providers

openai, anthropic, google (Gemini), mistral
custom with --url pointing at your HTTP API

Secrets

API keys are not written into config files. Pass a credential reference—typically an environment variable name—via --credential-ref so secrets resolve at runtime.

                Non-interactive example
                sg ai-configure --provider openai --credential-ref OPENAI_API_KEY
            

AI-required commands

sg explain and sg commit need a working provider configuration. Other commands may still run with rules, hosted APIs, or local git data.

Quick start

Inside any git repository:

Check health

                $ cd my-repo && sg status
                sg status
            

Configure AI (optional)

                Interactive
                sg ai-configure
                
# or
                
sg ai-configure --provider openai --credential-ref OPENAI_API_KEY

Explain and commit (with AI)

                git add src/feature.ts

                sg explain

                sg commit

Ship or push

                sg push

                # or a full delivery flow

                sg ship

                sg ship --status

Resources

Source, detailed guide, and package metadata:

GitHub repository README Full guide Changelog npm package

Open source

SaneGit is MIT-licensed. Issues and contributions are welcome on GitHub.