Git Worktree

git-worktree

This skill provides tools for creating and managing Git worktrees, handling both the setup of a clean environment and synchronization of relevant files (including gitignored or untracked files). The main entrypoint is the Python script scripts/create_git_worktree.py.

Key Features

• Create a new git worktree, or initialize a worktree at a target location
• Generate or customize branch names from task prompts
• Copy over selected git-ignored files and directories (e.g., node_modules, .env, .venv, vendor, etc.)
• Create symbolic links for local settings (e.g., .claude/settings.local.json)
• Optionally copy staged, modified, or untracked files into the new worktree
• Copy a plan/description file into the worktree for agent-based workflows
• Change the worktree directory owner (if needed, e.g., for VSCode agents)
• Run environment-specific checks to verify the new worktree's integrity (git, go, npm, etc.)

Requirements

• Python 3.x
• git CLI
• sudo/root access for chown (if using --agent-user)

Usage

python3 scripts/create_git_worktree.py [prompt words ...] [--branch BRANCH | --worktree WORKTREE_DIR] [--agent-user USER] [--no-copy-staged] [--copy-modified] [--copy-untracked] [--worktree-parent-dir DIR] [--verbose]

Main Arguments

• prompt (positional, optional): Task description (used to generate branch name, and perform verification checks e.g., "fix login bug in auth module").

Named Arguments (optional)

• --branch: Branch name for new worktree (overrides prompt-based naming)
• --base-branch: Base branch to create the new worktree from (local or remote). If not specified, worktree is created from current HEAD. Examples: develop, origin/main, release-1.0
• --worktree: Use an existing worktree directory path instead of creating a new one
• --agent-user: The OS user to set as owner of new worktree dir (for agent that run with a separate OS user)
• --no-copy-staged: Prevents copying staged files into the new worktree (default = copy staged files)
• --copy-modified: Also copy modified-but-not-staged files
• --copy-untracked: Also copy untracked files
• --worktree-parent-dir: The parent dir in which to place the new worktree dir
• --verbose, -v: Enable debug/verbose logging

Example Usages

# Create a new worktree with a branch name based on the prompt
python3 scripts/create_git_worktree.py feature add user auth --agent-user vscode --copy-untracked

# Create with explicit branch and copy all types of files
python3 scripts/create_git_worktree.py --branch feat/apply-fixes --copy-modified --copy-untracked

# Create worktree from a different base branch
python3 scripts/create_git_worktree.py implement new API --branch feature/new-api --base-branch develop

# Create worktree from remote branch
python3 scripts/create_git_worktree.py hotfix critical bug --branch hotfix/security-patch --base-branch origin/release-1.0

# Use an existing worktree dir created earlier
python3 scripts/create_git_worktree.py "apply patch" --worktree /workspaces/worktree-agent-no1

Troubleshooting

• If failed to create git worktree, try to invoke the script again with different arguments based on the error message you see.
• Do not attempt more than 3 times; if it still fails after 3 attempts, STOP and ask the user to create git worktree manually. (use AskUserQuestion tool)

Worktree Verification

• Always verify the new worktree exist by run git worktree list to ensure the worktree is actually created (regardless of whether the script output say success or not)
• Run git status inside the new worktree to check for active branch is correctly set to [branch_name].

Additional Verification

• Verify worktree is setup properly by run the following bash command in the worktree directory based on the tech-stack of the current project:
  • go mod verify if this is a Go project to ensure all dependencies are downloaded and valid.
  • go work sync if this Go project is setup as a Go workspace with go.work file.
  • npm list if this is a Node.js project to ensure all dependencies are installed.
  • pnpm dedupe --check if this this Node.js project is using pnpm
  • python -m pip freeze -r requirements.txt if this is a Python project contain a requirements file.
  • uv tree if this Python project is using uv

Notes

• The new worktree directory will be created in the parent directory specified by --worktree-parent-dir (default: cwd's parent directory) and have the name "worktree-agent-no1" (or "worktree-agent-no2" and so on to avoid directory name conflicts)
• The script materializes staged files and a known list of git-ignored files and directories (e.g., node_modules, .env, .venv, vendor, etc.) into the worktree to help fast setup the worktree for development.
• Dependency trees (node_modules, .venv, vendor) use the fastest available strategy, in order:
  1. clonefile(2) on macOS/APFS — clones the whole tree copy-on-write in one syscall; worktree edits never leak back to the main workspace.
  2. Per-package symlinks (e.g. Linux, where clone is unsupported) — each top-level package dir is symlinked to the main workspace (O(packages) instead of O(files)). Dot-entries like .bin and .pnpm are hard-linked instead, and .cache is skipped. Caveat: an in-place write inside a symlinked package (e.g. pip uninstall in .venv) reaches the main workspace — treat dep trees as read-mostly in the worktree.
  3. cp -al hard links, then a plain copy as final fallbacks.
• Shared tool caches (.pnpm-store, .ruff_cache, .mypy_cache) are symlinked to the main workspace.
• Symlinks are created for certain dev-local secrets/settings to avoid copying them into the worktree directory.
• Changing ownership requires appropriate system permissions.