Defame1297
ed8c99efbd
The #113 sweep rested on CLAUDE.md's premise that rtk either filters or passes through unchanged, so prefixing is always safe. Measured against rtk 0.42.4, that premise is false for several of the commands the sweep prefixed, and two skills were left giving wrong answers silently. Why: - `rtk git worktree list --porcelain -z` discards both flags and renders its own format. The `locked`/`lock_reason` fields git-worktrees Step 2 must emit are absent entirely, and paths under $HOME are abbreviated to `~/`. - `rtk git branch --list <name>` prints a phantom `* ` line even when nothing matches, so git-branches' stated ambiguity test — "output from both means the name is ambiguous" — reported every name as ambiguous. `tag --list` is a clean passthrough, so only one half broke. - `rtk git diff --name-only`/`--name-status` append a `Changes:` trailer to output documented as "one per line"; `--word-diff` emits none of the `[-removed-] {+added+}` markers its table describes; `rtk git log -L` truncates each line at ~72 chars, on the one command whose purpose is showing line content. - `rtk git stash pop` prints only `FAILED: git stash pop`, swallowing the conflict diagnostic and retained-entry message the surrounding prose tells the agent to rely on. Implementation notes: - Eleven sites reverted to bare `git`, each carrying its reason inline so the next sweep does not undo it. `mergetool` and `rebase -i` are reverted on clause 3's interactive limb only: the TTY defect does not reproduce — rtk filters exactly twelve subcommands and execs the rest — and ADR-0023 records that measurement rather than a convenient one. - ADR-0023 states the rule repo-wide with a third clause: a command whose output the skill parses, or which is interactive, stays bare. `plugins/git/README.md` is reduced to a pointer; its claim that gitea skills "contain no git/rtk mentions at all" was false, and its citation of `hard-rules.md` pointed at a file containing no occurrence of "rtk". - Eight gitea sites swept, all verified byte-identical passthroughs first. - `scripts/check-rtk-prefix.sh` gates clause 1. Run against main's pre-sweep corpus it reports 99 findings including every gitea site, so it would have caught the drift #113 was filed about. Impact: the gate covers clause 1 only, in shell-tagged fences and the opening span of Run cells. Clause 2 is not gateable — "Run `git switch`" and "`git switch` refuses" are the same tokens — and prose bullets are invisible to it. Both limits are recorded in gates.md rather than left implied. Refs: #113 ADR: 0023 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
60 lines
3.7 KiB
Markdown
60 lines
3.7 KiB
Markdown
---
|
|
source_keys:
|
|
- context7-git-htmldocs
|
|
---
|
|
|
|
# Per-action command mapping
|
|
|
|
One command per action. Where two forms exist, the first is the default and the second the escape
|
|
hatch.
|
|
|
|
- **create** — `rtk git switch -c <branch> <base>`. Base comes from the config's `base_branch`
|
|
(`main` under GitHub Flow, usually `develop` under Gitflow).
|
|
- **switch** — `rtk git switch <branch>` moves to an existing local branch; it aborts rather than
|
|
clobbering conflicting local changes. `rtk git switch -` returns to the previous branch.
|
|
- **delete (local)** — `rtk git branch -d <branch>` refuses when the branch holds unmerged commits,
|
|
which is why it is the default. `rtk git branch -D <branch>` forces the deletion and discards that
|
|
work — only after the destructive-operation gates pass and `confirm: true` is set.
|
|
- **delete (remote)** — not this skill's. Deleting a remote branch is a push, and every remote-side
|
|
gate lives in `git-remotes`; hand it there rather than running the push from here. Its
|
|
`references/push.md` carries the command and the refspec form.
|
|
- **rename** — `rtk git branch -m <old> <new>`.
|
|
- **list** — `rtk git branch` (local), `-a` (local plus remote-tracking), `-r` (remote-tracking only),
|
|
`--merged` / `--no-merged` (filter by merge status into the current branch).
|
|
- **track** — `rtk git branch --set-upstream-to=origin/<branch>` sets an upstream without pushing.
|
|
`rtk git branch -vv` shows the tracking state of every local branch.
|
|
|
|
## get-intent
|
|
|
|
Git has no native field for free-text branch metadata, and this skill does not persist any. On
|
|
`create`, the `intent` value is only returned in the structured result — the caller decides
|
|
whether to store it.
|
|
|
|
On `get-intent`, either parse the intent back out of the branch-name convention
|
|
(`feature/<intent-slug>`) or return `{ "intent": null }` when the caller never persisted the
|
|
create-time value. Never fabricate an intent: a downstream commit message built on a guessed
|
|
intent is worse than one built on none.
|
|
|
|
## Stashing work in progress
|
|
|
|
A switch aborts rather than clobbering conflicting local changes (see Gotchas). Stash is the way
|
|
past it: it shelves the working tree and index so the branch pointer can move.
|
|
|
|
- **save** — `rtk git stash push -m "<message>"`. Add `-u` to include untracked files; verified on Git
|
|
2.39.5, a plain `push` leaves them in place, and a plain `push` with *only* untracked changes
|
|
reports `No local changes to save` and stashes nothing. Bare `git stash` is `push` with no message.
|
|
- **restore** — `git stash pop` applies the newest entry and deletes it. Bare, not `rtk`: on a
|
|
conflict rtk prints only `FAILED: git stash pop` and swallows the conflict report the paragraph
|
|
below tells you to read (ADR-0023). `rtk git stash apply stash@{n}`
|
|
applies without deleting, for replaying one shelf onto more than one branch.
|
|
- **list** — `git stash list` — bare, not `rtk`: rtk prints `No stashes` where git prints nothing,
|
|
so an empty-output test misfires (ADR-0023). `rtk git stash show -p stash@{n}` prints that entry's diff.
|
|
- **drop** — `rtk git stash drop stash@{n}` deletes one entry. `rtk git stash clear` deletes all of them
|
|
and nothing recovers them — confirm before running it.
|
|
- **branch from a stash** — `rtk git stash branch <branch> stash@{n}` creates a branch at the commit the
|
|
stash was taken from and pops it there. Use it when the stash no longer applies to the current tip.
|
|
|
|
**A conflicting `pop` keeps the entry.** Verified on 2.39.5: it exits 1, writes conflict markers,
|
|
prints "The stash entry is kept in case you need it again", and `git stash list` still shows it.
|
|
Resolve, `rtk git add`, then `rtk git stash drop` the entry by hand — otherwise it silently accumulates.
|