From d319f00227cc7911b177a44292d698f676145ce5 Mon Sep 17 00:00:00 2001 From: Josh Knapp Date: Mon, 27 Jul 2026 07:05:12 -0700 Subject: [PATCH] docs: instance branches should be orphan branches MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Records why, so the next person doesn't rebuild the trap: a branch off main carries a full copy of the app it has no reason to have and drifts behind it, and syncing it via `git merge origin/main` silently replaces the instance manifests with main's placeholders — no conflict, because only main touches those paths. instance/dnspegasus has been converted accordingly. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/README.md b/README.md index c6ea95b..2247d2b 100644 --- a/README.md +++ b/README.md @@ -410,6 +410,25 @@ claude plugin marketplace add https://your-git-host/you/shared-memory.git#instan The `#ref` suffix is undocumented in `claude plugin marketplace add --help` but is honored and persisted in `known_marketplaces.json` (verified on Claude Code 2.1.220). +**Make that an orphan branch, not a branch off `main`.** `marketplace add` reads +only the manifests, so the branch needs nothing else: + +```bash +git checkout --orphan instance/ +git rm -rf --cached . && find . -mindepth 1 -maxdepth 1 ! -name .git -exec rm -rf {} + +# restore just .claude-plugin/marketplace.json, plugin/.claude-plugin/plugin.json, +# plugin/.mcp.json — fill in your URL and client ID +claude plugin validate . && git add -A && git commit && git push +``` + +A branch off `main` carries a full copy of the application it has no reason to +have, so it drifts and someone can cut a stale deploy from it. Worse, syncing it +means `git merge origin/main`, which **silently replaces those manifests** with +the placeholders below — no conflict is raised, because only `main` ever touches +those paths. With no shared history there is nothing to sync and nothing to +clobber; if the manifest format changes upstream, hand-edit the three files and +re-run `claude plugin validate .`. + ### B. OAuth flow (manual, per-machine) ```bash -- 2.52.0