Git
Français ▾ Topics ▾ Latest version ▾ git-submodule last updated in 2.44.0

NOM

git-submodule - Initialisation, mise à jour ou inspection des sous-modules

SYNOPSIS

git submodule [--quiet] [--cached]
git submodule [--quiet] add [<options>] [--] <dépôt> [<chemin>]
git submodule [--quiet] status [--cached] [--recursive] [--] [<chemin>…​]
git submodule [--quiet] init [--] [<chemin>…​]
git submodule [--quiet] deinit [-f|--force] (--all|[--] <chemin>…​)
git submodule [--quiet] update [<options>] [--] [<chemin>…​]
git submodule [--quiet] set-branch [<options>] [--] <chemin>
git submodule [--quiet] set-url [--] <chemin> <nouvelle-url>
git submodule [--quiet] summary [<options>] [--] [<chemin>…​]
git submodule [--quiet] foreach [--recursive] <commande>
git submodule [--quiet] sync [--recursive] [--] [<chemin>…​]
git submodule [--quiet] absorbgitdirs [--] [<chemin>…​]

DESCRIPTION

Inspecte, met à jour et gère les sous-modules.

Pour plus d’informations sur les sous-modules, voir gitsubmodules[7].

COMMANDES

Sans arguments, montrer l’état des sous-modules existants. Plusieurs sous-commandes sont disponibles pour effectuer des opérations sur les sous-modules.

add [-b <branche>] [-f|--force] [--name <nom>] [--reference <dépôt>] [--depth <profondeur>] [--] <dépôt> [<chemin>]

Ajouter le dépôt donné comme sous-module au chemin donné vers les modifications à valider à côté du projet en cours : le projet en cours est appelé « superprojet ».

<dépôt> est l’URL du dépôt d’origine du nouveau sous-module. Il peut s’agir soit d’une URL absolue, soit (si elle commence par ./ ou ../) de l’emplacement par rapport au dépôt distant par défaut du superprojet (veuillez noter que pour spécifier un dépôt foo.git, voisin d’un superprojet bar.git, vous devrez utiliser ../foo.git au lieu de ./foo.git - comme on pourrait s’y attendre en suivant les règles pour les URL relatives - car l’évaluation des URL relatives dans Git est identique à celle des répertoires relatifs).

Le distant par défaut est le distant de la branche de suivi à distance de la branche actuelle. Si une telle branche de suivi à distance n’existe pas ou si HEAD est détachée, "origin" est supposé être le distant par défaut. Si le superprojet n’a pas de distant par défaut configuré, le superprojet est l’amont d’autorité et le répertoire de travail actuel est utilisé à la place.

L’argument facultatif <chemin> est l’emplacement relatif du sous-module cloné dans le superprojet. Si <chemin> n’est pas donné, la partie canonique du dépôt de sources est utilisée ("depot" pour "/chemin/du/depot.git" et "foo" pour "hote.xz:foo/.git"). Si <chemin> existe et est déjà un dépôt Git valide, alors il est indexé pour le commit sans clonage. Le <chemin> est également utilisé comme nom logique du sous-module dans ses entrées de configuration, sauf si --name est utilisé pour spécifier un nom logique.

L’URL donnée est enregistrée dans .gitmodules pour être utilisée par les utilisateurs qui clonent le superprojet plus tard. Si l’URL est donnée par rapport au dépôt du superprojet, on suppose que les dépôts du superprojet et du sous-module seront conservés ensemble au même emplacement relatif, et que seule l’URL du superprojet doit être fournie. git-submodule localisera correctement le sous-module en utilisant l’URL relative dans .gitmodules.

status [--cached] [--recursive] [--] [<chemin>…​]

Afficher le statut des sous-modules. Cela affichera le SHA-1 du commit actuellement extrait pour chaque sous-module, ainsi que le chemin du sous-module et la sortie de git describe pour le SHA-1. Chaque SHA-1 sera éventuellement préfixé par - si le sous-module n’est pas initialisé, + si le commit du sous-module actuellement extrait ne correspond pas au SHA-1 trouvé dans l’index du dépôt contenant et U si le sous-module a des conflits de fusion.

Si --cached est spécifié, cette commande imprimera à la place le SHA-1 enregistre dans le superprojet pour chaque sous-module.

Si --recursive est spécifié, cette commande va parcourir récursivement les sous-modules imbriqués, et montrer leur statut également.

