Git Worktree

Git Worktree

Choose a branch in the current checkout or an isolated workspace according to the task. Branch naming and creation follow [branches](references/branches.md); isolation, candidate identity, and cleanup follow the workflow below. A branch-only request needs no extra checkout.

Workflow

1. Record the source: inspect git status --short, git diff, git diff --cached, git rev-parse HEAD, and git worktree list --porcelain. Identify whether the candidate is a commit, the index, or selected working-tree changes.
2. Choose isolation: use a linked worktree for a committed revision or new branch. Use the [dirty candidate procedure](references/dirty-candidate.md) when validation must include uncommitted files, or when checks must not share Git refs or hooks with the source.
3. Create a fresh destination: choose a new sibling or temporary path outside the source. For a read-only review of committed code, use git worktree add --detach ; for implementation, use git worktree add -b .
4. Inspect execution inputs: read the destination's tasks and hooks before running them; isolate virtual environments, build output, coverage, ports, databases, and caches that tests mutate. Do not copy credentials or reuse a live database to make a fixture pass.
5. Run the owning gate: invoke the project's commands from the destination. Formatter output changes the tested candidate; compare it with the intended source before transferring proof or applying any resulting edits.
6. Return only intended changes: review the destination diff, transfer task-owned changes when authorized, and preserve the source index. Commits, pushes, and merges follow the user's requested delivery flow.
7. Clean up deliberately: inspect destination status and recover useful artifacts first. Use git worktree remove for an owned clean linked worktree; retain a dirty one until its changes are accounted for. Remove only the recorded disposable clone for a copied candidate.
8. Report identity: revision, included dirty changes, executed gate, source-versus-tested differences, and any retained workspace.

Gotchas

• A clean HEAD is a different candidate: a passing worktree does not validate uncommitted edits in the source.
• Shared Git state: linked worktrees have separate indexes but share objects, refs, and usually repository configuration and hooks. They are not a security sandbox; do not run untrusted code merely because it is in a worktree.
• No forced reuse: do not use force, stash, reset, or broad clean commands to make a busy branch or dirty destination available.
• External symlinks: inspect and replace writable links into the source with safe fixture data or stop that test; a copied symlink can defeat isolation.

Documentation

• Git worktree · Git clone
• Companion skills: [mise](../mise/SKILL.md) (gates), [resolve-conflicts](../resolve-conflicts/SKILL.md) (integration conflicts).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fmind
• Source: fmind/dot
• License: MIT
• Homepage: https://fmind.dev

Install and usage instructions live in the source repository linked above.