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.

Navigating Nuance: Speaking About Worktrees in a Team Setting

The core concept of Git – branching and merging – can feel incredibly abstract if you’re not articulating the why behind your workflows. When talking about worktrees, particularly with colleagues who aren’t intimately familiar with the technical details, it’s vital to move beyond simply stating “I’m using a worktree.” Instead, you need to explain how that choice impacts the team and what you’re trying to achieve. This often involves phrasing related to isolation, parallel development, and risk mitigation. A common pitfall is assuming everyone understands the implications of a detached head; clarity here reduces misunderstandings and streamlines discussions during code reviews or when requesting changes. Framing your worktree strategy as an intentional design choice – rather than just a quirky Git feature – helps others appreciate its value in maintaining a stable codebase. For example, describing it as “allowing me to experiment on a separate branch without affecting the main development line” immediately conveys the core benefit. Furthermore, anticipating questions about potential conflicts and proactively addressing them demonstrates professionalism and strengthens collaboration. Remember that technical vocabulary is only part of the equation; clear communication is key.

Let’s consider a scenario: Sarah needs to investigate a bug reported on the develop branch but doesn’t want to disrupt her ongoing work on a feature branch, feature/new-widget. She creates a worktree linked to develop, allowing her to debug in isolation without interfering with her team’s progress. Later, during a code review of her PR, another developer asks, “Why did you create a separate worktree for this? Couldn’t you have just checked out develop?” Sarah responds, “I wanted to isolate the debugging process so that any changes I make while investigating the bug wouldn’t accidentally introduce regressions into the develop branch. This allows us to maintain stability and minimizes the risk of introducing unintended consequences.” This level of explanation demonstrates a thoughtful approach and reinforces the value proposition of using worktrees, even for seemingly simple tasks. It’s about clearly articulating the benefit – reduced risk and isolation – rather than just stating what you did.

Another common situation arises when discussing PR descriptions. A developer preparing to submit a change after working in a worktree might write: “This PR fixes a critical bug identified on the develop branch. I’ve created a dedicated worktree to ensure changes don’t impact ongoing development. The isolated environment allowed for thorough testing and debugging before integrating this fix.” This proactive explanation sets expectations, provides context, and demonstrates awareness of potential integration challenges. It also highlights that your worktree isn’t just a temporary setup; it’s a deliberate strategy for safe and efficient development.

git checkout -b my-worktree develop
git switch my-worktree --track develop

The above commands demonstrate the initial steps in creating a new, linked worktree based on develop. It’s important to note that the --track option ensures my-worktree correctly tracks and branches from develop, providing a clear link between the two environments. Using these phrases consistently – “isolated environment,” “risk mitigation,” “maintain stability” – will significantly improve your communication when discussing worktrees with colleagues, regardless of their Git expertise.