GitTreeDesk — 使用指南与功能说明
状态：✅ 已实现 —— 本指南描述的 v1 行为均已落地。 英文版为权威版本；本文件是站点
zh-Hans语言目录（website/i18n/zh-Hans/…）下的同步译文。 工程参考：../spec.md（架构、关键决策、性能预算）。
本文档如何驱动开发
这个目录既是使用手册，也是开发需求入口。工作流：
- 修改你要的功能所在页面（或新增章节 / 新页面）。
- 对 AI 说："实现
<页面>§<章节>"。 - AI 完成实现、验证行为，并更新该页的 Status 行。
编辑规则：
- 用现在时描述目标行为，就像产品已经完成一样："点击 X 会打开 Y。"
- 默认值、交互、错误提示与边界情况都是需求的一部分——改动时请明确写出。
- 属于后续版本的想法，行内标注
[Later]。 - 如果改动与
../spec.md冲突，AI 必须先指出冲突并建议同步更新 spec，不得默默偏离。 - 代码注释、标识符与提交信息一律不引用文档编号（
F4、AD-12、页码）。这些文档是实现期的过渡产物，功能上线后可能删除，编号会在代码历史里留下无法解析的引用——请改用行为描述（"在 diff 视图中暂存单个 hunk"，而不是"按 F7 实现"）。 - 你改任意一种语言即可，AI 负责同步另一版本。
状态图例：🚧 计划中 · 🔨 进行中 · ✅ 已实现
GitTreeDesk 是什么
工作区优先的多仓库 Git 工作台。打开任意文件夹——它本身不必是 Git 仓库——即可在一棵树里管理其中所有 Git 仓库、worktree 与 submodule：完整的 Git 操作、逐仓库提交图、带 diff 的文件浏览与轻量编辑、集成终端。它刻意不是通用 IDE；需要更深的代码智能时，提供一键"在 VSCode 中打开"逃生口。
前提条件
| Git | 要求 ≥ 2.23（建议 ≥ 2.36）。从 PATH 读取，可在设置中覆盖。版本过低或未安装时会给出提示。 |
| 操作系统 | Windows 10+ · macOS 11+ · Linux（AppImage / deb） |
快速上手
- 安装对应平台的 GitTreeDesk（安装包，或 Windows 便携 zip）。
- 首次启动进入欢迎页：最近工作区列表、"打开文件夹…"和一个拖放区——也可以直接把文件夹拖进窗口。
- 打开工作区根目录。 任意文件夹都可以，不要求是 Git 仓库。例如
E:\Projects\acme。 - 信任提示。 工作区第一次打开时会询问是否信任它——按工作区根各询问一次。在信任之前，GitTreeDesk 会抑制 Git hooks（覆盖
core.hooksPath）并禁用工作区自定义的终端快捷命令。信任状态按工作区根记忆，之后可通过命令面板更改（"信任此工作区" / "撤销信任"）。 - 仓库渐进出现。 目录发现完成后树一次性显示，随后状态与徽标随后台刷新逐个补齐（见第 01 页）。
窗口一览
┌ 标题栏：工作区名 · 窗口控制 ─────────────────────────────────────────────┐
│ 活动 │ 主侧栏 │ 编辑区（标签） │
│ 栏 │ ▸ Explorer │ • 文件 • diff • 提交图 │
│ 树 │ ▸ Repos │ • 设置 • 键位参考 │
│ SCM │ ▸ Source Control │ │
│ 图 │ ▸ Graph ├──────────────────────────────────┤
│ ⚙ │ │ 次侧栏：详情 │
│ │ │ （提交、文件、仓库）——可开关 │
├──────┴──────────────────────────────┴──────────────────────────────────┤
│ 底部面板：Terminal │ Output（Git 操作日志） ——可折叠 │
├─────────────────────────────────────────────────────────────────────────┤
│ 状态栏：工作区 · 分支 · ↓↑ · 主题 · 语言 · Git 版本 │
└─────────────────────────────────────────────────────────────────────────┘
- 活动栏在 Tree、Source Control、Graph、Settings 之间切换侧栏；终端在底部面板。
- 状态栏显示工作区名、当前仓库分支与 ahead/behind、主题、语言和 Git 版本——点击分支可打开分支选择器。
- 所有功能都能从命令面板（Ctrl/Cmd+Shift+P）触达，并有默认快捷键（第 12 页）。
五分钟走一遍
- 打开你的工作区，把侧栏切到 Tree。
- 在 Repos 视图里找一个带
●徽标的仓库（有未提交变更），点击它。 - Source Control 视图列出它的变更——点击文件看 diff，暂存文件（或单个 hunk），输入提交信息（或按 ✨ 生成按钮），然后 Commit。
- 打开该仓库的 Graph 标签；右键你刚提交的 commit——分支、tag、cherry-pick、revert 等操作都在那里。
- 按
Ctrl+`在仓库根目录打开终端，运行你惯用的命令。
页面索引
| # | 页面 | 内容 | 状态 |
|---|---|---|---|
| — | 01 工作区与仓库树 | 打开工作区、仓库发现、信任、Explorer 与 Repos 视图、徽标、过滤 | ✅ |
| — | 02 Worktree | 展示、创建、移动、删除、prune、lock——worktree 一等公民 | ✅ |
| — | 03 变更与 Diff | 多仓库变更列表、暂存、丢弃、diff 查看器、文件历史 | ✅ |
| — | 04 提交与提交信息 | 提交、amend、历史改写（消息/作者/时间）、提交信息生成（离线 + LLM） | ✅ |
| — | 05 分支、远端与标签 | 分支操作、远端、fetch/pull/push、tag、批量操作 | ✅ |
| — | 06 合并、变基与冲突 | merge、rebase（含交互式）、cherry-pick、revert、reset、冲突解决、安全网 | ✅ |
| — | 07 Stash | stash 的创建、列表、应用与删除 | ✅ |
| — | 08 Submodule | submodule 展示、状态、一键更新、sync | ✅ |
| — | 09 提交图 | 逐仓库提交 图、工作区活动时间线、过滤、提交操作、大仓库处理 | ✅ |
| — | 10 编辑器 | 文件查看与轻量编辑、TypeScript 提示、diff、在 VSCode 中打开 | ✅ |
| — | 11 终端 | Shell 配置、按目录级联配置、快捷命令 | ✅ |
| — | 12 设置与键位 | 设置界面、配置文件、默认快捷键、命令面板、键位自定义 | ✅ |
| — | 13 常见问题与排查 | 常见问题、恢复流程、如何提功能需求 | ✅ |