git-gud

https://mrmans0n.github.io/git-gud
Admin
git-gud is a stacked-diffs CLI tool for GitHub and GitLab that helps developers split large changes...
Tokens:33,560
Snippets:413
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Run git-gud setup in Quick or Full Mode

Source: https://mrmans0n.github.io/git-gud/commands/setup.html

Use 'gg setup' for essential settings or 'gg setup --all' for comprehensive configuration. This is ideal for new repositories or updating defaults.

```bash
gg setup        # Quick mode: essential settings only
gg setup --all  # Full mode: all settings organized by category
```

--------------------------------

### Git Gud Setup Confirmation

Source: https://mrmans0n.github.io/git-gud/commands/setup.html

After completing the quick setup, this message confirms the next step for configuring advanced options.

```bash
Tip: Run 'gg setup --all' to configure advanced options (sync, land, lint, etc.)
```

--------------------------------

### Git Gud Workflow Example

Source: https://mrmans0n.github.io/git-gud/getting-started.html

A step-by-step example demonstrating the typical workflow using git-gud commands, from creating a stack to landing changes.

```bash
__
# 1) Create a stack
gg co my-feature

# 2) Commit in small slices
git add . && git commit -m "Add data model"
git add . && git commit -m "Add API endpoint"
git add . && git commit -m "Add UI"

# 3) Inspect current stack
gg ls

# 4) Push branches and create PRs/MRs
gg sync --draft

# 5) Navigate to edit an earlier commit
gg mv 1
# ...make changes...
gg sc

# 6) Re-sync after changes
gg sync

# 7) Land approved changes
gg land --all

# 8) Clean merged stack
gg clean
```

--------------------------------

### Install git-gud

Source: https://mrmans0n.github.io/git-gud/print.html

Installation methods for git-gud using Homebrew or Cargo.

```shell
brew install mrmans0n/tap/gg-stack
```

```shell
cargo install gg-stack
```

```shell
cargo install --path .
```

--------------------------------

### Run the git-gud setup wizard

Source: https://mrmans0n.github.io/git-gud/getting-started.html

Run the interactive setup wizard for git-gud in any Git repository. This configures base branch, username, provider, and optional lint commands.

```bash
__
gg setup
```

--------------------------------

### gg lint execution examples

Source: https://mrmans0n.github.io/git-gud/commands/lint.html

Examples showing how to run linting on the entire stack or a specific subset of commits.

```bash
# Lint from bottom to current
gg lint

# Lint only a subset
gg lint --until 2
```

--------------------------------

### Install gg-stack using Homebrew

Source: https://mrmans0n.github.io/git-gud/getting-started.html

Install the gg-stack tool using the Homebrew package manager. Ensure Homebrew is installed on your system.

```bash
__
brew install mrmans0n/tap/gg-stack
```

--------------------------------

### Install Provider CLIs

Source: https://mrmans0n.github.io/git-gud/print.html

Install the necessary command-line interface tools for GitHub (`gh`) or GitLab (`glab`) if they are missing.

```bash
gh auth login
glab auth login
```

--------------------------------

### Example Global Git Gud Configuration

Source: https://mrmans0n.github.io/git-gud/configuration.html

This example demonstrates how to configure global defaults for git-gud, setting options like `sync_draft`, `land_auto_clean`, and `sync_behind_threshold` to apply across all repositories.

```json
{
  "defaults": {
    "sync_draft": true,
    "land_auto_clean": true,
    "sync_behind_threshold": 5
  }
}
```

--------------------------------

### CLI Command: gg setup

Source: https://mrmans0n.github.io/git-gud/print.html

Interactive configuration tool for initializing or updating the .git/gg/config.json file.

```APIDOC
## gg setup

### Description
Interactive setup for .git/gg/config.json. Use this when starting in a new repository or updating defaults.

### Usage
`gg setup` (Quick mode)
`gg setup --all` (Full mode)

### Configuration Fields (Full Mode)
#### General
- **provider** (select) - GitHub or GitLab
- **base** (string) - Default base branch
- **branch_username** (string) - Username for branch naming
- **unstaged_action** (select) - Action for gg amend with unstaged changes

#### Sync
- **sync_auto_rebase** (bool) - Auto-rebase when base is behind origin
- **sync_behind_threshold** (number) - Commits behind origin before warning
- **sync_draft** (bool) - Create new PRs/MRs as drafts
- **sync_update_descriptions** (bool) - Update PR/MR descriptions on re-sync

#### Land
- **land_auto_clean** (bool) - Auto-clean stack after landing
- **land_wait_timeout_minutes** (number) - Timeout for gg land --wait
```

--------------------------------

### Install Fish Completions for Git-Gud

Source: https://mrmans0n.github.io/git-gud/shell-completions.html

Installs fish shell completions for git-gud by creating the completions directory and saving the generated script to the appropriate file.

```fish
__
mkdir -p ~/.config/fish/completions
gg completions fish > ~/.config/fish/completions/gg.fish

```

--------------------------------

### Install Git Gud Plugin

Source: https://mrmans0n.github.io/git-gud/print.html

Instructions for adding and installing the Git Gud plugin for Claude.

```APIDOC
## Install Git Gud Plugin

### Description
Add the Git Gud plugin to your Claude marketplace and then install it.

### Commands
```bash
claude plugin marketplace add https://github.com/mrmans0n/git-gud
claude plugin install git-gud
```
```

--------------------------------

### Install Bash Completions for Git-Gud

Source: https://mrmans0n.github.io/git-gud/shell-completions.html

Installs bash completions for git-gud by creating the necessary directory and redirecting the output of the completions command to a file in the bash-completion directory.

```bash
__
mkdir -p ~/.local/share/bash-completion/completions
gg completions bash > ~/.local/share/bash-completion/completions/gg

```

--------------------------------

### CI failure output example

Source: https://mrmans0n.github.io/git-gud/commands/land.html

Example output displayed when the --wait flag is used and CI jobs fail.

