GitButler CLI workflow cheatsheet for git users

gitbutler-workflow.md

GitButler CLI Workflow (for git users)

Mental model

You stay on gitbutler/workspace always. Multiple virtual branches coexist in one directory. No switching, no stashing.

Daily work

but status                              # what's going on
but branch new feat/thing               # start a feature
but mark feat/thing                     # auto-route all new changes here
# ... write code ...
but commit feat/thing --ai              # commit (AI message)
but commit feat/thing -m "message"      # commit (manual message)
but push feat/thing                     # push
but pr new feat/thing                   # create PR

Multiple features at once

but branch new feat/a
but branch new fix/b
# edit files for both freely
but stage <file-id> feat/a              # assign file to branch
but stage <file-id> fix/b
but commit feat/a --ai
but commit fix/b --ai

Syncing with upstream

but pull                                # fetch upstream, rebase all virtual branches
but pull --check                        # dry-run: can branches cleanly rebase?

Landing a branch to main

but merge feat/thing                    # merge virtual branch into local main
git push upstream main                  # push main (real branch, not virtual)

Complex trunk work (rebase, conflicts, multi-PR landing)

but teardown                            # exit GitButler, snapshot state
git checkout main
git pull upstream main
# ... rebase, merge, fix conflicts ...
git push upstream main
but setup                               # re-enter GitButler, restore everything

Reviewing coworker PRs

gh pr diff 123                          # read diff (no checkout needed)
gh pr view 123                          # view PR details
gh pr checkout 123                      # need to run code? leaves workspace
git checkout gitbutler/workspace        # come back when done

Undo / safety net

but undo                                # undo last operation
but oplog                               # view full operation history
but oplog restore <sha>                 # restore to any point

Hooks

GitButler wraps hooks in .husky/_/ (gitignored, local-only). Your Husky lint-staged setup runs normally. Other contributors are unaffected. but teardown auto-restores original hooks.

Key rules

• Use but for writes (commit, push, branch, stage)
• Use git for reads (log, diff, blame, status)
• Use gh for collaboration (PR review, checkout)
• Never git commit or git checkout on gitbutler/workspace