O Git vê cada arquivo em sua cópia de trabalho em um de três estados:

  1. rastreado – um arquivo que já passou pelo staging ou foi confirmado;
  2. não rastreado – um arquivo que não passou pelo staging nem foi confirmado; ou
  3. ignorado – um arquivo que o Git foi forçado a ignorar.

Os arquivos ignorados costumam ser artefatos de desenvolvimento e arquivos gerados por máquina que podem ser derivados da fonte do seu repositório ou que não devem ser confirmados. Exemplos comuns incluem:

  • caches de dependência, como o conteúdo de /node_modules ou /packages
  • código compilado, como arquivos .o , .pyc e .class
  • diretórios de saída compilados, como /bin,/out ou /target
  • arquivos gerados no período de execução, como log, .lock ou .tmp
  • arquivos de sistema ocultos, como.DS_Store ou Thumbs.db
  • arquivos pessoais de configuração do IDE, como .idea/workspace.xml

Os arquivos ignorados são rastreados em um arquivo especial chamado .gitignore, que é verificado na origem do seu repositório. Não há nenhum comando git ignore explícito: em vez disso, é preciso editar e fazer o commit do arquivo .gitignore à mão quando você tiver novos arquivos que quer ignorar. Os arquivos .gitignore contêm padrões que são comparados com nomes de arquivos em seu repositório para determinar se devem ou não ser ignorados.

Padrões do Git ignore

O .gitignore usa padrões globbing para fazer a comparação dos nomes de arquivos. Você pode construir seus padrões usando vários símbolos:

