.gitignore

Visão Geral

Em uma cópia de trabalho, o Git vê cada arquivo em um de três estados: rastreado (já no repositório ou em staging), não rastreado (novo e ainda não em staging), ou ignorado (explicitamente excluído). Este capítulo explica como fazer o Git ignorar arquivos usando um arquivo .gitignore: a sintaxe de padrões, onde as regras de ignore podem estar (por diretório, por repositório e global), e como lidar com casos complicados — ignorar um arquivo que já foi commitado, forçar o commit de um arquivo ignorado, fazer stash de arquivos ignorados e depurar por que um arquivo está sendo ignorado.

Arquivos ignorados são aqueles que você disse ao Git para pular. Eles nunca são colocados em staging, nunca são commitados e nunca aparecem no git status como ruído não rastreado. Candidatos típicos são arquivos que são gerados a partir do código-fonte em vez de criados manualmente:

• Arquivos criados em tempo de execução — logs, arquivos de lock (*.log, *.lock).
• Metadados do sistema operacional e da IDE — .DS_Store, Thumbs.db, .idea/, .vscode/.
• Saída compilada e dependências — *.o, *.class, node_modules/, dist/.
• Segredos e configuração local — .env, arquivos de credenciais.

A regra de ouro: se um arquivo pode ser regenerado a partir do código-fonte do repositório, ou é específico da sua máquina, ignore-o.

Padrões do Git ignore

As regras de ignore ficam em um arquivo de texto simples chamado .gitignore. Não existe um comando git ignore — você cria e edita o arquivo manualmente e o commita como qualquer outro arquivo. Cada linha não vazia é um padrão comparado com os caminhos dos arquivos; um arquivo é ignorado quando corresponde a um padrão.

Algumas regras se aplicam ao formato do arquivo em si:

• Uma linha em branco não corresponde a nada e é usada apenas para legibilidade.
• Uma linha que começa com # é um comentário. Para corresponder a um nome de arquivo que literalmente começa com #, escape-o como \#.
• Espaços no final são ignorados a menos que escapados com uma barra invertida (\).
• Os padrões são comparados em relação ao local do arquivo .gitignore.

Os padrões em si são construídos com estes símbolos:

Aqui está um pequeno .gitignore mostrando como debug?.log (o ? corresponde a exatamente um caractere) se comporta. Ele ignora debug0.log e debug1.log, mas não debug10.log, porque 10 são dois caracteres:

padrões .gitignore

debug?.log

# matches debug0.log, debug1.log, debug9.log
# does NOT match debug10.log (two characters)

Arquivos .gitignore compartilhados no repositório

Você pode definir vários arquivos .gitignore em diferentes diretórios do repositório. Cada padrão é testado em relação ao diretório que contém esse arquivo. No entanto, a maneira mais simples é definir um único arquivo .gitignore na raiz do repositório.

Como o arquivo .gitignore é incluído no repositório, ele é versionado como outros arquivos e é compartilhado com sua equipe quando você faz push. Você deve incluir apenas padrões no .gitignore que beneficiem outros usuários do repositório.

Regras pessoais de Git ignore

Padrões de ignore pessoais para um único repositório podem ser colocados no arquivo especial .git/info/exclude. Sua sintaxe é idêntica à do .gitignore, mas como o diretório .git não faz parte do conteúdo do repositório, essas regras não são versionadas e não são compartilhadas quando você faz push ou clone. Use este arquivo para backups de editor, arquivos temporários ou qualquer coisa específica ao seu próprio fluxo de trabalho que o restante da equipe não deve ter imposta a eles.

Regras globais de Git ignore

Você pode definir a propriedade Git core.excludesFile para especificar adicionalmente padrões globais de Git ignore para todos os repositórios no seu sistema local. Este arquivo será criado por você mesmo. Você pode colocar seu arquivo .gitignore global no seu diretório home para encontrá-lo facilmente. Depois de criar o arquivo, configure sua localização com o comando git config, assim:

regras gitignore globais

touch ~/.gitignore
git config --global core.excludesFile ~/.gitignore

Ignorando um arquivo previamente commitado

Adicionar um padrão ao .gitignore não faz o Git parar de rastrear um arquivo que já foi commitado — as regras de ignore se aplicam apenas a arquivos não rastreados. Para começar a ignorar tal arquivo, você deve primeiro removê-lo do índice do Git. Use git rm com a opção --cached: isso coloca em staging a remoção do arquivo do repositório enquanto mantém a cópia no seu disco como um arquivo ignorado. Em seguida, faça o commit da mudança.

arquivos commitados no .gitignore

echo debug.log >> .gitignore
git rm --cached debug.log
#rm 'debug.log'
git commit -m "Start ignoring debug.log"

Se você também quiser que o arquivo seja removido do seu diretório de trabalho, omita --cached (git rm debug.log). Use git status depois para confirmar que o arquivo não aparece mais como rastreado ou não rastreado.

Commitando um arquivo ignorado

O arquivo ignorado pode ser commitado no repositório com a combinação da opção -f (ou --force) com git add. No entanto, escolha esse caminho caso você tenha um padrão geral, como *.log, mas queira commitar um arquivo específico:

commitando arquivos ignorados

cat .gitignore
# *.log
git add -f debug.log
git commit -m "Force adding debug.log"

Caso contrário, a maneira mais simples é definir uma exceção à regra geral:

commitar arquivos ignorados

echo '!debug.log' >> .gitignore

cat .gitignore
#*.log
#!debug.log

git add debug.log
git commit -m "Adding debug.log"

Fazendo stash de um arquivo ignorado

O comando git stash pega suas alterações não commitadas em staging e fora de staging, as salva para mais tarde e reverte sua cópia de trabalho para um estado limpo. Por padrão, ele faz stash apenas de alterações em arquivos rastreados — arquivos ignorados e não rastreados são deixados no lugar. Duas opções ampliam esse escopo:

• git stash --include-untracked (ou -u) também faz stash de arquivos não rastreados.
• git stash --all (ou -a) também faz stash de arquivos não rastreados e ignorados.

git stash --all

Depurando arquivos .gitignore

Com padrões complicados, ou regras espalhadas por vários arquivos .gitignore, pode ser difícil saber qual regra está ocultando um arquivo. O comando git check-ignore com -v (ou --verbose) relata o padrão exato responsável:

git verificar arquivos ignorados

git check-ignore -v debug.log
#.gitignore:3:*.log    debug.log

A saída tem quatro campos separados por dois-pontos (e um espaço antes do nome do arquivo):

<file containing the pattern>:<line number of the pattern>:<pattern>    <file name>

Então .gitignore:3:*.log debug.log significa: a regra *.log na linha 3 do .gitignore é o que faz com que debug.log seja ignorado. Se o comando não imprimir nada, o arquivo não está sendo ignorado por nenhuma regra.

Capítulos relacionados

• git rm — remover arquivos do rastreamento, a chave para ignorar um arquivo já commitado.
• git add — colocar arquivos em staging, incluindo -f para forçar a adição de um arquivo ignorado.
• git stash — salvar alterações de lado; combine com --all para incluir arquivos ignorados.
• git config — definir core.excludesFile para uma lista de ignore global.
• git clean — excluir arquivos não rastreados; use com -x para também remover os ignorados.

Prática