Commiat 🤖✍️

Tired of writing git commit messages? Let AI do it for you! ✨

commiat is a simple CLI tool that:

1. Optionally stages all changes (git add .) if you use the -a or --add-all flag.
2. Analyzes your staged git changes (git diff --staged).
3. Generates a commit message using an AI model via OpenRouter (defaults to Google Gemini 2.5 Flash Lite ⚡) or a local Ollama instance (defaults to qwen2.5).
4. Supports custom commit message formats defined in a local .commiat file.
5. Allows prefixing and suffixing commit messages with custom strings using --prefix and --affix options.
6. Prompts you to confirm ✅, adjust 📝, or cancel ❌ the commit.
7. Optionally bypasses git commit hooks using the -n or --no-verify flag.

🚀 Installation

Option 1: Install from npm (Recommended)

npm install -g commiat

Option 2: Manual Installation

1. Clone the repository:

   git clone https://github.com/javimosch/commiat.git
   cd commiat

2. Install dependencies:

   npm install

3. Link the CLI: This makes the commiat command available globally.

   npm link

⚙️ Configuration

commiat uses two types of configuration:

1. Global Configuration (~/.commiat/config)

This file stores settings that apply across all your projects, primarily your LLM provider choice, API keys, and default models. It uses the standard .env format (KEY=VALUE).

• Location: ~/.commiat/config (created automatically if needed)
• Managed via: commiat config (for OpenRouter), commiat config -m (for multi-commit default), and commiat ollama (for Ollama) commands.
• Key Settings:
  • OpenRouter:
    • COMMIAT_OPENROUTER_API_KEY: Your OpenRouter API key (required if using OpenRouter). If not found here or in environment variables, you'll be prompted.
    • COMMIAT_OPENROUTER_MODEL: The default OpenRouter model ID (e.g., google/gemini-2.5-flash-lite, anthropic/claude-3-haiku). Defaults to google/gemini-2.5-flash-lite.
  • Ollama: (Managed via commiat ollama)
    • COMMIAT_USE_OLLAMA: Set to true to use Ollama instead of OpenRouter. Defaults to false.
    • COMMIAT_OLLAMA_BASE_URL: The base URL for your running Ollama instance. Defaults to http://localhost:11434.
    • COMMIAT_OLLAMA_MODEL: The Ollama model to use. Defaults to llama3.
    • COMMIAT_OLLAMA_FALLBACK_TO_OPENROUTER: Set to true to automatically fall back to OpenRouter if the Ollama request fails (requires OpenRouter API key to be configured). Defaults to false.
  • Multi-Commit Mode: (Managed via commiat config -m)
    • COMMIAT_DEFAULT_MULTI: Set to true to enable multi-commit mode by default. Defaults to false.

2. Project-Specific Format Configuration (.commiat)

This optional file, placed in your project's root directory, allows you to define a custom commit message format for that specific project.

• Location: .commiat in your project root.
• Format: JSON
• Structure Example:

  {
    "format": "{type}({scope}): {msg} [Ticket: {gitBranchNumber}]",
    "variables": {
      "scope": "Description of what 'scope' means in this project (e.g., component, module, feature name)"
    }
  }

• format (string, required): The template for your commit messages.
  • Use {variableName} for placeholders.
  • {msg} is special: The main commit message generated by the AI will replace this.
  • System Variables: These are automatically handled by commiat:
    • {gitBranch}: The full current Git branch name (e.g., feature/DATA-123-button).
    • {gitBranchNumber}: The first sequence of digits found in the branch name (e.g., 123 from feature/DATA-123-button). Returns empty string if no number is found.
    • {type}: The conventional commit type (e.g., feat, fix, chore) determined by the AI based on the diff. The AI is instructed to generate this.
  • Custom Variables: Any other {variableName} (like {scope} above) is a custom variable.
• variables (object, required): Contains descriptions for your custom variables.
  • The keys are the custom variable names (e.g., "scope").
  • The values are strings describing what information should go into that variable. These descriptions are sent to the AI to help it fill the template correctly.
  • If you add a new custom variable to your format string, commiat will prompt you to provide its description the next time you run it, and it will save the description back to your .commiat file.

Configuration Precedence

Settings are looked for in this order:

