Skip to content
g Version CLI Git · stacks · worktrees

Playbooks for g

Story-style workflows—solo, team, and on-call. Jump into the full Use cases page anytime.

Playbook Stacked PR story Huge branch → pay/db-schema, pay/api, pay/webhooks. Playbook Hotfix worktree Prod fix without leaving your feature checkout. Playbook Triage a branch Log + compare from the shell. Playbook Unify diffs One diff mode for the team.

CLI Reference

Complete reference for all g commands, subcommands, and flags. Auto-generated from src/cli/ — do not edit this file directly.

Command-Line Help for g

This document contains the help content for the g command-line program.

Command Overview:

g

An enhanced Git CLI that layers powerful workflows on top of git.

All standard git commands are forwarded transparently — just swap ‘git’ for this tool and everything continues to work as expected.

Enhanced commands add colour, icons, and smarter output. New commands add stacked-PR workflows, parallel worktree workspaces, and an interactive conventional-commit builder.

Usage: g [OPTIONS] <COMMAND>

Examples:

g log enhanced git log with graph g status enhanced status with icons g add interactive file picker to stage g commit interactive conventional commit g diff enhanced diff g branch list branches with ahead/behind g compare main compare current branch to main g stack new my-feature start a stacked PR workflow g workspace create api create a parallel workspace

Pass —help to any subcommand for detailed usage and examples.

Subcommands:
  • workspace — Manage worktree-based workspaces (parallel branch checkouts)
  • stack — Manage stacked pull requests
  • commit — Interactive guided commit with message templates
  • add — Stage files interactively, or forward arguments to git add
  • stage — Interactive file-tree picker for staging and unstaging
  • compare — Compare two branches visually
  • log — Enhanced git log with beautiful formatting
  • status — Enhanced git status with icons and colors
  • diff — Enhanced git diff using your configured diff tool
  • branch — Enhanced branch listing, git branch passthrough, or branch squash
  • show — Enhanced git show
  • push — Enhanced git push with progress display
  • notes — Manage private review notes left from g diff’s c key
  • config — Open interactive config editor
  • stats — Display a rich usage-statistics report
  • developer — Developer / debugging utilities
  • workflow — Manage git workflows (branching strategies)
  • hooks — Manage personal git hooks
  • completions — Print a shell completion script and exit
Options:
  • -C <PATH> — Run as if git was started in
  • -c <KEY=VAL> — Override a configuration value (key=value)
  • --dry-run — Preview what commands would run without making any changes
  • --no-interactive — Disable all interactive TUI prompts; use defaults or require —flag values. Useful for scripting and CI environments

g workspace

Manage worktree-based workspaces (parallel branch checkouts)

Usage: g workspace <COMMAND>

Examples:

g workspace list list all workspaces g workspace create feature create workspace on a new branch g workspace create -b existing feature use an existing branch g workspace switch fuzzy-pick a workspace g workspace switch api switch to a named workspace g workspace status show current workspace info g workspace rename old new rename a workspace g workspace delete api remove a workspace

Subcommands:
  • init — Reorganise an existing repo into a container/worktree layout
  • list — List all workspaces (git worktrees)
  • create — Create a new workspace as a sibling worktree directory
  • switch — Open a subshell in a workspace directory
  • delete — Remove a workspace (git worktree remove)
  • status — Show current workspace info
  • rename — Rename a workspace (move directory and repair worktree)

g workspace init

Reorganise an existing repo into a container/worktree layout

Moves the repo root into a new sub-directory named after the default branch (e.g. main), then recreates the original path as a container directory. After init, new workspaces created with g workspace create are placed inside the container.

Usage: g workspace init

g workspace list

List all workspaces (git worktrees)

Usage: g workspace list [OPTIONS]

Options:
  • --json — Emit machine-readable JSON instead of the table view

g workspace create

Create a new workspace as a sibling worktree directory

Usage: g workspace create [OPTIONS] <NAME> [START_POINT]

Arguments:
  • <NAME> — Name for the new workspace
  • <START_POINT> — Starting commit or tag when creating a new branch (e.g. abc1234)
