Français ▾ Topics ▾ Latest version ▾ git-submodule last updated in 2.54.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>] [--ref-format <format>] [--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 origin 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 <nom> 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.

Si --ref-format <format> est spécifié, le format de stockage des ref des sous-modules récemment clonés sera défini en conséquence.

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[1] 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>] [--ref-format=<format>] [--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 --ref-format <format> est spécifié, le format de stockage des ref des sous-modules récemment clonés sera défini en conséquence.

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>

Evaluate an arbitrary shell <command> in each checked out submodule. The command has access to the variables $name, $sm_path, $displaypath, $sha1 and $toplevel:

$name

the name of the relevant submodule section in .gitmodules

$sm_path

le chemin du sous-module tel qu’enregistré dans le superprojet immédiat

$displaypath

the relative path from the current working directory to the submodules root directory

$sha1

the commit as recorded in the immediate superproject

$toplevel

the absolute path to the top-level of the immediate superproject.

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

Affiche l’état d’avancement 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. Valide seulement pour les commandes add et update.

--all

désinscrire tous les sous-modules dans l’arbre de travail. Cette option n’est valable que pour la commande deinit.

-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

Force the command to proceed, even if it would otherwise fail. This option is only valid for add, deinit and update commands.

add

permettre d’ajouter un chemin de sous-module autrement ignoré. Cette option est également utilisée pour contourner une vérification que le nom du sous-module n’est pas déjà utilisé. Par défaut, git submodule add échouera si le nom proposé (qui est dérivé du chemin) est déjà enregistré pour un autre sous-module dans le dépôt. L’utilisation de --force permet à la commande de continuer en générant automatiquement un nom unique en ajoutant un numéro au nom conflictuel (p. ex., si un sous-module nommé « enfant » existe, on va essayer « enfant1 », etc.).

deinit

les arbres de travail du sous-module seront supprimés même s’ils contiennent des modifications locales.

update

(seulement efficace avec la procédure de paiement), supprimer les modifications locales dans les sous-modules lors du passage à un commit différent ; et exécuter toujours une extraction dans le sous-module, même si le commit listé dans l’index du dépôt contenant correspond au commit extrait dans le sous-module.

--cached

Use the index to determine the commit instead of the HEAD. This option is only valid for status and summary commands.

--files

Force la commande summary à comparer le commit dans l’index avec celui de la HEAD du sous-module.

-n<n>
--summary-limit=<n>

Limiter la taille du résumé summary (nombre de validations affichées au total) à <n>. 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

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. Cette option n’est valable que pour la commande de mise à jour. 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

Ne pas récupérer les nouveaux objets depuis le site distant. Cette option n’est valide que pour la commande update.

--checkout

Extraire le commit enregistré dans le superprojet sur une HEAD détachée dans le sous-module. Cette option n’est valide que pour la commande update. 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

Fusionner le commit enregistré dans le superprojet dans la branche actuelle du sous-module. Cette option n’est valable que pour la commande update. 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 à merge, cette option est implicite.

--rebase

Rebaser la branche actuelle sur le commit enregistré dans le superprojet. Cette option n’est valide que pour la commande update.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é de configuration submodule.<nom>.update est définie à rebase, cette option est implicite.

--init

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

--name=<nom>

Fixer 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>

Passer le <dépôt> local comme référence lors du clonage du sous-module. 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

Après avoir utilisé un dépôt de référence depuis lequel cloner, ne plus s’appuyer sur lui par la suite. 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 la NOTE ci-dessus pour l’option --reference.
--recursive

Traverser les sous-modules récursivement. Cette option n’est valable que pour les commandes foreach, update, status et sync. 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=<profondeur>

Créer un clone superficiel avec un historique tronqué à <profondeur> révisions. Cette option est valable pour les commandes add et update. Voir git-clone[1]

--recommend-shallow
--no-recommend-shallow

Recommande ou non un clonage superficiel des sous-modules. Cette option n’est valable que pour la commande update. 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>

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

--single-branch
--no-single-branch

Clone only one branch during update: HEAD or one specified by --branch. This option is only valid for the update command.

<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.

VOIR AUSSI

gitsubmodules[7], gitmodules[5].

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 .