git-worktree-setup

k8zdev's avatarfrom k8zdev

Automate git worktree creation and copy private files (not tracked in git) to new workdirs. Use when creating a new git worktree for this Flutter project that requires untracked private files like secrets.dart, Firebase configs, etc.

⭐139stars🔀5forks📁View on GitHub🕐Updated Jan 3, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill automates the creation of Git worktrees and ensures that essential untracked private files—such as API keys, secrets, and Firebase configurations—are seamlessly synchronized to new workspaces. It streamlines the developer workflow by eliminating manual file copying and reducing configuration errors during multi-branch development, making it an essential utility for complex software projects.

Use Cases

  • 1. Multi-branch Development: Quickly switch between feature branches or hotfixes without manually re-configuring environment-specific files like secrets.dart or .env files.
  • 2. Flutter & Mobile App Setup: Automate the distribution of platform-specific configuration files (e.g., google-services.json, Firebase configs) across multiple Git worktrees to maintain build readiness.
  • 3. Environment Standardization: Use a centralized manifest to ensure all local development environments have the exact same set of required private files, minimizing 'it works on my machine' issues caused by missing local configs.
namegit-worktree-setup
descriptionAutomate git worktree creation and copy private files (not tracked in git) to new workdirs. Use when creating a new git worktree for this Flutter project that requires untracked private files like secrets.dart, Firebase configs, etc.

Git Worktree Setup

Overview

Automates the creation of git worktrees and copies untracked private files to the new work directory. This skill handles the setup process for worktrees that require development-only files not committed to git (e.g., API keys, Firebase configs).

Quick Start

Create a new worktree with private files copied:

scripts/setup_worktree.sh <worktree-name> [branch-name]

Or copy private files to an existing worktree:

scripts/setup_worktree.sh <existing-worktree-name>

Example:

# Create worktree for "feature-auth" branch
scripts/setup_worktree.sh feature-auth feature/auth

# Create worktree using main branch (default)
scripts/setup_worktree.sh hotfix-123

# Copy private files to an existing worktree
scripts/setup_worktree.sh feature-auth

The script:

  1. Creates the worktree in worktree/<worktree-name> directory (if it doesn't exist)
  2. Copies all files listed in references/manifest.md from the main repo (always runs)

Managing Private Files

Adding New Files

Edit references/manifest.md and add file paths relative to the repo root:

- lib/common/secrets.dart
- ios/firebase_app_id_file.json
- macos/firebase_app_id_file.json
- android/app/google-services.json

File Requirements

  • All paths must be relative to the git repository root
  • Target directories are created automatically if needed
  • Missing source files are skipped with a warning (no error)

Worktree Management

Working in a Worktree

cd worktree/<worktree-name>
# Make changes, commits, etc.

Removing a Worktree

git worktree remove worktree/<worktree-name>

List All Worktrees

git worktree list

Syncing Private Files to Existing Worktree

If you've updated private files in the main repo and want to sync them to an existing worktree:

scripts/setup_worktree.sh <existing-worktree-name>

The script will detect the existing worktree and skip the creation step, only copying the files from references/manifest.md. This is useful when:

  • You've added new private files to the manifest
  • You've updated file contents in the main repo
  • You want to refresh private files in multiple worktrees

Script Behavior

The setup_worktree.sh script automatically:

  • Validates git repository context
  • Creates the worktree directory structure (if needed)
  • Detects existing worktrees and skips creation
  • Copies private files using the manifest
  • Provides colored output for status/warnings/errors

Troubleshooting

Directory exists but is not a git worktree

ERROR: Directory exists but is not a git worktree: worktree/<name>

Remove the directory with rm -rf worktree/<name> or create a proper git worktree manually

Syncing to existing worktree fails

ERROR: Not in a git repository

Make sure you're running the script from within the main git repository

Source file not found

WARN: Source file not found: lib/common/secrets.dart, skipping...

The file is missing from your main repo; add it or remove from manifest

Resources

scripts/setup_worktree.sh

Executable shell script that creates git worktrees and copies private files. Execute directly without loading into context.

references/manifest.md

Configuration file listing all private files to copy. Read this file to add or remove files that should be copied to new worktrees.