home / skills / lambda-curry / devagent / worktree-setup-hook

worktree-setup-hook skill

safe

This skill automates worktree setup by detecting new worktrees and configuring env files, dependencies, and setup scripts.

npx playbooks add skill lambda-curry/devagent --skill worktree-setup-hook

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

2.2 KB

---
name: worktree-setup-hook
description: "Post-checkout git hook for automatic worktree setup. Use when: (1) Setting up automatic configuration for new git worktrees, (2) Creating post-checkout hooks that detect new worktrees and run setup tasks, (3) Configuring worktrees to automatically copy env files and install dependencies"
---

# Worktree Setup Hook

Provides a post-checkout git hook template that automatically configures new git worktrees by detecting new worktree creation and running setup tasks.

## Overview

The hook detects when a new worktree is created (not a regular checkout) and automatically:
- Copies environment files (.env, .env.local, etc.)
- Detects the project's package manager and installs dependencies
- Runs setup scripts if available

## Quick Start

Install the hook template:

```bash
cp .cursor/skills/worktree-setup-hook/assets/hook-templates/post-checkout .git/hooks/post-checkout
chmod +x .git/hooks/post-checkout
```

The hook will automatically run after `git worktree add` completes.

## How It Works

### Worktree Detection

The hook detects new worktrees by checking if the previous HEAD is the null-ref (`0000000000000000000000000000000000000000`). This is how git indicates a new worktree creation.

### Setup Tasks

1. **Environment Files**: Copies `.env.example` to `.env`, `.env.local.example` to `.env.local`, or copies env files from the main worktree
2. **Package Manager Detection**: Automatically detects and installs dependencies:
   - `package.json` → npm or yarn
   - `requirements.txt` → pip
   - `Cargo.toml` → cargo
   - `go.mod` → go
   - `Gemfile` → bundle
3. **Setup Scripts**: Runs `setup.sh` or `scripts/setup.sh` if present and executable

## Installation

See [setup-guide.md](references/setup-guide.md) for detailed installation instructions, including:
- Step-by-step installation
- Handling existing hooks
- Backup procedures
- Troubleshooting

## Customization

The hook is a standard POSIX shell script. Edit `.git/hooks/post-checkout` to add custom setup steps or modify behavior.

## Resources

- **Hook Template**: `assets/hook-templates/post-checkout` - The main hook script
- **Setup Guide**: `references/setup-guide.md` - Detailed installation and configuration instructions

Overview

This skill provides a post-checkout git hook that automatically configures newly created git worktrees. It detects worktree creation and runs a series of setup tasks so new worktrees are ready to use without manual steps. The hook is a POSIX shell script you can install into .git/hooks/post-checkout and customize to fit your project.

How this skill works

The hook checks whether the previous HEAD is the null ref (0000000000000000000000000000000000000000) to detect new worktrees. When a new worktree is detected it copies environment files, detects the project package manager to install dependencies, and runs optional setup scripts if present and executable. All steps are configurable by editing the hook script.

When to use it

When adding new git worktrees and you want automatic environment setup
When you maintain teammates who need consistent worktree bootstrapping
When you want to copy env files (.env, .env.local) into new worktrees automatically
When you need dependencies installed automatically for language-specific projects
When you want to run project-specific setup scripts on worktree creation

Best practices

Install the hook into .git/hooks/post-checkout and make it executable (chmod +x).
Keep the hook POSIX-compatible and small; delegate heavy tasks to project scripts (e.g., scripts/setup.sh).
Provide example env files (like .env.example) and fallback behavior if none exist.
Detect package managers conservatively and avoid destructive commands; prefer install-only operations.
Add logging or a dry-run flag to troubleshoot installation steps without side effects.

Example use cases

Automatically copy .env.example to .env when a new worktree is created so local configuration is immediate.
Detect package.json and run npm/yarn install in the new worktree to prepare JS projects for development.
Run scripts/setup.sh to initialize language tools, linters, or code generators right after git worktree add.
For polyglot repos, detect requirements.txt, go.mod, Cargo.toml, or Gemfile and run the appropriate installer for each language.
Provide consistent on‑boarding for contributors who use worktrees to review feature branches.

FAQ

Will this run on every checkout or only on worktree creation?

It detects new worktrees by checking for the null previous HEAD and only runs full setup when a worktree is created; normal branch checkouts are ignored by default.

How do I customize the setup steps?

Edit the post-checkout hook script to add or remove steps. Best practice is to call project-level scripts (e.g., scripts/setup.sh) from the hook rather than embedding complex logic inline.

What package managers are detected?

The hook recognizes common indicators and runs the matching installer: package.json (npm/yarn), requirements.txt (pip), Cargo.toml (cargo), go.mod (go), and Gemfile (bundle).