managing-git-worktrees

name	managing-git-worktrees
description	Deprecated internal reference for creating, inspecting, attaching, repairing, removing, or pruning local Git worktrees while preserving branches, commits, files, and submodule data.
metadata	{"internal":true}

Managing Git Worktrees (Deprecated Reference)

This workflow is excluded from active discovery but retained for repository reference and explicit local compatibility. Inspect before mutation. Keep worktree operations separate from commits, pushes, rebases, and unrelated branch changes. Treat dynamic refs and paths as untrusted: validate them, pass them as argv when possible, and quote shell values.

Inspect

1. Capture the invoking worktree, symbolic branch, and HEAD. A detached invoking HEAD requires an explicit creation start point.
2. Parse git worktree list --porcelain -z; the first record identifies the main worktree. If it is bare or stale, request a storage root or repair it before deriving paths.
3. Resolve the requested branch, path, and start point. Never assume the default branch name.

For a new path, default the storage root to $HOME/.worktrees; if $HOME is unset or unusable, request an explicit root. Create the root if absent, then use <root>/<main-name>-<branch-with-slashes-replaced-by-hyphens>. Stop on an existing path or normalization collision rather than inventing a suffix.

Create or Attach

1. Normalize the branch with git check-ref-format --branch "$branch" and resolve the start point to one commit with git rev-parse --verify --end-of-options "${start_point}^{commit}".
2. Determine exact branch existence with git show-ref --verify and occupancy from porcelain records; do not substring-match.