```text
OK Landed 1 MR(s)

⚠ Landed 1 MR(s), but encountered an error:

Error: MR !7621 CI failed
  Failed jobs: lint (stage: test), build-android (stage: build)
```

--------------------------------

### Install gg-stack using Cargo

Source: https://mrmans0n.github.io/git-gud/getting-started.html

Install the gg-stack tool using Cargo, Rust's package manager. This is an alternative installation method.

```bash
__
cargo install gg-stack
```

--------------------------------

### Fish Shell Completion Setup

Source: https://mrmans0n.github.io/git-gud/print.html

Set up fish shell completions by directing the output of `gg completions fish` to the completions directory.

```fish
mkdir -p ~/.config/fish/completions
gg completions fish > ~/.config/fish/completions/gg.fish
```

--------------------------------

### Command examples for gg reorder/arrange

Source: https://mrmans0n.github.io/git-gud/commands/reorder.html

Demonstrates various ways to use `gg reorder` and `gg arrange`, including interactive TUI, explicit ordering, and forcing editor fallback.

```bash
# Interactive reorder/drop with TUI
gg reorder
gg arrange
```

```bash
# Explicit reorder by position (no dropping)
gg reorder --order "3,1,2"
```

```bash
# Use text editor instead of TUI
gg arrange --no-tui
```

--------------------------------

### Install gg-stack from local source using Cargo

Source: https://mrmans0n.github.io/git-gud/getting-started.html

Install the gg-stack tool from a local source directory using Cargo. This is useful for development or when using a specific local version.

```bash
__
cargo install --path .
```

--------------------------------

### Bash Shell Completion Setup

Source: https://mrmans0n.github.io/git-gud/print.html

Set up bash shell completions by directing the output of `gg completions bash` to the appropriate directory.

```bash
mkdir -p ~/.local/share/bash-completion/completions
gg completions bash > ~/.local/share/bash-completion/completions/gg
```

--------------------------------

### Install Zsh Completions for Git-Gud

Source: https://mrmans0n.github.io/git-gud/shell-completions.html

Installs zsh completions for git-gud by creating a directory for zsh completion scripts and placing the generated script there. It also shows how to configure your zshrc to load these completions.

```zsh
__
mkdir -p ~/.zfunc
gg completions zsh > ~/.zfunc/_gg

```

```zsh
__
fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit

```

--------------------------------

### Common gg ls Command Examples

Source: https://mrmans0n.github.io/git-gud/commands/ls.html

Demonstrates various ways to use 'gg ls' including listing current, all local, and remote stacks, refreshing status, and generating JSON output.

```bash
# Current stack status
gg ls

```

```bash
# All local stacks
gg ls --all

```

```bash
# Remote stacks (active first, then landed)
gg ls --remote

```

```bash
# Refresh status badges from provider
gg ls --refresh

```

```bash
# Structured JSON for automation
gg ls --json
gg ls --all --json
gg ls --remote --json

```

--------------------------------

### Zsh Shell Completion Setup

Source: https://mrmans0n.github.io/git-gud/print.html

Set up zsh shell completions by directing the output of `gg completions zsh` to `~/.zfunc` and updating your `~/.zshrc`.

```zsh
mkdir -p ~/.zfunc
gg completions zsh > ~/.zfunc/_gg
```

```zsh
fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit
```

--------------------------------

### Configuration

Source: https://mrmans0n.github.io/git-gud/print.html

Git Gud supports global configuration at `~/.config/gg/config.json`. Local configuration takes precedence over global configuration. Fields are written to `config.json` after setup.

```APIDOC
## Configuration

Git Gud supports global configuration at `~/.config/gg/config.json`. When running `gg setup`:
  * If no local config exists, global defaults are shown in prompts
  * Local config always takes precedence over global config

This allows you to set organization-wide defaults while allowing per-repo overrides. All fields are written to `config.json` after setup, making it easy to review and edit configuration manually.

> Note: `auto_add_gg_ids` is deprecated. Existing configs that include it are still read, but setup no longer prompts for it and runtime behavior always treats it as enabled.

### Configuration Fields

#### Lint Configuration

Field| Type| Default| Description
---|---|---|---
`lint`| list| empty| Lint commands to run per commit
`sync_auto_lint`| bool| false| Run lint automatically before sync

#### Worktree Configuration

Field| Type| Default| Description
---|---|---|---
`worktree_base_path`| string| empty| Template for stack worktrees ({repo}, {stack})

#### Gitlab Configuration

Field| Type| Default| Description
---|---|---|---
`gitlab.auto_merge_on_land`| bool| false| Use “merge when pipeline succeeds”
```

--------------------------------

### Add and Install Git Gud Plugin

Source: https://mrmans0n.github.io/git-gud/guides/agent-skills.html

Use these commands to add the git-gud plugin from GitHub and install it for use with Claude Code.

```bash
claude plugin marketplace add https://github.com/mrmans0n/git-gud
claude plugin install git-gud
```

--------------------------------

### gg land usage examples

Source: https://mrmans0n.github.io/git-gud/commands/land.html

Common command-line patterns for merging stacks, handling automation, and using administrative overrides.

```bash
# Land one approved entry
gg land

# Land complete stack, waiting for readiness
gg land --all --wait

# Land part of stack
gg land --until 2

# GitLab auto-merge queue
gg land --all --auto-merge

# JSON output for automation
gg land --all --json

# Bypass approval requirements (GitHub admin)
gg land --admin

# Land full stack with admin override
gg land --all --wait --admin
```

--------------------------------

### Split Commits with File Arguments

Source: https://mrmans0n.github.io/git-gud/commands/split.html

Examples of using the split command with file paths, commit identifiers, and non-interactive flags.

```bash
# Move auth files to a new commit before the current one
gg split -m "Add authentication" src/auth.rs src/auth_test.rs

# Split a specific commit with explicit files
gg split -c 3 src/config.rs

# Non-interactive with both messages
gg split -c 2 -m "Extract helpers" --no-edit helpers.rs utils.rs

# Split by GG-ID
gg split -c c-abc1234 src/config.rs
```

