Git Genie — Documentation

Full reference for installation, usage, command palette, and advanced workflows.

Git Genie — Usage Guide

Essence: gg automates staging, Conventional Commit creation (Gemini), branch flow, optional merge to main, and push. Now includes secure API key storage and AI-powered branch/PR naming.

Contents

  • Quick start
  • Install & verify
  • Configure Gemini API key
  • Command syntax & options
  • Command palette (interactive)
  • How it works (mapped to source)
  • Common workflows
  • Branch & merge behavior
  • AI commit generation details
  • AI branch & PR generation
  • Open Source Contributions (--osc)
  • Examples
  • Troubleshooting
  • Security & privacy
  • Contributing / roadmap
  • FAQ / Support

Quick start

Global install:

npm install -g @gunjanghate/git-genie

Configure your Gemini API key (one time):

gg config YOUR_GEMINI_API_KEY_HERE

Make a commit with AI assist:

gg "add user profile section" --type feat --scope ui --genie

Install & verify

which gg            # macOS / Linux
Get-Command gg      # PowerShell
gg --help           # Shows banner + onboarding instructions

Use ad‑hoc (no global install):

npx @gunjanghate/git-genie "fix typo" --genie

Configure Gemini API key

Priority order used by the CLI:

  1. GEMINI_API_KEY env var (process.env)
  2. OS keychain (macOS Keychain, Windows Credential Vault, Linux Secret Service)
  3. Encrypted fallback: ~/.gitgenie/config.json

Store key (overwrites existing):

gg config <API_KEY>

Remove stored key:

# For OS keychain
keytar delete git-genie api-key
# For encrypted fallback, delete the file
rm ~/.gitgenie/config.json

Rotating keys: Simply run gg config <NEW_KEY> to overwrite the existing one (useful when hitting quota limits).

Command syntax

gg <desc> [options]

<desc> = short human summary (used in fallback commit message if AI unavailable).

Subcommands

config <apikey> – Securely store Gemini API key.

Options

--type <type> Conventional Commit type (default: feat) --scope <scope> Optional scope, e.g. auth, api, ui --genie Enable AI commit generation (Gemini) --osc Open source contribution mode (see below) --no-branch Commit directly to main (skip prompt) --push-to-main After commit: merge current branch into main & push --remote <url> Add remote origin if repo just initialized --help Show help banner with onboarding guide

Types: feat | fix | docs | style | refactor | test | chore | ci | build | perf

Fallback commit format (no AI or failure): type(scope?): desc.

Command palette (interactive)

Run gg (or start a supported action without enough context) to open the interactive Command Palette.

Keyboard controls:

  • ↑ / ↓ — navigate
  • Enter — select highlighted action
  • Esc or Ctrl+C — cancel

Available actions (subject to evolve):

  • commit — Commit changes with optional AI support
  • config — Save your Gemini API key securely
  • cl — Clone repository
  • b — Create & switch to new branch
  • s — Switch to a branch
  • wt — Create Git worktree (auto-creates branch if missing)

Tip: See the “Command palette demo” section on the homepage for a visual walkthrough of the UI.

