From d0e2ad43423defe36c255e26ffc436d64825a3a7 Mon Sep 17 00:00:00 2001 From: zhuangjianguo Date: Sun, 30 Aug 2026 09:45:42 +0000 Subject: [PATCH] docs(agents): harden the worktree recipe with --no-track, and name .git/config in the shared-namespace inventory The prescribed 'git worktree add -b origin/main' writes the new branch's upstream config (branch.NAME.remote / branch.NAME.merge) into the one .git/config every linked worktree shares, and that write can fail AFTER the branch is created -- leaving a branch with no worktree, a state the recipe never mentions. --no-track skips the config write entirely and still bases the worktree on origin/main; nothing in the agent flow needs the upstream, because 'git push -u origin ' sets one a command later. Line-neutral in both files (AGENTS.md 1162/1162, CLAUDE.md 86/86). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01EXxTW8mvPBhoHxmyPZ63de --- AGENTS.md | 6 +++--- CLAUDE.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a0de15a812..e48ff67dea 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -232,8 +232,8 @@ localStorage / auth gotchas. 11. **Worktree-first — never edit on the shared `main` checkout.** This repo is edited by **multiple agents at once**; the shared tree has its HEAD switched and reset *under you*, silently clobbering uncommitted work — a feature branch on the *shared* checkout is **not** enough (it still gets switched under you). Before your **first file - edit**, be in a dedicated worktree on a feature branch: `git fetch origin main && - git worktree add ../objectstack- -b origin/main && cd ../objectstack- && pnpm install`. Two + edit**, be in a dedicated worktree on a feature branch: `git fetch origin main && git worktree add --no-track + ../objectstack- -b origin/main && cd ../objectstack- && pnpm install`. Two PreToolUse hooks **enforce** this — `.claude/hooks/guard-main-checkout.sh` blocks `Edit`/`Write`/`NotebookEdit`, and `.claude/hooks/guard-main-checkout-bash.sh` blocks the identical write arriving through **Bash** (`>`/`>>` redirection, `sed -i`, `perl -i`, `tee`, `cp`, `mv`, `rm`, `touch`) — and both check the **target file's own @@ -394,7 +394,7 @@ git worktree add ../objectstack--cmp # a second tree to compa **⛔ The stash is one CASE — a worktree isolates your checkout and exactly four ref namespaces (`HEAD`, `refs/bisect`, `refs/worktree`, `refs/rewritten`) and NOTHING else:** -not the object store, not the config, not any other ref, so "worktrees isolate refs, +not the object store, not `.git/config`, not any other ref, so "worktrees isolate refs, except stash" is exactly backwards. **`refs/remotes/*` is shared** — a sibling's fetch advances **your** `origin/main` (measured next door: three moves in ten minutes), so `git checkout origin/main -- ` restores wherever that ref points **now**, possibly diff --git a/CLAUDE.md b/CLAUDE.md index a083dc92d4..577c197cab 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -29,7 +29,7 @@ shared checkout is NOT enough** — it still gets switched under you. You MUST b **dedicated per-task worktree**: ``` -git fetch origin main && git worktree add ../- -b origin/main && cd ../- && pnpm install +git fetch origin main && git worktree add --no-track ../- -b origin/main && cd ../- && pnpm install ``` Then make all edits there. This applies **per repo**: if a task spans `framework` and