using-git-worktrees

Overview

What is using-git-worktrees?

using-git-worktrees is a workflow skill from the obra/superpowers repository that guides you through creating isolated Git worktrees for feature development. It standardizes how and where worktrees are created, so you can safely work on multiple branches at once without constantly switching branches in a single working directory.

Instead of manually guessing where to place worktrees or risking untracked, unignored directories, this skill encodes a clear directory-selection and verification process. The goal is reliable isolation for implementation work while keeping your main project tree clean.

Who is this skill for?

This skill is designed for developers who:

• Work on several features or fixes in parallel
• Want a repeatable Git worktree convention across projects
• Need confidence that worktree directories are placed correctly and won’t pollute commits
• Use command-line Git and are comfortable running simple shell commands

It fits especially well in teams that want a documented, consistent Git workflow and a safer way to spin up temporary or long-lived feature environments.

What problems does using-git-worktrees solve?

using-git-worktrees helps you avoid common problems when working with multiple branches:

• Branch switching overhead: Work on multiple branches at the same time without constantly stashing and checking out.
• Messy project roots: Avoid scattering ad-hoc directories and worktree folders in random places.
• Accidental commits of worktree folders: The flow emphasizes verifying that local worktree directories are ignored before you create them.
• Inconsistent conventions across machines: By checking existing directories and optional preferences in CLAUDE.md, the skill nudges you toward a standard layout per project.

If you use Git worktrees regularly or want to start using them safely, this skill gives you a lightweight, opinionated procedure.

When is using-git-worktrees a good fit?

You should use using-git-worktrees when:

• You are about to start feature work that needs isolation from your current workspace.
• You are planning an implementation based on an existing design or plan and want a clean worktree to execute it.
• Your repository already uses .worktrees or worktrees directories and you want to keep following that convention.

It may be less useful if:

• You only ever work on a single branch at a time and do not need multiple working copies.
• You already have a strict, automated internal tool that manages worktrees in a different way.

In all other cases, adopting the using-git-worktrees flow can make your Git workflow more predictable and safer.

How to Use

Installation and setup

To add the using-git-worktrees skill to your environment, install it from the obra/superpowers repository:

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

After installation:

1. Open the skills/using-git-worktrees/SKILL.md file in the repository checkout.
2. Read it end-to-end once to understand the directory selection and safety-verification steps.
3. Make sure you are working inside a Git repository where you are comfortable creating additional worktree directories.

You do not need extra dependencies beyond Git and a shell that can run the commands shown in the skill description.

Core workflow: starting isolated feature work

When you begin new feature work and want an isolated workspace, follow the high-level flow encoded by using-git-worktrees:

1. Announce the workflow (for yourself and any assistants or tools):

   "I'm using the using-git-worktrees skill to set up an isolated workspace."

2. Determine the worktree directory using the directory-selection process (see the next section). This prevents scattering worktrees in arbitrary paths.

3. Run safety verification appropriate to the chosen directory type (project-local vs. global). This step is essential for avoiding accidental commits of worktree folders.

4. Create the Git worktree for the branch you need. For example:

   git worktree add <path-to-worktree> <branch-name>
   

5. Switch into the new worktree and perform your implementation work there, leaving your original working copy clean and available for code review, quick fixes, or other tasks.

Repeat this flow whenever you start a new feature, spike, or experiment that should not interfere with your current working directory.

Directory selection process

using-git-worktrees defines a structured directory-selection order so you always know where worktrees belong and you don’t have to re-decide each time.

1. Prefer existing worktree directories

From the root of your repository, check for preferred worktree directories in priority order:

ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

• If .worktrees exists, use it.
• If .worktrees does not exist but worktrees does, use worktrees.
• If neither exists, continue to the next step.

This rule makes your workflow consistent with previous choices in the same project.

2. Check CLAUDE.md for project preferences

If no standard worktree directory is present, look for a documented preference in CLAUDE.md at the project root:

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

If CLAUDE.md specifies a worktree directory convention, use that without asking further questions. This allows a project to centrally document its preferred worktree layout.

3. Ask and choose a new location when no preference exists

If there is no existing directory and no documented preference in CLAUDE.md, explicitly choose where new worktrees should live. The skill suggests offering yourself (or your team) a clear choice:

No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?

