auto-commit-ai/README.md

AI-powered tool to automatically generate your git commit messages

## Setup

> The minimum supported version of Node.js is the latest v14. Check your Node.js version with `node --version`.

1. Install `aca`:

   ```sh
   npm install -g auto-commit-ai
   ```

2. Authenticate using browser:

   ```sh
   aca auth
   ```

   Opens browser for authentication. For manual entry:

   ```sh
   aca auth --manual
   ```

3. (Optional) Configure settings:

   ```sh
   aca config
   ```

   Interactive interface to customize model, locale, commit type, etc.

### Upgrading

Check the installed version with:

```sh
aca --version
```

Upgrade to the latest version:

```sh
npm update -g auto-commit-ai
```

## Usage

### CLI mode

You can call `aca` directly to generate a commit message for your staged changes:

```sh
git add <files...>
aca
```

`aca` passes down unknown flags to `git commit`, so you can pass in [`commit` flags](https://git-scm.com/docs/git-commit).

#### Available CLI flags

- **Stage all changes**: Stage all tracked file changes before committing
  ```sh
  aca --all # or -a
  ```

- **Generate multiple options**: Generate multiple commit messages to choose from
  ```sh
  aca --generate 3 # or -g 3
  ```
  > Warning: this uses more tokens, meaning it costs more.

- **Exclude files**: Exclude specific files from AI analysis
  ```sh
  aca --exclude "*.lock" --exclude "dist/*" # or -x
  ```

#### Commit message types

Configure via `aca config`:

- **None**: Standard commit messages
- **Conventional**: [Conventional Commits](https://conventionalcommits.org/) format (feat:, fix:, etc.)
- **Gitmoji**: Commit messages with emojis 😄

### Git hook

Integrate `aca` with Git via the [`prepare-commit-msg`](https://git-scm.com/docs/githooks#_prepare_commit_msg) hook. Use Git normally and edit commit messages before committing.

#### Install

In the Git repository you want to install the hook in:

```sh
aca hook install
```

#### Uninstall

In the Git repository you want to uninstall the hook from:

```sh
aca hook uninstall
```

#### Usage

1. Stage your files and commit:

   ```sh
   git add <files...>
   git commit # Only generates a message when it's not passed in
   ```

   > If you ever want to write your own message instead of generating one, you can simply pass one in: `git commit -m "My message"`

2. `aca` will generate the commit message for you and pass it back to Git. Git will open it with the [configured editor](https://docs.github.com/en/get-started/getting-started-with-git/associating-text-editors-with-git) for you to review/edit it.

3. Save and close the editor to commit!

## Configuration

### Interactive Configuration

```sh
aca config
```

React-based terminal interface to:
- Configure authentication token
- Choose AI models and commit types  
- Set language preferences
- Adjust timeout and message length
- Get real-time validation and descriptions

### Authentication Commands

```sh
aca auth              # Browser-based authentication (recommended)
aca auth --manual     # Manual token entry
```

### Options

#### Configuration Options

| Option | Default | Description |
|--------|---------|-------------|
| **authtoken** | _(required)_ | AutoCommit API authentication token |
| **locale** | `en` | Language locale for commit messages ([ISO 639-1 codes](https://wikipedia.org/wiki/List_of_ISO_639-1_codes)) |
| **generate** | `1` | Number of commit messages to generate (1-5) |
| **type** | `conventional` | Commit message format: `none`, `conventional`, `gitmoji` |
| **model** | `deepseek-v3` | AI model to use (see supported models below) |
| **timeout** | `30000` | Request timeout in milliseconds |
| **max-length** | `50` | Maximum commit message length |

#### Supported AI Models

- **deepseek-v3** - DeepSeek V3 model (default)
- **deepseek-r1** - DeepSeek R1 model  
- **gemini-2.0** - Google Gemini 2.0 model
- **gpt-4-turbo** - OpenAI GPT-4 Turbo model

#### Configuration File Locations

`aca` stores configuration in INI format:
- **Local**: `./.autoCommit` (project-specific, takes priority)
- **Global**: `~/.autoCommit` (user-wide default)

## How it works

`aca` analyzes your staged git changes and generates intelligent commit messages using advanced AI models:

1. **Change Detection**: Runs `git diff --cached` to capture your staged changes
2. **AI Analysis**: Sends the diff to your selected AI model (DeepSeek, Gemini, or GPT-4)
3. **Smart Generation**: Generates contextual commit messages based on the code changes
4. **Format Support**: Outputs in your preferred format (conventional commits, gitmoji, or standard)

The tool respects `.gitignore` patterns and automatically excludes lock files and build artifacts from analysis.