git-update-index - Enregistre le contenu de fichiers de l’arbre de travail à l’index

Modifie l’index. Chaque fichier mentionné est mis à jour dans l’index et tout état non fusionné ou nécessitant une mise à jour est effacé.

Voir aussi git-add[1] pour un moyen plus convivial de réaliser certaines des opérations les plus courantes sur l’index.

La façon dont git update-index gère les fichiers qu’on lui indique peut être modifiée en utilisant les différentes options :

--refresh ne calcule pas un nouveau fichier sha1 ni ne met à jour l’index pour les changements de mode/contenu. Mais ce qu’il fait est de « re-faire correspondre » les informations stat d’un fichier avec l’index, de sorte que vous pouvez rafraîchir l’index pour un fichier qui n’a pas été modifié mais dont l’entrée stat est périmée.

Par exemple, vous voudriez le faire après avoir effectué un git read-tree, pour relier les détails de l’index stat aux fichiers appropriés.

--cacheinfo est utilisé pour enregistrer un fichier qui n’est pas dans le répertoire de travail courant. Ceci est utile pour les fusions à extraction minimale.

Pour faire comme si vous aviez un fichier au chemin avec le mode et la sha1, tapez :

--info-only est utilisé pour enregistrer des fichiers sans les placer dans la base de données des objets. Ceci est utile pour les dépôts en mode statut uniquement.

--cacheinfo et --info-only se comportent de manière similaire : l’index est mis à jour mais la base de données des objets ne l’est pas. --cacheinfo est utile lorsque l’objet est dans la base de données mais que le fichier n’est pas disponible localement. --info-only est utile lorsque le fichier est disponible, mais que vous ne souhaitez pas mettre à jour la base de données des objets.

--index-info est un mécanisme plus puissant qui vous permet de fournir plusieurs définitions d’entrées depuis l’entrée standard, et est spécialement conçu pour les scripts. Il peut prendre des entrées de trois formats :

Pour placer une entrée d’étape supérieure dans l’index, le chemin doit d’abord être supprimé en fournissant une entrée mode=0 pour le chemin, puis en fournissant les lignes d’entrée nécessaires dans le troisième format.

Par exemple, en commençant avec cet index :

Vous pouvez fournir l’entrée suivante à --index-info :

La première ligne de l’entrée fournit 0 comme mode pour supprimer le chemin ; la SHA-1 n’a pas d’importance tant qu’elle est bien formatée. Ensuite, la deuxième et la troisième ligne fournissent les entrées d’étape 1 et d’étape 2 pour ce chemin. Après ce qui précède, on obtient ceci :

De nombreuses opérations dans Git dépendent de l’efficacité de l’implémentation de lstat(2) de votre système de fichiers, afin que les informations st_mtime des fichiers de l’arbre de travail puissent être vérifiées à moindre coût pour voir si le contenu du fichier a changé par rapport à la version enregistrée dans le fichier index. Malheureusement, certains systèmes de fichiers ont un lstat(2) inefficace. Si votre système de fichiers est l’un d’eux, vous pouvez définir le bit « assume unchanged » sur des chemins que vous n’avez pas modifiés afin d’empêcher Git d’effectuer cette vérification. Notez que définir ce bit sur un chemin ne signifie pas que Git vérifiera le contenu du fichier pour voir s’il a changé — cela amène Git à omettre toute vérification et à supposer qu’il n’a pas changé. Lorsque vous apportez des modifications aux fichiers de l’arbre de travail, vous devez informer explicitement Git en retirant le bit « assume unchanged », soit avant, soit après les avoir modifiés.

Pour définir le bit « assume unchanged », utilisez l’option --assume-unchanged. Pour le désactiver, utilisez --no-assume-unchanged. Pour voir quels fichiers ont le bit « assume unchanged » défini, utilisez git ls-files -v (voir git-ls-files[1]).

La commande examine la variable de configuration core.ignorestat. Lorsque celle-ci est vraie, les chemins mis à jour avec git update-index chemins... et les chemins mis à jour avec d’autres commandes Git qui mettent à jour à la fois l’index et l’arbre de travail (par ex. git apply --index, git checkout-index -u et git read-tree -u) sont automatiquement marqués comme « assume unchanged ». Notez que le bit « assume unchanged » n’est pas défini si git update-index --refresh trouve que le fichier de l’arbre de travail correspond à l’index (utilisez git update-index --really-refresh si vous voulez les marquer comme « assume unchanged »).

Parfois, les utilisateurs confondent le bit assume-unchanged avec le bit skip-worktree. Voir le dernier paragraphe de la section « Bit skip-worktree » ci-dessous pour une explication des différences.

Pour mettre à jour et rafraîchir uniquement les fichiers déjà extraits :

Le bit skip-worktree peut être défini en une seule (longue) phrase : dire à Git d’éviter d’écrire le fichier dans le répertoire de travail lorsque c’est raisonnablement possible, et de traiter le fichier comme inchangé lorsqu’il n’est pas présent dans le répertoire de travail.

