Commitar

Commitar is a Python CLI that generates Conventional Commits messages with AI and can optionally create Git commits. Its core principle is preserving the staging area: when the index already has changes, only those changes are considered.

Portuguese documentation is available in README-PT.md.

Features

• Safe preview by default: no changes are made without --output commit.
• One-line Conventional Commit messages.
• OpenAI, Gemini, and Ollama support.
• File, directory, or whole-repository scope.
• Staging isolation, including partially staged files.
• TOML, environment-variable, and flag configuration.
• Colored feedback, a generation spinner, and elapsed time per message.
• Configurable AI timeout; the default is 60 seconds.

Requirements

• Python 3.11 or later.
• Git installed and a Git repository initialized.
• A configured AI provider:
  • OpenAI: OPENAI_API_KEY;
  • Gemini: GEMINI_API_KEY;
  • Ollama: a local service running with an installed model.

Installation

pip3 install commitar

For development, install the test dependencies too:

python -m pip install -e '.[dev]'
commitar --help

Quick start

Configure your Git identity if necessary:

git config user.name "Your Name"
git config user.email "you@example.com"

Preview tracked changes:

commitar

When there is no staging, Commitar generates a preview for each changed file. The preview lists the source, files, suggested message, and generation time.

Untracked files are ignored for safety. Include them explicitly:

commitar --include-added

Create commits after a single confirmation:

commitar src/ --output commit

For automation, skip the interaction:

commitar src/ --output commit --yes

To create one commit from files explicitly selected with git add:

git add src/moon_service.py tests/test_moon_service.py
commitar --output commit

With existing staging, Commitar exclusively uses git diff --cached, generates one message, and creates a commit containing exactly the files in the index.

Use --message to skip the AI provider call. The value must be a valid one-line Conventional Commit:

commitar app.py --include-added \
  --message "feat: add moon phase endpoint" \
  --output commit --yes

Staging safety

The behavior is deliberately conservative.

In path mode, Commitar verifies that the index remains empty before each commit. If another process changes staging, the operation stops to prevent changes from being mixed.

Command reference

commitar [OPTIONS] [PATH]
commitar config init [OPTIONS]
commitar config show [OPTIONS]

Use commitar --help and commitar config --help for current CLI details.

Configuration

Create a configuration template in the repository root:

commitar config init

Example .commitar.toml:

[ai]
provider = "ollama"
models = ["gemma4:e4b", "qwen2.5-coder:14b"]
endpoint = "http://localhost:11434/api/generate"
max_input_tokens = 12000
context_window_tokens = 32768
max_output_tokens = 80
temperature = 0.2
timeout_seconds = 60

[commit]
language = "pt-BR"
format = "conventional"
include_added = false
output = "preview"
confirm = true

[limits]
max_files_per_request = 50
max_diff_bytes = 100000

models accepts up to three models in preference order. If the AI returns an invalid message, Commitar tries the next model, for up to three attempts. model = "name" remains supported for a single model; --model takes precedence for the current run.

The configuration precedence, from highest to lowest, is: CLI flags; the --config file; COMMITAR_* environment variables; .commitar.toml in the repository root; ~/.config/commitar/config.toml; and built-in defaults.

Supported variables are COMMITAR_PROVIDER, COMMITAR_MODEL, COMMITAR_LANGUAGE, COMMITAR_OUTPUT, COMMITAR_ENDPOINT, COMMITAR_MAX_DIFF_BYTES, and COMMITAR_TIMEOUT_SECONDS.

Credentials are never read from TOML. Use OPENAI_API_KEY or GEMINI_API_KEY; Ollama normally does not need a key for local use.

AI providers

Ollama

ollama pull gemma4:e4b
ollama serve
commitar --provider ollama --model gemma4:e4b

The default endpoint is http://localhost:11434/api/generate.

OpenAI

export OPENAI_API_KEY="..."
commitar --provider openai --model gpt-5-mini

Gemini

export GEMINI_API_KEY="..."
commitar --provider gemini --model gemini-2.5-flash

Context limits

The context is controlled by four settings: max_files_per_request (maximum files per group), max_diff_bytes (maximum diff size), max_input_tokens (estimated full-prompt limit), and context_window_tokens (total input/output window).

max_input_tokens + max_output_tokens cannot exceed context_window_tokens. Input counting is a conservative estimate independent of the provider tokenizer. In Ollama, the context window is sent as num_ctx and the output limit as num_predict. OpenAI and Gemini validate the window locally before sending the output limit.

If the diff exceeds its byte or token limit, Commitar produces a deterministic summary of diff metadata. If that still exceeds a limit, the command fails explicitly; content is never silently truncated.

FastAPI example

The example/ directory contains an asynchronous FastAPI API that returns the approximate Moon phase for an ISO date:

python -m pip install fastapi uvicorn
uvicorn example.app:app --reload
curl 'http://127.0.0.1:8000/moon-phase?date=2026-07-28'
curl 'http://127.0.0.1:8000/next-moon-phase?phase=lua-cheia&from_date=2026-07-28'

/next-moon-phase accepts lua-nova, crescente, quarto-crescente, gibosa-crescente, lua-cheia, gibosa-minguante, quarto-minguante, and minguante. The calculation is an approximation based on the average synodic month.

Development and testing

Use the Makefile to standardize local tasks:

make help

make venv
make install
make check
make build

Warning: make clear is destructive to ignored files. It also removes virtual environments and local files such as .env; back up needed local data.

Troubleshooting

License

Distributed under the MIT License. A project by André Argôlo (argolo.dev).

Repository: github.com/argolo/commitar.