Using Git Worktrees Safely

What it does

This workflow addresses accidental edits to the wrong checkout and duplicate worktrees invisible to a host application. It first compares Git directory and common-directory identity, with a separate submodule guard because submodules can resemble linked worktrees. If isolation already exists, it uses that workspace and records branch or detached-HEAD state. Otherwise it respects the user’s worktree preference and tries native management before a manual fallback. Project setup and a clean test baseline establish what was true before implementation.

When to use it

• Start an approved feature while protecting unrelated edits in the main checkout.
• Recognize a host-created detached worktree instead of creating another one inside it.
• Prepare a repeatable baseline for an implementation plan on a separate branch.

Step-by-step workflow

1. Inspect Git metadata and submodule context to identify the actual checkout type and branch state.
2. Reuse existing isolation; when absent, follow the user’s stated preference or ask before creating a worktree.
3. Use the platform’s managed worktree facility if available; use manual Git only as the documented fallback.
4. For a project-local fallback, verify the directory is ignored before creation, then run appropriate project setup.
5. Run the actual project tests, report baseline failures and confirm the workspace path before beginning feature edits.

Example request

Use using-git-worktrees to prepare the already authorized isolated workspace for our invoice export. First check whether the current checkout is a linked worktree or a submodule. Prefer the platform’s native worktree tool. Preserve uncommitted work and report the resulting absolute path, branch or detached state, plus the baseline test command. Do not install dependencies unless the project setup actually requires them.

Worked example

A Codex-managed checkout may have a detached HEAD and a different Git common directory. That is already isolated; adding .worktrees/export below it would duplicate isolation and confuse later cleanup. In a normal repository, a manually selected .worktrees directory must be ignored before creation. A failing baseline test must be reported as pre-existing rather than quietly attributed to the new feature after implementation. The worktree path should be explicit in subsequent commands.

What you get

A verified workspace location, recorded branch state and baseline test evidence, with existing isolation reused where possible.

How to evaluate the result

• The result is the intended repository and branch, with submodule state understood.
• No duplicate worktree was created when a managed isolated checkout already existed.
• Baseline tests and any failures are recorded before feature changes begin.

What you need

A Git repository, access to its metadata and sufficient permissions to create the requested checkout. Native management needs the host’s actual worktree tool.

Setup and activation

The publisher documents separate installation routes for Claude Code, Codex App and CLI, Cursor and other harnesses. Use the README for your exact client; installing the whole Superpowers framework can activate additional workflows automatically. Preserve this skill’s companion files and relative references. Review and security-scan the exact selected version before installation. This directory only reviews sources; it has not installed, executed or tested this skill on those clients.

Limits and considerations

A worktree shares repository history and does not automatically isolate external services, databases, credentials or ports. The source’s generic setup examples may install dependencies and therefore need project-specific review. Directory and branch choices must follow the actual instructions. Permission fallback should preserve work and disclose that implementation is continuing in place.

Related workflows

• Use executing-plans after the workspace and baseline are ready.
• Use finishing-a-development-branch for integration and ownership-aware cleanup.

License and reuse

MIT, copyright 2025 Jesse Vincent. Preserve the copyright and permission notice when redistributing substantial source portions; inspect separately supplied dependencies and assets under their own terms.

Further reading

• Reviewed skill version (immutable commit)
• Publisher setup, compatibility and telemetry notes
• Reviewed MIT license