Git Workflow

主题

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 输出逻辑

Released under the MIT License.

Copyright © 2026 zjex