worktree-setup

Create idempotent symlinks for env and secret files in new git worktrees.

2|1|Updated Mar 26, 2026

Search Tags:#automation #git #worktree #setup #secrets #env #symlinks

Ready to run

npx skills add https://github.com/TeamSPWK/nova --skill worktree-setup-teamspwk

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: worktree-setup
Source: https://github.com/TeamSPWK/nova/tree/main/.claude/skills/worktree-setup
Command: npx skills add https://github.com/TeamSPWK/nova --skill worktree-setup-teamspwk

SYSTEM DOCUMENTATION & REQUIREMENTS

git worktree에서 메인 레포의 환경 설정이 필요할 때. — MUST TRIGGER: 새 worktree 진입 직후, 사용자가 '환경변수 안 읽힘·시크릿 못 찾음'을 보고할 때, EnterWorktree 도구 호출 직후. Use when the main repo's environment setup is needed inside a git worktree. — MUST TRIGGER: right after entering a new worktree, when the user reports 'env vars not read' or 'secrets not found', or right after the EnterWorktree tool is called.

What problem does it solve?

git worktree는 기본적으로 .env, .secret/, .npmrc 등과 같은 파일들을 새 작업 디렉토리로 자동 복사하지 않으므로 환경변수와 시크릿이 사라집니다. 이 스킬은 메인 레포의 환경 구성을 worktree에서도 동일하게 사용할 수 있도록 심볼릭 링크를 통해 격차를 해소합니다.

Core Features & Use Cases

Automatic environment parity: SessionStart 훅으로 worktree 진입 시 자동으로 환경 파일을 연결합니다.
Robust linking: .env, .env.local, .env.development, .secret, .npmrc를 worktree 루트로 심볼릭 링크합니다.
Safety & overrides: 기존 파일을 덮어쓰지 않고, 깨진 심링크를 감지하며 .claude/worktree-sync.json으로 프로젝트 별 오버라이드를 지원합니다.
Triggers & UX: 자동 트리거( SessionStart ) 및 수동 트리거(/nova:worktree-setup)를 모두 지원합니다.

Quick Start

Enter a new worktree to automatically symlink the main repo's env files and secrets into the worktree.

Frequently Asked Questions about worktree-setup

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

Why are environment variables and secrets missing after switching to a new git worktree?▼

Git worktree does not automatically copy hidden files like .env or .secret into the new working directory, causing environment variables to disappear when entering a new git worktree. Symlinking the main repo files restores them.

How do I automatically sync .env and secret files into a new git worktree?▼

You can sync .env and secret files by creating safe symlinks from the main repository to the worktree root, triggered automatically via SessionStart or manually to link .env, .env.local, and .npmrc configurations.

Does worktree environment setup overwrite existing .env files in the new directory?▼

No, safe linking ensures the worktree environment setup never overwrites existing files. It creates idempotent symlinks for your environment variables and detects broken symlinks without destroying local configurations.

Can I customize which secret files are linked in my git worktree?▼

Yes, you can customize linked secret files by creating a .claude/worktree-sync.json file to apply project-specific overrides for environment parity, specifying exactly which configurations to link into the worktree.

What is the best way to fix broken symlinks for environment files in git worktrees?▼

The best way to fix broken symlinks is to run an idempotent linking setup that detects broken symlinks and safely relinks the main repository's .env and secret files into the worktree with clear failure signaling.