Commita 🤖

AI-powered git auto-commit tool that intelligently groups your changes and generates meaningful commit messages.

Features

• AI-Generated Commit Messages: Uses OpenAI or Google Gemini to analyze diffs and create descriptive commit messages
• Multiple AI Providers: Support for both OpenAI and Google Gemini via the Vercel AI SDK
• Intelligent File Grouping: Automatically groups files by their directory structure for organized commits
• Configurable: Customize prompts, models, and commit styles
• Multiple Commit Styles: Support for conventional commits and emoji commits
• Bulk Operations: Process all changes at once with the --all flag
• Pattern Filtering: Exclude files using glob patterns with --ignore
• Intent Context: Steer messages with a free-text hint via --context (or --context-file) so they reflect what you meant, not just what the diff looks like
• Auto-Push: Automatically pushes commits to remote (can be disabled)
• Dry Run: Preview commit groups and AI-generated messages without committing using --dry-run
• Status Summary: Inspect staged/unstaged changes grouped by scope with --status
• Hook Bypass: Skip git pre-commit and commit-msg hooks with --no-verify

Requirements

• An API key from one of the supported AI providers:
  • OpenAI — get one at platform.openai.com/api-keys
  • Google Gemini — get one at aistudio.google.com/api-keys

Installation

Option 1 — bun (recommended, requires Bun ≥ 1.0)

bun install -g @misaelabanto/commita

Option 2 — npm (requires Node.js ≥ 18)

npm install -g @misaelabanto/commita

Option 3 — Shell script (no runtime required)

Downloads the correct pre-compiled binary for your OS and architecture directly from GitHub Releases:

curl -fsSL https://raw.githubusercontent.com/misaelabanto/commita/main/install.sh | bash

Supported platforms:

| OS | x86_64 | arm64 | |---------|-------------------------|-------| | macOS | ✅ | ✅ | | Linux | ✅ | ✅ | | Windows | ✅ (manual download) ¹ | ❌ |

¹ Windows users: download commita-windows-amd64.exe manually from the Releases page and add it to your PATH.

Local Development

git clone https://github.com/misaelabanto/commita.git
cd commita
bun install

Quick Start

1. Set your API key and provider:

commita set OPENAI_API_KEY=sk-...
# or for Gemini:
commita set GEMINI_API_KEY=your-key
commita set PROVIDER=gemini

2. Navigate to your project and run:

commita --all

Configuration

commita set (recommended)

Set config values from the command line. By default values are saved globally to ~/.commita. Use --local to save them to .commita in the current project instead.

# Set values directly
commita set PROVIDER=openai
commita set MODEL=gpt-4o-mini

# Omit the value to be prompted securely (input is hidden for API keys)
commita set OPENAI_API_KEY
commita set GEMINI_API_KEY

# Save to the current project only
commita set PROVIDER=gemini --local

.commita file (manual)

You can also create or edit a .commita file directly. Project-level (./.commita) takes precedence over global (~/.commita).

PROVIDER=openai
MODEL=gpt-4o-mini
PROMPT_STYLE=default
COMMIT_STYLE=conventional
OPENAI_API_KEY=sk-...

Or for Gemini:

PROVIDER=gemini
MODEL=gemini-2.5-flash
PROMPT_STYLE=default
COMMIT_STYLE=conventional
GEMINI_API_KEY=your-gemini-api-key

Environment Variables

export COMMITA_PROVIDER=openai
export COMMITA_MODEL=gpt-4o-mini
export COMMITA_PROMPT_STYLE=default
export COMMITA_COMMIT_STYLE=emoji
export OPENAI_API_KEY=sk-...

Or for Gemini:

export COMMITA_PROVIDER=gemini
export COMMITA_MODEL=gemini-2.5-flash
export GEMINI_API_KEY=your-gemini-api-key

Configuration Options

• PROVIDER: AI provider to use - openai or gemini (default: openai)
• MODEL: Model name to use (provider-specific)
  • OpenAI: gpt-4o-mini, gpt-4o, gpt-4-turbo, etc.
  • Gemini: gemini-2.5-flash, gemini-2.5-pro, gemini-1.5-pro, etc.
• PROMPT_STYLE: One of default, detailed, minimal, or custom
• PROMPT_TEMPLATE: Custom prompt template (when using custom style)
• CUSTOM_PROMPT: Complete custom prompt (when using custom style)
• COMMIT_STYLE: Either conventional or emoji
• OPENAI_API_KEY: Your OpenAI API key (required when PROVIDER=openai)
• GEMINI_API_KEY: Your Gemini API key (required when PROVIDER=gemini)
• GROUP_DEPTH: Grouping depth for files outside a detected project (default: 2, minimum 1)
• MAX_FILES_PER_GROUP: Auto-split groups larger than this into multiple commits (default: 0 = off)
• CONFIRM_THRESHOLD: File count at/above which a run requires confirmation (default: 100)
• DEFAULT_IGNORES: Whether to apply the built-in build/VCS-noise grouping ignore set (default: true)
• ATOMIC: Roll back all commits from a run if any group fails (default: false)
• REQUIRE_CLEAN_INDEX: Abort a --all run when the index already has staged changes (default: false)

