@zjex/git-workflow 0.2.24 → 0.3.0

package/docs/commands/update.md

@@ -0,0 +1,347 @@
+# Update 命令
+
+更新管理相关的命令详解。
+
+## 📋 命令概览
+
+| 命令 | 别名 | 说明 |
+|------|------|------|
+| `gw update` | `gw upt` | 检查并更新到最新版本 |
+
+## 🔄 版本更新
+
+### 基本用法
+
+```bash
+gw update
+gw upt
+```
+
+### 更新流程
+
+```bash
+$ gw update
+🔍 检查更新...
+
+┌─────────────────────────────────┐
+│                                 │
+│   🎉 发现新版本！               │
+│                                 │
+│   0.2.24  →  0.2.25             │
+│                                 │
+└─────────────────────────────────┘
+
+? 是否立即更新?
+❯ 是，立即更新
+  否，稍后更新
+  查看更新日志
+
+✔ 更新成功！
+
+┌─────────────────────────────────┐
+│                                 │
+│   ✨ 更新完成！                 │
+│                                 │
+│   请重新打开终端使用新版本      │
+│                                 │
+└─────────────────────────────────┘
+```
+
+## 📊 版本检查
+
+### 当前版本
+
+```bash
+$ gw --version
+0.2.24
+
+$ gw -v
+0.2.24
+```
+
+### 版本对比
+
+工具会自动对比本地版本和最新版本：
+
+```bash
+当前版本: 0.2.24
+最新版本: 0.2.25
+状态: 有新版本可用
+```
+
+## 🎯 更新场景
+
+### 有新版本
+
+```bash
+$ gw update
+🔍 检查更新...
+
+发现新版本: 0.2.24 → 0.2.25
+
+新版本特性:
+• 修复 AI commit 生成问题
+• 优化分支创建流程
+• 更新文档和示例
+
+? 是否立即更新?
+❯ 是，立即更新
+  否，稍后更新
+  查看完整更新日志
+```
+
+### 已是最新版本
+
+```bash
+$ gw update
+🔍 检查更新...
+
+✔ 当前已是最新版本 (0.2.25)
+```
+
+### 网络连接问题
+
+```bash
+$ gw update
+🔍 检查更新...
+
+❌ 无法连接到更新服务器
+请检查网络连接后重试
+```
+
+## 📋 更新日志
+
+### 查看更新日志
+
+```bash
+? 是否立即更新: 查看更新日志
+
+# Git Workflow v0.2.25
+
+## 🎉 新功能
+- 添加 AI commit 详细描述功能
+- 支持自定义分支前缀配置
+
+## 🐛 Bug 修复
+- 修复 tag 创建时的版本检测问题
+- 优化 stash 管理的文件显示
+
+## 📝 文档更新
+- 完善 VitePress 文档站点
+- 添加配置示例和最佳实践
+
+## 🔧 其他改进
+- 优化命令行界面显示
+- 提升错误处理和用户体验
+
+按任意键继续...
+```
+
+### 版本历史
+
+可以查看完整的版本更新历史：
+
+```bash
+# 最近版本
+v0.2.25 - 2026-01-11
+v0.2.24 - 2026-01-10
+v0.2.23 - 2026-01-09
+...
+```
+
+## 🔧 更新方式
+
+### 自动更新
+
+工具使用 npm 进行更新：
+
+```bash
+# 实际执行的命令
+npm install -g @zjex/git-workflow@latest
+```
+
+### 手动更新
+
+如果自动更新失败，可以手动更新：
+
+```bash
+# npm
+npm install -g @zjex/git-workflow@latest
+
+# pnpm
+pnpm add -g @zjex/git-workflow@latest
+
+# yarn
+yarn global add @zjex/git-workflow@latest
+```
+
+## 🔔 更新提醒
+
+### 自动检查
+
+工具会在以下情况自动检查更新：
+
+1. **每日首次使用** - 每天第一次运行命令时
+2. **版本差距较大** - 本地版本落后较多时
+3. **手动检查** - 运行 `gw update` 时
+
+### 提醒频率
+
+```bash
+# 配置更新检查频率
+export GW_UPDATE_CHECK=daily    # 每日检查（默认）
+export GW_UPDATE_CHECK=weekly   # 每周检查
+export GW_UPDATE_CHECK=never    # 禁用自动检查
+```
+
+### 静默模式
+
+```bash
+# 禁用更新提醒
+export GW_SILENT_UPDATE=true
+
+# 或在配置文件中设置
+{
+  "updateCheck": {
+    "enabled": false
+  }
+}
+```
+
+## 🎯 使用场景
+
+### 定期维护
+
+```bash
+# 每周检查更新
+gw update
+
+# 查看版本信息
+gw --version
+```
+
+### CI/CD 环境
+
+```bash
+# 在 CI 中使用固定版本
+npm install -g @zjex/git-workflow@0.2.24
+
+# 或使用最新版本
+npm install -g @zjex/git-workflow@latest
+```
+
+### 团队同步
+
+```bash
+# 团队统一版本
+echo "推荐使用 git-workflow v0.2.25"
+echo "更新命令: gw update"
+```
+
+## 🚀 版本管理
+
+### 语义化版本
+
+工具遵循 [Semantic Versioning](https://semver.org/) 规范：
+
+```
+主版本号.次版本号.修订号
+
+0.2.24 → 0.2.25  # 修订号：Bug 修复
+0.2.25 → 0.3.0   # 次版本号：新功能
+0.3.0 → 1.0.0    # 主版本号：重大变更
+```
+
+### 版本兼容性
+
+- **修订号更新** - 完全兼容，建议立即更新
+- **次版本更新** - 向下兼容，可以安全更新
+- **主版本更新** - 可能不兼容，需要查看迁移指南
+
+### 预发布版本
+
+```bash
+# 安装预发布版本
+npm install -g @zjex/git-workflow@beta
+npm install -g @zjex/git-workflow@alpha
+
+# 回到稳定版本
+npm install -g @zjex/git-workflow@latest
+```
+
+## 🔧 故障排除
+
+### 更新失败
+
+```bash
+# 权限问题
+sudo npm install -g @zjex/git-workflow@latest
+
+# 缓存问题
+npm cache clean --force
+npm install -g @zjex/git-workflow@latest
+
+# 网络问题
+npm config set registry https://registry.npmmirror.com/
+npm install -g @zjex/git-workflow@latest
+```
+
+### 版本冲突
+
+```bash
+# 卸载旧版本
+npm uninstall -g @zjex/git-workflow
+
+# 安装新版本
+npm install -g @zjex/git-workflow@latest
+
+# 验证安装
+gw --version
+```
+
+### 配置迁移
+
+主版本更新时可能需要迁移配置：
+
+```bash
+# 备份配置
+cp ~/.gwrc.json ~/.gwrc.json.backup
+
+# 重新初始化配置
+gw init
+
+# 对比配置差异
+diff ~/.gwrc.json.backup ~/.gwrc.json
+```
+
+## 📋 最佳实践
+
+### 更新策略
+
+1. **及时更新** - 修订号更新建议立即更新
+2. **测试验证** - 次版本更新前在测试环境验证
+3. **谨慎升级** - 主版本更新前详细阅读变更日志
+
+### 团队协作
+
+1. **版本统一** - 团队使用相同版本
+2. **更新通知** - 及时通知团队成员更新
+3. **文档维护** - 更新项目文档中的版本要求
+
+### 自动化
+
+```bash
+# 在 CI 中自动更新
+- name: Update git-workflow
+  run: |
+    npm install -g @zjex/git-workflow@latest
+    gw --version
+```
+
+### 监控
+
+```bash
+# 监控版本状态
+gw --version
+gw update --check-only  # 仅检查，不更新
+```

package/docs/config/ai-config.md

@@ -0,0 +1,160 @@
+# AI 配置
+
+AI commit 功能的详细配置指南。
+
+## 🤖 AI 提供商
+
+### GitHub Models（推荐）
+
+免费使用，每天 150 次调用限制。
+
+```json
+{
+  "aiCommit": {
+    "provider": "github",
+    "apiKey": "ghp_your_token_here"
+  }
+}
+```
+
+**获取 GitHub Token：**
+1. 访问：https://github.com/settings/tokens/new
+2. 勾选 `repo` 权限
+3. 生成并复制 token
+
+### OpenAI
+
+付费服务，需要 OpenAI API Key。
+
+```json
+{
+  "aiCommit": {
+    "provider": "openai",
+    "apiKey": "sk-your_api_key_here",
+    "model": "gpt-4o-mini"
+  }
+}
+```
+
+### Claude
+
+付费服务，需要 Claude API Key。
+
+```json
+{
+  "aiCommit": {
+    "provider": "claude",
+    "apiKey": "sk-ant-your_api_key_here",
+    "model": "claude-3-haiku-20240307"
+  }
+}
+```
+
+### Ollama（本地）
+
+免费本地运行，需要安装 Ollama。
+
+```json
+{
+  "aiCommit": {
+    "provider": "ollama",
+    "model": "qwen2.5-coder:7b"
+  }
+}
+```
+
+## 📝 详细描述配置
+
+控制是否生成包含修改点的详细 commit message。
+
+```json
+{
+  "aiCommit": {
+    "detailedDescription": true
+  }
+}
+```
+
+**效果对比：**
+
+简洁模式：
+```
+feat(auth): 添加用户登录功能
+```
+
+详细模式：
+```
+feat(auth): 添加用户登录功能
+
+- 实现用户名密码登录接口
+- 添加登录状态验证中间件
+- 完善登录错误处理逻辑
+```
+
+## 🌍 语言配置
+
+支持中文和英文两种语言。
+
+```json
+{
+  "aiCommit": {
+    "language": "zh-CN"  // 或 "en-US"
+  }
+}
+```
+
+## ⚙️ 高级配置
+
+### Token 限制
+
+```json
+{
+  "aiCommit": {
+    "maxTokens": 400
+  }
+}
+```
+
+### 温度参数
+
+```json
+{
+  "aiCommit": {
+    "temperature": 0.3
+  }
+}
+```
+
+### 自定义提示词
+
+```json
+{
+  "aiCommit": {
+    "customPrompt": "请生成简洁的中文 commit message"
+  }
+}
+```
+
+## 🔧 故障排除
+
+### 常见问题
+
+1. **API Key 无效**
+   - 检查 API Key 是否正确
+   - 确认权限设置
+
+2. **网络连接问题**
+   - 检查网络连接
+   - 考虑使用代理
+
+3. **Token 限制**
+   - 调整 maxTokens 参数
+   - 使用简洁模式
+
+### 调试模式
+
+设置环境变量启用调试：
+
+```bash
+DEBUG=1 gw c
+```

package/docs/config/branch-config.md

@@ -0,0 +1,133 @@
+# 分支配置
+
+分支管理相关的配置选项。
+
+## 🌿 基础分支
+
+设置默认的基础分支。
+
+```json
+{
+  "baseBranch": "develop"
+}
+```
+
+如果不设置，工具会自动检测 `main` 或 `master`。
+
+## 🏷️ 分支前缀
+
+自定义分支前缀。
+
+```json
+{
+  "featurePrefix": "feature",
+  "hotfixPrefix": "hotfix"
+}
+```
+
+**生成的分支名格式：**
+```
+feature/20260111-PROJ-123-add-login
+hotfix/20260111-BUG-456-fix-crash
+```
+
+## 🆔 ID 配置
+
+控制是否强制要求填写 ID。
+
+```json
+{
+  "requireId": true,
+  "featureIdLabel": "Jira ID",
+  "hotfixIdLabel": "Bug ID"
+}
+```
+
+**效果：**
+- `requireId: false` - ID 可选，可以跳过
+- `requireId: true` - ID 必填，不能跳过
+
+## 🚀 自动推送
+
+控制创建分支后是否自动推送到远程。
+
+```json
+{
+  "autoPush": true
+}
+```
+
+**选项：**
+- `true` - 自动推送，不询问
+- `false` - 不推送，不询问
+- 不设置 - 每次询问（默认）
+
+## 📋 使用场景
+
+### 个人开发
+
+```json
+{
+  "featurePrefix": "feat",
+  "requireId": false,
+  "autoPush": false
+}
+```
+
+### 团队协作
+
+```json
+{
+  "baseBranch": "develop",
+  "requireId": true,
+  "featureIdLabel": "Jira ID",
+  "hotfixIdLabel": "Bug ID",
+  "autoPush": true
+}
+```
+
+### 开源项目
+
+```json
+{
+  "featurePrefix": "feature",
+  "hotfixPrefix": "fix",
+  "requireId": false,
+  "autoPush": false
+}
+```
+
+## 🔧 高级用法
+
+### 自定义分支命名
+
+通过配置前缀和标签，可以实现不同的命名风格：
+
+```json
+{
+  "featurePrefix": "feat",
+  "hotfixPrefix": "fix",
+  "featureIdLabel": "Story",
+  "hotfixIdLabel": "Issue"
+}
+```
+
+生成：`feat/20260111-Story-123-description`
+
+### 多环境配置
+
+不同环境使用不同的基础分支：
+
+```json
+{
+  "baseBranch": "develop"
+}
+```
+
+### 分支保护
+
+配合 GitHub 分支保护规则，确保代码质量：
+
+1. 设置 `autoPush: true`
+2. 在 GitHub 设置分支保护
+3. 要求 PR 审查