Creating multiple working environments from a single repository can feel like magic, but it’s really just the power of git worktree.

This command provides a way to check out multiple branches simultaneously, allowing developers to work on features or fixes in isolation without needing to switch branches constantly. The flexibility of git worktree opens up new workflows that can enhance productivity and streamline collaboration.

What is Git Worktree?

git worktree is a command that allows you to create additional working trees associated with a single Git repository. This means you can have multiple directories checked out from different branches of the same repository at the same time.

This is particularly useful when:

Understanding git worktree requires a grasp of how Git manages its directory structure and how it treats branches and working directories.

How Git Worktree Works

To see how git worktree functions, let's first take a look at the structure of a typical Git repository.

When you clone a repository, the .git directory contains all the metadata about the repository, including branches, commit history, and configuration. In a standard setup, you have a single working directory that reflects the currently checked-out branch.

When you create a worktree, Git adds a new directory that references the same .git directory, but it will check out a different branch in that new directory. This allows you to work on different features or fixes in isolation while using the same underlying repository.

Creating a Worktree

To create a new worktree, you use the following command:

Example

Suppose you are working on a feature branch called feature-x, and you want to create a worktree for a bug fix on the main branch. You can do this:

This command creates a new directory called main-fix one level up from your current directory. In this new directory, the main branch will be checked out, allowing you to work on the bug fix independently.

Managing Worktrees

Once you have created worktrees, you may want to manage them effectively. Here are some key commands and practices for working with git worktree.

Listing Worktrees

To see a list of all active worktrees in your repository, use:

This will show you a simple list of all worktrees along with their paths and the branches they are checked out to. The output might look like this:

Removing a Worktree

If you no longer need a worktree, you can remove it using:

Make sure that all changes in that worktree are committed or discarded before removing it. This command cleans up the directory and removes references to the worktree from Git.

Example

To remove the main-fix worktree:

Checking Out Different Branches

If you need to check out a different branch in an existing worktree, you can do so with:

Make sure you are in the worktree directory where you want to switch branches. This is a straightforward way to quickly switch focus without creating a new worktree.

Real-World Use Cases for Git Worktree

Understanding the practical applications of git worktree can help you integrate it into your workflow seamlessly. Here are some scenarios where worktrees shine.

Feature Development and Bug Fixes

Imagine you are developing a new feature on the feature-y branch. You encounter a bug in the main branch that needs immediate attention. Instead of switching back and forth, you can create a worktree for main:

This allows you to fix the bug in the main branch while continuing to work on feature-y in the original directory.

Testing New Features

Suppose you want to test a new feature from a branch called feature-z, which is dependent on changes in the main branch. You can create a worktree for feature-z while having the latest main checked out in another worktree.

This enables you to test the feature against the latest code in main without affecting your ongoing work.

Collaboration with Team Members

When working in a team, you might need to review a colleague's work on a specific branch. By creating a worktree for that branch, you can quickly test and provide feedback without disturbing your local development environment.

Common Gotchas and Best Practices

While git worktree is powerful, there are a few nuances to keep in mind to avoid common pitfalls.

Detached HEAD State

When you create a worktree from a branch that hasn’t been merged, you might find yourself in a detached HEAD state if you check out a specific commit instead of a branch. Always make sure you are working on branches to avoid losing your commits.

Clean Up After Use

Remember to clean up worktrees you no longer need. Leaving unused worktrees can clutter your filesystem and lead to confusion later on.

Branch Management

Avoid creating worktrees for branches that already have an associated worktree. Git won't allow this, and you'll receive an error message. Use git worktree list to check existing worktrees before adding new ones.

Now that you understand how to manage multiple working directories with git worktree, you are ready to explore Git Submodules.

In the next chapter, we will look at how submodules can help you manage dependencies in your project while maintaining clean boundaries between codebases.