Log avançado do Git

Assim você sabe que o commit superior também foi verificado (indicado por HEAD) e que também é a ponta do branch main. O segundo commit tem outro branch apontando para ele chamado feature e, finalmente, o 4º commit é marcado como v0.9.

Branches, tags, HEAD e o histórico de commits são quase todas as informações contidas no seu Repositório do Git, então isso dá a você uma visão mais completa da estrutura lógica do seu repositório.

O comando git log inclui muitas opções para exibir comparações com cada commit. Duas das opções mais comuns são --stat e -p.

A opção --stat exibe o número de inserções e exclusões para cada arquivo alterado por cada commit (observe que a modificação de uma linha é representada como 1 inserção e 1 exclusão). É útil quando você quer um breve resumo das alterações introduzidas por cada commit. Por exemplo, o seguinte commit adicionou 67 linhas ao arquivo hello.py e removeu 38 linhas:

A quantidade de sinais + e - ao lado do nome do arquivo mostra o número relativo de alterações em cada arquivo alterado pelo commit. Isso lhe dá uma ideia de onde as alterações para cada commit podem ser encontradas.

Se você quiser ver as mudanças reais introduzidas por cada commit, você pode passar a opção -p para o git log. Isso gera todo o patch representando esse commit:

O comando git shortlog é uma versão especial do git log destinada a criar anúncios de lançamento. Ele agrupa cada commit por autor e exibe a primeira linha de cada mensagem de commit. Essa é uma maneira fácil de ver quem está trabalhando em quê.

Por exemplo, se dois desenvolvedores contribuíram com 5 commits para um projeto, a saída do git shortlog pode ser a seguinte:

Por padrão, o git shortlog classifica a saída pelo nome do autor, mas você também pode passar a opção -n para classificar pelo número de commits por autor.

A opção --graph desenha um gráfico ASCII representando a estrutura de branch do histórico de commits. Ela costuma ser usada em conjunto com os comandos --oneline e --decorate para facilitar a visualização de qual commit pertence a qual branch:

Para um repositório simples com apenas dois branches, o resultado vai ser o seguinte:

O asterisco mostra em qual branch o commit estava, então o gráfico acima diz que os commits 23ad9ad e 16b36c6 estão em um branch de tópico e o restante está no branch main.

Embora essa seja uma boa opção para repositórios simples, você provavelmente está melhor com uma ferramenta de visualização mais completa, como gitk ou Sourcetree para projetos que têm muitos branches.

Para todas as suas outras necessidades de formatação do git log, você pode usar a opção --pretty=format:"". Assim você pode exibir cada commit da maneira que quer usando espaços reservados no estilo printf.

Por exemplo, os caracteres %cn, %h e %cd no comando a seguir são substituídos pelo nome do committer, pelo hash do commit abreviado e pela data do committer, respectivamente.

Isso resulta no seguinte formato para cada commit:

A lista completa de espaços reservados pode ser encontrada na seção Formatos bonitos da página de manual do git log.

Além de permitir que você visualize apenas as informações de seu interesse, a opção --pretty=format:"" é particularmente útil quando você está tentando canalizar a saída do git log para outro comando.

Formatar como cada commit é exibido é apenas metade da batalha de aprender git log. A outra metade é entender como navegar pelo histórico de commits. O restante deste artigo apresenta algumas das maneiras avançadas de escolher commits específicos no histórico do seu projeto usando o git log. Tudo isso pode ser combinado com qualquer uma das opções de formatação discutidas acima.

Se você estiver procurando por um commit de um período específico, você pode usar as marcações --after ou --before para filtrar commits por data. Ambos aceitam uma variedade de formatos de data como parâmetro. Por exemplo, o comando a seguir mostra apenas os commits que foram criados após 1º de julho de 2014 (inclusive):

Você também pode passar referências relativas como "1 semana atrás" e "ontem":

Para pesquisar commits que foram criados entre duas datas, você pode indicar uma data --before e uma --after. Por exemplo, para exibir todos os commits adicionados entre 1º de julho de 2014 e 4 de julho de 2014, você usaria o seguinte:

Quando você estiver procurando apenas por commits criados por um usuário específico, use a marcação --author. Isso aceita uma expressão regular e retorna todos os commits cujo autor corresponde a esse padrão. Se você sabe exatamente quem está procurando, você pode usar uma cadeia de caracteres antiga simples em vez de uma expressão regular:

