npm package: @misaelabanto/commita
Description: AI-powered git auto-commit tool that intelligently groups your changes and generates meaningful commit messages
Author: Misael Abanto
Latest version: 0.5.0

# 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](https://platform.openai.com/api-keys)
  - **Google Gemini** — get one at [aistudio.google.com/api-keys](https://aistudio.google.com/api-keys)

## Installation

### Option 1 — bun (recommended, requires [Bun](https://bun.sh) ≥ 1.0)

```bash
bun install -g @misaelabanto/commita
```

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

```bash
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](https://github.com/misaelabanto/commita/releases):

```bash
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](https://github.com/misaelabanto/commita/releases) and add it to your `PATH`.

### Local Development

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

## Quick Start

1. Set your API key and provider:
```bash
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:
```bash
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.

```bash
# 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

```bash
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:
```bash
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)

```bash
git add <files>
bun run index.ts
```

### Process All Changes

Group all unstaged changes by folder and create multiple commits:

```bash
bun run index.ts --all
```

### Ignore Patterns

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

```bash
# 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:

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

### Custom Config File

Use a different config file:

```bash
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:

```bash
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:

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

### Scenario 3: Local Commits Only

Commit without pushing to remote:

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

### Scenario 4: Using Emoji Style

Set in your `.commita`:
```
COMMIT_STYLE=emoji
```

Then run:
```bash
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:
```bash
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:
```bash
bun run index.ts  # ✓ Correct
node index.ts     # ✗ Won't work
```

## Development

```bash
bun install
bun run dev
```

### Running Tests

```bash
bun test
```

### Build to Binary

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

## Contributing

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

## License

MIT