git remote

Ce que fait git remote

Un remote est une référence nommée vers une autre copie de votre dépôt — généralement hébergée sur un serveur tel que GitHub, GitLab ou Bitbucket. La commande git remote crée, liste, renomme et supprime ces connexions. Elle ne transfère pas de commits elle-même ; elle stocke plutôt des noms courts et mémorables qui pointent vers des URL de dépôts, afin que les commandes qui déplacent réellement des données — git fetch, git pull et git push — puissent s'y référer.

Pensez à un remote comme à un signet. Au lieu de taper git push https://github.com/acme/app.git main à chaque fois, vous enregistrez l'URL une seule fois sous le nom origin et exécutez git push origin main. La correspondance entre les noms et les URL est stockée dans le fichier .git/config de votre dépôt, de sorte que chaque clone conserve sa propre liste de remotes.

Le diagramme ci-dessous montre deux connexions distantes depuis un dépôt local : l'une vers un dépôt central et l'autre vers le dépôt d'un autre développeur. Parce que les noms sont partagés par convention, vous pouvez dire à un collègue de « tirer depuis upstream » et il saura exactement quelle commande exécuter.

Le remote origin

Exécuter git clone crée automatiquement un remote nommé origin qui pointe vers le dépôt depuis lequel vous avez cloné. Par convention, origin est « votre » copie canonique sur le serveur — celle vers laquelle vous poussez et depuis laquelle vous tirez au quotidien. Il n'y a rien de spécial dans ce nom ; c'est simplement le choix par défaut de Git, et vous pouvez le renommer ou le supprimer comme n'importe quel autre remote.

Un second remote courant est upstream. Lorsque vous forkez un projet, origin pointe vers votre fork et upstream pointe vers le dépôt original, ce qui vous permet d'intégrer les nouveaux changements du projet tout en poussant votre propre travail vers votre fork.

URL de dépôts

Une URL de remote indique à Git où se trouve le dépôt et quel protocole de transport utiliser. Les deux que vous verrez le plus souvent sont HTTPS et SSH.

HTTPS est le plus simple à configurer et fonctionne à travers les pare-feux et les proxies. Les dépôts publics peuvent être clonés via HTTPS sans identifiants ; pour les dépôts privés ou pour pousser, Git demande un nom d'utilisateur et un jeton d'accès personnel, généralement mis en cache par un assistant d'identifiants.

https://host/path/to/repo.git

SSH s'authentifie avec une paire de clés plutôt qu'un mot de passe, ce qui le rend pratique pour des poussées répétées une fois votre clé enregistrée auprès de l'hôte. Il se présente sous deux formes équivalentes — l'URL complète ssh:// et la syntaxe raccourcie de type SCP :

ssh://user@host/path/to/repo.git

user@host:path/to/repo.git

Vous n'avez pas besoin de mémoriser le format d'une URL ; vous la copiez depuis le bouton « Clone » du fournisseur d'hébergement. La commande git remote stocke ensuite la forme que vous avez utilisée.

Sous-commandes de git remote

git remote expose plusieurs sous-commandes. Chacune modifie la section remote de .git/config ; vous pourriez apporter les mêmes modifications manuellement dans un éditeur de texte, mais les sous-commandes sont plus sûres et mettent à jour les paramètres associés pour vous.

git remote add

Enregistre un nouveau remote nommé <name> qui pointe vers <url>.

git remote add <name> <url>

Deux options utiles :

• -f exécute git fetch <name> immédiatement après la création du remote, de sorte que ses branches sont téléchargées tout de suite.
• --tags récupère le remote et importe également tous ses tags.

git remote rename

Renomme un remote de <old> en <new>, en mettant à jour les branches de suivi distantes et toute configuration associée.

git remote rename <old> <new>

git remote remove

Supprime la connexion nommée <name> ainsi que ses branches de suivi distantes et sa configuration. git remote rm est un alias plus ancien pour la même commande.

git remote remove <name>

git remote set-url

Modifie l'URL vers laquelle pointe un remote existant — par exemple, lorsque vous passez un dépôt de HTTPS à SSH.

git remote set-url <name> <new-url>

git remote get-url

Affiche la ou les URL d'un remote. Ajoutez --push pour voir spécifiquement l'URL de push, ou --all pour lister toutes les URL configurées.

git remote get-url <name>

git remote show

Affiche des informations détaillées sur un remote : ses URL de fetch et de push, ses branches et comment vos branches locales le suivent.

git remote show <name>

git remote prune

Supprime les branches de suivi distant locales pour <name> dont les homologues ont été supprimés sur le serveur. Utilisez --dry-run pour lister ce qui serait supprimé sans rien supprimer réellement.

git remote prune <name>

Lister vos remotes

Exécuter git remote sans argument affiche le nom de chaque remote configuré, un par ligne :

git remote
origin
upstream
other_repo

Ajoutez l'option -v (verbose) pour voir également les URL de fetch et de push de chaque remote :

git remote -v
origin      [email protected]:origin_user/reponame.git (fetch)
origin      [email protected]:origin_user/reponame.git (push)
upstream    https://example.com/upstream_user/reponame.git (fetch)
upstream    https://example.com/upstream_user/reponame.git (push)
other_repo  https://example.com/other_repo/reponame.git (fetch)
other_repo  https://example.com/other_repo/reponame.git (push)

Un remote peut avoir une URL de fetch différente de l'URL de push — utile, par exemple, lorsque vous tirez depuis un miroir rapide mais poussez vers le serveur canonique.

Ajouter un remote

Pour commencer à collaborer avec un autre dépôt, enregistrez-le avec git remote add. Le nom que vous choisissez devient un raccourci que vous pouvez utiliser dans fetch, pull et push :

git remote add upstream https://example.com/upstream_user/reponame.git

Se connecter aux dépôts d'autres développeurs permet la collaboration en dehors du dépôt central. Par exemple, si un collègue maintient un dépôt accessible publiquement à dev.example.com/tom.git, ajoutez-le ainsi puis récupérez son travail :

git remote add tom https://dev.example.com/tom.git
git fetch tom

Inspecter un remote

La sous-commande show contacte le remote et rapporte ses branches et sa configuration de suivi — pratique lorsque vous voulez confirmer quelle branche sera mise à jour par un push ou un pull :

git remote show upstream
* remote upstream
  Fetch URL: https://example.com/upstream_user/reponame.git
  Push  URL: https://example.com/upstream_user/reponame.git
  HEAD branch: main
  Remote branches:
    main      tracked
    docs      tracked
    new-input tracked
  Local ref configured for 'git push':
    main pushes to main (fast-forwardable)

Fetch, pull et push

Configurer un remote n'est que l'étape de mise en place. Une fois qu'il existe, vous passez son nom aux commandes qui déplacent réellement les commits :

• git fetch <remote> télécharge les nouveaux commits du remote dans vos branches de suivi distant sans modifier vos fichiers de travail.
• git pull <remote> <branch> récupère puis fusionne (ou rebase) les changements dans votre branche actuelle.
• git push <remote> <branch> envoie vos commits locaux vers le remote.

git push <remote-name> <branch-name>

Par exemple, pour publier la branche main vers origin :

git push origin main

Si vous souhaitez approfondir l'emplacement de stockage de ces noms et URL, consultez le chapitre git config, qui documente le fichier .git/config que git remote modifie.

Pratique