Skip to content

fix(setup): ignore the snapshot symlink that worktree-init creates - #1092

Open
potiuk wants to merge 1 commit into
apache:mainfrom
potiuk:fix/worktree-snapshot-symlink-gitignore
Open

fix(setup): ignore the snapshot symlink that worktree-init creates#1092
potiuk wants to merge 1 commit into
apache:mainfrom
potiuk:fix/worktree-snapshot-symlink-gitignore

Conversation

@potiuk

@potiuk potiuk commented Aug 17, 2026

Copy link
Copy Markdown
Member

Summary

  • adopt writes /.apache-magpie/ and /.apache-magpie-sources/ into the adopter's .gitignore. A dir/-style pattern matches only directories — but only the main checkout has directories there. worktree-init deliberately replaces both with symlinks to the main checkout's copies so every worktree shares one framework state and picks up /magpie-setup upgrade automatically.
  • Net effect: both entries show as untracked in every worktree of every adopter. That is git status noise on its own, and one careless git add -A away from committing a symlink whose target is a machine-local absolute path.
  • Dropping the trailing slash matches the directory, its contents, and the symlink alike, so the main checkout is unaffected. verify check 4 is updated to expect the unslashed form and to flag a legacy /.apache-magpie/ entry as a finding.

Type of change

  • Skill change (.claude/skills/<name>/) — eval fixtures updated below
  • Tool / bridge contract (tools/<system>/*.md)
  • Python package (tools/*/ with pyproject.toml)
  • Groovy reference impl
  • Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
  • Documentation (docs/, README.md, CONTRIBUTING.md)
  • Project template (projects/_template/)
  • CI / dev loop (prek, workflows, validators)
  • Other:

Test plan

Verified the pattern semantics directly in a scratch repo, with /.apache-magpie as the only ignore line:

dir  -> IGNORED      # main checkout
file -> IGNORED      # .apache-magpie/skills/a.md
link -> IGNORED      # worktree symlink

and confirmed the old /.apache-magpie/ pattern reports the symlink as not ignored, reproducing the bug.

Also confirmed against a live adopter (apache/airflow, worktree off the main checkout): git status reported ?? .apache-magpie before, and is clean after.

  • prek run --all-files passes — not run; the pre-commit hooks ran on the changed files at commit time and passed, including symlink-lint and skill-and-tool-validate
  • For Python packages touched: n/a — no Python changed
  • For Groovy bridges touched: n/a
  • For skill changes: eval suite passes for the affected skill — n/a, see below
  • For skill behaviour changes: a new or updated eval fixture is included in this PR — n/a, see below
  • Other: no eval asserts the .gitignore entry list. grep -rn '^/\.apache-magpie/$' tools/skill-evals/evals/ returns nothing, and tools/skill-evals/evals/setup/ has no fixture mentioning gitignore, so there is no fixture to update and no existing eval this can regress. Happy to add a setup eval case pinning the entry list if you'd like the behaviour locked down.

RFC-AI-0004 compliance

  • HITL — no new mutation
  • Sandbox — no change to host access
  • Vendor neutrality — the changed prose keeps the existing placeholders; no adopter-specific names introduced
  • Conversational + correctable — no adopter-tunable behaviour added
  • Write-access discipline — no outbound messages
  • Privacy LLM — no content routed to an LLM

Linked issues

None filed — found while adopting the framework in apache/airflow. The adopter-side .gitignore entry there is being fixed separately; this PR fixes the source that generates it for every adopter.

Notes for reviewers (optional)

Two judgement calls worth a look:

  1. /.claude/hooks/guards.d/ keeps its trailing slash. worktree-init copies the guards rather than symlinking them, so it is a real directory in every worktree and the slash is correct there. Only the two entries worktree-init symlinks are changed.
  2. verify wording. I made the legacy slashed form an explicit ✗ rather than silently accepting both, and noted that the check has to run from a worktree to see the failure at all — in the main checkout the old pattern passes, which is exactly why this went unnoticed.

The gitignore entries adopt writes use `/.apache-magpie/` and
`/.apache-magpie-sources/`. A `dir/`-style pattern matches only
directories, and only the main checkout has directories there --
worktree-init deliberately replaces both with symlinks to the main
checkout's copies so every worktree shares one framework state and
picks up `/magpie-setup upgrade` automatically.

The result is that both entries show as untracked in every worktree
of every adopter. That is `git status` noise on its own, and one
careless `git add -A` away from committing a symlink whose target is
a machine-local absolute path.

Dropping the trailing slash matches the directory, its contents, and
the symlink alike, so the main checkout is unaffected. verify's
check 4 is updated to expect the unslashed form and to say that a
legacy `/.apache-magpie/` entry is a finding -- it passes in the main
checkout and fails in every worktree, so it has to be checked from a
worktree to be seen at all.

Found while adopting the framework in apache/airflow, where the
adopter-side entry is fixed separately.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant