QuiCommit/readme_zh.md

# QuiCommit

一款强大的AI驱动的Git助手，用于生成规范化的提交信息、标签和变更日志，并支持为不同工作场景管理多个Git配置。

![Rust](https://img.shields.io/badge/rust-%23000000.svg?style=for-the-badge&logo=rust&logoColor=white)
![LICENSE](https://img.shields.io/badge/license-MIT-blue.svg)

## ✨ 主要功能

- 🤖 **AI智能生成**：使用LLM API（OpenAI、Anthropic）或本地Ollama模型生成提交信息、标签注释和变更日志
- 📝 **规范化提交**：全面支持Conventional Commits和@commitlint格式规范
- 👤 **多配置管理**：为不同工作场景保存和切换多个Git配置（用户信息、SSH密钥、GPG签名）
- 🏷️ **智能标签管理**：基于语义版本的智能版本升级，自动生成发布说明
- 📜 **变更日志生成**：自动生成Keep a Changelog或GitHub Releases格式的变更日志
- 🔐 **安全保护**：加密存储敏感数据，如SSH密码和API密钥
- 🎨 **交互式界面**：美观的CLI界面，支持交互式提示和预览功能

## 📦 安装说明

### 从源码安装

```bash
git clone https://github.com/yourusername/quicommit.git
cd quicommit
cargo build --release
```

可执行文件将位于 `target/release/quicommit`。

### 环境要求

- Rust 1.70或更高版本
- Git 2.0或更高版本
- AI功能可选：Ollama（本地）或OpenAI/Anthropic的API密钥

## 🚀 快速开始

### 1. 初始化配置

```bash
quicommit init
```

这将引导您完成第一个配置和LLM配置的设置。

### 2. 生成提交信息

```bash
# AI生成提交信息（默认）
quicommit commit

# 手动提交
quicommit commit --manual -t feat -m "添加新功能"

# 基于日期的提交
quicommit commit --date

# 暂存所有文件并提交
quicommit commit -a
```

### 3. 创建标签

```bash
# 自动检测提交中的版本升级
quicommit tag

# 指定版本升级
quicommit tag --bump minor

# 自定义标签名
quicommit tag -n v1.0.0
```

### 4. 生成变更日志

```bash
# 为未发布变更生成
quicommit changelog

# 为特定版本生成
quicommit changelog -v 1.0.0

# 初始化新的变更日志
quicommit changelog --init
```

## ⚙️ 配置说明

### 多配置管理

为不同场景管理多个Git身份：

```bash
# 添加新配置
quicommit profile add

# 查看配置列表
quicommit profile list

# 切换配置
quicommit profile switch

# 应用配置到当前仓库
quicommit profile apply

# 为当前仓库设置配置
quicommit profile set-repo personal
```

### LLM提供商配置

#### Ollama（本地部署 - 推荐）

```bash
# 配置Ollama
quicommit config set-llm ollama

# 或使用特定设置
quicommit config set-ollama --url http://localhost:11434 --model llama2
```

#### OpenAI

```bash
quicommit config set-llm openai
quicommit config set-openai-key YOUR_API_KEY
```

#### Anthropic Claude

```bash
quicommit config set-llm anthropic
quicommit config set-anthropic-key YOUR_API_KEY
```

### 提交格式配置

```bash
# 使用规范化提交（默认）
quicommit config set-commit-format conventional

# 使用commitlint格式
quicommit config set-commit-format commitlint
```

## 📖 使用示例

### 交互式提交流程

```bash
$ quicommit commit
已暂存文件 (3)：
  • src/main.rs
  • src/lib.rs
  • Cargo.toml

🤖 AI正在分析您的变更...

────────────────────────────────────────────────────────────
生成的提交信息：
────────────────────────────────────────────────────────────
feat: 添加用户认证模块

实现OAuth2认证，支持GitHub和Google提供商。
────────────────────────────────────────────────────────────

您希望如何操作？
> ✓ 接受并提交
  🔄 重新生成
  ✏️  编辑
  ❌ 取消
```

### 配置管理

```bash
# 创建工作配置
$ quicommit profile add
配置名称：work
Git用户名：John Doe
Git邮箱：john@company.com
这是工作配置吗？yes
组织机构：Acme Corp

# 为当前仓库设置
$ quicommit profile set-repo work
✓ 已为当前仓库设置'work'配置
```

### 智能标签管理

```bash
$ quicommit tag
最新版本：v0.1.0

版本选择：
> 从提交中自动检测升级
  主版本升级
  次版本升级
  修订版本升级

🤖 AI正在从15个提交中生成标签信息...

标签预览：
名称：  v0.2.0
信息：
## 变更内容

### 🚀 新功能
- 添加用户认证
- 实现仪表板

### 🐛 问题修复
- 修复登录重定向问题

创建此标签？yes
✓ 已创建标签 v0.2.0
```

## 📁 配置文件

配置存储位置：

- **Linux**: `~/.config/quicommit/config.toml`
- **macOS**: `~/Library/Application Support/quicommit/config.toml`
- **Windows**: `%APPDATA%\quicommit\config.toml`

配置文件示例：

```toml
version = "1"
default_profile = "personal"

[profiles.personal]
name = "personal"
user_name = "John Doe"
user_email = "john@example.com"

[profiles.work]
name = "work"
user_name = "John Doe"
user_email = "john@company.com"
is_work = true
organization = "Acme Corp"

[llm]
provider = "ollama"
max_tokens = 500
temperature = 0.7

[llm.ollama]
url = "http://localhost:11434"
model = "llama2"

[commit]
format = "conventional"
auto_generate = true
max_subject_length = 100

[tag]
version_prefix = "v"
auto_generate = true
include_changelog = true

[changelog]
path = "CHANGELOG.md"
auto_generate = true
group_by_type = true
```

## 🔧 环境变量

| 变量名 | 说明 |
|--------|------|
| `QUICOMMIT_CONFIG` | 配置文件路径 |
| `EDITOR` | 交互式输入的默认编辑器 |
| `NO_COLOR` | 禁用彩色输出 |

## 💻 Shell补全

### Bash
```bash
quicommit completions bash > /etc/bash_completion.d/quicommit
```

### Zsh
```bash
quicommit completions zsh > /usr/local/share/zsh/site-functions/_quicommit
```

### Fish
```bash
quicommit completions fish > ~/.config/fish/completions/quicommit.fish
```

## 🔍 故障排除

### LLM连接问题

```bash
# 测试LLM连接
quicommit config test-llm

# 列出可用模型
quicommit config list-models
```

### Git操作

```bash
# 查看当前配置
quicommit profile show

# 应用配置修复git配置
quicommit profile apply
```

## 🤝 贡献指南

欢迎提交贡献！请随时提交Pull Request。

1. Fork本仓库
2. 创建您的功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交您的变更 (`git commit -m 'feat: 添加令人惊叹的功能'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 提交Pull Request

## 📄 许可证

本项目采用MIT或Apache-2.0许可证。

## 🙏 致谢

- [Conventional Commits](https://www.conventionalcommits.org/) 规范
- [Keep a Changelog](https://keepachangelog.com/) 格式
- [Ollama](https://ollama.ai/) 本地LLM支持