ai-commit

AI-Commit

AI-Commit is an AI-powered tool that automatically generates Conventional Commits based on your staged changes. It leverages OpenAI to produce concise, readable commit messages and now includes an experimental semantic release feature for automated versioning and interactive split mode for partial commits. Inspired by insulineru/ai-commit.

Table of Contents

• AI-Commit
  • Table of Contents
  • Key Features
  • Prerequisites
  • Installation
  • Configuration
    • OpenAI API Key
    • Custom Templates
    • Semantic Release
  • Usage
    • Command-Line Flags
  • How it Works
  • Examples
    • 1. Standard Interactive Commit
    • 2. Force Commit (Non-Interactive)
    • 3. Semantic Release
    • 4. Custom Template
    • 5. Interactive Commit Splitting (Partial Commits)
    • 6. Optional Emoji Prefix
  • License

Key Features

1. AI-Powered Commit Messages
   Generates helpful commit messages by analyzing your staged diff and prompting OpenAI.

2. Conventional Commits Compliance
   Ensures messages follow Conventional Commits for a cleaner, interpretable commit history.

3. Interactive or Non-Interactive
   Choose between a friendly TUI for confirming commits or a --force mode to skip prompts.

4. Customizable Commit Types
   Specify a commit type (e.g., feat, fix, docs) or let the tool infer it automatically.

5. Custom Templates
   Dynamically insert the AI-generated commit into custom templates with placeholders (e.g., branch name).

6. Semantic Release (Experimental)
   Automatically suggests a new semantic version tag (MAJOR.MINOR.PATCH) based on commit content, optionally creates a new git tag).

7. Interactive Commit Splitting
   Split large diffs into multiple smaller commits via an interactive TUI that shows each “chunk” of changes. Select which lines or hunks you want in each commit. Each partial commit can also be assigned an AI-generated commit message.

8. Optional Emoji Prefix
   Add an emoji prefix to your commit message if desired.

Prerequisites

• Git: AI-Commit operates on your local Git repository and requires Git installed.
• Go: Needed to build AI-Commit from source.
• OpenAI API Key: Sign up at https://openai.com/ to get your API key.

Installation

1. Clone the Repository

   git clone https://github.com/renatogalera/ai-commit.git
   cd ai-commit
   

2. Build the Application

   go build -o ai-commit ./cmd/ai-commit
   

3. (Optional) Install Globally

   sudo mv ai-commit /usr/local/bin/
   

   Now ai-commit is accessible from anywhere in your terminal.

Configuration

OpenAI API Key

Set your API key either via a command-line flag or an environment variable:

• Command-Line Flag: --apiKey YOUR_API_KEY
• Environment Variable:

export OPENAI_API_KEY=YOUR_API_KEY

Custom Templates

Use the --template flag to supply a commit message template with placeholders:

• {COMMIT_MESSAGE}
  The AI-generated commit message.

• {GIT_BRANCH}
  The name of the current Git branch.

For example:

ai-commit --template "Branch: {GIT_BRANCH}\nCommit: {COMMIT_MESSAGE}"

Semantic Release

1. Use --semantic-release when running AI-Commit. This will:
   • Parse your current version (from the latest vX.Y.Z Git tag).
   • Consult OpenAI to determine if you need a MAJOR, MINOR, or PATCH bump.

Usage

Run ai-commit inside a Git repository with staged changes.

Command-Line Flags

• --apiKey
  Your OpenAI API key. If not set, the tool looks for OPENAI_API_KEY.
• --commit-type
  Specify a commit type (feat, fix, docs, etc.). Otherwise the tool may infer it.
• --template
  Custom template for your commit message.
• --force
  Automatically commit without interactive confirmation.
• --language
  Language used in AI generation (default english).
• --semantic-release
  Triggers AI-assisted version bumping and release tasks (see Semantic Release).
• --interactive-split
  Launches an interactive TUI to split staged changes into multiple partial commits.
• --emoji
  Includes an emoji prefix in your commit message if specified.

How it Works

1. Check Git
   Ensures you’re in a valid Git repository and there are staged changes.

2. Retrieve Diff & Filter Lock Files
   Pulls the staged diff and removes lock files (go.mod, go.sum, etc.) from analysis.

3. Generate AI Prompt
   Assembles a request including your diff, commit type, and desired language.

4. OpenAI Request
   Calls OpenAI’s chat completion endpoint with the prompt, retrieving a commit message.

5. Sanitize & Format
   Applies Conventional Commits formatting, optionally adds an emoji prefix if requested, and substitutes into any template you provide.

6. Interactive UI
   Presents a TUI to review and optionally regenerate the commit message unless --force is used.

7. Commit & (Optional) Semantic Release
   Commits your changes. If --semantic-release is enabled, AI-Commit:

   • Reads the current version tag.
   • Generates a recommended next version (MAJOR, MINOR, or PATCH).
   • Creates new Git tag.

8. Interactive Commit Splitting (optional)
   If --interactive-split is used, AI-Commit shows a separate TUI that breaks the diff into chunks, letting you select what belongs in each commit. Each partial commit is also assigned an AI-generated commit message.

Examples

1. Standard Interactive Commit

ai-commit --apiKey YOUR_API_KEY

1. Stage changes with git add .
2. Let AI-Commit generate a message and show you an interactive UI:
   • Confirm (y / enter)
   • Regenerate (r)
   • Select Type (t)
   • Quit (q / ctrl+c)

2. Force Commit (Non-Interactive)

ai-commit --apiKey YOUR_API_KEY --force

Bypasses the interactive UI and commits immediately.

3. Semantic Release

ai-commit --apiKey YOUR_API_KEY --semantic-release

1. Generates the commit message (interactive or forced).
2. After committing, it reads your latest version tag, queries OpenAI for a suggested version increment, tags your repository, and runs GoReleaser.

4. Custom Template

ai-commit --template "Branch: {GIT_BRANCH}\nCommit: {COMMIT_MESSAGE}"

Inserts the current branch name and AI-generated message into the final commit log.

5. Interactive Commit Splitting (Partial Commits)

ai-commit --interactive-split

1. Stage your changes with git add .
2. AI-Commit shows a TUI listing each diff chunk or “hunk.”
3. Use Space to toggle which chunks you want included in a partial commit.
4. Press C to commit the selected chunks. AI will generate the message.
5. Repeat or exit once you have committed all the chunks you need.

6. Optional Emoji Prefix

ai-commit --emoji

Adds a relevant emoji to the beginning of your commit message if a recognized commit type (e.g. feat, fix) is found or inferred. If the commit type is unrecognized or you do not use --emoji, it won't add an emoji prefix.

License

This project is released under the MIT License. Please see the LICENSE file for details