gitbutler（gitbutler 搜索）

GitButler CLI Guide

GitButler (but) is a modern Git client that makes history manipulation safe and reversible.

[IMPORTANT] Detect GitButler Workspace

Before running any git commands, check if GitButler is active:

git branch --show-current

If the result is gitbutler/workspace:

• [PREFER] but commands when equivalent exists (commit, squash, undo, amend)
• [OK] Native git for operations but doesn't cover (cherry-pick, stash, tag, revert, blame)
• [CAUTION] Some git commands can corrupt virtual branch state (see below)

Git Command Guidelines:

Why prefer but when available? GitButler manages virtual branches through its workspace:

• but commands maintain virtual branch tracking
• but undo and oplog provide safer recovery
• Some raw git commands can corrupt the virtual branch state

Quick detection pattern:

# At start of git-related tasks, check:
if [[ $(git branch --show-current) == "gitbutler/workspace" ]]; then
    # Use 'but' commands instead of 'git'
fi

Key Advantages Over Git

Essential Commands

Inspection (Always Start Here!)

but status              # View workspace state (branches, commits, changes)
but oplog               # View operation history (time-travel checkpoints)

Status output explained:

╭┄00 [Unassigned Changes]
┊   g0 M calculator.py [LOCKED] 8ebedce   ← File ID, status, dependency
┊
┊╭┄al [calculator-feature]                ← Branch ID
┊●   abc1234 Commit message               ← Commit
├╯
┊
┴ 6e7da9e (common base) [origin/main]

• g0, h0: File/change IDs (use with but rub)
• al, ut: Branch IDs
• [LOCKED] <sha>: GitButler detected this change belongs to that commit
• M, A, D: Modified, Added, Deleted

The rub Multi-Tool

The rub command performs different operations based on source/target types:

Squash workflow:

but status                        # Get current SHAs
but rub <source-sha> <target-sha> # Squash source INTO target
but reword <new-sha> -m "Combined message"  # Update message

Smart Amending with absorb

When you modify code, GitButler detects which commit introduced those lines:

# Edit a file, then check status
but status
# Shows: g0 M file.py [LOCKED] abc123  ← Detected dependency!

# Auto-amend to the correct commit
but absorb

GitButler automatically:

1. Analyzes which lines changed
2. Finds the commit that introduced them
3. Amends the change into that commit
4. Rebases all dependent commits

Commit Editing

but reword <sha> -m "new message"  # Edit commit message (auto-rebases)
but absorb                            # Auto-amend changes to correct commits
but absorb <file-id>                  # Absorb specific file only

Undo & Recovery (Time Travel)

but undo                      # Undo last operation (one step back)
but oplog snapshot -m "checkpoint"  # Create named checkpoint
but restore <sha> --force     # Restore to any oplog snapshot

The oplog is your time machine:

but oplog                     # See all operations
# Output:
# 7f8e652 [SQUASH] SquashCommit
# abc1234 [CREATE] CreateCommit
# def5678 [MOVE_HUNK] MoveHunk

but restore 7f8e652 --force   # Go back to that point

Even undos are tracked! You can undo an undo.

Virtual Branches (Work on Multiple Features)

Create and manage branches:

but branch new <name>         # Create virtual branch
but branch list               # List all branches
but branch unapply <id>       # Hide branch temporarily
but branch apply <id>         # Show branch again

Work on multiple features simultaneously:

# Edit files for different features
vim feature-a.py
vim feature-b.py

# Check status - assign to different branches
but status
# g0 M feature-a.py
# h0 M feature-b.py

but rub g0 al                 # Assign to branch 'al'
but rub h0 ut                 # Assign to branch 'ut'

# Commit to each branch
but commit al -m "Feature A" --only
but commit ut -m "Feature B" --only

No context switching! Both branches are active simultaneously.

Committing

but commit <branch> -m "message"        # Commit ALL uncommitted changes
but commit <branch> -m "message" --only # Commit ONLY assigned changes
but commit -c -m "message"              # Create new branch and commit

[CAUTION] Important: Without --only, but commit includes ALL uncommitted changes!

Quick Reference: Git → But

Common Workflows

Fix typo in old commit message

but status                           # Find the commit SHA
but reword <sha> -m "Fixed message"

Squash multiple commits

but status                           # Get SHAs
but rub <source> <target>            # Squash
but reword <new-sha> -m "Combined" # Update message

Amend change to old commit

# Edit the file, then:
but status                           # Check for [LOCKED] dependency
but absorb                           # Auto-amend

Recover from mistake

but undo                             # Quick: undo last operation
# OR
but oplog                            # Find the right snapshot
but restore <sha> --force            # Go back in time

Error Handling

Common Errors and Recovery

Recovery Commands

but undo                    # Undo last operation (safe, always works)
but oplog                   # View all operations for recovery points
but restore <sha> --force   # Restore to any previous state
but oplog snapshot list           # List named checkpoints

When to Use undo vs restore

• but undo: Quick single-step rollback. Use when the last operation went wrong.
• but restore: Time-travel to any point. Use when you need to go back multiple operations or to a named checkpoint.

[INFO] The oplog tracks everything, including undos. You can always recover!

Claude Code Hooks Integration

GitButler integrates with Claude Code through hooks (but claude pre-tool, but claude post-tool, but claude stop) that automatically manage commits during AI-assisted development sessions.

Key benefits:

• Auto-assigns changes to appropriate branches
• Generates commit messages from user prompts
• Eliminates manual but commit during sessions

For detailed configuration and setup instructions, see references/hooks.md.

Reference Files

For detailed documentation, see:

• references/cheatsheet.md - Quick command reference with git → but mappings
• references/tutorial.md - Comprehensive step-by-step workflows
• references/hooks.md - Claude Code hooks setup guide