Defame1297
edcc57c0d6
Two related simplification-audit findings, bundled because they edit some of the same skill-audit files and splitting would fragment single-file diffs. Finding 10: delete 48 per-skill/reference README.md files (they restated SKILL.md in narrative form and no agent ever loads them) plus 2 scaffold templates. Drop the README criterion from skill-audit's file-structure.md and finding-criteria.md, and the README-generation step from skill-author's new-skill.sh; update new-skill.bats to match. Plugin-root READMEs are kept intentionally, out of scope. Finding 12: strip historical ADR-0020/ADR-0023 citations and changelog-style narration from model-facing skill content across kyberforge and git plugin skills. Delete skill-author's one-time retrofit.md migration guide and its references. Some ADR-0023 tags were not narration but check-rtk-prefix's required opt-out marker for intentionally-bare git commands -- those were restored, not stripped. Mirror re-synced and full pre-commit/pre-push suite verified green. Refs: SIMPLIFICATION-AUDIT.md findings 10, 12 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
69 lines
4.2 KiB
Markdown
69 lines
4.2 KiB
Markdown
---
|
|
name: git-worktrees
|
|
|
|
description: >
|
|
Use when working on several branches at once without stashing —
|
|
manages the full lifecycle of a git worktree.
|
|
Not ordinary branch switching or checkout -> `git-branches`.
|
|
Not interactive multi-step git guidance -> `git-workflow`.
|
|
|
|
metadata:
|
|
version: "1.0.2"
|
|
category: git
|
|
source_keys:
|
|
- git-scm-worktree-docs
|
|
---
|
|
|
|
## Gotchas
|
|
|
|
- **A branch can be checked out in only one worktree at a time.** `git worktree add` on an already-checked-out branch fails; `--force` is the only override, so use it only deliberately.
|
|
- **Never `rm -rf` a worktree directory.** That strands metadata in `$GIT_DIR/worktrees/`. Use `rtk git worktree remove`, or `rtk git worktree prune` afterwards.
|
|
- **Submodules break worktree support.** A worktree containing submodules cannot be moved at all, and needs `--force` to remove.
|
|
- **`extensions.worktreeConfig = true` is a one-way door.** Without it, `git config --worktree` errors; with it, that flag writes to the worktree's own `config.worktree` file, and `core.bare`/`core.worktree` are forced there too. It also breaks older Git. Leave it off unless per-worktree config is needed.
|
|
|
|
## Step 1 — Dispatch
|
|
|
|
| Operation | Run |
|
|
|---|---|
|
|
| Create on a branch that already exists locally | `rtk git worktree add <path> <branch>` |
|
|
| Create on a new branch | `rtk git worktree add -b <branch> <path>` |
|
|
| Create on the branch named after the path basename | `rtk git worktree add <path>` — checks that branch out if it exists, else creates it from HEAD |
|
|
| Create and reset an existing branch to HEAD — discards its commits | `rtk git worktree add -B <branch> <path>` |
|
|
| Create a local branch tracking a remote one | `rtk git worktree add --track -b <branch> <path> <remote>/<branch>` — always correct. `git worktree add <path> <branch>` expands to exactly this, but **only** under the conditions in `references/worktrees.md` |
|
|
| Throwaway experiment, no branch | `rtk git worktree add -d <path>` — detached HEAD |
|
|
| **Never** `git worktree add <path> <remote>/<branch>` | That ref resolves, so the shortcut never fires and you get **a detached HEAD, no branch, no upstream**. Commits there go unreachable once HEAD moves, and `git push` needs an explicit refspec. Use the tracking row above |
|
|
| List | `git worktree list -v` to read, or `git worktree list --porcelain -z` to parse — both bare (ADR-0023): rtk re-renders the output and drops the porcelain flags |
|
|
| Lock or unlock | `rtk git worktree lock [--reason <str>] <path>` / `rtk git worktree unlock <path>` |
|
|
| Move | `rtk git worktree move <from> <to>` |
|
|
| Remove | `rtk git worktree remove <path>` |
|
|
| Prune stale metadata | `rtk git worktree prune --dry-run`, then without the flag |
|
|
| Repair after a manual move | `rtk git worktree repair` — in the main worktree if *it* moved, or inside a linked worktree that moved. `rtk git worktree repair <path>...` — from any worktree, naming each moved linked worktree's new path |
|
|
|
|
If the operation needs anything the table does not carry — the full `add` flag
|
|
table, orphan branches, sparse-checkout, locking for removable media, remote
|
|
disambiguation across several remotes, how to name a worktree unambiguously,
|
|
worktree config keys, or the worked emergency-fix and PR-review patterns — read
|
|
`references/worktrees.md`.
|
|
|
|
Gates:
|
|
|
|
- **`move`, `remove` — the main worktree cannot be moved or removed.** Only linked worktrees, the ones `git worktree add` created, are candidates.
|
|
- **`add`, `move`, `remove` — escalate force flags one step at a time.** `-f` overrides a safeguard such as an unclean tree; `move` and `remove` need `-ff` on top of that when the worktree is locked. Confirm with the user before either — both discard state.
|
|
- **`add` — lock at creation, not after.** `rtk git worktree add --lock` is atomic, where add-then-`lock` leaves a window in which the worktree is unprotected.
|
|
|
|
## Step 2 — Report
|
|
|
|
```yaml
|
|
worktrees:
|
|
- path: <directory-path>
|
|
branch: <branch-name>
|
|
commit: <short-hash>
|
|
locked: <true/false>
|
|
lock_reason: <reason or empty>
|
|
```
|
|
|
|
Derive those fields from `git worktree list --porcelain -z` — bare, not `rtk`:
|
|
rtk drops both flags and never emits `locked`/`lock_reason`. For a single
|
|
operation, report its outcome instead — `created: true`, `moved: true`,
|
|
`removed: true`.
|