Note: You can also use GOOGLE_GENERATIVE_AI_API_KEY environment variable instead of GEMINI_API_KEY.

Note: Every config key above can also be set via a COMMITA_-prefixed environment variable (e.g. COMMITA_GROUP_DEPTH=3).

Prompt Styles

• default: Balanced analysis with clear instructions
• detailed: Deep analysis of code changes with context
• minimal: Quick, concise commit messages
• custom: Use your own prompt via PROMPT_TEMPLATE or CUSTOM_PROMPT

Using Custom Prompts

You can create your own prompt template using the {diff} placeholder:

PROMPT_STYLE=custom
CUSTOM_PROMPT=Analyze this diff and create a commit message: {diff}

Or use PROMPT_TEMPLATE for longer prompts:

PROMPT_STYLE=custom
PROMPT_TEMPLATE=You are an expert developer. Analyze the following changes and generate a clear commit message in conventional commit format. The diff is: {diff}

Commit Styles

Conventional Commits:

feat(components): add new button component
fix(utils): correct string formatting bug
refactor(services): restructure API client

Emoji Commits:

✨(components): add new button component
🐛(utils): correct string formatting bug
♻️(services): restructure API client

Emoji mappings:

• feat → ✨
• fix → 🐛
• refactor → ♻️
• chore → 🔧
• docs → 📝
• style → 💄
• test → ✅
• perf → ⚡

Usage

Important: You must either have staged changes OR use the --all flag. The tool requires one of these to proceed.

Basic Usage (with staged changes)

git add <files>
commita

Process All Changes

Group all unstaged changes by folder and create multiple commits:

commita --all

Dry Run

Preview the commit groups and AI-generated messages without actually committing or pushing:

commita --all --dry-run
# or short form
commita --all -d

Show Status

Display a grouped summary of staged and unstaged changes (after applying --ignore patterns) without running the AI or committing:

commita --status
# or short form
commita -s

# Combine with --ignore to preview filtering
commita --status --ignore "dist,*.log"

Ignore Patterns

Exclude files matching glob patterns. You can use folder names, glob wildcards, or both:

# Ignore entire directories by name
commita --all --ignore "dumps,node_modules"

# Ignore files by extension
commita --all --ignore "*.log,*.csv"

# Mix folder names and glob patterns
commita --all --ignore "dumps,*.log,dist/*"

Note: Bare folder names like dumps automatically match all files inside that folder (equivalent to dumps/**).

Skip Pushing

Don't push commits to remote:

commita --all --no-push

Skip Git Hooks

Bypass git pre-commit and commit-msg hooks (equivalent to git commit --no-verify):

commita --all --no-verify

Custom Config File

Use a different config file:

commita --config .commita.local

Provide Context

Commita generates messages from the diff alone, which can produce confidently wrong bullets (e.g. reading a moved line as a deletion). Pass --context / -x to describe your intent. The text is included in the prompt for every group and is treated as authoritative when it conflicts with what the diff appears to show:

commita -a --context "Count query moved into the SET LOCAL transaction, not removed"

For longer notes, read the context from a file with --context-file (mutually exclusive with --context):

commita -a --context-file .commit-notes.md

Pair it with --dry-run to preview how the context changes the generated messages before anything is committed:

commita -a -x "Implements trigram search" --dry-run

Notes:

• Context is per-run only. There is intentionally no .commita key or env var, so a stale note can't silently poison future runs.
• Context is capped at 2000 characters; longer input is rejected with an error.
• Commita only describes changes actually present in each group's diff, so a shared context won't bleed unrelated bullets into groups whose files don't include the described work.

All CLI Options

| Flag | Short | Description | |------|-------|-------------| | --all | -a | Process all changes grouped by folders | | --ignore <patterns> | -i | Comma-separated glob patterns to exclude | | --dry-run | -d | Show commit groups and messages without committing | | --status | -s | Show a summary of staged and unstaged changes | | --config <path> | -c | Path to custom config file | | --context <text> | -x | Free-text intent passed to the LLM alongside the diff for every group | | --context-file <path> | | Read --context from a file (mutually exclusive with --context) | | --depth <n> | | Grouping depth for files outside a detected project (default: 2) | | --max-files-per-group <n> | | Auto-split groups larger than n into multiple commits (0 = off) | | --atomic | | Roll back all commits from this run if any group fails | | --require-clean-index | | Abort if the index has pre-staged changes when using --all | | --yes | -y | Skip confirmation prompts for large or pushed runs | | --confirm-threshold <n> | | File count at/above which confirmation is required (default: 100) | | --no-default-ignores | | Disable the built-in build/VCS-noise grouping ignore set | | --no-push | | Skip pushing after commit | | --no-verify | | Bypass git pre-commit and commit-msg hooks | | --version | -v | Show version number |

Grouping, Safety, and Recovery

• Grouping depth (--depth, config GROUP_DEPTH): files that do not belong to a detected project (no package.json, Cargo.toml, etc. above them) are grouped by their top n directories instead of being lumped into a single root commit. Only true repo-root files land in root.
• Auto-split (--max-files-per-group, config MAX_FILES_PER_GROUP): caps how many files a single commit can contain, splitting oversized groups into scope (part k/N) commits with a warning.
• Default noise filtering (config DEFAULT_IGNORES, on by default): build/VCS artifacts (**/build/, **/.gradle/, dist/, node_modules/, **/target/, **/.next/, coverage/, ...) are excluded from grouping. They merge with any --ignore patterns. Pass --no-default-ignores to include them.
• Confirmation gate (--confirm-threshold, config CONFIRM_THRESHOLD): when a run touches at least this many files, commita prints the plan and asks for confirmation. Pass --yes/-y to skip the prompt. In a non-interactive shell an over-threshold run aborts unless --yes is given.
• Recovery (--atomic, config ATOMIC): if a group fails partway through a run, commita prints the created commit SHAs and a git reset --soft <pre-run-sha> undo hint. With --atomic it rolls those commits back automatically and never pushes a partial run.
• Clean-index enforcement (--require-clean-index, config REQUIRE_CLEAN_INDEX): abort a --all run if anything is already staged, instead of folding it into the grouping.