--------------------------------

### gg clean command examples

Source: https://mrmans0n.github.io/git-gud/commands/clean.html

Common usage patterns for the clean command, including flags for all stacks and JSON output.

```bash
gg clean
gg clean --all
gg clean --json
```

--------------------------------

### gg co usage examples

Source: https://mrmans0n.github.io/git-gud/commands/co.html

Common usage patterns for creating and switching stacks, including base branch specification and worktree usage.

```bash
# Create/switch stack
gg co user-auth

# Create stack based on a specific branch
gg co user-auth --base develop

# Create stack in worktree
gg co user-auth --worktree
```

--------------------------------

### gg run usage examples

Source: https://mrmans0n.github.io/git-gud/commands/run.html

Common patterns for using gg run, including validation, formatting, and parallel execution.

```bash
# Read-only validation across the whole stack
gg run -- cargo test

# Apply a formatter and fold changes into each commit
gg run --amend -- cargo fmt

# Run across up to commit 2 only
gg run --until 2 -- cargo check

# Parallel read-only run with 4 workers
gg run -j 4 -- cargo test

# Continue past failing commits (useful for auditing)
gg run --keep-going -- cargo clippy

# Pass a command with quoted arguments — argv boundaries are preserved
gg run -- sh -c 'echo "$GG_CURRENT_COMMIT" && cargo test --test integration'
```

--------------------------------

### Sequential Prompt Hunk Diff

Source: https://mrmans0n.github.io/git-gud/commands/split.html

Example of the diff output and prompt displayed during sequential mode.

```diff
--- a/src/auth.rs
+++ b/src/auth.rs
@@ -10,6 +10,12 @@ fn authenticate(user: &str) -> bool {
+    // Validate token
+    if token.is_empty() {
+        return false;
+    }

Include this hunk? [y]es/[n]o/[a]ll file/[d]one file/[s]plit/[q]uit/?help:
```

--------------------------------

### Example Git Gud Default Configuration

Source: https://mrmans0n.github.io/git-gud/configuration.html

This JSON structure defines the default settings for git-gud, covering provider, base branch, branch naming conventions, linting commands, and various behaviors for actions like unstaged changes, landing, and syncing.

```json
{
  "defaults": {
    "provider": "gitlab",
    "base": "main",
    "branch_username": "your-username",
    "lint": [
      "cargo fmt --check",
      "cargo clippy -- -D warnings"
    ],
    "auto_add_gg_ids": true,
    "unstaged_action": "ask",
    "land_wait_timeout_minutes": 30,
    "land_admin": false,
    "land_auto_clean": false,
    "sync_auto_lint": false,
    "sync_auto_rebase": false,
    "sync_behind_threshold": 1,
    "sync_draft": false,
    "sync_update_descriptions": true,
    "worktree_base_path": "/tmp/gg-worktrees",
    "gitlab": {
      "auto_merge_on_land": false
    }
  }
}
```

--------------------------------

### Git Gud Project Structure

Source: https://mrmans0n.github.io/git-gud/guides/agent-skills.html

This outlines the typical directory structure for the git-gud plugin, including manifest, skill definitions, and examples.

```directory
.claude-plugin/
  plugin.json           # Plugin manifest
skills/
  gg/
    SKILL.md            # Unified GitHub + GitLab skill
    reference.md        # Command reference + JSON schemas
    examples/
      basic-flow.md     # Provider-agnostic feature workflow
      multi-commit.md   # Absorb, reorder, lint
      merge-train.md    # GitLab merge train workflow
```

--------------------------------

### JSON output format

Source: https://mrmans0n.github.io/git-gud/commands/land.html

Example of the machine-readable JSON structure returned when using the --json flag.

```json
{
  "version": 1,
  "land": {
    "stack": "my-stack",
    "base": "main",
    "landed": [
      {
        "position": 1,
        "sha": "abc1234",
        "title": "feat: add parser",
        "gg_id": "c-abc1234",
        "pr_number": 42,
        "action": "merged",
        "error": null
      }
    ],
    "remaining": 0,
    "cleaned": false,
    "warnings": [],
    "error": null
  }
}
```

--------------------------------

### Commit Metadata Trailers

Source: https://mrmans0n.github.io/git-gud/print.html

Example of stable trailers added to stack commits for tracking.

```text
GG-ID: c-abc1234
GG-Parent: c-1234567
```

--------------------------------

### Split Commit Example

Source: https://mrmans0n.github.io/git-gud/print.html

This illustrates how a commit split creates a new commit with selected hunks and leaves the remainder in the original position, preserving the GG-ID.

```text
BEFORE                    AFTER
  4: "Fix tests"            5: "Fix tests"       (rebased)
  3: "Add auth+logging"     4: "Add logging"      ← remainder (keeps GG-ID)
  2: "Setup DB"             3: "Add auth"         ← NEW commit (selected changes)
  1: "Init project"         2: "Setup DB"
                             1: "Init project"
```

--------------------------------

### Skill Reference

Source: https://mrmans0n.github.io/git-gud/print.html

Location of detailed operational information, prompts, and examples for the unified skill.

```APIDOC
## Skill Reference

### Description
For full operational details, prompts, and examples, refer to the unified skill documentation.

### Location
*   Unified skill: `skills/gg/SKILL.md`
```

--------------------------------

### Custom PR Template Example

Source: https://mrmans0n.github.io/git-gud/configuration.html

Use this Markdown template to define your pull request description. Supported placeholders like {{description}}, {{stack_name}}, and {{commit_sha}} will be automatically filled.

```markdown
__
## Summary

{{description}}

---

**Stack:** `{{stack_name}}`
**Commit:** `{{commit_sha}}`

```

--------------------------------

### GET gg ls

Source: https://mrmans0n.github.io/git-gud/commands/ls.html

Lists current, local, or remote stacks with optional status refreshing and JSON output.

