gitgen

Git workflows in your terminal — AI commits included

Type less. Commit better. Ship faster.

gg cnp · add · AI Conventional Commit · push

npm install -g git-command-generator
gg setup          # one-time OpenRouter setup
gg cnp            # commit + push with AI message

What it does

gitgen (gg) is a terminal CLI that runs everyday Git workflows as short commands — and can write your commit message from the real git diff via OpenRouter.

No browser required. No accounts beyond an optional OpenRouter key. Works in any repo folder on Windows, macOS, and Linux.

| You type | What runs | |----------|-----------| | gg cnp | git add . → AI commit → git push | | gg cnp pr | commit → push → AI PR title/body → gh pr create | | gg pr [base] | commit if dirty → push → AI PR → open PR into base (default: main) | | gg b feature/login | new branch → add → commit → push -u | | gg m feature/login | commit work → merge into main → push | | gg s | commit work → checkout main |

Messages follow Conventional Commits (feat:, fix:, chore:, …). Pass -m anytime to skip AI.

Install

Requirements: Node.js 18+ and Git on your PATH.
For pull requests: GitHub CLI (gh) authenticated with gh auth login.

npm install -g git-command-generator

This puts three commands on your PATH (same binary):

| Command | Notes | |---------|--------| | gg | Short name — recommended | | gitgen | Full name | | git-gen | Alias |

Verify:

gg version
# or: gitgen version · gg v · gitgen --version

You should see the version, install path, and config path.

Update

gg update
# or: npm update -g git-command-generator

Uninstall

npm uninstall -g git-command-generator

Quick start

# 1. Install
npm install -g git-command-generator

# 2. One-time AI setup (API key is hidden as you type)
gg setup

# 3. In any git repo
cd your-project
gg cnp                 # stage everything, AI commit message, push

Without an API key, commits still work — they use sensible defaults (feat: update, wip: saving progress, …). Run gg setup when you want AI-written messages.

Bare gg / gitgen prints help. It does not open a browser.

Commands

All of these work with gg, gitgen, or git-gen.

Workflows

| Short | Long | Description | |-------|------|-------------| | gg c | gg commit | Stage all → commit (no push) | | gg c p | gg commit push | Stage all → commit → push | | gg cnp | gg commit-and-push | Same as commit + push (one token) | | gg cnp pr | gg commit-and-push pr | Commit → push → AI PR title/body → create PR (asks base) | | gg cnp pr develop | same | Same, base branch = develop (no prompt for base) | | gg pr | gg pr | Commit if dirty → push → AI PR → gh pr create (asks base) | | gg pr main | gg pr main | Same, merge target = main | | gg pr -y | gg pr -y | PR into default base (no base prompt) | | gg b <name> | gg branch <name> | Create branch → add → commit → push -u origin <name> | | gg m <src> [dst] | gg merge <src> [dst] | Commit → checkout dst (default main) → merge src → push | | gg s | gg save | Commit current work → checkout main | | gg sw <branch> | gg switch <branch> | Checkout a branch | | gg r <url> | gg remote <url> | git init → add origin → first push to main | | gg pl | gg pull | Pull upstream (--rebase default; --merge to merge) | | gg rs | gg restore | Discard all uncommitted changes, staged included (asks first) | | gg rs <file> | gg restore <file> | Discard changes to one file |

Inspect & fix

| Short | Long | Description | |-------|------|-------------| | gg st | gg status | Compact status: branch, ahead/behind, changed files | | gg lg [n] | gg log [n] | Recent commits (default 10, max 100) | | gg undo | gg undo | Un-commit the last commit, keep changes staged (asks first) | | gg amend | gg amend [-m] | Stage all → amend last commit (keep or replace message) | | gg stash | gg stash | Stash WIP including untracked files (-m "label" optional) | | gg stash pop | same | Restore the latest stash | | gg stash list | same | List stashes | | gg dr | gg doctor | Check git, gh, API key, repo, upstream |

undo and amend warn when the last commit is already on the remote (rewriting history may need a force push). Pushes from gg c p / gg cnp / gg m set the upstream automatically on a branch's first push.

Setup & tooling

| Short | Long | Description | |-------|------|-------------| | gg setup | gg setup / gg onboard | Interactive OpenRouter onboard (key, model, language) | | gg config | gg config | Show config (key masked, model, language) | | gg config set … | same | Set model, key, or language | | gg config path | same | Print config file path | | gg config reset | same | Re-run full onboard | | gg mo [slug] | gg model [slug] | Show or switch AI model | | gg u | gg update | Check npm and install latest | | gg v | gg version | Version + install + config paths | | gg h | gg help | Command list (also bare gg) | | gg start | gg start | Open the optional web UI for this folder |

Flags

| Flag | Commands | Effect | |------|----------|--------| | -m "msg" / --message "msg" | Any command that commits; amend; stash | Use this message instead of AI / default (on stash: label) | | -y / --yes | restore / rs / undo / pr | Skip the confirm; on PR, use default base without prompting | | --merge / --rebase | pull / pl | Pull by merge instead of the default rebase | | -v / -V / --version | — | Same as version | | -h / --help | — | Same as help |

gg c -m "fix: handle null user"
gg cnp -m "feat: add search filters"
gg rs -y
gg rs src/app.ts -y

Configuration

First-time setup

gg setup

Prompts for:

