Git status: como inspecionar um repositório

git status

O comando git status exibe as condições do diretório de trabalho e da área de staging. Ele permite que você veja quais alterações foram despreparadas, quais não foram e quais arquivos não estão sendo monitorados pelo Git. Os resultados de status não exibem qualquer informação sobre o histórico de projetos que recebeu commit. Para tal, você precisa usar o git log.

Comandos relacionados ao git

git tag
- Os marcadores são referências que apontam para pontos específicos no histórico do Git. git tag é em geral usado para capturar um ponto no histórico que é usado para uma versão marcada (por exemplo, v1.0.1).
git blame
- A função git blame de alto nível é a exibição de metadados do autor anexados a linhas confirmadas específicas em um arquivo. É usado para explorar o histórico de código específico e responder dúvidas sobre o que, como e por que o código foi adicionado ao repositório.
git log
- O comando git log exibe instantâneos que receberam commit. Ele permite que você liste e filtre o histórico do projeto e pesquise alterações específicas.

Uso

git status

Lista quais arquivos foram preparados, despreparados e não foram monitorados.

Discussão

Em termos relativos, o comando git status é simples. Ele apenas mostra o que está acontecendo com o git add e o git commit. Mensagens de status também incluem instruções relevantes para a staging/unstaging de arquivos. Os resultados para exemplificação que exibem as três categorias principais de uma execução do git status estão incluídos abaixo:

# On branch main
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
#modified: hello.py
#
# Changes not staged for commit:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
#modified: main.py
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
#hello.pyc

Como ignorar arquivos

Arquivos não monitorados costumam se encaixar em duas categorias. São arquivos que acabaram de ser adicionados ao projeto e ainda não receberam commit, ou são binários compilados como .pyc, .obj, .exe, etc. Embora com certeza seja vantajoso incluir o primeiro tipo nos resultados do git status, a inclusão do segundo pode dificultar a visualização do que está acontecendo de fato no repositório.

Por esse motivo, o Git permite que você ignore arquivos por completo ao incluir caminhos em um arquivo especial chamado .gitignore. Quaisquer arquivos que você quer ignorar devem ser incluídos em uma linha separada e o símbolo * pode ser usado como forma genérica. Por exemplo, a adição da linha a seguir a um arquivo .gitignore na raiz do projeto vai evitar que módulos Python compilados apareçam no git status:

*.pyc

Exemplo

É recomendável verificar as condições do repositório antes das alterações receberem commit para que isso não aconteça por acidente em algo que você não quer. Esse exemplo exibe o status do repositório antes e depois da preparação e do commit de um instantâneo:

# Edit hello.py
git status
# hello.py is listed under "Changes not staged for commit"
git add hello.py
git status
# hello.py is listed under "Changes to be committed"
git commit
git status
# nothing to commit (working directory clean)

O primeiro resultado de status vai mostrar o arquivo como despreparado. A ação git add vai se refletir no segundo git status e o resultado de status final vai informar que não há nada a receber commit — o diretório de trabalho corresponde ao commit mais recente. Alguns comandos do Git (por exemplo, git merge) exigem que o diretório de trabalho esteja limpo para que alterações não sejam sobrescritas por acidente.

git log

O comando git log exibe instantâneos que receberam commit. Ele permite que você liste e filtre o histórico do projeto e pesquise alterações específicas. Embora o git status permita que o diretório de trabalho e a área de staging sejam inspecionados, o git log funciona apenas com o histórico que recebeu commit.

Os resultados de log podem ser personalizados de diversas formas, desde a filtragem simples de commits até a exibição em um formato definido pelo usuário por completo. Algumas das configurações mais comuns do git log estão apresentadas abaixo.

Uso

git log

Mostre todo o histórico de commits usando a formatação padrão. Se os resultados aparecerem em mais de uma tela, você pode usar Espaço para rolar e q para sair.

git log -n <limit>

Limite o número de commits usando . Por exemplo, git log -n 3 vai exibir apenas 3 commits.

Deixe cada commit em apenas uma linha. É útil para ter uma visão geral de alto nível do histórico do projeto.

git log --oneline

git log --stat

Junto com as informações básicas do git log, inclua os arquivos que foram alterados e o número relacionado de linhas adicionadas ou excluídas de cada um.

git log -p

Mostre o patch que representa cada commit. Essa ação mostra o diff completo de cada commit, a visão mais aprofundada que você pode ter do histórico do projeto.

git log --author="<pattern>"

Pesquise commits por autor. O argumento pode ser uma sequência simples ou uma expressão regular.

git log --grep="<pattern>"

Pesquise commits com uma mensagem de commit que corresponde ao , que pode ser uma sequência simples ou uma expressão regular.

git log <since>..<until>

Mostre apenas commits que ocorrem entre < since > e < until >. Os argumentos podem ser o ID de um commit, o nome de uma ramificação, um HEAD ou qualquer outro tipo de referência de revisão.

git log <file>

Mostre apenas commits que incluem o arquivo especificado. É um jeito fácil de ver o histórico de um arquivo em particular.

git log --graph --decorate --oneline

Algumas opções úteis a serem consideradas. A flag --graph traça um gráfico com base em texto dos commits no lado esquerdo das mensagens de commit. A opção --decorate adiciona os nomes das ramificações ou tags dos commits exibidos. A opção --oneline mostra informações sobre os commits em uma única linha, facilitando a navegação rápida entre commits.

Discussão

O comando git log é a ferramenta básica do Git para explorar o histórico de um repositório. É usado quando se precisa encontrar uma versão específica de um projeto ou saber quais alterações vão ser implantadas por meio do merge de uma ramificação de recurso.

commit 3157ee3718e180a9476bf2e5cab8e3f1e78a73b7
Author: John Smith

Em grande parte, é bem simples; contudo, é necessária certa explicação sobre a primeira linha. A sequência de 40 caracteres após commit é uma soma de verificação SHA-1 dos conteúdos do commit. Tem dois objetivos. Primeiro, garante a integridade do commit — se estiver corrompido, o commit gera uma soma de verificação diferente. Segundo, funciona como um ID exclusivo do commit.

Esse ID pode ser usado em comandos como git log .. para indicar commits específicos. Por exemplo, git log 3157e..5ab91 vai exibir tudo entre os commits com os IDs 3157e e 5ab91. Além das somas de verificação, nomes de ramificações (abordadas no Módulo de Ramificações) e a palavra-chave HEAD são outros métodos comuns para indicar commits individuais. HEAD sempre se refere ao commit atual, seja uma ramificação ou um commit específico.

O caractere ~ é útil para se fazerem referências relativas ao pai de um commit. Por exemplo, 3157e~1 se refere ao commit antes de 3157e e HEAD~3 é o bisavô do commit atual.

A ideia por trás de todos esses métodos de verificação é permitir que se realizem ações com base em commits específicos. O comando git log é o ponto de partida comum dessas interações, já que permite que sejam encontrados os commits com os quais se quer trabalhar.

Exemplo

A seção Uso apresenta muitos exemplos do git log, mas é importante lembrar que diversas opções podem ser combinadas com um único comando:

git log --author="John Smith" -p hello.py

Esse comando vai exibir um diff completo de todas as alterações que o John Smith fez no arquivo hello.py.

A sintaxe .. é uma ferramenta muito útil para a comparação entre ramificações. O exemplo a seguir apresenta um panorama simplificado de todos os commits que estão em some-feature que não estão no branch main.