Commit for me! 🤖 Generate commit messages using aichat.

Uses the conventional-commits standard by default, but is easily customizable to your own needs.

Just run cfme after staging your changes, and it will generate a commit message using AI, prompt you to review and edit it, then commit it for you.

There is also a demo available showing how to use cfme from within Lazygit. Jump to the Lazygit Integration section below.

• AI-Powered Commit Messages - Leverages modern AI models (OpenAI GPT, GitHub Copilot) to analyze your staged changes and generate meaningful commit messages
• Interactive Review & Selection - Uses fzf to let you choose from multiple AI-generated candidates, then edit before committing
• Conventional Commits by Default - Follows the conventional-commits standard out of the box for consistent, parseable commit history
• Fully Customizable - Bring your own prompts, variables, and commit message standards - cfme adapts to your team's workflow
• Template-Based Prompts - Simple <__MY_VARIABLE__> syntax for injecting git diffs, test results, custom instructions, or any command output into your prompts
• Multiple Prompt Types - Switch between different commit message standards (conventional-commits, your-team-standard, etc.) with a single environment variable
• Runtime Instructions - Pass specific context with -i "Fixed login bug" to guide the AI without editing prompt files
• Pipe-Friendly Output - Use -r or -m flags to output messages for integration with other tools and workflows
• Free Tier Available - Works with GitHub Copilot's free tier (everyone with a GitHub account has access)
• Cross-Platform - Works on macOS, Linux, and Windows (via WSL/Git Bash/Cygwin)
• Tested - Uses Shellspec unit tests to ensure reliability and correctness

1. Install dependencies:

   • aichat
   • fzf
   • yq

   e.g. using Homebrew/Linuxbrew brew install aichat fzf yq

2. Install cfme:

   curl -sSL https://github.com/codevogel/cfme/releases/download/latest/cfme chmod +x cfme sudo mv cfme /usr/local/bin # or any directory, as long as it's in your $PATH

3. Setup aichat credentials (just run aichat and follow the prompts)

   ℹ️ Note: You can get your GitHub 'API Key' by creating a Personal Access Token (classic) with Copilot scope.

4. Stage some changes: git add .

5. Run cfme to generate commit message: cfme

Table of Contents

• cfme
  • Features ✨
  • Demo 🎥
  • Quick Start 🚀
  • Usage
    • Examples
  • Customization
    • Writing a custom prompt file
    • Writing a variables file
    • Environment Variables
  • Integration into other tools
    • Lazygit
    • Other tools
  • Contributing
  • License

The Quick Start section above provides a quick way to setup cfme. What follows is a more detailed explanation of the installation process.

1. Install dependencies:

   cfme depends on the following command-line tools. Please refer to their respective installation instructions for your platform.

   • aichat
     • This serves as the interface to various AI chat models, including OpenAI's GPT models and GitHub Copilot.
   • fzf
     • This is used to provide an interactive fuzzy search interface to select from the commit message candidates generated by the AI.
   • yq (from mikefarah)
     • This is used to parse the YAML variables file for use in the prompt.
     • Note: There are two popular yq tools, make sure to install the one from mikefarah, as the syntax differs between the two, and you might run into issues otherwise.

   Brew is a convenient way to install all of the dependencies on macOS and Linux, but feel free to use any other method you prefer.

   brew install aichat fzf yq

2. Install cfme: Download the latest release binary from the Releases page, make it executable, and move it to a directory in your $PATH.

   On Unix-like systems, you can do this with the following commands:

   curl -sSL https://github.com/codevogel/cfme/releases/download/latest/cfme chmod +x cfme sudo mv cfme /usr/local/bin # or any directory, as long as it's in your $PATH

   On Windows, it is important to know that cfme is a shell script written in bash, so you will need to have a bash environment set up, e.g. through WSL or, Git Bash (which comes with Git), Cygwin, mingw-64 etc.

