Branches distantes et tracking

origin/main n'est pas une branche distante : c'est un marqueur local mis à jour par git fetch. Cette confusion est la source de nombreuses erreurs, branches qui « ne se mettent pas à jour », pushs rejetés, upstreams manquants. Ce guide vous explique la mécanique des branches distantes, vous montre comment les synchroniser, lire leur état et configurer vos upstreams correctement.

Prérequis : Les branches Git en bref et Merge et résolution de conflits.

Ce que vous allez apprendre

Comprendre origin/main et le mécanisme de tracking branch
Distinguer fetch et pull pour synchroniser votre dépôt local
Pousser une branche locale vers le remote et configurer le suivi
Supprimer une branche distante proprement après fusion

Les 3 types de branches à ne pas confondre

Type	Exemple	Description	Modifiable ?
Branche locale	`main`, `feature/login`	Pointeur sur vos commits locaux	Oui
Référence distante	`origin/main`, `origin/develop`	Copie locale de l'état du remote, mise à jour par `fetch`	Non (lecture seule)
Upstream	`origin/main` lié à `main`	Le remote + branche que suit votre branche locale	—

Concrètement :

Votre machine                    Serveur (GitHub)
─────────────────────────────    ─────────────────
main              → commit A     main → commit A
origin/main       → commit A     (copie locale, mise à jour par fetch)

Après git fetch (quelqu'un a pushé B sur le serveur) :
main              → commit A     main → commit B
origin/main       → commit B     ← la copie est mise à jour
                                 votre main est en retard de 1 commit

Que se passe-t-il lors d'un `git clone` ?

Quand vous clonez un dépôt, Git :

Télécharge tous les objets (commits, arbres, blobs)
Crée des références distantes pour chaque branche du remote (ex. origin/main, origin/develop)
Crée une branche locale main qui suit origin/main
Vous place sur main

Remote (GitHub) :         Local après clone :
main → C3                 origin/main → C3
develop → C5              origin/develop → C5
                          main → C3 (tracking origin/main)
                          HEAD → main

Le nom origin est la convention par défaut pour le remote principal. Ce n'est qu'un alias configurable.

Références distantes : `origin/branch`

Les branches de forme origin/main, origin/develop sont des remote-tracking branches. Elles sont en lecture seule : vous ne pouvez pas faire de commit dessus directement.

# Voir toutes les branches (locales + distantes)
git branch -a

Sortie :

* main
  feature/auth
  remotes/origin/main
  remotes/origin/develop
  remotes/origin/feature/auth

Les remotes/origin/... sont les références distantes. Elles sont mises à jour uniquement par git fetch ou git pull.

`git fetch` : récupérer sans fusionner

git fetch télécharge les nouveaux commits du remote et met à jour les références distantes, sans modifier vos branches locales :

git fetch origin

Avant fetch :                 Après fetch :
origin/main → C3              origin/main → C5 (mis à jour)
main → C3 + C4 (local)        main → C3 + C4 (inchangé)

Votre branche main locale n'a pas bougé. Pour intégrer les changements distants :

# Option 1 : merge
git merge origin/main

# Option 2 : rebase (historique linéaire)
git rebase origin/main

`git fetch` vs `git pull`

Commande	Action	Modifie la branche locale ?
`git fetch`	Télécharge les commits distants	Non
`git pull`	`git fetch` + `git merge`	Oui
`git pull --rebase`	`git fetch` + `git rebase`	Oui

git fetch suivi d'un merge ou rebase explicite vous donne plus de contrôle. Vous pouvez inspecter les changements distants avant de les intégrer :

git fetch origin
git log main..origin/main --oneline  # Voir les nouveaux commits
git merge origin/main                 # Intégrer si OK

Tracking branches

Une tracking branch (branche de suivi) est une branche locale liée à une branche distante. Cette liaison permet à Git d'afficher des informations comme « 2 commits d'avance, 1 commit de retard ».

Créer une tracking branch

# Créer et suivre une branche distante existante
git switch --track origin/feature/api
# Raccourci (si le nom n'existe qu'en remote) :
git switch feature/api

Définir le tracking sur une branche existante

git branch -u origin/feature/auth
# ou
git branch --set-upstream-to=origin/feature/auth

Voir toutes les relations de tracking

git branch -vv

Sortie :

  feature/auth a1b2c3d [origin/feature/auth: ahead 2] Ajouter JWT
* main         i7j8k9l [origin/main] Merge PR #42
  fix/header   e4f5g6h [origin/fix/header: behind 1] Corriger z-index

ahead 2 : vous avez 2 commits locaux non poussés
behind 1 : le remote a 1 commit que vous n'avez pas
Pas d'indication : synchronisé

Pousser une branche

Premier push (créer la branche distante)

git push -u origin feature/login

Le -u (ou --set-upstream) crée la branche sur le remote et configure le tracking. Les push suivants n'ont besoin que de :

git push

Pousser toutes les branches

git push --all origin

Supprimer une branche distante

Après le merge d'une PR, supprimez la branche distante pour garder un remote propre :

git push origin --delete feature/login

Vérification :

git branch -a | grep feature/login
# Aucun résultat = suppression réussie

N'oubliez pas de supprimer la branche locale aussi :

git branch -d feature/login

Synchroniser un fork

Si vous travaillez sur un fork, vous avez généralement deux remotes :

# Ajouter le dépôt original comme remote "upstream"
git remote add upstream https://github.com/original/repo.git

# Vérifier les remotes
git remote -v

Pour synchroniser votre fork :

git fetch upstream
git switch main
git merge upstream/main
git push origin main

Dépannage : problèmes courants

Symptôme	Cause probable	Solution
`There is no tracking information for the current branch`	Pas de tracking configuré	`git branch -u origin/ma-branche`
`! [rejected] (non-fast-forward)`	Remote a divergé	`git pull --rebase` puis `git push`
`fatal: 'origin/feature' not found`	Branche supprimée sur le remote	`git fetch --prune` pour nettoyer
`ahead N, behind M`	Désynchronisation locale/remote	`git pull --rebase` pour rattraper le retard, puis `git push`

À retenir

origin/main est une référence locale, pas la branche distante elle-même
git fetch met à jour les références distantes sans toucher à vos branches
git pull = git fetch + git merge (ou --rebase)
git push -u crée la branche distante et configure le tracking
git branch -vv montre ahead/behind pour chaque branche
git push origin --delete supprime une branche sur le remote

Prochaines étapes

Cherry-pick Récupérez un commit spécifique d'une autre branche.

HEAD détaché Naviguer dans l'historique sans être sur une branche.

Gestion des branches Nommez et nettoyez vos branches.