Como usar o .gitignore: Uma introdução prática com exemplos

Tutoriais
Git

Ao trabalhar com o Git, manter seu repositório limpo e organizado não é apenas uma boa prática – é essencial para uma colaboração suave e um controle eficiente de versão. É aí que entra o .gitignore. Esse arquivo útil diz ao Git quais arquivos ignorar, evitando bagunça desnecessária e mantendo seus commits focados no que realmente importa.

Sem o .gitignore, seu repositório pode rapidamente se encher de arquivos temporários, logs e outras coisas que não pertencem ao controle de versão. Ainda pior, você pode compartilhar acidentalmente informações sensíveis.

Neste tutorial, você aprenderá como criar e usar um arquivo .gitignore para manter seu projeto organizado, evitar armadilhas comuns e trabalhar de forma mais eficaz com o Git. Vamos lá!

O que é um arquivo .gitignore?

Um arquivo .gitignore é um arquivo de configuração usado no Git para instruir o sistema de controle de versão sobre quais arquivos ou diretórios devem ser ignorados quando as alterações são preparadas ou confirmadas.

Ele impede que arquivos desnecessários – como arquivos temporários, gerados pelo sistema ou relacionados à compilação – baguncem seu repositório. Manter seu repositório limpo facilita a colaboração e garante que apenas arquivos essenciais sejam rastreados.

O arquivo .gitignore é um arquivo de texto simples colocado no diretório raiz do seu repositório Git. Ele contém padrões que indicam ao Git quais arquivos ou diretórios devem ser ignorados. Esses padrões podem ser personalizados para atender às necessidades do seu projeto, ajudando a manter um repositório bem organizado.

Novo no Git e GitHub? Obtenha uma introdução amigável para iniciantes ao controle de versão com este tutorial do GitHub e Git.

Aqui estão algumas categorias comuns de arquivos e diretórios que você deve considerar ignorar:

  • Artefatos de compilação: Arquivos gerados durante o processo de compilação que podem ser recriados a partir do código-fonte, como:
    • dist/, build/ (saídas de compilação de frontend e backend)
    • target/ (compilações de Java e outras linguagens)
  • Dependências: Sistemas de gerenciamento de pacotes criam diretórios para bibliotecas instaladas, que não devem ser rastreadas:
    • node_modules/ (Node.js)
    • vendor/ (PHP, Composer)
    • .venv/, venv/ (ambientes virtuais do Python)
  • Arquivos específicos do sistema: Esses arquivos são gerados automaticamente pelo sistema operacional e não contribuem para o projeto:
    • .DS_Store (macOS)
    • Thumbs.db (Windows)
  • Arquivos de configuração da IDE: Cada desenvolvedor pode usar um ambiente de desenvolvimento diferente, então suas configurações pessoais não devem ser incluídas no controle de versão:
    • .vscode/ (VS Code)
    • .idea/ (IDEs da JetBrains)
    • .project, .settings/ (Eclipse)
  • Logs e arquivos temporários: Logs, caches e arquivos temporários devem ser ignorados para evitar bagunça desnecessária:
    • *.log, npm-debug.log*, yarn-debug.log*, yarn-error.log* (Logs de várias ferramentas)
    • *.tmp, *.bak (Arquivos temporários e de backup)
    • .mypy_cache/, __pycache__/ (Caches do Python)
    • .ipynb_checkpoints/ (Pontos de verificação do Jupyter Notebook)
  • Arquivos de ambiente e segredo: Credenciais sensíveis e configurações específicas do ambiente nunca devem ser commitadas:
    • .env, .env.local, .env.development, .env.production
    • secrets.json, config.json (Arquivos de configuração sensíveis)
  • Banco de dados e arquivos de armazenamento: Estes são gerados localmente e não devem ser incluídos no controle de versão:
    • *.sqlite, *.sqlite3, *.db (Arquivos de banco de dados SQLite)
    • dump.rdb (Backup do banco de dados Redis)
  • Arquivos de CI/CD e cobertura: Relatórios de cobertura de teste e outros artefatos de CI/CD devem ser ignorados:
    • coverage/, *.lcov (Relatórios de cobertura de código)
    • .tox/, .pytest_cache/ (Arquivos de teste Python)

Precisa instalar o Git? Siga nosso guia passo a passo na tutorial de instalação do Git para configurar tudo rapidamente.

Sintaxe do .gitignore

Como mencionado, os arquivos .gitignore contêm padrões que são comparados com os nomes de arquivos em seu repositório para determinar se devem ser ignorados ou não.

