human-git (human)

An intent-based, human-friendly Git CLI written in TypeScript.

Express your intent naturally instead of remembering arcane Git syntax:

human push my work to main
human switch to feature/payment
human create a branch called feature/auth
human show my changes

⚡ Installation

Install globally using your favorite package manager:

# npm
npm install -g human-git

# bun
bun install -g human-git

# pnpm
pnpm add -g human-git

Or run directly without installing:

npx human-git show status
bunx human-git show status

🚀 Quick Start

Run human from anywhere:

1. Project Setup & Remotes

human init                     # Start a new Git repository here
human clone <url>              # Clone repository from URL
human show remotes             # Show configured remote repositories
human connect to <url>         # Set origin remote to URL
human add remote <name> <url>  # Add custom remote

2. Staging & Unstaging

human stage everything         # Stage all changes (git add -A)
human stage src/index.ts       # Stage specific file(s)
human unstage everything       # Unstage all staged changes
human unstage src/index.ts     # Unstage specific file(s)

3. Commits & Amending

human commit all "feat: add user login"  # Stage everything + commit in 1 step
human commit "fix: resolve bug"          # Commit already staged changes
human add this to last commit            # Amend last commit with staged changes
human change last commit message to "..." # Update last commit message
human undo last commit                   # Soft reset HEAD~1 (keeps working tree intact)

4. Work Preservation (Stashing)

human save my work for later   # Stash uncommitted changes
human restore my saved work    # Pop stash (restore saved work)
human show saved work          # List all saved stashes

5. Repository Inspection

human show status              # Current repo status
human show my changes          # Working directory diff
human show branches            # List all branches
human what branch am i on      # Current branch name
human show recent commits      # Last 10 commits
human show recent commits 5    # Last 5 commits
human show last commit         # Detailed last commit view

6. Branch Management

human switch to main
human checkout feature/auth
human create a branch called feature/login
human make a branch feature/experiment
human delete branch feature/old-work

7. Merging & Conflict Lifesavers

human merge feature/auth into main  # Switch to main and merge feature/auth
human merge feature/auth            # Merge feature/auth into current branch
human abort merge                   # Cancel and abort an in-progress merge
human show conflicts                # List conflicted files
human sync with main                # Rebase current branch on origin/main

8. Syncing & Remotes

human push my work
human push my work to main
human pull
human pull from main

9. Guarded Discarding

human discard all uncommitted changes  # Destructive: prompts for confirmation [y/N]

10. Releases & Tags

human tag release v1.1.0       # Create a tag at current HEAD
human show tags                # List all tags

🛡️ Safety & Guardrails

human-git is built with safety as a first-class citizen:

1. Risk Classification: Actions are categorized as SAFE, CAUTION, or DANGEROUS.
2. Context-Aware Protection: If you attempt to switch branches or merge with uncommitted changes, human warns or asks for confirmation so you never lose work.
3. No Shell Injections: Git commands execute directly via child process arguments with shell: false.
4. Actionable Suggestions: If a branch name is misspelled, human inspects the repository and prints available branches.
5. No Blind Aliases: Every phrase is parsed into a structured intent, evaluated against repository state, and verified before execution.

🔍 Preview & Explain Modes

Dry Run (--dry-run)

Preview what Git command would execute without touching repository state:

human --dry-run push my work to main

Explain Subcommand

Understand how human translates your intent into Git commands:

human explain push my work to main

Skip Prompts (--yes, -y)

For scripting or CI environments:

human --yes push my work to main

💡 Smart UX Features

1. Typo Auto-Recovery ("Did You Mean...?")

If you misspell a command or verb, human automatically detects your intent:

$ human swich to main

  ? I didn't recognize: "swich to main"
  Did you mean: human switch to main?

  Run this command now? [Y/n]

Pressing Enter or Y executes the corrected command immediately.

2. Built-In Cheatsheet

View all available natural-language phrases organized by category:

human commands
# or
human cheatsheet

3. Native Shell Completion (Bash, Zsh, Fish)

Enable instant tab completion in your shell:

# Zsh (macOS / Linux)
eval "$(human completion zsh)"

# Bash (Linux / WSL / Git Bash)
eval "$(human completion bash)"

# Fish
human completion fish | source

🏗️ Architecture

User Language ──> Parser ──> Intent ──> Repository Context ──> Planner ──> Safety Check ──> Git Executor

• Deterministic Parser: Fast, deterministic regex rules (sub-millisecond parsing).
• Zod Validation: Strict runtime schema validation on all recognized intents.
• Git Context Service: Queries current repository state via Git porcelain plumbing.
• Vitest Suite: 182 comprehensive automated tests covering parsing, planning, risk levels, and real Git integration.

📄 License

MIT © git-human contributors