GitButler CLI Skill
Use GitButler CLI (but ) as the default version-control interface.
Non-Negotiable Rules
-
Use but for all write operations. Never run git add , git commit , git push , git checkout , git merge , git rebase , git stash , or git cherry-pick . If the user says a git write command, translate it to but and run that.
-
Always add --json --status-after to mutation commands.
-
Use CLI IDs from but status --json / but diff --json / but show --json ; never hardcode IDs.
-
Start with but status --json before mutations so IDs and stack state are current.
-
Create a branch for new work with but branch new <name> when needed.
Core Flow
Every write task should follow this sequence.
1. Inspect state and gather IDs
but status --json
2. If new branch needed:
but branch new <name>
3. Edit files (Edit/Write tools)
4. Refresh IDs if needed
but status --json
5. Perform mutation with IDs from status/diff/show
but <mutation> ... --json --status-after
Command Patterns
-
Commit: but commit <branch> -m "<msg>" --changes <id>,<id> --json --status-after
-
Commit + create branch: but commit <branch> -c -m "<msg>" --changes <id> --json --status-after
-
Amend: but amend <file-id> <commit-id> --json --status-after
-
Reorder: but move <source-commit-id> <target-commit-id> --json --status-after
-
Push: but push or but push <branch-id>
-
Pull: but pull --check --json then but pull --json --status-after
Task Recipes
Commit files
-
but status --json
-
Find the cliId for each file you want to commit.
-
but commit <branch> -m "<msg>" --changes <id1>,<id2> --json --status-after
Use -c to create the branch if it doesn't exist. Omit IDs you don't want committed.
Amend into existing commit
-
but status --json (or but show <branch-id> --json )
-
Locate file ID and target commit ID.
-
but amend <file-id> <commit-id> --json --status-after
Reorder commits
-
but status --json
-
but move <commit-a> <commit-b> --json --status-after
-
Refresh IDs from the returned status, then run the inverse: but move <commit-b> <commit-a> --json --status-after
Stacked dependency / commit-lock recovery
If your change depends on another branch, or but commit fails with a lock error:
-
but status --json — confirm stack context.
-
but branch new <child-branch> -a <base-branch>
-
Continue mutations on the aligned branch.
Git-to-But Map
git but
git status
but status --json
git add
- git commit
but commit ... --changes ...
git checkout -b
but branch new <name>
git push
but push
git rebase -i
but move , but squash , but reword
git cherry-pick
but pick
Notes
-
Prefer explicit IDs over file paths for mutations.
-
--changes accepts comma-separated values (--changes a1,b2 ) or repeated flags (--changes a1 --changes b2 ), not space-separated.
-
Read-only git inspection (git log , git blame ) is allowed.
-
After a successful --status-after , don't run a redundant but status unless you need new IDs.
-
Avoid --help probes; use this skill and references/reference.md first. Only use --help after a failed attempt.
-
Run but skill check only when command behavior diverges from this skill, not as routine preflight.
-
For command syntax and flags: references/reference.md
-
For workspace model: references/concepts.md
-
For workflow examples: references/examples.md
-
For but link coordination workflow and conventions: references/link.md