Git
Français ▾ Topics ▾ Latest version ▾ git-fetch last updated in 2.46.2

NOM

git-fetch - Télécharger les objets et références depuis un autre dépôt

SYNOPSIS

git fetch [<options>] [<dépôt> [<spéc-de-réf>…​]]
git fetch [<options>] <groupe>
git fetch --multiple [<options>] [(<dépôt> | <groupe>)…​]
git fetch --all [<options>]

DESCRIPTION

Récupérer des branches et/ou des étiquettes (collectivement, "réfs") depuis un ou plusieurs autres dépôts, ainsi que les objets nécessaires pour compléter leur historique. Les branches de suivi à distance sont mises à jour (voir la description de <spéc-de-réf> ci-dessous pour les moyens de contrôler ce comportement).

Par défaut, toute étiquette qui pointe vers les historiques recherchés est également recherchée ; l’effet est de rechercher les étiquettes qui pointent vers les branches qui vous intéressent. Ce comportement par défaut peut être modifié en utilisant les options --tags ou --no-tags ou en configurant remote.<nom>.tagOpt. En utilisant une spécification de référence qui récupère les étiquettes explicitement, vous pouvez également récupérer les étiquettes qui ne pointent pas sur les branches qui vous intéressent.

git fetch peut aller chercher à partir d’un seul dépôt nommé ou d’une seule URL, ou à partir de plusieurs dépôts à la fois si <groupe> est donné et qu’il y a une entrée remotes.<groupe> dans le fichier de configuration. (Voir git-config[1]).

Lorsqu’aucun distant n’est spécifié, par défaut le distant origin sera utilisé, à moins qu’il n’y ait une branche amont configurée pour la branche courante.

Les noms des refs qui sont récupérés, ainsi que les noms des objets qu’ils pointent, sont écrits dans .git/FETCH_HEAD. Ces informations peuvent être utilisées par des scripts ou d’autres commandes git, telles que git-pull[1].

OPTIONS

--[no-]all

Récupérer tous les distants, à l’exception de ceux qui ont la variable de configuration remote.<nom>.skipFetchAll renseignée. Cela surcharge la variable de configuration fetch.all .

-a
--append

Ajouter les noms de références et les noms d’objets des références récupérées au contenu existant de .git/FETCH_HEAD. Sans cette option, les anciennes données dans .git/FETCH_HEAD seront écrasées.

--atomic

Utiliser une transaction atomique pour mettre à jour les références locales. Soit toutes les références sont mises à jour, soit, en cas d’erreur, aucune référence n’est mise à jour.

--depth=<profondeur>

Limiter la récupération au nombre spécifié de commits à partir du sommet de l’historique de chaque branche distante. Si vous allez chercher dans un dépôt "superficiel" créé par git clone avec l’option --depth=<profondeur> (voir git-clone[1]), approfondir ou raccourcir l’historique jusqu’au nombre spécifié de validations. Les étiquettes pour les commits approfondis ne sont pas récupérées.

--deepen=<profondeur>

Semblable à --depth, sauf que cela précise le nombre de commits à partir de la limite actuelle superficielle au lieu du sommet de l’historique de chaque branche distante.

--shallow-since=<date>

Approfondir ou raccourcir l’historique d’un dépôt superficiel pour inclure tous les commits accessibles après <date>.

--shallow-exclude=<révision>

Approfondir ou raccourcir l’historique d’un dépôt superficiel afin d’exclure les commits accessibles depuis une branche ou une étiquette distante spécifiée. Cette option peut être spécifiée plusieurs fois.

--unshallow

Si le dépôt de sources est complet, convertir un dépôt superficiel en un dépôt complet, en supprimant toutes les limitations imposées par les dépôts superficiels.

Si le dépôt source est superficiel, il faut en extraire le plus possible afin que le dépôt actuel ait le même historique que le dépôt source.

--update-shallow

Par défaut, lors de la récupération d’un dépôt superficiel, git fetch refuse les références qui nécessitent une mise à jour de .git/shallow. Cette option met à jour le fichier .git/shallow et accepte de telles références.

--negotiation-tip=<commit|glob>

Par défaut, Git signalera au serveur les commits accessibles à partir de toutes les références locales pour trouver les commits communs afin de réduire la taille du fichier de paquet à recevoir. Si ceci est spécifié, Git ne signalera que les commits accessibles à partir des sommets donnés. Ceci est utile pour accélérer les recherches lorsque l’utilisateur sait quelle réf locale est susceptible d’avoir des commits en commun avec la réf amont qui est recherchée.

Cette option peut être spécifiée plus d’une fois ; si c’est le cas, Git signalera les commits accessibles à partir de l’un des commits donnés.

L’argument de cette option peut être un glob sur les noms de référence, une référence ou le SHA-1 (éventuellement abrégé) d’un commit. La spécification d’un glob équivaut à spécifier cette option plusieurs fois, une pour chaque nom de référence correspondant.

Voir aussi les variables de configuration fetch.negotiationAlgorithm et push.negotiate documentées dans git-config[1], ainsi que l’option --negotiate-only ci-après.

--negotiate-only

Ne rien récupérer du serveur, et à la place afficher les ancêtres des arguments fournis par --negotiation-tip=*, que nous avons en commun avec le serveur.