3. Setup aichat credentials: Run aichat and follow the prompts to set up your AI chat model and API Key.

   • For GitHub Copilot, you can get your 'API Key' by creating a Personal Access Token (classic). Be sure to give this token the Copilot scope. Everyone who has a GitHub account has access to the GitHub Copilot Free plan. You may hit limits with this plan, however.

     Educators, students, and open source contributors may be eligible for free access to GitHub Copilot Pro. See this page for more information.

   • aichat supports a bunch of different AI providers, such as OpenAI GPT, Claude, and more.

   • Choose a model wisely: For example, GPT-4 mini generates faster commit message faster, whereas GPT-4 probably writes more accurate messages.

4. Stage some changes: cfme generates commit messages based on the staged changes in your git repository. Note that changed files aren't yet staged, so you need to stage them first using git add <file>. (You can optionally alter your prompt to include unstaged changes if you want to, see the 'Customization' section below for more information.)

5. Run cfme to generate commit message: Simply run cfme in your terminal while in the git repository with staged changes. Follow the prompts to review and edit the generated commit message, then confirm to commit it.

   Be sure to check out the 'Customization' section below to learn how to customize the prompt and variables to your own needs, and check out the 'Usage' section to learn about the available options, such as passing instructions to the AI on what the commit is about, piping the output to other tools, and more.

Not happy with the default prompt or variables?

cfme is designed to be customizable to your needs.

Simply create your own prompt at $CFME_CONFIG_DIR/$CFME_PROMPT_DIR/$CFME_PROMPT_TYPE/<your-prompt>.md and/or your own variables file at $CFME_CONFIG_DIR/$CFME_PROMPT_DIR/$CFME_PROMPT_TYPE/<your-variables>.yaml. then set $CFME_DEFAULT_PROMPT_FILE and/or $CFME_PROMPT_VARIABLES_FILE to point to your custom files, or use the -p and -v flags to specify them at runtime.

$CFME_PROMPT_TYPE will determine the subdirectory in the $CFME_PROMPT_DIR directory by default, allowing you to quickly switch between different prompt types (e.g. conventional-commits, or any other standard your team uses).

Example:

1. Say you want to create a custom prompt for your own commit message standard, you could do the following:

   • Prompt file: ~/.config/cfme/prompts/my-commit-standard/default.md
   • Variables file: ~/.config/cfme/prompts/my-commit-standard/default-vars.yaml
   • Environment variables:
   export CFME_PROMPT_TYPE="my-commit-standard"

   Or just use the flags:

   cfme -p "path/to/custom/prompt.md" -v "path/to/custom/vars.yaml"

2. Say you want to use the conventional-commits standard, but with your own custom prompt and variables, you could do the following:

   • Prompt file: ~/.config/cfme/prompts/conventional-commits/my-custom-prompt.md

   • Variables file: ~/.config/cfme/prompts/conventional-commits/my-custom-vars.yaml

   • Environment variables:

     export CFME_DEFAULT_PROMPT_FILE="$CFME_PROMPT_DIR/$CFME_PROMPT_TYPE/my-custom-prompt.md" export CFME_PROMPT_VARIABLES_FILE="$CFME_PROMPT_DIR/$CFME_PROMPT_TYPE/my-custom-vars.yaml"

     Or just use the flags:

   cfme -p "path/to/custom/prompt.md" -v "path/to/custom/vars.yaml"

ℹ️ If the specified $CFME_DEFAULT_PROMPT_FILE or $CFME_PROMPT_VARIABLES file does not yet exist, cfme will attempt to fetch these files from the /defaults folder in this repository. This requires $CFME_PROMPT_TYPE to be set to the default value of conventional-commits. See the 'Environment Variables' section below for more information.

cfme uses a prompt file in markdown format, in which you can write your prompt that will be sent to the AI.

cfme will parse your prompt file, replacing any template strings in the format of <__MY_TEMPLATE_STRING__> with the corresponding values from your variables file.

There are three special template strings that cfme recognizes by default:

