Git worktree : la feature qui a changé ma façon de coder

Pendant 8 ans, j'ai utilisé git comme tout le monde : une branche à la fois, git stash quand je devais passer à autre chose, et la prière à chaque git checkout que rien ne se perde. Jusqu'à ce que je découvre git worktree en 2025. Depuis, j'ai 3 à 5 branches checkées simultanément en permanence, chacune dans son propre dossier, et mon workflow Claude Code a complètement changé. Voici pourquoi — et le setup exact qui rend ça viable.

Le problème : changer de branche est lent et risqué

Scénario classique : je bosse sur feature/auth-v2. Un bug prod est signalé. Je dois switcher sur main, fixer, déployer, revenir à ma feature. Le problème :

1. 1.Je dois git stash mes changes WIP (ou faire un commit WIP)
2. 2.git checkout main — VS Code recharge tout, mes watchers se resetent
3. 3.Je fix le bug, je commit, je pousse
4. 4.git checkout feature/auth-v2 — re-reload complet
5. 5.git stash pop — et parfois conflit de merge sur mes propres changes

Temps perdu par switch : 3-5 minutes, plus la perte de contexte mental. En moyenne 8-10 switches par jour. 30-45 minutes perdues quotidiennement.

La solution : git worktree

git worktree permet d'avoir plusieurs working directories liés au même repo, chacun checké sur une branche différente. Les fichiers existent en parallèle sur ton disque.

# Créer un worktree pour une feature
git worktree add ../myproject-auth feature/auth-v2

# Créer un worktree pour un hotfix
git worktree add ../myproject-hotfix -b hotfix/login-bug main

# Lister les worktrees
git worktree list
# /home/patrice/myproject             abc123 [main]
# /home/patrice/myproject-auth        def456 [feature/auth-v2]
# /home/patrice/myproject-hotfix      ghi789 [hotfix/login-bug]

Chaque dossier est un working directory complet et indépendant. Ouvre n'importe lequel dans VS Code, lance npm run dev, edit, commit — comme s'ils étaient des clones séparés. Mais ils partagent la même base git (.git), donc pas de duplication d'historique.

Le gain réel sur mon workflow

Gain mesuré : ~35 minutes par jour = 2h55 par semaine.

Mon setup avec Claude Code

Mon layout typique :

~/dev/
├── patricehuetz/              # main (trunk)
├── patricehuetz-auth/         # feature/auth-v2
├── patricehuetz-blog/         # feature/blog-redesign
└── patricehuetz-experiment/   # exploration/langgraph-refactor

Chaque worktree a son propre Claude Code qui tourne. Quand je switche, j'ouvre un autre terminal / un autre tab zellij, et je suis dans un autre contexte sans avoir changé de branche.

Règle 1 : un worktree par tâche Claude Code

Quand je démarre une nouvelle tâche Claude Code, je crée un worktree dédié :

git worktree add ../patricehuetz-task-xyz -b task/xyz main
cd ../patricehuetz-task-xyz
claude-code "implement feature X"

Si Claude Code fait n'importe quoi, je peux jeter le worktree entier (git worktree remove ...) sans toucher au reste. C'est ma safety net par défaut.

Règle 2 : nommage cohérent

Tous mes worktrees suivent le pattern <nom-repo>-<context>. Ça fait des dossiers explicites dans ~/dev/, et mes aliases shell fonctionnent :

alias cdm='cd ~/dev/patricehuetz'
alias cda='cd ~/dev/patricehuetz-auth'
alias cdb='cd ~/dev/patricehuetz-blog'

Règle 3 : jamais de worktree dans le repo lui-même

# ❌ Pas bon
git worktree add ./temp-branch branch-name

# ✅ Bon
git worktree add ../repo-branch branch-name

Sinon ton .gitignore et tes watchers se confondent.

Les pièges à connaître

Piège 1 : `git pull` ne se propage pas

Si tu pull dans un worktree, les autres worktrees ne sont pas mis à jour. Chacun reste sur son commit. C'est logique mais contre-intuitif au début. Utilise git fetch --all + git pull dans chaque worktree concerné.

Piège 2 : pas de hook automatique

Les pre-commit hooks et autres doivent être installés une fois par worktree — sauf si tu utilises un hook global.

Piège 3 : l'espace disque

Chaque worktree contient ses propres node_modules, target/ (Rust), dist/, etc. Sur mon projet TypeScript, chaque worktree pèse ~1,2 GB. 5 worktrees = 6 GB. Pas négligeable si tu travailles sur un SSD petit.

Fix : utiliser pnpm qui déduplique les node_modules via hardlinks, ou des hardlinks manuels sur le cache de build.

Les commandes que j'utilise tous les jours

# Créer un worktree
git worktree add ../repo-feature feature/name

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

# Lister
git worktree list

# Supprimer un worktree (et optionnellement sa branche)
git worktree remove ../repo-feature
git branch -d feature/name  # si la branche est mergée

# Forcer suppression (worktree cassé)
git worktree remove --force ../repo-feature

Ce qu'il faut retenir

1. 1.Git worktree permet d'avoir plusieurs branches checkées en parallèle sans duplication.
2. 2.Gain mesurable : ~35 minutes par jour sur mon workflow.
3. 3.Parfait pour Claude Code — un worktree par tâche, jetable si ça foire.
4. 4.Pièges : propagation pull, hooks, espace disque.
5. 5.10 minutes d'apprentissage pour un gain permanent.

Pour le workflow complet Ralph Loop + Claude Code + worktrees qui permet de gérer plusieurs agents en parallèle, j'ai écrit un livre dédié :

La Boucle Ralph

Guide Pratique du Coding Autonome par IA.

Découvrir →