Better Git Commit Messages with cai. Bringing AI into the Workflow

Using git and LLM

If you were forced to choose the single most important Git command, the answer would probably be git commit. It creates a snapshot of the current state of your code base and records it as part of the project history. In practice, this command is very often used in the following way:

git commit -m "Some text"

This is acceptable in certain situations, for example when a linter has reformatted the code and the message clearly states something like “format linted”. Unfortunately, it is also common to see commit messages such as “bug fixed” or “file abc adjusted”. In reality, there may have been several bugs, the file may exist in multiple locations, or it may have been modified repeatedly. Such messages provide little value over time.

Writing meaningful commit messages is a crucial part of a healthy development workflow. For that reason, the inline message option should generally be avoided. Instead, simply run:

git commit

This opens the editor configured as the default for Git, allowing you to write the commit message. Saving and closing the editor confirms the message and finalises the commit. This is the place and the moment to write a proper commit message, and to consciously think about what has changed and why the change was necessary.

Over the years, I have observed that fewer developers, including myself, follow this practice. One reason is the perceived effort required to write good commit messages, especially when another well known rule is ignored: commit small and often. Instead of small, focused commits, many developers produce large or very large commits once per day, per week, or even per sprint.

Today, almost everyone who uses Git also relies on large language models. These tools are commonly used for exploratory coding and are increasingly used to generate well written commit messages. This is typically done by copying changes into tools such as ChatGPT, Gemini, and similar systems, or by using utilities that generate messages based on the output of git diff.

There are many such tools available. However, none that I have encountered fully meets my requirements. I apologise to anyone who has built a tool that does. If so, I was simply unable to find it.

I want a tool that fulfills the following requirements:

1. Usage like a native Git command, starting with git followed by a short subcommand
2. Easy installation
3. Support for different large language models from multiple providers
4. A meaningful commit message opened directly in the editor
5. The generated message must be editable and it must be possible to reject it by closing the editor without saving
6. The ability to generate commit messages in different languages
7. Option to write messages in different tone styles
8. Global configuration at user level, with the option to use different settings, providers, models, and tokens for each repository
9. An ignore file that excludes certain tracked files and directories from being taken into account when generating commit messages

Such a tool would encourage good Git practices while taking advantage of modern language models, without reducing developer control or intent.

cai in Practice

To address the issues described above, I built a tool myself and released it as open source. It is called cai, and it may be useful to others facing the same challenges.

The tool can be installed directly from source by cloning the repository from GitHub and build the python package:

git clone https://github.com/thorstenfoltz/cai.git

An easier and recommended approach is installation from PyPI using pipx:

pipx git-cai-cli

After installation, ensure that the pipx binary directory is available on your PATH and restart your shell:

pipx ensurepath 

If you are using Arch Linux or an Arch based distribution such as EndeavourOS or CachyOS, cai is also available via the AUR and can be installed using a package manager such as paru or yay:

paru -S cai

Once installed, the tool is ready to use. Execute it inside any Git repository:

git cai

On first execution, cai creates two files in your home directory under .config/cai:

1. cai_config.yml for configuration
2. tokens.yml for API tokens

The default provider is Groq, as it offers a free tier and fast response times. Currently, the following providers are supported:

• Anthropic
• Deepseek
• Gemini
• Groq
• Mistral
• OpenAI
• xAI

All providers require an API token. In cai_config.yml, you select the provider by setting it as the default. Within the chosen provider configuration, you can specify the model, the temperature value, typically between zero and two, which controls how creative the responses are, the language for the commit message, the tone style, whether emojis are allowed, and the path to the token file.

By default, cai uses the configuration in your home directory. However, it first looks for a configuration file at the root of the current repository. This allows you to define different providers, models, or token files per repository. This is particularly useful when working for different companies where separate API tokens are required. Don’t forget: token files should never be committed to a repository! If no repository specific configuration is found, cai falls back to the global configuration in your home directory.

To use cai in practice, make your changes, stage them using git add, and then run:

git cai

The editor opens with a pre-filled commit message generated from the staged changes. You can adjust the message as needed and save it to create the commit. Closing the editor without saving aborts the commit.

Regarding file exclusions, everything listed in .gitignore is ignored automatically. If you want to exclude tracked files or directories from being considered when generating commit messages, create a .caiignore file and use it in the same way as .gitignore.

In addition to the default behaviour, several command line options are available. You can consult the manual page:

man git cai

or display a short overview with:

git cai -h

Some useful examples include the following.

To stage already tracked files and commit them in one step:

git cai -a

To display a list of supported writing styles:

git cai -l style

To squash all commits in the current branch back to its starting point and generate a summarised commit message:

git cai -s

Finally, it is worth noting that every provider enforces token limits. For that reason alone, it remains in your own interest to follow the principle of committing small and often.