opencommit

Auto-generate meaningful commits in a second

Killing lame commits with AI

Winner of GitHub 2023 hackathon

--- All the commits in this repo are authored by OpenCommit — look at [the commits](https://github.com/di-sukharev/opencommit/commit/eae7618d575ee8d2e9fff5de56da79d40c4bc5fc) to see how OpenCommit works. Emojis and long commit descriptions are configurable, basically everything is. ## Setup OpenCommit as a CLI tool You can use OpenCommit by simply running it via the CLI like this `oco`. 2 seconds and your staged changes are committed with a meaningful message. 1. Install OpenCommit globally to use in any repository: ```sh npm install -g opencommit ``` 2. Get your API key from [OpenAI](https://platform.openai.com/account/api-keys) or other supported LLM providers (we support them all). Make sure that you add your OpenAI payment details to your account, so the API works. 3. Set the key to OpenCommit config: ```sh oco config set OCO_API_KEY= ``` Your API key is stored locally in the `~/.opencommit` config file. ## Usage You can call OpenCommit with `oco` command to generate a commit message for your staged changes: ```sh git add oco ``` Running `git add` is optional, `oco` will do it for you. ### Running locally with Ollama You can also run it with local model through ollama: - install and start ollama - run `ollama run mistral` (do this only once, to pull model) - run (in your project directory): ```sh git add oco config set OCO_AI_PROVIDER='ollama' OCO_MODEL='llama3:8b' ``` Default model is `mistral`. If you have ollama that is set up in docker/ on another machine with GPUs (not locally), you can change the default endpoint url. You can do so by setting the `OCO_API_URL` environment variable as follows: ```sh oco config set OCO_API_URL='http://192.168.1.10:11434/api/chat' ``` where 192.168.1.10 is example of endpoint URL, where you have ollama set up. #### Troubleshooting Ollama IPv6/IPv4 Connection Fix If you encounter issues with Ollama, such as the error ```sh ✖ local model issues. details: connect ECONNREFUSED ::1:11434 ``` It's likely because Ollama is not listening on IPv6 by default. To fix this, you can set the OLLAMA_HOST environment variable to 0.0.0.0 before starting Ollama: ```bash export OLLAMA_HOST=0.0.0.0 ``` This will make Ollama listen on all interfaces, including IPv6 and IPv4, resolving the connection issue. You can add this line to your shell configuration file (like `.bashrc` or `.zshrc`) to make it persistent across sessions. ### Running locally with llama.cpp You can run OpenCommit with local models served by [llama.cpp](https://github.com/ggerganov/llama.cpp): - install and build llama.cpp - start the server with a GGUF model: `./llama-server -m model.gguf --port 8080` - run (in your project directory): ```sh git add oco config set OCO_AI_PROVIDER='llamacpp' OCO_API_URL='http://localhost:8080' ``` If the server is running on a different machine, set the URL accordingly: ```sh oco config set OCO_API_URL='http://192.168.1.10:8080' ``` ### Flags There are multiple optional flags that can be used with the `oco` command: #### Use Full GitMoji Specification Link to the GitMoji specification: https://gitmoji.dev/ This flag enables GitMoji and allows users to use all emojis in the GitMoji specification. Without the flag, `OCO_EMOJI=true` uses a shorter set of 10 emojis (✨✅♻️⬆️) to limit the number of tokens sent in each request. This is due to limit the number of tokens sent in each request. However, if you would like to use the full GitMoji specification, you can use the `--fgm` flag. ``` oco --fgm ``` #### Skip Commit Confirmation This flag allows users to automatically commit the changes without having to manually confirm the commit message. This is useful for users who want to streamline the commit process and avoid additional steps. To use this flag, you can run the following command: ``` oco --yes ``` ## Configuration ### Local per repo configuration Create a `.env` file and add OpenCommit config variables there like this: ``` … ``` Global configs are same as local configs, but they are stored in the global `~/.opencommit` config file and set with `oco config set` command, e.g. `oco config set OCO_MODEL=gpt-4o`. ### Global config for all repos Local config still has more priority than Global config, but you may set `OCO_MODEL` and `OCO_LOCALE` globally and set local configs for `OCO_EMOJI` and `OCO_DESCRIPTION` per repo which is more convenient. Simply set any of the variables above like this: ```sh oco config set OCO_MODEL=gpt-4o-mini ``` To see all available configuration parameters and their accepted values: ```sh oco config describe ``` To see details for a specific parameter: ```sh oco config describe OCO_MODEL ``` Configure [GitMoji](https://gitmoji.dev/) to preface a message. ```sh oco config set OCO_EMOJI=true ``` To remove preface emojis: ```sh oco config set OCO_EMOJI=false ``` By default, GitMoji appears at the start of the commit header: ```text (server.ts): handle an unavailable port ``` To place GitMoji immediately before the subject, after the Conventional Commit type and optional scope: ```sh oco config set OCO_EMOJI_POSITION_BEFORE_DESCRIPTION=true ``` ```text fix(server.ts): handle an unavailable port ``` This setting only affects commits generated with `OCO_EMOJI=true` or `--fgm`. Other config options are behaving the same. ### Output WHY the changes were done (WIP) You can set the `OCO_WHY` config to `true` to have OpenCommit output a short description of WHY the changes were done after the commit message. Default is `false`. To make this perform accurate we must store 'what files do' in some kind of an index or embedding and perform a lookup (kinda RAG) for the accurate git commit message. If you feel like building this comment on this ticket https://github.com/di-sukharev/opencommit/issues/398 and let's go from there together. ```sh oco config set OCO_WHY=true ``` ### Switch to GPT-4 or other models By default, OpenCommit uses `gpt-4o-mini` model. You may switch to gpt-4o which performs better, but costs more ```sh oco config set OCO_MODEL=gpt-4o ``` or for as a cheaper option: ```sh oco config set OCO_MODEL=gpt-3.5-turbo ``` ### Model Management OpenCommit automatically fetches available models from your provider when you run `oco setup`. Models are cached for 7 days to reduce API calls. To see available models for your current provider: ```sh oco models ``` To refresh the model list (e.g., after new models are released): ```sh oco models --refresh ``` To see models for a specific provider: ```sh oco models --provider anthropic ``` ### Switch to other LLM providers with a custom URL By default OpenCommit uses [OpenAI](https://openai.com). You could switch to [Azure OpenAI Service](https://learn.microsoft.com/azure/cognitive-services/openai/) or Flowise or Ollama or llama.cpp. ```sh oco config set OCO_AI_PROVIDER=azure OCO_API_KEY= OCO_API_URL= oco config set OCO_AI_PROVIDER=flowise OCO_API_KEY= OCO_API_URL= oco config set OCO_AI_PROVIDER=ollama OCO_API_KEY= OCO_API_URL= oco config set OCO_AI_PROVIDER=llamacpp OCO_API_URL= ``` ### Use OrcaRouter as the model gateway By default OpenCommit uses [OpenAI](https://openai.com). You could switch to [OrcaRouter](https://www.orcarouter.ai), an OpenAI-compatible gateway that supports direct provider models and automatic model routing. It can also provide optional gateway-level guardrails and firewall policies for prompts, responses, and tool calls. Enabling and configuring those controls is a separate step on the OrcaRouter side: the recommended `balanced` posture is primarily audit-based, while `tight` applies default-deny enforcement. OpenCommit itself does not configure them — it simply calls the gateway like any OpenAI-compatible API. ```sh oco config set OCO_AI_PROVIDER=orcarouter OCO_API_KEY= oco config set OCO_AI_PROVIDER=orcarouter OCO_API_KEY= OCO_MODEL=orcarouter/auto ``` The default model is `orcarouter/auto`, which lets OrcaRouter pick the best model for your request automatically. ### Use with Proxy If you are behind a proxy, you can set it in the config: ```sh oco config set OCO_PROXY=http://127.0.0.1:7890 ``` If `OCO_PROXY` is unset, OpenCommit will automatically use `HTTPS_PROXY` or `HTTP_PROXY` environment variables. To explicitly disable proxy use for OpenCommit, even when those environment variables are set: ```sh oco config set OCO_PROXY=null ``` ### Locale configuration To globally specify the language used to generate commit messages: ```sh # de, German, Deutsch oco config set OCO_LANGUAGE=de oco config set OCO_LANGUAGE=German oco config set OCO_LANGUAGE=Deutsch # fr, French, française oco config set OCO_LANGUAGE=fr oco config set OCO_LANGUAGE=French oco config set OCO_LANGUAGE=française ``` The default language setting is **English** All available languages are currently listed in the [i18n](https://github.com/di-sukharev/opencommit/tree/master/src/i18n) folder ### Push to git (gonna be deprecated) A prompt for pushing to git is on by default but if you would like to turn it off just use: ```sh oco config set OCO_GITPUSH=false ``` and it will exit right after commit is confirmed without asking if you would like to push to remote. ### Switch to `@commitlint` OpenCommit allows you to choose the prompt module used to generate commit messages. By default, OpenCommit uses its conventional-commit message generator. However, you can switch to using the `@commitlint` prompt module if you prefer. This option lets you generate commit messages in respect with the local config. You can set this option by running the following command: ```sh oco config set OCO_PROMPT_MODULE= ``` Replace `` with either `conventional-commit` or `@commitlint`. #### Example: To switch to using the `'@commitlint` prompt module, run: ```sh oco config set OCO_PROMPT_MODULE=@commitlint ``` To switch back to the default conventional-commit message generator, run: ```sh oco config set OCO_PROMPT_MODULE=conventional-commit ``` #### Integrating with `@commitlint` The integration between `@commitlint` and OpenCommit is done automatically the first time OpenCommit is run with `OCO_PROMPT_MODULE` set to `@commitlint`. However, if you need to force set or reset the configuration for `@commitlint`, you can run the following command: ```sh oco commitlint force ``` To view the generated configuration for `@commitlint`, you can use this command: ```sh oco commitlint get ``` This allows you to ensure that the configuration is set up as desired. Additionally, the integration creates a file named `.opencommit-commitlint` which contains the prompts used for the local `@commitlint` configuration. You can modify this file to fine-tune the example commit message generated by OpenAI. This gives you the flexibility to make adjustments based on your preferences or project guidelines. OpenCommit generates a file named `.opencommit-commitlint` in your project directory which contains the prompts used for the local `@commitlint` configuration. You can modify this file to fine-tune the example commit message generated by OpenAI. If the local `@commitlint` configuration changes, this file will be updated the next time OpenCommit is run. This offers you greater control over the generated commit messages, allowing for customization that aligns with your project's conventions. ## Git flags The `opencommit`