worktrees

Create and manage git worktrees with predictable paths and safety checks.

3|Updated Jul 17, 2024

Search Tags:#git #workflow #isolation #safety #branching #worktree

Ready to run

npx skills add https://github.com/Castrozan/.dotfiles --skill worktrees-castrozan

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: worktrees
Source: https://github.com/Castrozan/.dotfiles/tree/main/agents/skills/worktrees
Command: npx skills add https://github.com/Castrozan/.dotfiles --skill worktrees-castrozan

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill helps developers isolate feature work by creating and managing git worktrees to keep the main branch clean.

Core Features & Use Cases

Create isolated worktrees with predictable paths like .worktree/<branch>.
Enforce safe directory layouts and prevent nested directories that could cause data loss.
Real-world use: Start a new feature branch in a dedicated worktree while the main repo remains stable.

Quick Start

Ensure you are in the project root. Update the main branch with: git fetch origin && git checkout main && git pull.
Create a new worktree (for general repos): git worktree add .worktree/<branch> -b <branch>.
For the dotfiles repo, use the provided helper: ./bin/git-worktree-crypt <branch> (creates at .worktrees/<branch> and uses git-crypt).
After finishing, run /rebuild to test changes and open a PR using your preferred tool (gh pr create or glab pr create) from the main repo directory.

Frequently Asked Questions about worktrees

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I create an isolated git worktree for a new feature branch?▼

Git worktrees let you isolate feature work by creating separate working directories from a single repository. This keeps your main branch clean while providing predictable paths like .worktree/<branch> for experiments without switching branches in place.

What's the best way to keep my main branch clean when starting new feature work?▼

Using git worktrees is the best way to keep your main branch clean. They enforce safe directory layouts, prevent nested directories that could cause data loss, and provide isolated workspaces with predictable paths for new features.

Can I use git worktrees with encrypted dotfiles repositories?▼

Yes, for dotfiles repositories you can use the provided helper ./bin/git-worktree-crypt <branch>. It creates worktrees at .worktrees/<branch> and integrates git-crypt to handle encrypted files within the isolated workspace.

What steps should I take after finishing work in a git worktree?▼

After finishing work in a git worktree, run a rebuild to test changes, then open a pull request using gh pr create or glab pr create from the main repository directory to merge your isolated feature branch.

Why should I avoid creating nested directories when setting up git worktrees?▼

You should avoid nested directories in git worktrees to prevent potential data loss. Enforcing safe directory layouts and using predictable paths like .worktree/<branch> ensures your isolated workspaces remain stable and recoverable.