Git

git-blame last updated in 2.52.0

NOM

git-blame - Montrer la révision et l’auteur qui ont modifié en dernier chaque ligne d’un fichier

SYNOPSIS

git blame [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]
	    [-L <plage>] [-S <fichier-de-révs>] [-M] [-C] [-C] [-C] [--since=<date>]
	    [--ignore-rev <rév>] [--ignore-revs-file <fichier>]
	    [--color-lines] [--color-by-age] [--progress] [--abbrev=<n>]
	     [--contents <fichier>] [<rév> | --reverse <rév>..<rév>][--] <fichier>

DESCRIPTION

Annote chaque ligne du fichier donné avec les informations de la dernière révision qui a modifié la ligne. Optionnellement, commence à annoter à partir de la révision donnée.

Lorsqu’il est spécifié une ou plusieurs fois, -L limite l’annotation aux lignes demandées.

L’origine des lignes est automatiquement suivie à travers les renommages de fichiers entiers (il n’y a actuellement aucune option pour désactiver le suivi des renommages). Pour suivre les lignes déplacées d’un fichier à un autre, ou pour suivre les lignes qui ont été copiées et collées depuis un autre fichier, etc., voir les options -C et -M.

Le rapport ne vous dit rien sur les lignes qui ont été supprimées ou remplacées ; vous devez utiliser un outil tel que "git diff" ou l’interface "pickaxe" brièvement mentionnée dans le paragraphe suivant.

Outre la prise en charge de l’annotation des fichiers, Git permet également de rechercher dans l’historique du développement la modification où un extrait de code est apparu. Il est ainsi possible de savoir quand un extrait de code a été ajouté à un fichier, déplacé ou copié entre des fichiers, ou supprimé ou remplacé. Il fonctionne en recherchant une chaîne de texte dans le diff. Un petit exemple de l’interface pickaxe qui recherche blame_usage :

$ git log --pretty=oneline -S'blame_usage'
5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <fichier-d-ancêtre>
ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output

OPTIONS

-b

Afficher un SHA-1 vierge pour les validations de limite. Cela peut également être contrôlé par l’option de configuration blame.blankBoundary.

--root

Ne pas considérer les commits de base comme des limites. Ceci peut également être contrôlé via l’option de configuration blame.showRoot.

--show-stats

Inclure des statistiques supplémentaires à la fin de la sortie de blame.

-L <début>,<fin>

-L: <nomfonc>

N’annoter que la plage de lignes donnée par <début>,<fin> ou par la regex du nom de la fonction <nom-de-fonction>. Peut être spécifié plusieurs fois. Les intervalles qui se chevauchent sont autorisés.

<début> et <fin> sont facultatifs. -L <début> ou -L <début>,, s’étend de <début> jusqu’à la fin du fichier. -L,<fin> s’étend du début du fichier jusqu’à <fin>.

<début> et <fin> peuvent prendre l’une de ces formes :

<nombre>

Si <début> ou <fin> est un nombre, il spécifie un numéro de ligne absolu (les lignes comptent à partir de 1).
/<regex>/

Cette forme utilisera la première ligne correspondant à la regex POSIX donnée. Si <début> est une regex, la recherche se fera à partir de la fin de la plage -L précédente, le cas échéant, sinon à partir du début du fichier. Si <début> est ^/<regex>/, la recherche se fera à partir du début du fichier. Si <fin> est une regex, la recherche débutera à partir de la ligne donnée par <début>.
+<offset> ou -<offset>

Ceci n’est valable que pour <fin> et spécifiera un nombre de lignes avant ou après la ligne donnée par <début>.

Si :<nom-de-fonction> est donné à la place de <début> et de <fin>, il s’agit d’une expression régulière qui indique la plage depuis première ligne qui correspond à <nom-de-fonction>, jusqu’à la ligne de nom-de-fonction suivante. La recherche de :<nom-de-fonction> se fait à partir de la fin de la plage -L précédente, s’il y en a une, sinon à partir du début du fichier. La recherche de ^:<nom-de-fonction> commence au début du fichier. Les noms de fonction sont déterminés de la même manière que celle par laquelle git diff fonctionne sur les en-têtes de section de rustine (voir Définir un en-tête personnalisé dans gitattributes[5]).

