Skip to content

README.md

Latest commit

 

History

History
397 lines (285 loc) · 9.95 KB

README.md

File metadata and controls

397 lines (285 loc) · 9.95 KB

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

Installation

Option 1 — bun (requires Bun ≥ 1.0)

bun install -g @miselabanto/commita

Option 2 — 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
  1. 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