Options:
  • -b, --branch <BRANCH> — Branch to check out (defaults to creating a new branch with the workspace name)
  • -d, --description <DESCRIPTION> — Description of this workspace
  • --copy — Show an interactive picker to copy untracked/gitignored files into the new workspace

g workspace switch

Open a subshell in a workspace directory

Usage: g workspace switch [NAME]

Arguments:
  • <NAME> — Workspace name (fuzzy matched). Omit to open an interactive picker

g workspace delete

Remove a workspace (git worktree remove)

Usage: g workspace delete [OPTIONS] <NAME>

Arguments:
  • <NAME> — Workspace name
Options:
  • --force — Force removal even if the worktree is dirty

g workspace status

Show current workspace info

Usage: g workspace status [OPTIONS]

Options:
  • --json — Emit machine-readable JSON instead of the rendered view

g workspace rename

Rename a workspace (move directory and repair worktree)

Usage: g workspace rename <OLD> <NEW>

Arguments:
  • <OLD> — Current name
  • <NEW> — New name

g stack

Manage stacked pull requests

Usage: g stack <COMMAND>

Workflow overview:

  1. g stack new my-feature create a stack from current branch
  2. g stack add next-step add a dependent branch on top
  3. (work, commit on each branch)
  4. g stack sync rebase all branches in order
  5. g stack push push all branches
  6. g stack pr open GitHub PRs for every branch

Other useful commands:

g stack view show the stack as a tree g stack details show per-branch commit lists g stack squash squash current branch to one commit g stack fold merge current branch into its parent

Subcommands:
  • new — Initialize a new stack starting from the current branch
  • add — Create a new branch on top of the current stack
  • list — List all stacks
  • view — Show the current stack as a tree
  • details — Show the current stack with commits for each branch
  • switch — Switch to a different stack (checks out its top branch)
  • absorb — Merge the current branch into the one below it in the stack
  • squash — Squash the current branch to one commit on top of its base, then rebase branches above
  • fold — Merge the current branch into its parent (preserving history), drop the extra ref, restack above
  • sync — Sync all stack branches (rebase each on the one below)
  • push — Push all branches in the current stack
  • pr — Create or update GitHub PRs for all branches in the stack
  • remove — Remove a branch from the stack (doesn’t delete the branch)
  • delete — Delete a stack (and optionally its branches)
  • up — Move a stack up or down in the stack list (affects display order and PR ordering)
  • down —

g stack new

Initialize a new stack starting from the current branch

Usage: g stack new <NAME>

Arguments:
  • <NAME> — Name for this stack

g stack add

Create a new branch on top of the current stack

Usage: g stack add <BRANCH>

Arguments:
  • <BRANCH> — Branch name to create

g stack list

List all stacks

Usage: g stack list [OPTIONS]

Options:
  • --json — Emit machine-readable JSON instead of the tree view

g stack view

Show the current stack as a tree

Usage: g stack view

g stack details

Show the current stack with commits for each branch

Usage: g stack details [OPTIONS]

Options:
  • --json — Emit machine-readable JSON instead of the rendered view

g stack switch

Switch to a different stack (checks out its top branch)

Usage: g stack switch <NAME>

Arguments:
  • <NAME> — Stack name to switch to

g stack absorb

Merge the current branch into the one below it in the stack

Usage: g stack absorb

g stack squash

Squash the current branch to one commit on top of its base, then rebase branches above

Usage: g stack squash [OPTIONS]

Options:
  • -m, --message <MESSAGE> — Commit message for the squashed commit (default: oldest commit subject in the range)
  • --no-interactive — Abort if any conflict is found instead of pausing

g stack fold

Merge the current branch into its parent (preserving history), drop the extra ref, restack above

Usage: g stack fold [OPTIONS]

Options:
  • --keep — Keep the current branch name as the combined branch (remove the parent ref from the stack)
  • --no-interactive — Abort if merge/rebase hits conflicts instead of pausing for resolution

g stack sync

Sync all stack branches (rebase each on the one below)

Usage: g stack sync [OPTIONS]

Options:
  • --no-interactive — Abort if any conflict is found instead of pausing

g stack push