-l: Afficher la révision long (par défaut : désactivé).
-t: Afficher les horodatages bruts (Défaut : désactivé).
-S <fichier-des-révs>: Utiliser les révisions depuis le fichier-des-révisions au lieu d’appeler git-rev-list[1].
--reverse <rév>..<rév>: Parcourir l’historique en avant au lieu d’en arrière. Au lieu de montrer la révision dans laquelle une ligne est apparue, ceci montre la dernière révision dans laquelle une ligne a existé. Cela nécessite une gamme de révisions comme DÉBUT..FIN où le chemin de blâme existe dans DÉBUT. Pour plus de commodité, git blame --reverse DÉBUT est pris comme git blame --reverse DÉBUT..HEAD.
--first-parent: Ne suivre que le premier commit parent lors de la rencontre d’un commit de fusion. Cette option peut être utilisée pour déterminer le moment où une ligne a été introduite dans une branche d’intégration particulière, plutôt que le moment où elle a été introduite dans l’historique global.
-p
--porcelain: Afficher dans un format propice à la consommation par machine.
--line-porcelain: Afficher le format porcelaine, mais sortir les informations de commit pour chaque ligne, et pas seulement la première fois qu’un commit est référencé. Implique --porcelaine.
--incremental: Afficher le résultat progressivement dans un format conçu pour la consommation par une machine.
--encoding=<codage>: Spécifier l’encodage utilisé pour produire les des noms d’auteurs et les résumés des commits. Le définir sur none rend la sortie de blâme des données non converties. Pour plus d’informations, voir la discussion sur l’encodage dans la page manuelle git-log[1].
--contents <fichier>: Annoter en utilisant le contenu du fichier nommé, en commençant par <rév> si elle est spécifiée, et HEAD sinon. Vous pouvez spécifier - pour que la commande lise le contenu du fichier à partir de l’entrée standard.
--date <format>: Spécifie le format utilisé pour les dates sur la sortie. Si --date n’est pas fourni, la valeur de la variable de configuration blame.date est utilisée. Si la variable de configuration blame.date n’est pas non plus définie, le format iso est utilisé. Pour les valeurs prises en charge, voir la discussion de l’option --date à git-log[1].
--[no-]progress: L’état d’avancement est indiqué par défaut sur le flux d’erreurs standard lorsqu’il est connecté à un terminal. Ce drapeau permet de signaler l’état d’avancement même s’il n’est pas attaché à un terminal. On ne peut pas utiliser --progress avec --porcelain ou --incremental.
-M[<num>]: Détecter les lignes déplacées ou copiées dans un fichier. Lorsqu’un commit déplace ou copie un bloc de lignes (par exemple, le fichier original a A puis B, et le commit le change en B puis A), l’algorithme traditionnel de blame ne remarque que la moitié du mouvement et blâme généralement les lignes qui ont été déplacées vers le haut (c’est-à-dire B) au parent et attribue le blâme aux lignes qui ont été déplacées vers le bas (c’est-à-dire A) au commit enfant. Avec cette option, les deux groupes de lignes sont blâmés sur le parent en effectuant des passes d’inspection supplémentaires.

<num>est facultatif, mais c’est la limite inférieure sur le nombre de caractères alphanumériques que Git doit détecter comme déplacées/copiées dans un fichier pour qu’il associe ces lignes avec le commit parent. La valeur par défaut est 20.
-C[<num>]: En plus de -M, détecter les lignes déplacées ou copiées à partir d’autres fichiers qui ont été modifiés dans le même commit. Ceci est utile lorsque vous réorganisez votre programme et que vous déplacez du code d’un fichier à l’autre. Lorsque cette option est donnée deux fois, la commande recherche en plus les copies depuis d’autres fichiers dans le commit qui crée le fichier. Lorsque cette option est donnée trois fois, la commande recherche également des copies d’autres fichiers dans n’importe quel commit.

<num> est optionnel mais c’est la limite inférieure du nombre de caractères alphanumériques que Git doit détecter comme étant des déplacements/copies entre fichiers pour qu’il puisse associer ces lignes au commit parent. Et la valeur par défaut est 40. S’il y a plus d’une option -C donnée, l’argument <num> du dernier -C prendra effet.
--ignore-rev <rév>: Ignorer les modifications apportées par la révision lors de l’attribution de la responsabilité, comme si la modification ne s’était jamais produite. Les lignes qui ont été modifiées ou ajoutées par un commit ignoré seront blâmées sur le commit précédent qui a modifié cette ligne ou les lignes voisines. Cette option peut être spécifiée plusieurs fois pour ignorer plus d’une révision. Si l’option de configuration blame.markIgnoredLines est activée, alors les lignes qui ont été modifiées par un commit ignoré et attribuées à un autre commit seront marquées avec un ? dans la sortie de blame. Si l’option de configuration blame.markUnblamableLines est définie, alors les lignes touchées par un commit ignoré que nous n’avons pas pu attribuer à une autre révision sont marquées d’un *. Dans les modes porcelaine, ignored et unblamable sont respectivement affichés.
--ignore-revs-file <fichier>: Ignorer les révisions listées dans le fichier, qui doit être au même format qu’un fsck.skipList. Cette option peut être répétée, et ces fichiers seront traités après tous les fichiers spécifiés avec l’option de configuration blame.ignoreRevsFile. Un nom de fichier vide, "", effacera la liste des révisions des fichiers précédemment traités.
--color-lines: Colorier différemment les annotations de ligne dans le format par défaut si elles proviennent du même commit que la ligne précédente. Cela permet de distinguer plus facilement les blocs de code introduits par des commits différents. La couleur par défaut est le cyan et peut être ajustée en utilisant l’option de configuration color.blame.repeatedLines.
--color-by-age: Colorer les annotations de ligne en fonction de l’âge de la ligne dans le format par défaut. L’option de configuration color.blame.highlightRecent contrôle quelle couleur est utilisée pour chaque tranche d’âge.
-h: Afficher le message d’aide.

