@zjex/git-workflow 0.2.24 → 0.3.2

package/docs/guide/stash-management.md

@@ -0,0 +1,608 @@
+# Stash 管理
+
+Stash 管理是 Git Workflow 的重要功能，提供了可视化的代码暂存管理，让你轻松处理临时代码变更。
+
+## 💾 Stash 管理理念
+
+### 可视化管理
+
+原生 `git stash list` 输出难以阅读：
+
+```bash
+# 原生 git stash 输出
+stash@{0}: WIP on main: a1b2c3d fix login bug
+stash@{1}: On feature: def4567 add new feature
+stash@{2}: WIP on develop: 890abcd update docs
+```
+
+Git Workflow 提供清晰的可视化界面：
+
+```bash
+# Git Workflow 可视化输出
+共 3 个 stash:
+
+? 选择 stash:
+❯ [0] main fix login bug (3 文件) 2 hours ago
+  [1] feature add new feature (5 文件) 1 day ago
+  [2] develop update docs (1 文件) 3 days ago
+  + 创建新 stash
+  取消
+```
+
+### 智能信息解析
+
+自动解析和格式化 stash 信息：
+
+- **索引编号** - stash@{0} → [0]
+- **分支名称** - 提取分支信息
+- **描述信息** - 清理和格式化消息
+- **文件统计** - 显示影响的文件数量
+- **时间信息** - 相对时间显示
+
+## 🎯 基本用法
+
+### 启动 Stash 管理
+
+```bash
+gw s
+# 或使用别名
+gw stash
+gw st
+```
+
+### 主界面
+
+```bash
+gw s
+共 3 个 stash:
+
+? 选择 stash:
+❯ [0] main fix login bug (3 文件) 2 hours ago
+  [1] feature add new feature (5 文件) 1 day ago
+  [2] develop update docs (1 文件) 3 days ago
+  + 创建新 stash
+  取消
+```
+
+**界面元素说明：**
+- **[索引]** - stash 的索引号
+- **分支名** - 创建 stash 时的分支
+- **描述** - stash 的描述信息
+- **文件数** - 包含的文件数量
+- **时间** - 创建时间（相对时间）
+
+## 📋 查看 Stash 详情
+
+### 选择 Stash 后的详情页
+
+```bash
+选择 stash [0] 后显示:
+
+Stash #0
+分支: main
+消息: fix login bug
+时间: 2 hours ago
+文件 (3):
+  • src/auth.ts
+  • src/login.ts
+  • tests/auth.test.ts
+────────────────────────────────────────
+? 操作:
+❯ 应用 (保留 stash)
+  弹出 (应用并删除)
+  创建分支
+  查看差异
+  删除
+  返回列表
+  取消
+```
+
+**详情信息包括：**
+- **索引编号** - stash 的唯一标识
+- **分支信息** - 创建时所在的分支
+- **消息内容** - 完整的描述信息
+- **创建时间** - 精确的时间信息
+- **文件列表** - 包含的所有文件（最多显示 10 个）
+
+## 🔄 Stash 操作
+
+### 应用 Stash（保留）
+
+```bash
+? 操作:
+❯ 应用 (保留 stash)
+
+✔ Stash 已应用
+💡 提示: stash 仍然保留，可以重复应用
+```
+
+**特点：**
+- 将 stash 中的更改应用到当前工作区
+- stash 本身不会被删除
+- 可以多次应用到不同分支
+
+**使用场景：**
+- 在多个分支中应用相同的更改
+- 测试 stash 内容是否正确
+- 保留 stash 作为备份
+
+### 弹出 Stash（应用并删除）
+
+```bash
+? 操作:
+❯ 弹出 (应用并删除)
+
+✔ Stash 已弹出并删除
+```
+
+**特点：**
+- 将 stash 中的更改应用到当前工作区
+- 同时删除该 stash
+- 最常用的 stash 操作
+
+**使用场景：**
+- 恢复临时保存的工作进度
+- 切换分支后恢复之前的更改
+- 清理不再需要的 stash
+
+### 创建分支
+
+```bash
+? 操作:
+❯ 创建分支
+
+? 选择分支类型:
+❯ feature
+  hotfix
+  取消
+
+? 请输入 Story ID (可跳过): STASH-001
+? 请输入描述: recover-login-work
+
+✔ 分支创建成功: feature/20260111-STASH-001-recover-login-work
+✔ Stash 已应用到新分支
+✔ Stash 已自动删除
+```
+
+**特点：**
+- 基于 stash 内容创建新分支
+- 自动应用 stash 到新分支
+- 遵循项目的分支命名规范
+- 创建成功后自动删除 stash
+
+**使用场景：**
+- 将临时工作转换为正式功能分支
+- 从实验性代码创建新功能
+- 恢复意外丢失的工作进度
+
+### 查看差异
+
+```bash
+? 操作:
+❯ 查看差异
+
+# 显示彩色的 diff 输出
+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 validateUser(username: string, password: string) {
+   if (!username || !password) {
+     return false;
+   }
++  
++  // 添加密码强度检查
++  if (password.length < 8) {
++    return false;
++  }
+   
+   return true;
+ }
+
+按 Enter 返回菜单...
+```
+
+**特点：**
+- 显示完整的代码差异
+- 支持彩色输出
+- 查看后返回操作菜单
+- 不影响 stash 状态
+
+**使用场景：**
+- 确认 stash 内容是否正确
+- 回顾之前的工作内容
+- 决定是否应用 stash
+
+### 删除 Stash
+
+```bash
+? 操作:
+❯ 删除
+
+? 确认删除 stash@{0}?
+❯ 是
+  否
+
+✔ Stash 已删除
+```
+
+**特点：**
+- 永久删除 stash
+- 需要确认操作
+- 无法恢复删除的 stash
+
+**使用场景：**
+- 清理不再需要的 stash
+- 释放存储空间
+- 保持 stash 列表整洁
+
+## ➕ 创建新 Stash
+
+### 自动检测变更
+
+```bash
+gw s
+# 如果没有现有 stash，会直接提示创建
+
+没有 stash 记录
+
+检测到未提交的变更，是否创建 stash?
+❯ 是
+  否
+```
+
+### 手动创建 Stash
+
+```bash
+gw s
+# 选择 "+ 创建新 stash"
+
+检测到以下变更:
+ M src/auth.ts
+ M src/login.ts
+ ?? src/new-feature.ts
+────────────────────────────────────────
+? 检测到未跟踪的文件，是否一并 stash?
+❯ 是 (包含未跟踪文件)
+  否 (仅已跟踪文件)
+
+? Stash 消息 (可跳过): 临时保存登录功能优化
+
+✔ Stash 创建成功
+```
+
+### 创建选项
+
+#### 包含未跟踪文件
+
+```bash
+? 检测到未跟踪的文件，是否一并 stash?
+❯ 是 (包含未跟踪文件)    # 使用 git stash push -u
+  否 (仅已跟踪文件)      # 使用 git stash push
+```
+
+**区别：**
+- **包含未跟踪文件** - 新创建的文件也会被 stash
+- **仅已跟踪文件** - 只 stash 已经被 Git 跟踪的文件
+
+#### 添加描述信息
+
+```bash
+? Stash 消息 (可跳过): 临时保存用户认证功能开发进度
+
+# 生成的 stash 消息格式
+WIP on main: a1b2c3d 临时保存用户认证功能开发进度
+```
+
+**推荐的描述格式：**
+- `功能模块: 简短描述`
+- `临时保存 XXX 功能开发进度`
+- `切换分支前保存当前工作`
+- `实验性代码 - XXX 方案`
+
+## 🎯 使用场景
+
+### 场景一：临时切换分支
+
+```bash
+# 正在开发功能，需要紧急修复 Bug
+gw s
+# 选择 "创建新 stash"
+# 描述: "临时保存用户界面开发进度"
+
+# 切换到 main 分支修复 Bug
+git checkout main
+gw h
+# 修复 Bug...
+
+# 修复完成，回到原分支
+git checkout feature/user-interface
+gw s
+# 选择之前的 stash，弹出恢复工作
+```
+
+### 场景二：实验性代码
+
+```bash
+# 尝试新的实现方案
+# 修改代码进行实验...
+
+# 实验不成功，保存实验代码
+gw s
+# 描述: "实验性代码 - 新的数据处理方案"
+
+# 恢复到实验前的状态
+git checkout .
+
+# 如果后续想要查看实验代码
+gw s
+# 选择实验 stash，查看差异
+```
+
+### 场景三：代码备份
+
+```bash
+# 重要更改前创建备份
+gw s
+# 描述: "重构前的代码备份"
+
+# 进行重构...
+# 如果重构出现问题，可以快速恢复
+gw s
+# 选择备份 stash，应用恢复
+```
+
+### 场景四：跨分支应用更改
+
+```bash
+# 在 feature 分支开发了通用工具函数
+gw s
+# 描述: "通用工具函数 - 可用于多个分支"
+
+# 切换到其他分支
+git checkout another-feature
+
+# 应用相同的工具函数
+gw s
+# 选择工具函数 stash，应用（保留 stash）
+```
+
+### 场景五：从 Stash 创建功能分支
+
+```bash
+# 临时代码变成了有价值的功能
+gw s
+# 选择相关 stash
+# 选择 "创建分支"
+# 类型: feature
+# 描述: implement-auto-save
+
+# 新分支创建成功，stash 内容已应用
+# 可以继续开发这个功能
+```
+
+## 🔧 高级 Stash 技巧
+
+### 技巧一：部分文件 Stash
+
+```bash
+# 只 stash 特定文件
+git stash push -m "部分文件 stash" src/auth.ts src/login.ts
+
+# 或使用交互式 stash
+git stash push -p -m "交互式选择变更"
+```
+
+### 技巧二：Stash 与分支切换集成
+
+Git Workflow 在创建分支时会自动检测未提交更改：
+
+```bash
+gw f
+检测到未提交的更改:
+ M src/index.ts
+────────────────────────────────────────
+? 是否暂存 (stash) 这些更改后继续?
+❯ 是，暂存更改并创建分支
+  否，取消操作
+
+✔ 更改已暂存到 stash
+✔ 分支创建成功: feature/20260111-new-feature
+💡 提示: 使用 'gw s' 可以恢复暂存的更改
+```
+
+### 技巧三：Stash 命名规范
+
+**推荐的命名格式：**
+
+```bash
+# 功能模块相关
+"auth: 添加登录验证逻辑"
+"ui: 调整用户界面布局"
+"api: 优化数据获取接口"
+
+# 工作状态相关
+"临时保存 XXX 功能开发进度"
+"切换分支前保存当前工作"
+"重构前的代码备份"
+
+# 实验性代码
+"实验性代码 - 新的算法实现"
+"性能优化尝试 - 缓存方案"
+```
+
+### 技巧四：Stash 与 Git Hooks 集成
+
+```bash
+# .git/hooks/pre-checkout
+#!/bin/sh
+# 切换分支前自动检查是否需要 stash
+
+if [ -n "$(git status --porcelain)" ]; then
+  echo "检测到未提交的更改，建议使用 'gw s' 创建 stash"
+  exit 1
+fi
+```
+
+## 📊 Stash 管理度量
+
+### Stash 使用统计
+
+```bash
+#!/bin/bash
+# stash-metrics.sh
+
+echo "=== Stash 管理度量报告 ==="
+echo "时间: $(date)"
+echo
+
+# Stash 数量统计
+stash_count=$(git stash list | wc -l)
+echo "📊 当前 stash 数量: $stash_count"
+echo
+
+# Stash 年龄分析
+echo "📊 Stash 年龄分析:"
+git stash list --format="%gd %cr %gs" | head -10
+echo
+
+# 分支分布
+echo "📊 Stash 分支分布:"
+git stash list --format="%gs" | \
+  grep -o "On [^:]*" | \
+  sort | uniq -c | sort -nr
+```
+
+### Stash 清理建议
+
+```bash
+# 检查超过 30 天的 stash
+git stash list --format="%gd %ct %gs" | \
+  awk '$2 < '$(date -d '30 days ago' +%s)' {print $1, $3}' | \
+  head -5
+```
+
+## 🚨 常见问题解决
+
+### 问题一：Stash 应用冲突
+
+```bash
+❌ Stash 应用失败: 存在冲突
+```
+
+**解决方案：**
+```bash
+# 查看冲突文件
+git status
+
+# 手动解决冲突
+# 编辑冲突文件...
+
+# 标记冲突已解决
+git add .
+
+# 删除已应用的 stash（如果需要）
+git stash drop stash@{0}
+```
+
+### 问题二：Stash 列表为空
+
+```bash
+没有 stash 记录
+```
+
+**可能原因：**
+- 当前没有未提交的更改
+- 所有 stash 都已被应用或删除
+
+**解决方案：**
+- 修改一些文件后再创建 stash
+- 检查是否在正确的仓库中
+
+### 问题三：无法创建 Stash
+
+```bash
+❌ 无法创建 stash: 工作区是干净的
+```
+
+**解决方案：**
+- 确认有未提交的更改：`git status`
+- 修改文件后再尝试创建 stash
+
+### 问题四：Stash 内容丢失
+
+```bash
+❌ Stash stash@{0} 不存在
+```
+
+**解决方案：**
+```bash
+# 查看 reflog 寻找丢失的 stash
+git fsck --unreachable | grep commit | cut -d' ' -f3 | \
+  xargs git log --merges --no-walk --grep=WIP
+```
+
+## 🔗 与其他功能集成
+
+### 与分支管理集成
+
+```bash
+# 创建分支时自动处理未提交更改
+gw f
+# 自动提示是否 stash 当前更改
+
+# 删除分支前检查是否有相关 stash
+gw d
+# 提示是否有该分支的 stash 需要处理
+```
+
+### 与提交功能集成
+
+```bash
+# 提交前检查是否有相关 stash
+gw c
+# 如果检测到相关 stash，提示是否先应用
+```
+
+### 与工作流集成
+
+```bash
+# 完整的工作流示例
+gw f    # 创建分支（自动 stash 当前更改）
+gw s    # 恢复之前的 stash
+# 开发代码...
+gw c    # 提交代码
+gw s    # 临时保存未完成的工作
+gw h    # 切换处理紧急问题
+gw s    # 恢复之前的工作继续开发
+```
+
+## 💡 最佳实践
+
+### 1. 及时清理
+
+- 定期检查和清理不需要的 stash
+- 避免积累过多的 stash
+- 使用描述性的 stash 消息
+
+### 2. 合理使用
+
+- 短期临时保存使用 stash
+- 长期保存考虑创建分支
+- 重要更改及时提交而不是 stash
+
+### 3. 命名规范
+
+- 使用清晰的描述信息
+- 包含功能模块和简短说明
+- 避免使用默认的 WIP 消息
+
+### 4. 安全操作
+
+- 应用 stash 前先查看差异
+- 重要 stash 先应用（保留）再删除
+- 定期备份重要的 stash 内容
+
+---
+
+通过 Git Workflow 的可视化 stash 管理，你可以轻松处理临时代码变更，提高开发效率。合理使用 stash 功能，让你的工作流程更加灵活和高效。