```APIDOC
## GET gg ls

### Description
List the current stack, all local stacks, or remote-only stacks. When the stack base is behind origin/<base>, output includes a ↓N indicator.

### Method
GET

### Endpoint
gg ls

### Parameters
#### Options
- **-a, --all** (flag) - Optional - Show all local stacks
- **-r, --refresh** (flag) - Optional - Refresh PR/MR status from remote
- **--remote** (flag) - Optional - List remote stacks not checked out locally
- **--json** (flag) - Optional - Print structured JSON output

### Request Example
gg ls --all --json

### Response
#### Success Response (200)
- **pr_state** (string) - The state of the pull/merge request
- **ci_status** (string) - The status of the continuous integration pipeline
```

--------------------------------

### Example JSON output from gg sync --json

Source: https://mrmans0n.github.io/git-gud/commands/sync.html

This JSON structure represents the output of `gg sync --json`, providing detailed information about the sync operation, including stack details, metadata, and individual entries.

```json
{
  "version": 1,
  "sync": {
    "stack": "my-stack",
    "base": "main",
    "rebased_before_sync": false,
    "metadata": {
      "gg_ids_added": 0,
      "gg_parents_updated": 1,
      "gg_parents_removed": 0
    },
    "entries": [
      {
        "position": 1,
        "sha": "abc1234",
        "title": "Add feature",
        "gg_id": "c-abc1234",
        "branch": "user/my-stack--c-abc1234",
        "action": "created",
        "pr_number": 42,
        "pr_url": "https://github.com/org/repo/pull/42",
        "draft": false,
        "pushed": true,
        "error": null
      }
    ]
  }
}
```

--------------------------------

### gg ls Options Explained

Source: https://mrmans0n.github.io/git-gud/commands/ls.html

Explore options like '--all' for local stacks, '--remote' for remote stacks, '--refresh' to update PR/MR status, and '--json' for scriptable output.

```bash
  * -a, --all: Show all local stacks
  * -r, --refresh: Refresh PR/MR status from remote
  * --remote: List remote stacks not checked out locally. Stacks whose PRs/MRs are all merged are shown in a separate “Landed” section at the bottom with a `✓` marker
  * --json: Print structured JSON output (for scripts and automation). Automatically performs a best-effort refresh of PR/MR state from the provider API, so `pr_state` and `ci_status` fields are populated without needing `--refresh`.

```

--------------------------------

### Configure git-gud

Source: https://mrmans0n.github.io/git-gud/print.html

Initialize git-gud configuration in a repository.

```shell
gg setup
```

--------------------------------

### gg absorb command examples

Source: https://mrmans0n.github.io/git-gud/commands/absorb.html

Common usage patterns for the absorb command including dry runs and rebasing.

```bash
# Preview before applying
gg absorb --dry-run

# Absorb and finish with rebase
gg absorb --and-rebase

# Heavy refactor across many files
gg absorb --whole-file --no-limit
```

--------------------------------

### Basic git-gud Workflow

Source: https://mrmans0n.github.io/git-gud/print.html

Standard commands for creating, syncing, and landing a stack of commits.

```shell
# 1) Create a stack
gg co my-feature

# 2) Commit in small slices
git add . && git commit -m "Add data model"
git add . && git commit -m "Add API endpoint"
git add . && git commit -m "Add UI"

# 3) Inspect current stack
gg ls

# 4) Push branches and create PRs/MRs
gg sync --draft

# 5) Navigate to edit an earlier commit
gg mv 1
# ...make changes...
gg sc

# 6) Re-sync after changes
gg sync

# 7) Land approved changes
gg land --all

# 8) Clean merged stack
gg clean
```

--------------------------------

### Authenticate with Provider CLI

Source: https://mrmans0n.github.io/git-gud/print.html

Authenticate with GitHub or GitLab CLI before using git-gud.

```shell
# GitHub
gh auth login

# GitLab
glab auth login
```

--------------------------------

### Project-level Configuration

Source: https://mrmans0n.github.io/git-gud/print.html

Configure the Git Gud plugin to be enabled by default for a repository using a `.claude/settings.json` file.

```APIDOC
## Project-level Configuration

### Description
Use this configuration file when you want the plugin enabled by default for a repository.

### File: `.claude/settings.json`
```json
{
  "plugins": [
    {
      "name": "git-gud",
      "path": "/path/to/git-gud"
    }
  ]
}
```
```

--------------------------------

### Drop Specific Commits

Source: https://mrmans0n.github.io/git-gud/print.html

Examples of dropping commits by their position in the stack or by GG-ID. The `--force` option skips the confirmation prompt.

```bash
# Drop the second commit in the stack
gg drop 2

# Drop multiple commits at once
gg drop 1 3

# Drop by GG-ID, skip confirmation
gg drop c-abc1234 --force

# Drop with JSON output
gg drop 2 --force --json

# Use the 'abandon' alias (inspired by jj)
gg abandon 2
```

--------------------------------

### Checkout Teammate's Stack and Sync Changes

Source: https://mrmans0n.github.io/git-gud/print.html

This sequence checks out a teammate's feature branch, lists the stack to confirm, makes local changes, and then syncs them using `gg sync`. Prefer `gg sync` over manual `git push` to maintain healthy mappings.

```bash
__
gg co teammate-feature
gg ls
# make changes
gg sync

```

--------------------------------

### Create and Switch Branch

Source: https://mrmans0n.github.io/git-gud/guides/your-first-stack.html

Use this command to create a new stack branch or switch to an existing one. It's the first step in organizing your work.

```bash
__
gg co user-auth
```

--------------------------------

### Configure Claude Desktop MCP Server

Source: https://mrmans0n.github.io/git-gud/mcp-server.html

Add this JSON configuration to your Claude Desktop MCP settings to enable interaction with git-gud. Ensure 'command' points to your 'gg-mcp' binary and 'GG_REPO_PATH' is set to your repository.

