Skip to content

(tooling): docs-sync pre-commit hook stages phantom src/content/docs/** paths when committing from a worktree #651

Open

Description

@fhuthmacher

Component

CDK / infrastructure — repo tooling (prek / pre-commit hooks)

Describe the bug

The docs-sync pre-commit hook (.pre-commit-config.yaml) fails during a real git commit from a linked git worktree (.worktrees/<branch>/, which AGENTS.md mandates for all feature work). The commit is blocked with:

sync docs → Starlight mirrors....Failed
- hook id: docs-sync
- files were modified by this hook

and git status fills with ~68 phantom src/content/docs/** entries staged at the repo root (AD — present in the index, absent on disk), e.g.:

AD src/content/docs/architecture/Api-contract.md
AD src/content/docs/index.md
AD src/content/docs/using/Jira-setup-guide.md
... (~68 total)

The real Starlight mirror under docs/src/content/docs/ is regenerated correctly — only these root-relative phantom paths are spurious, and they block the commit.

Expected behavior

Committing an edit to a file matching the hook's files: pattern (docs/(design|guides)/*.md or CONTRIBUTING.md) from a worktree regenerates the mirror, stages only the real docs/src/content/docs/** files, and the hook passes.

Current behavior

  • Reproduces only on a real git commit from a worktree — not via prek run docs-sync ... (which passes cleanly). This points at prek's commit-time behavior (it stashes unstaged changes during the run), not the sync script itself.
  • The hook entry is:
    entry: bash -lc 'cd "$(git rev-parse --show-toplevel)/docs" && node scripts/sync-starlight.mjs && git add src/content/docs/'
    In a worktree, git rev-parse --show-toplevel correctly returns the worktree root, and sync-starlight.mjs resolves its output to docs/src/content/docs/ correctly. Running the entry line manually stages the right path. Yet under a real commit, ~68 root-relative src/content/docs/** paths end up AD in the index.
  • Workaround: git reset, explicitly stage the intended files, and commit with --no-verify (after verifying the mirror out-of-band with mise //docs:sync).

Reproduction steps

  1. git worktree add .worktrees/docs-fix -b docs/test origin/main
  2. cd .worktrees/docs-fix && mise run install
  3. Append a line to docs/guides/LINEAR_SETUP_GUIDE.md and git add it.
  4. git commit -m "docs: test" (run through mise exec -- so the astro check hook gets Node 22 — see the related Node-version issue).
  5. Observe: docs-sync reports Failed — "files were modified by this hook", and git status shows ~68 phantom AD src/content/docs/** entries at the repo root while the real mirror under docs/src/content/docs/ is correct.

Note: prek run docs-sync --files docs/guides/LINEAR_SETUP_GUIDE.md does not reproduce it — the failure is specific to the full commit path.

Possible solution

Not root-caused with confidence; the trigger is the commit-time path (prek stash + the hook's git add), not the sync script. Candidate directions to investigate:

  • Make the hook's git add target explicit and worktree/cwd-independent so it cannot resolve against an unexpected root during prek's stash/restore, e.g. git -C "$(git rev-parse --show-toplevel)" add docs/src/content/docs/.
  • Confirm whether prek's partial-stash step interacts badly with a hook that both writes files and stages them, in a worktree specifically.

Node version

22.23.1 (via mise)

mise version

2026.7.13

Local modifications

Discovered while committing an unrelated CLI fix from a worktree at .worktrees/. No changes to the hook itself; the symptom is independent of the committed content.

Additional context

AGENTS.md requires all feature work in a worktree under .worktrees/<branch>/, so this affects the mandated workflow for any change touching docs/guides/, docs/design/, or CONTRIBUTING.md. Related issue: astro check hook fails under bare Node v20 unless the commit runs through mise exec (filed separately).

Activity

  1. krokoko commented on Nov 20, 2026

    @krokoko
    Contributor

    Triage: this looks resolved on main.

    Fixed by #1052 (merged 2026-11-19 as bf52b90; commit 542424b of that pull request): the docs-sync hook now runs mise //docs:sync from the top of the working tree and stages docs/src/content/docs/ (.pre-commit-config.yaml:76), where it used to change into docs/ and stage src/content/docs/. The cause was not prek's stash: git exports GIT_DIR to hooks in a linked worktree, and with it set a git command run from docs/ takes docs/ as the top of the work tree, so the old git add recorded the mirror files under root-relative paths. Checked on main (3dbfada) in a scratch clone with a linked worktree, by running prek's commit-time entry point with the variables git gives a pre-commit hook: the old command gives "files were modified by this hook" and 79 AD src/content/docs/** entries, the command on main passes and stages only the edited guide and its mirror page, also in a worktree under .worktrees/ and with unstaged changes in the tree. No test pins this yet (cdk/test/scripts/git-hooks.test.ts checks other properties of the hook commands), and no issue tracks adding one.

    Posted from an automated sweep of the open issues. Each pull request, commit and file named above was checked against main at 3dbfada1. The issue is left open for a maintainer to close.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    v1Version 1

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions