@zjex/git-workflow 0.4.4 → 0.4.6

package/docs/guide/debug-mode.md

@@ -0,0 +1,384 @@
+# Debug 模式
+
+Debug 模式可以帮助你诊断命令执行失败的原因，显示详细的命令、输出和错误信息。
+
+## 启用 Debug 模式
+
+在任何命令后添加 `--debug` 或 `-d` 参数：
+
+```bash
+# 基本用法
+gw tag --debug
+gw tag -d
+
+# 其他命令
+gw f --debug
+gw b --debug
+gw c --debug
+gw s --debug
+```
+
+## Debug 输出内容
+
+启用 debug 模式后，你会看到：
+
+### 1. 模式提示
+
+```
+🐛 Debug 模式已启用
+```
+
+### 2. 执行的命令
+
+每次执行 Git 命令时，会显示完整的命令字符串：
+
+```
+[DEBUG] 执行命令: git tag -a "v1.5.3" -m "Release v1.5.3"
+```
+
+### 3. 退出码
+
+命令执行完成后显示退出码：
+
+```
+[DEBUG] 退出码: 0
+```
+
+- `0` 表示成功
+- 非 `0` 表示失败
+
+### 4. 标准输出
+
+如果命令有标准输出，会显示：
+
+```
+[DEBUG] 标准输出:
+Counting objects: 3, done.
+Writing objects: 100% (3/3), 256 bytes | 256.00 KiB/s, done.
+Total 3 (delta 0), reused 0 (delta 0)
+```
+
+### 5. 错误输出
+
+如果命令失败，会显示详细的错误信息：
+
+```
+[DEBUG] 错误输出:
+fatal: Failed to resolve 'HEAD' as a valid ref.
+```
+
+### 6. 故障排查信息
+
+命令失败时，还会显示额外的排查信息：
+
+```
+[DEBUG] 故障排查信息:
+  命令: git tag -a "v1.5.3" -m "Release v1.5.3"
+  工作目录: /Users/username/project
+  Shell: /bin/zsh
+  建议: 尝试在终端中直接运行上述命令以获取更多信息
+```
+
+## 使用场景
+
+### 场景 1：Tag 创建失败
+
+```bash
+$ gw tag --debug
+
+🐛 Debug 模式已启用
+
+✔ 选择 tag 前缀: v (最新: v1.5.2)
+当前最新 tag: v1.5.2
+
+────────────────────────────────────────
+
+✔ 选择版本类型: patch  → v1.5.3
+
+────────────────────────────────────────
+
+[DEBUG] 执行命令: git tag -a "v1.5.3" -m "Release v1.5.3"
+[DEBUG] 退出码: 128
+[DEBUG] 错误输出:
+fatal: Failed to resolve 'HEAD' as a valid ref.
+
+✗ tag 创建失败
+  fatal: Failed to resolve 'HEAD' as a valid ref.
+
+[DEBUG] 故障排查信息:
+  命令: git tag -a "v1.5.3" -m "Release v1.5.3"
+  工作目录: /Users/username/cmk-vue
+  Shell: /bin/zsh
+  建议: 尝试在终端中直接运行上述命令以获取更多信息
+```
+
+从这个输出可以看出：
+
+- 命令本身是正确的（引号处理正常）
+- 退出码 128 表示 Git 错误
+- 错误原因：`HEAD` 无法解析（仓库没有提交）
+
+### 场景 2：分支推送失败
+
+```bash
+$ gw f --debug
+
+🐛 Debug 模式已启用
+
+✔ 请输入需求ID: 123
+✔ 请输入描述: add-feature
+
+────────────────────────────────────────
+
+[DEBUG] 执行命令: git fetch origin main
+[DEBUG] 退出码: 0
+
+[DEBUG] 执行命令: git checkout -b "feature/20240120-123-add-feature" origin/main
+[DEBUG] 退出码: 0
+[DEBUG] 标准输出:
+Switched to a new branch 'feature/20240120-123-add-feature'
+
+✔ 分支创建成功: feature/20240120-123-add-feature
+
+────────────────────────────────────────
+
+(自动推送已启用)
+
+[DEBUG] 执行命令: git push -u origin "feature/20240120-123-add-feature"
+[DEBUG] 退出码: 128
+[DEBUG] 错误输出:
+fatal: unable to access 'https://github.com/user/repo.git/': Could not resolve host: github.com
+
+✗ 远程推送失败
+  fatal: unable to access 'https://github.com/user/repo.git/': Could not resolve host: github.com
+
+[DEBUG] 故障排查信息:
+  命令: git push -u origin "feature/20240120-123-add-feature"
+  工作目录: /Users/username/project
+  Shell: /bin/zsh
+  建议: 尝试在终端中直接运行上述命令以获取更多信息
+```
+
+从这个输出可以看出：
+
+- 分支创建成功
+- 推送失败是因为网络问题（无法解析 github.com）
+
+### 场景 3：Stash 创建失败
+
+```bash
+$ gw s --debug
+
+🐛 Debug 模式已启用
+
+没有 stash 记录
+✔ 检测到未提交的变更，是否创建 stash? 是
+✔ Stash 消息 (可选): 临时保存：修复bug
+
+[DEBUG] 执行命令: git stash push -m "临时保存：修复bug"
+[DEBUG] 退出码: 0
+[DEBUG] 标准输出:
+Saved working directory and index state On master: 临时保存：修复bug
+
+✔ Stash 创建成功
+```
+
+## 对比：普通模式 vs Debug 模式
+
+### 普通模式
+
+```bash
+$ gw tag
+
+✔ 选择 tag 前缀: v (最新: v1.5.2)
+当前最新 tag: v1.5.2
+
+────────────────────────────────────────
+
+✔ 选择版本类型: patch  → v1.5.3
+
+────────────────────────────────────────
+
+✗ tag 创建失败
+  fatal: Failed to resolve 'HEAD' as a valid ref.
+```
+
+### Debug 模式
+
+```bash
+$ gw tag --debug
+
+🐛 Debug 模式已启用
+
+✔ 选择 tag 前缀: v (最新: v1.5.2)
+当前最新 tag: v1.5.2
+
+────────────────────────────────────────
+
+✔ 选择版本类型: patch  → v1.5.3
+
+────────────────────────────────────────
+
+[DEBUG] 执行命令: git tag -a "v1.5.3" -m "Release v1.5.3"
+[DEBUG] 退出码: 128
+[DEBUG] 错误输出:
+fatal: Failed to resolve 'HEAD' as a valid ref.
+
+✗ tag 创建失败
+  fatal: Failed to resolve 'HEAD' as a valid ref.
+
+[DEBUG] 故障排查信息:
+  命令: git tag -a "v1.5.3" -m "Release v1.5.3"
+  工作目录: /Users/username/cmk-vue
+  Shell: /bin/zsh
+  建议: 尝试在终端中直接运行上述命令以获取更多信息
+```
+
+## 常见问题排查
+
+### 问题 1：Failed to resolve 'HEAD'
+
+**错误信息：**
+
+```
+fatal: Failed to resolve 'HEAD' as a valid ref.
+```
+
+**原因：** 仓库没有任何提交
+
+**解决方法：**
+
+```bash
+git add .
+git commit -m "Initial commit"
+gw tag
+```
+
+### 问题 2：Tag already exists
+
+**错误信息：**
+
+```
+fatal: tag 'v1.5.3' already exists
+```
+
+**原因：** Tag 已经存在
+
+**解决方法：**
+
+```bash
+# 删除旧 tag
+git tag -d v1.5.3
+git push origin --delete v1.5.3
+
+# 重新创建
+gw tag
+```
+
+### 问题 3：Network error
+
+**错误信息：**
+
+```
+fatal: unable to access 'https://github.com/...': Could not resolve host
+```
+
+**原因：** 网络连接问题
+
+**解决方法：**
+
+- 检查网络连接
+- 检查代理设置
+- 稍后重试
+
+### 问题 4：Permission denied
+
+**错误信息：**
+
+```
+fatal: could not read Username for 'https://github.com': terminal prompts disabled
+```
+
+**原因：** 没有配置 Git 凭据
+
+**解决方法：**
+
+```bash
+# 配置 SSH
+ssh-keygen -t ed25519 -C "your_email@example.com"
+# 添加 SSH key 到 GitHub
+
+# 或使用 HTTPS + token
+git config --global credential.helper store
+```
+
+## 提交 Bug 报告
+
+如果你遇到问题需要提交 bug 报告，请：
+
+1. **使用 debug 模式重现问题**
+
+   ```bash
+   gw <command> --debug > debug.log 2>&1
+   ```
+
+2. **包含以下信息**
+   - 完整的 debug 输出
+   - 操作系统和 Shell 版本
+   - Git 版本：`git --version`
+   - gw 版本：`gw --version`
+   - 仓库状态：`git status`
+
+3. **提交到 GitHub Issues**
+   - 附上 `debug.log` 文件
+   - 描述期望的行为
+   - 描述实际的行为
+
+## 性能影响
+
+Debug 模式会：
+
+- ✅ 捕获额外的输出信息
+- ✅ 显示更多日志
+- ⚠️ 轻微增加执行时间（通常 < 100ms）
+- ✅ 不影响命令的实际功能
+
+建议：
+
+- 日常使用：不启用 debug 模式
+- 遇到问题：启用 debug 模式排查
+- 提交 bug：必须提供 debug 输出
+
+## 相关命令
+
+```bash
+# 查看版本
+gw --version
+gw -v
+
+# 查看帮助
+gw --help
+gw -h
+
+# 启用 debug
+gw <command> --debug
+gw <command> -d
+
+# 组合使用（不支持）
+# ❌ gw --version --debug  # 不会显示 debug 信息
+# ✅ gw tag --debug        # 正确用法
+```
+
+## 实现细节
+
+Debug 模式通过以下方式实现：
+
+1. **全局标志**：在主入口设置全局 `DEBUG_MODE` 标志
+2. **命令拦截**：在 `execAsync` 中检查 debug 模式
+3. **输出捕获**：捕获 stdout 和 stderr
+4. **格式化输出**：使用颜色和前缀标识 debug 信息
+
+相关文件：
+
+- `src/index.ts` - 解析 `--debug` 参数
+- `src/utils.ts` - 实现 debug 输出逻辑

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zjex/git-workflow",
-	"version": "0.4.4",
+	"version": "0.4.6",
 	"description": "🚀 极简的 Git 工作流 CLI 工具，让分支管理和版本发布变得轻松愉快",
 	"type": "module",
 	"bin": {

package/src/commands/amend-date.ts

@@ -19,14 +19,33 @@ function formatGitDate(date: Date): string {
 
 /**
  * 解析用户输入的日期
- * 支持格式：YYYY-MM-DD (默认 00:00:00)
+ * 支持格式：
+ * - YYYY-MM-DD (默认 00:00:00)
+ * - YYYY-MM-DD HH:mm:ss
  * @param input 用户输入
  * @returns Date 对象或 null
  */
 function parseDate(input: string): Date | null {
   const trimmed = input.trim();
-  const dateMatch = trimmed.match(/^(\d{4})-(\d{2})-(\d{2})$/);
 
+  // 尝试匹配完整格式: YYYY-MM-DD HH:mm:ss
+  const fullMatch = trimmed.match(
+    /^(\d{4})-(\d{2})-(\d{2})\s+(\d{2}):(\d{2}):(\d{2})$/,
+  );
+  if (fullMatch) {
+    const [, year, month, day, hours, minutes, seconds] = fullMatch;
+    return new Date(
+      parseInt(year),
+      parseInt(month) - 1,
+      parseInt(day),
+      parseInt(hours),
+      parseInt(minutes),
+      parseInt(seconds),
+    );
+  }
+
+  // 尝试匹配简化格式: YYYY-MM-DD (默认 00:00:00)
+  const dateMatch = trimmed.match(/^(\d{4})-(\d{2})-(\d{2})$/);
   if (dateMatch) {
     const [, year, month, day] = dateMatch;
     return new Date(
@@ -120,7 +139,6 @@ export async function amendDate(commitHash?: string): Promise<void> {
         value: c,
         description: c.date,
       })),
-      pageSize: 15,
       theme,
     });
   }
