Git
Português (Brasil) ▾ Topics ▾ Latest version ▾ git-blame last updated in 2.34.1

NOME

git-blame - Exiba qual revisão e qual foi o autor que alterou cada linha de um arquivo pela última vez

RESUMO

git blame [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]
	    [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<data>]
	    [--ignore-rev <rev>] [--ignore-revs-file <arquivo>]
	    [--progress] [--abbrev=<n>] [<rev> | --contents <arquivo> | --reverse <rev>..<rev>]
	    [--] <arquivo>

DESCRIÇÃO

Anota cada linha no arquivo informado com informações da revisão que modificou a linha pela última vez. Opcionalmente, comece a anotar a partir da revisão informada.

Quando informado uma ou mais vezes, a opção -L limita a anotação às linhas solicitadas.

A origem das linhas é seguida automaticamente pelas renomeações através de todos os arquivos (atualmente não há uma opção para desativar a presente renomeação). Para seguir as linhas movidas de um arquivo para outro ou para seguir as linhas que foram copiadas e coladas de um outro arquivo, etc., consulte as opções -C e -M.

O relatório não informa nada sobre quais as linhas foram eliminadas ou quais foram substituídas; é necessário utilizar uma ferramenta como "git diff" ou a interface "pickaxe" mencionada de forma breve no parágrafo seguinte.

Além de oferecer compatibilidade à anotação do arquivo, o Git também é compatível com a pesquisa no histórico do desenvolvimento para quando ocorra uma alteração em um trecho do código. Isso torna possível o monitoramento quando um trecho do código for adicionado em um arquivo, movido ou copiado entre os arquivos e eventualmente tenha sido excluído ou substituído. Funciona pesquisando uma sequência de texto no diff. Um pequeno exemplo da interface "pickaxe" que pesquisa por blame_usage:

$ git log --pretty=oneline -S'blame_usage'
5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <ancestry-file>
ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output

OPÇÕES

-b

Exiba o SHA-1 em branco para os commits limite. Também pode ser controlado através da opção da configuração blame.blankboundary.

--root

Não trate os commits raiz como limitadores. Também pode ser controlado através da opção da configuração blame.showRoot.

--show-stats

Inclui estatísticas adicionais no fim da saída do comando blame.

-L <inicio>,<fim>
-L :<funcname>

Anote apenas o intervalo das linhas informadas. Pode ser utilizado mais de uma vez. As variações sobrepostas são permitidas.

<inicio> e <fim> são opcionais. “-L <inicio>” ou “-L <inicio>,” abrange do <inicio> para o final do arquivo. “-L ,<fim>” abrange do começo ao <fim>.

<inicio> e <fim> podem assumir uma destas formas:

  • número

    Caso <inicio> ou <fim> seja um número, ele especifica um número de linha absoluto (as linhas contam a partir do 1).

  • /regex/

    Este formulário usará a primeira linha correspondente ao regex POSIX informado. Caso <inicio> seja um regex, ele procurará no final do L do intervalo, se houver, caso contrário, desde o início do arquivo. Caso <inicio> seja “^/regex/”, ele pesquisará desde o início do arquivo. Caso <fim> seja um regex, ele pesquisará a partir da linha fornecida através do <inicio>.

  • +offset ou -offset

    Válido apenas para <fim> que definirá uma quantidade de linhas antes ou depois da linha utilizada por <inicio>.

Caso “:<funcname>” seja informado no lugar de <inicio> e <fim>, é uma expressão regular que indica o intervalo da primeira "funcname" que coincide com <funcname> até a próxima linha "funcname". “:<funcname>” pesquisa no final do intervalo L anterior, se houver, caso contrário, a pesquisa ocorrerá desde o início do arquivo. “^:<funcname>” pesquisa desde o início do arquivo.

-l

Exibe o rev longo (Predefinição: desligado).

-t

Exibe o registro de data e hora em formato bruto (Predefinição: desligado).

-S <revs-file>

Utilize as revisões do arquivo-revs no lugar de chamar git-rev-list[1].

--reverse <rev>..<rev>

Avance a história adiante em vez de retroceder. Em vez de exibir a revisão onde a linha apareceu, exibe a última revisão na qual a linha já existiu. É necessário um intervalo de revisões como START..END (INICIO..FIM) onde o caminho reclamado exista em START. Por mera conveniência, o comando git blame --reverse START é atalho para git blame --reverse START..HEAD.

-p
--porcelain

Exiba em um formato designado para o consumo de uma máquina.