Sintaxe básica

No seu cerne, o arquivo .gitignore consiste em linhas, cada uma representando um padrão a ser ignorado. Os padrões podem corresponder a:

  • Arquivos específicos
  • Tipos de arquivo
  • Diretórios

O arquivo também suporta comentários, que podem ser adicionados iniciando uma linha com #, e linhas em branco para melhorar a legibilidade.

Aqui está uma visão geral da estrutura básica:

  • Ignorar um arquivo específico: Você pode listar o nome do arquivo diretamente para ignorá-lo.
secrets.txt
  • Ignorar um diretório inteiro: Ao adicionar um / no final do nome do diretório, você pode ignorar tudo dentro desse diretório.
logs/
  • Ignorar todos os arquivos de um tipo específico: Wildcards (*) podem ser usados para ignorar todos os arquivos com uma extensão específica.
*.py
  • Negação: Você pode usar ! para negar um padrão e rastrear explicitamente certos arquivos ou diretórios que de outra forma seriam ignorados.
*.txt  # Ignores all .txt files
!readme.txt  # Except for readme.txt

Como Criar e Usar um Arquivo .gitignore

Criar e usar .gitignore é bastante simples. Nesta seção, vou guiar você pelos passos.

Criando um arquivo .gitignore

Passo 1: Navegue até a raiz do seu repositório. O arquivo .gitignore geralmente é colocado no diretório raiz de um projeto Git. Abra seu terminal ou linha de comando e navegue até o diretório raiz do seu repositório Git:

cd /path/to/your/repo

Passo 2: Crie o arquivo .gitignore. Uma vez no diretório raiz, crie o arquivo .gitignore usando qualquer editor de texto ou executando um comando no terminal, como:

touch .gitignore

Passo 3: Adicionar padrões ao arquivo. Abra o arquivo .gitignore em um editor de texto e adicione os padrões necessários para ignorar arquivos ou diretórios. Cada linha representa um padrão diferente.

Aqui está um exemplo de arquivo .gitignore comumente usado em um projeto básico:

# Ignorar node_modules e diretórios de dependência
node_modules/
vendor/

# Ignorar artefatos de compilação
dist/
build/
*.log

# Ignorar arquivos gerados pelo sistema
.DS_Store
Thumbs.db

# Ignorar arquivos de ambiente e secretos
.env
config.json

Depois de adicionar os padrões necessários, salve o arquivo. O Git agora irá automaticamente ignorar esses arquivos ao adicionar ou confirmar alterações.

Passo 4: Faça o commit do arquivo no repositório. É importante fazer o commit do arquivo .gitignore no repositório para que todos os colaboradores utilizem as mesmas regras de ignorar. Isso garante consistência em todo o projeto para todos os envolvidos.

git add .gitignore
git commit -m "Add .gitignore file"
git push

Uma vez que o arquivo .gitignore é comitado, você estabelece regras de ignorar compartilhadas para toda a equipe.

Quer dominar o push e o pull no Git? Aprenda como sincronizar seu trabalho com repositórios remotos neste tutorial de push e pull do Git.

Melhores Práticas para Usar .gitignore

Ao criar um arquivo .gitignore é uma parte direta de manter um repositório Git limpo, várias melhores práticas devem ser seguidas para garantir que o arquivo seja gerenciado de forma eficaz ao longo do tempo.

Use um .gitignore global

Para desenvolvedores trabalhando em vários projetos, existem arquivos específicos que você pode querer excluir de cada repositório, independentemente do tipo de projeto.

Em vez de adicioná-los ao arquivo .gitignore de cada projeto, você pode configurar um .gitignore global que se aplica a todos os repositórios em seu sistema.

Para configurar um arquivo .gitignore global:

  • Crie um arquivo .gitignore_global:
touch ~/.gitignore_global
  • Adicione padrões para arquivos que deseja ignorar globalmente, como:
.DS_Store
*.log
/.vscode/
/.idea/
  • Configure o Git para usar o .gitignore global:
git config --global core.excludesfile ~/.gitignore_global

Aproveite os modelos existentes

Em vez de construir um arquivo .gitignore do zero para cada novo projeto, você pode aproveitar modelos pré-configurados de .gitignore para linguagens, frameworks ou ambientes específicos.

Um dos melhores recursos para esses modelos é o repositório oficial .gitignore do GitHub, onde você pode encontrar arquivos .gitignore adaptados para centenas de linguagens de programação e frameworks.

Revise o .gitignore regularmente