```json
{
  "mcpServers": {
    "git-gud": {
      "command": "gg-mcp",
      "env": {
        "GG_REPO_PATH": "/path/to/your/repo"
      }
    }
  }
}
```

--------------------------------

### Create or Switch Stack

Source: https://mrmans0n.github.io/git-gud/print.html

Use `gg co` to create a new Git stack, switch to an existing local stack, or check out a remote stack by name. Options include specifying a base branch or creating the stack in a worktree.

```bash
gg co [OPTIONS] [STACK_NAME]
```

```bash
# Create/switch stack
gg co user-auth
```

```bash
# Create stack based on a specific branch
gg co user-auth --base develop
```

```bash
# Create stack in worktree
gg co user-auth --worktree
```

--------------------------------

### Launch Claude with Git Gud Plugin

Source: https://mrmans0n.github.io/git-gud/print.html

How to launch Claude Code with the Git Gud plugin directory specified.

```APIDOC
## Launch Claude with Git Gud Plugin

### Description
Use this command when launching Claude Code directly to specify the plugin directory.

### Command
```bash
claude --plugin-dir /path/to/git-gud
```
```

--------------------------------

### Land All Entries

Source: https://mrmans0n.github.io/git-gud/guides/your-first-stack.html

Merge all entries in your stack. Use the `--wait` flag to pause execution until CI checks pass and approvals are received.

```bash
__
gg land --all
```

```bash
__
gg land --all --wait
```

--------------------------------

### gg co - Create or Switch Stack

Source: https://mrmans0n.github.io/git-gud/print.html

Command to create a new stack, switch to an existing local stack, or check out a remote stack by name.

```APIDOC
## `gg co` - Create or Switch Stack

### Description
Create a new stack, switch to an existing local stack, or check out a remote stack by name.

### Usage
```bash
gg co [OPTIONS] [STACK_NAME]
```

### Options
*   `-b, --base <BASE>`: Base branch to use (default auto-detected: main/master/trunk)
*   `-w, --worktree`: Create or reuse a managed worktree for this stack

### Examples
```bash
# Create/switch stack
gg co user-auth

# Create stack based on a specific branch
gg co user-auth --base develop

# Create stack in worktree
gg co user-auth --worktree
```
```

--------------------------------

### Git Commit with Stable Trailers

Source: https://mrmans0n.github.io/git-gud/core-concepts.html

Example of stable trailers used in git-gud commits. These trailers, like GG-ID and GG-Parent, help maintain metadata stability across rebases and enable auto-healing after history edits.

```git
__
GG-ID: c-abc1234
GG-Parent: c-1234567

```

--------------------------------

### gg sync command options

Source: https://mrmans0n.github.io/git-gud/commands/sync.html

These are the available options for `gg sync`. Use `--draft` to create new PRs/MRs as drafts, `--force` to push even if the remote is ahead, and `--update-descriptions` to refresh PR/MR titles/bodies from commit messages.

```bash
  * -d, --draft: Create new PRs/MRs as draft (does not affect existing PRs/MRs)
  * -f, --force: Force push even if remote is ahead
  * --update-descriptions: Update PR/MR title/body from commit messages
  * -l, --lint: Run lint before sync (aborts sync on lint failure and restores repository state to the pre-sync snapshot)
  * --no-lint: Disable lint before sync (overrides config default)
  * --no-rebase-check: Skip checking whether your stack base is behind `origin/<base>`
  * -u, --until <UNTIL>: Sync up to target commit (position, GG-ID, or SHA)
  * --json: Output structured JSON for automation (suppresses human/progress output)
```

--------------------------------

### gg sync command usage

Source: https://mrmans0n.github.io/git-gud/commands/sync.html

This shows the basic usage and available options for the `gg sync` command. Use it to push branches and manage PRs/MRs.

```bash
gg sync [OPTIONS]
```

--------------------------------

### PR/MR managed description markers

Source: https://mrmans0n.github.io/git-gud/commands/sync.html

When `gg sync` creates a new PR/MR, it wraps the generated description in HTML comment markers (`<!-- gg:managed:start -->` and `<!-- gg:managed:end -->`). Content outside these markers is preserved across syncs.

```html
<!-- gg:managed:start -->
(generated content from commit message / template)
<!-- gg:managed:end -->
```

--------------------------------

### Directory Structure

Source: https://mrmans0n.github.io/git-gud/print.html

Overview of the Git Gud plugin's directory structure.

```APIDOC
## Directory Structure

### Description
This is the typical directory structure for the Git Gud plugin.

```
.claude-plugin/
  plugin.json           # Plugin manifest
skills/
  gg/
    SKILL.md            # Unified GitHub + GitLab skill
    reference.md        # Command reference + JSON schemas
    examples/
      basic-flow.md     # Provider-agnostic feature workflow
      multi-commit.md   # Absorb, reorder, lint
      merge-train.md    # GitLab merge train workflow
```
```

--------------------------------

### gg sync - Sync Stack

Source: https://mrmans0n.github.io/git-gud/print.html

Command to push entry branches and create/update PRs/MRs for the current stack.

```APIDOC
## `gg sync` - Sync Stack

### Description
Push entry branches and create/update PRs/MRs for the current stack.

### Usage
```bash
gg sync [OPTIONS]
```
```

--------------------------------

### Open Interactive Hunk Picker

Source: https://mrmans0n.github.io/git-gud/print.html

Run `gg split` without arguments to open the interactive hunk picker for the current commit.

```bash
gg split
```

--------------------------------

### Checkout a stack

Source: https://mrmans0n.github.io/git-gud/guides/remote-stacks.html

Switches to the specified stack. If the stack is missing locally, it is reconstructed from remote mappings.

```bash
gg co user-auth
```

--------------------------------

### Run Linting

Source: https://mrmans0n.github.io/git-gud/guides/linting.html

Execute configured lint commands on commits. Use `gg lint` to run linters on your codebase.

```bash
gg lint
```

--------------------------------

### Syncing with draft PRs

Source: https://mrmans0n.github.io/git-gud/commands/sync.html

