@zjex/git-workflow 0.4.5 → 0.4.7

package/README.md

@@ -12,7 +12,7 @@
   <a href="https://github.com/iamzjt-front-end/git-workflow"><img src="https://img.shields.io/github/stars/iamzjt-front-end/git-workflow?style=flat&colorA=18181B&colorB=F59E0B" alt="github stars"></a>
   <a href="https://github.com/iamzjt-front-end/git-workflow/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@zjex/git-workflow?style=flat&colorA=18181B&colorB=10B981" alt="license"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-339933?style=flat&logo=node.js&logoColor=white&colorA=18181B" alt="node version"></a>
-  <a href="https://github.com/iamzjt-front-end/git-workflow/actions"><img src="https://img.shields.io/badge/tests-435%20passed-success?style=flat&colorA=18181B" alt="tests"></a>
+  <a href="https://github.com/iamzjt-front-end/git-workflow/actions"><img src="https://img.shields.io/badge/tests-474%20passed-success?style=flat&colorA=18181B" alt="tests"></a>
   <a href="https://github.com/iamzjt-front-end/git-workflow/issues"><img src="https://img.shields.io/github/issues/iamzjt-front-end/git-workflow?style=flat&colorA=18181B&colorB=EC4899" alt="issues"></a>
 </p>
 

package/dist/index.js

