故障排查

錯誤提示會給出原因和下一步。這一頁把常見的幾種展開。

找不到 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。