C’est incompatible avec --recurse-submodules=[yes|on-demand]. En interne, ceci est utilisé pour implémenter l’option push.negotiate, voir git-config[1].

--dry-run

Montrer ce qui serait fait, sans faire de changements.

--porcelain

Afficher la sortie sur la sortie standard dans un format facile à décrypter pour les scripts. Voir la section SORTIE dans git-fetch[1] pour plus de détails.

C’est incompatible avec --recurse-submodules=[yes|on-demand]`et a la priorité sur l'option de configuration `fetch.output.

--[no-]write-fetch-head

Ecrire la liste des refs distants récupérés dans le fichier FETCH_HEAD directement sous $GIT_DIR. C’est la valeur par défaut. Passer --no-write-fetch-head depuis la ligne de commande indique à Git de ne pas écrire le fichier. Avec l’option --dry-run, le fichier n’est jamais écrit.

-f
--force

Lorsque git fetch est utilisé avec la spécification de référence <src>:<dst>, il peut refuser de mettre à jour la branche locale comme cela a été discuté dans la partie <spécificateur-de-référence> ci-dessous. Cette option permet de passer outre à ce contrôle.

-k
--keep

Conserver le paquet téléchargé.

--multiple

Permettre de spécifier plusieurs arguments <dépôt> et <groupe>. Aucun <spécificateur-de-référence> ne peut être spécifié.

--[no-]auto-maintenance
--[no-]auto-gc

Exécuter git maintenance --auto à la fin pour effectuer la maintenance automatique du dépôt si nécessaire. (--[no-]auto-gc est un synonym.) Ceci est activé par défaut.

--[no-]write-commit-graph

Écrire un graphe de commit après avoir récupéré. Ceci remplace le paramètre de configuration fetch.writeCommitGraph.

--prefetch

Modifier le spécificateur de référence configuré pour placer toutes les refs dans l’espace de noms refs/prefetch/. Voir la tâche prefetch dans git-maintenance[1].

-p
--prune

Avant de récupérer, supprimer toutes les références de suivi à distance qui n’existent plus sur le dépôt distant. Les étiquettes ne sont pas sujettes à l’élagage si elles ne sont récupérées qu’en raison du suivi automatique de l’étiquette par défaut ou en raison d’une option --tags. Cependant, si les étiquettes sont récupérées en raison d’un spécificateur de référence explicite (soit en ligne de commande, soit dans la configuration distante, par exemple si le dépôt distant a été cloné avec l’option --mirror), alors elles sont également sujettes à l’élagage. La fourniture de --prune-tags est une abréviation pour la fourniture du spécificateur de référence d’étiquette.

Voir la section ÉLAGAGE ci-dessous pour plus de détails.

-P
--prune-tags

Avant de récupérer, supprimer toutes les étiquettes locales qui n’existent plus sur le distant si --prune est activé. Cette option doit être utilisée avec plus de précaution, car contrairement à --prune, elle supprime toutes les références locales (étiquettes locales) qui ont été créées. Cette option est un raccourci pour la fourniture du spécificateur de référence d’étiquette explicite avec --prune, voir la discussion à ce sujet dans sa documentation.

Voir la section ÉLAGAGE ci-dessous pour plus de détails.

-n
--no-tags

Par défaut, les étiquettes qui pointent sur des objets téléchargés à partir du dépôt distant sont récupérées et stockées localement. Cette option désactive le suivi automatique des étiquettes. Le comportement par défaut d’un distant peut être spécifié avec le paramètre remote.<nom>.tagOpt. Voir git-config[1].

--refetch

Au lieu de négocier avec le serveur pour éviter de transférer les commits et les objets associés qui sont déjà présents localement, cette option récupère tous les objets comme le ferait un nouveau clone. Utilisez cette option pour réappliquer un filtre de clone partiel depuis la configuration ou en utilisant --filter= lorsque la définition du filtre a changé. La maintenance automatique post-récupération effectuera une consolidation des paquets de la base de données des objets pour supprimer tout objet en double.

--refmap=<spécificateur-de-référence>

Lors de la récupération des références listées en ligne de commande, utiliser la spécification de référence (qui peut être donnée plusieurs fois) pour mapper les références sur les branches de suivi à distance, au lieu des valeurs des variables de configuration remote.*.fetch pour le dépôt distant. Fournir un <spécificateur-de-référence> vide à l’option --refmap fait que Git ignore les spécification de référence configurées et se fie entièrement aux spécifications de référence fournies comme arguments de la ligne de commande. Voir la section sur les "Branches de suivi à distance configurées" pour plus de détails.

-t
--tags

