# post-worktree-checkout-hooks

> Write post-worktree-checkout hooks for git worktrees. Use when creating hooks that run after worktree checkout, setting up symlinks, installing dependencies, or automating environment setup in new worktrees.

- Author: quail
- Repository: cursedquail/worktree-utils
- Version: 20260126121348
- Stars: 5
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/cursedquail/worktree-utils
- Web: https://mule.run/skillshub/@@cursedquail/worktree-utils~post-worktree-checkout-hooks:20260126121348

---

---
name: post-worktree-checkout-hooks
description: Write post-worktree-checkout hooks for git worktrees. Use when creating hooks that run after worktree checkout, setting up symlinks, installing dependencies, or automating environment setup in new worktrees.
user-invocable: true
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
---

# Post-Worktree-Checkout Hooks

Write hooks that run automatically after a git worktree is created via `git-worktree-create` or `git-lightweight-worktree`.

## Hook Location

The hook file must be at:
```
<main-worktree>/.git/hooks/post-worktree-checkout
```

The hook is sourced (not executed) in bash, so it inherits the runner's environment.

## Available Environment

When the hook runs, the following are available:

| Variable/Function | Description |
|-------------------|-------------|
| `$WORKTREE_DIR` | Absolute path to the new worktree |
| `$MAIN_DIR` | Absolute path to the main worktree |
| `$PWD` | Set to `$WORKTREE_DIR` (current directory) |
| `symlink_file <filename>` | Helper to symlink a file from main to worktree |

## Hook Template

```bash
#!/usr/bin/env bash
# Post-worktree-checkout hook
# Runs after worktree creation; sources in bash with WORKTREE_DIR and MAIN_DIR set

set -euo pipefail

echo "Setting up worktree at $WORKTREE_DIR..."

# Symlink shared config files from main worktree
symlink_file ".env"
symlink_file ".env.local"

# Install dependencies
if [[ -f package.json ]]; then
  echo "Installing npm dependencies..."
  npm install
fi

echo "Worktree setup complete!"
```

## The `symlink_file` Function

Creates a symlink from `$MAIN_DIR/<filename>` to `$WORKTREE_DIR/<filename>`:

- If the source file doesn't exist in main, prints a warning and returns 1
- If target already exists as a symlink pointing to the right place, does nothing
- If target exists as a symlink pointing elsewhere, replaces it
- If target exists as a regular file, prints a warning and skips (returns 1)

### Usage Examples

```bash
# Symlink environment files
symlink_file ".env"
symlink_file ".env.local"
symlink_file ".env.development"

# Symlink IDE config
symlink_file ".idea"
symlink_file ".vscode/settings.json"

# Symlink credentials (not in git)
symlink_file "credentials.json"
symlink_file ".npmrc"
```

## Common Patterns

### Node.js Project

```bash
#!/usr/bin/env bash
set -euo pipefail

# Symlink environment
symlink_file ".env"
symlink_file ".env.local"

# Install dependencies
npm install

# Build if needed
if [[ -f tsconfig.json ]]; then
  npm run build
fi
```

### Python Project

```bash
#!/usr/bin/env bash
set -euo pipefail

# Symlink environment
symlink_file ".env"

# Create virtual environment if it doesn't exist
if [[ ! -d .venv ]]; then
  python3 -m venv .venv
fi

# Activate and install
source .venv/bin/activate
pip install -e ".[dev]"
```

### Go Project

```bash
#!/usr/bin/env bash
set -euo pipefail

# Symlink local config
symlink_file ".env"
symlink_file "config.local.yaml"

# Download dependencies
go mod download
```

### Monorepo with Multiple Services

```bash
#!/usr/bin/env bash
set -euo pipefail

# Symlink root-level config
symlink_file ".env"
symlink_file ".env.local"

# Install root dependencies
npm install

# Bootstrap services that need local setup
for service in api worker dashboard; do
  if [[ -d "services/$service" ]] && [[ -f "services/$service/package.json" ]]; then
    echo "Setting up $service..."
    (cd "services/$service" && npm install)
  fi
done
```

## Best Practices

1. **Always use `set -euo pipefail`** - Ensures the hook fails fast on errors
2. **Use `symlink_file` for shared configs** - Don't copy files; symlinks keep them in sync
3. **Print progress messages** - Output goes to stderr and is visible to the user
4. **Handle missing files gracefully** - Check if files exist before operating on them
5. **Keep it fast** - The hook blocks worktree creation; defer slow tasks if possible
6. **Don't modify the main worktree** - The hook should only set up the new worktree

## Debugging

If a hook fails, you can run it manually:

```bash
WORKTREE_DIR=/path/to/worktree MAIN_DIR=/path/to/main bash -x .git/hooks/post-worktree-checkout
```

The `-x` flag shows each command as it executes.

## Skipping the Hook

To create a worktree without running the hook:

```bash
git-worktree-create --skip-hook <branch>
```