Push all branches in the current stack

Usage: g stack push [OPTIONS]

Options:
  • --force — Force push with lease

g stack pr

Create or update GitHub PRs for all branches in the stack

Usage: g stack pr [OPTIONS]

Options:
  • --open — Open PRs in browser after creating
  • --draft — Draft PRs

g stack remove

Remove a branch from the stack (doesn’t delete the branch)

Usage: g stack remove <BRANCH>

Arguments:
  • <BRANCH> — Branch name to remove from stack

g stack delete

Delete a stack (and optionally its branches)

Usage: g stack delete [OPTIONS] <NAME>

Arguments:
  • <NAME> — Stack name
Options:
  • --branches — Also delete all branches in the stack

g stack up

Move a stack up or down in the stack list (affects display order and PR ordering)

Usage: g stack up

g stack down

Usage: g stack down

g commit

Interactive guided commit with message templates

Usage: g commit [OPTIONS]

Options:
  • -m, --message <MESSAGE> — Commit message subject (skips interactive mode)
  • -b, --body <BODY> — Commit message body
  • --type <TYPE> — Commit type (feat, fix, docs, etc.) — skips prompt
  • --scope <SCOPE> — Commit scope — skips prompt
  • --no-verify — Don’t run pre-commit hooks
  • -a, --all — Stage all changes before committing
  • --amend — Amend the last commit
  • -s, --signoff — Add Signed-off-by trailer
  • -S, --gpg-sign — GPG-sign the commit

g add

Stage files interactively, or forward arguments to git add

With no arguments an interactive multi-select picker is shown so you can choose exactly which files to stage using ↑↓ / j k and Space. Any flags or paths you supply are forwarded to git add unchanged.

Usage: g add [ARGS]...

Arguments:
  • <ARGS> — Extra arguments forwarded to git

g stage

Interactive file-tree picker for staging and unstaging

Opens a full-screen tree view of every changed file (staged, unstaged and untracked). Navigate with j/k, toggle with Space, confirm with Enter. Press d on any tracked file to revert it to its last known state.

Already-staged files start pre-checked so running g stage a second time lets you adjust your selection without losing what you staged.

Usage: g stage

g compare

Compare two branches visually

Usage: g compare [OPTIONS] [BASE] [HEAD]

Arguments:
  • <BASE> — Base branch (defaults to main/master)
  • <HEAD> — Head branch (defaults to current)
Options:
  • --stat — Only show file-level stat, not full diff
  • --diff — Show full diff
  • --commits — Show only commits

g log

Enhanced git log with beautiful formatting

Usage: g log [ARGS]...

Arguments:
  • <ARGS> — Extra arguments forwarded to git

g status

Enhanced git status with icons and colors

Usage: g status [ARGS]...

Arguments:
  • <ARGS> — Extra arguments forwarded to git

g diff

Enhanced git diff using your configured diff tool

Usage: g diff [ARGS]...

Arguments:
  • <ARGS> — Extra arguments forwarded to git

g branch

Enhanced branch listing, git branch passthrough, or branch squash

Usage: g branch [REST]... [COMMAND]

Subcommands:
  • squash — Collapse all commits on the current branch into one (from merge-base with base)
Arguments:
  • <REST> — When no squash subcommand: forwarded to enhanced list or git branch

g branch squash

Collapse all commits on the current branch into one (from merge-base with base)

Usage: g branch squash [OPTIONS]

Options:
  • -m, --message <MESSAGE> — Commit message (default: oldest subject in the squashed range)
  • -b, --base <BASE> — Ref to merge against when finding the fork point (git merge-base HEAD <base>)

g show

Enhanced git show

Usage: g show [ARGS]...

Arguments:
  • <ARGS> — Extra arguments forwarded to git

g push

Enhanced git push with progress display

Usage: g push [ARGS]...

Arguments:
  • <ARGS> — Extra arguments forwarded to git

g notes

Manage private review notes left from g diff’s c key.

These notes live in the local SQLite DB and are never published to GitHub. Use g diff (and the c key inside the TUI) to create them; this command surfaces list/show/edit/delete/clear operations from outside the TUI.

