Introduction

Un remote est une URL nommée pointant vers un autre dépôt Git. git clone en crée un appelé origin automatiquement, mais vous pouvez en ajouter autant que vous le souhaitez. Les remotes sont le pont entre votre dépôt local et le monde extérieur.

Lister et inspecter

git remote
git remote -v
git remote show origin

git remote show contacte le serveur et signale les branches suivies, les règles de push et les refs obsolètes.

Ajouter et supprimer

git remote add upstream https://github.com/original/widget.git
git remote rename upstream origin-upstream
git remote remove origin-upstream

Le motif fork-and-upstream est courant : origin est votre fork, upstream est le projet dont vous avez fait le fork.

Changer une URL

Si un projet passe de HTTPS à SSH ou vers un nouvel hôte :

git remote set-url origin [email protected]:example/widget.git
git remote -v

URLs multiples

Vous pouvez pusher vers plusieurs miroirs à la fois en ajoutant des URLs de push supplémentaires :

git remote set-url --add --push origin [email protected]:example/widget.git
git remote -v

Élaguer les branches obsolètes

Quand des branches sont supprimées sur le serveur, vos refs locales refs/remotes/origin/* peuvent être en retard. Nettoyez-les :

git fetch --prune
git remote prune origin

Ou définissez-le de façon permanente :

git config --global fetch.prune true

Inspecter le tracking

git branch -vv
# main           a1b2c3d [origin/main] Latest fix
# feature/login  e4f5g6h [origin/feature/login: ahead 2] WIP

-vv montre l'upstream de chaque branche et son avance/retard.

Réécriture insteadOf

Si les URLs d'un projet changent (HTTPS vers SSH, migration d'hôte, ou si vous voulez que toutes les URLs GitHub utilisent SSH automatiquement), insteadOf les réécrit de façon transparente :

git config --global url."[email protected]:".insteadOf "https://github.com/"
git config --global url."https://github-mirror.example.com/".insteadOf "https://github.com/"

C'est particulièrement pratique en CI, où vous pouvez réécrire tous les clones vers un miroir local avec une ligne de configuration, sans modifications de script. La direction inverse (pushInsteadOf) vous permet de fetcher via HTTPS mais de pusher via SSH depuis le même remote.

Workflows triangulaires

En open source, vous fetchez typiquement depuis upstream (le projet canonique) et pushez vers origin (votre fork personnel). Configurez une fois et oubliez :

git remote add upstream https://github.com/project/repo.git
git config branch.main.remote upstream
git config branch.main.pushRemote origin
git config --global push.default current

Maintenant git pull lit depuis upstream et git push écrit vers votre fork, automatiquement. Le paramètre remote.pushDefault applique la règle à chaque branche d'un clone.

Erreurs fréquentes

Confondre le nom d'un remote avec son URL. origin n'est qu'une étiquette ; vous pouvez le renommer. Autre piège : ajouter la même URL sous deux noms différents, puis être surpris par des refs en double. Utilisez git remote -v pour auditer. Oublier de faire git fetch après avoir changé de réseau ou modifié une URL laisse vos branches de tracking obsolètes. Enfin, sur les serveurs partagés, supprimer une ref de tracking distante localement (par ex. git branch -dr origin/main) ne supprime pas la branche sur le serveur ; utilisez git push origin --delete main pour cela, et seulement quand vous le souhaitez vraiment.