Si vous n’êtes intéressé que par les modifications des sous-modules actuellement initialisés par rapport au commit enregistré dans l’index ou dans HEAD, git-status[1] et git-diff[1] vous fourniront également ces informations (et peuvent également signaler les modifications de l’arbre de travail d’un sous-module).

init [--] [<chemin>…​]

Initialiser les sous-modules enregistrés dans l’index (qui ont été ajoutés et validés ailleurs) en définissant submodule.$nom.url dans .git/config, en utilisant le même paramètre de .gitmodules comme modèle. Si l’URL est relative, elle sera résolue en utilisant le distant par défaut. S’il n’y a pas de distant par défaut, le dépôt actuel sera supposé être en amont.

Les arguments facultatifs <chemin> limitent les sous-modules qui seront initialisés. Si aucun chemin n’est spécifié et que submodule.active a été configuré, les sous-modules configurés pour être actifs seront initialisés, sinon tous les sous-modules sont initialisés.

La valeur de submodule.$name.update`sera aussi copiée, si présente dans le fichier `.gitmodules, dans .git/config, mais (1) cette commande ne modifie pas les informations existantes dans .git/config, et (2) submodule.$name.update qui est défini à une commande personnalisée n’est pas copié pour des raisons de sécurité.

Lorsqu’il est présent, copie également la valeur de submodule.$nom.update. Cette commande ne modifie pas les informations existantes dans le fichier .git/config. Vous pouvez ensuite personnaliser les URL de clonage de sous-module dans .git/config pour votre configuration locale et passer à git submodule update ; vous pouvez aussi simplement utiliser git submodule update --init sans l’étape explicite init si vous n’avez pas l’intention de personnaliser l’emplacement des sous-module.

Voir la sous-commande d’ajout pour la définition du distant par défaut.

deinit [-f|--force] (--all|[--] <chemin>…​)

Désenregistrez les sous-modules donnés, c’est-à-dire supprimez toute la section submodule.$name de .git/config ainsi que leur arborescence de travail. Les appels ultérieurs à git submodule update, git submodule foreach et git submodule sync ignoreront tous les sous-modules non enregistrés jusqu’à ce qu’ils soient initialisés à nouveau, donc utilisez cette commande si vous ne voulez plus avoir de vérification locale du sous-module dans votre arbre de travail.

Lorsque la commande est exécutée sans pathspec, elle sort en erreur, au lieu de tout dé-initialiser, pour éviter les erreurs.

Si --force est spécifié, l’arbre de travail du sous-module sera supprimé même s’il contient des modifications locales.

Si vous voulez vraiment supprimer un sous-module du dépôt et valider le résultat, utilisez plutôt git-rm[1]. Voir gitsubmodules[7] pour les options de suppression.

update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <dépôt>] [--depth <profondeur>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <spéc-de-filtre>] [--] [<chemin>…​]

Mettre à jour les sous-modules enregistrés pour qu’ils correspondent aux attentes du superprojet en clonant les sous-modules manquants, en récupérant les commits manquants dans les sous-modules et en mettant à jour l’arbre de travail des sous-modules. La "mise à jour" peut être effectuée de plusieurs façons, en fonction des options de la ligne de commande et de la valeur de la variable de configuration submodule.<nom>.update. L’option de ligne de commande a la priorité sur la variable de configuration. Si aucune des deux n’est donnée, un checkout est effectué. (note : ce qui est dans le fichier`.gitmodules` n’est pas pertinent à ce point ; voir git submodule init ci-dessus pour comment .gitmodules est utilisé). Les procédures de 'update’supportées aussi bien en ligne de commande que par la configuration `submodule.<nom>.update`sont :

checkout

le commit enregistré dans le superprojet sera extrait dans le sous-module sur une HEAD détachée.

Si --force est spécifié, le sous-module sera extrait (en utilisant git checkout --force), même si le commit spécifié dans l’index du dépôt contenant correspond déjà au commit extrait dans le sous-module.

rebase

la branche actuelle du sous-module sera rebasée sur le commit enregistré dans le superprojet.

merge

le commit enregistré dans le superprojet sera fusionné dans la branche actuelle dans le sous-module.

Les procédures de mise à jour suivantes ont des limites supplémentaires :

commande personnalisée

