Skip to main content

Git Worktree: Working Across Multiple Branches

Table of contents​

  1. What is Git Worktree?
  2. Creating a worktree
  3. Managing worktrees
  4. Use cases
  5. Best practices

1 - What is Git Worktree?​


git worktree lets you have several working directories linked to the same Git repository.

The problem​

Normally, to work on another branch, you have to:

  1. Stash your changes
  2. Check out the other branch
  3. Work
  4. Check out your branch
  5. Pop the stash

The Worktree solution​

With worktree, you have multiple folders with different branches:

~/projects/
├── mon-repo/              # main
├── mon-repo-feature/      # feature/login
└── mon-repo-hotfix/       # hotfix/urgent

Each folder is a different branch, and they share the same .git.

🔝 Back to table of contents​


2 - Creating a worktree​


Basic syntax​

git worktree add <chemin> <branche>

Examples​

# Créer un worktree pour une branche existante
git worktree add ../feature-login feature/login

# Créer un worktree avec nouvelle branche
git worktree add -b hotfix/urgent ../hotfix-urgent main

What happens​

$ git worktree add ../feature-login feature/login
Preparing worktree (checking out 'feature/login')
HEAD is now at abc1234 Latest commit on feature/login

$ ls ../
mon-repo/         # Votre repo principal
feature-login/    # Le nouveau worktree

Resulting structure​

~/projects/
├── mon-repo/
│   ├── .git/           # Le vrai dépôt Git
│   ├── src/
│   └── ...
└── feature-login/
    ├── .git            # Fichier (pas dossier!) pointant vers ../mon-repo/.git
    ├── src/
    └── ...

🔝 Back to table of contents​


3 - Managing worktrees​


List the worktrees​

git worktree list

Result:

/home/user/projects/mon-repo         abc1234 [main]
/home/user/projects/feature-login    def5678 [feature/login]
/home/user/projects/hotfix-urgent    ghi9012 [hotfix/urgent]

Remove a worktree​

# Méthode propre (supprime le dossier et la référence)
git worktree remove ../feature-login

# Si le dossier a été supprimé manuellement
git worktree prune

Move a worktree​

git worktree move ../feature-login ../login-feature

Lock a worktree​

Prevent accidental deletion:

git worktree lock ../feature-login
git worktree unlock ../feature-login

🔝 Back to table of contents​


4 - Use cases​


Case 1: Hotfix during development​

# Vous travaillez sur feature/login
cd ~/projects/mon-repo

# Un bug urgent ! Créer un worktree pour le hotfix
git worktree add ../hotfix-bug hotfix/urgent-bug

# Travailler sur le hotfix
cd ../hotfix-bug
# ... corriger le bug ...
git commit -am "fix: urgent bug"
git push origin hotfix/urgent-bug

# Revenir au travail principal
cd ../mon-repo
# Votre code feature est toujours là !

# Nettoyer après merge
git worktree remove ../hotfix-bug

Case 2: Pull Request review​

# Vous voulez tester la PR d'un collègue
git fetch origin pull/123/head:pr-123
git worktree add ../review-pr-123 pr-123

# Tester le code
cd ../review-pr-123
npm install
npm test

# Nettoyer
cd ../mon-repo
git worktree remove ../review-pr-123

Case 3: Compare two versions​

# Worktree pour la version actuelle
git worktree add ../version-current main

# Worktree pour une ancienne version
git worktree add ../version-old v1.0.0

# Comparer dans deux fenêtres VS Code
code ../version-current
code ../version-old

Case 4: Long build in parallel​

# Main fait un build long
cd ~/projects/mon-repo
npm run build  # 10 minutes...

# Pendant ce temps, travailler ailleurs
git worktree add ../quick-fix hotfix/quick
cd ../quick-fix
# Corriger rapidement un bug
git commit -am "fix: quick fix"
git push

🔝 Back to table of contents​


5 - Best practices​


Folder organization​

# Structure recommandée
~/projects/
├── mon-projet/           # main (worktree principal)
├── mon-projet-feature/   # feature branch
├── mon-projet-hotfix/    # hotfix branch
└── mon-projet-review/    # PR review

Consistent naming​

# Convention : repo-branch
git worktree add ../mon-repo-feature-login feature/login
git worktree add ../mon-repo-hotfix-urgent hotfix/urgent

✅ Do​

PracticeReason
Remove after useAvoid clutter
Use relative pathsPortability
Name clearlyFind them easily

❌ Avoid​

PracticeRisk
Too many worktreesConfusion
Forgetting to removeDisk space
Editing the same fileConflicts

Command summary​

CommandDescription
git worktree add <path> <branch>Create a worktree
git worktree add -b <new-branch> <path>Create with a new branch
git worktree listList the worktrees
git worktree remove <path>Remove a worktree
git worktree pruneClean up obsolete references
git worktree move <src> <dst>Move a worktree

🔝 Back to table of contents​