home / skills / vadimcomanescu / codex-skills / using-git-worktrees

using-git-worktrees skill

safe

/skills/.experimental/devtools/using-git-worktrees

This skill helps you start isolated feature work by creating git worktrees with safe paths, baseline checks, and clean status verification.

npx playbooks add skill vadimcomanescu/codex-skills --skill using-git-worktrees

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

Files (3)

SKILL.md

768 B

---
name: using-git-worktrees
description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans. Create isolated git worktrees with safe directory selection and baseline verification.
---

# Using Git Worktrees

Create isolated workspaces without disrupting the main working tree.

## Quick Start
1) Choose a worktree root (prefer `.worktrees/` if present).
2) Ensure the worktree path is ignored by git.
3) Create the worktree for the target branch.
4) Run project setup and verify clean status.

## Guardrails
- Don’t create worktrees in unignored paths.
- Keep one branch per worktree.
- Verify `git status` is clean before starting work.

## References
- Extended examples: `references/examples.md`

Overview

This skill helps you create isolated git worktrees for feature development or experimental changes without disrupting your main working tree. It guides safe directory selection, ensures the worktree path is ignored by git, and verifies the baseline repository state before you start. Use it to reduce context-switch risk and keep one branch per worktree for clear isolation.

How this skill works

The skill inspects your repository for a recommended worktree root (preferably a .worktrees/ directory) and confirms the target branch and path are valid and ignored by git. It creates the worktree for the specified branch, runs basic project setup steps, and checks that git status is clean so you start from a known baseline. It also enforces guardrails like preventing worktrees in unignored paths and ensuring one branch per worktree.

When to use it

Starting a new feature that must not affect your current workspace
Running experimental changes or refactors separate from main work
Preparing an isolated environment before executing an implementation plan
Creating short-lived branches for prototypes or bug reproductions
When you need a predictable, repeatable baseline for CI or local tests

Best practices

Prefer using a dedicated .worktrees/ directory at repo root for all worktrees
Ensure the chosen worktree path is listed in .gitignore before creation
Verify git status is clean on the source branch before creating a worktree
Use one branch per worktree to avoid accidental cross-branch edits
Run project setup (install deps, build artifacts) and a smoke test after creation

Example use cases

Spin up an isolated worktree to implement a risky refactor, keeping main workspace intact
Create a worktree to reproduce a bug on an older branch without modifying your current branch
Prepare a feature-specific environment to run end-to-end tests without committing temp files
Quickly prototype two alternative implementations in separate worktrees for A/B comparison

FAQ

What if .worktrees/ doesn't exist?

Choose another directory that is ignored by git, add it to .gitignore, or create .worktrees/ and use it consistently.

Can I use multiple branches in one worktree?

No. Keep one branch per worktree to prevent accidental mixing of changes across branches.