-c: Utiliser le même mode de sortie que git-annotate[1] (Défaut : désactivé).
--score-debug: Inclure les informations de débogage relatives au déplacement des lignes entre les fichiers (voir -C) et aux lignes déplacées à l’intérieur d’un fichier (voir -M). Le premier nombre listé est le score. C’est le nombre de caractères alphanumériques détectés comme ayant été déplacés entre ou dans des fichiers. Il doit être supérieur à un certain seuil pour que git blame considère que ces lignes de code ont été déplacées.
-f
--show-name: Afficher le nom de fichier dans le commit original. Par défaut, le nom du fichier est affiché s’il y a une ligne qui provient d’un fichier avec un nom différent, à cause de la détection des renommages.
-n
--show-number: Afficher le numéro de ligne dans le commit original (Défaut : off).
-s: Supprimer le nom de l’auteur et l’horodatage dans la sortie.
-e
--show-email: Montrer l’email de l’auteur au lieu du nom de l’auteur (Default : off). Ceci peut aussi être contrôlé par l’option de configuration blame.showEmail.
-w: Ignorer les espaces blancs lors de la comparaison de la version du parent et celle de l’enfant pour trouver d’où viennent les lignes.
--abbrev=<n>: Au lieu d’utiliser les 7 +1 chiffres hexadécimaux par défaut comme nom d’objet abrégé, utiliser <m>+1 chiffres, où <m> est au moins <n> mais garantir que les noms d’objet de commit sont uniques. Notez qu’une colonne est utilisée pour un signe d’insertion pour marquer le commit limite.

LE FORMAT PAR DÉFAUT

Lorsque ni l’option --porcelain ni l’option --incremental ne sont spécifiées, git blame sortira une annotation pour chaque ligne avec :

nom d’objet abrégé pour le commit d’où provient la ligne ;
l’identifiant de l’auteur (par défaut, le nom de l’auteur et la date, sauf si -s ou -e est spécifié) ; et
numéro de ligne

avant le contenu de la ligne.

LE FORMAT PORCELAINE

Dans ce format, chaque ligne est sortie après un en-tête ; l’en-tête au minimum a la première ligne qui a :

SHA-1 de 40 octets du commit auquel la ligne est attribuée ;
le numéro de la ligne dans le fichier d’origine ;
le numéro de la ligne dans le fichier final ;
sur une ligne qui commence un groupe de lignes d’un commit différent du précédent, le nombre de lignes dans ce groupe. Sur les lignes suivantes, ce champ est absent.

Cette ligne d’en-tête est suivie par les informations suivantes au moins une fois pour chaque commit :

le nom de l’auteur ("author"), le courriel ("author-mail"), l’heure ("author-time"), et le fuseau horaire ("author-tz") ; de même pour le validateur.
le nom du fichier dans le commit auquel la ligne est attribuée.
la première ligne du message de validation ("summary").

Le contenu de la ligne actuelle est affiché après l’en-tête ci-dessus, préfixé par un TAB. Cela permet d’ajouter ultérieurement d’autres éléments d’en-tête.

Le format porcelaine supprime généralement les informations de commit qui ont déjà été vues. Par exemple, deux lignes qui sont liées au même commit seront toutes deux affichées, mais les détails de ce commit ne seront affichés qu’une seule fois. Les informations spécifiques aux lignes individuelles ne seront pas regroupées, comme les révisions qui seront marquées « ignored » ou « unblamable ». Ceci est plus efficace, mais peut nécessiter de conserver plus d’information de contexte. C’est plus efficace, mais peut nécessiter que le lecteur conserve plus d’information en tête. L’option --line-porcelain peut être utilisée pour afficher toutes les informations de commit pour chaque ligne, permettant une utilisation plus simple (mais moins efficace) comme :

