@zjex/git-workflow 0.2.24 → 0.3.2

package/docs/commands/stash.md

@@ -0,0 +1,309 @@
+# Stash 命令
+
+Stash 管理相关的命令详解。
+
+## 📋 命令概览
+
+| 命令 | 别名 | 说明 |
+|------|------|------|
+| `gw stash` | `gw s`, `gw st` | 交互式管理 stash |
+
+## 💾 Stash 管理
+
+### 基本用法
+
+```bash
+gw stash
+gw s
+gw st
+```
+
+### 主界面
+
+```bash
+$ gw s
+💾 Stash 管理
+
+共 3 个 stash:
+
+? 选择 stash:
+❯ [0] main fix login bug (3 文件) 2 hours ago
+  [1] develop add new feature (5 文件) 1 day ago
+  [2] main WIP (1 文件) 3 days ago
+  + 创建新 stash
+  取消
+```
+
+## 📋 Stash 详情
+
+选择一个 stash 后显示详细信息：
+
+```bash
+Stash #0
+分支: main
+消息: fix login bug
+时间: 2 hours ago
+文件 (3):
+  • src/auth.ts
+  • src/login.ts
+  • tests/auth.test.ts
+────────────────────────────────────────
+? 操作:
+❯ 应用 (保留 stash)
+  弹出 (应用并删除)
+  创建分支
+  查看差异
+  删除
+  返回列表
+  取消
+```
+
+## 🔧 Stash 操作
+
+### 应用 Stash
+
+**应用 (保留 stash)**：
+- 将 stash 的更改应用到当前工作区
+- 保留 stash，可以重复应用
+- 等同于 `git stash apply`
+
+**弹出 (应用并删除)**：
+- 将 stash 的更改应用到当前工作区
+- 删除该 stash
+- 等同于 `git stash pop`
+
+### 创建分支
+
+从 stash 创建新分支：
+
+```bash
+? 操作: 创建分支
+
+? 选择分支类型:
+❯ Feature 分支
+  Hotfix 分支
+
+? 请输入 Story ID (可跳过): STASH-123
+? 请输入描述: restore-login-fix
+
+✔ 分支创建成功: feature/20260111-STASH-123-restore-login-fix
+✔ Stash 已应用到新分支
+✔ Stash 已删除: stash@{0}
+```
+
+### 查看差异
+
+显示 stash 包含的具体更改：
+
+```bash
+? 操作: 查看差异
+
+diff --git a/src/auth.ts b/src/auth.ts
+index 1234567..abcdefg 100644
+--- a/src/auth.ts
++++ b/src/auth.ts
+@@ -10,6 +10,10 @@ export function login(username: string, password: string) {
+   if (!username || !password) {
+     throw new Error('用户名和密码不能为空');
+   }
++  
++  // 添加输入验证
++  if (username.length < 3) {
++    throw new Error('用户名至少需要3个字符');
++  }
+ }
+
+按任意键返回...
+```
+
+### 删除 Stash
+
+```bash
+? 操作: 删除
+
+? 确认删除 stash "fix login bug"?
+❯ 是
+  否
+
+✔ Stash 已删除: stash@{0}
+```
+
+## ➕ 创建 Stash
+
+### 基本创建
+
+```bash
+? 选择 stash: + 创建新 stash
+
+检测到以下更改:
+  M src/auth.ts
+  M src/login.ts
+  ?? src/new-file.ts
+
+? 输入 stash 消息: WIP: 重构登录逻辑
+
+? 是否包含未跟踪的文件?
+❯ 是，包含所有文件
+  否，仅已跟踪文件
+
+✔ Stash 创建成功: stash@{0}
+```
+
+### 处理未跟踪文件
+
+工具会智能检测未跟踪的新文件：
+
+```bash
+检测到未跟踪的文件:
+  ?? src/new-component.ts
+  ?? tests/new-test.ts
+
+? 是否一并 stash 这些新文件?
+❯ 是，包含新文件
+  否，忽略新文件
+```
+
+## 🎯 使用场景
+
+### 临时切换分支
+
+```bash
+# 当前在 feature 分支开发，需要紧急修复 bug
+gw s
+# 选择 "创建新 stash"
+# 输入消息: "WIP: 用户管理功能开发中"
+
+# 切换到 main 分支修复 bug
+git checkout main
+gw h  # 创建 hotfix 分支
+
+# 修复完成后，回到 feature 分支
+git checkout feature/user-management
+gw s  # 恢复之前的工作
+```
+
+### 实验性更改
+
+```bash
+# 尝试新的实现方案
+# ... 编写代码 ...
+
+# 不确定是否要保留，先 stash
+gw s
+# 创建 stash: "实验: 新的数据处理方案"
+
+# 尝试其他方案
+# ... 编写代码 ...
+
+# 对比两种方案
+gw s
+# 查看之前的 stash 差异
+```
+
+### 代码审查准备
+
+```bash
+# 开发完成，准备提交前整理代码
+gw s
+# 创建 stash: "临时: 调试代码和注释"
+
+# 清理代码，移除调试信息
+# ... 整理代码 ...
+
+# 提交干净的代码
+gw c
+
+# 如果需要，可以恢复调试代码
+gw s
+# 应用之前的 stash
+```
+
+## 🔄 与原生 Git 对比
+
+### 原生 Git Stash
+
+```bash
+# 原生命令
+git stash list
+git stash show stash@{0}
+git stash apply stash@{0}
+git stash pop stash@{0}
+git stash drop stash@{0}
+git stash branch new-branch stash@{0}
+```
+
+输出难以阅读：
+```bash
+$ git stash list
+stash@{0}: WIP on main: 1234567 fix login bug
+stash@{1}: WIP on develop: abcdefg add new feature
+stash@{2}: WIP on main: 7890123 work in progress
+```
+
+### Git Workflow Stash
+
+```bash
+# 统一命令
+gw s
+```
+
+清晰的交互界面：
+```bash
+共 3 个 stash:
+
+? 选择 stash:
+❯ [0] main fix login bug (3 文件) 2 hours ago
+  [1] develop add new feature (5 文件) 1 day ago
+  [2] main WIP (1 文件) 3 days ago
+```
+
+## 🚀 最佳实践
+
+### Stash 命名规范
+
+**推荐格式：**
+```
+WIP: 功能描述
+实验: 尝试内容
+临时: 临时更改说明
+调试: 调试相关更改
+```
+
+**示例：**
+```
+WIP: 用户权限管理功能
+实验: 使用 Redis 缓存
+临时: 添加调试日志
+调试: 修复登录问题
+```
+
+### 定期清理
+
+1. **及时应用** - 完成工作后及时应用 stash
+2. **删除无用** - 定期删除不再需要的 stash
+3. **转为分支** - 长期保留的更改考虑创建分支
+
+### 团队协作
+
+1. **不要依赖** - stash 是本地的，不要依赖它进行团队协作
+2. **及时提交** - 重要更改应该提交而不是 stash
+3. **清晰命名** - 使用清晰的 stash 消息
+
+### 工作流集成
+
+```bash
+# 1. 开发过程中临时保存
+gw s  # 创建 stash
+
+# 2. 处理其他任务
+# ... 其他工作 ...
+
+# 3. 恢复工作
+gw s  # 应用 stash
+
+# 4. 完成开发
+gw c  # 提交代码
+
+# 5. 清理 stash
+gw s  # 删除不需要的 stash
+```