Use the `--draft` option to create new pull requests or merge requests as drafts. This is useful for initial submissions before they are ready for review.

```bash
gg sync --draft
```

--------------------------------

### Checkout Stack Branch

Source: https://mrmans0n.github.io/git-gud/faq.html

Use this command to switch to a branch that matches the stack naming scheme.

```bash
gg co <stack-name>
```

--------------------------------

### Navigation Commands

Source: https://mrmans0n.github.io/git-gud/commands/navigation.html

These commands allow you to move HEAD within your stack without manual rebase operations.

```APIDOC
## Navigation (`mv`, `first`, `last`, `prev`, `next`)

### Description
These commands move HEAD within your stack without manual rebase gymnastics.

### Method
Not applicable (CLI commands)

### Endpoint
Not applicable (CLI commands)

### `gg mv <TARGET>`

Move to a specific entry by:
  * Position (1-indexed)
  * GG-ID (`c-...`)
  * Commit SHA

#### Request Example
```
gg mv 1
gg mv c-abc1234
gg mv a1b2c3d
```

### Relative Navigation

#### Request Example
```
gg first   # first entry
gg last    # stack head
gg prev    # previous entry
gg next    # next entry
```
```

--------------------------------

### Configure Git Gud Plugin for a Repository

Source: https://mrmans0n.github.io/git-gud/guides/agent-skills.html

Add this JSON configuration to `.claude/settings.json` to enable the git-gud plugin by default for a specific repository.

```json
{
  "plugins": [
    {
      "name": "git-gud",
      "path": "/path/to/git-gud"
    }
  ]
}
```

--------------------------------

### Land All Stack Entries with CI/Approval Wait

Source: https://mrmans0n.github.io/git-gud/print.html

Use `gg land --all --wait` to merge all entries in the stack sequentially. The `--wait` flag ensures that git-gud waits for Continuous Integration (CI) checks to pass and for approvals before proceeding.

```bash
__
gg land --all --wait

```

--------------------------------

### Sync Stack with Rebasing Check

Source: https://mrmans0n.github.io/git-gud/print.html

This command syncs the stack. If the stack base is behind the origin, `gg sync` will warn and suggest running `gg rebase` first. Use `--no-rebase-check` to bypass this warning.

```bash
__
gg sync

```

--------------------------------

### gg co

Source: https://mrmans0n.github.io/git-gud/commands/co.html

Command to create a new stack, switch to an existing local stack, or check out a remote stack by name.

```APIDOC
## gg co

### Description
Create a new stack, switch to an existing local stack, or check out a remote stack by name.

### Endpoint
gg co [OPTIONS] [STACK_NAME]

### Parameters
#### Options
- **-b, --base** (string) - Optional - Base branch to use (default auto-detected: main/master/trunk)
- **-w, --worktree** (flag) - Optional - Create or reuse a managed worktree for this stack

### Request Example
# Create/switch stack
gg co user-auth

# Create stack based on a specific branch
gg co user-auth --base develop

# Create stack in worktree
gg co user-auth --worktree
```

--------------------------------

### Reconstruct and sync a stack

Source: https://mrmans0n.github.io/git-gud/guides/remote-stacks.html

Reconstructs a teammate's stack, lists it, and synchronizes local changes.

```bash
gg co teammate-feature
gg ls
# make changes
gg sync
```

--------------------------------

### MCP Server Integration

Source: https://mrmans0n.github.io/git-gud/print.html

Git Gud includes an MCP (Model Context Protocol) server that allows AI assistants to interact with stacked-diffs workflows programmatically.

```APIDOC
# MCP Server

Git Gud includes an MCP (Model Context Protocol) server that allows AI assistants like Claude Desktop, Cursor, and other MCP-compatible tools to interact with your stacked-diffs workflows programmatically.

## Availability

The `gg-mcp` binary is distributed alongside `gg`. If you installed via Homebrew or cargo-dist, it should already be available.

## Claude Desktop Configuration

### Configuration File

Add this to your Claude Desktop MCP configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```
__
{
  "mcpServers": {
    "git-gud": {
      "command": "gg-mcp",
      "env": {
        "GG_REPO_PATH": "/path/to/your/repo"
      }
    }
  }
}
```

### Configuration Details

Configure `gg-mcp` as a stdio-based MCP server. Set `GG_REPO_PATH` to point to your repository.

## Environment Variables

Variable| Description| Default
---|---|---
`GG_REPO_PATH`| Path to the git repository| Current working directory
```

--------------------------------

### Reconcile stack metadata

Source: https://mrmans0n.github.io/git-gud/guides/reconciling.html

Use these commands to preview or execute the reconciliation process when local and remote states diverge.

```bash
gg reconcile --dry-run
```

```bash
gg reconcile
```

--------------------------------

### Configure Linting Defaults

Source: https://mrmans0n.github.io/git-gud/guides/linting.html

Define default lint commands in `.git/gg/config.json`. These commands are executed by `gg lint`.

```json
{
  "defaults": {
    "lint": [
      "cargo fmt --check",
      "cargo clippy -- -D warnings"
    ]
  }
}
```

--------------------------------

### git-gud CLI Command Reference

Source: https://mrmans0n.github.io/git-gud/commands/index.html

Overview of the available commands for the git-gud CLI tool, organized by functional category.

```APIDOC
## git-gud CLI Reference

### Stack Lifecycle
- **co**: Checkout a stack or branch.
- **ls**: List current stack status.
- **sync**: Synchronize the stack with remote changes.
- **land**: Merge or land the stack.
- **clean**: Remove temporary or unused stack artifacts.

### Editing
- **mv**: Move commits or stack elements.
- **first**: Navigate to the first commit in the stack.
- **last**: Navigate to the last commit in the stack.
- **prev**: Navigate to the previous commit.
- **next**: Navigate to the next commit.
- **sc**: Shortcut for stack commit operations.
- **absorb**: Absorb changes into existing commits.
- **reorder**: Change the order of commits in the stack.
- **rebase**: Perform a rebase operation on the stack.

### Utilities
- **lint**: Run linting checks on the stack.
- **setup**: Initialize or configure the environment.
- **reconcile**: Reconcile local and remote states.
- **continue**: Continue a paused operation.
- **abort**: Abort the current operation.
- **completions**: Generate shell completion scripts.
```

