Describe Commit

describe-commit is a CLI tool that leverages AI to generate commit messages based on changes made in a Git repository. Currently, it supports the following AI providers:

• OpenAI ChatGPT
• Google Gemini
• OpenRouter
• Anthropic (Claude/Sonnet)

It also allows users to select the desired model for content generating.

🦾 tl;dr

Turn this	Into this

Without any manual effort (there's no time to write commit messages, lazy developers unite)!

🔥 Features list

• Generates meaningful commit messages using AI
• Supports different AI providers
• Can generate short commit messages (subject line only)
• Optionally includes emojis (🐛✨📝🚀✅♻️⬆️🔧🌐💡) in commit messages
• Takes the commit history into account for better context
• Supports custom API base URLs - connect to self-hosted or OpenAI-compatible endpoints (e.g., Ollama, LM Studio)
• Runs as a standalone binary (only installed git is required)
• Available for Linux, macOS, Windows, and as a Docker image

[!NOTE] Under the hood, this app does two things before returning the generated commit message:

• Retrieves the git diff (and git log optionally) for the specified directory
• Sends this diff to the AI provider with the provided special prompt

Please keep in mind that when working with proprietary code, some parts of the code will be sent to the AI provider. You should ensure that this is permitted by your company's policy. Additionally, make sure that the AI provider does not store your data (or stores it securely).

The author of this tool is not responsible for any data leaks or security issues.

🧩 Installation

📦 Debian/Ubuntu-based (.deb) systems

Execute the following commands in order:

# setup the repository automatically
curl -1sLf https://dl.cloudsmith.io/public/tarampampam/describe-commit/setup.deb.sh | sudo -E bash

# install the package
sudo apt install describe-commit

sudo apt remove describe-commit
rm /etc/apt/sources.list.d/tarampampam-describe-commit.list

📦 RedHat (.rpm) systems

# setup the repository automatically
curl -1sLf https://dl.cloudsmith.io/public/tarampampam/describe-commit/setup.rpm.sh | sudo -E bash

# install the package
sudo dnf install describe-commit # RedHat, CentOS, etc.
sudo yum install describe-commit # Fedora, etc.
sudo zypper install describe-commit # OpenSUSE, etc.

# RedHat, CentOS, Fedora, etc.
sudo dnf remove describe-commit
rm /etc/yum.repos.d/tarampampam-describe-commit.repo
rm /etc/yum.repos.d/tarampampam-describe-commit-source.repo

# OpenSUSE, etc.
sudo zypper remove describe-commit
zypper rr tarampampam-describe-commit
zypper rr tarampampam-describe-commit-source

📦 Alpine Linux

# bash is required for the setup script
sudo apk add --no-cache bash

# setup the repository automatically
curl -1sLf https://dl.cloudsmith.io/public/tarampampam/describe-commit/setup.alpine.sh | sudo -E bash

# install the package
sudo apk add describe-commit

sudo apk del describe-commit
$EDITOR /etc/apk/repositories # remove the line with the repository

📦 AUR (Arch Linux)

There are three packages available in the AUR:

• Build from source: describe-commit
• Precompiled: describe-commit-bin
• Unstable: describe-commit-git

pamac build describe-commit

pacman -Rs describe-commit

📦 Binary (Linux, macOS, Windows)

Download the latest binary for your architecture/OS from the releases page. For example, to install the latest version to the /usr/local/bin directory on an amd64 system (e.g., Debian, Ubuntu), you can run:

# download and install the binary
curl -SsL \
  https://github.com/tarampampam/describe-commit/releases/latest/download/describe-commit-linux-amd64.gz | \
  gunzip -c | sudo tee /usr/local/bin/describe-commit > /dev/null

# make the binary executable
sudo chmod +x /usr/local/bin/describe-commit

sudo rm /usr/local/bin/describe-commit

[!TIP] Each release includes binaries for linux, darwin (macOS) and windows (amd64 and arm64 architectures). You can download the binary for your system from the releases page (section Assets). And - yes, all what you need is just download and run single binary file.

📦 Docker image

Also, you can use the Docker image:

[!NOTE] It’s recommended to avoid using the latest tag, as major upgrades may include breaking changes. Instead, use specific tags in :X.Y.Z or only :X format for version consistency.

⚙ Configuration

You can configure describe-commit using a YAML file. Refer to this example for available options.

You can specify the configuration file's location using the --config-file option. By default, however, the tool searches for the file in the user's configuration directory:

• Linux: ~/.config/describe-commit.yml
• Windows: %APPDATA%\describe-commit.yml
• macOS: ~/Library/Application Support/describe-commit.yml

Configuration Options Priority

Configuration options are applied in the following order, from highest to lowest priority:

1. Command-line options (e.g., --ai-provider, --openai-api-key, etc.)
2. Environment variables (e.g., GEMINI_API_KEY, OPENAI_MODEL_NAME, etc.)
3. A configuration file in the working directory or any parent directory, up to the root (the file can be named .describe-commit.yml or describe-commit.yml)
4. A configuration file in the user's configuration directory (e.g., ~/.config/describe-commit.yml for Linux)

This means you can store API tokens and other default settings in the global user's configuration file and override them with command-line options or a configuration file in the working directory when needed (e.g., enabling emojis only for specific projects, disable commits history analysis, etc.).

🚀 Use Cases (usage examples)

☝ Commit the changes using an AI-generated commit message in a single command

git commit -m "$(describe-commit)"

A Git repository must be initialized in the specified directory, and git must be installed on your system. Additionally, ensure that changes are staged (git add -A) before running the tool.

☝ Integration with the git

Add this alias to your ~/.gitconfig file:

[alias]
  # Stage all changes and commit them with a generated message
  wip = "!f() { git add -Av && git commit -m \"$(describe-commit)\"; }; f"

Now, in any repository, you can simply run:

git wip

And voilà! All changes will be staged and committed with a generated message.

describe-commit /path/to/repo

docs: Add initial README with project description

This commit introduces the initial README file, providing a comprehensive
overview of the `describe-commit` project. It includes a project description,
features list, installation instructions, and usage examples.

- Provides a clear introduction to the project
- Guides users through installation and basic usage
- Highlights key features and functionalities

describe-commit /path/to/repo > /path/to/commit-message.txt

describe-commit --ai openai --openai-api-key "your-openai-api-key"

docs(README): Update project description and installation instructions

Enhanced the README file to provide a clearer project overview and detailed installation instructions. The
changes aim to improve user understanding and accessibility of the `describe-commit` CLI tool.

- Added project description and AI provider support
- Included features list for better visibility
- Updated installation instructions with binary and Docker options
- Provided usage examples for generating commit messages

describe-commit --ai gemini --gemini-api-key "your-gemini-api-key"

describe-commit \
  --ai openai \
  --openai-base-url "http://localhost:11434" \
  --openai-model-name "llama3.2" \
  --openai-api-key "ollama"

describe-commit -s -e

📝 docs(README): Update project description and installation instructions

💻 Command line interface

Description:
   This tool leverages AI to generate commit messages based on changes made in a Git repository.

Usage:
   describe-commit [<options>] [<git-dir-path>]

Version:
   0.0.0@undefined

Options:
   --config-file="…", -c="…"                        Path to the configuration file (default: depends/on/your-os/describe-commit.yml) [$CONFIG_FILE]
   --short-message-only, -s                         Generate a short commit message (subject line) only [$SHORT_MESSAGE_ONLY]
   --commit-history-length="…", --cl="…", --hl="…"  Number of previous commits from the Git history (0 = disabled) (default: 20) [$COMMIT_HISTORY_LENGTH]
   --enable-emoji, -e                               Enable emoji in the commit message [$ENABLE_EMOJI]
   --max-output-tokens="…"                          Maximum number of tokens in the output message (default: 500) [$MAX_OUTPUT_TOKENS]
   --retry-attempts="…"                             Maximum number of retry attempts on retryable API errors (0 = unlimited retries) (default: 5) [$RETRY_ATTEMPTS]
   --retry-delay="…"                                Delay between retry attempts (e.g. 1s, 500ms) (default: 1s) [$RETRY_DELAY]
   --ai-provider="…", --ai="…"                      AI provider name (gemini|openai|openrouter|anthropic) (default: gemini) [$AI_PROVIDER]
   --gemini-api-key="…", --ga="…"                   Gemini API key (https://aistudio.google.com/app/api-keys, as of February 2025 it's free) [$GEMINI_API_KEY]
   --gemini-model-name="…", --gm="…"                Gemini model name (https://ai.google.dev/gemini-api/docs/models) (default: gemini-2.5-flash) [$GEMINI_MODEL_NAME]
   --gemini-base-url="…"                            Gemini API base URL (overrides the default endpoint) [$GEMINI_BASE_URL]
   --openai-api-key="…", --oa="…"                   OpenAI API key (https://platform.openai.com/api-keys, you need to add funds to your account) [$OPENAI_API_KEY]
   --openai-model-name="…", --om="…"                OpenAI model name (https://developers.openai.com/api/docs/models) (default: gpt-4.1-nano) [$OPENAI_MODEL_NAME]
   --openai-base-url="…"                            OpenAI API base URL (use to connect to OpenAI-compatible endpoints, e.g. Ollama) [$OPENAI_BASE_URL]
   --openrouter-api-key="…", --ora="…"              OpenRouter API key (https://openrouter.ai/workspaces/default/keys) [$OPENROUTER_API_KEY]
   --openrouter-model-name="…", --orm="…"           OpenRouter model name (https://openrouter.ai/models) (default: google/gemma-4-31b-it:free) [$OPENROUTER_MODEL_NAME]
   --openrouter-base-url="…"                        OpenRouter API base URL (overrides the default endpoint) [$OPENROUTER_BASE_URL]
   --anthropic-api-key="…", --ana="…"               Anthropic API key (https://platform.claude.com/settings/keys) [$ANTHROPIC_API_KEY]
   --anthropic-model-name="…", --anm="…"            Anthropic model name (https://platform.claude.com/docs/en/about-claude/models/overview) (default: claude-haiku-4-5-20251001) [$ANTHROPIC_MODEL_NAME]
   --anthropic-base-url="…"                         Anthropic API base URL (overrides the default endpoint) [$ANTHROPIC_BASE_URL]
   --help, -h                                       Show help
   --version, -v                                    Print the version

📜 License

This is open-sourced software licensed under the MIT License.