Isso exibe todos os commits cujo autor inclui o nome John. O nome do autor não precisa ser uma correspondência exata — ele só precisa conter a frase especificada.

Você também pode usar expressões regulares para criar pesquisas mais complexas. Por exemplo, o comando a seguir procura por commits feitos por Mary ou John.

Observe que o e-mail do autor também está incluído com o nome do autor, para que você possa usar essa opção para pesquisar por e-mail também.

Se o fluxo de trabalho separa os committers dos autores, a marcação --committer vai funcionar da mesma maneira.

Para filtrar os commits por sua mensagem de commit, use a marcação --grep. O funcionamento é exatamente o mesmo daquele da marcação --author discutido acima, mas combina com a mensagem do commit em vez do autor.

Por exemplo, se sua equipe incluir números de itens relevantes em cada mensagem de commit, você vai poder usar algo como o seguinte para extrair todos os commits relacionados a esse item:

Você também pode passar o parâmetro -i para o git log para fazer com que ele ignore as diferenças de maiúsculas e minúsculas durante a correspondência de padrões.

Muitas vezes, você só está interessado nas mudanças que aconteceram em um determinado arquivo. Para mostrar o histórico relacionado a um arquivo, tudo o que você precisa fazer é passar o caminho do arquivo. Por exemplo, o seguinte retorna todos os commits que afetaram o arquivo foo.py ou bar.py:

O parâmetro -- é usado para informar ao git log que os argumentos subsequentes são caminhos de arquivo e não nomes de branches. Se não houver possibilidade de fazer confusão com um branch, você pode omitir o --.

Também é possível pesquisar por commits que introduzem ou removem uma determinada linha de código-fonte. Isso é chamado de pickaxe e assume a forma de -S"". Por exemplo, se você quiser saber quando a cadeia de texto Hello, World! foi adicionada a qualquer arquivo no projeto, você usaria o seguinte comando:

Se você quiser pesquisar usando uma expressão regular em vez de uma cadeia de caracteres, você pode usar a marcação -G"".

Esta é uma ferramenta de depuração muito poderosa, pois permite localizar todos os commits que afetam uma determinada linha de código. Pode até mostrar quando uma linha foi copiada ou movida para outro arquivo.

Você pode passar um intervalo de commits para o git log para mostrar apenas os commits contidos nesse intervalo. O intervalo é especificado no seguinte formato, onde e são referências de commit:

Esse comando é particularmente útil quando você usa referências de branch como parâmetros. É uma maneira simples de mostrar as diferenças entre dois branches. Considere o seguinte comando:

O intervalo main..feature contém todos os commits que estão no branch do feature, mas não estão no branch main. Em outras palavras, é o progresso que o feature alcançou desde que se separou do main. Você pode visualizar isso da seguinte forma:

Note que se você mudar a ordem do intervalo (feature..main), você vai obter todos os commits em main, mas não em feature. Se o git log gerar commits para ambas as versões, isso indica que seu histórico divergiu.

Por padrão, o git log inclui commits de merge no resultado. Mas, se sua equipe tiver uma política de merge contínuo (ou seja, você fizer merge das alterações upstream em branches de tópico em vez de fazer o rebase do branch de tópico no branch upstream), você vai ter muitos commits de merge estranhos no histórico do projeto.

Você pode impedir que o git log exiba esses commits de merge passando a marcação --no-merges:

Por outro lado, se você tiver interesse apenas nos commits de merge, você pode usar a marcação --merges:

Isso retorna todos os commits que têm pelo menos dois pais.

Agora você deve estar bastante confortável usando os parâmetros avançados do git log para formatar sua saída e selecionar quais commits quer exibir. Isso dá a você o poder de extrair exatamente o que você precisa do histórico do seu projeto.

Essas novas habilidades são uma parte importante do seu kit de ferramentas do Git, mas lembre-se de que o git log é frequentemente usado em conjunto com outros comandos do Git. Depois de encontrar o commit que você está procurando, você normalmente o passa para git checkout, git revert ou alguma outra ferramenta para manipular seu histórico de commits. Portanto, continue aprendendo sobre as características avançadas do Git.