Git Worktrees

What are Git Worktrees?

Git worktrees allow you to check out multiple branches of the same Git repository into separate directories. Instead of switching branches inside one working directory, you can keep several branches open at the same time. Example:

my-service/              -> master
my-service-feature-api/  -> feature/api
my-service-hotfix/       -> hotfix/login-bug

All directories belong to the same Git repository, but each directory has its own checked-out branch.

Worktrees vs Feature Branches

A feature branch is a Git branch used to develop a feature independently.

git checkout -b feature/new-api

A worktree is a separate folder where one branch is checked out.

git worktree add ../my-service-new-api feature/new-api

Key difference

Why use Worktrees?

Worktrees are useful when you need to:

• work on several branches in parallel
• keep a feature branch open while fixing a bug on master
• avoid frequent git stash
• run builds or tests independently per branch
• open multiple branches in IntelliJ IDEA at the same time
• compare different implementations side by side

Typical Java / Maven Use Case

Example structure:

~/dev/my-service/              -> master
~/dev/my-service-payment/      -> feature/payment
~/dev/my-service-hotfix/       -> hotfix/production-fix

Each worktree can be opened as a separate IntelliJ IDEA project. This is useful for Java projects because each branch can have:

• its own running application
• its own Maven or Gradle build state
• its own generated files
• its own local configuration
• its own IDE window

Basic Commands

List existing worktrees

git worktree list

Create a worktree for an existing branch

git worktree add ../my-service-feature feature/my-feature

Create a new branch and worktree

git worktree add -b feature/my-feature ../my-service-feature

Create a worktree from master

git worktree add -b hotfix/login-bug ../my-service-hotfix master

Remove a worktree

git worktree remove ../my-service-feature

Clean up deleted or broken worktree references

git worktree prune

GitHub Workflow

Worktrees work normally with GitHub. Example:

cd ../my-service-feature
git push -u origin feature/my-feature

Then create a Pull Request on GitHub:

feature/my-feature -> master

The GitHub workflow does not change. Only the local development workflow changes.

IntelliJ IDEA Usage

IntelliJ IDEA can open each worktree as a normal project. Example:

idea ../my-service-feature
idea ../my-service-hotfix

Each worktree can have its own IntelliJ IDEA window. Recommended usage:

1. Keep the main repository folder on master
2. Create separate worktrees for features or hotfixes
3. Open each worktree as a separate IntelliJ IDEA project
4. Commit and push normally from the corresponding worktree

Important Notes

One branch per worktree

The same branch should not be checked out in multiple worktrees at the same time. Good:

my-service/          -> master
my-service-feature/  -> feature/api

Bad:

my-service/          -> feature/api
my-service-copy/     -> feature/api

Git usually prevents this to avoid conflicting changes.

Recommended Directory Naming

Use clear folder names:

project-name/
project-name-feature-login/
project-name-feature-payment/
project-name-hotfix-production/

Example:

git worktree add ../moskito-monitoring-feature-charts feature/charts

Advantages

Disadvantages / Things to Watch

Recommended Workflow

cd ~/dev/my-service
# create new feature worktree
git worktree add -b feature/new-api ../my-service-new-api
# open in IntelliJ IDEA
idea ../my-service-new-api
# work normally
cd ../my-service-new-api
git status
git add .
git commit -m "Add new API"
git push -u origin feature/new-api

Then create a Pull Request in GitHub.

Summary

Git worktrees are a powerful way to work with multiple Git branches at the same time. They are especially useful for Java projects in IntelliJ IDEA because each branch can be opened, built, tested, and run independently. Feature branches define what you are working on.Worktrees define where you are working on it.