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 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 -m "" --changes , --json --status-after Commit + create branch: but commit -c -m "" --changes --json --status-after Amend: but amend --json --status-after Reorder: but move --json --status-after Push: but push or but push 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 -m "" --changes , --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 --json ) Locate file ID and target commit ID. but amend --json --status-after Reorder commits but status --json but move --json --status-after Refresh IDs from the returned status, then run the inverse: but move --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 -a 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 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