Quando você usa a Gemini CLI no terminal, o modelo pode acionar ferramentas que leem arquivos ou incluem trechos no contexto, por exemplo, ao usar O Gemini Ignore é o jeito previsto na documentação de dizer: isso aqui fica de fora dessas operações.

Você cria um arquivo .geminiignore na raiz do projeto. A ideia é parecida com .gitignore (Git) e .aiexclude (Gemini Code Assist). Mas o escopo é o fluxo da CLI: o que está ignorado não entra nas ferramentas que respeitam esse arquivo. Não substitui boas práticas de Git, revisão de PR ou políticas da empresa; é mais uma camada de controle de contexto na hora de trabalhar com a IA.

Depois de editar o arquivo, a documentação deixa claro: reinicie a sessão da Gemini CLI para aplicar as mudanças.

Por que isso importa na vida real

Variáveis de ambiente e segredos

Arquivos como .env, .env.local, .env.production ou pastas de credenciais costumam ter API keys, URLs internas e flags de feature. Mesmo que você nunca commite isso, eles podem existir no disco do projeto. Colocá-los no .geminiignore reduz o risco de o assistente ler ou anexar esse conteúdo ao responder um prompt ou ao usar @.

Chaves e tokens em outros formatos

Além de .env, vale ignorar padrões que costumam guardar segredos:

• arquivos de serviço cloud (*-key.json, service-account*.json);
• chaves privadas (.pem, id_rsa, pastas como .ssh/ dentro do repositório, se existirem);
• arquivos gerados por ferramentas (*.p12, credenciais exportadas).

Dados pessoais e sensíveis

Exports de CRM, CSV de usuários, backups de banco de teste, dumps com e-mail, telefone, documento ou qualquer dado que entre em LGPD/GDPR não deveriam virar contexto casual da sessão. Ignorar pastas como exports/, backups/ ou fixtures/pii/ ajuda a não expor isso ao fluxo da CLI por engano.

Como funciona (sintaxe que você já conhece)

Na prática, as regras seguem .gitignore:

• # Para comentário; linhas em branco são ignoradas.
• Glob: *, ?, [].
• / No fim casa com diretório; / no início ancora em relação ao .geminiignore.
• ! Nega um padrão (exceção).

---

Exemplo de .geminiignore focado em segredos e dados pessoais

# Ambiente e segredos
.env
.env.*
!.env.example

# Chaves e credenciais comuns
*.pem
id_rsa*
*-key.json
service-account*.json

# Dados sensíveis / exports locais
exports/
backups/
**/fixtures/pii/

# Dependências e artefatos enormes (menos ruído no contexto)
node_modules/
dist/Code language: PHP (php)

O !.env.example é útil quando você quer um arquivo de exemplo versionado para documentar variáveis sem valores reais — a exceção deixa só esse arquivo passar, se fizer sentido no seu fluxo.

---

Onde isso aparece no dia a dia

• Ao usar @ para compartilhar arquivos, caminhos listados no .geminiignore tendem a ser excluídos automaticamente (conforme a documentação do recurso).
• Ferramentas que respeitam o arquivo deixam de considerar esses caminhos nas operações compatíveis.

Abaixo, seguem as outras alavancas que convivem com o .geminiignore: não substituem o arquivo na raiz, mas ajudam em monorepos, em times com padrões próprios ou quando você quer ajustar o comportamento global da busca.

Além do .geminiignore: outras opções de configuração

.gitignore (complementar, não redundante)

Por padrão, a Gemini CLI respeita o .gitignore: node_modules, artefatos de build e o que você já excluí do Git tendem a ficar fora da busca. O papel do .geminiignore é outro: esconder da IA coisas que ainda existem no disco e, talvez, até no repositório; o caso clássico da documentação é o .env: você pode querer não ignorar no Git (ou ignorar de outro jeito), mas sim manter longe do contexto da sessão. Por isso, as duas camadas se combinam.

context.fileFiltering (settings)

Na configuração da CLI aparecem opções sob context.fileFiltering. As principais ligadas a exclusão e busca de arquivos:

Opção	O que faz (resumo)
respectGitIgnore	Respeitar .gitignore ao pesquisar (padrão costuma ser ligado).
respectGeminiIgnore	Respeitar .geminiignore ao pesquisar (padrão costuma ser ligado).
customIgnoreFilePaths	Lista de arquivos de ignore adicionais; têm precedência sobre .geminiignore e .gitignore, e a ordem na lista importa (o primeiro manda sobre o segundo). Útil para monorepos ou um único arquivo de padrões compartilhado pelo time.
enableRecursiveFileSearch	Ativa busca recursiva ao preencher referências @.
enableFuzzySearch	Ativa busca “fuzzy” ao resolver arquivos no prompt.

Desligar respectGeminiIgnore ou respectGitIgnore existe como opção técnica, mas para segredos e dados pessoais o caminho seguro é manter as exclusões nos arquivos de ignore — não depender de desativar o filtro.

Ferramentas de sistema de arquivos

Algumas ferramentas permitem afinar o comportamento por chamada, além do que está no .geminiignore na raiz:

• list_directory: parâmetros como array ignore (globs) e file_filtering_options (alinhado a .gitignore / .geminiignore).
• glob: por exemplo respect_git_ignore e, conforme a referência de ferramentas, respect_gemini_ignore ao encontrar arquivos.

Ou seja: filtros globais via settings e arquivos na raiz, com possibilidade de exclusões adicionais quando o modelo usa essas ferramentas.

Comandos customizados

Em fluxos de comandos customizados, a documentação indica que dá para respeitar .gitignore e .geminiignore quando isso estiver habilitado na configuração usada por aquele comando — vale conferir se o seu comando herdou o mesmo comportamento que a sessão interativa.

conclusão

Pense no .geminiignore como lista principal de exclusão de contexto para a IA: menos chance de puxar .env cheio de API keys, menos risco de anexar dados pessoais por engano, e sessões mais focadas no código útil. Em cima disso, context.fileFiltering, .gitignore, arquivos extras em customIgnoreFilePaths e parâmetros das ferramentas de arquivo ajustam o detalhe. No Git e na equipe, continue com .gitignore, revisão de PR e políticas internas — cada camada cobre um tipo de risco.