故障排查

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

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