docs: Expand README with comprehensive installation and usage guides 📖

mingcheng · mingcheng · commit aa13e1fffb05 · 2025-11-07T15:02:07.000+08:00
- add step-by-step installation options including crates.io, source, and Docker
- include detailed usage examples, command-line options, and workflow integration

Signed-off-by: mingcheng &lt;mingcheng@apache.org&gt;
diff --git a/README.md b/README.md
@@ -14,45 +14,76 @@ It inspects your diffs, summarizes the intent of your changes, and produces clea
 
 ## References
 
-- https://www.conventionalcommits.org/en/v1.0.0/
-- https://nitayneeman.com/blog/understanding-semantic-commit-messages-using-git-and-angular/
-- https://ssshooter.com/2020-09-30-commit-message/
+- [Conventional Commits Specification](https://www.conventionalcommits.org/en/v1.0.0/)
+- [Understanding Semantic Commit Messages](https://nitayneeman.com/blog/understanding-semantic-commit-messages-using-git-and-angular/)
+- [Commit Message Best Practices](https://ssshooter.com/2020-09-30-commit-message/)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests on [GitHub](https://github.com/mingcheng/aigitcommit).
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
 
 ## Features
 
-- Generates meaningful, semantic commit messages from staged changes.
-- Commit directly to the repository with the `--commit` flag or copy the generated message with `--copy`.
-- Output formats: human-readable text, JSON (machine-readable) and table view. JSON output is useful for CI integrations and automation; table view makes it easy to scan multiple suggested lines.
-- Easy-to-use command-line interface with sensible defaults and confirm prompts (can be skipped with `--yes`).
-- Uses libgit2 via the `git2` crate, avoiding external git commands for improved security and performance.
-- Supports multiple OpenAI-compatible models and configurable API base, token, and proxy settings.
-- Optional auto sign-off of commits when `AIGITCOMMIT_SIGNOFF=true` or `git config --bool aigitcommit.signoff true`.
-- Proxy support: HTTP and SOCKS5 (set via `OPENAI_API_PROXY`).
+- **AI-Powered Commit Messages**: Automatically generates meaningful, semantic commit messages from staged Git changes
+- **Conventional Commits**: Follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for consistent, structured messages
+- **Multiple Output Formats**:
+  - Human-readable table view (default)
+  - JSON format for CI/CD integration and automation
+  - Plain text output
+- **Flexible Workflow**:
+  - Direct commit with `--commit` flag
+  - Copy to clipboard with `--copy-to-clipboard`
+  - Git hook integration for automatic message generation
+- **Interactive & Non-Interactive**: Confirmation prompts by default, skip with `--yes` for scripting
+- **Security & Performance**: Uses libgit2 via the `git2` crate, avoiding external git command execution
+- **Multi-Provider Support**: Compatible with OpenAI and other OpenAI-compatible APIs (Azure OpenAI, local models, etc.)
+- **Flexible Configuration**:
+  - Environment variables for API settings
+  - Git config for repository-specific or global settings
+  - Configurable API base URL, token, proxy, and timeouts
+- **Sign-off Support**: Auto sign-off via `AIGITCOMMIT_SIGNOFF` environment variable or `git config aigitcommit.signoff`
+- **Proxy Support**: HTTP and SOCKS5 proxies via `OPENAI_API_PROXY`
 
 
 ## How It Works
 
-AIGitCommit inspects your staged Git changes, summarizes the intent of those changes, and generates clear semantic commit messages. It examines diffs and uses an AI model to infer intent and produce concise, useful commit lines.
+AIGitCommit streamlines your commit workflow by:
 
-## Install
+1. **Analyzing Changes**: Inspects staged changes using `git diff --cached`
+2. **Understanding Context**: Examines recent commit history for stylistic consistency
+3. **AI Generation**: Sends diffs to an OpenAI-compatible model with carefully crafted prompts
+4. **Structured Output**: Generates commit messages following Conventional Commits specification
+5. **User Review**: Presents the message for review and optional editing
 
-AIGitCommit is still in the early stages of development, I suggest you to install it using the git URL using the commands below:
+The tool uses libgit2 for secure, efficient Git operations without spawning external processes. It automatically filters out common noise files (lock files, generated code) to focus on meaningful changes.
 
-```
-cargo install --git https://github.com/mingcheng/aigitcommit.git
-```
+## Installation
 
-or, You can install from [crates.io](https://crates.io/crates/aigitcommit)
+### From crates.io (Recommended)
 
-```
+```bash
 cargo install aigitcommit
 ```
 
-Those command will auto-download the latest version of the project and install it to your cargo bin directory.
+### From Source
+
+For the latest development version:
+
+```bash
+cargo install --git https://github.com/mingcheng/aigitcommit.git
+```
+
+Both commands will download, compile, and install the binary to your Cargo bin directory (typically `~/.cargo/bin`). Ensure this directory is in your `PATH`.
 
-### Docker image
+### Docker Image
 
-AIGitCommit can run in Docker if you prefer not to install the binary locally. Example (read-only repository):
+Run AIGitCommit in Docker without installing the binary locally.
+
+**Read-only mode** (generate message only):
 
 ```bash
 docker run \
@@ -65,7 +96,7 @@ docker run \
   ghcr.io/mingcheng/aigitcommit
 ```
 
-If you want to use `--commit` from inside the container, mount the repo as writable and run interactively:
+**Interactive mode** (with `--commit` flag):
 
 ```bash
 docker run \
@@ -76,103 +107,209 @@ docker run \
   -e OPENAI_API_TOKEN='<api token>' \
   -e OPENAI_MODEL_NAME='<model name>' \
   -e OPENAI_API_PROXY='<proxy if needed>' \
-  ghcr.io/mingcheng/aigitcommit --commit
+  ghcr.io/mingcheng/aigitcommit --commit --yes
 ```
 
-Use `--yes` to skip interactive confirmations.
+Note: Use `--yes` to skip interactive confirmations in non-TTY environments.
 
-### Git hook
+### Git Hook
 
-AIGitCommit ships a `hooks/prepare-commit-msg` hook that pauses your commit workflow, looks at the staged diff, and pre-populates `COMMIT_EDITMSG` with an AI-generated summary. This lets you fine-tune the final message instead of writing it from scratch.
+AIGitCommit includes a `prepare-commit-msg` hook that automatically generates commit messages during your workflow. The hook triggers when you run `git commit` or `git commit -m ""`, generates a message from staged changes, and opens your editor for review.
 
 **Prerequisites**
-- `aigitcommit` must be installed and discoverable on your `PATH`.
-- Required environment variables (`OPENAI_API_TOKEN`, `OPENAI_API_BASE`, etc.) should be configured in your shell before running `git commit`.
 
-**Project-level installation**
+- `aigitcommit` must be installed and available in your `PATH`
+- Configure required environment variables before committing (see [Configuration](#configuration))
+
+**Per-Repository Installation**
 
-Install the hook in the current repository only:
+Install the hook for a single repository:
 
 ```bash
 cp hooks/prepare-commit-msg .git/hooks/prepare-commit-msg
 chmod +x .git/hooks/prepare-commit-msg
 ```
 
-After copying, stage some changes and run `git commit`. The hook prints progress messages, writes the suggested commit text, and drops you into your editor so you can adjust the result. To verify the hook without creating a new commit, try `git commit --amend` against a throwaway repository.
+After installation, the hook runs automatically when you execute `git commit`. You can review and edit the generated message before finalizing the commit.
 
-If you need to disable the hook for a single commit, use `git commit --no-verify`.
+**Disable for a single commit**: Use `git commit --no-verify` to bypass the hook.
 
-**Global installation**
+**Global Installation**
 
-Install once and reuse across repositories:
+Set up the hook for all new and existing repositories using Git templates:
 
 ```bash
-mkdir -p ~/.git-hooks
-cp hooks/prepare-commit-msg ~/.git-hooks/prepare-commit-msg
-chmod +x ~/.git-hooks/prepare-commit-msg
-git config --global core.hooksPath ~/.git-hooks
+# Create template directory structure
+mkdir -p ~/.git-template/hooks
+cp hooks/prepare-commit-msg ~/.git-template/hooks/prepare-commit-msg
+chmod +x ~/.git-template/hooks/prepare-commit-msg
+
+# Configure Git to use this template for new repositories
+git config --global init.templateDir ~/.git-template
+
+# Apply to existing repositories
+# Option 1: Copy manually
+cp ~/.git-template/hooks/prepare-commit-msg <repo>/.git/hooks/
+
+# Option 2: Re-initialize (safe, preserves existing data)
+cd <repo> && git init
 ```
 
-This approach lets every repository automatically pick up the hook as long as `core.hooksPath` remains set.
+**Important**: Setting `core.hooksPath` globally overrides all repository hooks. The template approach is more flexible and recommended.
+
+**Hook Behavior**
+
+The hook only runs when:
+- You execute `git commit` (interactive mode) with no pre-written message
+- You execute `git commit -m ""` (explicit empty message)
+
+The hook skips execution for:
+- Commits with pre-written messages (`git commit -m "message"`)
+- Merge commits, rebase, cherry-pick, or other automated commits
+- When the commit message file already contains non-comment content
 
 **Troubleshooting**
-- If the hook exits early with a warning about missing staged changes, make sure you have run `git add`.
-- A message about missing configuration usually means the OpenAI-related environment variables are not exported in your shell session.
-- Hook output is written to stderr; if you prefer a quieter experience, redirect or silence stderr in your Git configuration.
+
+- **"No staged changes detected"**: Run `git add` to stage your changes before committing
+- **"aigitcommit is not installed"**: Ensure the binary is in your `PATH` or install it first
+- **Missing configuration error**: Export required environment variables (`OPENAI_API_TOKEN`, etc.) in your shell
+- **Hook output too verbose**: Redirect stderr in your Git configuration: `git config core.hookStderr false`
 
 ## Configuration
 
-Before using AIGitCommit, export the following environment variables (for example in your shell profile):
+### Environment Variables
+
+Configure AIGitCommit by setting these environment variables (in your shell profile, `.bashrc`, `.zshrc`, etc.):
 
-- `OPENAI_API_TOKEN`: Your OpenAI-compatible API token.
-- `OPENAI_API_BASE`: The API base URL (useful for alternative providers or local proxies).
-- `OPENAI_MODEL_NAME`: The model name to query (e.g., a GPT-compatible model).
-- `OPENAI_API_PROXY`: Optional. Proxy address for network access (e.g., `http://127.0.0.1:1080` or `socks://127.0.0.1:1086`).
-- `AIGITCOMMIT_SIGNOFF`: Optional. Set to `true` (or any truthy value) to append a Signed-off-by line to commits.
+**Required:**
+- `OPENAI_API_TOKEN`: Your OpenAI-compatible API authentication token
+- `OPENAI_API_BASE`: API endpoint URL (e.g., `https://api.openai.com/v1` or your provider's URL)
+- `OPENAI_MODEL_NAME`: Model identifier (e.g., `gpt-4`, `gpt-3.5-turbo`, or provider-specific models)
 
-You can also enable sign-off via Git configuration:
+**Optional:**
+- `OPENAI_API_PROXY`: HTTP/SOCKS5 proxy URL (e.g., `http://127.0.0.1:1080`, `socks5://127.0.0.1:1086`)
+- `OPENAI_API_TIMEOUT`: Request timeout in seconds (default: 30)
+- `OPENAI_API_MAX_TOKENS`: Maximum tokens in response (default: model-specific)
+- `AIGITCOMMIT_SIGNOFF`: Enable auto sign-off (`true`, `1`, `yes`, `on`)
+
+**Example configuration:**
 
 ```bash
-git config aigitcommit.signoff true       # repository only
-git config --global aigitcommit.signoff true
+# ~/.bashrc or ~/.zshrc
+export OPENAI_API_TOKEN="sk-..."
+export OPENAI_API_BASE="https://api.openai.com/v1"
+export OPENAI_MODEL_NAME="gpt-4"
+export OPENAI_API_PROXY="http://127.0.0.1:1080"  # Optional
+export AIGITCOMMIT_SIGNOFF="true"                # Optional
 ```
 
-The Git configuration takes precedence over the environment variable.
+### Git Configuration
+
+You can also enable sign-off via Git configuration (takes precedence over environment variables):
+
+```bash
+# Repository-specific
+git config aigitcommit.signoff true
+
+# Global (all repositories)
+git config --global aigitcommit.signoff true
+```
 
-### Check the configuration
+### Verify Configuration
 
-After setting the environment variables, you can check if they are set correctly by running:
+Check your environment setup:
 
 ```bash
+# Verify all environment variables
 aigitcommit --check-env
+
+# Test API connectivity and model availability
+aigitcommit --check-model
+
+# Show all available options
+aigitcommit --help
 ```
 
-This will print the current configuration and verify that the required variables are set.
+## Usage
+
+### Basic Usage
 
-Then you can run
+Run AIGitCommit in a Git repository with staged changes:
 
 ```bash
-aigitcommit --check-model
+# In the current repository
+aigitcommit
+
+# Specify a different repository path
+aigitcommit /path/to/repo
 ```
 
-to check if the specified model is available and can be queried successfully.
+The tool will:
+1. Analyze your staged changes (`git diff --cached`)
+2. Generate a Conventional Commit message using AI
+3. Display the result in table format (default)
 
-You can also run `aigitcommit --help` to see the available options and usage instructions.
+### Command-Line Options
 
-## Usage
+**Output Formats:**
+- Default: Table view (easy to read)
+- `--json`: JSON output (for CI/automation)
+- `--no-table`: Plain text output
+
+**Actions:**
+- `--commit`: Automatically commit with the generated message
+- `--copy-to-clipboard`: Copy the message to clipboard
+- `--yes`: Skip confirmation prompts (useful for scripting)
+- `--signoff`: Append `Signed-off-by` line to the commit
 
-Run `aigitcommit` in a repository with staged changes. Optionally provide a path to the git directory: `aigitcommit <dir>`.
+**Diagnostics:**
+- `--check-env`: Verify environment variable configuration
+- `--check-model`: Test API connectivity and model availability
+- `--help`: Show all available options
 
-Common flags:
+### Examples
 
-1. `--commit` commit generated message directly to the repository.
-2. `--copy-to-clipboard` copy the generated message to the clipboard.
-3. `--json` print the suggestions as JSON for CI or automation.
-4. `--yes` skip confirmation prompts and apply the default action.
-5. `--signoff` append a Signed-off-by line to the commit message.
+**Generate and review message:**
+```bash
+aigitcommit
+```
 
-See `aigitcommit --help` for the full list of options.
+**Auto-commit without confirmation:**
+```bash
+aigitcommit --commit --yes
+```
 
+**Copy message to clipboard:**
+```bash
+aigitcommit --copy-to-clipboard
+```
+
+**JSON output for CI pipelines:**
+```bash
+aigitcommit --json | jq '.title'
+```
+
+**Commit with sign-off:**
+```bash
+aigitcommit --commit --signoff
+```
+
+### Workflow Integration
+
+**Typical workflow:**
+```bash
+# Stage your changes
+git add .
+
+# Generate and review commit message
+aigitcommit
+
+# Or commit directly
+aigitcommit --commit
+
+# Or use the Git hook (if installed)
+git commit  # Hook generates message automatically
+```
 
 ## License
 