• <__GIT_DIFF__> (required): Replaced with the output of git diff --cached (i.e. the staged changes)
• <__RESPONSE_FORMAT_REQUIREMENTS__> (required): Replaced with a list of requirements that dictates how the AI should format its response. This is essential so that cfme can parse the AI's response. Note that these requirements merely dictate the format of the response, they do not influence the requirements for the commit message itself.
• <__INSTRUCTIONS__> (optional): Replaced with any instructions passed via the [-i|--instructions] flag.
  • If no instructions are provided, this template string is replaced with an empty string.
  • You can leave out this template string from your prompt file if you don't plan to use it.

ℹ️cfme will warn you if you have template strings in your prompt file that are not defined in your variables file, and vice versa, it will warn you if you have variables defined that are not used in your prompt file.

For example, the simplest prompt file could look like this:

A more complex prompt file could look like this:

See below for how to write the corresponding variables file.

The variables file is a simple YAML file that defines key-value pairs for use in your prompt file. You can either define literal strings (single or multi-line), or command (sequences) that will be evaluated, and their output used as the value.

A valid variables file must have a top-level key vars, which contains an array of variable definitions.

A variable definition

• must have a template_string key, which defines the template string to be replaced in the prompt file (including the <__ and __> delimiters).
• must have either a
  • value key, which defines the literal string value to replace the template string with, or
  • value_from key, which defines a command (sequence) to be executed. The output of those commands is used as the value to replace the template string with.

For example, the variables file corresponding to the above complex prompt could look like this:

ℹ️ If you want to do so, you can use define default <__INSTRUCTIONS__> variable in your variables file, which you can overwrite by passing the [-i|--instructions] flag at runtime. You can also just leave out the <__INSTRUCTIONS__> template string from the variables file, and cfme will replace it with an empty string if no instructions are provided at runtime.

cfme supports the following environment variables for configuration:

Recommendations:

• keep CFME_CONFIG_DIR and CFME_PROMPT_DIR at their default values, unless you have a specific reason to change them.
• set CFME_PROMPT_TYPE to the prompt type you want to use by default (e.g. conventional-commits), if you have multiple prompt types set up. (see Customization section above for more information)
• keep the structure of CFME_DEFAULT_PROMPT_FILE and CFME_DEFAULT_PROMPT_VARIABLES_FILE as is, (i.e. keep the ${CFME_PROMPT_DIR}/${CFME_PROMPT_TYPE}/ prefix)

For advanced users, you can also set where cfme fetches the default files from, should they not exist on your system. This requires $CFME_PROMPT_TYPE to be set something other than conventional-commits. This is useful if you maintain your own fork with custom default prompts you want to use.

Lazygit is awesome. But cfme allows you to be even lazier! You can use cfme from within Lazygit's TUI to generate commit messages:

Just add the following custom command to your Lazygit config file (e.g. ~/.config/lazygit/config.yml):

And now, use lazygit to stage your changes, then just press Ctrl+a to run cfme and generate a commit message for the staged changes!

As cfme is just a bash script, you can easily integrate it into other tools and workflows. Have a look at the Lazygit section above for an example of how to do this.

The -r and -m flags are especially interesting for integration into other tools, as they allow you to pipe the AI-generated response or the reviewed commit message into other tools, instead of committing it directly.

The -p and -v flags allow you to specify custom prompt and variables files, which is useful if you want to have different prompts for different workflows.

I'm sure you can come up with many more use cases! If you ever get stuck integrating cfme into your workflow, or if you need an additional feature to make the integration easier, feel free to ask for help. Just open up an issue!

If you would like to contribute to this project, you're more than welcome to do so! Feel free to open up issues or submit pull requests.

Example contributions include:

• Wrote a prompt that you think delivers awesome results? Share it as a new prompt type!
• Found a way to improve the default prompt or variables? Submit a PR!
• Added a new feature or fixed a bug? Pull request welcome!
• Want to improve the documentation? Contributions are welcome!

See CONTRIBUTING.md for more information on how to contribute.

This project is licensed under the MIT License. See the LICENSE file for details.