\n\nAll 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.\n\n## Setup OpenCommit as a CLI tool\n\nYou 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.\n\n1. Install OpenCommit globally to use in any repository:\n\n ```sh\n npm install -g opencommit\n ```\n\n2. 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.\n\n3. Set the key to OpenCommit config:\n\n ```sh\n oco config set OCO_API_KEY=\n ```\n\n Your API key is stored locally in the `~/.opencommit` config file.\n\n## Usage\n\nYou can call OpenCommit with `oco` command to generate a commit message for your staged changes:\n\n```sh\ngit add \noco\n```\n\nRunning `git add` is optional, `oco` will do it for you.\n\n### Running locally with Ollama\n\nYou can also run it with local model through ollama:\n\n- install and start ollama\n- run `ollama run mistral` (do this only once, to pull model)\n- run (in your project directory):\n\n```sh\ngit add \noco config set OCO_AI_PROVIDER='ollama' OCO_MODEL='llama3:8b'\n```\n\nDefault model is `mistral`.\n\nIf you have ollama that is set up in docker/ on another machine with GPUs (not locally), you can change the default endpoint url.\n\nYou can do so by setting the `OCO_API_URL` environment variable as follows:\n\n```sh\noco config set OCO_API_URL='http://192.168.1.10:11434/api/chat'\n```\n\nwhere 192.168.1.10 is example of endpoint URL, where you have ollama set up.\n\n#### Troubleshooting Ollama IPv6/IPv4 Connection Fix\n\nIf you encounter issues with Ollama, such as the error\n\n```sh\nβ local model issues. details: connect ECONNREFUSED ::1:11434\n```\n\nIt'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:\n\n```bash\nexport OLLAMA_HOST=0.0.0.0\n```\n\nThis 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.\n\n### Running locally with llama.cpp\n\nYou can run OpenCommit with local models served by [llama.cpp](https://github.com/ggerganov/llama.cpp):\n\n- install and build llama.cpp\n- start the server with a GGUF model: `./llama-server -m model.gguf --port 8080`\n- run (in your project directory):\n\n```sh\ngit add \noco config set OCO_AI_PROVIDER='llamacpp' OCO_API_URL='http://localhost:8080'\n```\n\nIf the server is running on a different machine, set the URL accordingly:\n\n```sh\noco config set OCO_API_URL='http://192.168.1.10:8080'\n```\n\n### Flags\n\nThere are multiple optional flags that can be used with the `oco` command:\n\n#### Use Full GitMoji Specification\n\nLink to the GitMoji specification: https://gitmoji.dev/\n\nThis flag can only be used if the `OCO_EMOJI` configuration item is set to `true`. This flag allows users to use all emojis in the GitMoji specification, By default, the GitMoji full specification is set to `false`, which only includes 10 emojis (πβ¨ππβ β»οΈβ¬οΈπ§ππ‘).\n\nThis 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.\n\n```\noco --fgm\n```\n\n#### Skip Commit Confirmation\n\nThis 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:\n\n```\noco --yes\n```\n\n## Configuration\n\n### Local per repo configuration\n\nCreate a `.env` file and add OpenCommit config variables there like this:\n\n```env\n...\nOCO_AI_PROVIDER=\nOCO_API_KEY= // or other LLM provider API token\nOCO_API_URL=\nOCO_API_CUSTOM_HEADERS=\nOCO_TOKENS_MAX_INPUT=\nOCO_TOKENS_MAX_OUTPUT=\nOCO_DESCRIPTION=\nOCO_EMOJI=\nOCO_MODEL=\nOCO_LANGUAGE=\nOCO_MESSAGE_TEMPLATE_PLACEHOLDER=\nOCO_PROMPT_MODULE=\nOCO_ONE_LINE_COMMIT=\n```\n\nGlobal 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`.\n\n### Global config for all repos\n\nLocal 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.\n\nSimply set any of the variables above like this:\n\n```sh\noco config set OCO_MODEL=gpt-4o-mini\n```\n\nTo see all available configuration parameters and their accepted values:\n\n```sh\noco config describe\n```\n\nTo see details for a specific parameter:\n\n```sh\noco config describe OCO_MODEL\n```\n\nConfigure [GitMoji](https://gitmoji.dev/) to preface a message.\n\n```sh\noco config set OCO_EMOJI=true\n```\n\nTo remove preface emojis:\n\n```sh\noco config set OCO_EMOJI=false\n```\n\nOther config options are behaving the same.\n\n### Output WHY the changes were done (WIP)\n\nYou 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`.\n\nTo 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.\n\n```sh\noco config set OCO_WHY=true\n```\n\n### Switch to GPT-4 or other models\n\nBy default, OpenCommit uses `gpt-4o-mini` model.\n\nYou may switch to gpt-4o which performs better, but costs more π€ \n\n```sh\noco config set OCO_MODEL=gpt-4o\n```\n\nor for as a cheaper option:\n\n```sh\noco config set OCO_MODEL=gpt-3.5-turbo\n```\n\n### Model Management\n\nOpenCommit automatically fetches available models from your provider when you run `oco setup`. Models are cached for 7 days to reduce API calls.\n\nTo see available models for your current provider:\n\n```sh\noco models\n```\n\nTo refresh the model list (e.g., after new models are released):\n\n```sh\noco models --refresh\n```\n\nTo see models for a specific provider:\n\n```sh\noco models --provider anthropic\n```\n\n### Switch to other LLM providers with a custom URL\n\nBy default OpenCommit uses [OpenAI](https://openai.com).\n\nYou could switch to [Azure OpenAI Service](https://learn.microsoft.com/azure/cognitive-services/openai/) or Flowise or Ollama or llama.cpp.\n\n```sh\noco config set OCO_AI_PROVIDER=azure OCO_API_KEY= OCO_API_URL=\n\noco config set OCO_AI_PROVIDER=flowise OCO_API_KEY= OCO_API_URL=\n\noco config set OCO_AI_PROVIDER=ollama OCO_API_KEY= OCO_API_URL=\n\noco config set OCO_AI_PROVIDER=llamacpp OCO_API_URL=\n```\n\n### Use with Proxy\n\nIf you are behind a proxy, you can set it in the config:\n\n```sh\noco config set OCO_PROXY=http://127.0.0.1:7890\n```\n\nIf `OCO_PROXY` is unset, OpenCommit will automatically use `HTTPS_PROXY` or `HTTP_PROXY` environment variables.\n\nTo explicitly disable proxy use for OpenCommit, even when those environment variables are set:\n\n```sh\noco config set OCO_PROXY=null\n```\n\n### Locale configuration\n\nTo globally specify the language used to generate commit messages:\n\n```sh\n# de, German, Deutsch\noco config set OCO_LANGUAGE=de\noco config set OCO_LANGUAGE=German\noco config set OCO_LANGUAGE=Deutsch\n\n# fr, French, franΓ§aise\noco config set OCO_LANGUAGE=fr\noco config set OCO_LANGUAGE=French\noco config set OCO_LANGUAGE=franΓ§aise\n```\n\nThe default language setting is **English**\nAll available languages are currently listed in the [i18n](https://github.com/di-sukharev/opencommit/tree/master/src/i18n) folder\n\n### Push to git (gonna be deprecated)\n\nA prompt for pushing to git is on by default but if you would like to turn it off just use:\n\n```sh\noco config set OCO_GITPUSH=false\n```\n\nand it will exit right after commit is confirmed without asking if you would like to push to remote.\n\n### Switch to `@commitlint`\n\nOpenCommit 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.\n\nYou can set this option by running the following command:\n\n```sh\noco config set OCO_PROMPT_MODULE=\n```\n\nReplace `` with either `conventional-commit` or `@commitlint`.\n\n#### Example:\n\nTo switch to using the `'@commitlint` prompt module, run:\n\n```sh\noco config set OCO_PROMPT_MODULE=@commitlint\n```\n\nTo switch back to the default conventional-commit message generator, run:\n\n```sh\noco config set OCO_PROMPT_MODULE=conventional-commit\n```\n\n#### Integrating with `@commitlint`\n\nThe 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:\n\n```sh\noco commitlint force\n```\n\nTo view the generated configuration for `@commitlint`, you can use this command:\n\n```sh\noco commitlint get\n```\n\nThis allows you to ensure that the configuration is set up as desired.\n\nAdditionally, 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.\n\nOpenCommit 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.\n\nThis offers you greater control over the generated commit messages, allowing for customization that aligns with your project's conventions.\n\n## Git flags\n\nThe `opencommit` or `oco` commands can be used in place of the `git commit -m \"${generatedMessage}\"` command. This means that any regular flags that are used with the `git commit` command will also be applied when using `opencommit` or `oco`.\n\n```sh\noco --no-verify\n```\n\nis translated to :\n\n```sh\ngit commit -m \"${generatedMessage}\" --no-verify\n```\n\nTo include a message in the generated message, you can utilize the template function, for instance:\n\n```sh\noco '#205: $msgβ\n```\n\n> opencommit examines placeholders in the parameters, allowing you to append additional information before and after the placeholders, such as the relevant Issue or Pull Request. Similarly, you have the option to customize the OCO_MESSAGE_TEMPLATE_PLACEHOLDER configuration item, for example, simplifying it to $m!\"\n\n### Message Template Placeholder Config\n\n#### Overview\n\nThe `OCO_MESSAGE_TEMPLATE_PLACEHOLDER` feature in the `opencommit` tool allows users to embed a custom message within the generated commit message using a template function. This configuration is designed to enhance the flexibility and customizability of commit messages, making it easier for users to include relevant information directly within their commits.\n\n#### Implementation Details\n\nIn our codebase, the implementation of this feature can be found in the following segment:\n\n```javascript\ncommitMessage = messageTemplate.replace(\n config.OCO_MESSAGE_TEMPLATE_PLACEHOLDER,\n commitMessage\n);\n```\n\nThis line is responsible for replacing the placeholder in the `messageTemplate` with the actual `commitMessage`.\n\n#### Usage\n\nFor instance, using the command `oco '$msg #205β`, users can leverage this feature. The provided code represents the backend mechanics of such commands, ensuring that the placeholder is replaced with the appropriate commit message.\n\n#### Committing with the Message\n\nOnce users have generated their desired commit message, they can proceed to commit using the generated message. By understanding the feature's full potential and its implementation details, users can confidently use the generated messages for their commits.\n\n### Ignore files\n\nYou can remove files from being sent to OpenAI by creating a `.opencommitignore` file. For example:\n\n```ignorelang\npath/to/large-asset.zip\n**/*.jpg\n```\n\nThis helps prevent opencommit from uploading artifacts and large files.\n\nBy default, opencommit ignores files matching: `*-lock.*` and `*.lock`\n\n## Git hook (KILLER FEATURE)\n\nYou can set OpenCommit as Git [`prepare-commit-msg`](https://git-scm.com/docs/githooks#_prepare_commit_msg) hook. Hook integrates with your IDE Source Control and allows you to edit the message before committing.\n\nTo set the hook:\n\n```sh\noco hook set\n```\n\nTo unset the hook:\n\n```sh\noco hook unset\n```\n\nTo use the hook:\n\n```sh\ngit add \ngit commit\n```\n\nOr follow the process of your IDE Source Control feature, when it calls `git commit` command β OpenCommit will integrate into the flow.\n\n## Setup OpenCommit as a GitHub Action (BETA) π₯\n\nOpenCommit is now available as a GitHub Action which automatically improves all new commits messages when you push to remote!\n\nThis is great if you want to make sure all commits in all of your repository branches are meaningful and not lame like `fix1` or `done2`.\n\nCreate a file `.github/workflows/opencommit.yml` with the contents below:\n\n```yml\nname: 'OpenCommit Action'\n\non:\n push:\n # this list of branches is often enough,\n # but you may still ignore other public branches\n branches-ignore: [main master dev development release]\n\njobs:\n opencommit:\n timeout-minutes: 10\n name: OpenCommit\n runs-on: ubuntu-latest\n permissions: write-all\n steps:\n - name: Setup Node.js Environment\n uses: actions/setup-node@v2\n with:\n node-version: '16'\n - uses: actions/checkout@v3\n with:\n fetch-depth: 0\n - uses: di-sukharev/opencommit@github-action-v1.0.4\n with:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n\n env:\n # set openAI api key in repo actions secrets,\n # for openAI keys go to: https://platform.openai.com/account/api-keys\n # for repo secret go to: /settings/secrets/actions\n OCO_API_KEY: ${{ secrets.OCO_API_KEY }}\n\n # customization\n OCO_TOKENS_MAX_INPUT: 4096\n OCO_TOKENS_MAX_OUTPUT: 500\n OCO_OPENAI_BASE_PATH: ''\n OCO_DESCRIPTION: false\n OCO_EMOJI: false\n OCO_MODEL: gpt-4o\n OCO_LANGUAGE: en\n OCO_PROMPT_MODULE: conventional-commit\n```\n\nThat is it. Now when you push to any branch in your repo β all NEW commits are being improved by your never-tired AI.\n\nMake sure you exclude public collaboration branches (`main`, `dev`, `etc`) in `branches-ignore`, so OpenCommit does not rebase commits there while improving the messages.\n\nInteractive rebase (`rebase -i`) changes commits' SHA, so the commit history in remote becomes different from your local branch history. This is okay if you work on the branch alone, but may be inconvenient for other collaborators.\n\n## Payments\n\nYou pay for your requests to OpenAI API on your own.\n\nOpenCommit stores your key locally.\n\nOpenCommit by default uses 3.5-turbo model, it should not exceed $0.10 per casual working day.\n\nYou may switch to gpt-4, it's better, but more expensive.\n","readmeFilename":"README.md"}
![\"OpenCommit](\".github/logo-grad.svg\")
\n ![](\"https://img.shields.io/twitter/follow/_sukharev_?style=flat&label=_sukharev_&logo=twitter&color=0bf&logoColor=fff\")
\n ![\"Current](\"https://img.shields.io/npm/v/opencommit\")
\n ![\"OpenCommit](\".github/opencommit-example.png\")
\n