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:

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

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

Command-line options (e.g., --ai-provider, --openai-api-key, etc.)
Environment variables (e.g., GEMINI_API_KEY, OPENAI_MODEL_NAME, etc.)
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)
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.

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

☝ Use a local model via Ollama (or any OpenAI-compatible endpoint)

Any provider that speaks the OpenAI chat-completions API (Ollama, LM Studio, vLLM, etc.) can be used by pointing the --openai-base-url flag at the local server and selecting the openai provider:

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

The --openai-api-key value is ignored by Ollama but is required by the flag parser, so any non-empty string works.

The same --<provider>-base-url option is available for all four providers (gemini, openai, openrouter, anthropic), or you can set it via the corresponding environment variable (OPENAI_BASE_URL, GEMINI_BASE_URL, etc.) or through the baseUrl field in the configuration file.

☝ 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]
   --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

🧠 A note on AI-assisted development

AI tools are great assistants - they can autocomplete, review, summarize, and help you move faster. But they’re not a substitute for understanding what's going on. If you're using AI to contribute here, please make sure you actually read, understand, and stand behind the changes you’re proposing.

I personally write my code myself, and I encourage others to do the same. Not because AI is "bad", but because blindly trusting generated code tends to produce... let's say creative results.

And honestly, I'm still waiting for the day "AI-free software" becomes a trend - like organic food, but for code 😄 Until then: trust, but verify.

🤖 AI Agent Instructions

See AGENTS.md for detailed guidelines for AI agents working with this repository.

📜 License

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Describe Commit

🦾 tl;dr

🔥 Features list

🧩 Installation

📦 Debian/Ubuntu-based (.deb) systems

📦 RedHat (.rpm) systems

📦 Alpine Linux

📦 AUR (Arch Linux)

📦 Binary (Linux, macOS, Windows)

📦 Docker image

⚙ Configuration

Configuration Options Priority

🚀 Use Cases (usage examples)

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

☝ Integration with the git

💻 Command line interface

🧠 A note on AI-assisted development

🤖 AI Agent Instructions

📜 License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Describe Commit

🦾 tl;dr

🔥 Features list

🧩 Installation

📦 Debian/Ubuntu-based (.deb) systems

📦 RedHat (.rpm) systems

📦 Alpine Linux

📦 AUR (Arch Linux)

📦 Binary (Linux, macOS, Windows)

📦 Docker image

⚙ Configuration

Configuration Options Priority

🚀 Use Cases (usage examples)

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

☝ Integration with the git

💻 Command line interface

🧠 A note on AI-assisted development

🤖 AI Agent Instructions

📜 License