@@ -11,6 +11,9 @@ var __export = (target, all) => {
 
 // src/utils.ts
 import { execSync, spawn } from "child_process";
+function setDebugMode(enabled) {
+  debugMode = enabled;
+}
 function exec(cmd, silent = false) {
   try {
     const options = {
@@ -53,21 +56,58 @@ function divider() {
 }
 function execAsync(command, spinner) {
   return new Promise((resolve) => {
-    const [cmd, ...args] = command.split(" ");
-    const process2 = spawn(cmd, args, {
-      stdio: spinner ? "pipe" : "inherit"
+    if (debugMode) {
+      console.log(colors.dim(`
+[DEBUG] \u6267\u884C\u547D\u4EE4: ${colors.cyan(command)}`));
+    }
+    const process2 = spawn(command, {
+      stdio: spinner ? "pipe" : "inherit",
+      shell: true
     });
+    let errorOutput = "";
+    let stdoutOutput = "";
+    if (debugMode && process2.stdout) {
+      process2.stdout.on("data", (data) => {
+        stdoutOutput += data.toString();
+      });
+    }
+    if (process2.stderr) {
+      process2.stderr.on("data", (data) => {
+        errorOutput += data.toString();
+      });
+    }
     process2.on("close", (code) => {
-      resolve(code === 0);
+      if (debugMode) {
+        console.log(colors.dim(`[DEBUG] \u9000\u51FA\u7801: ${code}`));
+        if (stdoutOutput) {
+          console.log(colors.dim(`[DEBUG] \u6807\u51C6\u8F93\u51FA:
+${stdoutOutput}`));
+        }
+        if (errorOutput) {
+          const label = code === 0 ? "\u8F93\u51FA\u4FE1\u606F" : "\u9519\u8BEF\u8F93\u51FA";
+          console.log(colors.dim(`[DEBUG] ${label}:
+${errorOutput}`));
+        }
+      }
+      if (code === 0) {
+        resolve({ success: true });
+      } else {
+        resolve({ success: false, error: errorOutput.trim() });
+      }
     });
-    process2.on("error", () => {
-      resolve(false);
+    process2.on("error", (err) => {
+      if (debugMode) {
+        console.log(colors.dim(`[DEBUG] \u8FDB\u7A0B\u9519\u8BEF: ${err.message}`));
+        console.log(colors.dim(`[DEBUG] \u9519\u8BEF\u5806\u6808:
+${err.stack}`));
+      }
+      resolve({ success: false, error: err.message });
     });
   });
 }
 async function execWithSpinner(command, spinner, successMessage, errorMessage) {
-  const success = await execAsync(command, spinner);
-  if (success) {
+  const result = await execAsync(command, spinner);
+  if (result.success) {
     if (successMessage) {
       spinner.succeed(successMessage);
     } else {
@@ -79,13 +119,27 @@ async function execWithSpinner(command, spinner, successMessage, errorMessage) {
     } else {
       spinner.fail();
     }
+    if (result.error) {
+      console.log(colors.dim(`  ${result.error}`));
+    }
+    if (debugMode) {
+      console.log(colors.yellow("\n[DEBUG] \u6545\u969C\u6392\u67E5\u4FE1\u606F:"));
+      console.log(colors.dim(`  \u547D\u4EE4: ${command}`));
+      console.log(colors.dim(`  \u5DE5\u4F5C\u76EE\u5F55: ${process.cwd()}`));
+      console.log(colors.dim(`  Shell: ${process.env.SHELL || "unknown"}`));
+      console.log(
+        colors.dim(`  \u5EFA\u8BAE: \u5C1D\u8BD5\u5728\u7EC8\u7AEF\u4E2D\u76F4\u63A5\u8FD0\u884C\u4E0A\u8FF0\u547D\u4EE4\u4EE5\u83B7\u53D6\u66F4\u591A\u4FE1\u606F
+`)
+      );
+    }
   }
-  return success;
+  return result.success;
 }
-var colors, TODAY, theme;
+var debugMode, colors, TODAY, theme;
 var init_utils = __esm({
   "src/utils.ts"() {
     "use strict";
+    debugMode = false;
     colors = {
       red: (s) => `\x1B[31m${s}\x1B[0m`,
       green: (s) => `\x1B[32m${s}\x1B[0m`,
@@ -1006,6 +1060,25 @@ async function createTag(inputPrefix) {
 }
 async function doCreateTag(tagName) {
   divider();
+  const hasCommits = execOutput("git rev-parse HEAD 2>/dev/null");
+  if (!hasCommits) {
+    console.log(colors.red("\u5F53\u524D\u4ED3\u5E93\u6CA1\u6709\u4EFB\u4F55\u63D0\u4EA4"));
+    console.log("");
+    console.log(colors.dim("  \u63D0\u793A: \u9700\u8981\u5148\u521B\u5EFA\u81F3\u5C11\u4E00\u4E2A\u63D0\u4EA4\u624D\u80FD\u6253 tag:"));
+    console.log(colors.cyan("  git add ."));
+    console.log(colors.cyan('  git commit -m "Initial commit"'));
+    console.log(colors.cyan("  gw tag"));
+    return;
+  }
+  const existingTags = execOutput("git tag -l").split("\n").filter(Boolean);
+  if (existingTags.includes(tagName)) {
+    console.log(colors.red(`Tag ${tagName} \u5DF2\u5B58\u5728`));
+    console.log("");
+    console.log(colors.dim("  \u63D0\u793A: \u5982\u9700\u91CD\u65B0\u521B\u5EFA\uFF0C\u8BF7\u5148\u5220\u9664\u65E7 tag:"));
+    console.log(colors.cyan(`  git tag -d ${tagName}`));
+    console.log(colors.cyan(`  git push origin --delete ${tagName}`));
+    return;
+  }
   const spinner = ora2(`\u6B63\u5728\u521B\u5EFA tag: ${tagName}`).start();
   const success = await execWithSpinner(
     `git tag -a "${tagName}" -m "Release ${tagName}"`,
@@ -1153,9 +1226,12 @@ async function updateTag() {
     spinner.fail("tag \u91CD\u547D\u540D\u5931\u8D25");
     return;
   }
-  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("\u5220\u9664\u65E7 tag \u5931\u8D25");
+    if (deleteResult.error) {
+      console.log(colors.dim(`  ${deleteResult.error}`));
+    }
     return;
   }
   spinner.succeed(`Tag \u5DF2\u91CD\u547D\u540D: ${oldTag} \u2192 ${newTag}`);
@@ -1169,26 +1245,32 @@ async function updateTag() {
   });
   if (pushRemote) {
     const pushSpinner = ora2("\u6B63\u5728\u540C\u6B65\u5230\u8FDC\u7A0B...").start();
-    const pushNewSuccess = await execAsync(
+    const pushNewResult = await execAsync(
       `git push origin "${newTag}"`,
       pushSpinner
     );
-    if (!pushNewSuccess) {
+    if (!pushNewResult.success) {
       pushSpinner.warn(
         `\u8FDC\u7A0B\u540C\u6B65\u5931\u8D25\uFF0C\u53EF\u7A0D\u540E\u624B\u52A8\u6267\u884C:
   git push origin ${newTag}
   git push origin --delete ${oldTag}`
       );
+      if (pushNewResult.error) {
+        console.log(colors.dim(`  ${pushNewResult.error}`));
+      }
       return;
     }
-    const deleteOldSuccess = await execAsync(
+    const deleteOldResult = await execAsync(
       `git push origin --delete "${oldTag}"`,
       pushSpinner
     );
-    if (!deleteOldSuccess) {
+    if (!deleteOldResult.success) {
       pushSpinner.warn(
         `\u8FDC\u7A0B\u65E7 tag \u5220\u9664\u5931\u8D25\uFF0C\u53EF\u7A0D\u540E\u624B\u52A8\u6267\u884C: git push origin --delete ${oldTag}`
       );
+      if (deleteOldResult.error) {
+        console.log(colors.dim(`  ${deleteOldResult.error}`));
+      }
       return;
     }
     pushSpinner.succeed(`\u8FDC\u7A0B tag \u5DF2\u540C\u6B65: ${oldTag} \u2192 ${newTag}`);
@@ -1241,8 +1323,8 @@ async function cleanInvalidTags() {
   let localSuccess = 0;
   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++;
@@ -1268,11 +1350,11 @@ async function cleanInvalidTags() {
     let remoteSuccess = 0;
     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++;
@@ -2753,16 +2835,28 @@ function clearUpdateCache2() {
   }
 }
 async function getLatestVersion2(packageName) {
-  try {
-    const result = execSync4(`npm view ${packageName} version`, {
-      encoding: "utf-8",
-      timeout: 3e3,
-      stdio: ["pipe", "pipe", "ignore"]
+  return new Promise((resolve) => {
+    const npmView = spawn3("npm", ["view", packageName, "version"], {
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5e3
     });
-    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);
+    });
+  });
 }
 function isUsingVolta2() {
   try {
@@ -3533,7 +3627,7 @@ process.on("SIGTERM", () => {
   console.log("");
   process.exit(0);
 });
-var version = true ? "0.4.5" : "0.0.0-dev";
+var version = true ? "0.4.7" : "0.0.0-dev";
 async function mainMenu() {
   console.log(
     colors.green(`
@@ -3813,7 +3907,12 @@ cli.command("clean", "\u6E05\u7406\u7F13\u5B58\u548C\u4E34\u65F6\u6587\u4EF6").a
 });
 cli.option("-v, --version", "\u663E\u793A\u7248\u672C\u53F7");
 cli.option("-h, --help", "\u663E\u793A\u5E2E\u52A9\u4FE1\u606F");
+cli.option("-d, --debug", "\u542F\u7528\u8C03\u8BD5\u6A21\u5F0F\uFF0C\u663E\u793A\u8BE6\u7EC6\u7684\u547D\u4EE4\u548C\u9519\u8BEF\u4FE1\u606F");
 var processArgs = process.argv.slice(2);
+if (processArgs.includes("-d") || processArgs.includes("--debug")) {
+  setDebugMode(true);
+  console.log(colors.yellow("\u{1F41B} Debug \u6A21\u5F0F\u5DF2\u542F\u7528\n"));
+}
 if (processArgs.includes("-v") || processArgs.includes("--version")) {
   console.log(colors.yellow(`v${version}`));
   process.exit(0);

package/docs/.vitepress/config.ts

@@ -54,6 +54,8 @@ export default defineConfig({
           items: [
             { text: "开发指南", link: "/guide/development" },
             { text: "测试指南", link: "/guide/testing" },
+            { text: "Debug 模式", link: "/guide/debug-mode" },
+            { text: "命令引号处理", link: "/guide/command-quotes-handling" },
             { text: "API 文档", link: "/guide/api" },
             { text: "贡献指南", link: "/guide/contributing" },
           ],

package/docs/guide/command-quotes-handling.md

@@ -0,0 +1,279 @@
+# 命令参数引号处理
+
+本文档说明了 git-workflow 如何正确处理带引号和特殊字符的命令参数。
+
+## 问题背景
+
+在早期版本中，使用简单的字符串分割方式处理命令参数：
+
+```typescript
+// ❌ 错误的方式
+const [cmd, ...args] = command.split(" ");
+spawn(cmd, args);
+```
+
+这种方式无法正确处理引号：
+
+```javascript
+'git tag -a "v1.5.3" -m "Release v1.5.3"'.split(" ");
+// 结果: ["git", "tag", "-a", '"v1.5.3"', "-m", '"Release', 'v1.5.3"']
+// 引号被当作参数的一部分！
+```
+
+导致的问题：
+
+- Tag 名称包含引号：`"v1.5.3"` 而不是 `v1.5.3`
+- Git 报错：`fatal: Failed to resolve '"v1.5.3"' as a valid ref.`
+
+## 解决方案
+
+使用 `shell: true` 选项让 spawn 通过 shell 执行命令：
+
+```typescript
+// ✅ 正确的方式
+spawn(command, {
+  stdio: spinner ? "pipe" : "inherit",
+  shell: true, // 使用 shell 模式
+});
+```
+
+### 优势
+
+1. **正确处理引号**：Shell 会自动解析和移除引号
+2. **支持特殊字符**：emoji、中文、空格等都能正确处理
+3. **支持转义**：`\"` 等转义字符正常工作
+
+## 支持的场景
+
+### 1. Tag 命令
+
+```bash
+# 基本版本号
+gw tag  # 创建 v1.5.3
+
+# 预发布版本
+gw tag  # 创建 v1.0.0-beta.1
+
+# 带特殊字符
+git tag -a "v1.0.0-🎉" -m "Release 🎉"
+```
+
+### 2. Branch 命令
+
+```bash
+# 带日期和描述的分支
+gw b feature  # 创建 feature/20240120-123-add-feature
+
+# 删除带特殊字符的分支
+git branch -D "feature/20240120-123-add-feature"
+git push origin --delete "feature/20240120-123-add-feature"
+```
+
+### 3. Stash 命令
+
+```bash
+# 带中文的 stash 消息
+git stash push -m "临时保存：修复登录bug"
+
+# 带引号的消息
+git stash push -m "WIP: 添加\"新功能\""
+
+# 从 stash 创建分支
+git stash branch "feature/from-stash" stash@{0}
+```
+
+### 4. Commit 命令
+
+```bash
+# 带特殊字符的提交消息
+git commit -m "feat: add \"quotes\" support"
+git commit -m "fix: 修复登录问题 🐛"
+```
+
+## 测试覆盖
+
+我们创建了全面的测试用例来确保引号处理的正确性：
+
+### 测试场景
+
+1. **基本引号处理**
+   - 带引号的 tag 名称
+   - 带空格的分支名称
+   - 带特殊字符的 commit message
+
+2. **特殊字符支持**
+   - Emoji：`v1.0.0-🎉`
+   - 中文：`临时保存：修复bug`
+   - 转义引号：`feat: add \"quotes\" support`
+
+3. **错误处理**
+   - 捕获 stderr 错误信息
+   - 显示详细的失败原因
+   - 提供解决建议
+
+### 运行测试
+
+```bash
+# 运行引号处理测试
+npm test -- tests/command-with-quotes.test.ts
+
+# 运行所有测试
+npm test
+```
+
+## 错误信息改进
+
+现在当命令失败时，会显示详细的错误信息：
+
+### Tag 已存在
+
+```
+✗ Tag v1.5.3 已存在
+
+  提示: 如需重新创建，请先删除旧 tag:
+  git tag -d v1.5.3
+  git push origin --delete v1.5.3
+```
+
+### 没有提交
+
+```
+✗ 当前仓库没有任何提交
+
+  提示: 需要先创建至少一个提交才能打 tag:
+  git add .
+  git commit -m "Initial commit"
+  gw tag
+```
+
+### Git 命令错误
+
+```
+✗ tag 创建失败
+  fatal: Failed to resolve 'HEAD' as a valid ref.
+```
+
+## 实现细节
+
+### execAsync 函数
+
+```typescript
+export function execAsync(
+  command: string,
+  spinner?: Ora,
+): Promise<{ success: boolean; error?: string }> {
+  return new Promise((resolve) => {
+    const process = spawn(command, {
+      stdio: spinner ? "pipe" : "inherit",
+      shell: true, // 关键：使用 shell 模式
+    });
+
+    let errorOutput = "";
+
+    // 捕获错误输出
+    if (process.stderr) {
+      process.stderr.on("data", (data) => {
+        errorOutput += data.toString();
+      });
+    }
+
+    process.on("close", (code) => {
+      if (code === 0) {
+        resolve({ success: true });
+      } else {
+        resolve({ success: false, error: errorOutput.trim() });
+      }
+    });
+
+    process.on("error", (err) => {
+      resolve({ success: false, error: err.message });
+    });
+  });
+}
+```
+
+### execWithSpinner 函数
+
+```typescript
+export async function execWithSpinner(
+  command: string,
+  spinner: Ora,
+  successMessage?: string,
+  errorMessage?: string,
+): Promise<boolean> {
+  const result = await execAsync(command, spinner);
+
+  if (result.success) {
+    if (successMessage) {
+      spinner.succeed(successMessage);
+    } else {
+      spinner.succeed();
+    }
+  } else {
+    if (errorMessage) {
+      spinner.fail(errorMessage);
+    } else {
+      spinner.fail();
+    }
+
+    // 显示具体的错误信息
+    if (result.error) {
+      console.log(colors.dim(`  ${result.error}`));
+    }
+  }
+
+  return result.success;
+}
+```
+
+## 最佳实践
+
+### 1. 始终使用引号包裹可能包含特殊字符的参数
+
+```typescript
+// ✅ 推荐
+await execAsync(`git tag -a "${tagName}" -m "Release ${tagName}"`);
+
+// ❌ 不推荐（如果 tagName 包含空格会失败）
+await execAsync(`git tag -a ${tagName} -m Release ${tagName}`);
+```
+
+### 2. 转义用户输入中的引号
+
+```typescript
+// ✅ 正确处理用户输入
+const message = userInput.replace(/"/g, '\\"');
+await execAsync(`git commit -m "${message}"`);
+```
+
+### 3. 使用 execWithSpinner 显示进度
+
+```typescript
+// ✅ 推荐：显示进度和错误信息
+const spinner = ora("正在创建 tag...").start();
+const success = await execWithSpinner(
+  `git tag -a "${tagName}" -m "Release ${tagName}"`,
+  spinner,
+  "Tag 创建成功",
+  "Tag 创建失败",
+);
+
+if (!success) {
+  // 错误信息已自动显示
+  return;
+}
+```
+
+## 相关文件
+
+- `src/utils.ts` - execAsync 和 execWithSpinner 实现
+- `tests/command-with-quotes.test.ts` - 引号处理测试
+- `src/commands/tag.ts` - Tag 命令实现
+- `src/commands/branch.ts` - Branch 命令实现
+- `src/commands/stash.ts` - Stash 命令实现
+
+## 版本历史
+
+- **v0.4.5** - 修复引号处理问题，添加详细错误信息
+- **v0.4.4** - 修复 spinner 阻塞问题
+- **v0.4.3** - 添加 execAsync 和 execWithSpinner 函数