git fetch

La commande git fetch télécharge les commits, les fichiers et les références depuis un dépôt distant vers votre dépôt local, sans modifier votre propre travail. C'est le moyen sûr de voir ce que vos coéquipiers ont fait : rien dans votre répertoire de travail ni dans vos branches locales n'est modifié tant que vous ne décidez pas de fusionner.

Cette page explique ce que fait git fetch, comment il met à jour les branches de suivi à distance, les options les plus utiles, comment récupérer une branche spécifique ou un dépôt entier, et en quoi git fetch diffère de git pull.

Définition

La commande git fetch est utilisée pour télécharger des commits, des objets et des références depuis un dépôt distant vers le dépôt local. Elle permet de voir sur quoi travaillent les autres membres de l'équipe. Contrairement à git pull, elle ne fusionne jamais automatiquement le travail téléchargé dans votre branche actuelle.

Fonctionnement avec les branches distantes

Git stocke les commits locaux et distants et les sépare grâce à l'utilisation de références de branches. Les références pour les branches locales sont stockées dans /.git/refs/heads/. Pour afficher la liste des références de branches locales, exécutez la commande git branch.

git branch

git branch
* master
  crossword
  solver

L'exploration du contenu du répertoire /.git/refs/heads/ produit la sortie suivante :

ls ./.git/refs/heads/

ls ./.git/refs/heads/
master
crossword
solver

Les références de branches distantes sont stockées dans le répertoire ./.git/refs/remotes/. Pour voir les branches distantes, utilisez le drapeau -r avec git branch. Voici la sortie après avoir récupéré un dépôt distant :

git branch -r

git branch -r
  origin/master
  origin/crossword
  origin/solver
  remote-repo/master
  remote-repo/other-feature

La sortie affiche les branches distantes préfixées par origin/. Ce sont des branches de suivi à distance — des copies locales en lecture seule qui enregistrent l'état de chaque branche sur le dépôt distant lors du dernier fetch. Vous pouvez les examiner avec les commandes git checkout et git log. Après avoir examiné les modifications, vous pouvez fusionner une branche de suivi à distance dans votre branche locale avec git merge. Utilisez git pull pour combiner la récupération et la fusion en une seule étape.

Options courantes

Pour supprimer les références de suivi pour les branches qui n'existent plus sur le dépôt distant, utilisez --prune :

git fetch --prune

Pour récupérer depuis tous les dépôts distants configurés à la fois, utilisez --all :

git fetch --all

Comment récupérer une branche distante avec git fetch

Voici les étapes pour récupérer une branche distante et mettre à jour l'état de travail local avec le contenu distant. Dans l'exemple suivant, nous disposons d'un dépôt central origin depuis lequel le dépôt local a été cloné avec la commande git clone. Il existe un autre dépôt distant nommé test_repo contenant feature_branch qui doit être configuré et récupéré.

La première étape consiste à configurer le dépôt distant avec git remote :

git remote

git remote add test_repo git@hostname:test/test_repo.git

En utilisant l'URL du dépôt du collègue, nous avons créé une référence vers celui-ci. Pour télécharger le contenu, effectuez un git fetch de la feature_branch de test :

git fetch

git fetch test_repo feature_branch
From hostname:test/test_repo
* [new branch]      feature_branch -> test_repo/feature_branch

Cela télécharge le contenu de test_repo/feature_branch dans votre dépôt local en tant que branche de suivi à distance — cela ne le fusionne pas dans votre branche actuelle. Utilisez maintenant la commande git checkout pour inspecter la branche distante téléchargée :

git checkout test_repo/feature_branch

git checkout test_repo/feature_branch
Note: checking out 'test_repo/feature_branch'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can drop all the commits you make in this
state without influencing branches by executing another checkout.

If you want to generate a new branch for maintaining commits you create, you may
do so (now or later) if you use -b with the checkout command again. Example:

git checkout -b <new-branch-name>

La sortie indique que nous sommes dans l'état HEAD détaché, ce qui signifie que la référence HEAD pointe directement vers un commit plutôt que vers une branche.

Avec la commande git checkout, une nouvelle branche locale peut être créée à partir de la référence test/feature_branch :

git checkout -b local_feature_branch test_repo/feature_branch

git checkout -b local_feature_branch test_repo/feature_branch

La nouvelle branche locale est créée en mettant à jour HEAD pour pointer vers le dernier contenu distant.

Synchroniser origin avec git fetch

L'exemple suivant montre comment synchroniser le dépôt local avec la branche master du dépôt central :

git fetch origin

git fetch origin

La sortie affichera les branches qui ont été téléchargées :

