# Gitbutler CLI

> MANDATORY when on 'gitbutler/workspace' branch. Use `but` commands instead of git for commits, pushes, staging. Key commands: `but status -v`, `but stage <file> <branch>`, `but commit -m 'msg' <branch>`, `but push <branch>`. Invoke this skill BEFORE any git commit/push when gitbutler/workspace is the current branch.

- Skill: `amitkot/gitbutler-cli` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add amitkot/gitbutler-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/amitkot/gitbutler-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: amitkot (https://skillmd.com/u/amitkot)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/amitkot/gitbutler-cli

---


# 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 files to a branch (`but stage`)
- Viewing commit/branch details (`but show`)
- Viewing diffs (`but diff`)

Do NOT use for repositories NOT on `gitbutler/workspace` branch.

**Note:** Read-only git operations like `git log`, `git show` still work alongside `but`.

## Live Command Reference

The following is live help output from the installed `but` CLI. Use ONLY these flags.

### `but` top-level help
!`but --help 2>&1`

### `but status` help
!`but status --help 2>&1`

### `but show` help
!`but show --help 2>&1`

### `but diff` help
!`but diff --help 2>&1`

### `but commit` help
!`but commit --help 2>&1`

### `but branch` help
!`but branch --help 2>&1`

### `but push` help
!`but push --help 2>&1`

### `but pr` help
!`but pr --help 2>&1`

## Core Concepts

### Virtual Branches
Multiple branches active simultaneously. Changes belong to different virtual branches without switching contexts.

### Stacks
A series of commits on a virtual branch. Squash, amend, move, and reorder easily.

### The `but` Command
All GitButler operations use `but`. It is simpler and safer than complex Git commands, but has **different flags**.

## Best Practices

1. `but status -v` to see workspace state
2. `but undo` to revert any mistake
3. `but <cmd> --help` when unsure about flags
4. **Never guess flags from git knowledge** - always verify with `--help`
5. **Default to `--json`** (see the CRITICAL section at the top of this skill).