docs: add comprehensive project documentation

2026-06-09 17:22:03 +08:00
parent 455c5d9b41
commit 8be9f51532
1 changed files with 166 additions and 5 deletions
@@ -1,15 +1,176 @@
-# git-ai
+<div align="center">

-To install dependencies:
+# gai
+
+**AI-powered git commit message generator**
+
+[![Version](https://img.shields.io/badge/version-0.1.0-blue.svg)](https://github.com/mplan/git-ai)
+[![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 using AI — based on your project context, code diff, and commit history.
+
+</div>
+
+---
+
+## Features
+
+- **3-layer context** — 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"
+- **OpenAI-compatible API** — works with DeepSeek, OpenAI, Ollama, and more
+- **Review before commit** — confirm, edit, or abort the generated message
+- **Zero dependencies** — built entirely on Bun native APIs
+
+## Quick Start

 ```bash
+# Install dependencies
 bun install
+
+# Configure your API key
+bun run gai config
+
+# Generate a commit message
+bun run gai
 ```

-To run:
+## Usage
+
+```
+gai                Generate commit message (interactive file selection)
+gai --auto         Auto-stage all changed files
+gai --dry-run      Generate message without committing
+gai config         Configure API settings
+gai --help         Show help
+gai --version      Show version
+```
+
+### Interactive Flow
+
+```
+$ gai
+
+  Select files to stage:
+    ❯ ◉ Select all
+      ◉ src/git.ts (modified)
+      ○ src/ai.ts (modified)
+      ◉ src/newfile.ts (new)
+
+  ↑/↓ navigate, space select, enter confirm
+
+  Generating commit message...
+
+  Generated commit message:
+    feat(git): add interactive file staging and commit wrapper
+
+  Use this message? [Y/n/e] Y
+
+  Committed successfully!
+```
+
+## Configuration
+
+### Via `gai config` (interactive)

 ```bash
-bun run index.ts
+bun run gai config
 ```

-This project was created using `bun init` in bun v1.3.14. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+### Via environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `GAI_API_KEY` | — | **Required.** Your API key |
+| `GAI_API_BASE` | `https://api.deepseek.com/v1` | API base URL |
+| `GAI_MODEL` | `deepseek-chat` | Model name |
+| `GAI_MAX_TOKENS` | `500` | Max response tokens |
+| `GAI_TEMPERATURE` | `0.7` | Sampling temperature |
+
+### Via `.env` file
+
+Bun auto-loads `.env` — no dotenv needed:
+
+```bash
+GAI_API_KEY=sk-your-key
+GAI_API_BASE=https://api.deepseek.com/v1
+GAI_MODEL=deepseek-chat
+```
+
+### Using other providers
+
+<details>
+<summary><strong>OpenAI</strong></summary>
+
+```bash
+GAI_API_KEY=sk-xxx
+GAI_API_BASE=https://api.openai.com/v1
+GAI_MODEL=gpt-4o
+```
+
+</details>
+
+<details>
+<summary><strong>Ollama (local)</strong></summary>
+
+```bash
+GAI_API_KEY=ollama
+GAI_API_BASE=http://localhost:11434/v1
+GAI_MODEL=llama3
+```
+
+</details>
+
+<details>
+<summary><strong>OpenRouter</strong></summary>
+
+```bash
+GAI_API_KEY=sk-or-xxx
+GAI_API_BASE=https://openrouter.ai/api/v1
+GAI_MODEL=anthropic/claude-sonnet-4
+```
+
+</details>
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────┐
+│                gai                           │
+├─────────────────────────────────────────────┤
+│  1. Collect project context                  │
+│     ├─ README.md / package.json              │
+│     └─ Directory structure                   │
+│                                              │
+│  2. Collect code changes                     │
+│     └─ git diff --staged                     │
+│                                              │
+│  3. Collect commit history                   │
+│     └─ git log --oneline -10                 │
+│                                              │
+│  4. Build prompt → Call AI API               │
+│                                              │
+│  5. Review → Confirm → Commit                │
+└─────────────────────────────────────────────┘
+```
+
+## Build
+
+Compile to a standalone binary:
+
+```bash
+bun run build
+# Output: ./gai
+```
+
+## Test
+
+```bash
+bun test
+```
+
+## License
+
+[MIT](./LICENSE)