1. Environment Variables / Local .env File: COMMIAT_OPENROUTER_API_KEY, COMMIAT_OPENROUTER_MODEL, COMMIAT_USE_OLLAMA, COMMIAT_OLLAMA_BASE_URL, COMMIAT_OLLAMA_MODEL, COMMIAT_OLLAMA_FALLBACK_TO_OPENROUTER, COMMIAT_DEFAULT_MULTI set in your shell or a project-local .env file override everything else.
2. Project .commiat File: If present, the format and variables defined here are used for commit message generation.
3. Global ~/.commiat/config File: Used for LLM provider settings if not set by environment variables.
4. Prompts / Defaults:
   • If using OpenRouter and COMMIAT_OPENROUTER_API_KEY is not found, you'll be prompted, and it will be saved globally.
   • If LLM provider settings are not found, defaults are used (OpenRouter with Gemini 2.5 Flash Lite, or Ollama with llama3 if enabled).
   • If .commiat is not found, a standard conventional commit format ({type}: {msg}) is used. If .commiat is missing custom variable descriptions, you'll be prompted.

▶️ Usage

1. (Optional) Configure your LLM provider:
   • For OpenRouter (default): Run commiat once. It will prompt for your API key if needed and save it globally. You can edit the model later with commiat config.
   • For Ollama: Run commiat ollama to enable it, set the URL/model, and optionally enable fallback to OpenRouter.
2. (Optional) Create a .commiat file in your project root if you want a custom format (see example above).
3. Stage your changes:

   git add <your-files...>
   # OR stage all changes:
   git add .

4. Run commiat:

   # Generate commit message
   commiat
   
   # Stage all changes AND generate commit message
   commiat -a
   # or
   commiat --add-all
   
   # Generate commit message and bypass commit hooks
   commiat -n
   # or
   commiat --no-verify
   
   # Add a prefix to the commit message
   commiat --prefix "[WIP]"
   
   # Add a suffix/affix to the commit message  
   commiat --affix "(#12345)"
   
   # Combine multiple options
   commiat -a --prefix "[HOTFIX]" --affix "(#URGENT-456)"
   
   # Enable multi-commit mode
   commiat --multi --untracked -n

5. Follow the prompts:
   • If it's the first time using a custom variable in .commiat, you'll be asked for its description.
   • Confirm, adjust, or cancel the suggested commit message.

Example Workflow with Custom Format:

• Create .commiat:

  {
    "format": "feat({component}): {msg} [JIRA-{gitBranchNumber}]",
    "variables": {
      "component": "The UI component or backend module affected"
    }
  }

• Assume current branch is feature/JIRA-456-new-login.
• Make changes, stage them (git add .).
• Run commiat.
• AI generates a message like: feat(Auth): implement new login flow [JIRA-456]
• Confirm or adjust.

Multi-commit Mode (--multi)

The --multi flag enables an interactive multi-commit workflow, allowing you to group changes logically and commit them individually. This is particularly useful for large feature branches or refactors where multiple distinct changes are made.

Example Output:

commiat --multi --untracked -n
Commiat CLI - Generating commit message...
Loaded format from .commiat
? No changes staged. Stage all changes now? (git add .) Yes
Staging all changes (`git add .`)...
Changes staged.
Multi-commit mode enabled...

Using provider: openrouter, Model: google/gemini-2.5-flash-lite
Sending request to OpenRouter: https://openrouter.ai/api/v1/chat/completions
Successfully parsed group results.

Using provider: openrouter, Model: google/gemini-2.5-flash-lite
Sending request to OpenRouter: https://openrouter.ai/api/v1/chat/completions
? Suggested Commit Message:
"chore: Update Node.js version in Dockerfile to 20.17.0-alpine"

What would you like to do? ✅ Confirm and Commit
Committing with --no-verify flag...
✅ Group commit successful!


Using provider: openrouter, Model: google/gemini-2.5-flash-lite
Sending request to OpenRouter: https://openrouter.ai/api/v1/chat/completions
? Suggested Commit Message:
"feat: Add Dockerfile for application"

What would you like to do? ✅ Confirm and Commit
Committing with --no-verify flag...
✅ Group commit successful!


Processing group 3: Update automation API endpoint logging
Files: automation-api.js
Description: Enhances the `/health` endpoint response in the automation API to log the available API endpoints for better discoverability.
Using provider: openrouter, Model: google/gemini-2.5-flash-lite
Sending request to OpenRouter: https://openrouter.ai/api/v1/chat/completions
? Suggested Commit Message:
"feat: Add endpoint listing to automation API startup message"