--line-porcelain

Exiba o formato porcelana, porém envie informações do commit na saída para cada linha e não apenas na primeira vez que um commit tiver uma referência. Implica no uso da opção --porcelain.

--incremental

Exiba o resultado incrementadamente em um formado designado para o consumo de uma máquina.

--encoding=<codificação>

Defina a codificação a ser utilizada para gerar os nomes dos autores e do resumo dos commits. Definindo como none torna a saída "blame" em dados sem conversão. Para mais informações, consulte a discussão sobre codificação na página do manual git-log[1].

--contents <arquivo>

Quando <rev> não for definido, o comando anotará as alterações iniciando em sentido contrário na cópia da árvore de trabalho. Essa flag faz com que o comando pareça estar trabalhando na cópia da árvore de trabalho que tenha os conteúdos informados do arquivo (especifique - para que o comando leia a partir da entrada padrão).

--date <formato>

Especifica o formato utilizado para gerar as datas. Caso --date não seja utilizado, o valor da variável de configuração blame.date será utilizado. Caso a variável de configuração blame.date também não esteja definida, o formato ISO será utilizado. Para ver quais são os valores compatíveis, consulte a discussão da opção --date em git-log[1].

--[no-]progress

É predefinido que a condição do progresso seja relatado no fluxo de erros padrão quando estiver conectado em um terminal. Essa flag permite que os relatórios de progresso sejam feitos ainda que não estejam conectados em um terminal. Não é possível usar --progress junto com --porcelain ou --incremental.

-M[<num>]

Detecte as linhas movidas ou copiadas em um arquivo. Quando um commit move ou copia um bloco de linhas (o arquivo original possui A e, em seguida, B, e o commit muda para B e, em seguida, A por exemplo), o algoritmo tradicional de blame percebe apenas metade do movimento e normalmente responsabiliza as linhas que forem movidos para cima (ou seja, B) para a origem e atribuem a responsabilidade às linhas que foram movidas para baixo (ou seja, A) para o herdeiro do commit. Com esta opção, os dois grupos das linhas são atribuídos à origem durante a execução dos passes extras de inspeção.

A opção <num> é opcional porém é o limite inferior da quantidade de caracteres alfanuméricos que o Git deve detectar como mover/copiar dentro de um arquivo para associar essas linhas ao commit de origem. 20 é o valor predefinido.

-C[<num>]

Além de -M, detecte as linhas movidas ou copiadas de outros arquivos que foram alterados no mesmo commit. É útil ao reorganizar o seu programa e move o código através dos arquivos. Quando essa opção é utilizada duas vezes, o comando procura adicionalmente cópias dos outros arquivos no commit que cria o arquivo. Quando essa opção é utilizada três vezes, o comando procura adicionalmente por cópias dos outros arquivos em qualquer outro commit.

A opção <num> é opcional porém é o limite inferior da quantidade de caracteres alfanuméricos que o Git deve detectar como mover/copiar entre os arquivos para associar estas linhas ao commit de origem. 40 é o valor predefinido. Caso haja mais de uma opção -C, o argumento <num> do último -C entrará em vigor.

--ignore-rev <rev>

Ignore as alterações feitas pela revisão assumindo a responsabilidade como se a mudança nunca tivesse acontecido. As linhas que foram alteradas ou adicionadas através de um commit ignorado serão responsabilizados pelo commit anterior que alterou esta linha ou as próximas. Esta opção pode ser utilizada várias vezes para ignorar mais de uma revisão. Caso a opção da configuração blame.markIgnoredLines estiver definida, as linhas que forem alteradas por um commit ignorado e atribuídas a outro commit, serão marcados com um`?. Caso a opção da configuração `blame.markUnblamableLines estiver definida, as linhas tocadas por um commit ignorado onde não foi possível atribuir uma outra revisão, serão marcadas com um *.

--ignore-revs-file <arquivo>

Ignore as revisões listadas no arquivo que deve estar no mesmo formato que um fsck.skipList. Esta opção pode ser repetida, estes arquivos serão processados após qualquer outro arquivo definido com a opção da configuração blame.ignoreRevsFile. Um nome vazio de arquivo, "" limpará a lista de rotações dos arquivos processados anteriormente.

-h

Exiba a mensagem de ajuda.

-c

Utilize o mesmo modo de saída como o git-annotate[1] (Predefinição: desligado).

--score-debug