mécanisme pour exécuter des commandes arbitraires avec l’ID de commit comme argument. Plus précisément, si la variable de configuration submodule<nom>.update à !<commande personnalisée>', le nom de l’objet enregistré dans le superprojet pour le sous-module est ajouté à la fin de la chaîne <commande personnalisée> et celle-ci est exécutée. Notez que ce mécanisme n’est pas pris en charge dans le fichier .gitmodules ou sur la ligne de commande.

none

le sous-module n’est pas mis à jour. Cette procédure de mise à jour n’est pas autorisée sur la ligne de commande.

Si le sous-module n’est pas encore initialisé, et que vous souhaitez simplement utiliser le paramètre stocké dans .gitmodules, vous pouvez initialiser automatiquement le sous-module avec l’option --init.

Si --recursive est spécifié, cette commande va parcourir récursivement les sous-modules enregistrés, et mettre à jour tous les sous-modules imbriqués à l’intérieur.

Si --filter <spéc-de-filtre> est spécifié, le filtre de clone partiel donné sera appliqué au sous-module. Voir git-rev-list[1] pour plus de détails sur les spécifications du filtre.

set-branch (-b|--branch) <branche> [--] <chemin>
set-branch (-d|--default) [--] <chemin>

Définir la branche distante par défaut pour le sous-module. L’option --branch permet de spécifier la branche distante. L’option --default supprime la clé de configuration submodule.<nom>.branch, ce qui fait que la branche de suivi par défaut est la branche HEAD distante .

set-url [--] <chemin> <nouvelle-url>

Fixer l’URL du sous-module spécifié à <nouvelle-url>. Ensuite, il synchronisera automatiquement la nouvelle configuration de l’URL distante du sous-module.

summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<chemin>…​]

Afficher le résumé du commit entre le commit donné (par défaut HEAD) et l’arbre de travail/index. Pour un sous-module en question, une série de commits dans le sous-module entre le commit donné du super projet et l’index ou l’arbre de travail (commuté par --cached) sont affichés. Si l’option --files est donnée, afficher la série de commits dans le sous-module entre l’index du super projet et l’arbre de travail du sous-module (cette option ne permet pas d’utiliser l’option --cached ou de fournir un commit explicite).

L’utilisation de l’option --submodule=log avec git-diff[1] fournira également cette information.

foreach [--recursive] <commande>

Évaluer une commande shell arbitraire dans chaque sous-module extrait. La commande a accès aux variables $name, $sm_path, $displaypath, $sha1 et $toplevel : $name est le nom de la section du sous-module concernée dans .gitmodules, $sm_path est le chemin du sous-module tel qu’il est enregistré dans le superprojet immédiat, $displaypath contient le chemin relatif du répertoire de travail courant au répertoire racine du sous-modules, $sha1 est le commit tel qu’il est enregistré dans le superprojet immédiat, et $toplevel est le chemin absolu vers le niveau supérieur du superprojet immédiat. Notez que pour éviter les conflits avec $PATH sous Windows, la variable $path est maintenant un synonyme obsolète de la variable $sm_path. Tous les sous-modules définis dans le superprojet mais non extraits sont ignorés par cette commande. A moins qu’on ne lui donne --quiet, foreach imprime le nom de chaque sous-module avant d’évaluer la commande. Si la variable --recursive est donnée, les sous-modules sont parcourus de manière récursive (c’est-à-dire que la commande shell donnée est également évaluée dans les sous-modules imbriqués). Un retour non nul de la commande dans un sous-module quelconque entraîne l’arrêt du traitement. Il est possible d’y remédier en ajoutant || : à la fin de la commande.

À titre d’exemple, la commande ci-dessous indique le chemin et le commit actuellement extrait pour chaque sous-module :

git submodule foreach 'echo $sm_path `git rev-parse HEAD`'
sync [--recursive] [--] [<chemin>…​]

Synchroniser le paramètre de configuration de l’URL distante des sous-modules à la valeur spécifiée dans .gitmodules. Cela n’affectera que les sous-modules qui ont déjà une entrée d’URL dans .git/config (c’est le cas lorsqu’ils sont initialisés ou fraîchement ajoutés). Ceci est utile lorsque les URL des sous-modules changent en amont et que vous devez mettre à jour vos dépôts locaux en conséquence.

git submodule sync synchronise tous les sous-modules tandis que git submodule sync -- A synchronise uniquement le sous-module "A".

Si --recursive est spécifié, cette commande va parcourir récursivement les sous-modules enregistrés, et synchroniser tous les sous-modules imbriqués à l’intérieur.