@@ -133,7 +151,9 @@ export async function amendDate(commitHash?: string): Promise<void> {
   divider();
 
   // ========== 步骤 2: 输入新日期 ==========
-  console.log(colors.dim("输入日期格式: YYYY-MM-DD (如: 2026-01-19)"));
+  console.log(colors.dim("支持格式:"));
+  console.log(colors.dim("  YYYY-MM-DD (如: 2026-01-19，默认 00:00:00)"));
+  console.log(colors.dim("  YYYY-MM-DD HH:mm:ss (如: 2026-01-19 14:30:00)"));
   console.log("");
 
   const dateInput = await input({
@@ -141,7 +161,7 @@ export async function amendDate(commitHash?: string): Promise<void> {
     validate: (value) => {
       const parsed = parseDate(value);
       if (!parsed) {
-        return "日期格式不正确，请使用 YYYY-MM-DD 格式";
+        return "日期格式不正确，请使用 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss 格式";
       }
       return true;
     },

package/src/commands/amend.ts

@@ -79,7 +79,6 @@ export async function amend(commitHash?: string): Promise<void> {
         value: c,
         description: c.message,
       })),
-      pageSize: 15,
       theme,
     });
   }

package/src/index.ts

@@ -13,7 +13,7 @@
 import { cac } from "cac";
 import { select } from "@inquirer/prompts";
 import { ExitPromptError } from "@inquirer/core";
