495 lines
11 KiB
Markdown
495 lines
11 KiB
Markdown
# QuiCommit
|
||
|
||
[English](README.md) | 简体中文
|
||
|
||
一款强大的AI驱动的Git助手，用于生成规范化的提交信息、标签和变更日志，并支持管理多个Git配置。
|
||
|
||
【目前还处在早期开发阶段，依然有一些功能未完善，欢迎反馈和贡献。】
|
||
|
||
|
||
|
||
|
||
## 主要功能
|
||
|
||
- **AI智能生成**：使用LLM API（Ollama本地、OpenAI、Anthropic Claude、Kimi、DeepSeek、OpenRouter）生成提交信息、标签和变更日志
|
||
- **规范化提交**：支持Conventional Commits和commitlint格式规范
|
||
- **多配置管理**：为不同场景管理多个Git身份，支持SSH密钥和GPG签名配置
|
||
- **智能标签管理**：基于语义版本自动检测升级，AI生成标签信息
|
||
- **变更日志生成**：自动生成Keep a Changelog格式的变更日志
|
||
- **安全保护**：加密存储敏感数据
|
||
- **交互式界面**：美观的CLI界面，支持预览和确认
|
||
|
||
## 安装
|
||
|
||
### cargo安装
|
||
|
||
cargo安装版本可能暂时不如源码进展快速。
|
||
|
||
```bash
|
||
cargo install quicommit
|
||
```
|
||
|
||
### 从源代码安装
|
||
|
||
```bash
|
||
git clone https://git.lyz.one/SidneyZhang/QuiCommit.git
|
||
cd QuiCommit
|
||
cargo build --release
|
||
cargo install --path .
|
||
```
|
||
|
||
要求：Rust 1.70+、Git 2.0+
|
||
|
||
## 快速开始
|
||
|
||
### 初始化配置
|
||
|
||
```bash
|
||
quicommit init
|
||
```
|
||
|
||
### 生成提交信息
|
||
|
||
```bash
|
||
# AI生成提交信息（默认）
|
||
quicommit commit
|
||
|
||
# 手动提交
|
||
quicommit commit --manual -t feat -m "添加新功能"
|
||
|
||
# 暂存所有文件并提交
|
||
quicommit commit -a
|
||
|
||
# 跳过确认直接提交
|
||
quicommit commit --yes
|
||
|
||
# 使用日期格式的提交信息
|
||
quicommit commit --date
|
||
|
||
# 提交后推送到远程
|
||
quicommit commit --push
|
||
```
|
||
|
||
### 创建标签
|
||
|
||
```bash
|
||
# 自动检测版本升级
|
||
quicommit tag
|
||
|
||
# 指定版本升级类型
|
||
quicommit tag --bump minor
|
||
|
||
# 自定义标签名
|
||
quicommit tag -n v1.0.0
|
||
|
||
# AI生成标签信息
|
||
quicommit tag --generate
|
||
|
||
# 创建标签并推送到远程
|
||
quicommit tag --push
|
||
```
|
||
|
||
### 生成变更日志
|
||
|
||
```bash
|
||
# 生成未发布变更的变更日志
|
||
quicommit changelog
|
||
|
||
# 为特定版本生成
|
||
quicommit changelog -v 1.0.0
|
||
|
||
# AI生成变更日志
|
||
quicommit changelog --generate
|
||
|
||
# 初始化新的变更日志文件
|
||
quicommit changelog --init
|
||
|
||
# 指定输出文件
|
||
quicommit changelog -o RELEASE_NOTES.md
|
||
```
|
||
|
||
### 配置管理
|
||
|
||
```bash
|
||
# 添加新配置
|
||
quicommit profile add
|
||
|
||
# 查看配置列表
|
||
quicommit profile list
|
||
|
||
# 显示配置详情
|
||
quicommit profile show
|
||
|
||
# 切换配置
|
||
quicommit profile switch
|
||
|
||
# 设置默认配置
|
||
quicommit profile set-default personal
|
||
|
||
# 设置当前仓库的配置
|
||
quicommit profile set-repo personal
|
||
|
||
# 应用配置到当前仓库
|
||
quicommit profile apply
|
||
|
||
# 全局应用配置
|
||
quicommit profile apply --global
|
||
|
||
# 复制配置
|
||
quicommit profile copy personal work
|
||
|
||
# 编辑配置
|
||
quicommit profile edit personal
|
||
|
||
# 删除配置
|
||
quicommit profile remove old-profile
|
||
|
||
# 检查配置
|
||
quicommit profile check
|
||
|
||
# 查看使用统计
|
||
quicommit profile stats
|
||
|
||
# 管理配置的令牌
|
||
quicommit profile token
|
||
```
|
||
|
||
### LLM配置
|
||
|
||
```bash
|
||
# 配置Ollama（本地）
|
||
quicommit config set-llm ollama
|
||
quicommit config set-ollama --url http://localhost:11434 --model llama2
|
||
|
||
# 配置OpenAI
|
||
quicommit config set-llm openai
|
||
quicommit config set-openai-key YOUR_API_KEY
|
||
|
||
# 配置Anthropic Claude
|
||
quicommit config set-llm anthropic
|
||
quicommit config set-anthropic-key YOUR_API_KEY
|
||
|
||
# 配置Kimi
|
||
quicommit config set-llm kimi
|
||
quicommit config set-kimi-key YOUR_API_KEY
|
||
quicommit config set-kimi --base-url https://api.moonshot.cn/v1 --model moonshot-v1-8k
|
||
|
||
# 配置DeepSeek
|
||
quicommit config set-llm deepseek
|
||
quicommit config set-deepseek-key YOUR_API_KEY
|
||
quicommit config set-deepseek --base-url https://api.deepseek.com/v1 --model deepseek-chat
|
||
|
||
# 配置OpenRouter
|
||
quicommit config set-llm openrouter
|
||
quicommit config set-openrouter-key YOUR_API_KEY
|
||
quicommit config set-openrouter --base-url https://openrouter.ai/api/v1 --model openai/gpt-4
|
||
|
||
# 设置提交格式
|
||
quicommit config set-commit-format conventional
|
||
|
||
# 设置版本前缀
|
||
quicommit config set-version-prefix v
|
||
|
||
# 设置变更日志路径
|
||
quicommit config set-changelog-path CHANGELOG.md
|
||
|
||
# 设置输出语言
|
||
quicommit config set-language zh
|
||
|
||
# 设置保持提交类型为英文
|
||
quicommit config set-keep-types-english true
|
||
|
||
# 设置保持变更日志类型为英文
|
||
quicommit config set-keep-changelog-types-english true
|
||
|
||
# 测试LLM连接
|
||
quicommit config test-llm
|
||
|
||
# 重置配置为默认值
|
||
quicommit config reset
|
||
```
|
||
|
||
## 命令参考
|
||
|
||
| 命令 | 别名 | 说明 |
|
||
|------|------|------|
|
||
| `quicommit init` | `i` | 初始化配置 |
|
||
| `quicommit commit` | `c` | 生成并执行提交 |
|
||
| `quicommit tag` | `t` | 生成并创建标签 |
|
||
| `quicommit changelog` | `cl` | 生成变更日志 |
|
||
| `quicommit profile` | `p` | 管理Git配置 |
|
||
| `quicommit config` | `cfg` | 管理应用配置 |
|
||
|
||
### commit命令选项
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `--commit-type` | 提交类型（feat、fix等） |
|
||
| `-s, --scope` | 提交范围 |
|
||
| `-m, --message` | 提交描述 |
|
||
| `--body` | 提交正文 |
|
||
| `-b, --breaking` | 标记为破坏性变更 |
|
||
| `-d, --date` | 使用日期格式的提交信息 |
|
||
| `--manual` | 手动输入，跳过AI生成 |
|
||
| `-a, --all` | 暂存所有更改 |
|
||
| `-S, --sign` | GPG签名提交 |
|
||
| `--amend` | 修改上一次提交 |
|
||
| `--dry-run` | 试运行，不实际提交 |
|
||
| `--conventional` | 使用Conventional Commits格式 |
|
||
| `--commitlint` | 使用commitlint格式 |
|
||
| `--no-verify` | 不验证提交信息 |
|
||
| `-y, --yes` | 跳过确认提示 |
|
||
| `--push` | 提交后推送到远程 |
|
||
| `--remote` | 指定远程仓库（默认：origin） |
|
||
|
||
### tag命令选项
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `-n, --name` | 标签名称 |
|
||
| `-b, --bump` | 版本升级类型（major/minor/patch） |
|
||
| `-m, --message` | 标签信息 |
|
||
| `-g, --generate` | AI生成标签信息 |
|
||
| `-S, --sign` | GPG签名标签 |
|
||
| `-l, --lightweight` | 创建轻量标签 |
|
||
| `-f, --force` | 强制覆盖已存在的标签 |
|
||
| `-p, --push` | 推送到远程 |
|
||
| `-r, --remote` | 指定远程仓库（默认：origin） |
|
||
| `--dry-run` | 试运行 |
|
||
| `-y, --yes` | 跳过确认提示 |
|
||
|
||
### changelog命令选项
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `-o, --output` | 输出文件路径 |
|
||
| `-v, --version` | 为特定版本生成 |
|
||
| `-f, --from` | 从指定标签生成 |
|
||
| `-t, --to` | 生成到指定引用（默认：HEAD） |
|
||
| `-i, --init` | 初始化新的变更日志文件 |
|
||
| `-g, --generate` | AI生成变更日志 |
|
||
| `--prepend` | 添加到现有变更日志开头 |
|
||
| `--include-hashes` | 包含提交哈希 |
|
||
| `--include-authors` | 包含作者信息 |
|
||
| `--format` | 格式（keep-a-changelog、github-releases） |
|
||
| `--dry-run` | 试运行（输出到stdout） |
|
||
| `-y, --yes` | 跳过确认提示 |
|
||
|
||
## 配置文件
|
||
|
||
配置文件位置：
|
||
- 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 = "Your Name"
|
||
user_email = "your.email@example.com"
|
||
description = "个人项目"
|
||
is_work = false
|
||
|
||
[profiles.work]
|
||
name = "work"
|
||
user_name = "Your Name"
|
||
user_email = "your.name@company.com"
|
||
description = "工作项目"
|
||
is_work = true
|
||
organization = "Your Company"
|
||
|
||
[profiles.work.ssh]
|
||
private_key_path = "/home/user/.ssh/id_rsa_work"
|
||
agent_forwarding = true
|
||
|
||
[profiles.work.gpg]
|
||
key_id = "YOUR_GPG_KEY_ID"
|
||
program = "gpg"
|
||
use_agent = true
|
||
|
||
[llm]
|
||
provider = "ollama"
|
||
max_tokens = 500
|
||
temperature = 0.7
|
||
timeout = 30
|
||
|
||
[llm.ollama]
|
||
url = "http://localhost:11434"
|
||
model = "llama2"
|
||
|
||
[llm.openai]
|
||
model = "gpt-4"
|
||
base_url = "https://api.openai.com/v1"
|
||
|
||
[llm.anthropic]
|
||
model = "claude-3-sonnet-20240229"
|
||
|
||
[llm.kimi]
|
||
model = "moonshot-v1-8k"
|
||
|
||
[llm.deepseek]
|
||
model = "deepseek-chat"
|
||
|
||
[llm.openrouter]
|
||
model = "openai/gpt-4"
|
||
|
||
[commit]
|
||
format = "conventional"
|
||
auto_generate = true
|
||
allow_empty = false
|
||
gpg_sign = false
|
||
max_subject_length = 100
|
||
require_scope = false
|
||
require_body = false
|
||
body_required_types = ["feat", "fix"]
|
||
|
||
[tag]
|
||
version_prefix = "v"
|
||
auto_generate = true
|
||
gpg_sign = false
|
||
include_changelog = true
|
||
|
||
[changelog]
|
||
path = "CHANGELOG.md"
|
||
auto_generate = true
|
||
format = "keep-a-changelog"
|
||
include_hashes = false
|
||
include_authors = false
|
||
group_by_type = true
|
||
|
||
[theme]
|
||
colors = true
|
||
icons = true
|
||
date_format = "%Y-%m-%d"
|
||
|
||
[repo_profiles]
|
||
"/path/to/work/project" = "work"
|
||
"/path/to/personal/project" = "personal"
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
| 变量名 | 说明 |
|
||
|--------|------|
|
||
| `QUICOMMIT_CONFIG` | 配置文件路径 |
|
||
| `EDITOR` | 默认编辑器 |
|
||
| `NO_COLOR` | 禁用彩色输出 |
|
||
|
||
## 故障排除
|
||
|
||
```bash
|
||
# 查看当前配置
|
||
quicommit config list
|
||
|
||
# 显示配置详情
|
||
quicommit config show
|
||
|
||
# 编辑配置文件
|
||
quicommit config edit
|
||
|
||
# 设置配置值
|
||
quicommit config set llm.provider ollama
|
||
|
||
# 获取配置值
|
||
quicommit config get llm.provider
|
||
|
||
# 测试LLM连接
|
||
quicommit config test-llm
|
||
|
||
# 列出可用模型
|
||
quicommit config list-models
|
||
|
||
# 导出配置
|
||
quicommit config export -o config-backup.toml
|
||
|
||
# 导入配置
|
||
quicommit config import -i config-backup.toml
|
||
|
||
# 重置配置
|
||
quicommit config reset --force
|
||
```
|
||
|
||
## 贡献
|
||
|
||
欢迎贡献代码！请遵循以下步骤：
|
||
|
||
### 提交Pull Request
|
||
|
||
1. Fork本仓库
|
||
2. 创建功能分支：`git checkout -b feature/your-feature`
|
||
3. 提交变更：`git commit -m 'feat: 添加新功能'`
|
||
4. 推送分支：`git push origin feature/your-feature`
|
||
5. 提交Pull Request
|
||
|
||
### 开发环境
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone https://git.lyz.one/SidneyZhang/QuiCommit.git
|
||
cd QuiCommit
|
||
|
||
# 安装依赖
|
||
cargo fetch
|
||
|
||
# 开发模式运行
|
||
cargo run -- commit --help
|
||
|
||
# 运行测试
|
||
cargo test
|
||
|
||
# 代码检查
|
||
cargo clippy
|
||
cargo fmt --check
|
||
```
|
||
|
||
### 代码规范
|
||
|
||
- 遵循Rust官方代码风格（运行 `cargo fmt`）
|
||
- 提交信息使用Conventional Commits格式
|
||
- 新增功能应添加测试
|
||
- 运行 `cargo clippy` 确保无警告
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
src/
|
||
├── commands/ # CLI命令实现
|
||
│ ├── commit.rs
|
||
│ ├── tag.rs
|
||
│ ├── changelog.rs
|
||
│ ├── profile.rs
|
||
│ ├── config.rs
|
||
│ └── init.rs
|
||
├── config/ # 配置管理
|
||
│ ├── manager.rs
|
||
│ └── profile.rs
|
||
├── generator/ # AI内容生成
|
||
├── git/ # Git操作封装
|
||
│ ├── commit.rs
|
||
│ ├── tag.rs
|
||
│ └── changelog.rs
|
||
├── llm/ # LLM提供商实现
|
||
│ ├── ollama.rs
|
||
│ ├── openai.rs
|
||
│ ├── anthropic.rs
|
||
│ ├── kimi.rs
|
||
│ ├── deepseek.rs
|
||
│ └── openrouter.rs
|
||
├── i18n/ # 国际化支持
|
||
│ ├── messages.rs
|
||
│ └── translator.rs
|
||
├── utils/ # 工具函数
|
||
│ ├── validators.rs
|
||
│ ├── formatter.rs
|
||
│ ├── crypto.rs
|
||
│ └── editor.rs
|
||
└── main.rs # 程序入口
|
||
```
|
||
|
||
## 许可证
|
||
|
||
MIT License
|