@zjex/git-workflow 0.2.24 → 0.3.2

package/docs/commands/config.md

@@ -0,0 +1,346 @@
+# Config 命令
+
+配置管理相关的命令详解。
+
+## 📋 命令概览
+
+| 命令 | 说明 |
+|------|------|
+| `gw init` | 交互式初始化配置 |
+
+## ⚙️ 初始化配置
+
+### 基本用法
+
+```bash
+gw init
+```
+
+### 配置流程
+
+```bash
+$ gw init
+⚙️  初始化 git-workflow 配置
+
+? 选择配置范围:
+❯ 全局配置（所有项目生效）
+  项目配置（仅当前项目）
+```
+
+## 🌍 配置范围
+
+### 全局配置
+
+**位置**：`~/.gwrc.json`  
+**作用域**：所有项目  
+**优势**：一次配置，处处使用
+
+```bash
+? 选择配置范围: 全局配置（所有项目生效）
+
+配置保存到: ~/.gwrc.json
+✔ 所有项目都会使用此配置
+✔ 无需在每个项目中重复配置
+✔ 新项目自动继承配置
+```
+
+### 项目配置
+
+**位置**：`.gwrc.json`  
+**作用域**：当前项目  
+**优势**：项目特定配置，团队共享
+
+```bash
+? 选择配置范围: 项目配置（仅当前项目）
+
+配置保存到: .gwrc.json
+✔ 仅当前项目使用此配置
+✔ 可以提交到版本控制
+✔ 团队成员共享配置
+```
+
+## 🔧 配置项详解
+
+### 基础分支配置
+
+```bash
+? 默认基础分支 (留空自动检测 main/master): develop
+```
+
+### 分支前缀配置
+
+```bash
+? Feature 分支前缀: feature
+? Hotfix 分支前缀: hotfix
+```
+
+### ID 配置
+
+```bash
+? 是否要求必填 ID (Story ID / Issue ID)?
+❯ 否
+  是
+
+? Feature 分支 ID 标签: Story ID
+? Hotfix 分支 ID 标签: Issue ID
+```
+
+### Tag 配置
+
+```bash
+? 默认 Tag 前缀 (留空则每次选择): v
+```
+
+### 推送配置
+
+```bash
+? 创建分支后是否自动推送?
+❯ 每次询问
+  自动推送
+  不推送
+```
+
+### Commit 配置
+
+```bash
+? Commit 时是否自动暂存所有更改?
+❯ 是
+  否
+
+? Commit 时是否使用 emoji?
+❯ 是
+  否
+```
+
+### AI Commit 配置
+
+```bash
+? 是否启用 AI Commit 功能?
+❯ 是（推荐）
+  否
+
+? 选择 AI 提供商:
+❯ GitHub Models（免费，推荐）
+  OpenAI（付费）
+  Claude（付费）
+  Ollama（本地）
+
+? 生成的 commit message 语言:
+❯ 中文
+  English
+
+? 是否生成详细的修改点描述?
+❯ 是（包含修改点列表，推荐）
+  否（仅生成标题）
+```
+
+## 📁 配置文件位置
+
+### 查找顺序
+
+1. **当前目录** - `.gwrc.json`, `.gwrc`, `gw.config.json`
+2. **Git 根目录** - 同上文件名
+3. **用户主目录** - `~/.gwrc.json`
+
+### 配置合并
+
+**优先级**：项目配置 > 全局配置 > 默认配置
+
+```bash
+# 全局配置
+~/.gwrc.json
+{
+  "useEmoji": true,
+  "aiCommit": {
+    "enabled": true,
+    "provider": "github"
+  }
+}
+
+# 项目配置
+.gwrc.json
+{
+  "requireId": true,
+  "featureIdLabel": "Jira ID"
+}
+
+# 最终生效配置
+{
+  "useEmoji": true,           # 来自全局配置
+  "requireId": true,          # 来自项目配置
+  "featureIdLabel": "Jira ID", # 来自项目配置
+  "aiCommit": {
+    "enabled": true,          # 来自全局配置
+    "provider": "github"      # 来自全局配置
+  }
+}
+```
+
+## 🎯 使用场景
+
+### 个人开发者
+
+**推荐**：全局配置
+
+```bash
+gw init
+# 选择：全局配置（所有项目生效）
+# 配置 AI commit、个人偏好等
+```
+
+**优势**：
+- 一次配置，所有项目生效
+- 新项目自动继承配置
+- 无需重复配置
+
+### 团队协作
+
+**推荐**：全局配置 + 项目配置
+
+```bash
+# 1. 个人全局配置
+gw init
+# 选择：全局配置
+# 配置 AI commit API key 等个人信息
+
+# 2. 项目团队配置
+cd team-project
+gw init
+# 选择：项目配置
+# 配置团队统一的分支规范、ID 要求等
+```
+
+**优势**：
+- 个人配置私有化
+- 团队规范统一化
+- 灵活组合配置
+
+### 开源项目
+
+**推荐**：项目配置
+
+```bash
+gw init
+# 选择：项目配置（仅当前项目）
+# 配置项目特定规范
+# 提交到版本控制，贡献者共享
+```
+
+## 🔄 配置更新
+
+### 重新配置
+
+```bash
+# 覆盖现有配置
+gw init
+
+? 全局配置文件已存在，是否覆盖?
+❯ 否，取消
+  是，覆盖
+```
+
+### 手动编辑
+
+```bash
+# 编辑全局配置
+vim ~/.gwrc.json
+
+# 编辑项目配置
+vim .gwrc.json
+```
+
+### 配置验证
+
+工具会自动验证配置文件格式：
+
+```bash
+# 配置文件格式错误时
+⚠️  配置文件解析失败: ~/.gwrc.json
+使用默认配置继续执行
+```
+
+## 📋 配置模板
+
+### 个人开发模板
+
+```json
+{
+  "featurePrefix": "feat",
+  "hotfixPrefix": "fix",
+  "requireId": false,
+  "autoStage": true,
+  "useEmoji": true,
+  "aiCommit": {
+    "enabled": true,
+    "provider": "github",
+    "language": "zh-CN",
+    "detailedDescription": true
+  }
+}
+```
+
+### 团队协作模板
+
+```json
+{
+  "baseBranch": "develop",
+  "requireId": true,
+  "featureIdLabel": "Jira ID",
+  "hotfixIdLabel": "Bug ID",
+  "autoPush": true,
+  "autoStage": true,
+  "useEmoji": true,
+  "aiCommit": {
+    "enabled": true,
+    "language": "zh-CN",
+    "detailedDescription": true
+  }
+}
+```
+
+### 企业级模板
+
+```json
+{
+  "baseBranch": "develop",
+  "requireId": true,
+  "featureIdLabel": "Story ID",
+  "hotfixIdLabel": "Incident ID",
+  "defaultTagPrefix": "v",
+  "autoPush": true,
+  "autoStage": false,
+  "useEmoji": false,
+  "aiCommit": {
+    "enabled": true,
+    "provider": "openai",
+    "language": "en-US",
+    "detailedDescription": true
+  }
+}
+```
+
+## 🚀 最佳实践
+
+### 配置策略
+
+1. **全局配置** - 个人偏好和 API key
+2. **项目配置** - 团队规范和项目特定设置
+3. **环境变量** - 敏感信息（如 API key）
+
+### 团队配置管理
+
+1. **提交项目配置** - 将 `.gwrc.json` 提交到版本控制
+2. **文档说明** - 在 README 中说明配置要求
+3. **配置检查** - 在 CI 中检查配置完整性
+
+### 安全考虑
+
+1. **API Key 保护** - 不要将 API key 提交到版本控制
+2. **环境变量** - 使用环境变量存储敏感信息
+3. **权限控制** - 限制配置文件的访问权限
+
+### 配置维护
+
+1. **定期更新** - 根据需求更新配置
+2. **备份配置** - 备份重要的配置文件
+3. **版本控制** - 跟踪配置文件的变更历史

