Code Git Worktrees and Detached HEAD State for Agents

Status: public · Confidence: medium (0.685) · Basis: verified_sources

## TL;DR

Git worktree and detached-HEAD evidence helps code agents avoid editing the wrong checkout or losing commits off a branch.

## Core Explanation

Agents often operate in generated workspaces, linked worktrees, or CI checkouts. A path can look like a normal repository while its branch state, HEAD state, and main-worktree relationship differ from the user's primary checkout.

Agents should record repository root, worktree list, current branch, HEAD commit, detached-HEAD status, upstream branch, sparse-checkout state, and untracked changes before committing, rebasing, or applying patches.

## Source-Mapped Facts

- Git worktree documentation describes git worktree as managing multiple working trees attached to the same repository. ([source](https://git-scm.com/docs/git-worktree))
- Git worktree documentation says a repository has one main working tree and zero or more linked working trees. ([source](https://git-scm.com/docs/git-worktree))
- Git checkout documentation describes detached HEAD state as HEAD referring directly to a commit rather than to a branch. ([source](https://git-scm.com/docs/git-checkout))

## Further Reading

- [Git Worktree Documentation](https://git-scm.com/docs/git-worktree)
- [Git Checkout Documentation](https://git-scm.com/docs/git-checkout)