package/docs/commands/tag.md

@@ -0,0 +1,278 @@
+# Tag 命令
+
+Tag 管理相关的命令详解。
+
+## 📋 命令列表
+
+| 命令 | 别名 | 说明 |
+|------|------|------|
+| `gw tags [prefix]` | `gw ts` | 列出 tag |
+| `gw tag [prefix]` | `gw t` | 创建 tag |
+| `gw tag:delete` | `gw td` | 删除 tag |
+| `gw tag:update` | `gw tu` | 修改 tag |
+
+## 📋 列出 Tag
+
+### 基本用法
+
+```bash
+# 列出所有 tag
+gw tags
+gw ts
+
+# 按前缀过滤
+gw ts v
+gw ts release-
+```
+
+### 输出示例
+
+```bash
+$ gw ts
+📋 所有 tags (按时间倒序):
+
+v1.2.0    Release v1.2.0    2 days ago
+v1.1.0    Release v1.1.0    1 week ago  
+v1.0.0    Initial release   2 weeks ago
+
+共 3 个 tags
+```
+
+## 🏷️ 创建 Tag
+
+### 基本用法
+
+```bash
+# 交互式创建
+gw tag
+gw t
+
+# 指定前缀
+gw t v
+gw t release-
+```
+
+### 创建流程
+
+1. **选择前缀**（如果有多个）
+2. **选择版本类型**
+3. **输入 tag 消息**
+4. **确认创建**
+
+### 示例流程
+
+```bash
+$ gw t
+🏷️  创建 tag
+
+? 选择 tag 前缀:
+❯ v (最新: v1.2.0)
+  release- (最新: release-1.0.0)
+  + 使用新前缀
+
+? 选择版本类型:
+❯ patch   → v1.2.1
+  minor   → v1.3.0
+  major   → v2.0.0
+  alpha   → v1.2.1-alpha.1
+  beta    → v1.2.1-beta.1
+  rc      → v1.2.1-rc.1
+
+? 输入 tag 消息: Release v1.2.1 - Bug fixes
+
+✔ Tag 创建成功: v1.2.1
+✔ Tag 已推送: v1.2.1
+```
+
+## 🗑️ 删除 Tag
+
+### 基本用法
+
+```bash
+gw tag:delete
+gw td
+```
+
+### 删除流程
+
+```bash
+$ gw td
+🗑️  删除 tag
+
+? 选择要删除的 tag:
+❯ v1.2.0 (2 days ago)
+  v1.1.0 (1 week ago)
+  v1.0.0 (2 weeks ago)
+
+? 确认删除 tag v1.2.0?
+❯ 是，删除本地和远程
+  仅删除本地
+  取消
+
+✔ 本地 tag 已删除: v1.2.0
+✔ 远程 tag 已删除: origin/v1.2.0
+```
+
+## ✏️ 修改 Tag
+
+### 基本用法
+
+```bash
+gw tag:update
+gw tu
+```
+
+### 修改流程
+
+```bash
+$ gw tu
+✏️  修改 tag
+
+? 选择要修改的 tag:
+❯ v1.2.0 Release v1.2.0 (2 days ago)
+  v1.1.0 Release v1.1.0 (1 week ago)
+
+当前消息: Release v1.2.0
+? 输入新的 tag 消息: Release v1.2.0 - Bug fixes and improvements
+
+✔ Tag 消息已更新: v1.2.0
+✔ 已推送到远程
+```
+
+## 🔧 版本类型详解
+
+### 标准版本
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| `patch` | 补丁版本，Bug 修复 | 1.0.0 → 1.0.1 |
+| `minor` | 次版本，新功能 | 1.0.0 → 1.1.0 |
+| `major` | 主版本，破坏性变更 | 1.0.0 → 2.0.0 |
+
+### 预发布版本
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| `alpha` | 内部测试版 | 1.0.0 → 1.0.1-alpha.1 |
+| `beta` | 公开测试版 | 1.0.0 → 1.0.1-beta.1 |
+| `rc` | 发布候选版 | 1.0.0 → 1.0.1-rc.1 |
+
+### 预发布版本升级
+
+当前版本为预发布版本时，可以：
+
+```bash
+# 当前: v1.2.1-beta.1
+? 选择版本类型:
+❯ pre     → v1.2.1-beta.2    # 升级预发布版本
+  release → v1.2.1           # 转为正式版本
+  patch   → v1.2.2           # 跳过当前，升级 patch
+  minor   → v1.3.0           # 跳过当前，升级 minor
+  major   → v2.0.0           # 跳过当前，升级 major
+```
+
+## 🎯 前缀检测
+
+工具会自动检测仓库中已有的 tag 前缀：
+
+### 常见前缀
+
+- `v` - 最常用，如 v1.0.0
+- `release-` - 如 release-1.0.0
+- `@scope/` - 如 @myapp/1.0.0
+- 自定义前缀
+
+### 初始化仓库
+
+如果仓库没有任何 tag：
+
+```bash
+$ gw t
+🏷️  创建 tag
+
+当前仓库没有 tag，请输入前缀 (如 v): v
+
+? 选择初始版本号:
+❯ v0.0.1
+  v0.1.0
+  v1.0.0
+  自定义...
+```
+
+## 📝 Tag 消息规范
+
+### 推荐格式
+
+```
+Release v1.2.0
+
+## 新功能
+- 添加用户登录功能
+- 支持多语言切换
+
+## Bug 修复
+- 修复数据加载失败问题
+- 优化内存使用
+
+## 其他
+- 更新依赖版本
+- 改进文档
+```
+
+### 简洁格式
+
+```
+Release v1.2.0 - Bug fixes and improvements
+```
+
+## 🔄 与其他命令配合
+
+### 与 release 命令
+
+```bash
+# 1. 更新版本号
+gw release
+
+# 2. 创建对应 tag
+gw tag
+```
+
+### 与 commit 命令
+
+```bash
+# 1. 提交最后的更改
+gw commit
+
+# 2. 创建发布 tag
+gw tag
+```
+
+## 🚀 最佳实践
+
+### 版本发布流程
+
+1. **完成开发** - 确保所有功能完成
+2. **运行测试** - 确保代码质量
+3. **更新文档** - 更新 CHANGELOG 等
+4. **提交更改** - 使用 `gw c` 提交
+5. **创建 tag** - 使用 `gw t` 创建版本标签
+6. **发布版本** - 推送到生产环境
+
+### 语义化版本
+
+遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/) 规范：
+
+- **MAJOR** - 不兼容的 API 修改
+- **MINOR** - 向下兼容的功能性新增
+- **PATCH** - 向下兼容的问题修正
+
+### 预发布策略
+
+```
+1.0.0-alpha.1  → 内部测试
+1.0.0-alpha.2  → 修复问题
+1.0.0-beta.1   → 公开测试
+1.0.0-beta.2   → 修复反馈
+1.0.0-rc.1     → 发布候选
+1.0.0          → 正式发布
+```