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 Flash 1.5 ⚡) or a local Ollama instance (defaults to qwen2.5).
4. Supports custom commit message formats defined in a local .commiat file.
5. Prompts you to confirm ✅, adjust 📝, or cancel ❌ the commit.
6. 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) 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-flash-1.5, anthropic/claude-3-haiku). Defaults to google/gemini-flash-1.5.
  • 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.

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 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 Flash, 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
   
   # Combine flags
   commiat -a -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.

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

Happy committing! 🎉