Version
0.22.1
Operating System
Windows
Distribution Method
msi (Windows)
Describe the issue
My editor (Cursor IDE) was having issues with 0.22.1, potentially the previous version also, not sure. After watching it go in circles for a while, I had it do some research into what kept failing, and it suggested the following updates to some files.
In SKILL.md , it added a block between ## Command Patterns and ### Commit:
### Invalid combinations (do not run these)
`but commit` targeting is **mutually exclusive** — pick exactly one of `-b` / `--above` / `--below`:
```bash
# WRONG — CLI rejects: "the argument '--branch' cannot be used with '--above'"
but commit -b fix/war-room-sync-latency --above pyp -m "fix(sync): pool key" ow:8
# RIGHT — new commit at the branch tip
but commit -b fix/war-room-sync-latency -m "fix(sync): pool key" ow:8 ow:7
# RIGHT — insert above an existing commit (no -b; GitButler places on a new branch above the anchor)
but commit --above pyp -m "fix(sync): pool key" ow:8 ow:7
but absorb accepts at most one optional uncommitted file ID — not hunks, not multiple files:
# WRONG — CLI rejects: "unexpected argument 'lpk' found"
but absorb zl lpk --dry-run
# RIGHT — all uncommitted changes
but absorb
but absorb --dry-run
# RIGHT — one file at a time (re-run per file, or use bare absorb for all)
but absorb zl
but absorb lpk
It rewrote:
- Commit at a specific history position: `--above <commit-or-branch>` or `--below <commit-or-branch>` instead of `-b`
to
- Commit at a specific history position: `--above <commit-or-branch>` or `--below <commit-or-branch>` **instead of** `-b` — never combine them
It added:
- Absorb: `but absorb` (all uncommitted) or `but absorb <uncommitted-file-id>` (one file only) — amends dirty lines into the commits that own them; `but absorb --dry-run` / `--json` preview the plan. Unlike `commit`/`discard`, absorb does **not** accept multiple file IDs or hunk IDs in one call
It added:
### Absorb uncommitted edits into owning commits
Use when dirty files should land in existing commits (rules mirrored across branches, follow-up edits on stacked work) instead of a new `but commit`.
1. `but absorb --dry-run` — read the plan (which hunks target which commits).
2. `but absorb` — all uncommitted files; or `but absorb <file-id>` — **one** uncommitted file ID from `but diff` (e.g. `zl`, not `zl:6` and not `zl lpk`).
3. On failure (`Failed to absorb`, dependency hints), run the printed `but move <branch> --above <dependency>` once, then retry. If absorb still rejects one file, try `but amend -t <commit-id> <hunk-ids>` or `but commit -b <branch> -m "..." <ids>` per the split-commit recipe — do not pass multiple file IDs to `but absorb`.
In reference.md, it changed:
**Where the commit goes:** `-b`/`--branch`, `-A`/`--above`, and `-B`/`--below` are mutually exclusive.
into
**Where the commit goes:** `-b`/`--branch`, `-A`/`--above`, and `-B`/`--below` are mutually exclusive. Combining `-b` with `--above` or `--below` fails immediately (`the argument '--branch' cannot be used with '--above'`).
then added:
### `but absorb [SOURCE]`
Amend uncommitted edits into the commits that own them (dependency-aware). Optional `[SOURCE]` is **one** uncommitted **file** CLI ID from `but diff` — not a hunk ID, not multiple IDs (`but absorb zl lpk` fails).
```bash
but absorb # All uncommitted changes
but absorb zl # One file only
but absorb --dry-run # Plan only
but absorb --json # Machine-readable plan
On failure, read the plan / dependency Hint; do not retry with multiple file arguments.
### How to reproduce (Optional)
_No response_
### Expected behavior (Optional)
_No response_
### Relevant log output (Optional)
```shell
Version
0.22.1
Operating System
Windows
Distribution Method
msi (Windows)
Describe the issue
My editor (Cursor IDE) was having issues with 0.22.1, potentially the previous version also, not sure. After watching it go in circles for a while, I had it do some research into what kept failing, and it suggested the following updates to some files.
In SKILL.md , it added a block between ## Command Patterns and ### Commit:
but absorbaccepts at most one optional uncommitted file ID — not hunks, not multiple files:It rewrote:
to
It added:
It added:
In reference.md, it changed:
into
then added:
On failure, read the plan / dependency Hint; do not retry with multiple file arguments.