# 📝 Commit Message Guide

The `commit-msg` command generates a conventional commit message based on your currently staged changes. Unlike the `commit` command, it only outputs the suggested message without actually performing the git commit.

### Why use Commit Message?

- **Consistency**: Automatically generate messages following the [Conventional Commits](https://www.conventionalcommits.org/) specification (e.g., `feat(api): add JWT authentication`).
- **Convenience**: Quickly get a descriptive summary of your changes without manually reviewing the diff.
- **Workflow flexibility**: Useful when you want to review, edit, or use the generated message in a custom git command or GUI.

### Basic Usage

```bash
git add .
grokkit commit-msg               # Generate message only
grokkit commit-msg -m grok-4     # Use specific model
```

**Output format:** `type(scope): subject\n\nbody`

### Options

| Flag | Description |
|------|-------------|
| `--model`, `-m` | Override the default model (e.g., `grok-4`) |

### How it Works

1. **Diff Retrieval**: Grokkit runs `git diff --cached --no-color` to get all staged changes.
2. **AI Analysis**: It sends the diff to Grok with instructions to generate a conventional commit message.
3. **Streaming Output**: The generated message is streamed directly to your terminal.

### Workflow Example

1. Stage your changes:
   ```bash
   git add main.go internal/grok/client.go
   ```
2. Generate the message:
   ```bash
   grokkit commit-msg
   ```
3. Use the output to commit:
   ```bash
   git commit -m "$(grokkit commit-msg)"
   ```

### Comparison with `commit` command

| Feature | `commit-msg` | `commit` |
|---------|--------------|----------|
| Generates AI message | Yes | Yes |
| Shows diff-based summary | Yes | Yes |
| Asks for confirmation | No | Yes |
| Performs `git commit` | No | Yes |
| Use case | Scripting / Manual control | Interactive git workflow |

### Best Practices

- **Stage only related changes**: To get the most accurate commit message, stage only the changes that belong to a single logical unit of work.
- **Review the output**: AI-generated messages are usually good but may need minor tweaks for complex changes.
- **Model Choice**: Use a reasoning model (`grok-4`) for complex architectural changes to get more detailed body descriptions in the commit message.