-import { checkGitRepo, theme, colors } from "./utils.js";
+import { checkGitRepo, theme, colors, setDebugMode } from "./utils.js";
 import { createBranch, deleteBranch } from "./commands/branch.js";
 import {
   listTags,
@@ -488,12 +488,20 @@ cli
     console.log("");
   });
 
-// 不使用 cac 的 version，手动处理 --version 和 --help
+// 不使用 cac 的 version，手动处理 --version、--help 和 --debug
 cli.option("-v, --version", "显示版本号");
 cli.option("-h, --help", "显示帮助信息");
+cli.option("-d, --debug", "启用调试模式，显示详细的命令和错误信息");
 
-// 在 parse 之前检查 --version 和 --help
+// 在 parse 之前检查 --version、--help 和 --debug
 const processArgs = process.argv.slice(2);
+
+// 检查是否启用 debug 模式
+if (processArgs.includes("-d") || processArgs.includes("--debug")) {
+  setDebugMode(true);
+  console.log(colors.yellow("🐛 Debug 模式已启用\n"));
+}
+
 if (processArgs.includes("-v") || processArgs.includes("--version")) {
   console.log(colors.yellow(`v${version}`));
   process.exit(0);

package/src/utils.ts

@@ -1,6 +1,25 @@
 import { execSync, spawn, type ExecSyncOptions } from "child_process";
 import type { Ora } from "ora";
 
+/**
+ * 全局 debug 模式标志
+ */
+let debugMode = false;
+
+/**
+ * 设置 debug 模式（由主入口调用）
+ */
+export function setDebugMode(enabled: boolean): void {
+  debugMode = enabled;
+}
+
+/**
+ * 获取当前 debug 模式状态
+ */
+export function isDebugMode(): boolean {
+  return debugMode;
+}
+
 export interface Colors {
   red: (s: string) => string;
   green: (s: string) => string;
@@ -104,22 +123,68 @@ export function divider(): void {
  * 使用 spawn 异步执行命令，避免阻塞 spinner
  * @param command 命令字符串
  * @param spinner 可选的 ora spinner 实例
- * @returns Promise<boolean> 成功返回 true，失败返回 false
+ * @returns Promise<{success: boolean, error?: string}> 返回执行结果和错误信息
  */
-export function execAsync(command: string, spinner?: Ora): Promise<boolean> {
+export function execAsync(
+  command: string,
+  spinner?: Ora,
+): Promise<{ success: boolean; error?: string }> {
   return new Promise((resolve) => {
-    const [cmd, ...args] = command.split(" ");
+    // Debug 模式：显示执行的命令
+    if (debugMode) {
+      console.log(colors.dim(`\n[DEBUG] 执行命令: ${colors.cyan(command)}`));
+    }
 
-    const process = spawn(cmd, args, {
+    // 使用 shell 模式执行命令，这样可以正确处理引号
+    const process = spawn(command, {
       stdio: spinner ? "pipe" : "inherit",
+      shell: true,
     });
 
+    let errorOutput = "";
+    let stdoutOutput = "";
+
+    // 捕获标准输出（debug 模式）
+    if (debugMode && process.stdout) {
+      process.stdout.on("data", (data) => {
+        stdoutOutput += data.toString();
+      });
+    }
+
+    // 捕获错误输出
+    if (process.stderr) {
+      process.stderr.on("data", (data) => {
+        errorOutput += data.toString();
+      });
+    }
+
     process.on("close", (code) => {
-      resolve(code === 0);
+      // Debug 模式：显示退出码和输出
+      if (debugMode) {
+        console.log(colors.dim(`[DEBUG] 退出码: ${code}`));
+        if (stdoutOutput) {
+          console.log(colors.dim(`[DEBUG] 标准输出:\n${stdoutOutput}`));
+        }
+        if (errorOutput) {
+          console.log(colors.dim(`[DEBUG] 错误输出:\n${errorOutput}`));
+        }
+      }
+
+      if (code === 0) {
+        resolve({ success: true });
+      } else {
+        resolve({ success: false, error: errorOutput.trim() });
+      }
     });
 
-    process.on("error", () => {
-      resolve(false);
+    process.on("error", (err) => {
+      // Debug 模式：显示进程错误
+      if (debugMode) {
+        console.log(colors.dim(`[DEBUG] 进程错误: ${err.message}`));
+        console.log(colors.dim(`[DEBUG] 错误堆栈:\n${err.stack}`));
+      }
+
+      resolve({ success: false, error: err.message });
     });
   });
 }
@@ -138,9 +203,9 @@ export async function execWithSpinner(
   successMessage?: string,
   errorMessage?: string,
 ): Promise<boolean> {
-  const success = await execAsync(command, spinner);
+  const result = await execAsync(command, spinner);
 
-  if (success) {
+  if (result.success) {
     if (successMessage) {
       spinner.succeed(successMessage);
     } else {
@@ -152,7 +217,23 @@ export async function execWithSpinner(
     } else {
       spinner.fail();
     }
+
+    // 显示具体的错误信息
+    if (result.error) {
+      console.log(colors.dim(`  ${result.error}`));
+    }
+
+    // Debug 模式：显示完整的命令和建议
+    if (debugMode) {
+      console.log(colors.yellow("\n[DEBUG] 故障排查信息:"));
+      console.log(colors.dim(`  命令: ${command}`));
+      console.log(colors.dim(`  工作目录: ${process.cwd()}`));
+      console.log(colors.dim(`  Shell: ${process.env.SHELL || "unknown"}`));
+      console.log(
+        colors.dim(`  建议: 尝试在终端中直接运行上述命令以获取更多信息\n`),
+      );
+    }
   }
 
-  return success;
+  return result.success;
 }