git-gud

git-gud (gg)

A stacked-diffs CLI tool for GitHub and GitLab, inspired by Gerrit, Phabricator/Arcanist, and Graphite.

What are Stacked Diffs?

Stacked diffs allow you to break large changes into small, reviewable commits that build on each other. Each commit becomes its own Pull Request (GitHub) or Merge Request (GitLab), with proper dependency chains. This enables:

• Faster reviews - Small, focused changes are easier to review
• Parallel work - Start the next feature while waiting for review
• Clean history - Each commit is a logical unit of change

You can read more here or here.

Installation

Homebrew (macOS/Linux)

brew install mrmans0n/tap/gg-stack

From crates.io

cargo install gg-stack

Prerequisites

• Git 2.x+
• For GitHub repositories: gh - GitHub CLI
• For GitLab repositories: glab - GitLab CLI

git-gud automatically detects your remote provider from the URL (github.com or gitlab.com) and uses the appropriate CLI tool.

Self-hosted instances: For GitHub Enterprise or self-hosted GitLab (e.g., gitlab.mycompany.com), run gg setup to manually select your provider.

Authenticate with your provider before using git-gud:

# For GitHub
gh auth login

# For GitLab
glab auth login

Quick Start

# Create a new stack
gg co my-feature

# Make changes and commit (normal git workflow)
git add . && git commit -m "Add data model"
git add . && git commit -m "Add API endpoint"
git add . && git commit -m "Add UI component"

# View your stack
gg ls

# Sync with remote (creates PRs/MRs)
gg sync --draft

# Navigate within the stack
gg first          # Go to first commit
gg next           # Go to next commit
gg prev           # Go to previous commit
gg last           # Return to stack head

# After review feedback, modify a commit
gg mv 1           # Move to commit 1
# make changes...
gg sc             # Squash changes into current commit (or: gg amend)

# Land approved PRs/MRs
gg land --all

# Clean up merged stacks
gg clean

📚 Full documentation — guides, command reference, configuration, and more.

Demo

Worktree Support

gg co and gg unstack --wt support managed Git worktrees so you can develop a stack in its own checkout while keeping your original repository working tree untouched.

Create a stack worktree

gg co my-feature --wt
# or
gg co my-feature --worktree

This creates (or reuses) a managed worktree for the stack and checks it out there. To also move your shell into that worktree automatically, enable shell integration:

# zsh
eval "$(gg init zsh)"

# bash
eval "$(gg init bash)"

# fish
gg init fish | source

Unstack into a worktree

gg unstack --target 3 --name upper-feature --wt

This keeps your current directory on the lower stack and creates or reuses a managed worktree for the new upper stack.

Default worktree location

By default, git-gud creates worktrees next to your repository using:

../<repo-name>.<stack-name>

For example, if your repo is at /code/my-repo, stack user-auth is created at:

/code/my-repo.user-auth

You can customize the base directory with defaults.worktree_base_path in .git/gg/config.json.

{
  "defaults": {
    "worktree_base_path": "/tmp/gg-worktrees"
  }
}

Stack visibility and cleanup

• gg ls / gg ls --all shows [wt] for stacks that have an associated worktree.
• gg clean detects associated stack worktrees and removes them as part of cleanup (with confirmation unless --all is used).

Typical worktree workflow

# 1) Create stack in a worktree
gg co user-auth --wt

# 2) Work inside the new worktree
cd ../my-repo.user-auth
git add . && git commit -m "Add user model"
git add . && git commit -m "Add auth endpoints"

# 3) Sync stacked branches / PRs/MRs
gg sync

# 4) Inspect stacks (worktree stacks are marked with [wt])
gg ls --all