Workflow de fork

Vue d'ensemble

Le workflow de fork est le modèle standard pour les projets open source et tout contexte où les contributeurs ne bénéficient pas d'un accès direct en écriture (push) vers le dépôt principal. Au lieu de pousser vers un dépôt partagé, chaque contributeur travaille dans sa propre copie côté serveur — un fork — et propose ses modifications via une pull request. C'est ainsi que des millions de contributions parviennent chaque jour aux projets sur GitHub et GitLab.

Cette page explique ce qu'est un fork, en quoi il diffère du workflow avec dépôt partagé, les commandes précises pour cloner, configurer les remotes, pousser et ouvrir une pull request — et surtout — comment garder votre fork synchronisé pour que vos contributions restent faciles à fusionner.

La différence essentielle

Dans le workflow par branches de fonctionnalité, tout le monde pousse des branches vers un seul dépôt partagé. Le workflow de fork ajoute une couche : il existe désormais deux dépôts côté serveur — le dépôt officiel upstream, sur lequel vous n'avez pas d'accès en écriture, et votre fork, que vous contrôlez entièrement. Vous poussez vers votre fork et demandez à upstream d'y récupérer vos modifications.

On parle parfois de workflow triangulaire en raison de la relation entre les trois copies :

        upstream (official repo, read-only to you)
          ▲   │
   pull   │   │ fork (one click, server-side)
  request │   ▼
        your fork (origin) ──clone──▶ your laptop
                            ◀──push──

Vous récupérez (fetch) depuis upstream, vous poussez vers origin (votre fork), et la pull request est le pont qui demande à un mainteneur de tirer votre branche depuis votre fork vers upstream.

Étape par étape

1. Forkez le dépôt upstream sur la plateforme d'hébergement. Cela crée votre-fork sous votre compte — une copie complète côté serveur.

2. Clonez votre fork sur votre machine :

git clone https://github.com/you/project.git
cd project

3. Ajoutez upstream comme remote afin de pouvoir récupérer les dernières modifications du projet :

git remote add upstream https://github.com/original/project.git

Votre clone dispose maintenant de deux remotes. Vérifiez-les avec git remote -v :

origin    https://github.com/you/project.git (fetch)
origin    https://github.com/you/project.git (push)
upstream  https://github.com/original/project.git (fetch)
upstream  https://github.com/original/project.git (push)

origin pointe vers votre fork (là où vous poussez) ; upstream pointe vers le dépôt officiel (là où vous récupérez). Consultez git remote pour gérer ces remotes.

4. Créez une branche et travaillez. Créez toujours vos branches à partir d'un main à jour — ne committez jamais directement sur le main de votre fork, afin qu'il reste un miroir propre d'upstream :

git switch -c fix/typo-in-docs
# ...make changes and commit...
git push -u origin fix/typo-in-docs

L'option -u (--set-upstream) lie votre branche locale à celle de votre fork, de sorte que vous pourrez ensuite simplement exécuter git push.

5. Ouvrez une pull request depuis la branche de votre fork vers la branche principale d'upstream. Dans l'interface web, c'est un bouton ; avec le CLI de GitHub, vous pouvez le faire depuis le terminal :

gh pr create --base main --head you:fix/typo-in-docs

Les mainteneurs la relisent, demandent des modifications si nécessaire, et fusionnent lorsqu'ils sont satisfaits. S'ils demandent des corrections, committez et exécutez à nouveau git push — la pull request ouverte se met à jour automatiquement.

Rester synchronisé avec upstream

Le projet continue d'évoluer pendant que vous travaillez, alors actualisez votre fork depuis upstream avant de commencer de nouvelles branches. Utilisez git fetch pour télécharger les commits d'upstream, puis git merge (ou rebase) pour les intégrer :

git switch main
git fetch upstream
git merge upstream/main      # fast-forward main onto upstream
git push origin main         # update your fork's main on the server

Comme vous ne committez jamais vous-même sur main, cette fusion est toujours un fast-forward propre — sans conflits. Vous pouvez l'imposer avec git merge --ff-only upstream/main, qui échoue explicitement si main a divergé.

Mettre à jour une branche de fonctionnalité en cours

Si votre branche prend du retard pendant qu'une revue s'éternise, intégrez les nouveaux commits d'upstream. Le rebase conserve un historique linéaire que les mainteneurs préfèrent généralement :

git fetch upstream
git switch fix/typo-in-docs
git rebase upstream/main
git push --force-with-lease    # rewrite your fork's branch safely

--force-with-lease refuse d'écraser le remote si quelqu'un d'autre a poussé entre-temps, ce qui le rend bien plus sûr qu'un simple --force. Si vous préférez éviter de réécrire l'historique, exécutez plutôt git merge upstream/main. Consultez git rebase et les conflits de fusion pour gérer les détails.

Pourquoi ça fonctionne

Le modèle de fork permet à un projet d'accepter des contributions de n'importe qui tout en gardant le dépôt officiel verrouillé — seuls les mainteneurs peuvent fusionner. Les contributeurs n'ont besoin d'aucune permission spéciale, la revue se déroule en public sur chaque pull request, et l'historique upstream reste propre. Pour une collaboration à grande échelle avec des contributeurs non fiables, c'est le plus sûr des workflows Git courants.

Utilisez-le lorsque les contributeurs n'ont pas d'accès en push (la plupart des projets open source). Lorsque tout le monde est dans la même équipe et de confiance, le plus simple workflow par branches de fonctionnalité ou Gitflow évite le fork supplémentaire. Comparez-les côte à côte dans les workflows Git.

Pratique