1. OpenRouter API key (hidden input — never echoed)
2. Model (default: google/gemini-2.0-flash-001)
3. Language for commit messages (en or pt)

Get a free/paid key at openrouter.ai.

Show & edit

gg config                          # show (key is masked)
gg config set model google/gemini-2.0-flash-001
gg config set language pt
gg config set key sk-or-v1-…
gg model                           # show current model
gg mo anthropic/claude-3.5-sonnet  # switch model
gg config reset                    # full re-onboard

Where config lives

| OS | Path | |----|------| | Windows | %APPDATA%\gitgen\config.json | | macOS | ~/Library/Application Support/gitgen/config.json | | Linux | ~/.config/gitgen/config.json |

Permissions are owner-only where supported. The key stays on your machine and is only sent to OpenRouter when generating a message.

Environment overrides (optional)

| Variable | Purpose | |----------|---------| | OPENROUTER_API_KEY | API key (overrides file) | | OPENROUTER_MODEL | Model slug | | COMMIT_LANGUAGE | en or pt | | GITGEN_CONFIG_DIR | Custom config directory | | GCG_PORT | Web UI port for gg start (default 2001) |

Examples

# Everyday commit + push
gg cnp

# Commit only (stay local)
gg c

# Explicit message (no AI)
gg c p -m "chore: bump dependencies"

# Feature branch end-to-end (merge locally)
gg b feature/checkout
# …work…
gg cnp
gg m feature/checkout          # merge into main and push

# Feature branch → open a GitHub PR instead of merging locally
gg b feature/checkout
# …work…
gg cnp pr                      # commit + push + PR (asks which base branch)
# or, after work is already committed:
gg pr                          # asks base (default: main / origin HEAD)
gg pr develop                  # PR into develop
gg pr -y                       # default base, no base prompt

# Merge into a non-main branch
gg m feature/checkout develop

# Park work and jump back to main
gg s

# Switch branches
gg sw develop

# Brand-new repo → GitHub
gg r https://github.com/you/new-repo.git

# Undo uncommitted mess (confirm required unless -y)
gg rs
gg rs package-lock.json

# See where you are and what changed
gg st                          # branch, ahead/behind, changed files
gg lg 5                        # last 5 commits

# Fix the last commit
gg undo                        # un-commit, keep changes staged
gg amend                       # add forgotten files to the last commit
gg amend -m "fix: better msg"  # also rewrite its message

# Park work without committing
gg stash -m "half-done login"
gg sw main
# …later…
gg sw feature/login
gg stash pop

Live progress

Each step prints a compact status line (spinner, checkmark, timing). Pushes show a small transfer bar only while objects are counting/writing:

  ⠹ git push [████████░░░░░░]  63% Writing  2.3s
  ✓ git push  4.1s

How AI commits work

When you omit -m and a key is configured:

1. CLI runs git status / name-status / diff in your current folder
2. A compact summary is sent to OpenRouter
3. The model returns a short Conventional Commit subject
4. That message is used for git commit

| Situation | Result | |-----------|--------| | Key set, no -m | AI message from local diff | | -m "…" passed | Your message, no API call | | No key | Default message (feat: update, etc.) | | Clean working tree | Nothing to commit — exits cleanly |

First AI use without a key launches the setup wizard automatically.

How AI pull requests work

gg pr / gg cnp pr need the GitHub CLI on your PATH and a logged-in account:

gh auth login

Flow:

1. Commit dirty work (if any) with the same AI commit rules as cnp
2. git push (or push -u origin <branch> when there is no upstream)
3. Ask for the base branch (merge target) — default is origin/HEAD, else main / master
4. Two OpenRouter calls on the same commit log + diff: one for the title (one line), one for the markdown body (no JSON)
5. If this head branch already has an open PR, skip create — print that URL (push already updated it)
6. Otherwise: show title/body preview and create immediately via gh pr create, then print the URL

Without an API key, title/body fall back to the latest commit subject and the commit list.

| Command | Notes | |---------|--------| | gg cnp pr | Full path: stage → commit → push → PR | | gg pr | PR from current branch (commits first if dirty) | | gg pr develop | Base = develop (no base prompt) | | gg pr -y | Default base, no base prompt (creates immediately either way) |

Optional web UI

The package is CLI-first. There is also a local Next.js UI if you clone the full repo.

git clone https://github.com/MusicMaster4/gitgen.git
cd gitgen
npm install
npm run dev          # http://localhost:2001

From a full checkout (not the slim npm install), gg start can open the app with the current folder as ?path=. From a global npm install, gg start opens the browser only if the server is already running on port 2001.

| Script | Purpose | |--------|---------| | npm run dev | Dev server on port 2001 | | npm run build | Production web build | | npm run build:cli | Bundle CLI → dist/cli.js | | npm test | Unit tests | | npm run typecheck | TypeScript check | | npm run lint | ESLint |

Security

• API keys live in a user config file or env vars — never in the repo
• Key input in gg setup is hidden (not echoed)
• Config file mode is restricted to the owner when the OS allows it
• Diffs leave your machine only when you generate an AI commit (OpenRouter)

Treat keys like passwords. Do not commit .env.local or filled-in secrets.

License

Free for personal use, learning, and non-commercial projects.

Commercial use, resale, or paid hosting requires written permission.

See LICENSE for full terms.

Jubarte · 2026

gg cnp — commit messages that don't embarrass you.