Defame1297
0f2bb242ad
Regenerates `plugins/*/skills`, `plugins/*/agents`, both per-plugin `plugin.json` manifests and the two marketplace mirrors from `.apm/` per ADR-0017, via `scripts/sync-plugin-content.sh --all`. The manifests matter beyond tidiness here: `plugin.json` carries the plugin version and wins over the marketplace entry at install time (calculatePluginVersion precedence). Until this ran, the patch bumps in the preceding commit were inert for anyone installing these plugins. ADR: 0017 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
69 lines
4.3 KiB
Markdown
69 lines
4.3 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.1"
|
|
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 per 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` (ADR-0023). For a single
|
|
operation, report its outcome instead — `created: true`, `moved: true`,
|
|
`removed: true`.
|