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:

Prefer but

Use git freely Use git with caution

but commit over git commit

git cherry-pick

git reset --hard

but rub over git rebase -i

git stash

git push --force

but undo over git reset

git tag

git rebase

but absorb for amending git revert

git clean

but reword for messages git blame , git bisect

git checkout <file>

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

Feature Git GitButler

Undo operations Complex reflog but undo

Time travel Risky reset but restore <sha>

Squash commits rebase -i

• editor but rub <src> <target>

Fix old commit stash → rebase → amend but absorb

Multiple features Switch branches constantly Virtual branches (simultaneous)

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:

Source Target Operation Example

File Branch Assign but rub g0 al

File Commit Amend but rub g0 abc123

Commit Commit Squash but rub abc123 def456

Commit Branch Move but rub abc123 ut

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:

• Analyzes which lines changed

• Finds the commit that introduced them

• Amends the change into that commit

• 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

Git Command But Command

git status

but status

git reflog

but oplog

git checkout -b

but branch new

git add

but rub <file> <branch>

git commit

but commit <branch> -m

git commit --amend

but rub <file> <commit> or but absorb

git rebase -i (squash) but rub <commit> <commit>

git rebase -i (reword) but reword <sha> -m

git reset --hard

but restore <sha> --force

N/A but undo

N/A but oplog snapshot

N/A but absorb

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

Error Cause Recovery

but status fails GitButler not initialized Run but to initialize, or check .git/gitbutler directory

"Branch not found" Virtual branch deleted/renamed Run but status to list available branches

"Conflict detected" Merge conflict during operation Resolve conflicts in files, then but commit

"Uncommitted changes" Operation blocked by dirty state Commit or stash changes first

Command hangs Large repo or network issue Wait, or Ctrl+C and retry

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