文件管理

Gemini CLI 可以自己探索项目，也可以通过 @ 显式读取你指定的文件或目录。文件管理是它从“聊天”变成“agent”的关键能力，也是最容易越界的地方：读错文件会误判，改错文件会制造无关 diff。

1. 显式读取文件

单文件示例：@src/components/UserProfile.tsx 解释这个组件如何处理用户数据。

多个文件可以一起给：

@src/components/UserProfile.tsx @src/types/User.ts 检查这两个文件的类型关系。

目录也可以给：

@src/utils/ 检查这些工具函数是否还有 deprecated API。

显式引用适合你已经知道路径的情况。它的优势是范围明确；缺点是你可能漏掉相关文件。因此复杂问题可以先让 Gemini CLI 读结构，再由你确认要引用哪些文件。

2. 让它自己找文件

不知道路径时，不要乱猜：

可以直接问：Find the file that defines the UserProfile component.

Gemini CLI 会用目录列表、glob 等工具探索项目结构，再返回可能路径。

3. 修改和创建文件

修改文件：

Update @src/components/UserProfile.tsx to show a loading spinner if user data is null.

创建文件：

Create a new file @src/components/LoadingSpinner.tsx with a simple Tailwind CSS spinner.

修改前它会展示 unified diff。你要看清楚再确认。

4. .geminiignore

Gemini CLI 默认尊重 .gitignore。如果有些文件不想暴露给 AI，但不适合放进 .gitignore，可以用 .geminiignore：

常见排除项包括 .env、local-db-dump.sql、private-notes.md。

.geminiignore 适合排除本地敏感材料、临时数据、数据库 dump、客户资料和私有笔记。它不应该代替凭据管理；真正的密钥仍然不能放在项目目录里等工具来“忽略”。

5. 工具分工

显式 @file 适合你已经知道路径的情况。路径不确定时，让 Gemini CLI 先列目录、搜索名称或搜索内容；读单个文件和批量读上下文是两种不同动作；修改优先做精确替换，只有新建文件或整体重写时才适合完整写入。

flowchart TD
    Task["文件任务"] --> Known{"知道路径?"}
    Known -->|是| At["@file 精确引用"]
    Known -->|否| Search["先搜索文件和目录"]
    At --> Read["只读解释"]
    Search --> Read
    Read --> Plan["修改计划"]
    Plan --> Edit["限定文件编辑"]
    Edit --> Diff["看 unified diff"]
    Diff --> Test["跑最小验证"]

    style Read fill:#dcfce7,stroke:#22c55e
    style Edit fill:#fef3c7,stroke:#f59e0b
    style Diff fill:#dbeafe,stroke:#3b82f6

6. 安全顺序

1. 只读解释目录。
2. 指定单文件解释。
3. 让它提出修改计划。
4. 只授权一个小文件修改。
5. 看 diff。
6. 跑测试。

7. 验收方式

编辑文件前，要求 Gemini CLI 先说清它准备读哪些文件和为什么读。编辑后检查 unified diff、运行项目测试或最小验证命令。涉及 .geminiignore 的项目，再验证被排除文件不会通过 @ 或搜索进入上下文。

8. 接下来去哪

官方来源

• Gemini CLI file management tutorial
• Gemini CLI file system tools