How It Works

Flow Example

Given these changes:

src/components/button.tsx
src/components/carousel.tsx
src/utils/url.ts
src/utils/strings.ts
src/services/ai/ai.ts
src/services/profile/profile.ts

Running commita --all will create commits like:

feat(components): add new UI components
- Implement Button component with variants
- Add Carousel with auto-play feature

feat(utils): enhance utility functions
- Add URL parsing helper
- Improve string manipulation utilities

fix(ai): correct API integration
- Fix authentication flow
- Handle rate limiting

refactor(profile): restructure profile service
- Separate types into dedicated file
- Improve error handling

Staged Changes Behavior

Requirements: You must provide either:

• Staged changes (via git add), OR
• The --all flag

Behavior:

• If you have staged changes and run without --all: processes staged files, grouped by folders, and creates multiple commits
• If you have staged changes and run with --all: the pre-staged files are unstaged and regrouped together with the rest of your changes, so each file is committed in its correct group (pass --require-clean-index to abort instead)
• If you have no staged changes and run without --all: exits with error
• Note: Commita temporarily unstages the files you selected so it can create one commit per folder, then commits each group with an explicit pathspec so a commit only ever contains its own group's files.
• Use this to control exactly which files get committed together

Advanced Usage Examples

Scenario 1: Multiple Feature Commits

You've been working on several features and want to commit them separately:

commita --all

This will group files by their directories and create separate commits for each group.

Scenario 2: Exclude Generated Files

Ignore build artifacts and logs:

commita --all --ignore "dist,*.log,coverage"

Scenario 3: Local Commits Only

Commit without pushing to remote:

commita --all --no-push

Scenario 4: Using Emoji Style

Set in your .commita:

COMMIT_STYLE=emoji

Then run:

commita --all

Scenario 5: Preview Before Committing

Generate and review the AI commit messages without making any changes to your repository:

commita --all --dry-run

Scenario 6: Bypass Pre-Commit Hooks

When you need to commit through hooks that aren't relevant to this change:

commita --all --no-verify

Troubleshooting

"OpenAI API key is required" or "Gemini API key is required"

Make sure you have set your API key for the selected provider:

For OpenAI:

• .commita file: OPENAI_API_KEY=sk-...
• Environment variable: export OPENAI_API_KEY=sk-...

For Gemini:

• .commita file: GEMINI_API_KEY=your-key
• Environment variable: export GEMINI_API_KEY=your-key
• Or use: export GOOGLE_GENERATIVE_AI_API_KEY=your-key

"No staged changes found"

This error occurs when you run the tool without the --all flag and have no staged changes. Either:

• Stage some changes: git add <files>
• Use the --all flag: commita --all

Provider Selection

Make sure you've selected the correct provider and set the corresponding API key:

• Set PROVIDER=openai and provide OPENAI_API_KEY
• Set PROVIDER=gemini and provide GEMINI_API_KEY (or GOOGLE_GENERATIVE_AI_API_KEY)

Running From Source (Local Development Only)

If you cloned the repo instead of installing the commita binary, run the entry file with Bun — @/ path aliases require it:

bun run index.ts          # ✓ Correct
node index.ts             # ✗ Won't work (no Bun path-alias support)

If you hit a permission error invoking index.ts directly, make sure it's executable:

chmod +x index.ts

Development

bun install
bun run dev

Running Tests

bun test

Build to Binary

bun build index.ts --compile --outfile commita

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT