Comprehensive Guide to Git Worktrees

1. The Core Philosophy

In a standard Git setup, you have one Working Directory (your files) and one Repository (the .git folder). Switching branches requires "flipping pages" in that single folder. When you change branches, Git physically swaps the files on your disk to match the target branch.

Git Worktrees decouple the working directory from the repository. They allow you to have one single "Brain" (the .git database) connected to multiple "Bodies" (folders), each showing a different branch simultaneously. This is not a copy of the repository; it is a live, linked view of a specific branch.

Key Benefits

Zero-Stash Context Switching: Move to an urgent hotfix without the overhead of git stash or creating "work-in-progress" (WIP) commits. You simply change directories.
Parallel Execution: Run a long-running test suite or a build process on the main branch in one terminal while continuing to write code for a new feature in another folder.
Side-by-Side Comparison: Open two different branches in your IDE (e.g., VS Code or IntelliJ) simultaneously. This is invaluable for manual regression testing or verifying how a specific utility function evolved between versions.
Resource Efficiency: Unlike cloning the repo multiple times (which duplicates the entire .git history, often hundreds of megabytes), worktrees share the same object database. The only extra space used is for the actual checked-out source files.

2. Technical Architecture: The "Brain" vs. The "Body"

Understanding the link between worktrees is crucial for mastering the workflow.

The Brain (Main .git): Located in your primary folder, this holds the entire history, every commit, every blob, and all remote-tracking refs.
The Body (Linked Worktree): A folder containing the files for a specific branch. Inside, instead of a .git folder, there is a .git file. This file contains a text path that points Git back to the administrative metadata stored in the main repository's .git/worktrees/ directory.

The Connection Logic

Because all worktrees share the same database:

Shared Commits: If you commit a bug fix in Worktree_B, that commit object is immediately available in Worktree_A. You don't need to push or pull; the "Brain" already knows about it.
Universal Branch List: Creating a branch in one folder makes it visible across all folders. Running git branch in any worktree shows the same list of local branches.
Unified Remote Updates: Running git fetch or git pull from a remote (e.g., origin) in one worktree updates the shared database. All other worktrees instantly see the new remote commits.

3. Worktree vs. Stashing: When to Use Which?

While both tools help with context switching, they serve different purposes:

Use git stash for very minor interruptions (e.g., "I need to check one line of code on another branch and come right back"). It is faster for 30-second tasks.
Use git worktree for substantial interruptions (e.g., "A bug was found in production and I need to fix it while my current 2-hour build is running"). It allows you to keep your current workspace exactly as it is—open files, running debuggers, and terminal states—without any disruption.

4. Essential Command Reference

Basic Operations

Command	Purpose
`git worktree add <path> <branch>`	Creates a new folder at `<path>` and checks out the existing `<branch>`.
`git worktree add -b <new-branch> <path>`	Creates a brand new branch and checks it out into a new folder at `<path>`.
`git worktree list`	Displays a table of all active worktrees, their file paths, and active branches.
`git worktree remove <path>`	Deletes the worktree folder and tells the "Brain" to stop tracking it.
`git worktree prune`	Cleans up "ghost" references if you deleted a folder via the OS instead of the CLI.

Advanced Operations

Checking out Remote Branches:

git worktree add ../fix-folder origin/hotfix-api

This creates a local branch tracking the remote one and places it in a separate directory.

Locking a Worktree:

git worktree lock <path> --reason "On external drive"

Use this if your worktree is on a USB drive or network share. It prevents Git from accidentally pruning the metadata if the drive is disconnected.

5. The "Bare" Professional Workflow

In high-velocity environments, developers often use a "Bare" clone. This setup ensures that no branch is "special" and every branch (including main) lives in its own dedicated worktree.

Setup Steps

Clone as Bare: Initialize the "Brain" without an attached working directory.
```
git clone --bare https://github.com/user/repo.git .git
```
Configure Config: (Optional) Tell Git that this is actually a repository core.
```
git config core.bare false
```

Add Your Primary Branches:

git worktree add main
git worktree add develop

Resulting Structure

my-project/
├── .git/          # The central "Brain" (now a hidden folder in the root)
├── main/          # Production workspace
├── develop/       # Active development workspace
└── feature-abc/   # Temporary feature workspace

6. Critical Constraints & Safety Rules

The Single Branch Guard: Git strictly forbids checking out the same branch in two different worktrees. This is a safety feature to prevent "race conditions" where two different folders try to update the same branch pointer to different commits.
The "Merge" Logic: Remember: Branches contain code; Folders contain files. You always merge by branch name.

Scenario: You are in Folder_A (on main) and want changes from Folder_B (on feature-login).

Correct:

git merge feature-login

Note: You do not need to cd into the other folder to "send" the code; you simply "pull" the branch name from the shared database.

7. Common Troubleshooting & Best Practices

The "Already Checked Out" Error: If you see fatal: 'my-branch' is already checked out at '...', it means that branch is tied to another folder. You must either cd to that folder or move that worktree to a different branch before you can use it elsewhere.
Manual Deletion Cleanup: If you accidentally delete a worktree folder using the "Trash" or "Delete" key in your File Explorer, Git will still think the branch is "busy." Always run git worktree prune to refresh Git's internal map of your file system.
Relative Paths: When adding worktrees, using ../folder-name is generally safer as it keeps the worktrees as "siblings" rather than nesting a repository inside a repository.