Git : dépôts distants

Un dépôt distant (remote) est une copie du projet hébergée sur un serveur (Gitea, GitHub, GitLab…). Les exemples utilisent le serveur fictif git.exemple.com.

Gérer les dépôts distants

git remote -v                                                     # liste (nom et adresse)
git remote add origin git@git.exemple.com:equipe/monprojet.git    # ajoute un dépôt distant
git remote set-url origin https://git.exemple.com/equipe/monprojet.git   # change l'adresse
git remote rename origin gitea
git remote remove gitea
git remote show origin                                            # détails (branches, suivi)

origin est le nom donné par défaut au dépôt d’origine d’un git clone.

Envoyer : `git push`

git push -u origin main               # envoie main et mémorise origin/main comme branche amont
git push                              # ensuite, simplement
git push origin fonction-recherche    # une autre branche
git push --tags                       # envoie tous les tags
git push origin v1.0.0                # un tag précis
git push origin --delete fonction-recherche   # supprime une branche distante

-u (--set-upstream) relie la branche locale à la branche distante : git push et git pull n’ont plus besoin d’arguments.

Récupérer : `git fetch` et `git pull`

git fetch                        # télécharge les nouveautés sans toucher aux fichiers locaux
git fetch --prune                # supprime aussi les références des branches distantes supprimées
git log HEAD..origin/main --oneline      # ce qui est arrivé sur origin/main
git pull                         # fetch puis fusion (ou rebase) dans la branche courante
git pull --rebase                # fetch puis rebase : historique linéaire
git pull --ff-only               # refuse s'il faut un commit de fusion

git pull = git fetch + git merge. Préférer git fetch puis examiner avant d’intégrer. Choisir son comportement par défaut :

git config --global pull.rebase false     # fusion (par défaut)
git config --global pull.rebase true      # rebase
git config --global pull.ff only          # n'accepte que le fast-forward

Suivre une branche distante

git switch fonction-recherche               # si elle existe sur origin, Git crée la branche locale qui la suit
git switch -c ma-branche origin/ma-branche
git branch -vv                              # branches locales et leur amont, avec « ahead / behind »
git branch --set-upstream-to=origin/main main

Push refusé : historique divergent

! [rejected]        main -> main (fetch first)

Quelqu’un a poussé avant vous. Récupérer, intégrer, puis repousser :

git pull --rebase
git push

Forcer avec précaution

Après avoir réécrit un historique personnel (rebase, amend) :

git push --force-with-lease          # force seulement si la branche distante n'a pas changé depuis votre dernier fetch

SSH ou HTTPS ?

Méthode	Adresse	Authentification
SSH	`git@git.exemple.com:equipe/monprojet.git`	Clé SSH (voir Installation)
HTTPS	`https://git.exemple.com/equipe/monprojet.git`	Nom d’utilisateur et jeton d’accès

Changer de méthode sur un dépôt existant : git remote set-url origin <nouvelle-adresse>.

Plusieurs dépôts distants

git remote add upstream https://git.exemple.com/projet-original/monprojet.git   # dépôt d'origine d'un fork
git fetch upstream
git switch main
git merge upstream/main               # met son fork à jour
git push origin main

Pousser vers deux serveurs en une commande (miroir de secours) :

git remote set-url --add --push origin git@git.exemple.com:equipe/monprojet.git
git remote set-url --add --push origin git@secours.exemple.com:equipe/monprojet.git
git push

Copie complète (miroir)

git clone --mirror git@git.exemple.com:equipe/monprojet.git monprojet.git   # toutes les références, sans fichiers de travail
cd monprojet.git
git remote set-url --push origin git@nouveau.exemple.com:equipe/monprojet.git
git push --mirror

Dépôt vide à créer sur le serveur

git init
git add .
git commit -m "feat: initial commit"
git branch -M main
git remote add origin git@git.exemple.com:equipe/monprojet.git
git push -u origin main

Dépannage

Symptôme	Piste
`Permission denied (publickey)`	Clé publique non enregistrée sur le serveur, ou `ssh-add` manquant
`fatal: Authentication failed` (HTTPS)	Utiliser un jeton d’accès et non le mot de passe du compte
`fatal: refusing to merge unrelated histories`	Deux historiques sans ancêtre commun : `git pull --allow-unrelated-histories` (seulement si voulu)
`error: failed to push some refs`	Historique divergent : `git pull --rebase` puis `git push`
`fatal: The current branch has no upstream branch`	`git push -u origin <branche>`
`remote: error: GH006 / protected branch`	Branche protégée : passer par une branche et une demande de fusion

Pour aller plus loin

Manuel : Working with Remotes
Suite : Annuler et corriger