501 lines
11 KiB
Markdown
501 lines
11 KiB
Markdown
# QuiCommit
|
|
|
|
English | [中文文档](README_zh.md)
|
|
|
|
A powerful AI-powered Git assistant for generating conventional commits, tags, and changelogs. Manage multiple Git profiles for different work contexts.
|
|
|
|
[Still in early development, some features may not be complete. Feedback and contributions are welcome.]
|
|
|
|
|
|
|
|
|
|
## Features
|
|
|
|
- **AI-Powered Generation**: Generate commits, tags, and changelogs using LLM APIs (Ollama, OpenAI, Anthropic, Kimi, DeepSeek, OpenRouter) or local models
|
|
- **Conventional Commits**: Full support for Conventional Commits and commitlint formats
|
|
- **Profile Management**: Manage multiple Git identities with SSH keys and GPG signing support
|
|
- **Smart Tagging**: Semantic version bumping with AI-generated release notes
|
|
- **Changelog Generation**: Automatic changelog generation in Keep a Changelog format
|
|
- **Security**: Encrypt sensitive data
|
|
- **Interactive UI**: Beautiful CLI with previews and confirmations
|
|
|
|
## Installation
|
|
|
|
### Cargo Install
|
|
|
|
The cargo-installed version may temporarily lag behind the source code progress.
|
|
|
|
```bash
|
|
cargo install quicommit
|
|
```
|
|
|
|
### Install from Source
|
|
|
|
```bash
|
|
git clone https://git.lyz.one/SidneyZhang/QuiCommit.git
|
|
cd QuiCommit
|
|
cargo build --release
|
|
cargo install --path .
|
|
```
|
|
|
|
Requirements: Rust 1.70+, Git 2.0+
|
|
|
|
## Quick Start
|
|
|
|
### Initialize
|
|
|
|
```bash
|
|
quicommit init
|
|
```
|
|
|
|
### Generate Commit
|
|
|
|
```bash
|
|
# AI-generated commit (default)
|
|
quicommit commit
|
|
|
|
# Manual commit
|
|
quicommit commit --manual -t feat -m "add new feature"
|
|
|
|
# Stage all and commit
|
|
quicommit commit -a
|
|
|
|
# Skip confirmation
|
|
quicommit commit --yes
|
|
|
|
# Use date-based commit message
|
|
quicommit commit --date
|
|
|
|
# Push after committing
|
|
quicommit commit --push
|
|
```
|
|
|
|
### Create Tag
|
|
|
|
```bash
|
|
# Auto-detect version bump
|
|
quicommit tag
|
|
|
|
# Specify bump type
|
|
quicommit tag --bump minor
|
|
|
|
# Custom tag name
|
|
quicommit tag -n v1.0.0
|
|
|
|
# AI-generate tag message
|
|
quicommit tag --generate
|
|
|
|
# Create tag and push to remote
|
|
quicommit tag --push
|
|
```
|
|
|
|
### Generate Changelog
|
|
|
|
```bash
|
|
# Generate for unreleased changes
|
|
quicommit changelog
|
|
|
|
# Generate for specific version
|
|
quicommit changelog -v 1.0.0
|
|
|
|
# AI-generate changelog
|
|
quicommit changelog --generate
|
|
|
|
# Initialize new changelog file
|
|
quicommit changelog --init
|
|
|
|
# Specify output file
|
|
quicommit changelog -o RELEASE_NOTES.md
|
|
```
|
|
|
|
### Manage Profiles
|
|
|
|
```bash
|
|
# Add new profile
|
|
quicommit profile add
|
|
|
|
# List profiles
|
|
quicommit profile list
|
|
|
|
# Show profile details
|
|
quicommit profile show
|
|
|
|
# Switch profile
|
|
quicommit profile switch
|
|
|
|
# Set default profile
|
|
quicommit profile set-default personal
|
|
|
|
# Set profile for current repo
|
|
quicommit profile set-repo personal
|
|
|
|
# Apply profile to current repo
|
|
quicommit profile apply
|
|
|
|
# Apply profile globally
|
|
quicommit profile apply --global
|
|
|
|
# Copy profile
|
|
quicommit profile copy personal work
|
|
|
|
# Edit profile
|
|
quicommit profile edit personal
|
|
|
|
# Remove profile
|
|
quicommit profile remove old-profile
|
|
|
|
# Check profile
|
|
quicommit profile check
|
|
|
|
# View usage statistics
|
|
quicommit profile stats
|
|
|
|
# Manage profile tokens
|
|
quicommit profile token
|
|
```
|
|
|
|
### Configure LLM
|
|
|
|
```bash
|
|
# Configure Ollama (local)
|
|
quicommit config set-llm ollama
|
|
quicommit config set-ollama --url http://localhost:11434 --model llama2
|
|
|
|
# Configure OpenAI
|
|
quicommit config set-llm openai
|
|
quicommit config set-openai-key YOUR_API_KEY
|
|
|
|
# Configure Anthropic Claude
|
|
quicommit config set-llm anthropic
|
|
quicommit config set-anthropic-key YOUR_API_KEY
|
|
|
|
# Configure Kimi (Moonshot AI)
|
|
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
|
|
|
|
# Configure 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
|
|
|
|
# Configure 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
|
|
|
|
# Set commit format
|
|
quicommit config set-commit-format conventional
|
|
|
|
# Set version prefix
|
|
quicommit config set-version-prefix v
|
|
|
|
# Set changelog path
|
|
quicommit config set-changelog-path CHANGELOG.md
|
|
|
|
# Set output language
|
|
quicommit config set-language en
|
|
|
|
# Set keep commit types in English
|
|
quicommit config set-keep-types-english true
|
|
|
|
# Set keep changelog types in English
|
|
quicommit config set-keep-changelog-types-english true
|
|
|
|
# Test LLM connection
|
|
quicommit config test-llm
|
|
|
|
# Reset configuration to defaults
|
|
quicommit config reset
|
|
```
|
|
|
|
## Command Reference
|
|
|
|
| Command | Alias | Description |
|
|
|---------|-------|-------------|
|
|
| `quicommit init` | `i` | Initialize configuration |
|
|
| `quicommit commit` | `c` | Generate and create commit |
|
|
| `quicommit tag` | `t` | Generate and create tag |
|
|
| `quicommit changelog` | `cl` | Generate changelog |
|
|
| `quicommit profile` | `p` | Manage Git profiles |
|
|
| `quicommit config` | `cfg` | Manage settings |
|
|
|
|
### Commit Options
|
|
|
|
| Option | Description |
|
|
|--------|-------------|
|
|
| `--commit-type` | Commit type (feat, fix, etc.) |
|
|
| `-s, --scope` | Commit scope |
|
|
| `-m, --message` | Commit description |
|
|
| `--body` | Commit body |
|
|
| `-b, --breaking` | Mark as breaking change |
|
|
| `-d, --date` | Use date-based commit message |
|
|
| `--manual` | Manual input, skip AI |
|
|
| `-a, --all` | Stage all changes |
|
|
| `-S, --sign` | GPG sign commit |
|
|
| `--amend` | Amend previous commit |
|
|
| `--dry-run` | Show without committing |
|
|
| `--conventional` | Use Conventional Commits format |
|
|
| `--commitlint` | Use commitlint format |
|
|
| `--no-verify` | Skip commit message verification |
|
|
| `-y, --yes` | Skip confirmation |
|
|
| `--push` | Push after committing |
|
|
| `--remote` | Specify remote repository (default: origin) |
|
|
|
|
### Tag Options
|
|
|
|
| Option | Description |
|
|
|--------|-------------|
|
|
| `-n, --name` | Tag name |
|
|
| `-b, --bump` | Version bump (major/minor/patch) |
|
|
| `-m, --message` | Tag message |
|
|
| `-g, --generate` | AI-generate message |
|
|
| `-S, --sign` | GPG sign tag |
|
|
| `-l, --lightweight` | Create lightweight tag |
|
|
| `-f, --force` | Force overwrite existing tag |
|
|
| `-p, --push` | Push to remote |
|
|
| `-r, --remote` | Specify remote repository (default: origin) |
|
|
| `--dry-run` | Dry run |
|
|
| `-y, --yes` | Skip confirmation |
|
|
|
|
### Changelog Options
|
|
|
|
| Option | Description |
|
|
|--------|-------------|
|
|
| `-o, --output` | Output file path |
|
|
| `-v, --version` | Generate for specific version |
|
|
| `-f, --from` | Generate from specific tag |
|
|
| `-t, --to` | Generate to specific ref (default: HEAD) |
|
|
| `-i, --init` | Initialize new changelog file |
|
|
| `-g, --generate` | AI-generate changelog |
|
|
| `--prepend` | Prepend to existing changelog |
|
|
| `--include-hashes` | Include commit hashes |
|
|
| `--include-authors` | Include authors |
|
|
| `--format` | Format (keep-a-changelog, github-releases) |
|
|
| `--dry-run` | Dry run (output to stdout) |
|
|
| `-y, --yes` | Skip confirmation |
|
|
|
|
## Configuration File
|
|
|
|
Location:
|
|
- 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 = "Personal projects"
|
|
is_work = false
|
|
|
|
[profiles.work]
|
|
name = "work"
|
|
user_name = "Your Name"
|
|
user_email = "your.name@company.com"
|
|
description = "Work projects"
|
|
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"
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Description |
|
|
|----------|-------------|
|
|
| `QUICOMMIT_CONFIG` | Configuration file path |
|
|
| `EDITOR` | Default editor |
|
|
| `NO_COLOR` | Disable colored output |
|
|
|
|
## Troubleshooting
|
|
|
|
```bash
|
|
# View current configuration
|
|
quicommit config list
|
|
|
|
# Show configuration details
|
|
quicommit config show
|
|
|
|
# Edit configuration file
|
|
quicommit config edit
|
|
|
|
# Set configuration value
|
|
quicommit config set llm.provider ollama
|
|
|
|
# Get configuration value
|
|
quicommit config get llm.provider
|
|
|
|
# Test LLM connection
|
|
quicommit config test-llm
|
|
|
|
# List available models
|
|
quicommit config list-models
|
|
|
|
# Export configuration
|
|
quicommit config export -o config-backup.toml
|
|
|
|
# Import configuration
|
|
quicommit config import -i config-backup.toml
|
|
|
|
# Reset configuration
|
|
quicommit config reset --force
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please follow these steps:
|
|
|
|
### Submit a Pull Request
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch: `git checkout -b feature/your-feature`
|
|
3. Commit changes: `git commit -m 'feat: add new feature'`
|
|
4. Push branch: `git push origin feature/your-feature`
|
|
5. Open a Pull Request
|
|
|
|
### Development Setup
|
|
|
|
```bash
|
|
# Clone repository
|
|
git clone https://git.lyz.one/SidneyZhang/QuiCommit.git
|
|
cd QuiCommit
|
|
|
|
# Fetch dependencies
|
|
cargo fetch
|
|
|
|
# Run in development mode
|
|
cargo run -- commit --help
|
|
|
|
# Run tests
|
|
cargo test
|
|
|
|
# Code quality checks
|
|
cargo clippy
|
|
cargo fmt --check
|
|
```
|
|
|
|
### Code Standards
|
|
|
|
- Follow Rust formatting (run `cargo fmt`)
|
|
- Use Conventional Commits for commit messages
|
|
- Add tests for new features
|
|
- Ensure `cargo clippy` passes with no warnings
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
src/
|
|
├── commands/ # CLI command implementations
|
|
│ ├── commit.rs
|
|
│ ├── tag.rs
|
|
│ ├── changelog.rs
|
|
│ ├── profile.rs
|
|
│ ├── config.rs
|
|
│ └── init.rs
|
|
├── config/ # Configuration management
|
|
│ ├── manager.rs
|
|
│ └── profile.rs
|
|
├── generator/ # AI content generation
|
|
├── git/ # Git operations
|
|
│ ├── commit.rs
|
|
│ ├── tag.rs
|
|
│ └── changelog.rs
|
|
├── llm/ # LLM provider implementations
|
|
│ ├── ollama.rs
|
|
│ ├── openai.rs
|
|
│ ├── anthropic.rs
|
|
│ ├── kimi.rs
|
|
│ ├── deepseek.rs
|
|
│ └── openrouter.rs
|
|
├── i18n/ # Internationalization support
|
|
│ ├── messages.rs
|
|
│ └── translator.rs
|
|
├── utils/ # Utility functions
|
|
│ ├── validators.rs
|
|
│ ├── formatter.rs
|
|
│ ├── crypto.rs
|
|
│ └── editor.rs
|
|
└── main.rs # Program entry point
|
|
```
|
|
|
|
## License
|
|
|
|
MIT License
|
|
|
|
## Acknowledgments
|
|
|
|
- [Conventional Commits](https://www.conventionalcommits.org/) specification
|
|
- [Keep a Changelog](https://keepachangelog.com/) format
|
|
- [Ollama](https://ollama.ai/) for local LLM support
|