@zjex/git-workflow 0.4.5 → 0.4.6

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [v1.0.0](https://github.com/iamzjt-front-end/git-workflow/compare/v0.4.5...v1.0.0) (2026-01-19)
+
+
+## [v0.4.5](https://github.com/iamzjt-front-end/git-workflow/compare/v0.4.4...v0.4.5) (2026-01-19)
+
+### ✨ Features
+
+- 更新日期格式说明，支持完整时间输入 ([25f2b39](https://github.com/iamzjt-front-end/git-workflow/commit/25f2b39))
+
+### 📖 Documentation
+
+- 📝 docs: 自动更新测试数量徽章 [skip ci] ([c49a4bd](https://github.com/iamzjt-front-end/git-workflow/commit/c49a4bd))
+
+### 🔧 Chore
+
+- 🔖 chore(release): 发布 v0.4.5 ([8abd7b4](https://github.com/iamzjt-front-end/git-workflow/commit/8abd7b4))
+
+
 ## [v0.4.4](https://github.com/iamzjt-front-end/git-workflow/compare/v0.4.3...v0.4.4) (2026-01-19)
 
 ### ✨ Features

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,57 @@ 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) {
+          console.log(colors.dim(`[DEBUG] \u9519\u8BEF\u8F93\u51FA:
+${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 +118,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`,
@@ -3533,7 +3586,7 @@ process.on("SIGTERM", () => {
   console.log("");
   process.exit(0);
 });
-var version = true ? "0.4.5" : "0.0.0-dev";
+var version = true ? "0.4.6" : "0.0.0-dev";
 async function mainMenu() {
   console.log(
     colors.green(`
@@ -3813,7 +3866,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/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 函数