From 4572605f330a2cfba0940b7fa88adc48f0ce15ba Mon Sep 17 00:00:00 2001 From: Mplan Date: Tue, 16 Jun 2026 02:01:07 +0800 Subject: [PATCH] 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 --- README.md | 249 +++++++++++++++++++++++++++++++++++++-------------- package.json | 4 +- 2 files changed, 183 insertions(+), 70 deletions(-) diff --git a/README.md b/README.md index f82e76c..ef1414e 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,13 @@ # gai -**AI-powered Git commit and pull request helper** +**AI-powered Git helper — commit messages, PRs, code review, changelogs, and more** -[![Release](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fgit.catpl.top%2Fapi%2Fv1%2Frepos%2FMplan%2Fgai%2Freleases%2Flatest&query=%24.tag_name&label=release&color=blue)](https://git.catpl.top/Mplan/gai/releases) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE) [![Bun](https://img.shields.io/badge/runtime-Bun-f9d71c.svg)](https://bun.sh) [![TypeScript](https://img.shields.io/badge/lang-TypeScript-3178c6.svg)](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. @@ -17,15 +16,18 @@ Generate **Conventional Commits** messages and pull request descriptions using A ## Features -- **Interactive menu** — `gai` opens a menu, select actions with ↑/↓ + space/enter -- **Context-aware commits** — reads project overview, staged diff, and recent commit history -- **Conventional Commits** — `feat(scope): description` format by default -- **Interactive file selection** — ↑/↓ to navigate, space to select, top-level "Select all" -- **Inline editing** — edit AI-generated messages right in the terminal with cursor movement -- **AI-generated PRs** — create GitHub, Gitea, or GitLab pull requests with generated title and body -- **OpenAI-compatible API** — works with DeepSeek, OpenAI, Ollama, OpenRouter, and more -- **Review before commit** — confirm, edit, or abort the generated message -- **Bun-native runtime** — built on Bun APIs with no runtime npm dependencies +- **🤖 AI Commit Messages** — generate Conventional Commits from staged diffs with project context +- **🔀 AI Pull Requests** — create GitHub, Gitea, or GitLab PRs with AI-generated title and body +- **📖 Explain Changes** — `gai explain` explains diffs in plain language +- **🔍 Code Review** — `gai review` provides thorough, constructive code review +- **📝 Changelog Generation** — `gai changelog` generates user-facing changelogs from commits +- **💡 Smart Suggestions** — `gai suggest` recommends branch names or commit types +- **✏️ Amend Commits** — `gai commit --amend` amends with AI-generated message +- **⚡ Streaming Output** — AI responses stream token-by-token for instant feedback +- **📂 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 @@ -39,25 +41,79 @@ gai config # Open interactive menu gai -# Or directly generate a commit message +# Generate a commit message gai commit -# Or create an AI-generated pull request -gai pr +# Explain your changes +gai explain ``` ## Usage ``` -gai Open interactive menu -gai commit Generate commit message (interactive file selection) -gai commit --auto Auto-stage all changed files -gai commit -d Generate message without committing -gai pr Create a PR with AI-generated title and body -gai pr --draft Create a draft PR -gai config Configure API settings -gai --help Show help -gai --version Show version +gai Open interactive menu +gai commit Generate AI commit message (interactive file selection) +gai commit -a Auto-stage all changed files +gai commit -d Generate message without committing +gai commit -m "msg" Use custom message (skip AI) +gai commit --amend Amend last commit with AI-generated message +gai pr Create a PR with AI-generated title and body +gai pr --draft Create a draft PR +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 Get a specific setting +gai config set Set a setting +gai help Show help +gai help 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 @@ -66,58 +122,105 @@ gai --version Show version $ gai gai - Choose a workflow + AI-powered git helper — choose a workflow ↑/↓ navigate · enter/space select · ctrl+c cancel - ❯ ● commit Generate AI commit message - ○ pr Create a PR with AI-generated title - ○ config Configure API settings + ❯ ● commit Generate AI commit message + ○ pr Create a PR with AI-generated title + ○ 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 -``` -$ 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. +#### Commit ```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 + +# Draft PR 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 ### Via `gai config` (interactive) @@ -126,6 +229,15 @@ gai pr --draft 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 | Variable | Default | Description | @@ -193,13 +305,14 @@ GAI_MODEL=anthropic/claude-sonnet-4 │ │ │ 2. Collect code changes │ │ ├─ git diff --staged for commits │ -│ └─ branch diff for pull requests │ +│ ├─ Branch diff for pull requests │ +│ └─ Pipe support for external diffs │ │ │ │ 3. Collect commit history │ │ ├─ 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 │ └─────────────────────────────────────────────┘ diff --git a/package.json b/package.json index ad09ed6..ed9aa5f 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "gai", - "version": "0.1.2", - "description": "AI-powered git commit message generator", + "version": "0.2.0", + "description": "AI-powered git helper — commit messages, PRs, code review, changelogs, and more", "module": "index.ts", "type": "module", "bin": {