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:**

```bash
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 describe` 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:**
```bash
# 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!)
```bash
but statu