--------------------------------

### Sync with Linting

Source: https://mrmans0n.github.io/git-gud/guides/linting.html

Perform a repository synchronization that includes running lint checks. If linting fails, the sync is aborted.

```bash
gg sync --lint
```

--------------------------------

### gg clean command syntax

Source: https://mrmans0n.github.io/git-gud/commands/clean.html

Basic usage syntax for the clean command.

```bash
gg clean [OPTIONS]
```

--------------------------------

### stack_navigate

Source: https://mrmans0n.github.io/git-gud/mcp-server.html

Navigate within the stack.

```APIDOC
## stack_navigate

### Description
Navigate within the stack.

### Parameters
#### Query Parameters
- **direction** (string) - Required - "first", "last", "prev", or "next".
```

--------------------------------

### Add and Commit Changes

Source: https://mrmans0n.github.io/git-gud/print.html

This sequence of commands adds all changes and commits them with descriptive messages. It's recommended to keep each commit small and self-contained for better stack management.

```bash
__
git add . && git commit -m "Add user model"
git add . && git commit -m "Add auth endpoints"
git add . && git commit -m "Add login UI"

```

--------------------------------

### Authenticate GitHub CLI

Source: https://mrmans0n.github.io/git-gud/faq.html

Use this command to log in to your GitHub account via the GitHub CLI.

```bash
gh auth login
```

--------------------------------

### Sync Stack with Lint Checks Enabled

Source: https://mrmans0n.github.io/git-gud/print.html

The `gg sync --lint` command performs a stack sync while also running configured lint checks. If linting fails, the sync is aborted, and the repository state is restored.

```bash
__
gg sync --lint

```

--------------------------------

### gg run command syntax

Source: https://mrmans0n.github.io/git-gud/commands/run.html

The basic syntax for executing commands across commits. Use -- to separate gg run options from the command to be executed.

```bash
gg run [OPTIONS] -- <COMMAND>...
```

--------------------------------

### Checkout Stack into Worktree (Short Flag)

Source: https://mrmans0n.github.io/git-gud/print.html

This is a shorthand for checking out a stack into a worktree using the `-w` flag. It provides the same functionality as `--worktree` but with a more concise command.

```bash
__
gg co user-auth -w

```

--------------------------------

### gg co command syntax

Source: https://mrmans0n.github.io/git-gud/commands/co.html

The basic command structure for gg co.

```bash
gg co [OPTIONS] [STACK_NAME]
```

--------------------------------

### gg lint command usage

Source: https://mrmans0n.github.io/git-gud/commands/lint.html

Basic command structure for running linting on stack commits.

```bash
gg lint [OPTIONS]
```

--------------------------------

### Authenticate GitLab CLI

Source: https://mrmans0n.github.io/git-gud/faq.html

Use this command to log in to your GitLab account via the GitLab CLI.

```bash
glab auth login
```

--------------------------------

### Authenticate with GitHub CLI and GitLab CLI

Source: https://mrmans0n.github.io/git-gud/getting-started.html

Authenticate with your Git provider using their respective CLIs. This is a prerequisite for `gg sync` and `gg land` to create or merge pull/merge requests.

```bash
__
# GitHub
gh auth login

# GitLab
gl ab auth login
```

--------------------------------

### Rules for AI Agents with Git Gud

Source: https://mrmans0n.github.io/git-gud/print.html

Important rules to follow when using AI agents with the Git Gud CLI.

```APIDOC
## Rules for AI Agents with Git Gud

### Description
When using AI agents with `gg`, keep these rules:

1.  **Never land without explicit user confirmation**
2.  **Never run `git add -A` blindly** (stage only reviewed/intended files)
3.  **Prefer worktrees** for isolation (`gg co --wt`)
4.  **Use structured output (`--json`)** when automation must parse command results
```

--------------------------------

### Land All Stack Entries and Clean Up

Source: https://mrmans0n.github.io/git-gud/print.html

The `gg land --all --clean` command merges all entries in the stack and then cleans up the associated branches and worktrees. This is a one-off operation for a complete merge and cleanup.

```bash
__
gg land --all --clean

```

--------------------------------

### List Stack Entries

Source: https://mrmans0n.github.io/git-gud/print.html

Use `gg ls` to list all entries in the current stack. The output includes ordered entries, each with a unique GG-ID, which is essential for referencing specific commits.

```bash
__
gg ls

```

--------------------------------

### Run Sequential Prompt Mode

Source: https://mrmans0n.github.io/git-gud/commands/split.html

Use the --no-tui flag to trigger the legacy sequential prompt style, which is also the default in non-TTY environments.

```bash
gg split --no-tui
```

--------------------------------

### Create or Switch to Stack Branch

Source: https://mrmans0n.github.io/git-gud/print.html

Use `gg co` to create or switch to a branch for a specific user-auth stack. This command is useful for managing individual feature branches within a larger stack.

```bash
__
gg co user-auth

```

--------------------------------

### Sync Stack with Draft PRs/MRs

Source: https://mrmans0n.github.io/git-gud/print.html

The `gg sync --draft` command pushes each branch in the stack and creates a draft Pull Request (PR) or Merge Request (MR) for each commit. These PRs/MRs are chained by their dependencies.

```bash
__
gg sync --draft

```

--------------------------------

### gg ls - List Stacks

Source: https://mrmans0n.github.io/git-gud/print.html

Command to list the current stack, all local stacks, or remote-only stacks.

