docs: update README and package.json for v0.2.0
- Full README rewrite with all new commands, pipe support, aliases, global flags, and configuration examples - Bump version to 0.2.0, update description
This commit is contained in:
@@ -2,14 +2,13 @@
|
|||||||
|
|
||||||
# gai
|
# gai
|
||||||
|
|
||||||
**AI-powered Git commit and pull request helper**
|
**AI-powered Git helper — commit messages, PRs, code review, changelogs, and more**
|
||||||
|
|
||||||
[](https://git.catpl.top/Mplan/gai/releases)
|
|
||||||
[](./LICENSE)
|
[](./LICENSE)
|
||||||
[](https://bun.sh)
|
[](https://bun.sh)
|
||||||
[](https://www.typescriptlang.org/)
|
[](https://www.typescriptlang.org/)
|
||||||
|
|
||||||
Generate **Conventional Commits** messages and pull request descriptions using AI, based on your project context, code diff, branch changes, and commit history.
|
Generate **Conventional Commits** messages, pull request descriptions, code reviews, changelogs, and more — powered by AI with full project context.
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
@@ -17,15 +16,18 @@ Generate **Conventional Commits** messages and pull request descriptions using A
|
|||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- **Interactive menu** — `gai` opens a menu, select actions with ↑/↓ + space/enter
|
- **🤖 AI Commit Messages** — generate Conventional Commits from staged diffs with project context
|
||||||
- **Context-aware commits** — reads project overview, staged diff, and recent commit history
|
- **🔀 AI Pull Requests** — create GitHub, Gitea, or GitLab PRs with AI-generated title and body
|
||||||
- **Conventional Commits** — `feat(scope): description` format by default
|
- **📖 Explain Changes** — `gai explain` explains diffs in plain language
|
||||||
- **Interactive file selection** — ↑/↓ to navigate, space to select, top-level "Select all"
|
- **🔍 Code Review** — `gai review` provides thorough, constructive code review
|
||||||
- **Inline editing** — edit AI-generated messages right in the terminal with cursor movement
|
- **📝 Changelog Generation** — `gai changelog` generates user-facing changelogs from commits
|
||||||
- **AI-generated PRs** — create GitHub, Gitea, or GitLab pull requests with generated title and body
|
- **💡 Smart Suggestions** — `gai suggest` recommends branch names or commit types
|
||||||
- **OpenAI-compatible API** — works with DeepSeek, OpenAI, Ollama, OpenRouter, and more
|
- **✏️ Amend Commits** — `gai commit --amend` amends with AI-generated message
|
||||||
- **Review before commit** — confirm, edit, or abort the generated message
|
- **⚡ Streaming Output** — AI responses stream token-by-token for instant feedback
|
||||||
- **Bun-native runtime** — built on Bun APIs with no runtime npm dependencies
|
- **📂 Interactive File Selection** — ↑/↓ navigate, space toggle, "Select all" support
|
||||||
|
- **📋 Pipe Support** — pipe diffs directly: `git diff | gai explain`
|
||||||
|
- **🎨 Mainstream CLI UX** — proper flags, aliases, `--help` per command, `--no-color`
|
||||||
|
- **🔧 OpenAI-compatible API** — works with DeepSeek, OpenAI, Ollama, OpenRouter, and more
|
||||||
|
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
@@ -39,25 +41,79 @@ gai config
|
|||||||
# Open interactive menu
|
# Open interactive menu
|
||||||
gai
|
gai
|
||||||
|
|
||||||
# Or directly generate a commit message
|
# Generate a commit message
|
||||||
gai commit
|
gai commit
|
||||||
|
|
||||||
# Or create an AI-generated pull request
|
# Explain your changes
|
||||||
gai pr
|
gai explain
|
||||||
```
|
```
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
```
|
```
|
||||||
gai Open interactive menu
|
gai Open interactive menu
|
||||||
gai commit Generate commit message (interactive file selection)
|
gai commit Generate AI commit message (interactive file selection)
|
||||||
gai commit --auto Auto-stage all changed files
|
gai commit -a Auto-stage all changed files
|
||||||
gai commit -d Generate message without committing
|
gai commit -d Generate message without committing
|
||||||
gai pr Create a PR with AI-generated title and body
|
gai commit -m "msg" Use custom message (skip AI)
|
||||||
gai pr --draft Create a draft PR
|
gai commit --amend Amend last commit with AI-generated message
|
||||||
gai config Configure API settings
|
gai pr Create a PR with AI-generated title and body
|
||||||
gai --help Show help
|
gai pr --draft Create a draft PR
|
||||||
gai --version Show version
|
gai explain Explain staged changes in plain language
|
||||||
|
gai explain --unstaged Explain unstaged changes
|
||||||
|
gai review AI code review of staged changes
|
||||||
|
gai review --strict Thorough review, flag minor issues
|
||||||
|
gai review --lenient Focus only on major issues
|
||||||
|
gai changelog Generate changelog from recent commits
|
||||||
|
gai changelog --from v1.0 --to v1.1 Range-based changelog
|
||||||
|
gai suggest branch Suggest branch names for current changes
|
||||||
|
gai suggest type Suggest Conventional Commit type
|
||||||
|
gai config Configure API settings (interactive)
|
||||||
|
gai config list List all settings
|
||||||
|
gai config get <key> Get a specific setting
|
||||||
|
gai config set <key> <v> Set a setting
|
||||||
|
gai help Show help
|
||||||
|
gai help <command> Show command-specific help
|
||||||
|
gai --version Show version
|
||||||
|
```
|
||||||
|
|
||||||
|
### Global Flags
|
||||||
|
|
||||||
|
| Flag | Description |
|
||||||
|
|---|---|
|
||||||
|
| `-h, --help` | Show help |
|
||||||
|
| `-V, --version` | Show version |
|
||||||
|
| `-v, --verbose` | Verbose output |
|
||||||
|
| `--no-color` | Disable colored output |
|
||||||
|
|
||||||
|
Also respects the `NO_COLOR` and `FORCE_COLOR` environment variables.
|
||||||
|
|
||||||
|
### Subcommand Aliases
|
||||||
|
|
||||||
|
| Command | Aliases |
|
||||||
|
|---|---|
|
||||||
|
| `commit` | `c`, `ci` |
|
||||||
|
| `pr` | `p` |
|
||||||
|
| `config` | `cfg` |
|
||||||
|
| `explain` | `x` |
|
||||||
|
| `review` | `r`, `rv` |
|
||||||
|
| `changelog` | `cl`, `log` |
|
||||||
|
| `suggest` | `sg` |
|
||||||
|
| `help` | `h` |
|
||||||
|
|
||||||
|
### Pipe Support
|
||||||
|
|
||||||
|
All AI commands accept piped input — no git repository required:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Explain any diff
|
||||||
|
git diff main..feature | gai explain
|
||||||
|
|
||||||
|
# Review changes from a PR
|
||||||
|
curl https://patch-diff.githubusercontent.com/... | gai review
|
||||||
|
|
||||||
|
# Suggest branch name for a diff
|
||||||
|
git diff | gai suggest branch
|
||||||
```
|
```
|
||||||
|
|
||||||
### Interactive Menu
|
### Interactive Menu
|
||||||
@@ -66,58 +122,105 @@ gai --version Show version
|
|||||||
$ gai
|
$ gai
|
||||||
|
|
||||||
gai
|
gai
|
||||||
Choose a workflow
|
AI-powered git helper — choose a workflow
|
||||||
↑/↓ navigate · enter/space select · ctrl+c cancel
|
↑/↓ navigate · enter/space select · ctrl+c cancel
|
||||||
|
|
||||||
❯ ● commit Generate AI commit message
|
❯ ● commit Generate AI commit message
|
||||||
○ pr Create a PR with AI-generated title
|
○ pr Create a PR with AI-generated title
|
||||||
○ config Configure API settings
|
○ explain Explain staged changes in plain language
|
||||||
|
○ review AI code review of staged changes
|
||||||
|
○ changelog Generate changelog from commits
|
||||||
|
○ suggest Suggest branch name or commit type
|
||||||
|
○ amend Amend last commit with AI message
|
||||||
|
○ config Configure API settings
|
||||||
```
|
```
|
||||||
|
|
||||||
### Commit Flow
|
### Command Examples
|
||||||
|
|
||||||
```
|
#### Commit
|
||||||
$ gai commit
|
|
||||||
|
|
||||||
Staged files (will be included):
|
|
||||||
✓ src/git.ts (modified)
|
|
||||||
|
|
||||||
Select files to stage:
|
|
||||||
2 unstaged files available
|
|
||||||
↑/↓ navigate · space toggle · enter confirm · ←/backspace back · ctrl+c cancel
|
|
||||||
|
|
||||||
❯ □ Select all
|
|
||||||
□ src/ai.ts modified
|
|
||||||
■ src/newfile.ts new
|
|
||||||
|
|
||||||
Generating commit message...
|
|
||||||
|
|
||||||
Generated commit message:
|
|
||||||
feat(git): add interactive file staging and commit wrapper
|
|
||||||
|
|
||||||
Use this message? [Y/n/e] Y
|
|
||||||
|
|
||||||
✔ Committed successfully!
|
|
||||||
[main a3f7c2b] feat(git): add interactive file staging and commit wrapper
|
|
||||||
1 file changed, 45 insertions(+), 12 deletions(-)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Pull Request Flow
|
|
||||||
|
|
||||||
`gai pr` detects the remote platform from `origin`:
|
|
||||||
|
|
||||||
- GitHub remotes use the `gh` CLI
|
|
||||||
- Gitea remotes use the `tea` CLI
|
|
||||||
- GitLab remotes use the `glab` CLI
|
|
||||||
- Unknown remotes prompt you to choose a platform
|
|
||||||
|
|
||||||
The command compares your current branch against the default branch, pushes the branch if needed, generates a PR title/body from the branch commits and diff, then asks for confirmation before creating the PR.
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
# Interactive file selection
|
||||||
|
gai commit
|
||||||
|
|
||||||
|
# Auto-stage everything
|
||||||
|
gai commit -a
|
||||||
|
|
||||||
|
# Dry-run (no commit)
|
||||||
|
gai commit -d
|
||||||
|
|
||||||
|
# Custom message (skip AI)
|
||||||
|
gai commit -m "fix: correct typo in README"
|
||||||
|
|
||||||
|
# Amend last commit with AI message
|
||||||
|
gai commit --amend
|
||||||
|
|
||||||
|
# Pipe diff for commit message
|
||||||
|
git diff --staged | gai commit
|
||||||
|
```
|
||||||
|
|
||||||
|
#### PR
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create PR
|
||||||
gai pr
|
gai pr
|
||||||
|
|
||||||
|
# Draft PR
|
||||||
gai pr --draft
|
gai pr --draft
|
||||||
```
|
```
|
||||||
|
|
||||||
|
#### Explain
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Explain staged changes
|
||||||
|
gai explain
|
||||||
|
|
||||||
|
# Explain unstaged changes
|
||||||
|
gai explain --unstaged
|
||||||
|
|
||||||
|
# Pipe any diff
|
||||||
|
git diff HEAD~3 | gai explain
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Review
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Review staged changes (normal strictness)
|
||||||
|
gai review
|
||||||
|
|
||||||
|
# Thorough review
|
||||||
|
gai review --strict
|
||||||
|
|
||||||
|
# Lenient review
|
||||||
|
gai review --lenient
|
||||||
|
|
||||||
|
# Review unstaged changes
|
||||||
|
gai review --unstaged
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Changelog
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# From last 20 commits
|
||||||
|
gai changelog
|
||||||
|
|
||||||
|
# Custom count
|
||||||
|
gai changelog -n 50
|
||||||
|
|
||||||
|
# Between tags
|
||||||
|
gai changelog --from v1.0.0 --to v1.1.0
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Suggest
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Suggest branch name
|
||||||
|
gai suggest branch
|
||||||
|
|
||||||
|
# Suggest commit type
|
||||||
|
gai suggest type
|
||||||
|
```
|
||||||
|
|
||||||
## Configuration
|
## Configuration
|
||||||
|
|
||||||
### Via `gai config` (interactive)
|
### Via `gai config` (interactive)
|
||||||
@@ -126,6 +229,15 @@ gai pr --draft
|
|||||||
gai config
|
gai config
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### CLI-based config
|
||||||
|
|
||||||
|
```bash
|
||||||
|
gai config list
|
||||||
|
gai config get model
|
||||||
|
gai config set model gpt-4o
|
||||||
|
gai config set temperature 0.3
|
||||||
|
```
|
||||||
|
|
||||||
### Via environment variables
|
### Via environment variables
|
||||||
|
|
||||||
| Variable | Default | Description |
|
| Variable | Default | Description |
|
||||||
@@ -193,13 +305,14 @@ GAI_MODEL=anthropic/claude-sonnet-4
|
|||||||
│ │
|
│ │
|
||||||
│ 2. Collect code changes │
|
│ 2. Collect code changes │
|
||||||
│ ├─ git diff --staged for commits │
|
│ ├─ git diff --staged for commits │
|
||||||
│ └─ branch diff for pull requests │
|
│ ├─ Branch diff for pull requests │
|
||||||
|
│ └─ Pipe support for external diffs │
|
||||||
│ │
|
│ │
|
||||||
│ 3. Collect commit history │
|
│ 3. Collect commit history │
|
||||||
│ ├─ git log --oneline -10 for commits │
|
│ ├─ git log --oneline -10 for commits │
|
||||||
│ └─ branch commits for pull requests │
|
│ └─ Branch commits for pull requests │
|
||||||
│ │
|
│ │
|
||||||
│ 4. Build prompt → Call AI API │
|
│ 4. Build prompt → Call AI API (streaming) │
|
||||||
│ │
|
│ │
|
||||||
│ 5. Review → Confirm → Commit or Create PR │
|
│ 5. Review → Confirm → Commit or Create PR │
|
||||||
└─────────────────────────────────────────────┘
|
└─────────────────────────────────────────────┘
|
||||||
|
|||||||
+2
-2
@@ -1,7 +1,7 @@
|
|||||||
{
|
{
|
||||||
"name": "gai",
|
"name": "gai",
|
||||||
"version": "0.1.2",
|
"version": "0.2.0",
|
||||||
"description": "AI-powered git commit message generator",
|
"description": "AI-powered git helper — commit messages, PRs, code review, changelogs, and more",
|
||||||
"module": "index.ts",
|
"module": "index.ts",
|
||||||
"type": "module",
|
"type": "module",
|
||||||
"bin": {
|
"bin": {
|
||||||
|
|||||||
Reference in New Issue
Block a user