Gerador de .gitignore

O que é um gerador de .gitignore?

Um ficheiro .gitignore diz ao git que caminhos deve deixar em paz: resultados de compilação, pastas de dependências, restos do editor, tudo o que não quer no histórico. Um gerador dá-lhe um ficheiro de partida sensato para as tecnologias que usa, para não estar a escrever node_modules de cabeça sempre que começa um repositório.

A metade que gera é a metade fácil, e sozinha vale pouco: não se verifica uma lista de padrões olhando para ela. Por isso esta página emparelha-a com a parte que se pode verificar: cole um caminho e ela diz-lhe se o git o ignoraria, e que linha tomou essa decisão.

É nessa segunda metade que estão as surpresas. Um .gitignore não é uma lista de ficheiros, é um conjunto de regras com precedência, ancoragem e semântica de diretórios, e a regra que toda a gente cita está incompleta de uma forma que acaba por morder quase todos.

Como usar

1. Marque as tecnologias que está a usar. O ficheiro é composto a partir de modelos, com um cabeçalho por cada um. Os marcados como globais vão no seu próprio ~/.gitignore_global e não no repositório: a pasta do seu editor é assunto seu, não do projeto.
2. Edite o ficheiro à vontade. É uma caixa de texto normal. Se o que quer é o verificador, cole ali directamente um .gitignore que já tenha.
3. Escreva um caminho e leia o veredicto. Obtém se é ignorado ou não, o número e o texto da linha que decidiu e, quando se aplica, o diretório acima sobre o qual a decisão foi realmente tomada.

Porque !build/keep.txt não faz nada, e o que escrever em vez disso

A regra que toda a gente repete é que ganha o último padrão que corresponde. É verdadeira até onde vai, e prevê a resposta errada na dúvida mais comum sobre .gitignore. Com build/ numa linha e !build/keep.txt na seguinte, o ficheiro continua ignorado. O git concorda: se lhe perguntar, aponta a linha 1, a do diretório, como a que decidiu.

A razão é que o git não percorre uma lista plana de padrões contra o seu caminho. Percorre os diretórios do caminho de cima para baixo, e assim que um diretório fica excluído nunca mais entra nele. Não há ocasião para um padrão de baixo voltar a incluir seja o que for, porque nunca se olha para o que lá está dentro.

A correcção é um carácter. Exclua o conteúdo do diretório em vez do diretório: build/* em vez de build/. Aí o git entra, a negação é alcançada e build/keep.txt fica guardado enquanto todo o resto lá dentro continua ignorado. Esta ferramenta assinala-lhe a forma partida: lista qualquer negação que uma regra anterior tenha tornado inalcançável, portanto fica a saber antes de fazer commit e não depois de se interrogar porque é que o ficheiro nunca apareceu.

O resto da sintaxe também vale a pena conhecer, e o verificador exercita-a toda: uma barra em qualquer sítio que não o fim ancora o padrão ao diretório do próprio ficheiro, portanto /build só corresponde na raiz enquanto build corresponde a qualquer profundidade; uma barra final restringe o padrão a diretórios; um asterisco pára na barra mas um duplo atravessa-a; e um ponto de exclamação inicial nega, a não ser que o escape.

Limites honestos

Os modelos são um ponto de partida, não uma autoridade. São uma selecção do conjunto de domínio público que o github publica, e por baixo da ferramenta está a data em que este instantâneo foi tirado. Um modelo que não acompanhou algum diretório de compilação novo está incompleto, e isso vê-se e corrige-se na caixa de texto; é coisa diferente de estar errado.

Esta página raciocina ainda sobre um único ficheiro .gitignore de cada vez. Um repositório a sério pode ter vários — um por diretório, mais .git/info/exclude, mais o seu ficheiro global — e o git aplica-os do menos para o mais específico, portanto uma regra num subdiretório ganha a uma da raiz. O verificador responde pelo ficheiro que está na caixa, relativo ao sítio onde esse ficheiro se encontra.

Mais duas coisas que um caminho sozinho não lhe consegue dizer. Um ficheiro que já está a ser seguido continua a sê-lo por muito que o acrescente ao .gitignore, porque as regras de ignorar valem para ficheiros não seguidos; é preciso git rm --cached para deixar de o seguir. E isto raciocina sobre padrões e não sobre o seu disco, portanto trata o caminho exactamente como o escreve: a caixa está ali porque ser ou não um diretório muda a resposta para os padrões terminados em barra.

Por fim, os veredictos foram verificados contra o próprio git e não contra outra implementação: uma varredura gerada de 252 combinações de padrão e caminho, corrida num repositório a sério, sem uma única divergência.

Porque é grátis

Porque não custa nada manter. A comparação acontece no seu navegador; nenhum ficheiro é enviado, nenhum servidor vê os seus caminhos e não há conta nenhuma.

Os modelos são de domínio público, as regras dos padrões saem do comportamento documentado do próprio git, e o teste que compara esta implementação com o git está guardado ao lado do código.