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

Uninstalling

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.

Uninstalling

# 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

Uninstalling

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

Uninstalling

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

Uninstalling

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:

Registry	Image
GitHub Container Registry	ghcr.io/tarampampam/describe-commit

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.

Example

docker run --rm \
  -u "$(id -u):$(id -g)" \                                # to avoid problems with permissions
  -v "$HOME/.config/describe-commit.yml:/config.yml:ro" \ # use your configuration file
  -v "$(pwd):/rootfs:ro" \                                # mount current directory as read-only
  -e "CONFIG_FILE=/config.yml" \                          # specify the configuration file path
  -w "/rootfs" \                                          # set the working directory
    ghcr.io/tarampampam/describe-commit ...

⚙ 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: ~/.configs/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., ~/.configs/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.

☝ Get a Commit Message for a Specific Directory

describe-commit /path/to/repo

Example output:

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

You are able to save the output to a file:

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

Or do wherever you want with it.

☝ Switch Between AI Providers

Generate a commit message using OpenAI:

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

Will output something like this:

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

But if you want to use Gemini instead:

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

☝ Generate a short commit message (only the first line) with emojis

describe-commit -s -e

Will give you something like this:

📝 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]
   --ai-provider="…", --ai="…"                      AI provider name (gemini|openai|openrouter|anthropic) (default: gemini) [$AI_PROVIDER]
   --gemini-api-key="…", --ga="…"                   Gemini API key (https://bit.ly/4jZhiKI, as of February 2025 it's free) [$GEMINI_API_KEY]
   --gemini-model-name="…", --gm="…"                Gemini model name (https://bit.ly/4i02ARR) (default: gemini-2.0-flash) [$GEMINI_MODEL_NAME]
   --openai-api-key="…", --oa="…"                   OpenAI API key (https://bit.ly/4i03NbR, you need to add funds to your account) [$OPENAI_API_KEY]
   --openai-model-name="…", --om="…"                OpenAI model name (https://bit.ly/4hXCXkL) (default: gpt-4o-mini) [$OPENAI_MODEL_NAME]
   --openrouter-api-key="…", --ora="…"              OpenRouter API key (https://bit.ly/4hU1yY1) [$OPENROUTER_API_KEY]
   --openrouter-model-name="…", --orm="…"           OpenRouter model name (https://bit.ly/4ktktuG) (default: nvidia/llama-3.1-nemotron-70b-instruct:free) [$OPENROUTER_MODEL_NAME]
   --anthropic-api-key="…", --ana="…"               Anthropic API key (https://bit.ly/4klw0Mw) [$ANTHROPIC_API_KEY]
   --anthropic-model-name="…", --anm="…"            Anthropic model name (https://bit.ly/4bmQDDV) (default: claude-3-7-sonnet-20250219) [$ANTHROPIC_MODEL_NAME]
   --help, -h                                       Show help
   --version, -v                                    Print the version

📜 License

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