Introduction

Une branche de tracking distant est une ref locale qui reflète une branche sur un remote. Elles vivent sous refs/remotes/<remote>/ et sont mises à jour par git fetch (et les opérations qui impliquent un fetch, comme git pull et git clone). Vous ne commitez pas directement vers elles.

D'où elles viennent

Le refspec par défaut pour origin est :

+refs/heads/*:refs/remotes/origin/*

Donc quand le serveur a refs/heads/main, votre clone obtient refs/remotes/origin/main. Le + en tête signifie « mise à jour forcée ».

Lister

git branch -r
git branch -a                # locales + tracking distant
git branch -vv               # affiche l'upstream des locales

Lier une branche locale à l'une d'elles

git switch feature/login                       # crée auto une locale depuis origin/feature/login
git switch -c mine origin/feature/login        # explicite
git branch -u origin/main                      # définit l'upstream de la branche courante
git branch --unset-upstream

Le lien upstream pilote l'avance/retard de git status, et les cibles par défaut pour git push et git pull.

Élaguer

Les branches de tracking distant ne disparaissent pas quand la branche distante est supprimée. Élaguez-les :

git fetch --prune
git remote prune origin
git config --global fetch.prune true

Le HEAD distant spécial

Chaque remote a un HEAD symbolique indiquant sa branche par défaut :

git symbolic-ref refs/remotes/origin/HEAD
git remote set-head origin --auto    # interroger le serveur

C'est ce qui fait que origin seul résout vers origin/main (ou quel que soit le défaut).

Differ contre une branche de tracking distant

git fetch
git log HEAD..origin/main --oneline      # ce qui est en upstream
git log origin/main..HEAD --oneline      # ce qui est local seulement
git diff @{u}                            # vs upstream

@{u} (ou @{upstream}) est un raccourci pour l'upstream configuré de la branche courante.

Comportement de push

Le défaut push.default = simple pousse la branche courante vers son upstream du même nom. Si vous poussez une branche sans upstream et avez push.autoSetupRemote = true (Git 2.37+), l'upstream est créé automatiquement.

Détails des refspecs

Le refspec de fetch pour un remote peut être personnalisé pour fetcher des refs supplémentaires ou les mapper différemment. Par exemple, pour aussi récupérer les refs de PR GitHub et les refs de MR GitLab :

git config --add remote.origin.fetch '+refs/pull/*/head:refs/remotes/origin/pr/*'
git config --add remote.origin.fetch '+refs/merge-requests/*/head:refs/remotes/origin/mr/*'

Le + en tête signifie « mise à jour forcée », nécessaire parce que les refs de PR peuvent bouger (rebases sur la branche de PR). Après le fetch, les PRs du serveur apparaissent comme des refs locales origin/pr/*, prêtes pour git switch -c review/<n> origin/pr/<n>.

Erreurs fréquentes

Essayer git checkout origin/main et éditer ; cela vous met en HEAD détaché parce que origin/main est en lecture seule. Créez plutôt une branche de tracking. Oublier de faire git fetch et être trompé par des compteurs avance/retard obsolètes. Traiter les branches de tracking distant comme si pousser vers elles mettait à jour le serveur ; ce sont des miroirs locaux. Utilisez git push origin main. Enfin, supprimer origin/main avec git branch -dr et supposer que la branche du serveur est partie ; elle ne l'est pas. Utilisez git push origin --delete main et seulement quand vous le pensez vraiment.