檔案管理

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