Defame1297
38f1ba4e03
Claude Code's (and Copilot's) native plugin installer has zero awareness of .apm/ nesting -- it convention-scans only flat skills/, agents/, commands/, hooks.json at each plugin's root. Confirmed via strings on the installed claude binary and live installs of git@holocron/gitea@holocron/kyberforge@ holocron, all reporting Skills(0) Agents(0) Hooks(0) post ADR-0015's apm conversion. Root cause (apm_cli/core/plugin_manifest.py): apm's plugin.json compiler deliberately strips skills/agents/commands keys, assuming the host already auto-discovers those convention directories -- it has no model of .apm/ being host-visible at all. Separately, apm's own bundle exporter (apm_cli/bundle/plugin_exporter.py, behind `apm pack --format plugin`) implements the correct .apm/ -> flat mapping, but only ever targeted build/<name>-<version>/, a path nothing in marketplace.json's source: points at. scripts/sync-plugin-content.sh wraps that bundle exporter and copies its agents/, skills/, commands/, instructions/, extensions/, and merged hooks.json back into each plugin's own root as a second tracked compiled-output category -- same governance status as .claude-plugin/plugin.json: generated from .apm/, never hand-edited. tests/ subdirectories are excluded from the mirror (dev fixtures, not host-visible runtime content; several hardcode a relative repo-root walk-up sized for the .apm/-nested depth, which breaks when duplicated one level shallower). Applied for real across all 6 plugins and verified two ways: `claude plugin validate --strict` passes on every real plugin directory, and a live `claude --plugin-dir <path> -p "list skills/agents"` behavioral test confirms content is now actually discovered. Also, from the same issue #90 review round: - scripts/check-manifests.sh pointed at each plugin's root-level plugin.json (checking skills/hooks/mcpServers/agents pointer fields) -- that file was a stale near-duplicate of .claude-plugin/plugin.json nothing else read or wrote, now deleted across all 6 plugins. check-manifests.sh is rewritten to validate .claude-plugin/plugin.json instead, and drops the pointer-field checks entirely (nothing to check -- those fields are correctly absent by design). Content-presence drift is now check-plugin-content-sync's job, a new pre-push hook wired in .pre-commit-config.yaml. docs/adr/0017 records the root cause and decision in full, including two rejected alternatives (patching plugin.json's path fields directly -- apm's compiler strips them on every run; pointing marketplace.json at apm pack's build/ output -- a version-suffixed non-source directory nothing can install from without an extra build step). ADR-0015 and CONTEXT.md are updated to point at it. Refs: #90
2.4 KiB
2.4 KiB
topic, source_keys
| topic | source_keys | |
|---|---|---|
| worktrees |
|
Full add flag table
| Flag | Meaning |
|---|---|
-b <branch> |
Create and check out a new branch; fails if it exists |
-B <branch> |
Like -b but resets the branch if it already exists |
-d / --detach |
Detach HEAD; useful for throwaway experiments |
--orphan |
Create empty unborn branch |
--no-checkout |
Suppress initial checkout (for sparse-checkout setup) |
--guess-remote |
Look for a matching remote-tracking branch by path basename |
--lock [--reason <str>] |
Lock immediately on creation (atomic; avoids race vs. add-then-lock) |
-f / --force |
Allow when branch is already checked out elsewhere |
--relative-paths |
Link via relative paths (portable across moves) |
Using - as <commit-ish> is shorthand for @{-1} (the branch checked out before the current one), e.g. git worktree add <path> -.
New unborn branch
git worktree add --orphan -b <branch> <path>
Creates an empty branch with no commits.
Sparse-checkout worktree
Suppress the initial checkout to configure sparse-checkout first:
git worktree add --no-checkout ../sparse main
cd ../sparse
git sparse-checkout init --cone
git sparse-checkout set src/
git checkout main
Worktree on removable media
git worktree add --lock --reason "external SSD" <path> <branch>
git worktree unlock <path> # when reconnected
Remote-branch disambiguation
git worktree add <path> <remote>/<branch>
For ambiguous names across remotes, checkout.defaultRemote config disambiguates explicitly, or --guess-remote auto-matches by path basename (default controlled by worktree.guessRemote config). If a branch name matches multiple remotes during worktree add and neither is set, Git refuses rather than guessing.
Configuration
| Key | Effect |
|---|---|
worktree.guessRemote |
Default for --guess-remote on git worktree add |
worktree.useRelativePaths |
Default for --relative-paths on git worktree add (link via relative paths — portable across moves) |
gc.worktreePruneExpire |
How long before stale worktree metadata is pruned by git gc |
extensions.worktreeConfig |
Enable per-worktree config scope (config.worktree file) — see Gotchas in SKILL.md |
checkout.defaultRemote |
Disambiguates which remote to use when a branch name matches multiple remotes during worktree add |