```APIDOC
## `gg ls` - List Stacks

### Description
List the current stack, all local stacks, or remote-only stacks. When the stack base is behind `origin/<base>`, output includes a `↓N` indicator (`N` = commits behind).

### Usage
```bash
gg ls [OPTIONS]
```

### Options
*   `-a, --all`: Show all local stacks
*   `-r, --refresh`: Refresh PR/MR status from remote
*   `--remote`: List remote stacks not checked out locally. Stacks whose PRs/MRs are all merged are shown in a separate “Landed” section at the bottom with a `✓` marker
*   `--json`: Print structured JSON output (for scripts and automation). Automatically performs a best-effort refresh of PR/MR state from the provider API, so `pr_state` and `ci_status` fields are populated without needing `--refresh`.

### Examples
```bash
# Current stack status
gg ls

# All local stacks
gg ls --all

# Remote stacks (active first, then landed)
gg ls --remote

# Refresh status badges from provider
gg ls --refresh

# Structured JSON for automation
gg ls --json
gg ls --all --json
gg ls --remote --json
```
```

--------------------------------

### List Git Stacks

Source: https://mrmans0n.github.io/git-gud/print.html

Use `gg ls` to list the current stack, all local stacks, or remote-only stacks. The `--json` flag provides structured output for automation.

```bash
gg ls [OPTIONS]
```

```bash
# Current stack status
gg ls
```

```bash
# All local stacks
gg ls --all
```

```bash
# Remote stacks (active first, then landed)
gg ls --remote
```

```bash
# Refresh status badges from provider
gg ls --refresh
```

```bash
# Structured JSON for automation
gg ls --json
gg ls --all --json
gg ls --remote --json
```

--------------------------------

### Configure Lint Commands in Git Gud Config

Source: https://mrmans0n.github.io/git-gud/print.html

This JSON configuration snippet shows how to set default lint commands within the `.git/gg/config.json` file. These commands will be executed by `gg lint` and `gg sync --lint`.

```json
{
  "defaults": {
    "lint": [
      "cargo fmt --check",
      "cargo clippy -- -D warnings"
    ]
  }
}

```

--------------------------------

### Relative navigation with git-gud

Source: https://mrmans0n.github.io/git-gud/commands/navigation.html

Navigate the commit stack relative to the current entry. Use `gg first` to go to the beginning of the stack, `gg last` to go to the most recent commit, `gg prev` for the previous commit, and `gg next` for the next commit.

```bash
gg first   # first entry
```

```bash
gg last    # stack head
```

```bash
gg prev    # previous entry
```

```bash
gg next    # next entry
```

--------------------------------

### Stack Management Commands

Source: https://mrmans0n.github.io/git-gud/print.html

Commands for managing Git Gud stacks, including checking out and syncing stacks.

```APIDOC
## Stack Management

### `stack_checkout`

Create a new stack or switch to an existing one.

**Parameters:**
  * `name` (string, optional): Stack name.
  * `base` (string, optional): Base branch (default: main/master).
  * `worktree` (boolean, optional): Use a git worktree for isolation.

### `stack_sync`

Push branches and create/update PRs/MRs for the current stack.

**Parameters:**
  * `draft` (boolean, optional): Create PRs as draft.
  * `force` (boolean, optional): Force-push branches.
  * `update_descriptions` (boolean, optional): Update PR descriptions from commit messages.
  * `no_rebase_check` (boolean, optional): Skip rebase-needed check.
  * `lint` (boolean, optional): Run lint before syncing.
  * `until` (string, optional): Only sync up to this position/GG-ID/SHA.
```

--------------------------------

### List Git Gud Entries

Source: https://mrmans0n.github.io/git-gud/guides/your-first-stack.html

View your ordered entries, each associated with a unique GG-ID. This helps in tracking and managing your stacked commits.

```bash
__
gg ls
```

--------------------------------

### CLI Command: gg run

Source: https://mrmans0n.github.io/git-gud/print.html

Executes an arbitrary command on each commit in the stack, supporting read-only validation, amending, or discarding changes.

```APIDOC
## gg run

### Description
Run an arbitrary command on each commit in the stack. Useful for validating changes, applying auto-fixers, or running per-commit shell commands.

### Usage
`gg run [OPTIONS] -- <COMMAND>...`

### Options
- **--until <UNTIL>** (string) - Optional - Stop at this commit position.
- **--amend** (flag) - Optional - Stage and fold modifications into the current commit.
- **--discard** (flag) - Optional - Revert working-tree changes after each commit.
- **--keep-going** (flag) - Optional - Continue on command failure.
- **--jobs <N>** (number) - Optional - Number of parallel workers.
- **--json** (flag) - Optional - Emit structured JSON output.

### Response Example (JSON)
{
  "version": 1,
  "run": {
    "results": [
      {
        "position": 1,
        "sha": "abc1234",
        "title": "Add feature",
        "passed": true,
        "commands": [
          {"command": "cargo test", "passed": true, "output": null}
        ]
      }
    ],
    "all_passed": true
  }
}
```

--------------------------------

### Git Gud Commands with JSON Output

Source: https://mrmans0n.github.io/git-gud/guides/agent-skills.html

These commands support a `--json` flag for machine-readable output, useful for AI agents and automation.

```bash
gg ls --json
```

```bash
gg sync --json
```

```bash
gg land --json
```

```bash
gg clean --json
```

```bash
gg lint --json
```

--------------------------------

### Move Entry and Amend

Source: https://mrmans0n.github.io/git-gud/guides/your-first-stack.html

Reorder entries and amend the current one. `gg sc` automatically rebases subsequent entries after the amendment.

```bash
__
gg mv 1
# edit files
git add .
gg sc
```

--------------------------------

### Sync Stack with Base Check

Source: https://mrmans0n.github.io/git-gud/guides/your-first-stack.html

Synchronize your stack. This command checks if your stack base is behind the origin base and warns if necessary. Use `--no-rebase-check` to bypass this warning.

```bash
__
gg sync
```

--------------------------------

### gg land command syntax

Source: https://mrmans0n.github.io/git-gud/commands/land.html

Basic usage syntax for the gg land command.

```bash
gg land [OPTIONS]
```
Tokens:
Raw