whygit

whygit

我的 Git 仓库刚刚发生了什么？该如何修复？

whygit 会检查 Git 仓库，用通俗易懂的语言告诉你仓库当前的状态，以及哪些命令可以帮你摆脱困境：合并冲突、进行到一半而停止的变基、分离的 HEAD、被拒绝的推送、GitHub 不接受的登录，或一个 GitHub 会拒绝的 120 MB CSV 文件。把错误消息贴给它，它也会解释。

它面向初次接触 Git 的人。Git 自带的消息虽然准确，却难以理解；whygit 会将它们转化为简短说明和确切的修复方法。

它只会读取你的仓库，绝不会运行它建议的修复命令，因此你始终掌控全局，并能在过程中逐步学习这些命令。

它有两种使用方式，底层使用同一引擎：

• 在命令行中使用，不涉及 AI 工具：whygit。
• 作为 MCP 服务使用，让 Claude Code、Claude Desktop 或 Cursor 等助手能获得可靠的诊断，而不是根据 git status 猜测。

安装

whygit 需要 Python 3.10 或更高版本，以及 Git。选择一种方式：

uv tool install whygit     # with uv (https://docs.astral.sh/uv/)
pipx install whygit        # with pipx
uvx whygit                 # run once without installing

在 macOS、Windows 和 Linux 上的使用方法相同。

在终端中使用

在项目文件夹中运行：

whygit                    # what's wrong here, most urgent first
whygit status             # a plain summary: branch, upstream, what's changed
whygit explain "fatal: refusing to merge unrelated histories"
git push 2>&1 | whygit explain -

选项：使用 --path <folder>（或 -C）查看其他文件夹，使用 --json 输出机器可读的结果，使用 --no-color 关闭颜色。只有在真实终端中才会使用颜色，且设置了 NO_COLOR 时不会使用颜色。

退出码：0 表示没有阻塞问题，1 表示发现了阻塞问题，2 表示用法错误（例如文件夹不存在），3 表示 explain 无法识别该消息。

示例

$ whygit
whygit: /Users/sam/ds3500/hw2 (branch main)

[BLOCKING] Merge in progress with conflicts in 1 file
  Git tried to combine two lines of work, but both changed the same part of these
  files, so it stopped and is waiting for you to choose what the result should be.
  Nothing is lost while you decide.
  Conflicted files:
    - analysis.py  (both changed)
  How to fix:
    Finish the merge:
      1. Open each file and find the blocks between <<<<<<< and >>>>>>>. The part
         above ======= is one version, the part below is the other. Keep what you
         want, and delete the three marker lines.
      2. git add analysis.py
         Marks the files as resolved
      3. git commit --no-edit
         Records the merge and finishes it
    Or cancel the merge:
      1. git merge --abort
         Puts everything back the way it was before the merge started
  Learn more: https://git-scm.com/docs/git-merge#_how_to_resolve_conflicts

1 blocking. whygit never runs these commands for you; copy the ones you want.

可能丢失工作的命令（例如 git restore、git rebase --skip、git push --force-with-lease）始终会标注警告；如果有更安全的选项，会优先列出。

与 AI 助手搭配使用（MCP）

whygit mcp 会通过 stdio 运行一个 Model Context Protocol 服务，并提供三个只读工具：

工具	适用场景	返回内容
diagnose_repo(path=".")	感觉有什么操作卡住或出错时	找到的所有问题，按紧急程度排序，并附带说明和修复方法
explain_git_error(error_text, path=None)	Git 命令输出了错误时	错误的含义和修复方法；如果给出了 path，还会参考仓库状态
explain_state(path=".")	想要了解中立的概要时	分支、上游、领先/落后状态、远程仓库、暂存和已更改的文件、正在进行的操作

结果是精简的 JSON 对象。请传入绝对路径：相对路径会根据服务的工作目录解析；对于桌面应用，该目录通常不是你的项目目录。~ 可用。

Claude Code

claude mcp add --scope user whygit -- uvx whygit mcp

--scope user 会让它在每个项目中都可用；省略此参数则只会将它添加到当前项目中。使用 claude mcp list 检查。