Notez que toutes les commandes Git ne tiennent pas compte de ce bit, et certaines ne le prennent en charge que partiellement.

Les options de update-index et les capacités de read-tree relatives au bit skip-worktree ont précédé l’introduction de la commande git-sparse-checkout[1], qui fournit un moyen beaucoup plus simple de configurer et de gérer les bits skip-worktree. Si vous voulez réduire votre arbre de travail pour ne traiter qu’un sous-ensemble des fichiers du dépôt, nous encourageons vivement l’utilisation de git-sparse-checkout[1] de préférence aux primitives de bas niveau update-index et read-tree.

L’objectif principal du bit skip-worktree est de permettre les extractions éparses, c’est-à-dire d’avoir des répertoires de travail avec seulement un sous-ensemble de chemins présents. Lorsque le bit skip-worktree est défini, les commandes Git (comme switch, pull, merge) éviteront d’écrire ces fichiers. Cependant, ces commandes écriront parfois ces fichiers quand même dans des cas importants tels que les conflits lors d’une fusion ou d’un rebasage. Les commandes Git éviteront également de traiter l’absence de ces fichiers comme une suppression intentionnelle ; par exemple git add -u ne mettra pas en attente une suppression pour ces fichiers et git commit -a ne fera pas non plus un commit les supprimant.

Bien que ce bit ressemble au bit assume-unchanged, son objectif est différent. Le bit assume-unchanged sert à laisser le fichier dans l’arbre de travail tout en faisant Git omette de vérifier les changements et en présumant que le fichier n’a pas été modifié (bien que s’il peut déterminer sans effectuer stat sur le fichier qu’il a changé, il est libre d’enregistrer les changements). skip-worktree indique à Git d’ignorer l’absence du fichier, d’éviter de le mettre à jour lorsque c’est possible avec les commandes qui mettent normalement à jour une grande partie du répertoire de travail (par ex. checkout, switch, pull, etc.), et de ne pas enregistrer son absence dans les commits. Notez que dans les extractions éparses (configurées par git sparse-checkout ou en définissant core.sparseCheckout à true), si un fichier est marqué comme skip-worktree dans l’index mais est trouvé dans l’arbre de travail, Git effacera le bit skip-worktree pour ce fichier.

Ce mode est conçu pour les dépôts avec de très grands indexes, et vise à réduire le temps nécessaire pour écrire répétitivement ces indexes.

Dans ce mode, l’index est divisé en deux fichiers, $GIT_DIR/index et $GIT_DIR/sharedindex.<SHA-1>. Les changements sont accumulés dans $GIT_DIR/index, l’index partagé, tandis que le fichier d’index partagé contient toutes les entrées d’index et reste inchangé.

Tous les changements de l’index partagé sont reportés dans le fichier d’index partagé lorsque le nombre d’entrées dans l’index partagé atteint un niveau spécifié par la variable de configuration splitIndex.maxPercentChange (voir git-config[1]).

Chaque fois qu’un nouveau fichier d’index partagé est créé, les anciens fichiers d’index partagé sont supprimés si leur heure de modification est antérieure à ce qui est spécifié par la variable de configuration splitIndex.sharedIndexExpire (voir git-config[1]).

Pour éviter de supprimer un fichier d’index partagé encore utilisé, son heure de modification est mise à jour à l’heure actuelle chaque fois qu’un nouvel index partagé basé sur le fichier d’index partagé est soit créé, soit lu.

Ce cache est destiné à accélérer les commandes impliquant la détermination des fichiers non suivis tels que git status.

Cette fonctionnalité fonctionne en enregistrant le mtime des répertoires de l’arbre de travail puis en omettant la lecture des répertoires et les appels stat sur les fichiers de ces répertoires dont le mtime n’a pas changé. Pour que cela fonctionne, le système d’exploitation et le système de fichiers sous-jacents doivent modifier le champ st_mtime des répertoires lorsque des fichiers dans le répertoire sont ajoutés, modifiés ou supprimés.

Vous pouvez tester si le système de fichiers prend en charge cela avec l’option --test-untracked-cache. L’option --untracked-cache effectuait implicitement ce test dans les anciennes versions de Git, mais ce n’est plus le cas.

Si vous voulez activer (ou désactiver) cette fonctionnalité, il est plus facile d’utiliser la variable de configuration core.untrackedCache (voir git-config[1]) plutôt que l’option --untracked-cache de git update-index dans chaque dépôt, surtout si vous voulez le faire pour tous les dépôts que vous utilisez, car vous pouvez définir la variable de configuration à true (ou false) une seule fois dans votre $HOME/.gitconfig et elle affectera tous les dépôts que vous touchez.

Lorsque la variable de configuration core.untrackedCache est modifiée, le cache des non-suvis est ajouté ou supprimé de l’index la prochaine fois qu’une commande lit l’index ; tandis que lorsque --[no-|force-]untracked-cache est utilisé, le cache des non-suvis est immédiatement ajouté ou supprimé de l’index.

