English for Git Worktrees

Switching branches with git checkout mid-task means stashing, losing your build cache, and re-installing dependencies — worktrees let you check out several branches into separate folders at once, and the vocabulary around them is worth having precise, because “just switch branches” and “add a worktree” solve genuinely different problems.

Key Vocabulary

Worktree — a separate working directory linked to the same Git repository, each checked out to its own branch, letting you have multiple branches checked out simultaneously without cloning the repo again. “I added a worktree for the hotfix so I could keep my feature branch’s build running in the other folder instead of stashing everything.”

Linked worktree — any worktree other than the original repository checkout, sharing the same .git object database but with its own working files and index. “The linked worktree lives in a sibling folder, but it still shares history and objects with the main checkout, so a fetch in either one updates both.”

Main worktree — the original repository directory created by git clone, distinguished from linked worktrees because it can’t be removed the same way and always exists as long as the repo does. “Don’t delete the main worktree’s folder directly — remove linked worktrees with git worktree remove instead, or the repo’s internal bookkeeping gets confused.”

Detached HEAD (in a worktree) — a worktree checked out to a specific commit rather than a branch tip, common for building or testing a specific commit without creating a new branch. “I checked out that commit into a new worktree in detached HEAD state, just to run the test suite against it without touching my branch.”

Prune — the cleanup step (git worktree prune) that removes stale worktree references left behind when a linked worktree’s folder was deleted manually instead of through git worktree remove. “Git still listed the worktree as active even after I deleted the folder by hand — running prune cleared the stale reference.”

Common Phrases

• “Can you just add a worktree for that branch instead of stashing your changes?”
• “Is this a linked worktree, or are we in the main checkout?”
• “That folder’s a worktree in detached HEAD — don’t commit there without creating a branch first.”
• “The worktree list is out of sync; try pruning it.”
• “Each worktree has its own node_modules, so you’ll need to reinstall dependencies there separately.”

Example Sentences

Suggesting a worktree instead of a branch switch: “Rather than stashing your in-progress changes to review this PR, just add a worktree for the PR branch — you’ll keep both build caches intact and can switch between the two folders instantly.”

Explaining a detached HEAD state to a teammate: “That worktree is in detached HEAD because I checked out a specific commit to bisect the regression — if you want to keep any changes there, you’ll need to create a branch before switching away.”

Cleaning up after a manual folder deletion: “I deleted the worktree folder directly instead of using the remove command, so Git still thinks it exists — running git worktree prune should clear it up.”

Professional Tips

• Recommend a worktree over stashing whenever someone needs to context-switch between branches without losing a running build or test state — it’s a strictly faster workflow for that case.
• Always use git worktree remove, not manual folder deletion, so Git’s internal tracking doesn’t drift — mention prune as the recovery step if someone already deleted a folder by hand.
• Clarify detached HEAD explicitly when directing someone to a worktree checked out to a raw commit — work committed there needs a branch created first, or it can become unreachable.
• Note that each linked worktree needs its own dependency install (node_modules, virtualenvs) since only Git history is shared, not the working files.

Practice Exercise

1. Write a sentence recommending a worktree instead of stashing changes.
2. Explain the difference between the main worktree and a linked worktree.
3. Describe what pruning worktrees fixes and when it’s needed.