sortie de git fetch origin

b341bc3..32a45b1  master     -> origin/master
b341bc3..7a52a22  develop    -> origin/develop
* [new branch]      some-feature -> origin/some-feature

Appelez git log en utilisant origin/master comme filtre pour afficher les commits ajoutés au master amont :

git log --oneline master..origin/master

git log --oneline master..origin/master

Vérifiez les modifications et fusionnez-les dans la branche master locale :

git checkout master && git log origin/master

git checkout master
git log origin/master

Exécutez git merge origin/master pour synchroniser avec les développements amont :

git merge

git merge origin/master

Un scénario de collaboration courant

Voici un scénario pour vous aider à mieux comprendre ce concept.

Supposons qu'il y ait une petite équipe de développement composée de deux développeurs, Alice et Bob. Ils travaillent sur un projet hébergé sur un dépôt Git distant appelé origin. Alice clone le dépôt sur sa machine locale et commence à travailler sur la branche main, tandis que Bob travaille sur une branche séparée appelée feature-branch.

1- Alice crée un nouveau fichier appelé README.md et y apporte des modifications. Elle valide ensuite ses modifications et les pousse vers la branche main du dépôt origin :

$ git add README.md
$ git commit -m "Add README file"
$ git push origin main

2- Pendant ce temps, Bob a apporté des modifications à feature-branch et les a poussées vers le dépôt origin :

$ git add some_file.txt
$ git commit -m "Add new feature"
$ git push origin feature-branch

3- Alice réalise qu'elle doit intégrer les modifications de Bob dans son propre travail, elle récupère donc les modifications depuis le dépôt origin :

$ git fetch origin

4- Après la récupération, Alice peut voir qu'il y a de nouvelles modifications dans feature-branch :

$ git branch -r
  origin/HEAD -> origin/main
  origin/main
  origin/feature-branch

5- Alice peut maintenant fusionner les modifications de Bob dans sa branche main :

$ git merge origin/feature-branch

6- Alice résout les conflits de fusion éventuels, puis pousse ses modifications vers le dépôt origin :

$ git push origin main

7- Bob peut maintenant récupérer les modifications apportées par Alice :

$ git fetch origin

8- Bob peut maintenant voir qu'il y a de nouvelles modifications dans la branche main :

$ git branch -r
  origin/HEAD -> origin/main
  origin/main
  origin/feature-branch

9- Bob peut fusionner les modifications apportées par Alice dans sa feature-branch :

$ git merge origin/main

10- Bob résout les conflits de fusion éventuels, puis pousse ses modifications vers le dépôt origin :

$ git push origin feature-branch

Et ainsi le cycle continue, Alice et Bob utilisant tous deux git fetch pour suivre les modifications apportées par l'autre et pousser leurs propres modifications vers le dépôt origin. En utilisant git fetch, ils sont en mesure de maintenir leur dépôt local à jour avec les modifications apportées par leurs coéquipiers, ce qui aide à éviter les conflits et assure un processus de collaboration fluide.

Git fetch vs git pull

Git fetch et git pull sont tous deux utilisés pour télécharger du contenu depuis le dépôt distant. La commande git fetch ne fusionne pas automatiquement les modifications dans vos branches locales ; elle met simplement à jour vos branches de suivi à distance. Le contenu récupéré n'affecte pas votre répertoire de travail local, ce qui vous permet d'examiner les commits en toute sécurité avant de les fusionner. La commande git pull télécharge le nouveau contenu et le fusionne automatiquement dans votre branche actuelle. Cela peut provoquer des conflits de fusion, il est donc recommandé d'exécuter git pull uniquement lorsque votre copie de travail est propre.

En résumé, git pull est grossièrement équivalent à git fetch suivi de git merge :

git pull origin main
# is similar to:
git fetch origin
git merge origin/main

Quand utiliser git fetch

Utilisez git fetch lorsque vous souhaitez :

• Voir ce qui a changé avant de l'intégrer. Récupérez d'abord, puis inspectez avec git log origin/main.. ou git diff main origin/main, et ne fusionnez que lorsque vous êtes prêt.
• Mettre à jour les branches de suivi à distance sans toucher à votre travail. Utile au milieu d'une tâche lorsque votre répertoire de travail contient des modifications non validées qu'un git pull pourrait perturber.
• Nettoyer les branches obsolètes. git fetch --prune supprime les références de suivi à distance pour les branches qui ont été supprimées sur le dépôt distant.
• Examiner la branche d'un coéquipier. Récupérez-la, consultez le code, et décidez si vous souhaitez la fusionner.

Pratique