Avant 2.17, le cache des non-suvis avait un bogue où le remplacement d’un répertoire par un lien symbolique vers un autre répertoire pouvait causer un affichage incorrect de fichiers suivis par git comme non suivis. Voir le commit « status: add a failing test showing a core.untrackedCache bug » dans git.git. Un correctif pour cela est (et cela pourrait fonctionner pour d’autres bogues non découverts à l’avenir) :

Ce bogue a également été montré pour affecter les cas non-liens symboliques de remplacement d’un répertoire par un fichier en ce qui concerne les structures internes du cache des non-suvis, mais aucun cas n’a été signalé où cela a résulté en une sortie incorrecte de "git status".

Il existe également des cas où les index existants écrits par des versions de Git antérieures à 2.17 référenceront des répertoires qui n’existent plus, causant potentiellement de nombreux avertissements « could not open directory » à être affichés lors de "git status". Ce sont de nouveaux avertissements pour des problèmes existants qui étaient précédemment silencieusement ignorés.

Comme pour le bogue décrit ci-dessus, la solution est d’effectuer ponctuellement une exécution de "git status" avec core.untrackedCache=false pour purger les données erronées restantes.

Cette fonctionnalité est destinée à accélérer les opérations de git pour les dépôts ayant de grands répertoires de travail.

Elle permet à git de travailler avec un moniteur de système de fichiers (voir git-fsmonitor--daemon[1] et la section « fsmonitor-watchman » de githooks[5]) qui peut l’informer des fichiers qui ont été modifiés. Cela permet à git d’éviter d’avoir à effectuer lstat() sur chaque fichier pour trouver les fichiers modifiés.

Lorsqu’elle est utilisée en conjunction avec le cache des non-suvis, elle peut encore améliorer les performances en évitant le coût de l’analyse de l’ensemble du répertoire de travail à la recherche de nouveaux fichiers.

Si vous voulez activer (ou désactiver) cette fonctionnalité, il est plus facile d’utiliser la variable de configuration core.fsmonitor (voir git-config[1]) plutôt que l’option --fsmonitor de git update-index dans chaque dépôt, surtout si vous voulez le faire pour tous les dépôts que vous utilisez, car vous pouvez définir la variable de configuration une seule fois dans votre $HOME/.gitconfig et elle affectera tous les dépôts que vous touchez.

Lorsque la variable de configuration core.fsmonitor est modifiée, le moniteur de système de fichiers est ajouté ou supprimé de l’index la prochaine fois qu’une commande lit l’index. Lorsque --[no-]fsmonitor est utilisé, le moniteur de système de fichiers est immédiatement ajouté ou supprimé de l’index.

La commande respecte la variable de configuration core.filemode. Si votre dépôt se trouve sur un système de fichiers dont les bits exécutables ne sont pas fiables, celle-ci doit être définie à false (voir git-config[1]). Cela amène la commande à ignorer les différences de mode de fichier enregistrées dans l’index et le mode de fichier sur le système de fichiers s’ils ne diffèrent que sur le bit exécutable. Sur un tel système de fichiers malchanceux, vous devrez peut-être utiliser git update-index --chmod=.

De manière très similaire, si la variable de configuration core.symlinks est définie à false (voir git-config[1]), les liens symboliques sont extraits en tant que fichiers simples, et cette commande ne modifie pas un mode de fichier enregistré de lien symbolique en fichier régulier.

La commande examine la variable de configuration core.ignorestat. Voir la section « Utilisation du bit « assume unchanged » » ci-dessus.

La commande examine également la variable de configuration core.trustctime. Cela peut être utile lorsque le temps de changement d’inode est régulièrement modifié par quelque chose en dehors de Git (les explorateurs de systèmes de fichiers et les systèmes de sauvegarde utilisent ctime pour marquer les fichiers traités) (voir git-config[1]).

L’extension de cache des non-suivis peut être activée par la variable de configuration core.untrackedCache (voir git-config[1]).

Les utilisateurs essaient souvent d’utiliser les bits assume-unchanged et skip-worktree pour dire à Git d’ignorer les modifications de fichiers qui sont suivis. Cela ne fonctionne pas comme prévu, car Git peut toujours vérifier les fichiers de l’arbre de travail par rapport à l’index lors de l’exécution de certaines opérations. En général, Git ne fournit pas de moyen d’ignorer les modifications de fichiers suivis, donc des solutions alternatives sont recommandées.

Par exemple, si le fichier que vous voulez modifier est une sorte de fichier de configuration, le dépôt peut inclure un fichier de configuration exemple qui peut ensuite être copié sous le nom ignoré et modifié. Le dépôt peut même inclure un script pour traiter le fichier exemple comme un modèle, le modifiant et le copiant automatiquement.

git-config[1], git-add[1], git-ls-files[1]

Fait partie de la suite git[1]

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 .