TL;DR

git worktree is a built-in git command that lets you create separate working directories linked to the same repository. This means you can run code on one branch while writing code on another branch, without stashing changes or making messy commits. Perfect for when you need to run long tests on one branch while continuing to work on others.

Never Pause Your Development Flow Again with Git Worktree

Have you ever been stuck in this situation? You need to run a test that takes hours to complete. At the same time, you need to work on something else. If you commit your code or stash your changes to switch branches, you can't keep running your test.

This happened to me recently. I needed to test a process that took about 5 hours to run, and I needed to work on other features while waiting. The usual Git workflows didn't work for me—until I found git worktree.

When I discovered this feature, it felt like finding a secret superpower that Git had been hiding all along. What would otherwise have forced me to wait for hours or juggle multiple repository clones suddenly became simple and streamlined. That’s why I feel the need to share this secret with the world.

What is Git Worktree?

git worktree is a native git command that's built right into the standard git toolset - no extra installations or dependencies required. This helpful feature allows you to maintain multiple working trees connected to the same repository. In simple terms, you can work on different branches at the same time in different folders without switching back and forth.

Think of it like having two or more copies of your project open at once. Each copy can be on a different branch, but they're all linked to the same Git repository. Changes you make in one folder don't mess up work in another, so you can truly work on multiple things at once.

Basic Usage of Git Worktree

The main commands for git worktree are simple:

• git worktree add <relative_path> - Creates a new worktree in the location you choose
• git worktree list - Shows all your current worktrees
• git worktree remove <relative_path> - Removes a worktree when you're done with it

When you create a worktree, Git checks out a branch in that folder. If the last folder name in your path matches a branch that already exists, Git will check out that branch. If not, it creates and checks out a new branch with that name.

For example, if you run git worktree add ../feature-login, Git will create a new folder called "feature-login" with a new branch also called "feature-login".

How Git Worktree Solved My Problem

When faced with my long-running test process, git worktree provided the perfect solution:

1. I kept my primary worktree on the feature branch with my test running
2. I created a new worktree on a different branch to work on other features

This approach eliminated hours of waiting time and dramatically improved my productivity. I could let my tests run in one directory while writing new code in another directory. Without git worktree, I would have been stuck waiting for tests to finish before starting new work.

Potential Pitfalls and Best Practices

Despite its usefulness, git worktree comes with some challenges that aren't always clear from the documentation or tutorials. Here are the key issues I encountered and how to address them:

1. Path Location Matters

Pitfall: Creating a worktree inside your main project directory can cause file duplication issues.

Best Practice: Always create worktrees outside your main project directory. From your project root, use paths that start with ../ to place worktrees in parallel locations.

# Good approach - creates worktree in a parallel directory

git worktree add ../project-fix-bug fix-bug

# Better approach - organize all worktrees in a dedicated directory

git worktree add ../project-worktrees/fix-bug fix-bug

2. Branch Management

Pitfall: New worktrees branch from your current branch by default, which might not be what you want.

Best Practice: Either:

• First checkout your main development branch (e.g., main, dev) before creating a worktree, or
• End your path with the name of your main development branch. For example: git worktree add ../project-worktrees/main

For more advanced options and command flags, check out the official documentation at https://git-scm.com/docs/git-worktree.

3. Untracked Files Don't Transfer

Pitfall: Only git-tracked files appear in new worktrees. Configuration files like .env, dependency directories, and databases aren't included.

Best Practice: Depending on your tech stack, you'll need to

• Copy configuration files like .env to the new worktree
• Install dependencies in the new worktree or create symlinks
• Configure database access appropriately

In my case with a Python/Django project using SQLite, I had to:

1. Copy the .env file to the new worktree
2. Create a symlink to my virtual environment so I could use my existing Python interpreter and dependencies: ln -s ../../main-project/venv venv
3. Install Node.js dependencies separately: npm install
4. Copy the SQLite database file or run migrations to create a new one: cp ../../main-project/db.sqlite3. # OR python3 manage.py migrate

4. Port Conflicts

Pitfall: Running local servers in multiple worktrees simultaneously will cause port conflicts. You'll get errors saying the port is already in use.

Best Practice: Make sure your app gets all port numbers from your .env file. Then set different ports in each worktree's .env file. For example, if your main project runs on port 8000, set the worktree to use port 8001:

# In your main worktree's .env

PORT=8000

# In your linked worktree's .env

PORT=8001

Another option is to only run code in one worktree at a time while editing code in both.

Step-by-Step Example

Here's a simple walkthrough of how to use git worktree:

1. Set up a folder for your worktrees: From your main project directory git worktree add ../project-worktrees/feature-x
2. Go to your new worktree: cd ../project-worktrees/feature-x
3. Set up what you need in your new worktree: # Copy your config file cp ../../main-project/.env. For Python projects, link to your existing virtual environment ln -s ../../main-project/venv venv. If you also have Node.js dependencies, install these separately with npm install
4. Use both folders as needed: Run your tests in the original folder Work on new code in the worktree folder
5. Clean up when you're done: Go back to your main project cd ../../main-project. Remove the worktree git worktree remove ../project-worktrees/feature-x

When to Use Git Worktree

Git worktree is really helpful when

• You need to run or test code in one branch while working in another
• You want to review several PRs at the same time
• You need to look at code from another branch without switching back and forth
• You're fixing a bug that requires keeping your code a certain way in one branch
• You have long-running tests that you don't want to interrupt

Conclusion

git worktree might not be worthwhile if you want to work on something else while you run a process that only takes a few minutes, but when you have to run longer processes, it can lets you stay productive by working on a different branch while you wait. I no longer have to choose between running tests or working on new features - I can do both without complex workarounds.

I only discovered git worktree a few days ago, but it's already become an essential part of my toolkit. If you've never used it before, I encourage you to try it the next time you have to wait for a long-running process to complete. Sometimes the best productivity improvements come from tools that have been there all along, just waiting to be discovered.

Have you used git worktree in your development workflow? What other Git features have helped you improve your productivity?

Note: Remember to properly configure your environment for each worktree based on your specific project requirements. The solutions provided here may need adaptation for your particular tech stack.

#GitTips #DeveloperProductivity #SoftwareDevelopment #GitWorkflow #CodingTips