Récupérer toutes les étiquettes à distance (c’est-à-dire, récupérer les étiquettes refs/tags/* dans les étiquettes locales avec le même nom), en plus de tout ce qui serait récupéré autrement. L’utilisation de cette seule option ne soumet pas les étiquettes à un élagage, même si --prune est utilisé (bien que les étiquettes puissent être élaguées de toute façon si elles sont aussi la destination d’une spécification de référence explicite ; voir --prune).

--recurse-submodules[=(yes|on-demand|no)]

Cette option contrôle si et sous quelles conditions les nouveaux commits des sous-modules doivent être récupérés également. Lorsqu’il parcourt les sous-modules, git fetch essaie toujours de récupérer les sous-modules "modifiés", c’est-à-dire les sous-modules qui ont des commits référencés par un commit de superprojet récemment récupéré mais qui sont manquants dans le clone de sous-module local. Un sous-module modifié peut être récupéré tant qu’il est présent localement, par exemple dans $GIT_DIR/modules/ (voir gitsubmodules[7]) ; si l’amont ajoute un nouveau sous-module, ce sous-module ne peut pas être récupéré jusqu’à ce qu’il soit cloné, par exemple par git submodule update.

Lorsqu’il est défini sur on-demand, seuls les sous-modules modifiés sont récupérés. Lorsqu’il a pour valeur yes, tous les sous-modules peuplés sont récupérés et les sous-modules non peuplés et modifiés sont récupérés. Avec la valeur no, les sous-modules ne sont jamais récupérés.

Lorsque cette option n’est pas spécifiée, elle utilise la valeur de fetch.recurseSubmodules si elle est définie (voir git-config[1]), et prend par défaut la valeur on-demand si elle n’est pas définie. Lorsque cette option est utilisée sans aucune valeur, elle prend par défaut la valeur yes.

-j
--jobs=<n>

Nombre d’enfants parallèles à utiliser pour toutes les formes d’extraction.

Si l’option --multiple a été spécifiée, les différents distants seront récupérés en parallèle. Si plusieurs sous-modules sont récupérés, ils seront récupérés en parallèle. Pour les contrôler indépendamment, utilisez les paramètres de configuration fetch.parallel et submodule.fetchJobs (voir git-config[1]).

Généralement, les recherches récursives parallèles et sur des distants multiples seront plus rapides. Par défaut, les recherches sont effectuées de manière séquentielle, et non en parallèle.

--no-recurse-submodules

Désactiver la récupération récursive des sous-modules (cela a le même effet que d’utiliser l’option --recurse-submodules=no).

--set-upstream

Si le distant est récupéré avec succès, ajouter la référence (de suivi) amont , utilisée par les commandes sans argument git-pull[1] et autres. Pour plus d’informations, voir branch.<nom>.merge et branch.<nom>.remote dans git-config[1].

--submodule-prefix=<chemin>

Préfixer <chemin> aux chemins affichés dans les messages informatifs tels que "Récupération du sous-module foo". Cette option est utilisée en interne lors de la récursion sur les sous-modules.

--recurse-submodules-default=[yes|on-demand]

Cette option est utilisée en interne pour fournir temporairement une valeur par défaut non négative pour l’option --recurse-submodules. Toutes les autres méthodes de configuration de la récupération récursive des sous-module (comme les paramètres de gitmodules[5] et git-config[1]) remplacent cette option, tout comme le fait de spécifier directement --[no-]recurse-submodules.

-u
--update-head-ok

Par défaut, git fetch refuse de mettre à jour la tête qui correspond à la branche en cours. Ce drapeau désactive la vérification. C’est purement pour l’usage interne de git pull pour communiquer avec git fetch, et à moins que vous n’implémentiez votre propre Porcelaine, vous n’êtes pas censé l’utiliser.

--upload-pack <upload-pack>

Lorsqu’il est donné, et que le dépôt à récupérer est géré par git fetch-pack, --exec=<upload-pack> est passé à la commande pour spécifier le chemin par défaut pour la commande exécutée à l’autre bout.

-q
--quiet

Passer --quiet pour git-fetch-pack et faire taire toute autre commande git utilisée en interne. La progression n’est pas signalée dans le flux d’erreurs standard.

-v
--verbose

Mode bavard.

--progress

L’état d’avancement est affiché sur la sortie d’erreur standard quand elle est attachée à un terminal, à moins que -q soit spécifié. Ce drapeau force l’état d’avancement même si le flux d’erreur standard n’est pas dirigé vers un terminal.

-o <option>
--server-option=<option>

Transmettre la chaîne donnée au serveur lors d’une communication utilisant la version 2 du protocole. La chaîne donnée ne doit pas contenir de caractère NUL ou LF. La gestion par le serveur des options du serveur, y compris les options inconnues, est spécifique au serveur. Lorsque plusieurs --server-option=<option> sont donnés, ils sont tous envoyés à l’autre côté dans l’ordre indiqué sur la ligne de commande.

--show-forced-updates

Par défaut, git vérifie si une branche est mise à jour de force pendant la récupération. Cela peut être désactivé via fetch.showForcedUpdates, mais l’option --show-forced-updates garantit que cette vérification a lieu. Voir git-config[1].

--no-show-forced-updates

Par défaut, git vérifie si une branche est mise à jour de force pendant la récupération. Passer --no-show-forced-updates ou régler fetch.showForcedUpdates à false pour sauter cette vérification pour des raisons de performance. Si elle est utilisée pendant git-pull, l’option --ff-only vérifiera toujours les mises à jour forcées avant de tenter une mise à jour rapide. Voir git-config[1].

-4
--ipv4

Utiliser uniquement les adresses IPv4, en ignorant les adresses IPv6.

-6
--ipv6

Utiliser uniquement les adresses IPv6, en ignorant les adresses IPv4.

<dépôt>

Le dépôt "distant" qui est la source d’une opération de récupération ou de tirage. Ce paramètre peut être soit une URL (voir la section URLS GIT ci-dessous) soit le nom d’un remote (voir la section DISTANTS ci-dessous).

<groupe>

Un nom faisant référence à une liste des dépôts comme la valeur de remotes.<groupe> dans le fichier de configuration. (voir git-config[1]).

<spécificateur-de-référence>

Préciser les références à récupérer et les références locales à mettre à jour. Lorsqu’aucun <spéc-de-réf> n’apparaît sur la ligne de commande, les références à récupérer sont lues à partir des variables remote.<dépôt>.fetch à la place (voir BRANCHES DE SUIVI À DISTANCE CONFIGURÉES ci-dessous).

Le format d’un paramètre <spéc-de-réf> est un plus + optionnel, suivi de la source <src>, suivi de deux points :, suivi de la destination ref <dst>. Les deux points peuvent être omis lorsque <dst> est vide. <src> est typiquement une réf, mais cela peut aussi être un nom d’objet hexadécimal entier.

Un <spec-de-réf> peut contenir un * dans son <src> pour indiquer une simple correspondance de motif. Un tel refspec fonctionne comme un motif qui correspond à n’importe quelle ref avec le même préfixe. Un motif <spec-de-réf> doit avoir un * dans les deux <src> et <dst>. Il va faire correspondre les références à la destination en remplaçant le * par le contenu correspondant de la source.

Si un spécificateur de référence est préfixé par ^, il sera interprété comme un spécificateur de référence négatif. Plutôt que de spécifier les références à récupérer ou les références locales à mettre à jour, un tel spécificateur de référence spécifiera les références à exclure. Une référence sera considérée comme correspondante si elle correspond à au moins une référence positive, et ne correspond à aucune référence négative. Les spécificateurs de référence négatifs peuvent être utiles pour restreindre le champ d’application d’un spécificateur modèle de référence afin qu’il n’inclue pas de références spécifiques. Les spécificateurs de référence négatifs peuvent eux-mêmes être des spécificateurs modèles de référence . Cependant, ils ne peuvent contenir qu’un <src> et ne peuvent pas spécifier un <dst>. Les noms d’objets hexagonaux complets ne sont pas non plus pris en charge.

tag <étiquette> signifie la même chose que refs/tags/<tag>:refs/tags/<tag> ; cela demande de tout récupérer jusqu’à l’étiquette donnée.

La référence distante qui correspond à <src> est récupérée, et si <dst> n’est pas une chaîne vide, une tentative est faite pour mettre à jour la référence locale qui lui correspond.

Le fait que cette mise à jour soit autorisée sans --force dépend de l’espace de noms de référence vers lequel elle est récupérée, du type d’objet récupéré, et si la mise à jour est considérée comme une avance rapide. Généralement, les mêmes règles s’appliquent pour la récupération que pour la poussée, voir la section <spéc-de-réf>... de git-push[1] pour les connaître. Les exceptions à ces règles particulières à git fetch sont notées ci-dessous.

Jusqu’à la version 2.20 de Git, et contrairement à ce qui se passe avec git-push[1], toute mise à jour de refs/tags/* serait acceptée sans + dans la spéc-de-réf (ou --force). Lors de la récupération, nous considérons sans distinction toutes les mises à jour d’étiquettes depuis un dépôt distance comme des récupérations forcées. Depuis la version 2.20 de Git, la récupération pour mettre à jour les refs/tags/* fonctionne de la même manière que lors de la poussée. C’est-à-dire que toute mise à jour sera rejetée sans "+" dans le spécificateur de référence (ou --force).

Contrairement à une poussée avec git-push[1], toute mise à jour en dehors de refs/{tags,heads}/* sera acceptée sans + dans le spéc-de-réf (ou --force), que ce soit en échangeant par exemple un objet arbre pour un blob, ou un commit pour un autre commit qui n’a pas le commit précédent comme ancêtre etc.

Contrairement à une poussée avec git-push[1], il n’y a pas de configuration qui modifie ces règles, et rien de tel qu’un crochet pré-récupération pre-fetch analogue à celui de pré-réception`pre-receive`.

Comme pour la poussée avec git-push[1], toutes les règles décrites ci-dessus concernant ce qui n’est pas autorisé comme une mise à jour, peuvent être annulées en ajoutant un "+" optionnel à un spécificateur de référence (ou en utilisant l’option de ligne de commande --force). La seule exception à cette règle est qu’aucun forçage ne fera accepter à l’espace de noms refs/heads/* un objet non commit.

Note
 Lorsque la branche distante que vous voulez récupérer est connue pour être régulièrement rembobinée et rebasée, on s’attend à ce que son nouveau sommet ne soit pas un descendant de son sommet précédent (telle qu’il était stocké dans votre branche de suivi à distance la dernière fois que vous l’avez récupéré). Vous pouvez utiliser le signe "+" pour indiquer que des mises à jour non en avance rapide seront nécessaires pour ces branches. Il n’y a aucun moyen de déterminer ou de déclarer qu’une branche sera rendue disponible dans un dépôt avec ce comportement ; l’utilisateur qui tire doit simplement savoir que c’est le modèle d’utilisation attendu pour une branche.
--stdin

Lire les spécifications de référence, une par ligne, de stdin en plus de celles fournies comme arguments. Le format "tag <nom>" n’est pas pris en charge.

URL GIT

En général, les URL contiennent une information sur le protocole de transport, l’adresse du serveur distant et le chemin vers le dépôt. En fonction du protocole de transport, certaines de ces informations peuvent être absentes.

Git supporte les protocoles ssh, git, http et https (en plus, ftp et ftps peuvent être utilisés pour la récupération, mais ceux-ci sont inefficaces et déconseillés ; ne les utilisez pas).

Le transport natif (c’est-à-dire l’URL git://) n’utilise pas d’authentification et ne devrait être utilisé qu’avec précaution sur des réseaux non sécurisés.

Les syntaxes suivantes peuvent être utilisées avec eux :

  • ssh://[<utilisateur>@]<hôte>[:<port>]/<chemin-du-dépôt-git>

  • git://<hôte>[:<port>]/<chemin-du-dépôt-git>

  • http[s]://<hôtet>[:<port>]/<chemin-du-dépôt-git>

  • ftp[s]://<hôte>[:<port>]/<chemin-du-dépôt-git>

Une syntaxe alternative de type scp peut aussi être utilisée pour le protocole ssh :

  • [<utilisateur>@]<hôte>:/<chemin-du-dépôt-git>

Cette syntaxe n’est reconnue que s’il n’y a pas de barre oblique devant les premiers deux-points. Cela permet de prendre en charge des chemins locaux qui contiendraient des deux-points. Par exemple, le chemin local toto:titi pourrait être spécifié comme un chemin absolu ou ./toto:titi pour éviter d’être interprété comme une url ssh.

Les protocoles ssh et git supportent en plus l’expansion ~<utilisateur>  :

  • ssh://[<utilisateur>@]<hôte>[:<port>]/~<utilisateur>/<chemin-du-dépôt-git>

  • git://<hôte>[:<port>]/~<utilisateur>/<chemin-du-dépôt-git>

  • [<utilisateur>@]<hôte>:~<utilisateur>/<chemin-du-dépôt-git>

Pour les dépôts locaux, supportés aussi nativement par Git, les syntaxes suivantes sont aussi admises :

Ces deux syntaxes sont à peu près équivalentes, à part lors d’un clonage, où la première implique l’option --local. Voir git-clone[1] pour plus de détails.

git clone, git fetch et git pull, mais pas git push, acceptent également un fichier paquet approprié. Voir git-bundle[1].

Quand Git ne sait pas comment gérer un certain protocole, il essaie d’utiliser l’assistant de gestion de distant remote-<transport>, s’il existe. Pour requérir l’emploi d’un assistant spécifique, la syntaxe suivante peut être utilisée :

  • <transport>::<adresse>

où <adresse> peut être un chemin, un serveur et chemin, ou une chaîne URL arbitraire reconnue par l’assistant de gestion de distant invoqué. Voir gitremote-helpers[7] pour plus de détails.

S’il y a un grand nombre de dépôts aux noms similaires et que vous souhaitez utiliser un format différent pour eux (de telle sorte que les URL que vous utiliserez seront réécrites en URL fonctionnelles), vous pouvez créer une section de configuration de la forme :

	[url "<veritable-base-d-url>"]
		insteadOf = <autre-base-d’URL>

Par exemple, avec ceci :

	[url "git://git.host.xz/"]
		insteadOf = host.xz:/chemin/vers/
		insteadOf = travail:

une URL comme « travail:depot.git » ou « host.xz:/chemin/vers/depot.git » sera réécrite dans tout contexte qui requiert une URL en « git://git.host.xz/depot.git ».

Si vous souhaitez réécrire les URL seulement pour pousser, vous pouvez créer une section de configuration de la forme :

	[url "<veritable-base-d’URL>"]
		pushInsteadOf = <autre-base-d-URL>

Par exemple, avec ceci :

	[url "ssh://exemple.org/"]
		pushInsteadOf = git://exemple.org/

une URL telle que « git://exemple.org/chemin/vers/le/depot.git » sera réécrite en « ssh://exemple.org/chemin/vers/le/depot.git » pour les poussées, mais les tirages utiliseront encore l’URL originale.

DISTANTS

Le nom de l’un des éléments suivants peut être utilisé à la place d’une URL en tant qu’argument <dépôt> :

  • un distant dans le fichier de configuration Git : $GIT_DIR/config,

  • un fichier dans le répertoire $GIT_DIR/remotes, ou

  • un fichier dans le répertoire $GIT_DIR/branches.

Toutes ces options vous permettent également d’omettre le spécificateur de référence de la ligne de commande car elles contiennent chacune un spécificateur de référence que git utilisera par défaut.

distant nommé dans le fichier de configuration

Vous pouvez choisir de fournir le nom d’un distant que vous aviez précédemment configuré en utilisant git-remote[1], git-config[1] ou même par une modification manuelle du fichier $GIT_DIR/config. L’URL de ce distant sera utilisée pour accéder au dépôt. Le spécificateur de référence de ce distant sera utilisé par défaut lorsque vous ne fournissez pas de spécificateur de référence sur la ligne de commande. L’entrée dans le fichier de configuration apparaîtra comme ceci :

	[remote "<nom>"]
		url = <URL>
		pushurl = <url-poussée>
		push = <spéc-de-réf>
		fetch = <spéc-de-réf>

Le <url-de-poussée> est utilisé uniquement pour les poussées. Il est optionnel et sa valeur par défaut est <URL>. Pousser vers un distant affecte tous les urls-de-poussés définis ou tous les urls définis si aucun url-de-poussée n’est défini. Fetch, cependant, ne récupérera que le premier url défini si plusieurs urls sont définis.

Fichier nommé dans $GIT_DIR/remotes

Vous pouvez choisir de fournir le nom d’un fichier dans $GIT_DIR/remotes. L’URL dans ce fichier sera utilisée pour accéder au dépôt. Le spécificateur de référence dans ce fichier sera utilisé par défaut lorsque vous ne fournissez pas de spécificateur de référence sur la ligne de commande. Ce fichier doit avoir le format suivant :

	URL: un des format d'URL ci-dessus
	Push: <spéc-de-réf>
	Pull: <spéc-de-réf>

Les lignes Push:" sont utilisées par git push et les lignes Pull: sont utilisées par git pull et git fetch. Des lignes Push: et Pull: multiples peuvent être spécifiées pour des mappages supplémentaires de branches.

Fichier nommé dans $GIT_DIR/branches

Vous pouvez choisir de fournir le nom d’un fichier dans $GIT_DIR/branches. L’URL de ce fichier sera utilisée pour accéder au dépôt. Ce fichier doit avoir le format suivant :

	<URL>#<tête>

<URL> est obligatoire ; #<tête> est facultatif.

En fonction de l’opération, git utilisera l’un des spécificateurs de référence suivants, si vous n’en fournissez pas un en ligne de commande. <branche> est le nom de ce fichier dans $GIT_DIR/branches et <tête> vaut par défaut master.

git fetch utilise :

	refs/heads/<tête>:refs/heads/<branche>

git push utilise :

	HEAD:refs/heads/<tête>

LES BRANCHES DE SUIVI À DISTANCE CONFIGURÉES

Vous interagissez souvent avec le même dépôt distant en y allant régulièrement et de manière répétée. Afin de suivre la progression d’un tel dépôt distant, git fetch vous permet de configurer les variables de configuration remote.<dépôt>.fetch.

En général, une telle variable peut ressembler à ceci :

[remote "origin"]
	fetch = +refs/heads/*:refs/remotes/origin/*

Cette configuration est utilisée de deux façons :

  • Lorsque git fetch est lancé sans spécifier les branches et/ou les étiquettes à récupérer en ligne de commande, par exemple git fetch origin ou git fetch, les valeurs remote.<dépôt>.fetch sont utilisées comme spéc-de-réf --elles spécifient quelles réfs à récupérer et quelles réfs locales à mettre à jour. L’exemple ci-dessus va chercher toutes les branches qui existent dans origin (c’est-à-dire toute réf qui correspond au côté gauche de la valeur, "refs/heads/*") et mettre à jour les branches de suivi à distance correspondantes dans la hiérarchie refs/remotes/origin/*.

  • Lorsque git fetch est lancé avec des branches et/ou des étiquettes explicites à récupérer en ligne de commande, par exemple git fetch origin master, les <spéc-de-réf>s données en ligne de commande déterminent ce qui doit être récupéré (par exemple master dans l’exemple, qui est un raccourci pour master:, ce qui signifie "chercher la branche master mais je ne dis pas explicitement quelle branche de suivi à distance mettre à jour avec elle depuis la ligne de commande"), et la commande de l’exemple ne cherchera que la branche master. Les valeurs de remote.<dépôt>.fetch déterminent quelle branche de suivi à distance, s’il y en a une, est mise à jour. Lorsqu’elles sont utilisées de cette façon, les valeurs de remote.<dépôt>.fetch n’ont aucun effet sur la décision de ce qui est récupéré (c’est-à-dire que les valeurs ne sont pas utilisées comme spéc-de-réf lorsque la ligne de commande liste les spéc-de-réfs) ; elles ne sont utilisées que pour décider de l’endroit où les réfs qui sont récupérées sont stockées en agissant comme une table de correspondance.

Cette dernière utilisation des valeurs de remote.<dépôt>.fetch peut être écrasée en donnant le(s) paramètre(s) --refmap=<spéc-de-réf> sur la ligne de commande.

ÉLAGAGE

Par défaut, Git conserve les données à moins qu’elles ne soient explicitement jetées ; cela s’étend à la conservation des références locales aux branches des distants qui ont eux-mêmes supprimé ces branches.

Si on les laisse s’accumuler, ces références périmées pourraient rendre les performances mauvaises sur les gros dépôt qui ont beaucoup de branches, et par exemple rendre la sortie de commandes comme git branch -a --contains <commit> inutilement verbeuse, ainsi qu’avoir un impact sur tout ce qui travaillera avec l’ensemble des références connues.

Ces références de suivi à distance peuvent être supprimées une seule fois avec l’une ou l’autre des commandes suivantes :

# Pendant la récupération
$ git fetch --prune <nom>

# Élaguer seulement, ne pas récupére
$ git remote prune <nom>

Pour élaguer les références dans le cadre de votre flux de travail normal sans avoir besoin de vous rappeler de l’exécuter, définissez fetch.prune globalement, ou remote.<nom>.prune pour chaque dépôt distant dans la configuration. Voir git-config[1].

C’est là que les choses deviennent délicates et plus spécifiques. La fonction d’élagage ne se préoccupe pas vraiment des branches, elle va plutôt élaguer les références locales ←→ à distance en fonction du spécificateur de référence du dépôt distant (voir <spéc-de-réf> et BRANCHES DE SUIVI À DISTANCE CONFIGURÉES ci-dessus).

Par conséquent, si le spécificateur de référence du serveur distant inclut par exemple refs/tags/*:refs/tags/*, ou si vous lancez manuellement par exemple git fetch --prune <nom> "refs/tags/*:refs/tags/*", ce ne seront pas les branches de suivi à distance qui seront supprimées, mais toute étiquette locale qui n’existe pas sur le serveur distant.

Ce n’est peut-être pas ce à quoi vous vous attendez, c’est-à-dire que vous voulez élaguer le server distant <nom>, mais aussi y récupérer explicitement des étiquettes, de sorte que lorsque vous le récupérez, vous supprimez toutes vos étiquettes locales, dont la plupart ne proviennent pas du dépôt distant <nom> au départ.

Soyez donc prudent lorsque vous utilisez un spécificateur de référence comme refs/tags/*:refs/tags/*, ou toute autre spécificateur de référence qui pourrait faire correspondre des références de plusieurs dépôts distants au même espace de noms local.

Étant donné que la mise à jour des branches et des étiquettes sur le dépôt distant est un cas d’utilisation courant, l’option --prune-tags peut être fournie avec --prune pour élaguer les étiquettes locales qui n’existent pas sur le dépôt distant, et forcer la mise à jour des étiquettes qui diffèrent. L’élagage des étiquettes peut également être activé avec fetch.pruneTags ou remote.<nom>.pruneTags dans la configuration. Voir git-config[1].

L’option --prune-tags est équivalente à avoir refs/tags/*:refs/tags/* déclaré dans les spécificateurs de référence du dépôt distant. Cela peut conduire à des interactions apparemment étranges :

# Ces deux ligne vont chercher les étiquettes
$ git fetch --no-tags origin 'refs/tags/*:refs/tags/*
$ git fetch --no-tags --prune-tags origin

La raison pour laquelle il ne génère pas d’erreur lorsqu’il est fourni sans --prune ou ses pendants en configuration est pour la flexibilité des versions configurées et pour maintenir un mappage 1 = 1 entre ce que font les drapeaux de ligne de commande et ce que font les versions de configuration.

Il est raisonnable, par exemple de configurer fetch.pruneTags = true dans` ~ / .gitconfig` pour que les étiquettes soient élaguées chaque fois que git fetch --prune est exécuté, sans que chaque appel de git fetch sans --prune soit une erreur.

L’élagage des étiquettes avec --prune-tags fonctionne également lors de la récupération d’une URL au lieu d’un dépôt distant nommé. Toutes ces lignes élagueront les étiquettes non trouvées sur origin :

$ git fetch origin --prune --prune-tags
$ git fetch origin --prune 'refs/tags/*:refs/tags/*
$ git fetch <url-d-origin> --prune --prune-tags
$ git fetch <url-d-origin> --prune 'refs/tags/*:refs/tags/*

SORTIE

La sortie de "git fetch" dépend de la méthode de transport utilisée ; cette section décrit la sortie lors de la récupération sur le protocole Git (soit localement soit via ssh) et le protocole Smart HTTP.

L’état de la récupération est affiché sous forme de tableau, chaque ligne représentant l’état d’une seule référence. Chaque ligne est de la forme :

 <drapeau> <résumé> <de> -> <à> [<raison>]

Lorsque vous utilisez --porcelain, le format de sortie est destiné à être analysé par la machine. Contrairement aux formats de sortie lisibles par l’homme, il s’imprime donc sur la sortie standard au lieu de l’erreur standard. Chaque ligne est de la forme :

<drapeau> <ancien-id-objet> <nouveau-id-objet> <référence-locale>

L’état des références à jour n’est affiché que si l’option --verbose est utilisée.

En mode de sortie compact, spécifié avec la variable de configuration fetch.output, si l’un des deux <de> ou <à> est trouvé dans l’autre chaîne, il sera substitué par * dans l’autre chaîne. Par exemple, master -> origin/master devient master -> origin/*.

drapeau

Un seul caractère indiquant le statut de la référence :

(espace)

pour une récupération en avance rapide réussie ;

+

pour une mise à jour forcée avec succès ;

-

pour une ref. élaguée avec succès ;

t

pour une mise à jour d’étiquette avec succès ;

*

pour la récupération réussie d’une nouvelle réf. ;

!

pour une référence qui a été rejetée ou qui n’a pas pu être mise à jour ; et

=

pour une référence qui était à jour et n’avait pas besoin d’être récupérée.

résumé

Pour une réf récupérée avec succès, le résumé montre les anciennes et les nouvelles valeurs de la réf sous une forme qui peut être utilisée comme argument pour git log (c’est <ancien>..<nouveau> dans la plupart des cas, et <ancien>...<nouveau> pour les mises à jour forcées pas en avance rapide).

de

Le nom de la référence distante récupérée, moins son préfixe "refs/<type>/". En cas de suppression, le nom de la référence distante est "(none)".

à

Le nom de la référence locale en cours de mise à jour, moins son préfixe refs/<type>/.

raison

Une explication compréhensible. Dans le cas des références qui ont été récupérées avec succès, aucune explication n’est nécessaire. Dans le cas d’une référence en échec, la raison de l’échec est décrite.

EXEMPLES

  • Mettre à jour les branches de suivi distantes :

    $ git fetch origin

    La commande ci-dessus copie toutes les branches de l’espace de nom distant refs/heads/ et les stocke dans l’espace de noms local refs/remotes/origin/, sauf si l’option remote. <dépôt> .fetch est utilisée pour spécifier un spécificateur de référence autre que celui par défaut.

  • En utilisant explicitement les spécificateurs de référence :

    $ git fetch origin +seen:seen maint:tmp

    Cela met à jour (ou crée, si nécessaire) les branches seen et tmp dans le dépôt local en récupérant (respectivement) les branches seen et maint dans le dépôt distant.

    La branche seen sera mise à jour même si ce n’est pas en avance rapide, car elle est préfixée par un signe plus ; tmp ne le sera pas.

  • Jette un coup d’œil à la branche d’un dépôt distant, sans configurer le distant dans votre dépôt local :

    $ git fetch git://git.kernel.org/pub/scm/git/git.git maint
$ git log FETCH_HEAD

    La première commande récupère la branche maint dans le dépôt à git://git.kernel.org/pub/scm/git/git.git et la seconde commande utilise FETCH_HEAD pour examiner la branche avec git-log[1]. Les objets récupérés seront éventuellement supprimés par le service d’entretien intégré de git (voir git-gc[1]).

SÉCURITÉ

Les protocoles "fetch" et "push" ne sont pas conçus pour empêcher un tiers de voler des données de l’autre dépôt qui n’étaient pas destinées à être partagées. Si vous avez des données privées que vous devez protéger contre un tiers malveillant, la meilleure solution est de les stocker dans un autre dépôt. Cela s’applique aussi bien aux clients qu’aux serveurs. En particulier, les espaces de noms sur un serveur ne sont pas efficaces pour le contrôle de l’accès en lecture ; vous ne devez accorder l’accès en lecture à un espace de noms qu’aux clients auxquels vous feriez confiance pour l’accès en lecture à l’ensemble du dépôt.

Les vecteurs d’attaque connus sont les suivants :

  1. La victime envoie des lignes "have" annonçant les identifiants des objets qu’elle possède et qui ne sont pas explicitement destinés à être partagés, mais qui peuvent être utilisés pour optimiser le transfert si le pair les possède également. L’attaquant choisit un ID d’objet X à voler et envoie une référence à X, mais n’est pas obligé d’envoyer le contenu de X parce que la victime l’a déjà. La victime croit maintenant que l’attaquant a X, et elle lui renvoie le contenu de X plus tard. (Cette attaque est la plus simple à réaliser pour un client sur un serveur, en créant une référence à X dans l’espace de noms auquel le client a accès et en la récupérant ensuite. La façon la plus probable pour un serveur de l’exécuter sur un client est de "fusionner" X dans une branche publique et d’espérer que l’utilisateur fasse un travail supplémentaire sur cette branche et la repousse vers le serveur sans remarquer la fusion).

  2. Comme en n°1, l’attaquant choisit un objet ID X à voler. La victime envoie un objet Y que l’attaquant possède déjà, et l’attaquant prétend faussement avoir X et non Y, de sorte que la victime envoie Y comme delta contre X. Le delta révèle à l’attaquant des régions de X qui sont similaires à Y.

CONFIGURATION

Warning

Missing fr/includes/cmd-config-section-all.txt

See original version for this content.
Warning

Missing fr/config/fetch.txt

See original version for this content.

BOGUES

L’utilisation de --recurse-submodules ne permet actuellement d’obtenir de nouveaux commits que dans les sous-modules qui sont présents par exemple dans $GIT_DIR/modules/. Lorsqu’un nouveau sous-module est ajouté en amont, le sous-module lui-même ne peut pas être récupéré, ce qui rend impossible de vérifier ce sous-module plus tard sans avoir à le récupérer à nouveau. Ce problème devrait être corrigé dans une prochaine version de Git.

VOIR AUSSI

git-pull[1]

GIT

Fait partie de la suite git[1]

TRADUCTION

Cette page de manuel a été traduite par Jean-Noël Avila <jn.avila AT free DOT fr> et les membres du projet git-manpages-l10n. Veuillez signaler toute erreur de traduction par un rapport de bogue sur le site https://github.com/jnavila/git-manpages-l10n .

scroll-to-top