Claude Desktop

打开 Settings > Developer > Edit Config，并将 whygit 添加到 claude_desktop_config.json（在 macOS 上是 ~/Library/Application Support/Claude/，在 Windows 上是 %APPDATA%\Claude\）：

{
  "mcpServers": {
    "whygit": {
      "command": "uvx",
      "args": ["whygit", "mcp"]
    }
  }
}

重启 Claude Desktop。如果它找不到 uvx，请将 which uvx（macOS）或 where uvx（Windows）输出的完整路径用作 command。

Cursor

将相同的代码块添加到 ~/.cursor/mcp.json（适用于所有项目）或项目中的 .cursor/mcp.json：

{
  "mcpServers": {
    "whygit": {
      "command": "uvx",
      "args": ["whygit", "mcp"]
    }
  }
}

如果你通过 uv tool install 或 pipx 安装了 whygit，也可以将 "command": "whygit" 与 "args": ["mcp"] 搭配使用。

它能识别的情况

仓库状态：合并冲突（以及已解决但尚未提交的合并，包括残留的 <<<<<<< 标记）、因冲突或 edit 而停止的变基、正在进行的 cherry-pick、revert、git am 和 bisect、分离的 HEAD（以及没有分支指向的提交）、与上游分支分叉／落后／领先、尚无上游分支（首次执行 git push -u）、没有远程仓库、上游分支已删除、尚无提交、当前目录不是仓库（包括目录层级高了一层和你的主目录）、意外被变成仓库的主目录、嵌套仓库（下载的入门代码中很常见）、已暂存或位于未推送提交中的超出 GitHub 100 MB 限制（以及超过 50 MB）的文件、通常包含密钥的文件（.env、id_rsa、*.pem、kaggle.json、凭据 JSON）、含有大量已保存输出的笔记本、Jupyter 笔记本冲突、缺少 user.name／user.email、残留的 index.lock，以及 Git 因“可疑所有权”而拒绝访问的文件夹。

错误消息：推送被拒绝、“You have divergent branches”、“refusing to merge unrelated histories”、GitHub 登录失败（密码已无法使用；它会说明令牌、SSH 和 gh auth login 的用法，并且绝不会索要你的令牌）、Permission denied (publickey)、找不到仓库、403、“Your local changes would be overwritten”、未跟踪文件阻挡操作、“not a git repository”、“src refspec main does not match any”、“pathspec did not match”、“remote origin already exists”、缺少上游分支、“couldn't find remote ref”、GitHub 拒绝大文件（GH001）、“detected dubious ownership”、“Please tell me who you are”、index.lock 已存在、行尾警告、网络错误等。如果它无法识别某条消息，会如实说明，并展示它在仓库中能看到的内容。

只读承诺

whygit 绝不会更改你的仓库；这一点由代码强制保障，而非依赖良好意愿：

• 所有 Git 命令都通过一个只接受只读子命令（status、rev-parse、for-each-ref、rev-list、diff、log、ls-files、cat-file、config --get、remote -v 等）的单一函数执行，其他命令一律拒绝，包括 config、remote 和 symbolic-ref 的写入形式。
• 它会设置 GIT_OPTIONAL_LOCKS=0，因此即使执行 git status 也不会刷新索引；同时会禁用外部 diff 程序和 fsmonitor 钩子。
• 它绝不会运行 git fetch。领先／落后计数以“上次获取时的状态”为准；在需要时，whygit 会提示你自行运行 git fetch。
• 测试套件会在真实仓库中构建每种状态，在诊断前后对 .git 下的每个文件（名称、时间戳和内容）进行快照，并检查是否有任何改动。它还会检查软件包中的其他模块是否能启动进程或写入文件。

绝不会打印凭据：像 https://name:[email protected]/... 这样的远程地址，在所有输出中都会显示为 https://***@github.com/...。

隐私

whygit 不会收集任何信息，也不会发起网络请求。它只会读取你自己计算机上的仓库并打印结果，仅此而已。

许可证

MIT。版权所有 (c) 2026 Kameswara Sai Srikar Manda。