Usage: g notes <COMMAND>

Subcommands:
  • list — List every saved note in this repo (newest first)
  • show — Show a single note by id — prints the body and its anchor
  • edit — Edit the body of an existing note in $EDITOR
  • delete — Delete a single note by id
  • clear — Delete all notes for a given file (or every note when no path is given). Requires --force to actually run — protects against fat-finger typos
  • publish — Publish a saved private note to the GitHub PR for the current branch

g notes list

List every saved note in this repo (newest first)

Usage: g notes list

g notes show

Show a single note by id — prints the body and its anchor

Usage: g notes show <ID>

Arguments:
  • <ID>

g notes edit

Edit the body of an existing note in $EDITOR

Usage: g notes edit <ID>

Arguments:
  • <ID>

g notes delete

Delete a single note by id

Usage: g notes delete <ID>

Arguments:
  • <ID>

g notes clear

Delete all notes for a given file (or every note when no path is given). Requires --force to actually run — protects against fat-finger typos

Usage: g notes clear [OPTIONS] [PATH]

Arguments:
  • <PATH> — Restrict to this repo-relative file path (optional)
Options:
  • --force — Skip the confirmation prompt

g notes publish

Publish a saved private note to the GitHub PR for the current branch.

The “public bucket” of the two-bucket model: this posts the note body as a line-anchored review comment on the open PR whose head matches the current branch. Requires GITHUB_TOKEN in the environment (or a token set in [github].token) and an open PR on the current branch.

Usage: g notes publish <ID>

Arguments:
  • <ID>

g config

Open interactive config editor

Usage: g config [OPTIONS] [KEY] [COMMAND]

Subcommands:
  • set — Set a config key, validated against the editable schema
Arguments:
  • <KEY> — Optional positional key — when present alone, fuzzy-search the summary for matching lines (legacy behaviour)
Options:
  • --edit — Open config file in $EDITOR
  • --path — Print the path to the config file
  • --themes — List available themes (built-in + custom) and exit
  • --list — Print every editable scalar setting with its current value and help text
  • --menu — Interactive menu: pick a setting, see its current value, choose a new one
  • --get <KEY> — Print the exact current value of <key> (scripting-friendly). Pair with a key positional: g config --get ui.log_limit
  • --new-theme — Launch the interactive theme creator. Writes a new TOML file under ~/.config/g/themes/<name>.toml that extends an existing theme and overrides only the colors you choose

g config set

Set a config key, validated against the editable schema.

Comments and formatting in config.toml are preserved.

Usage: g config set <KEY> <VALUE>

Arguments:
  • <KEY> — Dotted key path, e.g. ui.log_limit or ui.theme
  • <VALUE> — New value. Booleans accept true/false/yes/no/on/off. Enums must match one of the documented choices

g stats

Display a rich usage-statistics report

Aggregates data from the internal SQLite database (command runs, commits recorded via g commit) and the current repository’s git history to produce a terminal report that includes:

• Overview totals and streak information • GitHub-style commit heatmap for the last 52 weeks • Lines-added / lines-removed sparkline (current branch) • Top commands by frequency • Conventional-commit type distribution • Repository activity ranking • Activity-by-hour chart

Usage: g stats [OPTIONS]

Examples:

g stats full report, last 365 days g stats —days 90 last 90 days g stats —no-git skip sections that require git g stats —import import git history for commit analysis g stats —search “fix bug” fuzzy search commit messages g stats —duplicates show duplicate commit messages

Options:

  • --days <DAYS> — Number of days to look back for time-based stats

    Default value: 365

  • --no-git — Skip sections that require a git repository (heatmap, lines chart)

  • --import — Import git commit history into the statistics database

  • --import-limit <N> — Maximum number of commits to import (default: all)

  • --search <QUERY> — Search commit messages using fuzzy matching

  • --duplicates — Show duplicate commit messages

  • --message-stats — Show commit message length statistics and trends

g developer

Developer / debugging utilities

Usage: g developer <COMMAND>

Subcommands:
  • db — Open an interactive SQLite shell connected to the internal g.db database
  • repos — List all repositories tracked in the internal database