# compter le nombre de lignes attribuées à chaque auteur
git blame --line-porcelain file |
sed -n 's/^author //p' |
sort | uniq -c | sort -rn

SPÉCIFICATION DE PLAGES

Contrairement à git blame et git annotate dans les anciennes versions de git, l’étendue de l’annotation peut être limitée à la fois à des plages de lignes et à des plages de révisions. L’option -L, qui limite l’annotation à une plage de lignes, peut être spécifiée plusieurs fois.

Lorsque vous souhaitez trouver l’origine des lignes 40-60 du fichier foo, vous pouvez utiliser l’option -L comme suit (elles signifient la même chose — toutes deux demandent 21 lignes à partir de la ligne 40) :

git blame -L 40,60 foo
git blame -L 40,+21 foo

Vous pouvez également utiliser une expression régulière pour spécifier la plage de lignes :

git blame -L '/^sub hello {/,/^}$/' foo

qui limite l’annotation au corps de la sous-routine hello.

Lorsque vous n’êtes pas intéressé par les changements plus anciens que la version v2.6.18, ou les changements plus anciens que 3 semaines, vous pouvez utiliser des spécificateurs d’intervalle de révision similaires à git rev-list :

git blame v2.6.18.. -- foo
git blame --since=3.weeks -- foo

Lorsque des spécificateurs de plage de révision sont utilisés pour limiter l’annotation, les lignes qui n’ont pas été modifiées depuis la limite de l’intervalle (soit le commit v2.6.18 ou le commit le plus récent qui date de plus de 3 semaines dans l’exemple ci-dessus) sont blâmées pour ce commit de limite de plage.

Un moyen particulièrement utile est de voir si un fichier ajouté comporte des lignes créées par copier-coller à partir de fichiers existants. Cela indique parfois que le développeur a été négligent et n’a pas refactoré le code correctement. Vous pouvez d’abord trouver le commit qui a introduit le fichier avec :

git log --diff-filter=A --pretty=short -- foo

et ensuite annoter la modification entre le commit et ses parents, en utilisant la notation commit^! :

git blame -C -C -f $commit^! -- foo

SORTIE INCRÉMENTALE

Quand elle est appelée avec l’option --incremental, la commande affiche le résultat au fur et à mesure qu’il est construit. La sortie parle généralement des lignes touchées par les commits les plus récents en premier (c’est-à-dire que les lignes seront annotées dans le désordre) et est destinée à être utilisée par des visionneurs interactifs.

Le format de sortie est similaire au format Porcelain, mais il ne contient pas les lignes réelles du fichier qui est annoté.

Chaque entrée de blâme commence toujours par une ligne de :
```
<sha1-hex-de-40-octets> <lignesource> <lignerésultat> <nombre-de-lignes>
```
Les numéros de ligne comptent à partir de 1.
La première fois qu’un commit apparaît dans le flux, diverses autres informations le concernant sont affichées avec une étiquette d’un mot au début de chaque ligne décrivant les informations supplémentaires du commit (auteur, email, validateur, dates, résumé, etc.).

Contrairement au format Porcelaine, l’information sur le nom de fichier est toujours donnée et termine l’entrée :

"nom de fichier" <nom-de-fichier-avec-espaces-échappés-ici>

et donc il est vraiment très facile à analyser pour un analyseur orienté lignes et mots (ce qui devrait être assez naturel pour la plupart des langages de script).

Note

Pour les personnes qui font de l’analyse syntaxique : pour la rendre plus robuste, il suffit d’ignorer toutes les lignes entre la première et la dernière (lignes "<sha1>" et "nom-de-fichier") où vous ne reconnaissez pas les mots-clés (ou ne vous souciez pas de celui-là en particulier) au début des lignes "informations étendues". De cette façon, s’il y a un jour des informations ajoutées (comme le codage du commit ou le commentaire étendu du commit), un visualisateur de blame ne s’en souciera pas.

TRANSFORMER LES AUTEURS

Voir gitmailmap[5].

CONFIGURATION

Tout ce qui se trouve en dessous de cette ligne dans cette section est inclus de manière sélective à partir de la documentation git-config[1]. Le contenu est le même que celui qui s’y trouve :

Warning

Missing fr/config/blame.adoc

See original version for this content.

VOIR AUSSI

git-annotate[1]

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 .

Setup and Config

Getting and Creating Projects

Basic Snapshotting

Branching and Merging

Sharing and Updating Projects

Inspection and Comparison

Patching

Debugging

Email

External Systems

Server Admin

Guides

Administration

Plumbing Commands

NOM