gitbutler-clilisted

# GitButler CLI Skill ## CRITICAL: Default to `--json` **Always pass `--json` (or `-j`) to `but` commands unless a human is reading the output directly.** The default human tree output uses unicode box-drawing characters (`┊╭├┄┴`) that break common `grep`/`sed` patterns, and `tail -N` on a long status hides entire stacks — leading to wrong conclusions about workspace state. Pipe `--json` through `jq` instead. ```text but status --json | jq '.unassigned[].path' but status --json | jq '.stacks[].branches[].name' but show <id> --json | jq '.commits[]' but oplog list --json ``` Reserve plain output for the user-facing summary at the end of a turn. ## CRITICAL: `but` is NOT `git` **`but` has its own flags and syntax. Git flags DO NOT work with `but`.** Common mistakes to NEVER make: - `but show <commit> --stat` - WRONG (`--stat` is a git flag, not a but flag) - `but show <commit> --patch` - WRONG (`--patch` is a git flag) - `but show <commit> --oneline` - WRONG (`--oneline` is a git flag) - `but diff --cached` - WRONG (`--cached` is a git flag) - `but diff --stat` - WRONG (`--stat` is a git flag) - `but branch -a` - WRONG (`-a` is a git flag) **Rule: Only use flags that appear in the help output below. When unsure, run `but <cmd> --help` first.** ## When to Use This Skill Use this skill when on `gitbutler/workspace` branch - **use `but` instead of `git`** for: - Committing changes (`but commit` not `git commit`) - Pushing changes (`but push` not `git push`) - Staging fil