• Option 1: .worktrees/ keeps the worktrees alongside the project, hidden by default and easy to discover in the repo.
• Option 2: ~/.config/superpowers/worktrees/<project-name>/ centralizes worktrees per project outside the repo root, which can be useful if you want your Git working directory to stay visually minimal.

Once you pick an option, keep using that location for the same project to avoid fragmentation.

Safety verification before creating a worktree

The using-git-worktrees skill emphasizes safety checks, especially when using project-local directories that live inside the Git repository.

Verifying project-local directories are ignored

For project-local directories like .worktrees or worktrees, verify they are ignored by Git before you create worktrees inside them. The skill calls this out as a MUST condition.

At a minimum, you should:

• Confirm that .worktrees or worktrees appears in a relevant ignore file (.gitignore, .git/info/exclude, or global ignore files), and
• Use git check-ignore to ensure Git truly ignores the directory in your current configuration.

A typical check pattern is to run git check-ignore against the directory path and confirm that Git treats it as ignored, respecting local, global, and system ignore settings.

If the directory is not ignored:

• Add it to an appropriate ignore file, commit the ignore rule if it belongs in the repository, and
• Re-run the check before creating any worktrees in that location.

This reduces the risk that your worktree infrastructure ends up staged or committed by accident.

Using global locations safely

If you choose the global directory option (for example, under ~/.config/superpowers/worktrees/), the directories live outside the repository and are not tracked by Git. In that case, the ignore requirement is less critical, but you should still make sure:

• The path is stable across machines (or documented for teammates).
• You have enough disk space for multiple full worktrees.

Consistently applying these verification steps keeps your Git history focused on source changes, not tooling artifacts.

Adapting the skill to your workflow

The using-git-worktrees skill is deliberately lightweight and repository-focused. To integrate it into your broader workflow:

• Document your final choice of worktree directory in your project’s contribution or onboarding docs.
• Consider adding a short section to CLAUDE.md describing how your team uses Git worktrees.
• Wrap the directory-selection and verification steps in your own shell scripts if you want a one-command setup, while keeping the original rules as the source of truth.

The skill is intended as a clear reference implementation that you can follow as-is or adapt carefully to match your environment.

FAQ

What is the main benefit of using-git-worktrees over normal Git checkouts?

using-git-worktrees makes it easy to work on multiple branches in parallel by creating additional working directories (worktrees) that share the same Git history. Instead of repeatedly checking out and stashing in a single directory, you keep each feature or fix in its own isolated workspace, guided by a consistent directory-selection and safety process.

How do I install the using-git-worktrees skill?

Install the skill from the obra/superpowers repository using:

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

After installation, open skills/using-git-worktrees/SKILL.md in your local checkout to follow the detailed workflow.

Do I need to change my existing Git workflow to use this skill?

You do not have to overhaul your entire workflow. using-git-worktrees is focused on how you start and manage isolated workspaces. You can continue committing, rebasing, and pushing as usual; the skill mainly standardizes where and how you create worktrees and ensures they are placed safely.

Can I use using-git-worktrees on any Git repository?

Yes, as long as the repository is compatible with Git worktrees in general. The skill relies on standard Git commands and shell utilities. For best results, run the directory checks from the repository root and follow the ignore recommendations for any project-local worktree directories.

What if my project already has a different worktree convention?

If your project already uses .worktrees, worktrees, or a convention documented in CLAUDE.md, using-git-worktrees will naturally pick up that preference through its directory-selection rules. If your convention is entirely different, you can still adapt the principles (clear directory choice and safety checks) while pointing them to your existing directory layout.

Is using-git-worktrees suitable for large or long-lived projects?

Yes. The skill is particularly useful for large projects where multiple long-running branches are common. Its structured directory selection and emphasis on ignore rules help keep your repository organized over time, even when you accumulate many worktrees for ongoing work.

When should I avoid using-git-worktrees?

You might not need this skill if you rarely work on more than one branch at a time, or if your team already uses another dedicated tool that manages worktrees and enforces its own directory conventions. In these cases, the additional structure from using-git-worktrees may not add enough value to justify changing your habits.

Where can I see the original definition of this skill?

The authoritative definition for using-git-worktrees lives in the SKILL.md file inside the skills/using-git-worktrees directory of the obra/superpowers repository on GitHub. Refer to that file for the most precise and up-to-date behavior description.