g developer db

Open an interactive SQLite shell connected to the internal g.db database

Launches sqlite3 with the path to ~/.config/g/g.db so you can run arbitrary SQL queries for debugging. Pass --path to print the database path without opening a shell.

Usage: g developer db [OPTIONS]

Options:
  • --path — Print the database path and exit (don’t open the shell)

g developer repos

List all repositories tracked in the internal database

Shows every repo root path that has been seen by the tool, along with the first and most recent time it was active.

Usage: g developer repos

g workflow

Manage git workflows (branching strategies)

Define and use custom workflows like Git Flow, GitHub Flow, trunk-based, or create your own branching model with custom branch types, merge strategies, and lifecycle hooks.

Usage: g workflow <COMMAND>

Workflow overview:

g workflow list list all available workflows g workflow info gitflow show workflow details with diagram g workflow use github-flow switch to a workflow

Branch lifecycle:

g workflow start feature login create a new branch g workflow sync update branch from source g workflow publish push and create PR g workflow finish merge to target branch(es)

Configuration:

g workflow create interactive workflow builder g workflow init —local set up .g/ folder in repo

Subcommands:
  • start — Start a new branch using workflow rules
  • finish — Finish the current branch (merge to target)
  • sync — Update branch from its source
  • publish — Push branch and create/update PR
  • status — Show workflow status of current branch
  • list — List all available workflows
  • info — Show detailed workflow information
  • use — Switch to a different workflow
  • create — Create a new workflow interactively
  • edit — Edit an existing workflow
  • init — Initialize workflow configuration
  • validate — Validate workflow configuration
  • clone — Clone a workflow with a new name
  • export — Export workflow configuration to TOML
  • import — Import workflow from a TOML file

g workflow start

Start a new branch using workflow rules

Creates a branch with the proper prefix, from the correct source branch, according to the workflow’s branch type configuration.

Usage: g workflow start [OPTIONS] <TYPE> <NAME>

Arguments:
  • <TYPE> — Branch type (e.g., feature, hotfix, release)
  • <NAME> — Branch name (without prefix)
Options:
  • --from <BRANCH> — Override the source branch
  • --no-verify — Skip validation checks

g workflow finish

Finish the current branch (merge to target)

Merges the current branch to its configured target(s) using the appropriate merge strategy, then optionally deletes the branch and creates tags as configured.

Usage: g workflow finish [OPTIONS] [BRANCH]

Arguments:
  • <BRANCH> — Branch to finish (defaults to current branch)
Options:
  • --no-delete — Don’t delete the branch after merge
  • --no-tag — Don’t create a tag even if configured
  • --no-verify — Skip pre-finish hooks
  • --strategy <STRATEGY> — Override the merge strategy

g workflow sync

Update branch from its source

Fetches latest changes and rebases or merges from the source branch to keep the current branch up-to-date.

Usage: g workflow sync [OPTIONS] [BRANCH]

Arguments:
  • <BRANCH> — Branch to sync (defaults to current branch)
Options:
  • --rebase — Force rebase even if merge is the default strategy
  • --merge — Force merge even if rebase is the default strategy

g workflow publish

Push branch and create/update PR

Pushes the branch to the remote and creates a pull request if one doesn’t exist, or updates the existing PR.

Usage: g workflow publish [OPTIONS] [BRANCH]

Arguments:
  • <BRANCH> — Branch to publish (defaults to current branch)
Options:
  • --draft — Create PR as draft
  • --no-verify — Skip on_publish hooks
  • --title <TITLE> — PR title (defaults to branch name)
  • --body <BODY> — PR body
  • --reviewers <USERS> — Add reviewers (comma-separated)
  • --labels <LABELS> — Add labels (comma-separated)

g workflow status

Show workflow status of current branch

Displays the current branch’s workflow context including type, source, target, merge strategy, age, and PR status.

Usage: g workflow status

g workflow list

List all available workflows

Shows all defined workflows (built-in presets and custom) with their branch types and a brief description.

Usage: g workflow list

g workflow info

Show detailed workflow information

Displays the full workflow configuration including ASCII diagram, use cases, pros/cons, and branch type details.

