Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

refactor(git): normalize rtk-prefix usage, add metadata.version

Browse Source 
Two bundled fixes across the same nine skills, since both touch the
same files.

Issue #113: skill prose used rtk git and bare git inconsistently for
the same operations, with no stated rule for which applied where.
Executable instructed commands (a dispatch-table "Run" cell, a fenced
code-block procedure, an imperative step) now consistently use rtk
git; illustrative or referential mentions -- naming a flag's behavior,
quoting a doc heading, warning against an anti-pattern -- stay bare
git. Documented in the new plugins/git/README.md, scoped to this
plugin only: gitea-* skills talk to the server over MCP tools and
carry no git/rtk mentions at all.

Also the git-plugin slice of #127: metadata.version added to the
eight skills that lacked it. git-commits already had one and is
untouched.

Fixes: #113
Fixes: #127
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
This commit is contained in:
Defame1297
2026-09-07 20:36:49 +00:00
parent ffaa3afb41
commit 2c6ce438b6
22 changed files with 237 additions and 178 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
plugins/git/.apm/skills/git-worktrees/SKILL.md
View File

@@ -8,6 +8,7 @@ description: >
Not interactive multi-step git guidance -> `git-workflow`.
metadata:
version: "1.0.0"
category: git
source_keys:
- git-scm-worktree-docs
@@ -16,7 +17,7 @@ metadata:
## 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 `git worktree remove`, or `git worktree prune` afterwards.
- **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.
@@ -24,19 +25,19 @@ metadata:
| Operation | Run |
|---|---|
| Create on a branch that already exists locally | `git worktree add <path> <branch>` |
| Create on a new branch | `git worktree add -b <branch> <path>` |
| Create on the branch named after the path basename | `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 | `git worktree add -B <branch> <path>` |
| Create a local branch tracking a remote one | `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 | `git worktree add -d <path>` — detached HEAD |
| 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`, or `--porcelain -z` to parse |
| Lock or unlock | `git worktree lock [--reason <str>] <path>` / `git worktree unlock <path>` |
| Move | `git worktree move <from> <to>` |
| Remove | `git worktree remove <path>` |
| Prune stale metadata | `git worktree prune --dry-run`, then without the flag |
| Repair after a manual move | `git worktree repair` — in the main worktree if *it* moved, or inside a linked worktree that moved. `git worktree repair <path>...` — from any worktree, naming each moved linked worktree's new path |
| List | `rtk git worktree list -v`, or `--porcelain -z` to parse |
| 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
@@ -48,7 +49,7 @@ 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.** `git worktree add --lock` is atomic, where add-then-`lock` leaves a window in which the worktree is unprotected.
- **`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
@@ -61,6 +62,6 @@ worktrees:
lock_reason: <reason or empty>
```
Derive those fields from `git worktree list --porcelain -z`. For a single
Derive those fields from `rtk git worktree list --porcelain -z`. For a single
operation, report its outcome instead — `created: true`, `moved: true`,
`removed: true`.

62
plugins/git/.apm/skills/git-worktrees/references/worktrees.md
View File

@@ -23,17 +23,17 @@ that are usable.
## `add` forms
```bash
git worktree add <path> <branch> # <branch> exists locally: check it out — non-destructive
git worktree add -b <branch> <path> # create a new branch; fails if it exists
git worktree add <path> # branch named after $(basename <path>): checked out
rtk git worktree add <path> <branch> # <branch> exists locally: check it out — non-destructive
rtk git worktree add -b <branch> <path> # create a new branch; fails if it exists
rtk git worktree add <path> # branch named after $(basename <path>): checked out
# if it exists, else created from HEAD
git worktree add -B <branch> <path> # create the branch, or reset an existing one to HEAD,
rtk git worktree add -B <branch> <path> # create the branch, or reset an existing one to HEAD,
# discarding the commits it carried
git worktree add --track -b <branch> <path> <remote>/<branch>
rtk git worktree add --track -b <branch> <path> <remote>/<branch>
# new local branch tracking the remote — always works
git worktree add <path> <branch> # <branch> absent locally and in exactly one remote:
rtk git worktree add <path> <branch> # <branch> absent locally and in exactly one remote:
# Git expands this to the --track -b form above
git worktree add -d <path> # detached HEAD, no branch
rtk git worktree add -d <path> # detached HEAD, no branch
```
The same `git worktree add <path> <branch>` spelling appears twice above and does two
@@ -65,19 +65,19 @@ Using `-` as `<commit-ish>` is shorthand for `@{-1}` (the branch checked out bef
## New unborn branch
```bash
git worktree add --orphan -b <branch> <path>
rtk git worktree add --orphan -b <branch> <path>
```
Creates an empty branch with no commits. **`--orphan` needs Git 2.42 or later** — it was added
upstream in 2.42, and on 2.39.5 this fails with `error: unknown option 'orphan'` and exit 129.
Check `git --version` before reaching for it.
Check `rtk git --version` before reaching for it.
Fallback on older Git, verified on 2.39.5 — detach first, then orphan the linked worktree in place,
which leaves the main worktree on its own branch throughout:
```bash
git worktree add -d <path> # linked worktree, detached HEAD
rtk git worktree add -d <path> # linked worktree, detached HEAD
cd <path>
git switch --orphan <branch> # unborn branch: empty index, empty working tree
rtk git switch --orphan <branch> # unborn branch: empty index, empty working tree
```
`git worktree list` then shows the new worktree at `0000000 [<branch>]` until its first commit.
@@ -88,25 +88,25 @@ the disruption worktrees exist to avoid.
Suppress the initial checkout to configure sparse-checkout first:
```bash
git worktree add --no-checkout ../sparse main
rtk git worktree add --no-checkout ../sparse main
cd ../sparse
git sparse-checkout init --cone
git sparse-checkout set src/
git checkout main
rtk git sparse-checkout init --cone
rtk git sparse-checkout set src/
rtk git checkout main
```
## Worktree on removable media
```bash
git worktree add --lock --reason "external SSD" <path> <branch>
git worktree unlock <path> # when reconnected
rtk git worktree add --lock --reason "external SSD" <path> <branch>
rtk git worktree unlock <path> # when reconnected
```
## Remote-branch disambiguation
```bash
git worktree add --track -b <branch> <path> <remote>/<branch> # explicit: no guessing at all
git worktree add <path> <branch> # shortcut: needs one clear remote
rtk git worktree add --track -b <branch> <path> <remote>/<branch> # explicit: no guessing at all
rtk git worktree add <path> <branch> # shortcut: needs one clear remote
```
**The bare-name shortcut needs exactly one remote.** It fires only when `<branch>` is not found
locally, none of `-b`/`-B`/`--detach` were given, and a tracking branch of that name exists in
@@ -122,10 +122,10 @@ exactly one remote has it, and marks that branch as upstream. Its default comes
## Repair after a manual move
```bash
git worktree repair # the MAIN worktree moved: run it there to reconnect every linked
rtk git worktree repair # the MAIN worktree moved: run it there to reconnect every linked
# worktree back to the main worktree
git worktree repair # a LINKED worktree moved: run it inside that recently-moved worktree
git worktree repair <path>... # reconnect a specific linked worktree — runnable from any worktree,
rtk git worktree repair # a LINKED worktree moved: run it inside that recently-moved worktree
rtk git worktree repair <path>... # reconnect a specific linked worktree — runnable from any worktree,
# naming each moved tree's new path
```
@@ -133,10 +133,10 @@ Which form applies depends on what moved:
| What moved | Remedy |
|---|---|
| The main worktree (or bare repo) | `git worktree repair` in the main worktree |
| One linked worktree | `git worktree repair` inside that worktree |
| Several linked worktrees | `git worktree repair <path>...` from any worktree, listing each new path |
| Both main and linked worktrees | `git worktree repair <path>...` in the main worktree, naming each linked worktree's new path — this restores the connections in both directions |
| The main worktree (or bare repo) | `rtk git worktree repair` in the main worktree |
| One linked worktree | `rtk git worktree repair` inside that worktree |
| Several linked worktrees | `rtk git worktree repair <path>...` from any worktree, listing each new path |
| Both main and linked worktrees | `rtk git worktree repair <path>...` in the main worktree, naming each linked worktree's new path — this restores the connections in both directions |
Only the no-argument form is tied to the current directory. The `<path>...` form is not — it
reestablishes the connection to every path you name, run from any worktree.
@@ -157,20 +157,20 @@ reestablishes the connection to every path you name, run from any worktree.
untouched throughout:
```bash
git worktree add -b emergency-fix ../temp main
rtk git worktree add -b emergency-fix ../temp main
cd ../temp
# fix, then commit
git commit -a -m "fix: critical production bug"
rtk git commit -a -m "fix: critical production bug"
cd -
git worktree remove ../temp
rtk git worktree remove ../temp
```
**Review a PR branch alongside your own work** — both branches stay checked out, so there is no
context switch:
```bash
git worktree add ../review-pr-123 origin/feature-xyz # detached HEAD — read-only review
git worktree add --track -b feature-xyz ../review-pr-123 origin/feature-xyz # if you will commit
rtk git worktree add ../review-pr-123 origin/feature-xyz # detached HEAD — read-only review
rtk git worktree add --track -b feature-xyz ../review-pr-123 origin/feature-xyz # if you will commit
# open ../review-pr-123 in a second editor window or terminal
```