@zjex/git-workflow 0.4.5 → 0.4.7

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.5",
+	"version": "0.4.7",
 	"description": "🚀 极简的 Git 工作流 CLI 工具，让分支管理和版本发布变得轻松愉快",
 	"type": "module",
 	"bin": {

package/scripts/generate-changelog-manual.js

@@ -30,7 +30,7 @@ for (let i = 0; i < tags.length; i++) {
   if (!previousTag) break;
 
   changelog += `## [${currentTag}](https://github.com/iamzjt-front-end/git-workflow/compare/${previousTag}...${currentTag}) (${getTagDate(
-    currentTag
+    currentTag,
   )})\n\n`;
 
   // 获取该版本的提交
@@ -39,79 +39,30 @@ for (let i = 0; i < tags.length; i++) {
     {
       encoding: "utf8",
       env: { ...process.env, LANG: "zh_CN.UTF-8", LC_ALL: "zh_CN.UTF-8" },
-    }
+    },
   )
     .trim()
     .split("\n")
     .filter(Boolean);
 
-  // 按类型分组
-  const groups = {
-    "✨ Features": [],
-    "🐛 Bug Fixes": [],
-    "📖 Documentation": [],
-    "🎨 Styles": [],
-    "♻️ Refactors": [],
-    "⚡ Performance": [],
-    "✅ Tests": [],
-    "🔧 Chore": [],
-    "🤖 CI": [],
+  // 格式化消息：处理多行内容（用 - 分隔的子任务）
+  const formatMessage = (msg, commitLink) => {
+    const parts = msg.split(" - ");
+    if (parts.length === 1) {
+      // 没有子任务，直接返回
+      return `${msg} ${commitLink}`;
+    }
+    // 有子任务，主标题后面加 commit hash，子任务换行缩进
+    const mainTitle = parts[0];
+    const subTasks = parts.slice(1);
+    return `${mainTitle} ${commitLink}\n  - ${subTasks.join("\n  - ")}`;
   };
 
+  // 直接输出提交信息，不分组
   commits.forEach((commit) => {
     const [message, hash] = commit.split("|");
     const link = `([${hash}](https://github.com/iamzjt-front-end/git-workflow/commit/${hash}))`;
-
-    if (message.match(/^(feat|✨)/i)) {
-      groups["✨ Features"].push(
-        `- ${message.replace(/^(feat|✨)[:(]\w*\)?:?\s*/i, "")} ${link}`
-      );
-    } else if (message.match(/^(fix|🐛)/i)) {
-      groups["🐛 Bug Fixes"].push(
-        `- ${message.replace(/^(fix|🐛)[:(]\w*\)?:?\s*/i, "")} ${link}`
-      );
-    } else if (message.match(/^(docs|📖|📝)/i)) {
-      groups["📖 Documentation"].push(
-        `- ${message.replace(/^(docs|📖|📝)[:(]\w*\)?:?\s*/i, "")} ${link}`
-      );
-    } else if (message.match(/^(style|🎨)/i)) {
-      groups["🎨 Styles"].push(
-        `- ${message.replace(/^(style|🎨)[:(]\w*\)?:?\s*/i, "")} ${link}`
-      );
-    } else if (message.match(/^(refactor|♻️)/i)) {
-      groups["♻️ Refactors"].push(
-        `- ${message.replace(/^(refactor|♻️)[:(]\w*\)?:?\s*/i, "")} ${link}`
-      );
-    } else if (message.match(/^(perf|⚡)/i)) {
-      groups["⚡ Performance"].push(
-        `- ${message.replace(/^(perf|⚡)[:(]\w*\)?:?\s*/i, "")} ${link}`
-      );
-    } else if (message.match(/^(test|✅)/i)) {
-      groups["✅ Tests"].push(
-        `- ${message.replace(/^(test|✅)[:(]\w*\)?:?\s*/i, "")} ${link}`
-      );
-    } else if (message.match(/^(chore|🔧|🏡)/i)) {
-      groups["🔧 Chore"].push(
-        `- ${message.replace(/^(chore|🔧|🏡)[:(]\w*\)?:?\s*/i, "")} ${link}`
-      );
-    } else if (message.match(/^(ci|🤖)/i)) {
-      groups["🤖 CI"].push(
-        `- ${message.replace(/^(ci|🤖)[:(]\w*\)?:?\s*/i, "")} ${link}`
-      );
-    } else {
-      groups["🔧 Chore"].push(`- ${message} ${link}`);
-    }
-  });
-
-  // 输出各分组
-  Object.entries(groups).forEach(([title, items]) => {
-    if (items.length > 0) {
-      changelog += `### ${title}\n\n`;
-      items.forEach((item) => {
-        changelog += `${item}\n`;
-      });
-      changelog += "\n";
-    }
+    changelog += `- ${formatMessage(message, link)}\n`;
   });
 
   changelog += "\n";

package/src/commands/tag.ts

@@ -418,6 +418,29 @@ export async function createTag(inputPrefix?: string): Promise<void> {
 async function doCreateTag(tagName: string): Promise<void> {
   divider();
 
+  // 检查是否有提交
+  const hasCommits = execOutput("git rev-parse HEAD 2>/dev/null");
+  if (!hasCommits) {
+    console.log(colors.red("当前仓库没有任何提交"));
+    console.log("");
+    console.log(colors.dim("  提示: 需要先创建至少一个提交才能打 tag:"));
+    console.log(colors.cyan("  git add ."));
+    console.log(colors.cyan('  git commit -m "Initial commit"'));
+    console.log(colors.cyan("  gw tag"));
+    return;
+  }
+
+  // 检查 tag 是否已存在
+  const existingTags = execOutput("git tag -l").split("\n").filter(Boolean);
+  if (existingTags.includes(tagName)) {
+    console.log(colors.red(`Tag ${tagName} 已存在`));
+    console.log("");
+    console.log(colors.dim("  提示: 如需重新创建，请先删除旧 tag:"));
+    console.log(colors.cyan(`  git tag -d ${tagName}`));
+    console.log(colors.cyan(`  git push origin --delete ${tagName}`));
+    return;
+  }
+
   const spinner = ora(`正在创建 tag: ${tagName}`).start();
   const success = await execWithSpinner(
     `git tag -a "${tagName}" -m "Release ${tagName}"`,
@@ -614,9 +637,12 @@ export async function updateTag(): Promise<void> {
   }
 
   // 删除旧 tag
-  const deleteSuccess = await execAsync(`git tag -d "${oldTag}"`, spinner);
-  if (!deleteSuccess) {
+  const deleteResult = await execAsync(`git tag -d "${oldTag}"`, spinner);
+  if (!deleteResult.success) {
     spinner.fail("删除旧 tag 失败");
+    if (deleteResult.error) {
+      console.log(colors.dim(`  ${deleteResult.error}`));
+    }
     return;
   }
 
@@ -635,26 +661,32 @@ export async function updateTag(): Promise<void> {
     const pushSpinner = ora("正在同步到远程...").start();
 
     // 推送新 tag
-    const pushNewSuccess = await execAsync(
+    const pushNewResult = await execAsync(
       `git push origin "${newTag}"`,
       pushSpinner,
     );
-    if (!pushNewSuccess) {
+    if (!pushNewResult.success) {
       pushSpinner.warn(
         `远程同步失败，可稍后手动执行:\n  git push origin ${newTag}\n  git push origin --delete ${oldTag}`,
       );
+      if (pushNewResult.error) {
+        console.log(colors.dim(`  ${pushNewResult.error}`));
+      }
       return;
     }
 
     // 删除远程旧 tag
-    const deleteOldSuccess = await execAsync(
+    const deleteOldResult = await execAsync(
       `git push origin --delete "${oldTag}"`,
       pushSpinner,
     );
-    if (!deleteOldSuccess) {
+    if (!deleteOldResult.success) {
       pushSpinner.warn(
         `远程旧 tag 删除失败，可稍后手动执行: git push origin --delete ${oldTag}`,
       );
+      if (deleteOldResult.error) {
+        console.log(colors.dim(`  ${deleteOldResult.error}`));
+      }
       return;
     }
 
@@ -729,8 +761,8 @@ export async function cleanInvalidTags(): Promise<void> {
   let localFailed = 0;
 
   for (const tag of invalidTags) {
-    const success = await execAsync(`git tag -d "${tag}"`, localSpinner);
-    if (success) {
+    const result = await execAsync(`git tag -d "${tag}"`, localSpinner);
+    if (result.success) {
       localSuccess++;
     } else {
       localFailed++;
@@ -761,11 +793,11 @@ export async function cleanInvalidTags(): Promise<void> {
     let remoteFailed = 0;
 
     for (const tag of invalidTags) {
-      const success = await execAsync(
+      const result = await execAsync(
         `git push origin --delete "${tag}"`,
         remoteSpinner,
       );
-      if (success) {
+      if (result.success) {
         remoteSuccess++;
       } else {
         remoteFailed++;

package/src/commands/update.ts

@@ -27,16 +27,32 @@ function clearUpdateCache(): void {
  * 获取 npm 上的最新版本
  */
 async function getLatestVersion(packageName: string): Promise<string | null> {
-  try {
-    const result = execSync(`npm view ${packageName} version`, {
-      encoding: "utf-8",
-      timeout: 3000,
-      stdio: ["pipe", "pipe", "ignore"],
+  return new Promise((resolve) => {
+    const npmView = spawn("npm", ["view", packageName, "version"], {
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
     });
-    return result.trim();
-  } catch {
-    return null;
-  }
+
+    let output = "";
+
+    if (npmView.stdout) {
+      npmView.stdout.on("data", (data) => {
+        output += data.toString();
+      });
+    }
+
+    npmView.on("close", (code) => {
+      if (code === 0 && output.trim()) {
+        resolve(output.trim());
+      } else {
+        resolve(null);
+      }
+    });
+
+    npmView.on("error", () => {
+      resolve(null);
+    });
+  });
 }
 
 /**

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);