Metadata-Version: 2.1
Name: gptcomet
Version: 2.11.0
Summary: GPTComet: AI-Powered Git Commit Message Generator.
Keywords: ai,git,commit,message,ai-powered,commit-message,gptcomet,chatgpt
Author-Email: belingud <im.victor@qq.com>
License: MIT license
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Project-URL: Homepage, https://github.com/belingud/gptcomet
Project-URL: Repository, https://github.com/belingud/gptcomet
Project-URL: Documentation, https://github.com/belingud/gptcomet
Requires-Python: <4.0,>=3.9
Description-Content-Type: text/markdown

# GPTComet: AI-Powered Git Commit Message Generator And Reviewer

<p align="center">
  <img src="artwork/logo.png" width="150" height="150" alt="GPTComet Logo">
</p>

<a href="https://www.producthunt.com/posts/gptcomet?embed=true&utm_source=badge-featured&utm_medium=badge&utm_source=badge-gptcomet" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=774818&theme=neutral&t=1747386848397" alt="GPTComet - GPTComet&#0058;&#0032;AI&#0045;Powered&#0032;Git&#0032;Commit&#0032;Message&#0032;Generator | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>

[![PyPI version](https://img.shields.io/pypi/v/gptcomet?style=for-the-badge)](https://pypi.org/project/gptcomet/)
![GitHub Release](https://img.shields.io/github/v/release/belingud/gptcomet?style=for-the-badge)
[![License](https://img.shields.io/github/license/belingud/gptcomet.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/belingud/gptcomet?style=for-the-badge)
![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/belingud/gptcomet/release.yml?style=for-the-badge)
![PyPI - Downloads](https://img.shields.io/pypi/dm/gptcomet?logo=pypi&style=for-the-badge)
![Pepy Total Downloads](https://img.shields.io/pepy/dt/gptcomet?style=for-the-badge&logo=python)
![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/belingud/gptcomet/total?style=for-the-badge&label=Release%20Download)

[简体中文](README.zh.md)

<!-- TOC -->

- [GPTComet: AI-Powered Git Commit Message Generator And Reviewer](#gptcomet-ai-powered-git-commit-message-generator-and-reviewer)
  - [💡 Overview](#-overview)
  - [✨ Features](#-features)
  - [⬇️ Installation](#️-installation)
  - [📕 Usage](#-usage)
  - [🔧 Setup](#-setup)
    - [Configuration Methods](#configuration-methods)
    - [Managing Providers](#managing-providers)
    - [Provider Setup Guide](#provider-setup-guide)
      - [OpenAI](#openai)
      - [Gemini](#gemini)
      - [Claude/Anthropic](#claudeanthropic)
      - [Vertex](#vertex)
      - [Azure](#azure)
      - [Ollama](#ollama)
      - [Other Supported Providers](#other-supported-providers)
    - [Manual Provider Setup](#manual-provider-setup)
  - [⌨️ Commands](#️-commands)
  - [🪝 Git Hook](#-git-hook)
  - [🧩 Scripting and exit codes](#-scripting-and-exit-codes)
  - [⚙ Configuration](#-configuration)
    - [file\_ignore](#file_ignore)
    - [provider](#provider)
    - [output](#output)
    - [Markdown theme](#markdown-theme)
    - [Supported languages](#supported-languages)
    - [console](#console)
    - [Sensitive data scanning](#sensitive-data-scanning)
  - [🔦 Supported Keys](#-supported-keys)
  - [📃 Example](#-example)
    - [Basic Usage](#basic-usage)
    - [Enhanced Error Messages](#enhanced-error-messages)
    - [Progress Indicators](#progress-indicators)
  - [💻 Development](#-development)
    - [Requirements](#requirements)
    - [Setup](#setup)
    - [Running Tests](#running-tests)
      - [Go Tests](#go-tests)
      - [Python Tests](#python-tests)
    - [Code Quality](#code-quality)
      - [Go](#go)
      - [Python](#python)
    - [Build](#build)
  - [📩 Contact](#-contact)
  - [☕️ Sponsor](#️-sponsor)
  - [📜 License](#-license)

<!-- /TOC -->

## 💡 Overview

GPTComet is an AI-powered developer tool that streamlines your Git workflow and enhances code quality through automated commit message generation and intelligent code review.

## ✨ Features

This project leverages the power of large language models to automate repetitive tasks and improve the overall development process. The core features include:

-   **Automatic Commit Message Generation**: GPTComet can generate commit messages based on the changes made in the code.
-   **Git Hook Integration**: Install a `prepare-commit-msg` hook once and let `git commit` fill the message automatically.
-   **Intelligent Code Review**: Get AI-powered code reviews with actionable feedback and suggestions.
-   **Progress Indicators**: Optional verbose mode shows real-time progress for long-running operations.
-   **Support for Multiple Languages**: GPTComet supports multiple languages, including English, Chinese and so on.
-   **Customizable Configuration**: GPTComet allows users to customize the configuration to suit their needs, such llm model and prompt.
-   **Support for Rich Commit Messages**: GPTComet supports rich commit messages, which include a title, summary, and detailed description.
-   **Support for Multiple Providers**: GPTComet supports multiple providers, including OpenAI, Gemini, Claude/Anthropic, Vertex, Azure, AWS Bedrock, Ollama, and others.
-   **Support SVN and Git**: GPTComet supports both SVN and Git repositories.

## ⬇️ Installation

To use GPTComet, you can install it with Homebrew:

```bash
brew install belingud/tap/gptcomet
```

To upgrade a Homebrew-managed installation, use:

```bash
brew upgrade gptcomet
```

You can also download from [Github release](https://github.com/belingud/gptcomet/releases/latest), or by install scripts:

```bash
curl -sSL https://cdn.jsdelivr.net/gh/belingud/gptcomet@master/install.sh | bash
```


Windows:

```powershell
irm https://cdn.jsdelivr.net/gh/belingud/gptcomet@master/install.ps1 | iex
```
If you want to install specific version, you can use the following script:

```bash
curl -sSL https://cdn.jsdelivr.net/gh/belingud/gptcomet@master/install.sh | bash -s -- -v 0.4.2
```

```powershell
irm https://cdn.jsdelivr.net/gh/belingud/gptcomet@master/install.ps1 | iex -CommandArgs @("-v", "0.4.2")
```

If you prefer to run in python, you can install by `pip` directly, it packaged the binary files corresponding to the platform already.

```shell
pip install gptcomet

# Using pipx
pipx install gptcomet

# Using uv
uv tool install gptcomet
Resolved 1 package in 1.33s
Installed 1 package in 8ms
 + gptcomet==0.1.6
Installed 2 executables: gmsg, gptcomet
```

## 📕 Usage

To use gptcomet, follow these steps:

1.  **Install GPTComet**: Install GPTComet through pypi.
2.  **Configure GPTComet**: See [Setup](#setup). Configure GPTComet with your api_key and other required keys like:

-   `provider`: The provider of the language model (default `openai`).
-   `api_base`: The base URL of the API (default `https://api.openai.com/v1`).
-   `api_key`: The API key for the provider.
-   `model`: The model used for generating commit messages (default `gpt-6.1-sol`).

3.  **Run GPTComet**: Run GPTComet using the following command: `gmsg commit`.

If you are using `openai` provider, and finished set `api_key`, you can run `gmsg commit` directly.

## 🔧 Setup

### Configuration Methods

1. **Direct Configuration**

    - Configure directly in `~/.config/gptcomet/gptcomet.yaml`.

2. **Interactive Setup**
    - Use the `gmsg provider new` command for guided setup (`gmsg newprovider` is deprecated and
      will be removed in v2.14.0; see [Deprecations](docs/deprecations.md)).

3. **Environment Variables**
    - If `api_key` is not set in the configuration file, GPTComet falls back to
      the provider's conventional environment variable, such as
      `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `AZURE_API_KEY`,
      or `<PROVIDER>_API_KEY` for other providers.
    - The configuration file takes precedence when both are set.

### Managing Providers

Inspect the active provider and every known provider, switch the default, and verify a provider
with one minimal request:

```shell
gmsg provider list     # active provider, model, API base, and API key source
gmsg provider use claude
gmsg provider test      # probe the active provider; or: gmsg provider test deepseek
```

`gmsg provider list` shows where each provider's API key comes from:

-   `config (sk-ab***)` — set in `gptcomet.yaml` (masked in the output);
-   `env OPENAI_API_KEY` — the config value is empty and the built-in environment variable is set;
-   `not required` — local providers such as `ollama` and `lmstudio`;
-   `missing` — no key found; commands that call the provider fail until one is set.

`gmsg provider use <name>` switches the default provider and creates a default configuration block
for a built-in provider that does not have one yet. It never overwrites an existing block, and it
warns when the API key or a provider-specific field (for example `azure.deployment_name`) is still
missing. Configured custom providers keep working through the OpenAI-compatible fallback.

`gmsg provider test [provider]` sends exactly one small request without retries, using the
provider's saved configuration, and reports the model, API base, key source, latency, and a short
response. It exits non-zero when the request fails and prints an actionable error (invalid key,
rate limit, provider outage, or network/proxy problem). It does not need a Git repository.

To add or reconfigure a provider interactively, use `gmsg provider new` (`gmsg newprovider` is
deprecated and will be removed in v2.14.0; see [Deprecations](docs/deprecations.md)).

### Provider Setup Guide

![Made with VHS](https://vhs.charm.sh/vhs-6019QMIveifvh9vGKc2ZZ8.gif)

```bash
gmsg provider new

    Select Provider

  > 1. azure
    2. chatglm
    3. claude
    4. cohere
    5. deepseek
    6. gemini
    7. groq
    8. kimi
    9. mistral
    10. ollama
    11. openai
    12. openrouter
    13. sambanova
    14. silicon
    15. tongyi
    16. vertex
    17. xai
    18. Input Manually

    ↑/k up • ↓/j down • ? more
```

#### OpenAI

OpenAI api key page: https://platform.openai.com/api-keys

```shell
gmsg provider new

Selected provider: openai
Configure provider:

Previous inputs:
  Enter OpenAI API base: https://api.openai.com/v1
  Enter API key: sk-abc*********************************************
  Enter max tokens: 1024

Enter Enter model name (default: gpt-6.1-sol):
> gpt-6.1-sol


Provider openai configured successfully!
```

#### Gemini

Gemini api key page: https://aistudio.google.com/u/1/apikey

```shell
gmsg provider new
Selected provider: gemini
Configure provider:

Previous inputs:
  Enter Gemini API base: https://generativelanguage.googleapis.com/v1beta/models
  Enter API key: AIz************************************
  Enter max tokens: 1024

Enter Enter model name (default: gemini-3.8-flash):
> gemini-3.8-flash

Provider gemini already has a configuration. Do you want to overwrite it? (y/N): y

Provider gemini configured successfully!
```

#### Claude/Anthropic

I don't have an anthropic account yet, please see [Anthropic console](https://console.anthropic.com)

#### Vertex

Vertex console page: https://console.cloud.google.com

```shell
gmsg provider new
Selected provider: vertex
Configure provider:

Previous inputs:
  Enter Vertex AI API Base URL: https://us-central1-aiplatform.googleapis.com/v1
  Enter API key: sk-awz*********************************************
  Enter location (e.g., us-central1): us-central1
  Enter max tokens: 1024
  Enter model name: gemini-3.8-flash

Enter Enter Google Cloud project ID:
> test-project


Provider vertex configured successfully!
```

#### Azure

```shell
gmsg provider new

Selected provider: azure
Configure provider:

Previous inputs:
  Enter Azure OpenAI endpoint: https://gptcomet.openai.azure.com
  Enter API key: ********************************
  Enter API version: 2024-02-15-preview
  Enter Azure OpenAI deployment name: gpt-6.1-sol
  Enter max tokens: 1024

Enter Enter deployment name (default: gpt-6.1-sol):
> gpt-6.1-sol


Provider azure configured successfully!
```

#### Ollama

```shell
gmsg provider new
Selected provider: ollama
Configure provider:

Previous inputs:
  Enter Ollama API Base URL: http://localhost:11434/api
  Enter max tokens: 1024

Enter Enter model name (default: qwen3.8:27b):
> qwen3.8:27b


Provider ollama configured successfully!
```

#### Other Supported Providers

-   AI21
-   AWS Bedrock
-   Baidu Qianfan (ERNIE)
-   ByteDance Doubao
-   Cloudflare Workers AI
-   Groq
-   Mistral
-   Tongyi/Qwen
-   XAI
-   Sambanova
-   Silicon
-   Deepseek
-   ChatGLM
-   KIMI
-   LM Studio
-   LongCat
-   Cohere
-   OpenRouter
-   Hunyuan
-   ModelScope
-   MiniMax

Default models are refreshed periodically; see
[docs/provider-models.md](https://github.com/belingud/gptcomet/blob/master/docs/provider-models.md) for the current defaults and
the last verification date.

> AWS Bedrock uses the OpenAI-compatible Bedrock runtime endpoint with a
> Bedrock API key (set `bedrock.api_key` or `AWS_BEARER_TOKEN_BEDROCK`). IAM
> access-key/SigV4 authentication is not supported yet.

### Manual Provider Setup

Or you can enter the provider name manually, and setup config manually.

```shell
gmsg provider new
You can either select one from the list or enter a custom provider name.
  ...
  vertex
> Input manually

Enter provider name: test
Enter OpenAI API Base URL [https://api.openai.com/v1]:
Enter model name [gpt-6.1-sol]:
Enter API key: ************************************
Enter max tokens [1024]:
[GPTComet] Provider test configured successfully.
```

This is also the escape hatch for any OpenAI-compatible service that GPTComet
does not ship a preset for: enter a custom provider name, then set its
`api_base`, `model`, and `api_key`. Advanced users can also set
`completion_path`, `answer_path`, `stream_answer_path`, `extra_headers`, and
`extra_body` for non-standard APIs.

Cloudflare Workers AI is a built-in provider now. Select `cloudflare` in
`gmsg provider new` and enter your account ID, API token, and Workers AI model
(for example `@cf/openai/gpt-oss-120b`); GPTComet builds the OpenAI-compatible
endpoint for you. The old `/ai/run` + `result.response` manual workaround is no
longer needed.

```shell
$ gmsg provider new

Selected provider: cloudflare
Configure provider:

Enter Cloudflare account ID: <account_id>
Enter Cloudflare API token: *************************************
Enter Workers AI model ID [@cf/openai/gpt-oss-120b]:
Enter max tokens [1024]:

Provider cloudflare configured successfully!
```

## ⌨️ Commands

The following are the available commands for GPTComet:

-   `gmsg config`: Config manage commands group.
    -   `get <key>`: Get the value of a configuration key.
    -   `list`: List the entire configuration content.
    -   `reset`: Reset the configuration to default values (optionally reset only the prompt section with `--prompt`).
    -   `set <key> <value>`: Set a configuration value.
    -   `path`: Get the configuration file path.
    -   `remove <key> [value]`: Remove a configuration key or a value from a list. (List value only, like `fileignore`)
    -   `append <key> <value>`: Append a value to a list configuration.(List value only, like `fileignore`)
    -   `keys`: List all supported configuration keys.
    -   `validate`: Validate the current configuration and report issues.
-   `gmsg commit`: Generate commit message by changes/diff.
    -   `--svn`: Generate commit message for svn.
    -   `--dry-run`: Dry run the command without actually generating the commit message.
    -   `-y/--yes`: Skip the confirmation prompt.
    -   `--no-verify`: Skip git hooks verification, akin to using `git commit --no-verify`
    -   `--secrets`: Sensitive data scan mode for this run: `off`, `warn`, `redact`, or `block` (default from config).
    -   `--repo`: Path to the repository (default ".").
    -   `--answer-path`: Override answer path
    -   `--api-base`: Override API base URL
    -   `--api-key`: Override API key
    -   `--completion-path`: Override completion path
    -   `--frequency-penalty`: Override frequency penalty
    -   `--max-tokens`: Override maximum tokens
    -   `--model`: Override model name
    -   `--provider`: Override AI provider (openai/deepseek)
    -   `--proxy`: Override proxy URL
    -   `--retries`: Override retry count
    -   `--timeout`: Override request timeout in seconds
    -   `--temperature`: Override temperature
    -   `--top-p`: Override top_p value
-   `gmsg generate`: Generate a commit message from the staged diff and print only the message to stdout.
    -   `--repo`: Path to the repository (default ".").
    -   `--rich`: Generate a rich commit message with details.
    -   `--secrets`: Sensitive data scan mode for this run: `off`, `warn`, `redact`, or `block`.
    -   API override flags: `--model`, `--api-base`, `--api-key`, `--timeout`, and the other advanced flags.
-   `gmsg hook`: Manage the Git `prepare-commit-msg` hook.
    -   `install [--repo] [--force]`: Install the hook; `--force` backs up an existing hook first.
    -   `uninstall [--repo]`: Remove a gptcomet-managed hook and restore a backup.
    -   `status [--repo]`: Show the hooks directory, state, and backup.
-   `gmsg provider`: Inspect, switch, test, and add LLM providers.
    -   `list`: Show the active provider plus every provider's model and API key source.
    -   `new`: Configure a new provider interactively (replaces `gmsg newprovider`).
    -   `use <name>`: Switch the default provider; seeds defaults for a built-in provider without a config block.
    -   `test [provider]`: Send one minimal request and report connectivity, auth, latency, and a short response.
-   `gmsg newprovider`: Deprecated; use `gmsg provider new`. Kept for now; scheduled for removal in v2.14.0
    ([deprecation schedule](docs/deprecations.md)).
-   `gmsg review`: Review staged diff or pipe to `gmsg review`.
    -   `--svn`: Get diff from svn.
    -   `--stream`: Stream output as it arrives from the LLM.
    -   `--raw`: Print the raw Markdown returned by the model (no rendering or border).
    -   `--secrets`: Sensitive data scan mode for this run: `off`, `warn`, `redact`, or `block`.
    -   `--repo`: Path to the repository (default ".").
    -   `--answer-path`: Override answer path
    -   `--api-base`: Override API base URL
    -   `--api-key`: Override API key
    -   `--completion-path`: Override completion path
    -   `--frequency-penalty`: Override frequency penalty
    -   `--max-tokens`: Override maximum tokens
    -   `--model`: Override model name
    -   `--provider`: Override AI provider (openai/deepseek)
    -   `--proxy`: Override proxy URL
    -   `--retries`: Override retry count
    -   `--timeout`: Override request timeout in seconds
    -   `--temperature`: Override temperature
    -   `--top-p`: Override top_p value

Global flags:

```shell
  -c, --config string   Config file path
  -d, --debug           Enable debug mode
```

## 🪝 Git Hook

Install the hook once per repository:

```shell
gmsg hook install
gmsg hook status
```

The managed `prepare-commit-msg` hook generates a message from the staged diff before the editor
opens. It **fails open**: if gptcomet is missing, the configuration is invalid, there is no staged
diff, or the API call fails or times out, the commit message file is left unchanged and the commit
continues.

```shell
gmsg hook uninstall          # remove the managed hook
gmsg hook install --force    # back up and replace an existing hook
```

Behavior:

- Skips `git commit -m` / `-F`, merges, squash commits, and `git commit --amend`.
- Skips when the message file already has non-comment content. The all-comment template used by
  the first commit is still filled; a custom template with real content is left untouched.
- `GMSG_SKIP=1` skips the hook entirely.
- `GMSG_FORCE=1` overrides the explicit-message and existing-content skips.
- `GMSG_BIN=/path/to/gmsg` selects the binary; `GMSG_CONFIG=/path/to/config.yaml` selects the
  configuration file. `gmsg hook install -c <config>` embeds that config path in the hook.
- `gmsg hook install --force` backs up an existing hook to
  `prepare-commit-msg.gptcomet-backup`; `gmsg hook uninstall` restores it.
- The hooks directory is resolved with `git rev-parse`, so `core.hooksPath` and linked worktrees
  are respected.
- Generation is synchronous, so the editor opens after the model responds; the configured
  `<provider>.timeout` bounds the wait.
- `git commit --no-verify` does **not** skip `prepare-commit-msg`; use `GMSG_SKIP=1` instead.

To preview the exact message without committing:

```shell
gmsg generate
gmsg generate --rich
```

`generate` writes only the message to stdout; status and token-usage output goes to stderr, so it is
safe to use in scripts. See [Scripting and exit codes](#-scripting-and-exit-codes) for the full
contract.

## 🧩 Scripting and exit codes

GPTComet separates results from status so it can be used inside scripts, editor plugins, and CI:

-   **stdout carries only the result**: the commit message from `gmsg generate`, the review from
    `gmsg review` (rendered, or verbatim Markdown with `--raw`), and the previewed message from
    `gmsg commit --dry-run`.
-   **stderr carries status**: provider/model banner, progress, reminders, token usage, warnings,
    prompts, and errors. Secret-scan findings are always on stderr and are masked.

```shell
gmsg generate > commit-msg.txt          # only the message ends up in the file
gmsg review --raw > review.md           # raw model Markdown, no rendering or border
gmsg review --stream | pbcopy           # stream the review; status stays out of the pipe
git commit -F commit-msg.txt            # use the generated message directly
```

`gmsg commit` is interactive: its prompts, message previews, and commit summary stay on stderr, and
nothing is written to stdout. `--raw` only affects the non-stream review path; streamed chunks are
already unformatted.

Exit codes classify failures so scripts can distinguish them:

| Code | Meaning |
| --- | --- |
| `0` | Success |
| `1` | Unexpected or unclassified error |
| `2` | Command-line usage error (unknown flag or invalid flag value) |
| `3` | Configuration error (missing provider/API key, invalid config) |
| `4` | Network, proxy, or connection error |
| `5` | Git/VCS error, including "no staged changes" |
| `6` | API/LLM error (request rejected, response parsing, retries exhausted) |
| `7` | Validation/content error, including a diff blocked by `sensitive.mode=block` |

Scripts that only check "non-zero means failure" keep working; the fine-grained codes are for
choosing remediation or gating CI. Hook management commands (`gmsg hook install/uninstall/status`)
are human-facing and keep their current stdout output.

## ⚙ Configuration

Here's a summary of the main configuration keys:

| Key                            | Description                                                | Default Value                     |
| :----------------------------- | :--------------------------------------------------------- | :-------------------------------- |
| `provider`                     | The name of the LLM provider to use.                       | `openai`                          |
| `file_ignore`                  | A list of file patterns to ignore in the diff.             | (See [file_ignore](#file_ignore)) |
| `sensitive.mode`               | Pre-send secret scanning mode: `off`, `warn`, `redact`, or `block`. | `warn`                            |
| `sensitive.allow`              | Regex allowlist matched against a finding's secret or line; matches are ignored. | `[]`                              |
| `output.lang`                  | The language for commit message generation.                | `en`                              |
| `output.rich_template`         | The template to use for rich commit messages.              | `<title>:<summary>\n\n<detail>`   |
| `output.translate_title`       | Translate the title of the commit message.                 | `false`                           |
| `output.review_lang`           | The language to generate the review message.               | `en`                              |
| `output.markdown_theme`        | The theme to display markdown_theme content.               | `auto`                            |
| `console.verbose`              | Enable verbose output with progress indicators and detailed error messages. | `true`                            |
| `<provider>.api_base`          | The API base URL for the provider.                         | (Provider-specific)               |
| `<provider>.api_key`           | The API key for the provider.                              |                                   |
| `<provider>.model`             | The model name to use.                                     | (Provider-specific)               |
| `<provider>.retries`           | The number of retry attempts for API requests.             | `2`                               |
| `<provider>.timeout`           | Request timeout in seconds. Non-streaming calls use it as a total deadline; streaming calls use it as an idle timeout that resets whenever content arrives. | `60`                              |
| `<provider>.proxy`             | The proxy URL to use (if needed).                          |                                   |
| `<provider>.max_tokens`        | The maximum number of tokens to generate.                  | `2048`                            |
| `<provider>.top_p`             | The top-p value for nucleus sampling.                      | `0.7`                             |
| `<provider>.temperature`       | The temperature value for controlling randomness.          | `0.7`                             |
| `<provider>.frequency_penalty` | The frequency penalty value.                               | `0`                               |
| `<provider>.extra_headers`     | Extra headers to include in API requests (JSON string).    | `{}`                              |
| `<provider>.extra_body`        | Extra body to include in API requests (JSON string).       | `{}`                              |
| `<provider>.completion_path`   | The API path for completion requests.                      | (Provider-specific)               |
| `<provider>.answer_path`       | The JSON path to extract the answer from the API response. | (Provider-specific)               |
| `prompt.brief_commit_message`  | The prompt template for generating brief commit messages.  | (See `defaults/defaults.go`)      |
| `prompt.rich_commit_message`   | The prompt template for generating rich commit messages.   | (See `defaults/defaults.go`)      |
| `prompt.translation`           | The prompt template for translating commit messages.       | (See `defaults/defaults.go`)      |
| `prompt.review`                | The prompt template for reviewing code changes.            | (See `defaults/defaults.go`)      |

**Note:** `<provider>` should be replaced with the actual provider name (e.g., `openai`, `gemini`, `claude`).

Some providers require specific keys, such as Vertex needing project ID, location, etc.

The configuration file for GPTComet is `gptcomet.yaml`. The file should contain the following keys:

`output.translate_title` is used to determine whether to translate the title of the commit message.

For example in `output.lang: zh-cn`, the title of the commit message is `feat: Add new feature`

If `output.translate_title` is set to `true`, the commit message will be translated to `功能：新增功能`.
Otherwise, the commit message will be translated to `feat: 新增功能`.

In some case you can set `complation_path` to empty string, like `<provider>.completion_path: ""`, to use `api_base` endpoint directly.

### file_ignore

The file to ignore when generating a commit. The default value is

```yaml
- bun.lockb
- Cargo.lock
- composer.lock
- Gemfile.lock
- package-lock.json
- pnpm-lock.yaml
- poetry.lock
- yarn.lock
- pdm.lock
- Pipfile.lock
- "*.py[cod]"
- go.sum
- uv.lock
```

You can add more file_ignore by using the `gmsg config append file_ignore <xxx>` command.
`<xxx>` uses gitignore-style patterns:

- `*.lock` matches `a.lock` and `vendor/a.lock` (a pattern without `/` matches at any depth).
- `vendor/**` matches everything under `vendor/`, and `docs/*.md` matches only direct children of `docs/`.
- `/go.sum` matches only the repository-root `go.sum`; `go.sum` matches it at any depth.
- `build/` matches a directory named `build` and everything below it.
- `!important.lock` re-includes a file matched by an earlier pattern.

Example:

```shell
gmsg config append file_ignore "vendor/**"
gmsg config append file_ignore "!vendor/keep.go"
```

### sensitive data scanning

Before any diff is sent to a provider, GPTComet scans the **added lines** for credentials with a
lightweight engine loaded from the MIT-licensed [gitleaks](https://github.com/gitleaks/gitleaks)
rule data (222 rules, vendored under `internal/secretscan/rules/`). It never changes your staged
diff; only the text sent to the model can be rewritten.

```yaml
sensitive:
  mode: warn      # off | warn | redact | block
  allow: []       # regexes matched against the secret or the full line
```

| Mode | Behavior |
| --- | --- |
| `off` | No scanning. |
| `warn` (default) | Send the diff unchanged and print masked findings to stderr. |
| `redact` | Replace secret spans with `[REDACTED:<rule>]` before sending. |
| `block` | Send nothing and exit with a structured error. |

Sensitive file names (`.env*`, private key material, `credentials.json`, `.npmrc`, `.pypirc`,
`.netrc`) are flagged even when no per-line regex matches. Silence known false positives with
`sensitive.allow`, or a single line with a `gitleaks:allow` comment. The Git hook stays fail-open:
in `block` mode it prints the warning but does not block `git commit`.

Override the mode for one command (all commands that send a diff):

```shell
gmsg commit --secrets redact
gmsg generate --secrets off
gmsg review --secrets block
```

Not detected: secrets hidden inside base64/hex blobs, git history, or archive contents — this is a
pre-send guard, not a replacement for `gitleaks`/GitHub secret scanning in CI.

### provider

The provider configuration of the language model.

The default provider is `openai`. You can inspect and switch it with `gmsg provider list` and
`gmsg provider use <name>`, and verify the configuration with `gmsg provider test`.

Provider config just like:

```yaml
provider: openai
openai:
    api_base: https://api.openai.com/v1
    api_key: YOUR_API_KEY
    model: gpt-6.1-sol
    retries: 2
    max_tokens: 1024
    temperature: 0.7
    top_p: 0.7
    frequency_penalty: 0
    extra_headers: {}
    answer_path: choices.0.message.content
    completion_path: /chat/completions
```

If you are using `openai`, just leave the `api_base` as default. Set your `api_key` in the `config` section.

If you are using an `openai` class provider, or a provider compatible interface, you can set the provider to `openai`.
And set your custom `api_base`, `api_key` and `model`.

For example:

`Openrouter` providers api interface compatible with openai,
you can set provider to `openai` and set `api_base` to `https://openrouter.ai/api/v1`,
`api_key` to your api key from [keys page](https://openrouter.ai/settings/keys)
and `model` to `openai/gpt-6.1-sol` or some other you prefer.

```shell
gmsg config set openai.api_base https://openrouter.ai/api/v1
gmsg config set openai.api_key YOUR_API_KEY
gmsg config set openai.model openai/gpt-6.1-sol
gmsg config set openai.max_tokens 1024
```

Silicon providers the similar interface with openrouter, so you can set provider to `openai`
and set `api_base` to `https://api.siliconflow.cn/v1`.

**Note that max tokens may vary, and will return an error if it is too large.**

### output

The output configuration of the commit message.

The default output is

```yaml
output:
    lang: en
    rich_template: "<title>:<summary>\n\n<detail>"
    translate_title: false
    review_lang: "en"
    markdown_theme: "auto"
```

You can set `rich_template` to change the template of the rich commit message,
and set `lang` to change the language of the commit message.

### Markdown theme

Supported markdown theme:

-   `auto`: Auto detect markdown theme (default).
-   `ascii`: ASCII style.
-   `dark`: Dark theme.
-   `dracula`: Dracula theme.
-   `light`: Light theme.
-   `tokyo-night`: Tokyo Night theme.
-   `notty`: Notty style, no render.
-   `pink`: Pink theme.

If you not set `markdown_theme`, the markdown theme will be auto detected.
If you are using light terminal, the markdown theme will be `dark`, if you are using dark terminal, the markdown theme will be `light`.

GPTComet is using glamour to render markdown, you can preview the markdown theme in [glamour preview](https://github.com/charmbracelet/glamour/tree/master/styles/gallery#glamour-style-section).

### Supported languages

`output.lang` and `output.review_lang` support the following languages:

-   `en`: English
-   `zh-cn`: Simplified Chinese
-   `zh-tw`: Traditional Chinese
-   `fr`: French
-   `vi`: Vietnamese
-   `ja`: Japanese
-   `ko`: Korean
-   `ru`: Russian
-   `tr`: Turkish
-   `id`: Indonesian
-   `th`: Thai
-   `de`: German
-   `es`: Spanish
-   `pt`: Portuguese
-   `it`: Italian
-   `ar`: Arabic
-   `hi`: Hindi
-   `el`: Greek
-   `pl`: Polish
-   `nl`: Dutch
-   `sv`: Swedish
-   `fi`: Finnish
-   `hu`: Hungarian
-   `cs`: Czech
-   `ro`: Romanian
-   `bg`: Bulgarian
-   `uk`: Ukrainian
-   `he`: Hebrew
-   `lt`: Lithuanian
-   `la`: Latin
-   `ca`: Catalan
-   `sr`: Serbian
-   `sl`: Slovenian
-   `mk`: Macedonian
-   `lv`: Latvian

### console

The console output config.

The default console is

```yaml
console:
    verbose: true
```

When `verbose` is enabled (`true`), GPTComet provides enhanced user experience:

- **Progress Indicators**: Shows real-time progress for commit message generation and code review
  ```
  [1/2] Fetching git diff...
  ✓ Fetching git diff (0.07s)
  Discovered provider: mistral, model: codestral-latest
  [2/2] Generating message...
  ✓ Generating message (13.24s)
  ```

- **Detailed Operation Information**: Displays which provider and model are being used

- **Enhanced Error Messages**: All errors include:
  - Clear problem description
  - Specific suggestions for resolution
  - Relevant documentation links
  - Appropriate emoji indicators for quick identification

When `verbose` is disabled (`false`), GPTComet runs in silent mode with minimal output, suitable for scripting and automated workflows.

## 🔦 Supported Keys

You can use `gmsg config keys` to check supported keys.

## 📃 Example

Here is an example of how to use GPTComet:

### Basic Usage

1.  When you first set your OpenAI KEY by `gmsg config set openai.api_key YOUR_API_KEY`, it will generate config file at `~/.local/gptcomet/gptcomet.yaml`, includes:

```
provider: "openai"
openai:
  api_base: "https://api.openai.com/v1"
  api_key: "YOUR_API_KEY"
  model: "gpt-6.1-sol"
  retries: 2
output:
  lang: "en"
```

2.  Run the following command to generate a commit message: `gmsg commit`
3.  GPTComet will generate a commit message based on the changes made in the code and display it in the console.

### Enhanced Error Messages

GPTComet provides helpful error messages with actionable suggestions:

```bash
$ gmsg commit

❌ API Key Not Configured

Provider 'openai' requires an API key, but none was found.

What to do:
  • Set API key: gmsg config set openai.api_key <your-key>
  • Or set env var: export OPENAI_API_KEY=<your-key>
  • Check provider: gmsg config get openai

Docs: https://github.com/belingud/gptcomet#configuration
```

### Progress Indicators

When `console.verbose` is enabled (default), you'll see real-time progress:

```bash
$ gmsg commit

[1/2] Fetching git diff...(0.07s)
Discovered provider: mistral, model: codestral-latest
[2/2] Generating message...
📤 Sending request to mistral...
Token usage> prompt: 1341, completion: 10, total: 1,351
✓ Generating message (13.24s)

feat: add user authentication feature
```

To disable progress indicators and run in silent mode:

```bash
gmsg config set console.verbose false
```

Note: Replace `YOUR_API_KEY` with your actual API key for the provider.

## 💻 Development

### Requirements
- Go 1.25+
- Python 3.9+
- just command runner
- pytest (for Python tests)

### Setup

If you'd like to contribute to GPTComet, feel free to fork this project and submit a pull request.

First, fork the project and clone your repo.

```shell
git clone https://github.com/<yourname>/gptcomet
```

Second, make sure you have `uv`, you can install by `pip`, `brew` or other way in their [installation](https://docs.astral.sh/uv/getting-started/installation/) docs

Use `just` command to install dependencies:

```shell
just install
```

### Running Tests

#### Go Tests

```bash
# Run all Go tests
go test ./...

# Run specific package tests
go test ./internal/llm/

# Run with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Using just
just test              # Run tests with coverage
just test-coverage     # Generate coverage report
just test-cover-func   # Show coverage by function
```

#### Python Tests

```bash
# Run Python wrapper tests
just test-py

# Run with coverage
just test-py-cov

# Or manually with uv
uv run pytest tests/py_tests/ -v
uv run pytest tests/py_tests/ --cov=py/gptcomet --cov-report=html
```

### Code Quality

#### Go

```bash
# Static analysis
go vet ./...
staticcheck ./...

# Using just
just check             # Run go vet and staticcheck
just format            # Format Go code
```

#### Python

```bash
# Code linting
ruff check py/

# Formatting
ruff format py/
```

### Build

```bash
# Build Go binary
just build

# Build all platforms
just build-all

# Build Python wheel
just build-py
```

## 📩 Contact

If you have any questions or suggestions, feel free to contact.

## ☕️ Sponsor

If you like GPTComet, you can buy me a coffee to support me. Any support can help the project go further.

[Buy Me A Coffee](./SPONSOR.md)

## 📜 License

GPTComet is licensed under the MIT License.

[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fbelingud%2Fgptcomet.svg?type=large&issueType=license)](https://app.fossa.com/projects/git%2Bgithub.com%2Fbelingud%2Fgptcomet?ref=badge_large&issueType=license)
