npm package: @isaacmiles/commit-scribe
Description: An AI-powered NPM package that analyzes Git diffs and automatically generates meaningful, standardised commit messages.
Author: Isaac Miles
Latest version: 0.1.0

<div style="text-align: center;">
<h1>Commit Genie ✨</h1>

<p style="font-style:italic">Let your diffs do the talking.</p>

  <a href="https://www.npmjs.com/package/commit-genie" target="_blank">
    <img src="https://img.shields.io/npm/v/commit-genie.svg" alt="npm version" />
  </a>
  <a href="https://opensource.org/licenses/MIT" target="_blank">
    <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" />
  </a>
</div>

## 🚀 Overview

`commit-genie` is an AI-powered CLI tool that streamlines your Git workflow by automatically generating meaningful, standardized commit messages based on your staged changes. Leveraging the power of large language models (LLMs), it analyzes your Git diffs and suggests commit messages that adhere to conventions like Conventional Commits.

Say goodbye to generic "fix bug" messages and hello to a clean, descriptive Git history!

## 🎯 Key Features

- **Diff Analysis:** Automatically detects and parses your staged Git changes (`git diff --staged`) to understand the context of your modifications.
- **AI Integration:** Utilizes the Gemini API to intelligently summarize changes and generate relevant commit messages.
- **Conventional Commits Support:** Generates messages formatted according to common standards (e.g., `feat:`, `fix:`, `refactor:`), promoting consistency across your team.
- **Interactive CLI:** Provides an interactive prompt to preview, edit, accept, or regenerate suggested commit messages before committing.
- **Direct Commit:** Upon acceptance, `commit-genie` can directly execute the `git commit` command with the chosen message.
- **Flexible Input:** Supports automatic diff detection, direct diff pasting, or simple descriptions via command-line arguments.

## ⚙️ Installation

To install `commit-genie` globally (recommended for CLI tools):

```bash
npm install -g commit-genie
```

Alternatively, if you prefer to use npx without global installation:

```bash
# You can run it directly using npx in your project directory
npx commit-genie
```

## 📖 Usage

**Basic Usage (Recommended)**
Navigate to your Git repository, stage your changes (`git add .`), and then simply run `commit-genie`:

```bash
# 1. Stage your changes (e.g., after making code modifications)

git add .

# 2. Run commit-genie

commit-genie
```

`commit-genie` will automatically detect your staged changes, generate a suggestion, and present an interactive prompt:

```
Attempting to retrieve staged Git changes...
Staged changes retrieved successfully.

Analyzing changes and generating message...

Suggested commit message:
feat(auth): implement JWT authentication for user login

What would you like to do?
❯ Accept (use this message)
  Edit (modify the message)
  Regenerate (get a new suggestion)
  Quit (do not commit)
```

Select `Accept` to commit with the suggested message, `Edit` to refine it, `Regenerate` for a new suggestion, or `Quit` to cancel.

### Providing Manual Input

You can also provide diff content or a description directly:

- **Direct Diff Content:**

```bash
commit-genie "diff --git a/src/index.js b/src/index.js\n--- a/src/index.js\n+++ b/src/index.js\n@@ -1,3 +1,4 @@\n console.log('Hello');\n+console.log('World');\n"
```

- **Description via --prompt:**

```bash
commit-genie --prompt "Added a new function to calculate the sum of two numbers."
```

### Interactive Editor for Diff Input

If you run `commit-genie` without any arguments and no staged changes are detected, it will prompt you to open an editor to paste your diff or describe changes manually.

## **🔑 Configuration (API Key)**

`commit-genie` requires a Gemini API key to interact with the large language model.

1. **Get your API Key:**
   Obtain your Gemini API key from [Google AI Studio](https://aistudio.google.com/app/apikey).

2. **Create a `.env` file:**
   In the root directory of your project where you run commit-genie (or the commit-genie package's root if you're developing it), create a file named `.env`.

3. **Add your API Key to `.env`:**
   GEMINI_API_KEY=YOUR_ACTUAL_GEMINI_API_KEY_HERE

4. **Add `.env` to `.gitignore` (Crucial!):**
   To prevent your API key from being committed to your Git repository, add `.env` to your `.gitignore` file:

## 🚧 Future Enhancements

- **Git Hook Integration:** Support for pre-commit or commit-msg Git hooks (e.g., via Husky or lefthook).

- **Extensible Rules:** Allow users to define custom rules, keywords, and AI prompts for tailored commit messages.

- **Local Model Support:** Explore integration with local LLMs (e.g., via llama.cpp or transformers.js) for offline usage and enhanced privacy.

- **Configuration File:** A dedicated configuration file (e.g., commit-genie.config.js) for more advanced settings.

- **More Output Formats:** Options for different commit message formats (e.g., JIRA issue keys).

## 🤝 Contributing

Contributions are welcome! If you have ideas for new features, improvements, or bug fixes, please open an issue or submit a pull request.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.