Inclua as informações de depuração relacionadas a movimentação das linhas entre os arquivos (consulte -C) e as linhas que foram movidas dentro de um arquivo (consulte -M). O primeiro número listado é a pontuação. Esta é a quantidade de caracteres alfanuméricos detectados como movidos entre os arquivos ou dentro deles. Deve estar acima de um certo limite para que o comando git blame considere que estas linhas do código tenham sido movidas.

-f
--show-name

Exiba o nome do arquivo no commit original. É predefinido que o nome do arquivo seja exibido caso haja alguma linha que tenha vindo de um arquivo com um nome diferente, devido à detecção de renomeação.

-n
--show-number

Exiba o número da linha no commit original (Predefinição: desligado).

-s

Suprima o nome do autor e o registro de data e hora da saída.

-e
--show-email

Exiba o endereço e-mail do autor em vez do se nome (Predefinição: desligado). Também pode ser controlado através da opção da configuração blame.showEmail.

-w

Ignore os espaços durante a comparação da versão das origens e seus herdeiros para descobrir de onde vieram as linhas.

--abbrev=<n>

Em vez de utilizar os dígitos 7+1 hexadecimais predefinidos como o nome abreviado do objeto, utilize <n>+1 dígitos. Observe que uma coluna é utilizada para um sinal de intercalação para marcar o limite do commit.

O FORMATO PORCELANA

Nesse formato, cada linha é enviada após um cabeçalho; o cabeçalho no mínimo tem a primeira linha que tem:

  • 40-byte SHA-1 do commit da linha é atribuído a;

  • o número da linha no arquivo original;

  • o número da linha no arquivo final;

  • em uma linha que inicie um grupo de linhas a partir de um commit diferente ao anterior, a quantidade de linhas neste grupo. Nas linhas subsequentes este campo está ausente.

Esta linha de cabeçalho é seguida pelas seguintes informações por pelo menos uma vez para cada commit:

  • o nome do autor ("autor"), email ("autor-mail"), tempo ("author-time") e o fuso horário ("autor-tz"); da mesma forma para quem realizou o commit.

  • o nome do arquivo no commit ao qual a linha seja atribuída.

  • a primeira linha da mensagem do registro log do commit ("resumo").

O conteúdo da linha real é gerado após o cabeçalho acima, prefixado por um TAB. Permite adicionar mais elementos de cabeçalho posteriormente.

O formato porcelana geralmente suprime as informações dos commits que já foram vistos. Duas linhas forem atribuídos ao mesmo commit serão exibidos, porém os detalhes deste commit serão exibidos apenas uma vez por exemplo. É mais eficiente porém pode exigir que mais condições sejam mantidos pelo leitor. A opção --line-porcelain pode ser utilizado para gerar informações completas do commit em cada linha, permitindo um uso mais simples (porém menos eficiente), como:

# conta a quantidade de linhas atribuídas para cada autor
git blame --line-porcelain file |
sed -n 's/^author //p' |
sort | uniq -c | sort -rn

DEFININDO OS INTERVALOS

Ao contrário do comando git blame e do git annotate nas versões mais antigas do git, a extensão da anotação pode ser limitada a intervalos de linhas e de revisão. A opção -L, que limita a anotação a um intervalo de linhas, pode ser utilizada várias vezes.

Quando quiser encontrar a origem para as linhas 40-60 do arquivo foo, utilize a opção` -L` assim (eles significam a mesma coisa - ambos pedem 21 linhas iniciando na linha 40):

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

Você tambem pode utilizar uma expressão regular para determinar o intervalo da linha:

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

que limita a anotação ao corpo da sub-rotina hello.

Quando não quiser encontrar as alterações mais antigas que a versão v2.6.18 ou nas alterações anteriores a 3 semanas, utilize especificadores de intervalo da revisão similares ao git rev-list:

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

Quando os especificadores de intervalo da revisão forem utilizados para limitar a anotação, as linhas que não foram alteradas desde o limite do intervalo (seja o commit v2.6.18 ou o commit mais recente que seja 3 semanas mais antigo como no exemplo acima) são responsabilizadas por este limite do intervalo do commit.

Uma maneira particularmente útil é verificar se um arquivo que foi adicionado possua linhas criadas através de um copiar e colar vindos dos arquivos já existentes. Às vezes isso indica que o desenvolvedor estava sendo desleixado e não reorganizou o código corretamente. Você pode encontrar primeiro o commit que introduziu o arquivo com o comando:

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

e então anote a alteração entre o commit e as suas origens, utilizando a notação commit^!:

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

