Git Worktree Best Practices

Directory Structure & Placement

The most important decision is where to put your worktrees. The sibling directory pattern is the most popular convention: place every worktree next to the main clone rather than inside it. This avoids nested .git issues and keeps things predictable.

# Recommended: sibling directory layout
~/projects/
├── myapp/                  # main worktree (your original clone)
│   ├── .git/               # the actual Git repository
│   ├── src/
│   └── ...
├── myapp-feature-auth/     # linked worktree for feature/auth
│   ├── .git                # file (not directory) pointing to main repo
│   ├── src/
│   └── ...
├── myapp-hotfix-login/     # linked worktree for hotfix/login
└── myapp-staging/          # linked worktree for staging

An alternative is a grouped parent directory that contains everything, including the bare clone:

# Alternative: bare-clone parent layout
~/projects/myapp/
├── myapp.git/              # bare clone (git clone --bare)
├── main/                   # worktree checked out to main
├── feature-auth/           # worktree for feature/auth
└── hotfix-login/           # worktree for hotfix/login

The bare-clone pattern is especially clean when you always work in worktrees and never need a “default” checkout. Pick whichever layout suits your habits and stick with it across projects.

Naming Conventions

Consistent names make it easy to identify worktrees in your terminal, editor, and file manager. A reliable pattern is to prefix the directory name with the project name and include the branch purpose:

# Pattern: <project>-<branch-slug>
git worktree add ../myapp-feature-auth feature/auth
git worktree add ../myapp-hotfix-login hotfix/login
git worktree add ../myapp-release-3.2 release/3.2

• Use lowercase and hyphens — avoid spaces and special characters.
• Mirror the branch name in the directory name so you can find it at a glance.
• Keep names short but descriptive. myapp-feat-auth beats worktree-for-the-authentication-feature-branch.

Cleanup Strategy

Stale worktrees waste disk space and clutter git worktree list output. Build a habit of removing worktrees as soon as their branch is merged.

# 1. Merge your branch
git checkout main && git merge feature/auth

# 2. Remove the worktree
git worktree remove ../myapp-feature-auth

# 3. Delete the branch if it's fully merged
git branch -d feature/auth

If a worktree directory was deleted manually (e.g., via rm -rf), run git worktree prune to clean up the leftover metadata:

# Preview what will be pruned
git worktree prune --dry-run

# Then prune for real
git worktree prune

Consider adding git worktree prune to a weekly cron job or a Git hook if your team creates worktrees frequently.

Working with node_modules

Every worktree gets its own working directory, which means each one needs its own node_modules. On large JavaScript or TypeScript projects, this can consume gigabytes of disk space and slow down worktree creation.

Strategies to manage this include:

• Run npm install immediatelyafter creating a worktree so you don’t forget.
• Use a shared cache — tools like pnpm use a content-addressable store that deduplicates packages across all worktrees automatically.
• Script it — wrap git worktree add in a shell function that also runs your package manager.

# Example helper function (add to ~/.zshrc or ~/.bashrc)
gwt() {
  git worktree add "$@" && cd "$1" && npm install
}

For a deeper dive, see Working with node_modules in Git Worktrees.

Team Workflow Tips

• Agree on a layout. If everyone uses the sibling directory pattern, shared scripts (CI helpers, editor configs) work the same way for every team member.
• Keep the main worktree clean.Use it as your “stable” reference. Create linked worktrees for all active development so you can always build or test against main without switching branches.
• Use worktrees for code reviews. Instead of stashing your work and checking out a PR branch, spin up a worktree. You can review and test the PR without disrupting your in-progress work.
• Lock worktrees on shared drives. If your worktree lives on a network share or external drive that may be unmounted, run git worktree lock to prevent accidental pruning.
• Coordinate branch checkouts. Git prevents two worktrees from checking out the same branch. If a teammate needs the same branch, they should either pull into an existing worktree or create a tracking branch with a different name.

Things to Avoid

• Don’t create worktrees inside the main worktree. Nesting worktrees leads to confusing .git resolution and can break tools that walk up the directory tree looking for a repository root.
• Don’t delete worktree directories with rm -rf. Always use git worktree remove so Git can clean up its internal bookkeeping. If you do accidentally delete one, run git worktree prune afterward.
• Don’t move worktrees with mv. Use git worktree move instead. A plain mv breaks the bidirectional symlink between the main repo and the worktree.
• Don’t accumulate dozens of stale worktrees. Each worktree holds a full checkout of the repository files. Ten worktrees of a 2 GB repo means 20 GB of disk usage. Remove them when the branch is merged.
• Don’t forget to install dependencies in each worktree. Worktrees share the Git object database but not the working directory. Build artifacts, node_modules, virtual environments, and other ignored files are per-worktree.