worktree-bootstrap
Use immediately after `git worktree add` or `git gtr new` creates a fresh worktree for any repo (a web/Next app, a Node/TypeScript backend, a Python data/ETL project, an Android/Gradle app, or anything else) and it won't run or build because .gitignored env files and installed dependencies weren't carried over. Fire when the user says "set up the worktree", "the new worktree won't build/run", "missing .env in the worktree", "node_modules is missing", "gradle can't find the SDK / local.properties", or a dev server errors on missing env vars right after a worktree is created. Skip when the repo ships its own bootstrap skill: that one knows its extra credential files and hooks. Skip if the worktree has already run once.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- worktree-bootstrap
- description
- Use immediately after `git worktree add` or `git gtr new` creates a fresh worktree for any repo (a web/Next app, a Node/TypeScript backend, a Python data/ETL project, an Android/Gradle app, or anything else) and it won't run or build because .gitignored env files and installed dependencies weren't carried over. Fire when the user says "set up the worktree", "the new worktree won't build/run", "missing .env in the worktree", "node_modules is missing", "gradle can't find the SDK / local.properties", or a dev server errors on missing env vars right after a worktree is created. Skip when the repo ships its own bootstrap skill: that one knows its extra credential files and hooks. Skip if the worktree has already run once.
02 资源文件 1
- 参考文档README.md2.3 KB
03 SKILL.md 正文
Bootstrap a fresh worktree (generic)
A new worktree shares the repo's git history but is a separate working tree on disk. Two classes of thing do NOT come across, and both cause confusing first-run failures:
- .gitignored config:
.env,.env.local, service credentials, local settings. The app boots, then errors on a missing variable that "works on the other branch". - Installed dependencies and generated artifacts:
node_modules/, a Python.venv/, Prisma/codegen output. These are gitignored or per-tree, so a fresh worktree has none.
This skill copies the first from a donor worktree and rebuilds the second for
the detected stack, so the next dev/build/test works on the first try. It
covers what any repo needs; where a repo ships its own bootstrap skill, defer
to that instead. It will know the extra credential files, submodules and hooks
this one deliberately omits.
Procedure
1. Detect the stack
From the worktree root:
ls package.json pnpm-lock.yaml yarn.lock package-lock.json \
pyproject.toml poetry.lock requirements.txt go.mod \
settings.gradle settings.gradle.kts build.gradle gradlew 2>/dev/null
| Signal | Stack | Dep install | Common gitignored config |
|---|---|---|---|
pnpm-lock.yaml |
Node (pnpm) | pnpm install |
.env, .env.local, .env.*.local |
package-lock.json |
Node (npm) | npm ci |
.env, .env.local |
yarn.lock |
Node (yarn) | yarn install --immutable |
.env, .env.local |
poetry.lock |
Python (poetry) | poetry install |
.env |
requirements.txt / pyproject.toml |
Python (venv) | python -m venv .venv && .venv/bin/pip install -e . |
.env |
go.mod |
Go | go mod download |
.env, local config |
settings.gradle{,.kts} / gradlew |
Gradle / Android | none separate: Gradle resolves on first build | local.properties, keystore.properties, *.jks |
If nothing matches it is general, and the dep install is the part that cannot be guessed. Look for a manifest the repo's own tooling would recognise before giving up on it:
ls Gemfile Gemfile.lock Cargo.toml composer.json mix.exs pubspec.yaml \
Package.swift Makefile justfile 2>/dev/null
Where one turns up, take the install command from the repo's README or its CI
workflow rather than from memory, because it is often wrapped: bin/setup,
make deps, a just target. Where none turns up, copy the config in step 3,
skip the install, and say in the report that dependencies were not
installed. Step 6 otherwise fails on a missing dependency and reads as a
broken worktree rather than an uninstalled one, which is the harder bug to find
because nothing in the output mentions the install that never ran.
2. Find a donor worktree
Any existing worktree of the same repo has the machine-local config (it's per-machine, not per-branch):
SOURCE=$(git worktree list --porcelain \
| awk '/^worktree / {sub(/^worktree /, ""); print}' \
| grep -vxF "$(git rev-parse --show-toplevel)" \
| head -1)
echo "Donor: ${SOURCE:-<none. This is the only worktree>}"
If SOURCE is empty, ask the user where their primary checkout lives. Don't
fabricate config.
3. Copy the .gitignored config
Copy only the files git ignores (never tracked files). List what the donor actually has, then copy the env/config among them:
# --ignored is REQUIRED: the files to carry over are gitignored, so plain
# --exclude-standard (which HIDES ignored files) returns nothing.
git -C "$SOURCE" ls-files --others --ignored --exclude-standard \
| grep -E '(^|/)\.env($|\.)|\.env\.local|local\.settings|\.envrc|local\.properties|keystore\.properties|\.jks$' || true
Copy each match into the same relative path here (create parent dirs as
needed). Then confirm the files this stack needs are present: .env /
.env.local for a Node/Python app, local.properties (plus
keystore.properties if the app signs) for Android. If an expected file is
missing, the donor didn't have it either. Stop and ask, don't fabricate it.
4. Install dependencies (and submodules)
Run the command from the step-1 table for the detected stack. For Node, match
the lockfile's package manager exactly: using npm install where the repo uses
pnpm rewrites the lockfile and is a real bug. Gradle and general repos have
no separate install step (Gradle resolves on the first build).
If the repo has submodules, a fresh worktree does not populate them:
[ -f .gitmodules ] && git submodule update --init --recursive
5. Run codegen / prerequisites (only if the repo has them)
Check package.json scripts (or the Makefile / pyproject.toml) for a
postinstall, generate, prepare, codegen, or prisma generate step and
run it. Skip if none. Don't invent one.
6. Verify the worktree actually works
Run the cheapest command that exercises real config + deps, not just a lockfile check:
-
Node app: with the package manager step 1 detected (or, lacking a lockfile, the
packageManagerfield inpackage.json, else npm), run the first oftypecheck/buildthat actually exists underscripts(read it; a guessed script name fails as "missing script", not as a real verdict). If the change is runtime-facing, start the dev server bounded and never leave it running. Take the URL from the dev script's own output or the port in the project's config, never a guessed 3000: a probe against the wrong port fails the same way a broken server does.timeoutis GNU coreutils and a stock macOS does not have it, so the bound is the shell's:<pm> run dev & pid=$! ready= for _ in $(seq 1 30); do curl -sf --max-time 2 "$url" >/dev/null && { ready=1; break; } # --max-time, or one hung request outlasts the loop sleep 1 done kill "$pid" 2>/dev/null # started it, so stop it on both paths [ -n "$ready" ] || { echo "dev server never answered $url"; exit 1; } -
Python:
pytest -qorpython -m <package> --help. -
Android/Gradle:
./gradlew help -q, the cheapest full configure; it proveslocal.propertiesresolves. Then one task that actually compiles, read rather than guessed, because:appis a convention and a multi-module project may name no module that:./gradlew -q projects # the module paths that exist ./gradlew -q :<module>:tasks --all | grep -E '^assembleDebug( |$)'Take the module the change touches, or the smallest one that compiles where it touches none in particular. Listing is not by itself a choice: on one module a broader
^(assemble|compile).*Debugreturned 15 tasks, most of them test and source-set variants that prove nothing about the app building. -
General: the repo's documented smoke command.
A green install is not proof: the app booting and reading its env is. If it fails on a missing variable, step 3 missed a file; re-list the donor's ignored files.
When to STOP
- No donor worktree and no known primary checkout. The bootstrap needs a source for machine-local config; don't fabricate
.envvalues or invent secrets. - The donor's
.envcontains real secrets and the worktree is destined for a shared/remote location. Copying secrets into a shell others can read is a leak: confirm the destination first. - The lockfile's package manager differs from what's installed (e.g.
pnpm-lock.yamlbut nopnpm). Surface the missing tool; don't silently fall back tonpmand rewrite the lockfile. - The verify step fails for a reason that isn't missing config/deps (a real compile error on the branch). That's the branch's problem, not the worktree's: report it, don't paper over it.
- The repo ships its own bootstrap skill. Stop and use it. A repo-specific one also handles things this generic skill omits: extra credential files, submodule init, worktree-config trust prompts, and lint hooks that run on push.
Anti-patterns to avoid
- ❌ Committing
.env/ credentials "to fix the worktree permanently". They're gitignored because they're machine- or secret-specific: copy them, never track them. - ❌ Authoring
.envfrom memory. Copy it from a donor; a fabricated value that "looks right" fails silently later.