SAÍDA INCREMENTAL

Quando invocado com a opção --incremental, o comando gera o resultado conforme ele foi construído. A saída geralmente fala sobre as linhas tocadas pelos commits mais recentes primeiro (ou seja, as linhas serão anotadas fora de ordem) e deve ser utilizado por visualizadores interativos.

O formato da saída é semelhante ao formato Porcelana, mas não contém as linhas reais do arquivo que está sendo anotado.

  1. Cada entrada responsabilizada sempre começa com uma linha com:

    <40-byte hex sha1> <sourceline> <resultline> <num_lines>

    Os números das linhas começam a contagem a partir do 1.

  2. A primeira vez que um commit é exibido no fluxo, ele contém várias outras informações sobre ele impressas com uma tag de uma palavra no início de cada linha, descrevendo as informações adicionais do commit (autor, e-mail, quem fez o commit, as datas, resumo, etc.).

  3. Ao contrário do formato Porcelana, as informações do nome do arquivo são sempre informadas e encerram a entrada:

    "nome do arquivo" <citação-do-nome-do-arquivo-com-espaço-em-branco-vai-aqui>

    logo, é realmente muito fácil analisar alguma linha algo que seja orientado por palavra (que deve ser bastante natural para a maioria das linguagens de script).

    Note
    		 Para pessoas que fazem a analise: para torná-lo mais robusto, ignore todas as linhas entre a primeira e a última (linhas "<sha1>" e "filename") nas quais você não reconheça as palavras-chave (ou se preocupe com uma em particular) no início das linhas com "informações estendidas". Dessa forma, caso alguma vez haja informações que foram adicionadas (como a codificação do commit ou o comentário estendido do commit), um "blame viewer" não irá se importar.

MAPEANDO AUTORES

Caso o arquivo .mailmap exista no topo do repositório ou no local apontado pelas opções da configuração mailmap.file ou mailmap.blob, ele será utilizado para mapear os nomes dos autores e os endereços de email para os seus respectivos nomes e endereços de email verdadeiros.

No formato simples, cada linha do arquivo consiste no nome real de um autor, espaço e um endereço de email utilizado no commit (delimitado por < and >) mapeando para o nome. Por exemplo:

Nome Próprio <commit@email.xx>

Os formatos mais complexos são:

<proper@email.xx> <commit@email.xx>

o que permite que o mailmap substitua apenas a parte do email de um commit e:

Nome Próprio <proper@email.xx> <commit@email.xx>

o que permite que o mailmap substitua ambos os nomes e o email de um commit correspondente ao endereço de email do commit especificado, e:

Nome Próprio <proper@email.xx> Nome de quem fez o Commit <commit@email.xx>

o que permite que o mailmap substitua ambos os nomes e o email de um commit que corresponda a ambos os nomes de quem fez o commit e com o endereço de email.

Exemplo 1: O seu histórico contém confirmações de dois autores, Jane e Joe, cujos nomes aparecem no repositório de diferentes maneiras:

Joe Developer <joe@example.com>
Joe R. Developer <joe@example.com>
Jane Doe <jane@example.com>
Jane Doe <jane@laptop.(none)>
Jane D. <jane@desktop.(none)>

Agora, suponha que Joe queira que seu nome do meio seja utilizado no começo e Jane prefere que o nome de sua família seja escrito por extenso. Um arquivo .mailmap apropriado se pareceria com:

Jane Doe         <jane@desktop.(none)>
Joe R. Developer <joe@example.com>

Observe como não há necessidade de uma entrada para <jane@laptop.(none)> porque o nome real deste autor já está correto.

Exemplo 2: O seu repositório contém commits dos seguintes autores:

nick1 <bugs@company.xx>
nick2 <bugs@company.xx>
nick2 <nick2@company.xx>
santa <me@company.xx>
claus <me@company.xx>
CTO <cto@coompany.xx>

Então você pode querer um arquivo .mailmap parecido com:

<cto@company.xx>                       <cto@coompany.xx>
Some Dude <some@dude.xx>         nick1 <bugs@company.xx>
Other Author <other@author.xx>   nick2 <bugs@company.xx>
Other Author <other@author.xx>         <nick2@company.xx>
Santa Claus <santa.claus@northpole.xx> <me@company.xx>

Utilize o sinal de jogo da velha # para comentários que estejam em sua própria linha ou após o endereço de email.

VEJA TAMBÉM

git-annotate[1]

GIT

Parte do conjunto git[1]

scroll-to-top