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
• Auto-Push: Automatically pushes commits to remote (can be disabled)

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)

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

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>
bun run index.ts

Process All Changes

Group all unstaged changes by folder and create multiple commits:

bun run index.ts --all

Ignore Patterns

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

# Ignore entire directories by name
bun run index.ts --all --ignore "dumps,node_modules"

# Ignore files by extension
bun run index.ts --all --ignore "*.log,*.csv"

# Mix folder names and glob patterns
bun run index.ts --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:

bun run index.ts --all --no-push

Custom Config File

Use a different config file:

bun run index.ts --config .commita.local

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: ignores staged files and processes all unstaged changes grouped by folders
• 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 restages and commits each group for you.
• 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:

bun run index.ts --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:

bun run index.ts --all --ignore "dist,*.log,coverage"

Scenario 3: Local Commits Only

Commit without pushing to remote:

bun run index.ts --all --no-push

Scenario 4: Using Emoji Style

Set in your .commita:

COMMIT_STYLE=emoji

Then run:

bun run index.ts --all

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: bun run index.ts --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)

Permission Denied

Make sure the script is executable:

chmod +x index.ts

Import Errors

The project uses Bun's built-in support for @/ path aliases. Make sure you're running with Bun, not Node.js:

bun run index.ts  # ✓ Correct
node index.ts     # ✗ Won't work

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