aicommit 🤖

使用 AI 自動生成符合 Conventional Commits 規範的 Git commit 訊息。

採用 gemini-3.1-flash-lite 模型，這是速度最快的 Flash 模型，經過最佳化調整，成本效益最高，輸送量也最大。

✨ 功能特色

• 🤖 AI 智能生成 - 使用 Google Gemini AI 分析程式碼變更，自動生成專業的 commit 訊息
• ✏️ 直觀編輯 - 清晰顯示 AI 建議，支援複製貼上修改，保留個人風格
• ⌨️ 鍵盤快捷鍵 - 支援 Ctrl+A/E/U/K 等終端編輯快捷鍵
• ✅ 格式驗證 - 自動檢查 commit 訊息是否符合 Conventional Commits 規範
• 🎯 繁體中文支援 - 生成的訊息使用繁體中文描述
• 🚀 全域命令 - 安裝後可在任何 Git 專案中直接使用
• 📦 零配置 - 只需設定 API 金鑰即可開始使用
• 🧠 智慧截斷 - 大型 diff 自動優先保留實際變更行（+/-），確保 AI 獲得完整的修改內容，避免分析不完整

📋 系統需求

• Python 3.10 或更高版本
• Git
• Google Gemini API 金鑰（免費取得）

🚀 安裝

使用 pip 安裝（推薦）

pip install aicommit-joy

使用 uv 安裝

uv tool install aicommit-joy

使用 pipx 安裝

pipx install aicommit-joy

💡 提示：

• 使用 pip 是最通用的安裝方式
• 使用 uv 速度最快（需先安裝 uv）
• 使用 pipx 會在獨立環境中安裝，避免套件衝突

⚙️ 設定

1. 取得 Gemini API 金鑰

前往 Google AI Studio 免費取得 API 金鑰。

2. 設定環境變數

在您的專案目錄建立 .env 檔案：

echo "GEMINI_API_KEY=your_gemini_api_key_here" > .env

注意： 請將 your_gemini_api_key_here 替換為您的實際 API 金鑰。

📖 使用方法

基本使用

# 1. 暫存您的變更
git add .

# 2. 執行 aicommit
aicommit

完整使用範例

$ cd /path/to/your/project
$ git add .
$ aicommit

🤖 AI 正在分析程式碼變更，請稍候...

------------------------------------
📝 建議訊息: feat: 新增使用者登入功能
------------------------------------

請選擇操作 (y=使用/e=編輯/n=取消): e

======================================================================
✏️  編輯 Commit 訊息
======================================================================

📋 AI 建議訊息（可複製下方文字進行編輯）:

   feat: 新增使用者登入功能

──────────────────────────────────────────────────────────────────────
💡 提示:
   • 可以複製上面的建議訊息，修改後貼到下方輸入框
   • 或直接輸入全新的 commit 訊息
   • 快捷鍵: Ctrl+A=行首 | Ctrl+E=行尾 | Ctrl+U=清空
──────────────────────────────────────────────────────────────────────

請輸入 commit 訊息 > feat: 新增使用者登入與註冊功能

✅ 訊息格式正確！
📝 更新後的訊息: feat: 新增使用者登入與註冊功能

是否提交此訊息? (y/n): y
✅ 提交成功！可以使用 git push 上傳

互動選項

執行 aicommit 後，您可以選擇：

• y - 直接使用 AI 生成的訊息提交
• e - 編輯訊息後再提交
  • 會顯示清晰的編輯界面，包含 AI 建議訊息
  • 可以複製 AI 建議並修改，或完全重新輸入
  • 支援鍵盤快捷鍵輔助編輯
• n - 取消提交

編輯模式快捷鍵

在編輯 commit 訊息時，支援以下終端快捷鍵：

快捷鍵	功能
Ctrl+A	移動游標到行首
Ctrl+E	移動游標到行尾
Ctrl+U	清空目前輸入內容
Ctrl+K	刪除游標到行尾的內容
←/→	左右移動游標

📝 Conventional Commits 規範

aicommit 遵循 Conventional Commits 規範，支援以下 commit 類型：

Type	說明	範例
feat	新增功能	feat: 新增使用者登入功能
fix	修復 bug	fix: 修復登入頁面顯示錯誤
docs	文件修改	docs: 更新 API 文件
style	程式碼格式調整	style: 調整程式碼縮排
refactor	程式碼重構	refactor: 重構資料處理邏輯
perf	效能優化	perf: 優化資料庫查詢效能
test	測試相關	test: 新增登入功能測試
build	建置系統修改	build: 更新依賴套件版本
ci	CI 設定修改	ci: 新增 GitHub Actions 工作流程
chore	其他雜項修改	chore: 更新 .gitignore
revert	恢復先前提交	revert: 恢復登入功能變更

訊息格式

<type>: <subject>

✅ 正確範例：

• feat: 新增使用者登入功能
• fix: 修復登入頁面顯示錯誤
• docs: 更新 README 安裝說明

❌ 錯誤範例：

• feature: 新增功能 → type 錯誤，應為 feat
• feat 新增功能 → 缺少冒號
• feat: → subject 為空

🔧 常見指令

查看版本

aicommit --version

查看幫助

aicommit --help

更新到最新版本

# 使用 pip
pip install --upgrade aicommit-joy

# 使用 uv
uv tool upgrade aicommit-joy

# 使用 pipx
pipx upgrade aicommit-joy

卸載

# 使用 pip
pip uninstall aicommit-joy

# 使用 uv
uv tool uninstall aicommit-joy

# 使用 pipx
pipx uninstall aicommit-joy

� 問題排除

找不到 GEMINI_API_KEY

錯誤訊息：

❌ Error: 找不到 GEMINI_API_KEY
請在當前目錄建立 .env 檔案，內容：GEMINI_API_KEY=你的金鑰

解決方案：

1. 確認專案目錄中有 .env 檔案
2. 檢查 .env 內容格式：GEMINI_API_KEY=your_key_here
3. 確保 API 金鑰沒有多餘的引號或空格

沒有偵測到暫存的變更

錯誤訊息：

⚠️ 沒有偵測到暫存的變更(Staged Changes)，如有變更請先執行 git add

解決方案：

git add .                    # 暫存所有變更
git add file1.py file2.py   # 暫存特定檔案

AI 生成失敗

可能原因：

• 網路連線問題
• API 金鑰無效或過期
• API 配額已用完
• 變更內容過大

解決方案：

1. 檢查網路連線
2. 確認 API 金鑰有效
3. 前往 Google AI Studio 查看配額使用狀況

👨‍💻 開發者資訊

專案結構

aicommit-joy/
├── aicommit_cli/         # 主要套件
│   ├── __init__.py       # 套件初始化
│   ├── core.py           # 核心功能（Git、AI、驗證）
│   └── cli.py            # CLI 入口點
├── pyproject.toml        # 專案配置
├── LICENSE               # MIT 授權
└── README.md             # 專案說明

本地測試

# 建立測試專案
cd /tmp
mkdir test-repo && cd test-repo
git init

# 建立測試檔案
echo "# Test" > README.md
git add README.md

# 測試 aicommit
aicommit

📄 授權

本專案採用 MIT License 授權。

🙏 致謝

• Google Gemini - 提供強大的 AI 能力
• Conventional Commits - 提供 commit 訊息規範

🔗 相關連結

• PyPI 套件

---

享受使用 aicommit 的樂趣！ 🚀