À medida que os projetos evoluem, novos arquivos e diretórios podem precisar ser incluídos no arquivo .gitignore. É importante revisar e atualizar periodicamente seu arquivo para refletir o estado atual de seus projetos.

Alguns cenários em que você pode precisar atualizar o arquivo .gitignore incluem:

  • Adoção de novas ferramentas ou bibliotecas que geram arquivos adicionais (por exemplo, mudar para um novo sistema de compilação).
  • Refatoração ou reorganização de diretórios, o que pode resultar em novos arquivos que devem ser excluídos.
  • Remoção de arquivos ou diretórios obsoletos que não fazem mais parte do projeto.

Resolução de problemas com o .gitignore

Mesmo depois de configurar um arquivo .gitignore, você pode encontrar cenários onde arquivos específicos estão sendo rastreados, ou padrões que não parecem funcionar como esperado. Esta seção abordará duas áreas comuns de solução de problemas e como resolvê-las.

Rastreando arquivos já comprometidos 

O arquivo .gitignore não se aplica retroativamente a arquivos já comprometidos.

Se você adicionar um padrão ao .gitignore após certos arquivos já terem sido comprometidos, o Git continuará a rastreá-los mesmo que correspondam ao padrão no arquivo .gitignore.

Para parar de rastrear arquivos que já foram comprometidos, siga estes passos:

  • Remova os arquivos do controle do Git: Use o comando git rm para removê-los do repositório mantendo-os no seu diretório de trabalho.
git rm --cached <file_or_directory_name>
  • Commit as alterações: Após remover os arquivos do controle do Git, faça o commit das alterações para garantir que os arquivos não façam mais parte do histórico de controle de versão.
git commit -m "Stop tracking ignored files"
  • Envie as alterações para o repositório remoto: Por fim, envie as alterações para o repositório remoto para garantir que os arquivos não sejam mais rastreados.
git push

Depois de realizar essas etapas, o Git deixará de rastrear os arquivos. O arquivo commitado ainda estará no seu diretório de trabalho, mas será ignorado por futuros commits com base nos padrões do seu .gitignore.

Garanta que os padrões estão funcionando 

Às vezes, você pode notar que arquivos específicos que você esperava que fossem ignorados ainda aparecem no status do Git ou estão sendo rastreados. 

Siga essas etapas para garantir que os padrões do seu .gitignore estão funcionando corretamente:

  • Verifique o status dos seus arquivos: Use o comando git status para ver quais arquivos estão sendo rastreados pelo Git. Isso ajudará você a verificar se seus arquivos ignorados ainda estão listados.
git status
  • Verifique se o padrão está correto: Verifique a sintaxe dos padrões do seu arquivo .gitignore para garantir que estejam formatados corretamente. Por exemplo:
    • Assegure-se de usar o caminho do diretório correto (relativo à raiz do repositório).
    • Adicione um / para direcionar diretórios específicos e evitar o rastreamento de todos os arquivos com nomes semelhantes.
  • Atualize o cache: Se você atualizou recentemente seu arquivo .gitignore e as alterações não estão sendo aplicadas, o Git pode estar retendo o cache anterior. Para atualizar o cache, execute o seguinte comando:
git rm -r --cached .
git add .
git commit -m "Refresh .gitignore"
  • Verificar exceções: Às vezes, um padrão específico no arquivo .gitignore pode ser substituído por um padrão mais específico em outro lugar no arquivo. Revise suas regras para garantir que não haja padrões conflitantes.

Procurando por um rápido guia de referência do Git? Mantenha comandos essenciais ao alcance de suas mãos com este quadro de ajuda do Git.

Conclusão

Um arquivo .gitignore pode parecer pequeno, mas desempenha um papel enorme em manter seu repositório Git limpo e gerenciável. Ao ignorar arquivos desnecessários—como dependências, artefatos de construção e arquivos gerados pelo sistema—você garante que seu projeto permaneça organizado e livre de bagunça.

Neste tutorial, você aprendeu como criar um arquivo .gitignore, adicionar padrões e aplicar as melhores práticas para manter seu repositório eficiente. Com essas habilidades, você evitará dores de cabeça no controle de versão e tornará a colaboração mais suave para todos em sua equipe.

Se você deseja aprofundar suas habilidades no Git, confira o Git Fundamentals para um caminho de aprendizado estruturado. Você também pode explorar cursos práticos como Foundations of Git e Introduction to GitHub Concepts para construir uma compreensão sólida de controle de versão e fluxos de colaboração!

Source:
https://www.datacamp.com/tutorial/gitignore