Padrão Exemplo de correspondências Explicação*
**/logs logs/debug.log
logs/monday/foo.bar
build/logs/debug.log
Você pode prefixar um padrão com um asterisco duplo para combinar diretórios em qualquer lugar no repositório.
**/logs/debug.log logs/debug.log
build/logs/debug.log
but not
logs/build/debug.log
Você também pode usar um asterisco duplo para combinar arquivos com base no nome do arquivo e do diretório pai.
*.log debug.log
foo.log
.log
logs/debug.log
Um asterisco é um curinga que corresponde a zero ou mais caracteres.
*.log
!important.log
debug.log
trace.log
but not
important.log
logs/important.log
Inserir um ponto de exclamação a um padrão faz com que ele seja negado. Se um arquivo corresponder a um padrão, mas também corresponder a um padrão de negação definido mais tarde no arquivo, não vai ser ignorado.
*.log
!important/*.log
trace.*
debug.log
important/trace.log
but not
important/debug.log
Os padrões definidos após um padrão de negação vão ignorar de volta todos os arquivos já negados.
/debug.log debug.log
but not
logs/debug.log
Prefixar uma barra obriga a correspondência apenas com arquivos na origem do repositório.
debug.log debug.log
logs/debug.log
Por definição, os padrões fazem a correspondência com arquivos em qualquer diretório
debug?.log debug0.log
debugg.log
but not
debug10.log
Um ponto de interrogação corresponde exatamente a um caractere.
debug[0-9].log debug0.log
debug1.log
but not
debug10.log
Os colchetes também podem ser usados para corresponder a um único caractere de um intervalo especificado.
debug[01].log debug0.log
debug1.log
but not
debug2.log
debug01.log
Os colchetes correspondem a um único caractere no conjunto especificado.
debug[!01].log debug2.log
but not
debug0.log
debug1.log
debug01.log
Um ponto de exclamação pode ser usado para simolizar qualquer caractere, exceto um do conjunto especificado.
debug[a-z].log debuga.log
debugb.log
but not
debug1.log
Os intervalos podem ser numéricos ou alfabéticos.
logs logs
logs/debug.log
logs/latest/foo.bar
build/logs
build/logs/debug.log
Se você não anexar uma barra, o padrão vai combinar os arquivos e o conteúdo dos diretórios com esse nome. Na correspondência de exemplo à esquerda, os diretórios e arquivos chamados logs são ignorados
logs/ logs/debug.log
logs/latest/foo.bar
build/logs/foo.bar
build/logs/latest/debug.log
Acrescentar uma barra indica que o padrão é um diretório. Todo o conteúdo de qualquer diretório no repositório que corresponda a esse nome – incluindo todos os seus arquivos e subdiretórios – vai ser ignorado.
Registos
!logs/important.log
logs/debug.log
logs/important.log
Espere um minuto! O logs/important.log não deve ser negado no exemplo à esquerda?

Não! Devido a uma peculiaridade relacionada à performance no Git, você não pode negar um arquivo que é ignorado devido a um padrão correspondente a um diretório
logs/***/debug.log logs/debug.log
logs/monday/debug.log
logs/monday/pm/debug.log
Um asterisco duplo corresponde a zero ou mais diretórios.
logs/*day/debug.log logs/monday/debug.log
logs/tuesday/debug.log
but not
logs/latest/debug.log
Os curingas também podem ser usados em nomes de diretórios.
logs/debug.log logs/debug.log
but not
debug.log
build/logs/debug.log
Os padrões que especificam um arquivo em um determinado diretório são relativos à origem do repositório. (Você pode prefixar uma barra se quiser, mas não acontece nada de especial.)

** essas explicações supõem que seu arquivo.gitignore está no diretório de nível superior do seu repositório, assim como a convenção. Se seu repositório tiver vários arquivos .gitignore, substitua “origem do repositório” por “diretório que contém o arquivo .gitignore” (e pense em unir todos eles, para a sanidade de sua equipe).*

Além desses caracteres, você pode usar # para incluir comentários no arquivo .gitignore:

# ignore all logs
*.log

Para desconsiderar os caracteres do padrão .gitignore, use \:

# ignore the file literally named foo[01].txt
foo\[01\].txt

Arquivos .gitignore compartilhados no seu repositório

As regras do git ignore costumam ser definidas em um arquivo .gitignore na origem do seu repositório. No entanto, você pode optar por definir vários arquivos .gitignore em diretórios diferentes no repositório. Cada padrão em um arquivo .gitignore específico é testado em relação ao diretório que contém esse arquivo. No entanto, a convenção, e a abordagem mais simples, é definir um único arquivo .gitignore na origem. Conforme seu arquivo .gitignore é verificado, ele é atualizado como qualquer outro arquivo em seu repositório e compartilhado com seus colegas quando você faz o push. No geral, você só deve incluir padrões no .gitignore se eles beneficiarem outros usuários do repositório.

Regras pessoais do Git ignore

Você também pode definir padrões pessoais para o git ignore para um determinado repositório em um arquivo especial em .git/info/exclude. Esses arquivos não são atualizados nem distribuídos com seu repositório, portanto, é um lugar apropriado para incluir padrões que, talvez, só vão beneficiar você. Por exemplo, se você tiver uma configuração de log personalizada ou ferramentas especiais de desenvolvimento que produzem arquivos no diretório atual do seu repositório, você pode preferir que sejam adicionadas ao .git/info/exclude para evitar que sejam confirmadas por acidente em seu repositório.

Regras globais do Git ignore

Além disso, você pode definir padrões globais do Git ignore para todos os repositórios em seu sistema local definindo a propriedade Git core.excludesFile. Você mesmo vai ter que criar este arquivo. Se não tiver certeza de onde colocar o arquivo .gitignore global, seu diretório pessoal pode ser uma boa escolha (e fica mais fácil encontrar mais tarde). Depois de criar o arquivo, você vai precisar configurar sua localização com o git config:

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

Você deve ter cuidado com quais padrões escolhe ignorar por completo, pois diferentes tipos de arquivo são relevantes para diferentes projetos. Arquivos especiais do sistema operacional (por exemplo, .DS_Store e thumbs.db) ou arquivos temporários criados por algumas ferramentas de desenvolvimento são opções comuns a serem ignoradas por completo.

Como ignorar um arquivo após o commit

Caso queira ignorar um arquivo após o commit, vai precisar excluir o arquivo do repositório e, em seguida, adicionar uma regra .gitignore para ele. Usar a opção --cached com git rm faz o arquivo ser excluído do seu repositório, mas ele vai permanecer em seu diretório atual na forma de um arquivo ignorado.

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

Você pode omitir a opção --cached se quiser excluir o arquivo do repositório e do sistema de arquivos local.

Como fazer o commit de um arquivo ignorado

É possível forçar o commit de um arquivo ignorado no repositório usando a opção -f (ou --force) com git add:

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

Isso pode ser uma boa ideia se você tiver um padrão geral (como *.log) definido e também quiser fazer o commit um arquivo específico. No entanto, uma solução melhor é definir uma exceção à regra geral:

$ echo !debug.log >> .gitignore
$ cat .gitignore
*.log
!debug.log
$ git add debug.log
$ git commit -m "Adding debug.log"

Essa solução é mais óbvia e menos confusa para seus colegas.

Como fazer o stash de um arquivo ignorado

O recurso git stash é bastante potente para armazenar e reverter alterações locais temporariamente, o que possibilita fazer a reaplicação mais tarde. Como seria de se esperar, por padrão, o git stash ignora arquivos ignorados e apenas faz o stash das alterações em arquivos que são rastreados pelo Git. No entanto, você também pode usar o git stash com a opção --all para fazer o stash de alterações em arquivos ignorados e não rastreados.

Como depurar arquivos .gitignore

Se você tem padrões .gitignore complicados, ou padrões espalhados por vários arquivos .gitignore, pode ser difícil descobrir por que um determinado arquivo está sendo ignorado. Você pode usar o comando git check-ignore com a opção -v (ou --verbose) para determinar qual padrão está fazendo com que um arquivo específico seja ignorado:

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

O resultado mostra:

<arquivo contendo o padrão> : <número da linha do padrão> : <padrão> <nome do arquivo>

Você pode passar vários nomes de arquivos para o git check-ignore se quiser, e os nomes nem precisam corresponder aos arquivos que existem em seu repositório.

Pronto para aprender sobre o Git?

Experimente este tutorial interativo.

Comece agora mesmo