Git Worktree: Managing Multiple Working Directories

Git worktree is a powerful feature that allows you to have multiple working directories associated with a single repository. Instead of switching branches and potentially losing uncommitted work, you can check out different branches in separate directories simultaneously without recloning the repository.

Git worktree creates additional working trees linked to the same repository. Each worktree can have a different branch checked out, allowing you to work on multiple features, bug fixes, or experiments without the overhead of cloning the entire repository multiple times. The main point is that you only have one git index (.git directory), reducing disk space usage and improving performance.

When you're in the flow of coding, switching contexts can be disruptive. Git worktree helps by:

• Preserving context: Keep your current work intact while quickly switching to fix a bug or review code
• Parallel development: Work on multiple features simultaneously without branch switching overhead
• Agent coding: You can let an AI agent work on a separate branch while you continue your current tasks
• Reduced cognitive load: No need to stash or commit incomplete work when switching tasks
• Comparing files: Easily compare changes across branches without needing to switch back and forth. You can have multiple versions of the same file open in different worktrees, making it easier to see how changes affect your code.

To create a new worktree:

# Create a worktree for an existing branch
git worktree add ../feature-branch feature-branch

# Create a worktree with a new branch from the main branch
git worktree add -b new-feature ../new-feature origin/main

To delete a worktree, you can use:

# Remove a worktree
git worktree remove ../feature-branch

# Or delete the directory and clean up:
rm -rf ../feature-branch
git worktree prune

You can also list all worktrees with:

# List all worktrees
git worktree list

Best practices for using Git worktree:

• Keep worktrees in a predictable location (e.g., sibling directories)
• Use descriptive directory names that match branch names
• Clean up unused worktrees regularly to avoid clutter

#Advanced Workflow: Using Bare Clones with Worktrees

For users managing multiple worktrees frequently, combining Git worktrees with bare clones provides an even cleaner workflow. A bare clone contains only the Git repository data (.git directory) without any working files.

Here's how to set up this advanced workflow:

# Create a parent directory for the project
mkdir my-project
cd my-project

# Create a bare clone
git clone --bare https://github.com/user/repo.git repo.git

# Navigate to the bare repository
cd repo.git

# Create worktrees as sibling directories
git worktree add ../main
git worktree add ../feature-branch
git worktree add -b new-feature ../new-feature

This structure results in:

my-project/
├── repo.git/          # Bare repository (Git data only)
├── main/              # Worktree for main branch
├── feature-branch/    # Worktree for feature branch
└── new-feature/       # Worktree for new feature branch

##Configuring Upstream Tracking for Bare Clones

When using bare clones with worktrees, you may encounter issues with upstream tracking. By default, bare clones don't configure the standard refspec for remote branches. To fix this:

# In the bare repository directory
cd repo.git

# Configure the fetch refspec for origin
git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'

# Fetch remote branches
git fetch origin

# Now you can create worktrees with automatic tracking
git worktree add ../feature-branch origin/feature-branch

Benefits of the bare clone + worktree workflow:

• Centralized Git repository management
• Clear separation between Git data and working directories
• Easier to manage multiple long-lived branches
• Reduced disk space usage compared to multiple full clones

Git worktree is an underutilized feature that can significantly improve your development workflow, especially when you need to maintain multiple contexts simultaneously. For developers who frequently work on multiple features or need to switch between different branches often, combining worktrees with bare clones provides an even more powerful and organized approach to managing multiple working directories.

#VS Code

VS Code recently added support for Git worktrees. You may need to enable it in your settings: https://code.visualstudio.com/updates/v1_103#_git-worktree-support

Then, you can use the UI to create or delete worktrees:

Create a worktree in VS Code

Delete a worktree in VS Code

Do you have a question or a suggestion about this post? Contact me!