QuiCommit/README.md

QuiCommit

English | 中文文档

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.]

⚠️ Important Notice: QuiCommit now uses system keyring to store API keys securely. This change may cause breaking changes to your existing configuration. If you encounter issues after updating, please run quicommit config reset --force to reset your configuration, then reconfigure your settings.

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: Use system keyring to store API keys securely
• Interactive UI: Beautiful CLI with previews and confirmations
• Multi-language Support: Output in 7 languages (English, Chinese, Japanese, Korean, Spanish, French, German)
• Config Export/Import: Backup and restore configuration with optional encryption

Installation

Cargo Install

The cargo-installed version may temporarily lag behind the source code progress.

cargo install quicommit

Install from Source

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

quicommit init

Generate Commit

# 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

# 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

# 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

# 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

# Configure Ollama (local)
quicommit config set-llm ollama
quicommit config set-llm ollama --url http://localhost:11434 --model llama2

# Configure OpenAI
quicommit config set-llm openai
quicommit config set-api-key YOUR_API_KEY

# Configure Anthropic Claude
quicommit config set-llm anthropic
quicommit config set-api-key YOUR_API_KEY

# Configure Kimi (Moonshot AI)
quicommit config set-llm kimi
quicommit config set-api-key YOUR_API_KEY
quicommit config set-llm kimi --base-url https://api.moonshot.cn/v1 --model moonshot-v1-8k

# Configure DeepSeek
quicommit config set-llm deepseek
quicommit config set-api-key YOUR_API_KEY
quicommit config set-llm deepseek --base-url https://api.deepseek.com/v1 --model deepseek-chat

# Configure OpenRouter
quicommit config set-llm openrouter
quicommit config set-api-key YOUR_API_KEY
quicommit config set-llm 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 (en, zh, ja, ko, es, fr, de)
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

# Check keyring availability
quicommit config check-keyring

# Show config file path
quicommit config path

# Export configuration (with optional encryption)
quicommit config export -o config-backup.toml
quicommit config export -o config-backup.enc --password

# Import configuration
quicommit config import -i config-backup.toml
quicommit config import -i config-backup.enc --password

# Reset configuration to defaults
quicommit config reset --force

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

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

# 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

# Set API key (stored in system keyring)
quicommit config set-api-key YOUR_API_KEY

# Delete API key from keyring
quicommit config delete-api-key

# Test LLM connection
quicommit config test-llm

# List available models
quicommit config list-models

# Check keyring availability
quicommit config check-keyring

# Show config file path
quicommit config path

# Export configuration (with optional encryption)
quicommit config export -o config-backup.toml
quicommit config export -o config-backup.enc --password

# Import configuration
quicommit config import -i config-backup.toml
quicommit config import -i config-backup.enc --password

# 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

# 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 specification
• Keep a Changelog format
• Ollama for local LLM support