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

chore(plugins): sync generated content mirrors

Browse Source 
Regenerate plugins/*/skills/ from plugins/*/.apm/ after the previous
four commits, via scripts/sync-plugin-content.sh --all. The mirror is
generated output (ADR-0017) that check-plugin-content-sync's pre-push
hook diffs against .apm/; nothing here is hand-edited.

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:43:51 +00:00
parent 09eea5e7ab
commit af8b46cd57
45 changed files with 467 additions and 201 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
plugins/git/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
```