跳到主要内容

01 · 工作区与仓库树

状态：✅ 已实现 · 范围：v1 · 工程参考：../spec.md

打开工作区​

  • 首次启动进入欢迎页：最近工作区列表与"打开文件夹…"。也可以用菜单（File → Open Folder…），或把文件夹拖进窗口。
  • 工作区就是一个文件夹——不要求是 Git 仓库。通常指向一个包含多个仓库的文件夹（如 E:\Projects\acme）。
  • 最近列表保留最近 10 个工作区，每项右键可"从列表移除"。重新打开工作区原地完成，无需重启。
  • v1 为单窗口：打开另一个工作区会替换当前窗口内容。

会发现什么​

GitTreeDesk 遍历文件夹，发现任意深度的 Git 仓库、链接 worktree 与 submodule。发现规则：

规则默认
跳过的目录node_modules、.git、.svn、.hg（外加 exclude 中配置的）
符号链接不跟随
最大深度8 层
安全预算200 000 个目录；超限时给出提示，可调高后继续
  • 允许仓库嵌套在另一仓库的工作树里，以父子形式展示。
  • 放在独立目录（如 __worktree__/）里的链接 worktree 会挂到其主仓库下，而不是当作无关文件夹（详见第 02 页）。
  • 应用运行期间新建的仓库会被自动发现——树自动更新，无需手动刷新。
  • 不想被扫描的文件夹加进 exclude（见下）——适用于备份目录、fixtures、大数据目录等。

工作区配置 —— .gitreedesk/workspace.json​

在工作区根目录创建此文件即可调整发现与分组规则。不含任何机密，可以提交到仓库。

{
  "name": "acme",
  "exclude": ["content/中文文档", "**/fixtures/**"],
  "scan": { "maxDepth": 8, "followSymlinks": false },
  "groups": [{ "name": "Backend", "match": ["backend/*"] }]
}
  • exclude —— 追加的跳过模式（glob），相对工作区根。
  • groups —— 可选；不配置时分组取自首层路径段。
  • 该文件在工作区打开时读取；修改在下次打开（或重新扫描）后生效。

信任​

工作区第一次打开时会询问是否信任——按工作区根各询问一次。在信任之前：

  • 该工作区内提交与历史改写使用的 Git hooks 被抑制（本应执行 pre-commit 的提交将在无 hook 的情况下完成——提交框会显示 "此工作区未启用 Git 钩子"）；
  • 工作区自定义的终端快捷命令被禁用。

信任状态按工作区根记忆。之后可在命令面板更改："信任此工作区" / "撤销信任"。

两个树视图​

侧栏的 Tree 活动下有两个协同视图，数据来自同一份仓库注册表：

Explorer 视图 —— 真实文件系统树​

  • 文件夹按磁盘上的样子展示。仓库文件夹带徽标（分支名或短 SHA）；worktree 文件夹带 worktree 图标。
  • 目录惰性加载；只监听已展开的文件夹。
  • 文件与文件夹操作（右键菜单）：新建文件、新建文件夹、在系统文件管理器中显示、在 VS Code 中打开、在此打开终端、复制路径（绝对路径）、复制相对路径、重命名（F2）、移入回收站——按分割线分组；属于某仓库的任意行还会多出打开提交图。删除会把内容移入系统回收站（可逆）。
  • 对比两个文件 —— 右键一个文件选择选作对比基准（该行会被高亮），再在第二个文件上选择与所选对比。这一对文件会在 diff 查看器中并排打开：字母序靠前的路径固定在左侧，同一对文件无论先选哪个都复用同一个标签页。两张图片以 2-up 并排预览展示，并带有与 diff 视图相同的洋葱皮开关；其他组合则说明为什么无法比较。这两个入口在命令面板里同样可用，作用于光标所在的行。
  • 对比一个文件夹 —— 右键一个文件夹（或仓库自身那一行）选择文件夹与…对比，再从文件 diff 使用的同一份列表里挑一个基线：INDEX、HEAD 或任意分支 / ref。它会列出该路径下相对基线、针对工作区的改动，点其中一行就打开该文件的 diff。详见第 03 页。
  • JS/TS/JSON 等文件在内置编辑器中打开（第 10 页）。

Repos 视图 —— 逻辑仓库树​

  • 仓库是一级行：名称、当前分支（或 detached @ <短sha>）与状态徽标。
  • 链接 worktree 与 submodule 嵌套显示在其主仓库下（第 02、08 页）。
  • 位于工作区之外的 worktree 默认隐藏；在视图选项中开启 "显示外部 worktree" 后以灰色 + 绝对路径显示。
  • 分组：默认取自首层路径段，或通过 workspace.json 的 groups 配置。
  • 多选仓库做批量操作："Fetch 所选"、"Pull 所选（仅快进）"。
  • 仓库右键菜单：复制路径、在系统中显示、打开终端、打开提交图标签，以及上述批量操作。仓库行右缘的 … 按钮打开完全相同的菜单，常用操作不必再右键。

徽标与展示项（显示选项）​

两个视图共用同一套徽标。每一类徽标都有独立的 View options 开关：

徽标含义开关
●工作树脏（有未提交变更）脏状态
↓n ↑n落后 / 领先 upstream同步状态
⚑nstash 数量stash
⟳有进行中的操作（merge、rebase……）操作状态
detachedHEAD 处于 detached 状态detached
◇ ⧉ main bare仓库类别：submodule 需要处理、被锁定或已失效的 worktree、主 worktree、裸仓库仓库徽标

树上方的快捷过滤："仅 dirty"、"仅 ahead/behind"、"仅 worktree"。

逐仓库勾选：每个仓库行可勾选，决定它是否进入 Source Control 视图——仓库多时可以把变更列表收窄到手头正在处理的几个（第 03 页）——以及是否进入工作区时间线（第 09 页）。视图工具栏提供"全选 / 全不选"。

树内键盘操作​

  • ↑ / ↓ 移动，← / → 折叠 / 展开，Enter 在 Explorer 中打开文件，在两个树里切换该行的展开状态。
  • F2 重命名，Delete 删除（回收站），Ctrl/Cmd+P 在工作区中快速打开任意文件（遵守 exclude）。
  • Ctrl/Cmd+R 按名字跳转到仓库。

提示与边界情况​

  • 空文件夹 —— 空态提示，附"打开其他文件夹"。
  • 未发现任何仓库 —— 树内提示（检查 exclude / scan.maxDepth，或此文件夹确实没有仓库）。
  • 超出预算 —— 可关闭的提示说明扫描提前停止，附"调高上限并重新扫描"。
  • 磁盘上新增 / 删除仓库——应用运行期间会自动反映，通常在数秒内。