/ Documentation

Documentation

Getting StartedCore CommandsWorkflows & InternalsAI FeaturesNew Add OnsOpen Source & CollaborationReference & ExamplesSecurity & Community
Star the RepoContributenpm install

How it works (mapped to source)

  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.

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).