Git Worktrees

Despite having worked with Git for decades, I’ve never used worktrees until recently when working with multiple AI agents at the same time, each working in parallel on different features.

Git worktrees allow you to have multiple working directories for the same repository, each checked out to a different branch.

This is not just useful for building with AI, for example you’re working on a feature branch, but suddenly need to quickly check something on the main branch, or switch to fix a bug in production.

The traditional way would be to commit your current work (or stash it), switch branches, do what you need to do, then switch back. This can be tedious and disrupts your workflow.

A Git worktree is essentially a separate working directory that’s linked to your main repository. Think of it as having multiple copies of your project folder, but they all share the same Git history and can be synchronized.

Instead of having just one working directory where you switch between branches, you can have multiple directories, each with a different branch checked out.

This is very useful when you need to:

• Work on multiple features simultaneously
• Compare code between branches
• Test changes on different branches without losing your current work
• Work with AI agents that need to operate on different branches

Let’s say you’re working on a new feature in a branch called feature/user-authentication. You’ve made some changes but haven’t committed them yet.

Suddenly, you need to:

1. Check how something works on the main branch
2. Fix a critical bug in production
3. Review a pull request

Without worktrees, you’d need to do something like this:

# save the changes

git add .
git commit -m "WIP: user authentication"
git checkout main

# do your work

git checkout feature/user-authentication

Alternatively you could stash the changes, but with worktrees it’s even simpler, you can open another terminal and work on the main branch in a separate directory, while keeping your feature branch work intact in the original directory.

Let’s start with the essential commands you need to know.

Creating a Worktree

To create a new worktree, use:

git worktree add <path> <branch>

For example, suppose we’re working on a repository, and we’re in the feature-1 branch:

We can create a worktree for the main branch in a directory called test-main:

git worktree add ../test-main main

This creates a new directory at the same level as your current project, checked out to the main branch:

You can also create a new branch when creating a worktree, very useful to start working on a new feature branch when you’re on main, for example:

# Create a new branch and worktree at the same time
git worktree add -b feature-2 ../test-feature-2

To see all your worktrees, run this command:

git worktree list

This shows you all the worktrees and which branches they’re on.

When you’re done with a worktree, you can remove it:

git worktree remove <path>

Remember to do this often to avoid having stale worktrees around which will add confusion to your workflow. Each worktree uses disk space. For large repositories, this can add up quickly.

Or if you want to force remove a worktree (useful if there are uncommitted changes), use the --force flag:

git worktree remove --force <path>

Git worktrees are particularly powerful when working with AI coding assistants.

You can have an AI agent work on one branch while you work on another:

# Create a worktree for AI agent work
git worktree add ../ai-feature feature/ai-improvements

# The AI can work in ../ai-feature/ while you work in your main directory

Git worktrees are a powerful feature that can significantly improve your development workflow, especially when working on multiple features or with AI agents. They allow you to work on different branches simultaneously without the overhead of constantly switching between them.

Start with simple use cases like creating a worktree for quick bug fixes or code reviews, and gradually incorporate them into your regular workflow as you become more comfortable with the concept.

The key is to use worktrees when they genuinely improve your productivity, not just because they’re available. For simple projects or when you’re working on a single feature, the traditional branch switching approach might be sufficient.

But when you find yourself frequently switching between branches or working with multiple features simultaneously, worktrees can be a game-changer for your development workflow.

Remember, if you modify the same file in multiple worktrees, you might encounter conflicts when merging.