Skip to content

Commit

Permalink
fix(README): Fix readme to be easier to read and understand
Browse files Browse the repository at this point in the history
  • Loading branch information
@negoziator
negoziator committed Oct 12, 2023
1 parent dcb628e commit 91fdbed
Showing 1 changed file with 37 additions and 219 deletions.
256 changes: 37 additions & 219 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,25 +1,35 @@
<div align="center">
<h1>🤖 AI-Commit 🤖 </h1>
<h1>🤖 AI-Commit 🤖</h1>
<p>Your coding companion, ensures that every commit you make is meaningful, insightful, and contributing positively towards your development workflow.</p>
<a href="https://www.npmjs.com/package/@negoziator/ai-commit"><img src="https://img.shields.io/npm/v/@negoziator/ai-commit" alt="Current version"></a>
</div>

---
## Setup

> The minimum supported version of Node.js is the latest v14. Check your Node.js version with `node --version`.
## Table of Contents
- [Setup](#setup)
- [Installation](#installation)
- [Upgrading](#upgrading)
- [Usage](#usage)
- [CLI Mode](#cli-mode)
- [Configuration](#configuration)
- [Options](#options)
- [Maintainers](#maintainers)
- [Contributing](#contributing)

1. Install _ai-commit_:
## Setup
> A minimum of Node v18 is required. Check your Node.js version with `node --version`.
```sh
npm install -g @negoziator/ai-commit
```
### Installation
1. **Install AI-Commit:**
```sh
npm install -g @negoziator/ai-commit

2. Retrieve your API key from [OpenAI](https://platform.openai.com/account/api-keys)
2. **Retrieve your API key from [OpenAI](https://platform.openai.com/account/api-keys)**

> Note: If you haven't already, you'll have to create an account and set up billing.
> Note: This requires an OpenAI account. If you don't have one, you can sign up for a free trial.
3. Set the key so aicommit can use it:
3. **Set the key so aicommit can use it:**
```sh
aicommit config set OPENAI_KEY=<your token>
Expand All @@ -29,251 +39,59 @@
### Upgrading
Check the installed version with:

```
aicommit --version
```
If it's not the [latest version](https://github.com/negoziator/aicommit/releases/latest), run:
```sh
npm update -g @negoziator/ai-commit
```
## Usage
### CLI mode
### CLI Mode
You can call `aicommit` directly to generate a commit message for your staged changes:
Use `aicommit` directly to generate a commit message for your staged changes:
```sh
git add <files...>
aicommit
```
`aicommit` passes down unknown flags to `git commit`, so you can pass
in [`commit` flags](https://git-scm.com/docs/git-commit).

For example, you can stage all changes in tracked files with as you commit:

```sh
aicommit --all # or -a
```

> 👉**Tip:** Use the `aic` alias if `aicommit` is too long for you.
#### Generate multiple recommendations

Sometimes the recommended commit message isn't the best so you want it to generate a few to pick from. You can generate
multiple commit messages at once by passing in the `--generate <i>` flag, where 'i' is the number of generated messages:

```sh
aicommit --generate <i> # or -g <i>
```

> Warning: this uses more tokens, meaning it costs more.
#### Generating Conventional Commits

If you'd like to generate [Conventional Commits](https://conventionalcommits.org/), you can use the `--type` flag
followed by `conventional`. This will prompt `aicommit` to format the commit message according to the Conventional
Commits specification:

```sh
aicommit --type conventional # or -t conventional
```

This feature can be useful if your project follows the Conventional Commits standard or if you're using tools that rely
on this commit format.

### Git hook

You can also integrate _aicommit_ with Git via
the [`prepare-commit-msg`](https://git-scm.com/docs/githooks#_prepare_commit_msg) hook. This lets you use Git like you
normally would, and edit the commit message before committing.

#### Install

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

```sh
aicommit hook install
```

#### Uninstall

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

```sh
aicommit 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. aicommit 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
Manage configuration using the `aicommit config` command.
### Reading a configuration value

To retrieve a configuration option, use the command:
To get a configuration option value, use the command:
```sh
aicommit config get <key>
```

For example, to retrieve the API key, you can use:
```sh
aicommit config get OPENAI_KEY
> sk_1234567890
```
You can also retrieve multiple configuration options at once by separating them with spaces:

```sh
aicommit config get OPENAI_KEY generate
```

### Setting a configuration value

To set a configuration option, use the command:
```sh
aicommit config set <key>=<value>
```
For example, to set the API key, you can use:

```sh
aicommit config set OPENAI_KEY=<your-api-key>
```

You can also set multiple configuration options at once by separating them with spaces, like

```sh
aicommit config set OPENAI_KEY=<your-api-key> generate=3 locale=en
```

### Options
#### OPENAI_KEY

Required

The OpenAI API key. You can retrieve it from [OpenAI API Keys page](https://platform.openai.com/account/api-keys).

#### locale

Default: `en`

The locale to use for the generated commit messages. Consult the list of codes
in: https://wikipedia.org/wiki/List_of_ISO_639-1_codes.

#### generate

Default: `1`

The number of commit messages to generate to pick from.

Note, this will use more tokens as it generates more results.

#### model

Default: `gpt-3.5-turbo`

The Chat Completions (`/v1/chat/completions`) model to use. Consult the list of models available in
the [OpenAI Documentation](https://platform.openai.com/docs/models/model-endpoint-compatibility).

> Tip: If you have access, try upgrading to [`gpt-4`](https://platform.openai.com/docs/models/gpt-4) for next-level code
> analysis. It can handle double the input size, but comes at a higher cost. Check out OpenAI's website to learn more.
#### timeout
The timeout for network requests to the OpenAI API in milliseconds.
Default: `10000` (10 seconds)
```sh
aicommit config set timeout=20000 # 20s
```
#### max-length
The maximum character length of the generated commit message.
Default: `50`
```sh
aicommit config set max-length=100
```
#### type
Default: `""` (Empty string)
The type of commit message to generate. Set this to "conventional" to generate commit messages that follow the
Conventional Commits specification:
```sh
aicommit config set type=conventional
```
You can clear this option by setting it to an empty string:
```sh
aicommit config set type=
```
#### auto-confirm
Default: `false`
Automatically confirm the generated commit message without prompting the user.
```sh
aicommit config set auto-confirm=true
```
#### prepend-reference
Default: `false`
Prepends issue reference from branch name to commit message.
branch name: `feature/abc-123-branch-name`
commit message: `ABC-123: <generated commit message>`
```sh
aicommit config set prepend-reference=true
```
## How it works
This CLI tool runs `git diff` to grab all your latest code changes, sends them to OpenAI's GPT-3, then returns the AI
generated commit message.

Video coming soon where I rebuild it from scratch to show you how to easily build your own CLI tools powered by AI.
| Option | Default | Description |
|---------------------|----------------|-------------------------------------------------------------------------|
| `OPENAI_KEY` | N/A | The OpenAI API key. |
| `locale` | `en` | Locale for the generated commit messages. |
| `generate` | `1` | Number of commit messages to generate. |
| `model` | `gpt-3.5-turbo`| The Chat Completions model to use. |
| `timeout` | `10000` ms | Network request timeout to the OpenAI API. |
| `max-length` | `50` | Maximum character length of the generated commit message. |
| `type` | `""` | Type of commit message to generate. |
| `auto-confirm` | `false` | Automatically confirm the generated commit message without user prompt. |
| `prepend-reference` | `false` | Prepend issue reference from branch name to commit message. |
## Maintainers

- **Lars Schou**: [@NegoZiatoR](https://github.com/NegoZiatoR) [<img src="https://img.shields.io/twitter/follow/negoziator?style=flat&label=negoziator&logo=twitter&color=0bf&logoColor=fff" align="center">](https://twitter.com/negoziator)
- **Lars Schou**: <img src="https://img.shields.io/twitter/follow/negoziator?style=flat&label=negoziator&logo=twitter&color=0bf&logoColor=fff" align="center">
## Contributing

If you want to help fix a bug or implement a feature in [Issues](https://github.com/negoziator/ai-commit/issues), checkout
the [Contribution Guide](CONTRIBUTING.md) to learn how to setup and test the project.

0 comments on commit 91fdbed

Please sign in to comment.