Usage: g workflow info <NAME>

Arguments:
  • <NAME> — Workflow name (preset or custom)

g workflow use

Switch to a different workflow

Sets the active workflow for the current repository (if —local) or globally.

Usage: g workflow use [OPTIONS] <NAME>

Arguments:
  • <NAME> — Workflow name to activate
Options:
  • --local — Set for this repository only (saves to .g/workflow.toml)

g workflow create

Create a new workflow interactively

Opens a full-screen wizard to define a custom workflow with branch types, merge strategies, hooks, and validation rules.

Usage: g workflow create [OPTIONS] [NAME]

Arguments:
  • <NAME> — Workflow name
Options:
  • --from <PRESET> — Start from a preset
  • --local — Save to repo-local config (.g/workflow.toml)
  • --no-interactive — Skip interactive wizard, save defaults immediately

g workflow edit

Edit an existing workflow

Opens the workflow configuration in your editor ($EDITOR) for direct modification.

Usage: g workflow edit [OPTIONS] [NAME]

Arguments:
  • <NAME> — Workflow name to edit
Options:
  • --raw — Edit raw TOML in $EDITOR

g workflow init

Initialize workflow configuration

Sets up the workflow system for first use. With —local, creates a .g/ folder in the repository for team-shared configuration.

Usage: g workflow init [OPTIONS]

Options:
  • --local — Create .g/ folder in repository for team-shared config
  • --preset <PRESET> — Use a preset as starting point
  • --no-interactive — Skip interactive setup

g workflow validate

Validate workflow configuration

Checks the workflow configuration for errors and warnings.

Usage: g workflow validate [OPTIONS] [FILE]

Arguments:
  • <FILE> — File to validate (defaults to active config)
Options:
  • --workflow <NAME> — Workflow name to validate (within config)

g workflow clone

Clone a workflow with a new name

Creates a copy of an existing workflow (preset or custom) that can be modified independently.

Usage: g workflow clone <SOURCE> <NAME>

Arguments:
  • <SOURCE> — Source workflow name
  • <NAME> — New workflow name

g workflow export

Export workflow configuration to TOML

Prints the workflow configuration to stdout or writes to a file.

Usage: g workflow export [OPTIONS] <NAME>

Arguments:
  • <NAME> — Workflow name to export
Options:
  • -o, --output <FILE> — Output file (defaults to stdout)

g workflow import

Import workflow from a TOML file

Loads a workflow configuration from a file and adds it to the available workflows.

Usage: g workflow import [OPTIONS] <FILE>

Arguments:
  • <FILE> — TOML file to import
Options:
  • --name <NAME> — Override workflow name
  • --local — Save to repo-local config (.g/workflow.toml)

g hooks

Manage personal git hooks

Configure and run personal hooks that coexist with team hooks (like Husky). Hooks are stored in .g/hooks.toml (gitignored) or ~/.config/g/hooks/.

Usage: g hooks <COMMAND>

Subcommands:
  • list — List all configured hooks for this repository
  • run — Run a specific hook manually
  • init — Create a hooks.toml template in .g/
  • status — Show where hooks config is loaded from

g hooks list

List all configured hooks for this repository

Usage: g hooks list

g hooks run

Run a specific hook manually

Usage: g hooks run [OPTIONS] <HOOK>

Arguments:
  • <HOOK> — Hook name to run (pre-commit, post-commit, pre-push, etc.)
Options:
  • --skip-empty — Skip the hook if no files match patterns

g hooks init

Create a hooks.toml template in .g/

Usage: g hooks init

g hooks status

Show where hooks config is loaded from

Usage: g hooks status

g completions

Print a shell completion script and exit

Pipe the output to the right location for your shell:

Bash: g completions bash >> ~/.bash_completion Zsh: g completions zsh > ~/.zsh/completions/_g Fish: g completions fish > ~/.config/fish/completions/g.fish

Usage: g completions <SHELL>

Arguments:

  • <SHELL> — Shell to generate completions for

    Possible values: bash, elvish, fish, powershell, zsh

This document was generated automatically by clap-markdown.