.geminiignore
.geminiignore 的用途：排除敏感文件、大文件、构建产物、本地数据库和不希望 Gemini CLI 读取的项目内容。
.geminiignore 用来告诉 Gemini CLI 哪些文件不要读取或搜索。官方 file management tutorial 说明：Gemini CLI 默认尊重 .gitignore，但你可以用 .geminiignore 排除不适合暴露给 AI 的文件。
.geminiignore 是上下文过滤，不是安全沙箱。不要因为写了 ignore，就把密钥、客户数据或本地数据库留在 AI 可操作目录里。
工作机制
.geminiignore 的语法基本沿用 .gitignore：
- 空行和
#注释会被忽略。 - 支持
*、?、[]等 glob。 - 结尾
/只匹配目录。 - 开头
/表示相对.geminiignore所在目录锚定。 !可以取消排除。
被排除的路径会从支持该机制的 Gemini CLI 工具里过滤掉，例如 @ 文件引用、文件读取和搜索。但它不会替你改变 Git、磁盘权限或第三方服务访问能力。修改 .geminiignore 后需要重启当前 Gemini CLI 会话才会生效。
官方配置里还有两个容易被忽略的开关：context.fileFiltering.respectGitIgnore 和 context.fileFiltering.respectGeminiIgnore。如果你发现 @ 引用、read_many_files 或搜索结果和预期不一致，先检查这两个开关是否被用户级、项目级或系统级 settings 覆盖。
@<path> 文件引用是最常见的触发点。它会通过多文件读取工具把文件或目录加入上下文，并按 Git-aware 过滤规则处理。也就是说，.geminiignore 不是孤立生效，而是和 .gitignore、settings 里的 fileFiltering、工具参数一起决定最终能看到哪些文件。
推荐模板
.env
.env.*
*.pem
*.key
*.p12
*.sqlite
*.db
*.log
local-db-dump.sql
private-notes.md
coverage/
dist/
build/
node_modules/适合排除
.env、凭据、token、私钥。- 本地数据库 dump。
- 私人笔记。
- 大型构建产物。
- 生成文件。
- 版权敏感或不该进入上下文的素材。
不建议盲目排除所有 Markdown。很多项目规则、README、设计文档都在 Markdown 里；如果全排除，Gemini CLI 会缺少项目上下文。需要排除文档时，优先排除具体路径，例如 /private-notes/，而不是 *.md。
monorepo 里要特别小心根目录规则。根 .geminiignore 写得过宽，会同时影响多个 package；如果只有某个子项目有敏感 fixture 或私有导出文件，优先在子目录放更窄的规则，或者用锚定路径限制影响范围。
和 .gitignore 的区别
| 文件 | 目的 |
|---|---|
.gitignore | 不进入 Git |
.geminiignore | 不进入 Gemini CLI 上下文 |
有些文件可以进 Git，但不该让 AI 读；这时用 .geminiignore。
| 文件类型 | .gitignore | .geminiignore |
|---|---|---|
.env.local | 应该排除 | 应该排除 |
node_modules/ | 应该排除 | 应该排除 |
README.md | 不应排除 | 通常不应排除 |
| 已提交的测试 fixture | 不应排除 | 视是否含敏感数据 |
| 内部客户案例 | 可能已进 Git | 通常应排除 |
常见误区
- 以为
.geminiignore等于安全沙箱。它只是上下文过滤，不是访问控制。 - 修改后不重启会话，然后以为规则无效。
- 只写
.gitignore，忘了仓库里仍可能有已跟踪的敏感样例、客户数据或内部文档。 - 在 monorepo 根目录写得过宽，导致子项目的说明文档、schema、测试样例也被排除。
- 把
.geminiignore当作补救手段，而不是先从仓库里移除不该存在的敏感文件。
验收方式
重启 Gemini CLI 后，用 @ 引用一个被排除文件，确认它不会被加入上下文。再让 Gemini CLI 搜索一个只存在于被排除目录里的字符串，确认搜索结果不返回该文件。最后保留一条允许项测试 !README.md 这类反向规则是否符合预期。
如果项目开启了多入口规则文件，还要检查 context.fileName 指向的文件没有被 ignore 误伤。规则文件、README、schema、测试说明通常是 agent 正确工作的基础，不应该被宽泛规则排除。
接下来去哪
Custom commands
上下文边界清楚后，继续把重复操作做成项目命令。
文件管理
回看 @ 文件引用、目录上下文和 ignore 的日常用法。
Sandbox
需要真正限制文件系统和命令执行时，继续看 sandbox。