故障排查

错误提示会给出原因和下一步。这一页把常见的几种展开。

找不到 git

提示：找不到 Git。请安装 Git，或在设置中选择路径。

1. 在终端运行 git --version。没有输出就先安装 Git：
   • macOS：xcode-select --install，或用 Homebrew 安装；
   • Windows：安装 Git for Windows；
   • Linux：用发行版的包管理器。
2. 如果终端里能跑、应用里仍找不到，说明应用继承的 PATH 与登录 Shell 不同。到「设置 → Git → Git 二进制」填入绝对路径，点「测试」确认。
3. 「设置 → 高级 → 日志 → 检查 PATH」可以把应用看到的目录与登录 Shell 对比，列出缺失项（macOS 与 Linux 提供）。这些目录也影响 hooks 与 Agent 能否找到 node 等工具。

仓库被锁定

提示：另一个 Git 进程正在写入这个仓库。

git 会用 .git/index.lock 保护索引。遇到这个错误时：

1. 先确认没有正在运行的 git 命令、IDE 后台任务或其他客户端；
2. 等待其结束，再重试操作；
3. 确认没有其他进程后，可以按提示清理残留的锁文件。

不要在 git 正在运行时删除锁文件，否则可能损坏索引。

超大仓库

大仓库不会让界面一次读入全部数据，但有几处明确的上限：

如果读取超时，先在「Git 输出」确认是哪条命令慢。常见原因是网络文件系统上的仓库、未拉取的 LFS 对象，或非常大的工作区。把仓库放到本地磁盘通常是最有效的改善。

提交签名失败

提示：Git 无法签名提交。

• 检查「设置 → Git → 提交签名」里的格式（OpenPGP / SSH）与密钥是否匹配你的 git config；
• SSH 签名密钥必须是仓库之外的现有公钥文件；应用不会接受粘贴的密钥内容；
• Git 版本过旧时可能无法校验某些签名格式，历史里的徽标会显示为无法验证，更新 Git 即可；
• 实在无法签名时，可以临时关闭提交签名再提交。

CRLF 与长路径

混用行尾。 一个文件同时含 CRLF 与 LF 时，片段级与行级操作会被拒绝：请整文件暂存或丢弃，或先统一行尾。

提示：该文件混用 CRLF 与 LF 行尾。

Windows 长路径。 路径超过 260 个字符时，需要系统启用长路径支持（组策略或注册表中的 LongPathsEnabled）。应用不会替你改系统设置；启用后重新打开仓库即可。

认证失败

提示：认证失败。请打开终端解锁 SSH agent 或登录。

• SSH：确认 key 已加载，ssh-add -l 能列出它；
• HTTPS：确认凭据助手已配置并能提供凭据；
• 应用不会把凭据写进日志；HTTPS 密码由 git 的 credential helper 提供；
• 令牌类凭据（Forge）在「设置 → Git → Forge 令牌」里单独管理。

推送被阻止

推送前的本地预检会拦下三类问题：

• 私钥内容 — 不可覆盖。移除密钥、改写提交，并轮换该密钥；
• 疑似令牌或冲突标记 — 需要输入 push 明确确认；
• 新增大文件 — 默认阈值 10 MiB，可调整或改用 LFS。

部分克隆无法在本地完成扫描时，会要求先获取再推送。这时预检本身没有联网。

恢复被拒绝

提示：快照与当前文件不一致，未写入任何内容。

这是设计行为：快照之后文件又改过，恢复不会覆盖新内容。可以先导出快照人工比对，或处理完当前改动后重试。快照仍然保留。

仍然解决不了

「帮助 → 导出诊断包…」会打包日志、崩溃记录、系统信息与脱敏设置。把它和复现步骤一起发给 contact@once.work。