OpenCommit: Auto-generate meaningful commits in a second

OpenCommit: Auto-generate meaningful commits in a second

A practical deep-dive into transforming your commit messages with AI

OpenCommit is a CLI tool designed to replace the dreaded “lame commits” with meaningful, well-described messages generated by AI. In a few seconds, you can stage changes and have a high-quality commit message crafted for you, often with an appealing GitMoji prefix and context-aware description. This guide walks you through what OpenCommit is, how it works, how to set it up, and how to leverage its most powerful features—from local model hosting to Git hooks and GitHub Actions. To illustrate, you’ll see examples and embedded visuals from the project input.

Table of contents

• What OpenCommit is and why it exists
• Core features at a glance
• Getting started: installation and first setup
• Using OpenCommit: your day-to-day workflow
• Running OpenCommit with local models
• Ollama
• llama.cpp
• Troubleshooting common model issues
• Advanced configuration and personalization
• Emoji and GitMoji
• Message templates and placeholders
• WHY the changes were done (OCO_WH Y)
• Localization and language support
• Global vs local configuration
• Special integrations and workflows
• Git hooks: the killer feature
• GitHub Actions: OpenCommit in your CI/CD
• Commitlint integration
• Model management and providers
• OpenAI and other providers
• Proxies and network considerations
• Security, cost considerations, and best practices
• A practical example workflow
• Frequently asked questions

What OpenCommit is and why it exists

OpenCommit is a command-line interface (CLI) tool that automates the generation of meaningful commit messages for staged changes. It leverages powerful language models to analyze your changes and produce concise, descriptive commits. The project emphasizes configurability: you can tailor emojis, descriptions, and even the underlying model to fit your team’s conventions. The aim is to save time, reduce guesswork, and foster clearer project history—without sacrificing your preferred style or workflow.

Key features at a glance

• AI-generated commit messages with customizable descriptions and GitMoji prefixes
• Flexible model providers: OpenAI and alternatives such as Ollama or llama.cpp via local endpoints
• Per-repo and global configuration with a clear priority order
• Optional “why” descriptions to explain the rationale behind changes
• Full control over the commit flow: pre-commit hooks, prompts, and push behavior
• Git hooks that integrate directly with your IDE or VCS workflow
• GitHub Action for automatic message improvement on pushes
• Fine-grained ignore rules and a dedicated ignore file for large artifacts
• Message templating with a placeholder system to inject dynamic content
• Local model hosting options to reduce API calls and latency

Getting started: installation and first setup

To begin, install OpenCommit globally in any repository you work in:

• npm install -g opencommit

Next, obtain an API key from your preferred LLM provider (OpenAI is the default, but the project supports others). Ensure your account has payment details configured so requests can be fulfilled.

Set your API key in the OpenCommit configuration:

• oco config set OCOAPIKEY=YOURAPIKEY

OpenCommit stores its local configuration in the ~/.opencommit directory, so your credentials and preferences stay under your control.

Your everyday workflow with OpenCommit

• Stage your changes as usual, or let OpenCommit stage them for you:
• git add oco
• oco
• OpenCommit generates a commit message for your staged changes and commits them. It supports the standard git flags, so you can include --no-verify or use a custom message template. If you want to skip the manual confirmation step, you can add the flag:
• oco --yes

A simple day-to-day flow looks like:

• Make changes
• git add .
• oco
• (Optionally) git push

Running locally with Ollama (local models)

If you prefer running a local model through Ollama, you can use a setup that keeps model ingestion inside your network, reducing external API usage. Here’s a streamlined path:

• Install and start Ollama
• Run ollama run mistral to pull the model (one-time setup)
• In your project directory, set:
• git add oco
• oco config set OCOAIPROVIDER='ollama'
• OCO_MODEL='llama3:8b' Default model for local runs is mistral, but you can switch to others as you see fit.

If your Ollama endpoint uses a different host/port, adjust the API URL accordingly:

• oco config set OCOAPIURL='http://192.168.1.10:11434/api/chat'

Troubleshooting Ollama IPv6/IPv4 connections

A common issue is ECONNREFUSED on IPv6. If you encounter this:

• Set the Ollama host to listen on all interfaces:
• export OLLAMA_HOST=0.0.0.0
• Add this to your shell profile to persist across sessions.

Running locally with llama.cpp

For even more local control, you can run a server provided by llama.cpp:

• Build and run the server with a GGUF model:
• ./llama-server -m model.gguf --port 8080
• Then configure OpenCommit to use this local endpoint:
• oco config set OCOAIPROVIDER='llamacpp'
• OCOAPIURL='http://localhost:8080' If your server is on another machine, set the URL to that machine’s endpoint, e.g.:
• oco config set OCOAPIURL='http://192.168.1.10:8080'

A robust set of flags to customize behavior

• Use Full GitMoji Specification: Link to GitMoji (https://gitmoji.dev/). The full spec can be enabled if OCO_EMOJI is true and you pass the --fgm flag:
• oco --fgm
• Skip commit confirmation: oco --yes

Configuration: local vs global, and how they interact

OpenCommit supports both per-repo (local) configurations and global configurations that apply across repositories:

• Local per-repo configuration is stored in a .env file within the repository
• Global configuration is stored in ~/.opencommit and can be managed with oco config
• Local config takes precedence over global config, but you can set OCOMODEL and OCOLOCALE globally and override OCOEMOJI and OCODESCRIPTION per repo for convenience

A quick peek at useful config commands

• Describe available parameters and accepted values:
• oco config describe
• See details for a specific parameter:
• oco config describe OCO_MODEL
• Change locale/language globally:
• oco config set OCO_LANGUAGE=de
• oco config set OCO_LANGUAGE=German
• Turn on/off GitMoji:
• oco config set OCO_EMOJI=true
• oco config set OCO_EMOJI=false

Output customization: why the changes were done (OCOWHY) OpenCommit can optionally output a short description of why changes were made after the commit message. This is labeled OCOWHY and is currently a work in progress (WIP). To enable it:

• oco config set OCO_WHY=true

Model selection and management

• By default, OpenCommit uses gpt-4o-mini, but you can switch to gpt-4o for better performance (at a higher cost):
• oco config set OCO_MODEL=gpt-4o
• For a cheaper option, you can select:
• oco config set OCO_MODEL=gpt-3.5-turbo
• OpenCommit automatically fetches available models from your provider when you run oco setup and caches models for 7 days to minimize API calls
• To see available models for your current provider:
• oco models
• Refresh the model list after new releases:
• oco models --refresh
• To view models for a specific provider:
• oco models --provider anthropic

Switching providers and using custom URLs

OpenCommit can operate with multiple LLM providers and even custom endpoints:

• Default: OpenAI
• Other examples: Azure OpenAI Service, Flowise, Ollama, llama.cpp
• Examples:
• oco config set OCOAIPROVIDER=azure
• OCOAPIKEY=
• OCOAPIURL=
• oco config set OCOAIPROVIDER=flowise
• OCOAPIURL=
• oco config set OCOAIPROVIDER=ollama
• OCOAPIURL=
• oco config set OCOAIPROVIDER=llamacpp
• OCOAPIURL= If you’re behind a proxy, configure:
• oco config set OCOPROXY=http://127.0.0.1:7890 If OCOPROXY is unset, OpenCommit will try HTTPSPROXY or HTTPPROXY environment variables. To disable the proxy explicitly:
• oco config set OCO_PROXY=null

Language localization: global language support

OpenCommit supports many languages. Globally configure the language you want OpenCommit to use for generated messages:

• oco config set OCO_LANGUAGE=de
• oco config set OCO_LANGUAGE=German
• oco config set OCO_LANGUAGE=fr
• oco config set OCO_LANGUAGE=French The default language is English. A full list of available languages is in the i18n folder of the repository.

Push to git (historical note)

There used to be a push prompt by default; you can turn it off if you don’t want OpenCommit to prompt to push after a commit:

• oco config set OCO_GITPUSH=false

Commit message module options

OpenCommit can generate conventional-commit messages by default, but you can switch to the @commitlint module for a different style. Configure the module with:

• oco config set OCOPROMPTMODULE=@commitlint To switch back:
• oco config set OCOPROMPTMODULE=conventional-commit Integration with @commitlint If you’re using @commitlint, OpenCommit automatically integrates the first time you run with OCOPROMPTMODULE set to @commitlint. You can:
• oco commitlint force
• oco commitlint get OpenCommit also creates a local file named .opencommit-commitlint that contains the prompts used for the local @commitlint configuration. You can modify this file to tailor the generated messages to your project’s conventions. If the local configuration changes, the file will be updated the next time you run OpenCommit.

Git hook: the killer feature

One of the most popular capabilities is the Git hook integration. OpenCommit can hook into Git’s prepare-commit-msg hook, so you have a chance to edit the message before it’s saved:

• Set the hook: oco hook set
• Unset the hook: oco hook unset
• To use the hook in a regular workflow: git add and git commit will automatically involve OpenCommit

Setup OpenCommit as a GitHub Action (BETA)

OpenCommit can enhance commit messages automatically on pushes via a GitHub Action. This is particularly valuable for teams that want a uniform, meaningful history across branches. To use it, create a workflow file at .github/workflows/opencommit.yml with the following structure (example shown in the input):

• name: 'OpenCommit Action'
• on:
• push
• branches-ignore: [main, master, dev, development, release]
• jobs:
• opencommit:
  • timeout-minutes: 10
  • name: OpenCommit
  • runs-on: ubuntu-latest
  • permissions: write-all
  • steps:
  • name: Setup Node.js Environment uses: actions/setup-node@v2 with: node-version: '16'
  • uses: actions/checkout@v3 with: fetch-depth: 0
  • uses: di-sukharev/[email protected] with: GITHUBTOKEN: ${{ secrets.GITHUBTOKEN }} env: OCOAPIKEY: ${{ secrets.OCOAPIKEY }} OCOTOKENSMAXINPUT: 4096 OCOTOKENSMAXOUTPUT: 500 OCOOPENAIBASEPATH: '' OCODESCRIPTION: false OCOEMOJI: false OCOMODEL: gpt-4o OCOLANGUAGE: en OCOPROMPT_MODULE: conventional-commit

The benefit is clear: every new commit in the specified branches is enhanced by AI, reducing the risk of mundane messages slipping into the history. Just be mindful of the interactive rebase caveat: if you rebase, the SHAs will change, which can matter for collaboration with others.

Payments and cost considerations

OpenCommit handles the bill for your OpenAI API usage directly with your chosen provider. The default OpenAI model is gpt-4o mini, and the project suggests that typical usage should not exceed about $0.10 per day for casual use. You can switch to higher-performance models like gpt-4 (or gpt-4o) for better results, with corresponding cost increases. Always monitor your usage and adjust models and token limits to fit your budget.

A practical example workflow: putting it all together

• Install and configure:
• npm install -g opencommit
• oco config set OCOAPIKEY=your_key
• oco config set OCO_MODEL=gpt-4o
• oco config set OCO_LANGUAGE=en
• Stage your changes:
• git add .
• Generate and commit:
• oco
• If you want to enforce a fuller workflow with more control:
• oco --yes
• oco --fgm
• When using local models:
• ollama run mistral
• oco config set OCOAIPROVIDER='ollama'
• oco config set OCO_MODEL='llama3:8b'

Best practices and caveats

• Always review the generated message before pushing, especially if you use the --yes flag.
• Be mindful of the licensing and data-ownership implications of using external LLM providers.
• Use the ignore mechanism to prevent large artifacts from being uploaded to the model service:
• Create a .opencommitignore with patterns such as:
  • path/to/large-asset.zip
  • */.jpg
• By default, OpenCommit ignores -lock. and *.lock files to prevent unnecessary uploads.
• If you rely on local servers (ollama or llama.cpp), ensure they are properly secured and accessible only within your trusted network.

A practical look at why teams love OpenCommit

• It streamlines the development process by removing the guesswork around commit messages.
• It improves project history readability, making it easier to understand why changes were made.
• The flexibility to switch between providers, run locally, or use a CI workflow makes it a versatile tool for various environments.
• The ability to tailor the exact format of the commit message—through placeholders, message templates, and the optional “why” section—lets teams align their commits with established guidelines.

Conclusion

OpenCommit positions itself as a practical, configurable solution to a ubiquitous problem: lame, hard-to-understand commits. By combining AI-powered message generation with a broad set of customization options, it lets developers maintain a meaningful and searchable history without sacrificing speed or convenience. Whether you want to run AI locally with Ollama or llama.cpp, or rely on a cloud provider, OpenCommit offers a path to more expressive commits while keeping your workflow fast and familiar. The Git hook integration and GitHub Action beta expand its reach from local repositories to automated CI/CD pipelines, ensuring that meaningful messages accompany every change across your project.

Images referenced from the input

• OpenCommit branding:
• Example commit generation:

If you’re ready to elevate your commit history and reduce “lame” messages, OpenCommit provides a robust, flexible, and well-documented path to AI-assisted, meaningful commits. Try it in your next project, and you might find yourself writing better messages with less effort—and that’s a win for you and your team.