# Worktree

> Create git worktree with automatic sync of gitignored files (configs, .env, IDE settings). Use when setting up parallel development environments or working on multiple branches simultaneously. Use when this capability is needed.

- Skill: `tomevault-io/worktree-7` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/worktree-7`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/worktree-7/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/worktree-7

---


# Git Worktree with Gitignored Files Sync

Create a git worktree and automatically copy important gitignored files (configs, .env, IDE settings) while excluding heavy dependencies like node_modules.

## Platform Support

This skill works on **macOS**, **Linux**, and **Windows** using a single Python script.

**Requirements:** Python 3.7+ (pre-installed on macOS and most Linux distributions)

## Usage

### All Platforms (Universal)

```bash
python3 .codex/skills/worktree/scripts/worktree.py $ARGUMENTS
```

Or on Windows:

```powershell
python .codex/skills/worktree/scripts/worktree.py $ARGUMENTS
```

## Execution Requirements

**IMPORTANT: Set bash timeout to 300000ms (5 minutes) when running this script.**

In large repositories the file scanning and copying phase may take several minutes. The default agent timeout (60-180 seconds) is often insufficient. When invoking the script via Bash tool, always specify `timeout: 300000`.

## What This Skill Does

1. **Validates** the current directory is a git repository
2. **Generates** default path and branch if not specified
3. **Creates** a new git worktree at the specified path
4. **Finds** gitignored files using `git ls-files` for accurate matching
5. **Copies** important config files while excluding heavy directories
6. **Reports** what was copied and provides next steps

## Copied Files (from .gitignore)

The script copies gitignored files that are typically needed for local development:
- `.env`, `.env.local`, `.env.development`, etc.
- `.claude/settings.local.json`
- Local config files (`config/local.*`, `*.local.*`)
- IDE local settings

## Excluded (Never Copied)

Heavy directories are always excluded:
- `node_modules/`
- `.venv/`, `venv/`
- `__pycache__/`
- `dist/`, `build/`
- `.cache/`, `.pytest_cache/`, `.mypy_cache/`
- `.next/`, `.nuxt/`
- `vendor/`, `target/`
- Files larger than 10MB

## Arguments

- `worktree-path` (optional): Path where the worktree will be created
  - Default: `../worktrees/<repo-name>-<unix-timestamp>`
- `branch` (optional): Branch name
  - Default: `ai-worktree/<random-car-brand>-<unix-timestamp>`
  - Creates new branch if doesn't exist

## Examples

```bash
# Auto-generate both path and branch (simplest usage)
/worktree
# Creates: ../worktrees/my-project-1738680000
# Branch: ai-worktree/ferrari-1738680000

# Specify path only, auto-generate branch
/worktree ../my-feature
# Creates: ../my-feature
# Branch: ai-worktree/toyota-1738680000

# Specify both path and branch
/worktree ../my-repo-feature feature/new-auth

# Absolute path with specific branch
/worktree /tmp/worktree-test develop
```

## Output Example

```
Source repository: /Users/dev/my-project
Branch: feature/auth
Worktree path: /Users/dev/my-project-feature

Creating git worktree...
Worktree created successfully

Scanning gitignored files...
Copying gitignored files...
  + .env (234 B)
  + .env.local (128 B)
  + .claude/settings.local.json (1 KB)

========================================
Git Worktree Created Successfully
========================================

Worktree Details:
  Path:   /Users/dev/my-project-feature
  Branch: feature/auth
  Source: /Users/dev/my-project

Copied Files:
  Total: 3 files, 1 KB

Excluded (heavy directories):
  - node_modules/ (skipped)
  - .venv/ (skipped)

Next Steps:
  1. cd /Users/dev/my-project-feature
  2. Install dependencies if needed
  3. Start working on your changes
```

## Error Handling

| Situation | Behavior |
|-----------|----------|
| Not a git repository | Error message, exit |
| Path already exists | Error with suggestion for alternative path |
| Branch doesn't exist | Automatically creates new branch |
| No .gitignore | Creates worktree without file sync |
| File copy fails | Warning, continues with other files |
| File > 10MB | Skipped with warning |

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/rouksonix) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->