AIGitCommit is a command-line tool that generates meaningful, semantic commit messages from your staged Git changes using AI.

It inspects your diffs, summarizes the intent of your changes, and produces clear, concise commit messages that follow the Conventional Commits specification.

• Conventional Commits Specification
• Understanding Semantic Commit Messages
• Commit Message Best Practices

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests on GitHub.

This project is licensed under the MIT License. See the LICENSE file for details.

• AI-Powered Commit Messages: Automatically generates meaningful, semantic commit messages from staged Git changes
• Conventional Commits: Follows the Conventional Commits 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
• Local Response Cache: Reuses previous results when nothing has changed, avoiding redundant API calls
• Proxy Support: HTTP and SOCKS5 proxies via OPENAI_API_PROXY

AIGitCommit streamlines your commit workflow by:

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

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 aigitcommit

For the latest development version:

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.

Run AIGitCommit in Docker without installing the binary locally.

Read-only mode (generate message only):

docker run \
  --rm \
  -v $PWD:/repo:ro \
  -e OPENAI_API_BASE='<api base>' \
  -e OPENAI_API_TOKEN='<api token>' \
  -e OPENAI_MODEL_NAME='<model name>' \
  -e OPENAI_API_PROXY='<proxy if needed>' \
  ghcr.io/mingcheng/aigitcommit

Interactive mode (with --commit flag):

docker run \
  --rm \
  -it \
  -v $PWD:/repo:rw \
  -e OPENAI_API_BASE='<api base>' \
  -e OPENAI_API_TOKEN='<api token>' \
  -e OPENAI_MODEL_NAME='<model name>' \
  -e OPENAI_API_PROXY='<proxy if needed>' \
  ghcr.io/mingcheng/aigitcommit --commit --yes

Note: Use --yes to skip interactive confirmations in non-TTY environments.

AIGitCommit includes a prepare-commit-msg hook that automatically generates commit messages during your workflow.

Quick install (recommended)

Install into the current repository:

aigitcommit install-hook .

Install into a specific repository:

aigitcommit install-hook /path/to/repo

If a prepare-commit-msg hook already exists, it is renamed to prepare-commit-msg.bak before the new hook is written, so your previous hook is preserved (any prior .bak is overwritten).

Prerequisite: aigitcommit is installed and available in your PATH.

Prerequisites

• aigitcommit must be installed and available in your PATH
• Configure required environment variables before committing (see Configuration)

Manual install (alternative)

cp hooks/prepare-commit-msg .git/hooks/prepare-commit-msg
chmod +x .git/hooks/prepare-commit-msg

Disable for a single commit: Use git commit --no-verify to bypass the hook.

Global installation (optional)

Use Git templates so new repos have the hook:

mkdir -p ~/.git-template/hooks
cp hooks/prepare-commit-msg ~/.git-template/hooks/prepare-commit-msg
chmod +x ~/.git-template/hooks/prepare-commit-msg
git config --global init.templateDir ~/.git-template

Apply to an existing repo (either copy the file or re-init):

cp ~/.git-template/hooks/prepare-commit-msg <repo>/.git/hooks/
# or
cd <repo> && git init

Hook behavior (summary)

• Triggers on git commit with no message or with -m "".
• Skips merge/rebase/cherry-pick and commits with an existing message.

Troubleshooting

• "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

Configure AIGitCommit by setting these environment variables (in your shell profile, .bashrc, .zshrc, etc.):

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)

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: HTTP request timeout in seconds. Unset, empty, invalid, or 0 means "use the HTTP client default (no timeout)"
• AIGITCOMMIT_SIGNOFF: Enable auto sign-off (true, 1, yes, on)

Example configuration:

# ~/.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

You can also enable sign-off via Git configuration (takes precedence over environment variables):

# Repository-specific
git config aigitcommit.signoff true

# Global (all repositories)
git config --global aigitcommit.signoff true

Check your environment setup:

# Verify all environment variables
aigitcommit --check-env

# Test API connectivity and model availability
aigitcommit --check-model

# Show all available options
aigitcommit --help

Run AIGitCommit in a Git repository with staged changes:

# In the current repository
aigitcommit

# Specify a different repository path
aigitcommit /path/to/repo

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)

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
• --save <file>: Save the generated commit message to the given file

Cache:

• --no-cache: Bypass the local cache for this run
• --clear-cache: Remove cached entries for the current repository and exit

Diagnostics:

• --check-env: Verify environment variable configuration
• --check-model: Test API connectivity and model availability
• --help: Show all available options

Generate and review message:

aigitcommit

Auto-commit without confirmation:

aigitcommit --commit --yes

Copy message to clipboard:

aigitcommit --copy-to-clipboard

JSON output for CI pipelines:

aigitcommit --json | jq '.title'

Commit with sign-off:

aigitcommit --commit --signoff

Responses are cached under <repo>/.git/aigitcommit-cache/ and keyed by the staged diff, recent commit logs, model and prompt. Any change to those inputs invalidates the entry automatically. Use --no-cache to bypass it for a single run, or --clear-cache to wipe it.

Typical workflow:

# 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

This project is licensed under the MIT License. See the LICENSE file for details.