🪴 Sanjeed's Garden

git worktree

2 min read

TLDR

How to refer another git branch while you are working on a different branch?

git worktree add ../current-dir-reference your-current-branch

This will create a new directory next to your current one that you can open in a separate Cursor window. This is the most Git-friendly approach as it doesn’t require multiple clones.

Git Worktree: A Simple Guide

What is Git Worktree?

Git worktree is a powerful feature that lets you work on multiple branches simultaneously by checking them out into different directories. Think of it as having multiple versions of your project open at once, each in its own folder.

Why Use Git Worktree?

  • Compare code between branches without constantly switching
  • Work on multiple features simultaneously
  • Keep a stable branch as reference while working on new features
  • Review pull requests while continuing your work

Basic Commands

1. Create a New Worktree

# Basic syntax
git worktree add <path> <branch>
 
# Example: Create a new worktree for a new feature
git worktree add ../project-new-feature feature/new-feature
 
# Create a new branch and worktree in one go
git worktree add -b feature/new-feature ../project-new-feature

2. List Worktrees

git worktree list

3. Remove a Worktree

git worktree remove <path>

4. Cleanup Stale Worktrees

git worktree prune

Common Use Cases

1. Reference While Developing

# Keep main branch as reference
git worktree add ../project-main main
 
# Create new feature branch in current directory
git checkout -b feature/new-feature

2. Hotfix While Developing

# Create a worktree for hotfix
git worktree add ../project-hotfix -b hotfix/bug-123

Best Practices

  1. Use meaningful directory names for your worktrees
  2. Clean up worktrees when you’re done with them
  3. Don’t check out the same branch in multiple worktrees
  4. Keep your main working directory as your primary workspace

Common Gotchas

  • You can’t check out the same branch in multiple worktrees
  • Each worktree needs its own directory
  • Submodules need to be initialized in each worktree
  • Git hooks are shared between worktrees

Example Workflow

# Start a new feature while keeping main as reference
git worktree add ../project-main main        # Create main reference
git worktree add -b feature/new ../project-feature  # Create feature branch
 
# Now you have:
# - ../project-main (main branch)
# - ../project-feature (new feature branch)
# - ./current-directory (original working directory)

That’s it! Git worktree is a simple but powerful tool that can significantly improve your development workflow.

[

Graph View