---
# System prepended metadata

title: '[AI] agent / Gemini CLI'
tags: [tools, AI, commit, agent, 追蹤, gemini, 摘要, AI Tools]

---

[AI] agent / Gemini CLI
===
###### tags: `AI Tools`
###### tags: `AI`, `tools`, `agent`, `gemini`, `追蹤`, `commit`, `摘要`

<br>

[TOC]

<br>

## Intro
> 官方說明 https://google-gemini.github.io/gemini-cli/

<br>



### 安裝方式
1. **安裝 Node.js**
    用 NodeSource（系統層級，全機可用）
    > [[HackMD] JavaScript Runtime](/ioPaKTHcTVOkDyJXraPYLA) (安裝 Node.js)

    ```
    # 1) 先準備基本工具
    sudo apt-get update
    sudo apt-get install -y ca-certificates curl gnupg

    # 2) 啟用 Node.js 22.x LTS 的套件庫（要 20.x 就把 22.x 改成 20.x）
    curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

    # 3) 安裝
    sudo apt-get install -y nodejs

    # 4) 驗證
    node -v
    npm -v
    npx -v
    ```
2. **擇一安裝**
    ```
    # 免安裝（跑一次就好）
    npx https://github.com/google-gemini/gemini-cli

    # 全域安裝（npm） 
    sudo npm install -g @google/gemini-cli
    ```
    - [首次安裝完，會跳出驗證畫面](#首次安裝完，會跳出驗證畫面)
3. **查看版本** (針對全域安裝？)（待驗證）
    ```
    $ which gemini
    /usr/bin/gemini

    $ gemini --version
    0.6.1   # 202
    ```

<br>

### 安裝方式 - Troubleshooting
- ### `Command 'npx' not found`
    ```
    $ npx https://github.com/google-gemini/gemini-cli
    Command 'npx' not found, but can be installed with:
    sudo apt install npm
    ```
    - ### 直接安裝 Node.js
        用 NodeSource（系統層級，全機可用）
        > [[HackMD] JavaScript Runtime](/ioPaKTHcTVOkDyJXraPYLA)
        ```
        # 1) 先準備基本工具
        sudo apt-get update
        sudo apt-get install -y ca-certificates curl gnupg

        # 2) 啟用 Node.js 22.x LTS 的套件庫（要 20.x 就把 22.x 改成 20.x）
        curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

        # 3) 安裝
        sudo apt-get install -y nodejs

        # 4) 驗證
        node -v
        npm -v
        npx -v
        ```
- ### `npm WARN EBADENGINE Unsupported engine`
    ```
    $ npx https://github.com/google-gemini/gemini-cli
    Need to install the following packages:
      github:google-gemini/gemini-cli
    Ok to proceed? (y) y
    npm WARN EBADENGINE Unsupported engine {
    npm WARN EBADENGINE   package: '@google/gemini-cli@0.7.0-nightly.20250918.2722473a',
    npm WARN EBADENGINE   required: { node: '>=20.0.0' },
    npm WARN EBADENGINE   current: { node: 'v18.19.1', npm: '9.2.0' }
    npm WARN EBADENGINE }
    ```
    - 錯誤原因
        - **Gemini CLI 需要 Node.js ≥ 20**，但你的環境是 **Node v18.19.1**

<br>

---

## 啟動方式
### 首次安裝完，會跳出驗證畫面
![](https://hackmd.io/_uploads/HydMg4znlg.png)
```
How would you like to authenticate for this project? 
 ● 1. Login with Google
   2. Use Gemini API Key
   3. Vertex AI
```
- 會彈出登入畫面，按照導引流程進行

<br>

### 後續啟動
```
$ cd /path/to/your-repo
$ gemini
```

<br>

---

## 指令

### 退出程式
```
> /quit 
```

### 更多指令
![](https://hackmd.io/_uploads/Sk3dF4G2gl.png)

<br>

---

## 使用範例1：追蹤近期 commit
> 需在 Git 專案根目錄執行 `gemini` 指令
> ```
> ~/workspace/k8s/slinky/slurm-operator$ gemini
> ```
- ### Prompt
    針對目前 repo，請彙整最近兩天的 commit：列出每筆的 commit ID、變更摘要、關鍵檔案與修改重點，並以白話解釋此 commit 的目的與可能影響；最後給一份整體趨勢與待辦建議。

- ### 執行過程
    ![](https://hackmd.io/_uploads/HJVi4VGhgg.png)
    
- ### 執行範例
    > https://github.com/SlinkyProject/slurm-operator

    ```
      Commit 2: 新增主機名稱解析服務

       * 變更摘要: feat: add hostname resolution service
       * 關鍵檔案:
           * internal/builder/worker_service.go: 新增了建立 Headless Service 的主要邏輯。
           * internal/controller/nodeset/nodeset_sync.go: 在 NodeSet 的同步流程中呼叫上述新邏輯。
           * internal/builder/login_app.go & worker_app.go: 修改了應用程式設定，以利用新的服務。
           * docs/index.rst: 新增了相關文件。
       * 修改重點:
           * 為 NodeSet 的 Pods 建立一個 Kubernetes Headless Service。
           * 這使得 NodeSet 中的每個 Pod (計算節點) 都有一個可以被叢集內部解析的穩定 DNS 名稱 (hostname)。
           * 同時更新了 LoginSet (登入節點)，讓它們也能利用這個服務來解析計算節點的主機名稱。
       * 目的與可能影響:
           * 目的: 解決特定工作負載 (workloads) 需要透過主機名稱來找到並與其他節點溝通的需求。在這之前，節點間的通訊可能只能依賴 IP 位址，而 IP 位址在 Pod 重啟後可能會改變。
           * 影響:
               * 正面: 大幅提升了 Slurm 叢集在 Kubernetes 上運行的相容性和靈活性，特別是對於那些依賴主機名稱解析的 MPI 或其他平行計算應用。
               * 潛在: 這個新功能引入了新的 Kubernetes Service 物件。需要確保 RBAC 權限設定正確，且不會與現有網路策略衝突。
    ```
    - snapshot
        ![](https://hackmd.io/_uploads/SJsXONG2ee.png)
        ![](https://hackmd.io/_uploads/rkOPOEznlx.png)

<br>

---

<br>

## 討論
### 用 gemini 問 local .git ，怎麼安裝和使用？
- ### gpt-5 (2025/09/25)
    沒問題！Gemini CLI 已經能在終端機裡直接「讀你的本機程式碼庫（含 Git 專案）」並回答問題、跑指令與幫你改檔。下面給你從安裝到在本機 `.git` 專案上實際使用的最短路徑。

    ---

    ### 安裝

    **系統需求**：Node.js ≥ 20（macOS / Linux / Windows）([google-gemini.github.io][1])

    三種快速方式擇一：

    ```bash
    # 免安裝（跑一次就好）
    npx https://github.com/google-gemini/gemini-cli

    # 全域安裝（npm）
    npm install -g @google/gemini-cli

    # macOS / Linux（Homebrew）
    brew install gemini-cli
    ```

    以上指令與需求見官方文件的 Installation 區塊。([google-gemini.github.io][1])

    ---

    ### 登入 / 授權

    進入 CLI 後首選用 Google 帳號 OAuth 登入（免費額度：60 req/min、1,000 req/日；模型為 Gemini 2.5 Pro，1M token 視窗）。也支援 **Gemini API Key** 或 **Vertex AI**：

    ```bash
    # 方式一：Google 登入（開啟後依畫面指示登入）
    gemini

    # 方式二：Gemini API Key
    export GEMINI_API_KEY="你的API金鑰"
    gemini

    # 方式三：Vertex AI（企業用）
    export GOOGLE_API_KEY="你的API金鑰"
    export GOOGLE_GENAI_USE_VERTEXAI=true
    gemini
    ```

    額度、模型與三種登入方式詳見官方「Authentication Options」。([google-gemini.github.io][1])

    ---

    ### 在本機 Git 專案上使用（最短路徑）

    1. **進到你的 repo**：

    ```bash
    cd /path/to/your-repo
    gemini
    ```

    Gemini CLI 會把「目前資料夾」視為工作根目錄；所有檔案工具都在這個範圍內運作。([google-gemini.github.io][2])

    2. **直接發問（互動模式）**
       在出現 `> GEMINI` 介面後，你可以直接打：

    * 「幫我**總結這個程式庫的架構**與模組關係」
    * 「找出**定義 `foo()`** 的檔案與使用處」
    * 「請**執行 `git log --since='yesterday' --oneline`**，並摘要昨天的變更」
      （CLI 會用 **shell tool** 執行並先詢問你確認，適用任何 `git` 指令。）([google-gemini.github.io][3])

    3. **一次性問答（非互動模式，方便寫腳本）**

    ```bash
    gemini -p "Explain the architecture of this codebase"
    # 需要機器可讀回傳：
    gemini -p "Explain the architecture of this codebase" --output-format json
    ```

    ([google-gemini.github.io][1])

    4. **跨資料夾讀取（單次或動態加入）**

    ```bash
    # 啟動時一口氣加進多個資料夾
    gemini --include-directories ../lib,../docs

    # 啟動後用指令加入/檢視工作目錄
    /directory add ../lib,../docs
    /directory show
    ```

    ([google-gemini.github.io][1])

    ---

    ### 與 Git / 專案檔案的互動細節

    * **預設遵守 `.gitignore`，且會忽略 `.git/` 與常見雜項資料夾**（例如 `node_modules`）。
      這能避免把不必要或巨大的檔案塞進模型上下文。檔案工具也會在 Git repo 內優先用 **`git grep`** 加速內容搜尋。([google-gemini.github.io][2])

    * 想讓它**讀到被 `.gitignore` 排除的檔案**或**包含 `.git/` 內部**（通常不需要）：
      你可以在專案的 `.gemini/settings.json` 調整：

      ```json
      {
        "context": {
          "fileFiltering": {
            "respectGitIgnore": false
          }
        }
      }
      ```

      另外，多檔案讀取工具 `read_many_files` 也能關掉預設排除（含 `.git/`）：
      `useDefaultExcludes=false`、`respect_git_ignore=false`。([google-gemini.github.io][4])

    * **常用檔案/搜尋工具**（模型會自動呼叫，並在敏感操作前向你確認）：

      * `list_directory`、`read_file`、`search_file_content`（內容搜尋在 repo 裡會用 `git grep`）([google-gemini.github.io][2])
      * `write_file`（改檔前會顯示 diff 要你同意）([google-gemini.github.io][2])
      * `run_shell_command`（跑 `git`、`npm`…；可在設定只允許 `git` 類指令）([google-gemini.github.io][3])

    ---

    ### 快速範例（在 Git 專案根目錄執行）

    * **總結架構**

      ```
      > 請閱讀 src/**/*.ts 與 docs/**/*.md，畫出模組互動與資料流摘要
      ```

      （模型會用多檔案讀取與搜尋工具聚合內容。）([google-gemini.github.io][5])

    * **找出變更摘要**

      ```
      > 請執行：git log --since="yesterday" --oneline --stat
      > 再幫我分門別類整理成 Changelog（Fix/Feat/Docs 等）
      ```

      （CLI 會以 shell tool 執行並回傳 stdout，再請模型整理。）([google-gemini.github.io][3])

    * **全庫快速問答（非互動）**

      ```bash
      gemini -p "列出此專案最重要的5支服務與入口檔，並指出其相依關係"
      ```

      ([google-gemini.github.io][1])

    ---

    ### 進階：專案專屬說明書 `GEMINI.md`

    在專案根目錄放一個 `GEMINI.md`，可告訴 Gemini「如何閱讀與回答這個專案」；也可用 `/memory` 指令查看、更新記憶。([google-gemini.github.io][1])
    （例如：專案目的、程式風格、測試策略、常見腳本、輸出格式要求等。）

    ---

    ### 安全提醒

    * CLI 具備**改檔**與**跑系統指令**能力；寫檔會先顯示 diff、跑指令會先徵求你同意，但仍建議在**可信的 repo**中使用，並避免對不明專案給出危險指令（如 `rm -rf`）。([google-gemini.github.io][2])
    * 今年曾通報過 CLI 的安全弱點並已修補，建議保持在最新版：

      ```bash
      npm i -g @google/gemini-cli@latest   # 或
      brew upgrade gemini-cli
      ```

      （新聞背景參考。） ([Medium][6])

    ---

    如果你要「只讓它用 Git 指令、不允許其它系統指令」，可在 `.gemini/settings.json` 加上：

    ```json
    {
      "tools": { "core": ["run_shell_command(git)"] }
    }
    ```

    （只允許以 `git` 開頭的 shell 指令。）([google-gemini.github.io][3])

    需要我直接幫你針對某個 repo 設好 `.gemini/settings.json` 與 `GEMINI.md` 的範本嗎？我可以依你的語言/專案風格客製一份。

    [1]: https://google-gemini.github.io/gemini-cli/ "Gemini CLI | gemini-cli"
    [2]: https://google-gemini.github.io/gemini-cli/docs/tools/file-system.html "Gemini CLI file system tools | gemini-cli"
    [3]: https://google-gemini.github.io/gemini-cli/docs/tools/shell.html "Shell Tool (run_shell_command) | gemini-cli"
    [4]: https://google-gemini.github.io/gemini-cli/docs/cli/configuration.html "Gemini CLI Configuration | gemini-cli"
    [5]: https://google-gemini.github.io/gemini-cli/docs/tools/multi-file.html "Multi File Read Tool (read_many_files) | gemini-cli"
    [6]: https://medium.com/google-cloud/practical-gemini-cli-bring-your-own-system-instruction-19ea7f07faa2?utm_source=chatgpt.com "Practical Gemini CLI: Bring your own system instruction"


<br>

{%hackmd vaaMgNRPS4KGJDSFG0ZE0w %}