absorbgitdirs

Si un répertoire git d’un sous-module se trouve à l’intérieur du sous-module, déplacer le répertoire git du sous-module dans le chemin $GIT_DIR/modules de son superprojet, puis connecter le répertoire git et son répertoire de travail en définissant le core.worktree et en ajoutant un fichier .git pointant sur le répertoire git intégré dans le répertoire git du superprojet.

Un dépôt qui a été cloné indépendamment et ajouté plus tard comme un sous-module ou d’anciennes configurations, a le répertoire git des sous-modules à l’intérieur du sous-module au lieu d’être intégré dans le répertoire git des superprojets.

Cette commande est récursive par défaut.

OPTIONS

-q
--quiet

N’afficher que les messages d’erreur.

--progress

Cette option n’est valide que pour les commandes add et update. L’état d’avancement est affiché sur la sortie d’erreur standard par défaut 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.

--all

Cette option n’est valide que pour la commande deinit. Désenregistrer tous les sous-modules dans l’arbre de travail.

-b <branche>
--branch <branche>

Branche du dépôt à ajouter comme sous-module. Le nom de la branche est enregistré comme submodule.<nom>.branch dans .gitmodules pour update--remote. Une valeur spéciale de . est utilisée pour indiquer que le nom de la branche dans le sous-module doit être le même que celui de la branche active dans le dépôt actuel. Si l’option n’est pas spécifiée, la valeur par défaut est HEAD distant.

-f
--force

Cette option n’est valable que pour les commandes add, deinit et update. Lors de l’exécution de la commande add, autorisez l’ajout d’un chemin de sous-module autrement ignoré. Lors de l’exécution de deinit, les arbres de travail des sous-module seront supprimés même s’ils contiennent des modifications locales. Lors de l’exécution de update (uniquement active avec la procédure de checkout), jeter les modifications locales dans les sous-module lors du passage à un commit différent ; et toujours exécuter une opération d’extraction dans le sous-module, même si le commit listé dans l’index du dépôt le contenant correspond au commit extrait dans le sous-module.

--cached

Cette option n’est valide que pour les commandes d’état et de résumé. Ces commandes utilisent généralement le commit trouvé dans la HEAD du sous-module, mais avec cette option, le commit stocké dans l’index est utilisé à la place.

--files

Cette option n’est valable que pour la commande summary. Cette commande compare le commit dans l’index avec celui du sous-module HEAD lorsque cette option est utilisée.

-n
--summary-limit

Cette option n’est valable que pour la commande summary. Limiter la taille du résumé (nombre de validations affichées au total). Donner 0 désactivera le résumé ; un nombre négatif signifie illimité (par défaut). Cette limite ne s’applique qu’aux sous-modules modifiés. La taille est toujours limitée à 1 pour les sous-modules ajoutés/supprimés/modifiés.

--remote

Cette option n’est valable que pour la commande de mise à jour. Au lieu d’utiliser le SHA-1 enregistrée du superprojet pour mettre à jour le sous-module, utiliser le statut de la branche de suivi à distance du sous-module. Le distant utilisé est le distant de la branche (branch.<nom>.remote), dont la valeur par défaut est origin. La branche distante utilisée est par défaut la branche distante HEAD, mais le nom de la branche peut être remplacé par l’option submodule.<nom>.branch dans .gitmodules ou .git/config (avec .git/config en priorité).

Cela fonctionne pour toutes les procédures de mise à jour prises en charge (--checkout, --rebase, etc.). Le seul changement est la source de la cible SHA-1. Par exemple, submodule update --remote --merge fusionnera les changements de sous-module en amont dans les sous-modules, tandis que submodule update --merge fusionnera les changements du superprojet de gitlink dans les sous-modules.

Afin d’assurer un état actuel de la branche de suivi, update --remote va chercher le dépôt distant du sous-module avant de calculer le SHA-1. Si vous ne voulez pas récupérer, vous devez utiliser submodule update --remote --no-fetch.

Utiliser cette option pour intégrer les changements du sous-projet en amont dans la HEAD actuelle de votre sous-module. Alternativement, vous pouvez lancer git pull depuis le sous-module, qui est équivalent à l’exception du nom de la branche distante : update --remote utilise le dépôt amont par défaut et submodule.<nom>.branch, alors que git pull utilise le branch.<nom>.merge du sous-module. Préférez submodule.<nom>.branch si vous voulez distribuer la branche amont par défaut avec le superprojet et branch.<nom>.merge si vous voulez un aspect plus natif tout en travaillant dans le sous-module lui-même.

