aicommit-joy 0.1.5
AI-powered Git commit message generator using Conventional Commits
License: MIT
Requires Python: >=3.10
Keywords: ai, aicommit, aicommit-cli, aicommitcli, autocommit, automate, automation, cli, commit, commits, conventional-commits, gemini, git, smartcommit

# aicommit 🤖

[![PyPI version](https://badge.fury.io/py/aicommit-joy.svg)](https://pypi.org/project/aicommit-joy/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

使用 AI 自動生成符合 [Conventional Commits](https://www.conventionalcommits.org/) 規範的 Git commit 訊息。

採用 **Gemini 2.5 Flash-Lite** 模型，這是速度最快的 Flash 模型，經過最佳化調整，成本效益最高，輸送量也最大。

## ✨ 功能特色

- 🤖 **AI 智能生成** - 使用 Google Gemini AI 分析程式碼變更，自動生成專業的 commit 訊息
- ✏️ **手動編輯** - 可以編輯 AI 生成的訊息，保留個人風格
- ✅ **格式驗證** - 自動檢查 commit 訊息是否符合 Conventional Commits 規範
- 🎯 **繁體中文支援** - 生成的訊息使用繁體中文描述
- 🚀 **全域命令** - 安裝後可在任何 Git 專案中直接使用
- 📦 **零配置** - 只需設定 API 金鑰即可開始使用

## 📋 系統需求

- Python 3.10 或更高版本
- Git
- Google Gemini API 金鑰（[免費取得](https://aistudio.google.com/apikey)）

## 🚀 安裝

### 使用 pip 安裝（推薦）

```bash
pip install aicommit-joy
```

### 使用 uv 安裝

```bash
uv tool install aicommit-joy
```

### 使用 pipx 安裝

```bash
pipx install aicommit-joy
```

> 💡 **提示：**
>
> - 使用 `pip` 是最通用的安裝方式
> - 使用 `uv` 速度最快（需先[安裝 uv](https://docs.astral.sh/uv/)）
> - 使用 `pipx` 會在獨立環境中安裝，避免套件衝突

## ⚙️ 設定

### 1. 取得 Gemini API 金鑰

前往 [Google AI Studio](https://aistudio.google.com/apikey) 免費取得 API 金鑰。

### 2. 設定環境變數

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

```bash
echo "GEMINI_API_KEY=your_gemini_api_key_here" > .env
```

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

## 📖 使用方法

### 基本使用

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

# 2. 執行 aicommit
aicommit
```

### 完整使用範例

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

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

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

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

請輸入新的 commit 訊息（按 Enter 確認）:
feat: 新增使用者登入功能
> feat: 新增使用者登入與註冊功能

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

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

### 互動選項

執行 `aicommit` 後，您可以選擇：

- **`y`** - 直接使用 AI 生成的訊息提交
- **`e`** - 編輯訊息後再提交
- **`n`** - 取消提交

## 📝 Conventional Commits 規範

aicommit 遵循 [Conventional Commits](https://www.conventionalcommits.org/) 規範，支援以下 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 為空

## 🔧 常見指令

### 查看版本

```bash
aicommit --version
```

### 查看幫助

```bash
aicommit --help
```

### 更新到最新版本

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

# 使用 uv
uv tool upgrade aicommit-joy

# 使用 pipx
pipx upgrade aicommit-joy
```

### 卸載

```bash
# 使用 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
```

**解決方案：**

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

### AI 生成失敗

**可能原因：**

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

**解決方案：**

1. 檢查網路連線
2. 確認 API 金鑰有效
3. 前往 [Google AI Studio](https://aistudio.google.com/) 查看配額使用狀況

## 👨‍💻 開發者資訊

### 專案結構

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

### 本地測試

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

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

# 測試 aicommit
aicommit
```

## 📄 授權

本專案採用 [MIT License](LICENSE) 授權。

## 🙏 致謝

- [Google Gemini](https://ai.google.dev/) - 提供強大的 AI 能力
- [Conventional Commits](https://www.conventionalcommits.org/) - 提供 commit 訊息規範

## 🔗 相關連結

- [PyPI 套件](https://pypi.org/project/aicommit-joy/)

---

**享受使用 aicommit 的樂趣！** 🚀