Skip to content

Worktree

git worktree is a powerful feature in Git that allows you to work on multiple branches simultaneously by creating additional working directories (worktrees) linked to the same Git repository. Each worktree is a separate, fully-fledged working copy of the repository, with its own branch and file state, but sharing the same .git history and object database. This can be incredibly useful for tasks like:

  • Working on different branches at the same time without the overhead of cloning the repository again.
  • Performing code reviews, testing, or building features in parallel.
  • Avoiding the need to stash or commit uncommitted work when switching between branches.

How it works:

  • The main working directory is still managed as usual, but each additional worktree allows you to check out a different branch or commit without affecting the main directory or other worktrees.
  • The .git directory is shared across all worktrees, meaning the version history is common to all of them, but each worktree can operate independently regarding the current branch and working directory.

Key Commands for Git Worktree

1. Create a new worktree

To create a new worktree for a specific branch or commit:

git worktree add <path> <branch>
  • <path>: The directory where the new worktree will be created.
  • <branch>: The branch to be checked out in the new worktree (or a new branch can be created if it doesn’t exist).

Example: 

git worktree add ../feature-branch feature
This creates a new worktree in the directory ../feature-branch and checks out the branch feature. Now, you can work on this branch without interfering with your current working directory.

2. List existing worktrees

To list all the worktrees associated with the current repository, use:

git worktree list

Example Output: 

/path/to/repo            123abc [main]
/path/to/repo/feature-branch 456def [feature]

This command shows where your worktrees are located and which branch each one is on.

3. Remove a worktree

Once you're done with a worktree and no longer need it, you can remove it with:

git worktree remove <path>

This command will remove the specified worktree directory. The branch still exists in the repository, but the worktree itself is cleaned up.

Example: 

git worktree remove ../feature-branch

After running this command, the ../feature-branch directory is deleted, but the feature branch remains in the repository.

4. Prune worktrees

If a worktree is deleted manually (outside of Git), Git may still have references to it. You can clean up those references using:

git worktree prune

This command removes any worktree records that no longer exist on disk.

Use Cases for Git Worktree

  1. Simultaneous Work on Multiple Branches: If you're working on a feature branch but need to quickly switch to another branch (e.g., for a hotfix), instead of committing or stashing your current work, you can create a new worktree for the hotfix branch. This allows you to continue working on the feature branch while addressing the hotfix.

Example: 

git worktree add ../hotfix-branch hotfix

This creates a separate directory for the hotfix branch without disturbing your ongoing feature development.

  1. Testing or Reviewing Code in Parallel: You can use worktrees to test or review code from different branches without switching your main working directory. This is particularly useful if you want to test a branch but keep your primary working directory focused on another task.

Example: 

git worktree add ../test-branch test

  1. Building or Running CI/CD in Isolated Environments: Worktrees are useful in Continuous Integration (CI) or Continuous Deployment (CD) pipelines when multiple branches or configurations need to be tested or built simultaneously. Instead of switching between branches in the same directory, you can create isolated worktrees for each task.

Comparison with git clone

Feature git clone git worktree
Creates a separate Git repository Yes No
Independent .git directory Yes No (shared)
Disk usage High Low (objects and history shared)
Can switch between branches No (independent repo) Yes (same repository)
Easy cleanup Moderate Easy (with git worktree remove)

Key Points to Remember

  • Shared History: All worktrees share the same Git history and objects, so they don’t take up much additional disk space.
  • Simultaneous Work: You can work on multiple branches at the same time without needing to commit or stash uncommitted changes.
  • Avoid Cloning: Unlike git clone, git worktree doesn't create an entirely new Git repository. It's lightweight and uses the same object store as the main repository.

Example Workflow

  1. Suppose you're working on a feature branch but need to quickly address a bug on the main branch.

  2. Instead of stashing your work or committing half-done changes, you can use git worktree to create a new working directory for the main branch.

git worktree add ../main-branch main

  1. Work on the bug fix in ../main-branch, and once done, commit and push the changes.

  2. Return to your original directory, where your feature branch remains untouched and ready to continue development.

By using worktrees, you can manage multiple tasks in parallel, avoid interrupting your flow, and work efficiently on different branches.