-N
--no-fetch

Cette option n’est valable que pour la commande update. Ne pas récupérer de nouveaux objets sur le site distant.

--checkout

Cette option n’est valable que pour la commande update. Vérifier le commit enregistré dans le superprojet sur une HEAD détachée dans le sous-module. C’est le comportement par défaut, l’utilisation principale de cette option est de remplacer submodule.$nom.update lorsqu’elle est définie à une valeur autre que checkout. Si la clé submodule.$nom.update n’est pas explicitement définie ou est définie à checkout, cette option est implicite.

--merge

Cette option n’est valable que pour la commande update. Fusionner le commit enregistré dans le superprojet dans la branche actuelle du sous-module. Si cette option est donnée, la HEAD du sous-module ne sera pas détachée. Si un échec de fusion empêche ce processus, vous devrez résoudre les conflits résultants au sein du sous-module avec les outils de résolution de conflits habituels. Si la clé submodule.$nom.update est définie sur fusion, cette option est implicite.

--rebase

Cette option n’est valable que pour la commande de mise à jour. Rebaser la branche actuelle sur le commit enregistré dans le superprojet. Si cette option est donnée, la HEAD du sous-module ne sera pas détachée. Si un échec de fusion empêche ce processus, vous devrez résoudre ces échecs avec git-rebase[1]. Si la clé submodule.$nom.update est définie sur rebase, cette option est implicite.

--init

Cette option n’est valable que pour la commande update. Initialiser tous les sous-modules pour lesquels "git submodule init" n’a pas été appelé jusqu’à présent avant la mise à jour.

--name

Cette option n’est valable que pour la commande add. Elle fixe le nom du sous-module à la chaîne de caractères donnée au lieu de choisir par défaut son chemin d’accès. Le nom doit être valide en tant que nom de répertoire et ne peut pas se terminer par un "/".

--reference <dépôt>

Cette option n’est valable que pour les commandes add et update. Ces commandes ont parfois besoin de cloner un dépôt distant. Dans ce cas, cette option sera passée à la commande git-clone[1].

NOTE : N’utilisez pas cette option si vous n’avez pas lu attentivement la note pour les options --reference, --shared, et --dissociate de git-clone[1].

--dissociate

Cette option n’est valable que pour les commandes add et update. Ces commandes ont parfois besoin de cloner un dépôt distant. Dans ce cas, cette option sera passée à la commande git-clone[1].

NOTE : voir NOTE pour l’option --reference.

--recursive

Cette option n’est valable que pour les commandes foreach, update, status et sync. Traverser les sous-modules de façon récursive. L’opération est effectuée non seulement dans les sous-modules du dépôt actuel, mais aussi dans tous les sous-modules imbriqués à l’intérieur de ces sous-modules (et ainsi de suite).

--depth

Cette option est valable pour les commandes d’ajout et de mise à jour. Créer un clone superficiel avec un historique tronqué au nombre de révisions spécifié. Voir git-clone[1]

--[no-]recommend-shallow

Cette option n’est valable que pour la commande de mise à jour. Le clone initial d’un sous-module utilisera le submodule.<nom>.shallow recommandé, tel que fourni par le fichier .gitmodules par défaut. Pour ignorer les suggestions, utilisez --no-recommend-shallow.

-j <n>
--jobs <n>

Cette option n’est valable que pour la commande update. Cloner les nouveaux sous-modules en parallèle avec autant de tâches. L’option submodule.fetchJobs est utilisée par défaut.

--[no-]single-branch

Cette option n’est valable que pour la commande update. Cloner une seule branche pendant la mise à jour : HEAD ou une branche spécifiée par --branch.

<chemin>…​

Chemins vers le(s) sous-module(s). Lorsque cela est spécifié, la commande ne fonctionnera que sur les sous-modules se trouvant sur les chemins spécifiés. (Cet argument est requis avec add).

FICHIERS

Lors de l’initialisation des sous-modules, un fichier .gitmodules dans le répertoire de niveau supérieur du dépôt contenant est utilisé pour trouver l’url de chaque sous-module. Ce fichier doit être formaté de la même manière que le fichier $GIT_DIR/config. La clé de l’url de chaque sous-module est "submodule.$nom.url". Voir gitmodules[5] pour plus de détails.

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