13 · 常见问题与排查
状态：✅ 已实现 · 范围：v1 · 工程参考：
../spec.md
安装与平台
提示 Git 缺失或版本过低
GitTreeDesk 使用系统 Git（见页首 README → 前提条件）。要求 ≥ 2.23；低于 2.36 也能用，但会显示一条警告，因为部分便利功能依赖较新的 Git 行为。
- Git 已安装但没被找到：在设置 → Git → 路径里指定可执行文件的完整路径（
git.exe/git），立即生效。 - 确实没装 Git：从 git-scm.com 安装后重启应用。
macOS 打不开应用
v1 发布的 macOS 构建未签名（公证需要 Apple 开发者账号，暂时推迟）。首次打开：右键应用 → 打开 → 打开；之后即可正常启动，也可以在"系统设置 → 隐私与安全性"里选择"仍要打开"。
我的设置在哪里？如何完全重置？
| 内容 | 位置 |
|---|---|
| 用户设置、键位 | 应用 user-data 目录下的 settings.json / keybindings.json |
| 工作区设置、发现规则、终端配置 | <工作区>/.gitreedesk/（settings.json、workspace.json、terminal.json） |
缓存数据库（状态、操作日志、信任决策）是一次性的——随时可以删除，下次启动会全量重扫并重建。注意：清掉它也会忘记所有工作区的信任状态（会重新询问）。
终端配置里没有我用的 shell
在 .gitreedesk/terminal.json 里加一个自定义配置即可（第 11 页）——配置就是"命令 + 参数"的普通定义，任何 shell 都能用。
工作区与仓库发现
某个仓库没有出现在树里
按顺序排查（第 01 页）：
exclude—— 该路径（或匹配的通配符）可能被.gitreedesk/workspace.json排除了。- 深度 —— 发现过程止于
scan.maxDepth（默认 8 层）。 - 预算 —— 可能触发了 20 万目录的扫描预算；此时会弹出提示并提供"提高上限并重扫"。
- 符号链接 —— 默认不跟随。
- 嵌套仓库 —— 位于另一个仓库工作树内部的仓库会挂在父仓库下面，不在顶层；展开父仓库行找找。
应用运行期间新建或删除的仓库会在几秒内自动上屏，基本不需要手动重扫。
状态像是没刷新，或出现了"polling"标记
仓库与已展开目录的文件监听是自动的。当目录位于网络盘，或触到系统监听上限（Linux inotify）时，受影响的仓库会退化为轮询刷新——状态栏出现告警标记"部分文件夹的实时更新已暂停"，悬停可见具体文件夹。间隔见设置 → Git → 回退轮询间隔（默认 60 秒）。
操作与恢复
我不小心做了 rebase / reset --hard / 删分支，能撤销吗？
能。在每个破坏性操作之前——reset --hard、rebase（含交互式）、历史改写、stash drop、强制删除 worktree——GitTreeDesk 都会在 refs/gitreedesk/backup/… 下创建一个备份 ref，指向即将被替换的状态（第 06 页）。删除分支时，只有未合并进 HEAD 的分支会创建备份 ref；已合并的分支以记录下来的分支尖端作为恢复依据。
- 操作完成后的 toast 上直接有 Undo（撤销）。
- 之后随时可通过仓库右键菜单 → "从备份恢复…"，列表会给出备份对应操作、时间和目标 ref，每行都有 Restore（恢复） 按钮。恢复前会先把当前状态做成备份，所以一次恢复本身也能再被撤销。
- 备份 ref 不会出现在普通分支/tag 列表里（不干扰提交图），但它们是仓库里的真实 ref——在备份本身被清理之前，什么都不丢 。
操作卡在中途（merge、rebase、cherry-pick…）
这是正常的冲突流程，不是崩溃。界面会弹出操作横幅，包含 Continue / Skip / Abort 和冲突文件列表；一切都能在横幅里完成，不必回到命令行。如果你确实在终端里处理了，GitTreeDesk 也会感知并更新横幅状态（第 06 页）。
push / pull 从不提示输入密码，直接失败
这是有意为之：操作在关闭凭据提示的环境下运行，Git 永远不会因为后台刷新而挂在隐藏的输入等待上。认证优先走你现有的配置——系统凭据助手（如 Git for Windows 自带的那个）、SSH agent。GitTreeDesk 不会弹出自己的密码输入框：缺少凭据时操作以分类错误失败——认证、非快进、网络、被 hook 拒绝——各自带对应的下一步操作，Git 原始输出在"详情"抽屉里。
如果 HTTPS 远端持续认证失败，请在全局 Git 配置里配置一次凭据助手（就用你在终端里用的那套）。
提交框显示"此工作区未启用 Git 钩子"
说明该工作区尚未被信任（第 01 页）。在未信任的工作区里，Git hooks 会被抑制（覆盖 core.hooksPath），这样打开陌生人的文件夹不会执行他的 pre-commit 脚本；终端快捷命令同样被禁用。如果这是你自己的工作区，从命令面板执行**"信任此工作区"**即可，之后 hooks 正常运行，输出显示在提交框里。
点了 ✨ 生成按钮却什么都没出来
- 生成器作用于已暂存的 diff——先暂存一些内容（第 04 页）。
- 离线模式（默认）总能工作，但只识别常见的约定格式；项目里检测不到任何约定时，只能给出最小草稿。
- LLM 模式需要在设置 → 提交信息里配置提供方。检查 base URL / 模型是否已保存、主机是否可达——超时（30 秒）会回退到离线草稿。你的 API key 不会离开系统钥匙串（见下一条）。
LLM 的 API key 存在哪里？
用 safeStorage 存在系统钥匙串里（钥匙串 / 凭据管理器 / libsecret）。Linux 上没有钥匙环服务时，key 仅保留在当前会话并明确提示——绝不明文落盘。LLM 生成默认关闭，而且对某个主机的首次请求会请你确认"将暂存区 diff 发送至该主机"（第 04 页）。离线模式下数据完全不出本机。
性能与显示
仓库很大时应用感觉慢
- 未跟踪文件通常是主因。未跟踪内容极多的仓库（构建产物、下载的模型）保持默认
untrackedStrategy: "normal"（设置 → Git）：按仓库开"all"会逐个列出所有未跟踪文件，只在小仓库里值得。 - 提交图：超大历史按页加载（先 1 000 行，之后每 2 000 行一块）；加载下一页时图上会有加载指示。过滤器能减少需要加载的量（第 09 页）。
- 性能预算（首屏树、状态刷新、图滚动）是发布门槛，在参考场景上测量——在这种规模的工作区里卡顿会被当作 bug 处理。反馈时请把设置 → 高级 → 日志详细度调高，并附上 Output 面板内容。
diff 里全是 CRLF / 空白噪音
GitTreeDesk从不归一化换行符：完全遵循 core.autocrlf 与 .gitattributes（交给 Git 处理），展示的也是原始 diff。diff 视图有忽略空白开关，只影响显示，不影响暂存内容（第 03 页）。
文档与反馈
怎么提功能需求或报告 bug？
这份指南就是功能需求清单（见页首 README → "本文档如何驱动开发"）：
- 想改行为？直接改对应页面——默认值、交互或边界情况——然后对 AI 说："实现
<页面>§<章节>"。 - 后续版本的想法：行内标
[Later]。 - 报告 bug：在对应页面的章节里写清"预期行为 vs 实际行为"，AI 负责实现修复并更新该页的 Status 行。与
../spec.md的冲突会先被指出，在 spec 中解决后再落地。