package/docs/commands/index.md

@@ -0,0 +1,312 @@
+# 命令参考
+
+Git Workflow 提供了一套简洁而强大的命令，涵盖了 Git 工作流的各个方面。所有命令都支持交互式操作，让你无需记忆复杂的参数。
+
+## 📋 命令概览
+
+### 核心命令
+
+| 命令    | 别名              | 功能                 | 示例                    |
+| ------- | ----------------- | -------------------- | ----------------------- |
+| `gw`    | -                 | 显示交互式菜单       | `gw`                    |
+| `gw f`  | `feat`, `feature` | 创建 feature 分支    | `gw f --base develop`   |
+| `gw h`  | `fix`, `hotfix`   | 创建 hotfix 分支     | `gw h`                  |
+| `gw c`  | `cm`, `commit`    | 提交代码（AI 模式）  | `gw c`                  |
+| `gw t`  | `tag`             | 创建 tag             | `gw t v`                |
+| `gw d`  | `del`, `delete`   | 删除分支             | `gw d feature/old`      |
+| `gw s`  | `st`, `stash`     | 管理 stash           | `gw s`                  |
+
+### 辅助命令
+
+| 命令     | 别名   | 功能                     | 示例      |
+| -------- | ------ | ------------------------ | --------- |
+| `gw r`   | `release` | 发布版本              | `gw r`    |
+| `gw ts`  | `tags` | 列出 tags                | `gw ts v` |
+| `gw td`  | `tag:delete` | 删除 tag           | `gw td`   |
+| `gw tu`  | `tag:update` | 修改 tag           | `gw tu`   |
+| `gw init`| -      | 初始化配置               | `gw init` |
+| `gw upt` | `update` | 更新工具               | `gw upt`  |
+
+## 🎯 使用模式
+
+Git Workflow 支持两种使用模式：
+
+### 1. 交互式模式（推荐新手）
+
+直接运行 `gw` 显示交互式菜单：
+
+```bash
+gw
+```
+
+```
+ ███████╗     ██╗███████╗██╗  ██╗
+ ╚══███╔╝     ██║██╔════╝╚██╗██╔╝
+   ███╔╝      ██║█████╗   ╚███╔╝
+  ███╔╝  ██   ██║██╔══╝   ██╔██╗
+ ███████╗╚█████╔╝███████╗██╔╝ ██╗
+ ╚══════╝ ╚════╝ ╚══════╝╚═╝  ╚═╝
+
+  git-workflow v0.2.24
+
+? 选择操作:
+  [1] ✨ 创建 feature 分支      gw f
+  [2] 🐛 创建 hotfix 分支       gw h
+  [3] 🗑️  删除分支               gw d
+  [4] 📝 提交代码               gw c
+  [5] 🏷️  创建 tag               gw t
+  [6] 🗑️  删除 tag               gw td
+  [7] ✏️  修改 tag               gw tu
+  [8] 📋 列出 tags              gw ts
+  [9] 📦 发布版本               gw r
+  [a] 💾 管理 stash             gw s
+  [b] ⚙️  初始化配置             gw init
+  [0] ❓ 帮助
+  [q] 退出
+```
+
+**特点：**
+- 🎨 优雅的 ASCII Art Logo
+- 📋 清晰的操作菜单
+- 🎯 键盘快捷操作
+- 🔍 实时搜索和过滤
+
+### 2. 命令行模式（推荐熟练用户）
+
+直接使用具体命令：
+
+```bash
+# 创建 feature 分支
+gw f
+
+# 提交代码
+gw c
+
+# 创建 tag
+gw t
+
+# 删除分支
+gw d
+```
+
+**特点：**
+- ⚡️ 快速执行
+- 🤖 支持脚本化
+- 📝 支持参数传递
+- 🔄 适合 CI/CD 集成
+
+## 🎨 界面特性
+
+### 颜色编码
+
+Git Workflow 使用颜色来区分不同类型的信息：
+
+- 🟢 **绿色** - 成功信息、分支名、确认操作
+- 🟡 **黄色** - 警告信息、版本号、重要提示
+- 🔴 **红色** - 错误信息、危险操作
+- 🔵 **蓝色** - 链接、命令、可点击内容
+- ⚪ **灰色** - 辅助信息、时间戳、次要内容
+
+### 图标系统
+
+每个功能都有对应的图标，提高可识别性：
+
+- ✨ **feature** - 新功能开发
+- 🐛 **hotfix** - 紧急修复
+- 🏷️ **tag** - 版本标签
+- 📝 **commit** - 代码提交
+- 💾 **stash** - 代码暂存
+- 🗑️ **delete** - 删除操作
+- ⚙️ **config** - 配置管理
+- 🔄 **update** - 更新操作
+
+### 键盘操作
+
+所有交互界面都支持键盘操作：
+
+| 按键       | 功能                     |
+| ---------- | ------------------------ |
+| ↑/↓        | 上下选择选项             |
+| ←/→        | 左右切换（多选模式）     |
+| 空格       | 选择/取消选择（多选模式） |
+| 回车       | 确认选择                 |
+| Ctrl+C     | 优雅退出                 |
+| Tab        | 自动补全（输入模式）     |
+| Esc        | 取消当前操作             |
+
+## 🔧 全局选项
+
+所有命令都支持以下全局选项：
+
+### 版本信息
+
+```bash
+gw --version
+gw -v
+```
+
+显示当前版本号。
+
+### 帮助信息
+
+```bash
+gw --help
+gw -h
+```
+
+显示帮助信息和可用命令列表。
+
+### 调试模式
+
+```bash
+DEBUG=gw:* gw c
+```
+
+启用详细日志，用于问题排查。
+
+## 🎯 命令分类
+
+### 分支管理
+
+专注于分支的创建、删除和管理：
+
+- [**gw f**](/commands/branch#创建-feature-分支) - 创建 feature 分支
+- [**gw h**](/commands/branch#创建-hotfix-分支) - 创建 hotfix 分支  
+- [**gw d**](/commands/branch#删除分支) - 删除本地/远程分支
+
+### 提交管理
+
+处理代码提交和提交信息：
+
+- [**gw c**](/commands/commit) - 交互式提交（支持 AI 生成）
+
+### 版本管理
+
+管理项目版本和标签：
+
+- [**gw t**](/commands/tag#创建-tag) - 创建版本标签
+- [**gw ts**](/commands/tag#列出-tags) - 列出所有标签
+- [**gw td**](/commands/tag#删除-tag) - 删除标签
+- [**gw tu**](/commands/tag#修改-tag) - 修改标签
+- [**gw r**](/commands/release) - 发布新版本
+
+### 代码暂存
+
+管理 Git stash：
+
+- [**gw s**](/commands/stash) - 可视化管理 stash
+
+### 工具管理
+
+配置和维护工具本身：
+
+- [**gw init**](/commands/config) - 初始化配置
+- [**gw upt**](/commands/update) - 更新工具
+- [**gw clean**](/commands/update#清理缓存) - 清理缓存
+
+## 🚀 快速参考
+
+### 日常开发流程
+
+```bash
+# 1. 创建功能分支
+gw f
+# 输入: PROJ-123, add-login-feature
+
+# 2. 开发代码...
+
+# 3. 提交代码（AI 模式）
+gw c
+# AI 自动生成: ✨ feat(auth): 添加用户登录功能
+
+# 4. 创建版本标签
+gw t
+# 选择: patch → v1.2.1
+
+# 5. 清理旧分支
+gw d
+# 选择要删除的分支
+```
+
+### 紧急修复流程
+
+```bash
+# 1. 创建 hotfix 分支
+gw h
+# 输入: BUG-456, fix-login-crash
+
+# 2. 修复代码...
+
+# 3. 提交修复
+gw c
+# AI 生成: 🐛 fix(auth): 修复登录页面崩溃问题
+
+# 4. 创建补丁版本
+gw t
+# 选择: patch → v1.2.2
+```
+
+### 版本发布流程
+
+```bash
+# 1. 更新版本号
+gw r
+# 选择: minor → 1.3.0
+
+# 2. 创建发布标签
+gw t
+# 选择: v1.3.0
+
+# 3. 清理功能分支
+gw d
+# 批量删除已合并的分支
+```
+
+## 📚 深入学习
+
+每个命令都有详细的使用指南：
+
+- [**交互式菜单**](/commands/interactive) - 了解主菜单的所有功能
+- [**分支命令**](/commands/branch) - 掌握分支管理的最佳实践
+- [**Tag 命令**](/commands/tag) - 学习版本标签的高级用法
+- [**提交命令**](/commands/commit) - 深入了解 AI 提交和手动提交
+- [**Stash 命令**](/commands/stash) - 高效管理代码暂存
+- [**版本命令**](/commands/release) - 自动化版本发布流程
+- [**配置命令**](/commands/config) - 自定义工具行为
+- [**更新命令**](/commands/update) - 保持工具最新状态
+
+## 🔍 命令查找
+
+不确定使用哪个命令？可以通过以下方式快速找到：
+
+### 按功能查找
+
+- **我想创建分支** → `gw f` (feature) 或 `gw h` (hotfix)
+- **我想提交代码** → `gw c` (commit)
+- **我想创建版本** → `gw t` (tag) 或 `gw r` (release)
+- **我想删除分支** → `gw d` (delete)
+- **我想管理 stash** → `gw s` (stash)
+- **我想配置工具** → `gw init`
+- **我想更新工具** → `gw upt`
+
+### 按场景查找
+
+- **开始新功能** → `gw f`
+- **修复紧急 Bug** → `gw h`
+- **提交当前更改** → `gw c`
+- **发布新版本** → `gw r` + `gw t`
+- **清理旧分支** → `gw d`
+- **暂存当前工作** → `gw s`
+
+### 交互式查找
+
+如果不确定，直接运行 `gw` 查看所有可用选项：
+
+```bash
+gw
+# 浏览菜单，选择需要的功能
+```
+
+---
+
+掌握这些命令后，你就能高效地管理 Git 工作流了。每个命令都经过精心设计，旨在简化复杂的 Git 操作，让你专注于代码开发。