How it works (step mapping)

  1. Parse args via Commander (main action wrapper).
  2. Repo check: if not a git repo → git init.
  3. Remote: if --remote provided → attempt git remote add origin <url> (ignore if exists).
  4. Detect first commit (rev-parse HEAD).
  5. Branch logic:
  • If --no-branch OR no commits → force/create main (git checkout -B main).
  • Else interactive: current branch vs create new branch.
  • Open source mode (--osc): prompts for issue number, creates branch type/#<issue_number>-shorttitle.
    • If --genie is used, short title is generated by Gemini.
    • Otherwise, uses the message from gg "message".
  • AI-generated branch name: <type>-<kebab-case-desc> (max 40 chars) if not using --osc.
  1. Staging: if no staged diff → auto stage all (./*) → re-check; error if still empty.
  2. AI commit generation (if --genie & key): send staged diff to Gemini model gemini-2.0-flash with strict prompt; capture plain message.
  3. Commit: git commit "<message>".
  4. Push flow:
  • If --push-to-main and not on main → merge helper (see below).
  • Else prompt to push; if yes → push with retry (2 retries).
  • If pushed and branch != main → optional prompt to merge to main.
  1. Optional merge to main: checkout main → pull → merge feature → push → optional delete local + remote branch.

Open Source Contributions (--osc)

Use the --osc flag for open source workflows:

  • When you run:

    gg "fix bug in API" --type fix --osc

    You will be prompted for an issue number (e.g. 123).

  • The branch name will be: fix/#123-fix-bug-in-api

  • If you use --genie:

    gg "improve error handling" --type refactor --osc --genie

    The short title is generated by Gemini, e.g. refactor/#456-enhance-error-handling.

  • If you do not use --genie, the short title is based on your commit message.

This works seamlessly with your existing workflow and helps keep branches organized for open source contributions.

Common workflows

Feature with AI + push:

gg "add oauth flow" --type feat --scope auth --genie

Direct quick fix on main:

gg "fix typo in README" --no-branch --genie

Initialize new repo + remote:

gg "initial commit" --no-branch --remote https://github.com/you/repo.git --genie

Auto merge after finishing work:

gg "implement payment flow" --push-to-main

Open source contribution:

gg "update docs for API v2" --type docs --osc
# Prompts for issue number, creates branch: docs/#789-update-docs-for-api-v2

Branch & merge behavior

  • AI-generated branch names: conventional type prefix + kebab-case description (max 40 chars).
  • --osc branch names: type/#<issue_number>-shorttitle (short title from Gemini or message).
  • --push-to-main triggers: checkout main → pull (non-fatal if remote missing) → merge → push main → optional feature cleanup.
  • Branch cleanup: interactive confirm; deletes local + tries remote (ignored if absent).

AI commit generation

Model: gemini-2.0-flash. Prompt enforces: Conventional Commit, max ~50 char description, imperative, lowercase first letter, no trailing period. Only staged diff is sent (added/removed lines & headers). No untracked / unstaged content. Failure path: logs warning + fallback commit string.

AI branch & PR generation

Branch naming (generateBranchName)

  • Uses Gemini to create descriptive, kebab-case branch names.
  • Format: <type>-<descriptive-kebab-case> (under 40 characters).
  • For --osc: type/#<issue_number>-shorttitle.
  • Based on commit type and change description.

PR titles (generatePRTitle)

  • AI-generated pull request titles for cleaner GitHub integration.
  • Follows conventional commit style but optimized for PR context.
  • Generated from branch changes and commit history.

Examples

Plain conventional commit (no AI):

gg "add dark mode toggle" --type feat --scope ui

Force AI (if key missing → fallback + warning):

gg "refactor data layer" --type refactor --genie

Custom remote same run:

gg "initial commit" --no-branch --remote https://github.com/you/new.git

Open source branch with issue:

gg "fix login bug" --type fix --osc
# Prompts for issue number, creates branch: fix/#321-fix-login-bug

Open source branch with Gemini short title:

gg "improve error handling" --type refactor --osc --genie
# Prompts for issue number, creates branch: refactor/#456-enhance-error-handling

Troubleshooting

API Key Issues:

  • "GEMINI_API_KEY not found" → Run gg config <key> or export env var.
  • Corrupted config file → Delete ~/.gitgenie/config.json and re-run gg config <key>.
  • Invalid/empty encrypted key format → Re-configure with gg config <key>.

Git Issues:

  • "No changes detected to commit" → Ensure edits; check git status; verify .gitignore.
  • Push retries failing → validate remote URL & auth; run manual: git push origin <branch>.
  • Merge conflicts (during --push-to-main): resolve manually, then commit & push main.
  • Branch already exists (creating) → choose a different name or delete existing branch.

Staging Issues:

  • Files not staged → Check .gitignore rules; manually stage with git add <files>.
  • Large files causing issues → Use .gitignore or Git LFS for binary/large files.

Security & privacy

API Key Storage (Secure):

  • Primary: OS keychain via keytar (macOS Keychain, Windows Credential Vault, Linux Secret Service).
  • Fallback: AES-256-CBC encryption in ~/.gitgenie/config.json.
  • Encryption format: <random-iv>:<ciphertext> with unique per-user key.
  • Keys never leave your machine and are never hardcoded in source.

Data Privacy:

  • Only staged diff is sent to Gemini AI (added/removed lines & file headers).
  • No untracked files, personal data, or full repository content is transmitted.
  • Avoid staging secrets; keep .env files in .gitignore.

Contributing / roadmap

Planned: PR automation, partial diff selection, stats mode, model selection flag. Contribute: fork → branch → changes → gg "feat xyz" --genie → PR.

FAQ

Q: How do I rotate API keys?
A: Just run gg config <new_key> to overwrite the existing one.

Q: What if I hit quota on my API key?
A: Swap to another key using gg config <backup_key>.

Q: Is key storage secure?
A: Yes—uses OS keychain when available, fallback to AES-256-CBC encryption with per-user keys.

Q: Windows support?
A: Yes (PowerShell tested), uses Windows Credential Vault for secure storage.

Q: Can it open PRs?
A: Not yet (roadmap), but generates PR titles for manual creation.

Q: Model configurable?
A: Currently fixed to gemini-2.0-flash.

Q: How does --osc work?
A: Prompts for issue number, creates branch type/#<issue_number>-shorttitle (short title from Gemini if --genie is used, otherwise from your message).

Publish (maintainers)

npm version patch   # or minor / major
npm publish --access public

Support

End of docs