What would you like to do? ✅ Confirm and Commit
Committing with --no-verify flag...
✅ Group commit successful!


Processing group 4: Refactor docker-compose for separate app Dockerfile
Files: docker-compose.yml
Description: Modifies the docker-compose file to use the new `Dockerfile.app` for the 'app' service and removes the explicit `command` which was likely redundant.
Staged for this group: docker-compose.yml
Loaded format from .commiat
Detected current branch: master
Detected current branch: master
No number found in branch name: master
Using provider: openrouter, Model: google/gemini-2.5-flash-lite
Sending request to OpenRouter: https://openrouter.ai/api/v1/chat/completions
? Suggested Commit Message:
"feat: Add cleanup for Xvfb lock file"

What would you like to do? ✅ Confirm and Commit
Committing with --no-verify flag...
✅ Group commit successful!


Processing group 6: Update server startup logging for admin and public APIs
Files: server.js
Description: Expands the startup log messages for the admin server to include a comprehensive list of all admin API endpoints, along with a dedicated section for public API endpoints.
Staged for this group: server.js
Loaded format from .commiat
Detected current branch: master
Detected current branch: master
No number found in branch name: master
Using provider: openrouter, Model: google/gemini-2.5-flash-lite
Sending request to OpenRouter: https://openrouter.ai/api/v1/chat/completions
? Suggested Commit Message:
"feat: Enhance server startup logs with detailed API endpoints"

What would you like to do? ✅ Confirm and Commit
Committing with --no-verify flag...
✅ Group commit successful!


🎉 Multi-commit process completed successfully.
➜  substack-schedule git:(master)

🏷️ Message Modification Options

Commiat provides two convenient options to modify the AI-generated commit message:

--prefix <string>

Prepends a string to the beginning of the generated commit message (first line only).

Common use cases:

# Mark work-in-progress commits (space added automatically)
commiat --prefix "[WIP]"

# Indicate hotfixes
commiat --prefix "[HOTFIX]"

# Add urgency markers
commiat --prefix "🚨"

# Specify environment
commiat --prefix "[PROD]"

Note: A space is automatically added between the prefix and commit title if not already present.

--affix <string>

Appends a string to the end of the generated commit message (first line only).

Common use cases:

# Add ticket numbers
commiat --affix "(#12345)"

# Reference JIRA tickets
commiat --affix "[JIRA-456]"

# Add GitHub issue references
commiat --affix " (closes #789)"

# Add reviewer mentions
commiat --affix " cc: @teamlead"

Combining Both Options

You can use both --prefix and --affix together:

# Result: "[HOTFIX] fix authentication bug (#URGENT-123)"
commiat --prefix "[HOTFIX]" --affix "(#URGENT-123)"

# Result: "🚨 feat: add new login system [JIRA-456]"
commiat --prefix "🚨" --affix "[JIRA-456]"

Order of Operations

1. AI generates the base commit message (potentially multi-line)
2. Prefix is added to the beginning of the first line (if provided)
3. Affix is added to the end of the first line (if provided)
4. Final message is presented for confirmation/editing

Example:

• AI generates:

  fix: resolve login timeout issue
  
  Updated authentication logic to handle edge cases
  

• Command: commiat --prefix "[HOTFIX] " --affix " (#12345)"
• Result:

  [HOTFIX] fix: resolve login timeout issue (#12345)
  
  Updated authentication logic to handle edge cases
  

Note: Only the first line (commit subject) is modified. The commit body remains unchanged.

Other Commands

• Edit Global Configuration (Mainly OpenRouter): Opens ~/.commiat/config in your editor. Use this primarily for the OpenRouter API key and model if not using environment variables.

  commiat config

• Configure Ollama: Interactively enable/disable Ollama, set its URL and model, and configure fallback to OpenRouter.

  commiat ollama

• Test LLM Configuration: Checks connection and basic generation using your currently configured provider (OpenRouter OR Ollama w/ fallback).

  commiat config --test

• Set --multi as Default Mode: Interactively enables or disables multi-commit mode as the default behavior for all commiat commands. Once enabled, you don't need to pass --multi to use multi-commit mode; you can disable it per-run with --no-multi if needed.

  commiat config -m
  # or
  commiat config --multi

Happy committing! 🎉