Skip to content

Issue 191

Jump to bottom
clean edited this page Oct 6, 2026 · 1 revision

Issue #191：子模块管理与 Git LFS 文件展示

背景与目标

Alune 过去只识别改动列表中的子模块，缺少初始化、更新和打开入口；LFS 文件的指针内容也难以解释实际文件变化。本次提供本地与 SSH 仓库的基础子模块管理，以及 LFS 状态、元数据和已下载图片展示，不包含 LFS 锁定。

方案与取舍

子模块

在文件视图加入独立分组，基于暂存区 gitlink 读取记录提交，在已初始化目录读取当前提交与脏状态，递归列出已初始化的嵌套子模块。未初始化子模块须先更新才能读取其内部模块。

初始化／更新执行 git submodule update --init --recursive，同步执行 git submodule sync --recursive，均沿用执行主机的认证与 Alune 代理。更新不使用 --force，不会强行覆盖未提交内容；Git 写操作沿用超时、互斥和取消机制。失败或部分完成后重新读取状态。

打开前校验该路径确属已初始化子模块，沿用本地／SSH 来源登记为独立仓库，并复用已有登记。Diff 使用 --submodule=log 显示前后提交及摘要。

Git LFS

在仓库所在主机检测 git-lfs 与文件的 LFS 属性。Diff 和文件预览解析指针，显示实际大小与 SHA-256 OID。图片按对应版本的 OID 查找执行主机缓存，支持自定义存储和 linked worktree 的缓存定位，读取时校验大小与摘要，沿用 5 MiB 图片上限。预览不会触发下载；缺失时提示在仓库主机运行 git lfs pull。

推送／拉取通过 GIT_LFS_FORCE_PROGRESS 和标准输出／错误回调显示 LFS 阶段，失败保留 Git 原文。git lfs 内部的通配路径检出需要取消全局 literal-pathspecs 标志。

缺少已配置为必需的 git-lfs filter 时，仅状态／Diff 读取禁用缺失 filter 后重试，避免整个仓库无法打开。写入仍保留失败，防止将水合文件误提交为普通 Git blob。

验收状态

  • 已在本地和回环 SSH 验证子模块状态、递归初始化、同步与未提交改动保护。
  • 已验证子模块路径校验、同源登记和浏览器新标签打开及状态读取。
  • 已验证 LFS Diff／预览元数据、真实图片加载、缓存校验与缺失提示。
  • 已验证缺失 git-lfs 时普通文件读取／Diff 和状态仍可用，LFS 写入不被静默放行。
  • 已验证本地与真实回环 SSH/SFTP 的 LFS 提交、推送、克隆、拉取流程。
  • 前后截图与视觉审查：浏览器截图工具持续超时，不能把 DOM 通过等同于视觉验收。
  • Windows/Linux 原生桌面、独立 SSH 主机、真实私有托管认证与代理组合现场验收。

验证记录

日期：2026-10-07。环境：macOS arm64，Node.js 25.5.0。完整 LFS 流程使用临时 git-lfs 3.8.0，不安装到系统；所有集成仓库和 SSH 服务为隔离测试资源。

命令 / 场景 实际结果
shared、ssh-client、server、web 构建 通过
npm test -w server -- --runInBand 30 个套件、315 项通过
npm test -w web 262 项通过
执行层全量回归（PATH 中提供临时 git-lfs） 初次 236 项通过、1 项失败、4 项平台测试跳过；失败为原先期待 Subproject commit 的旧断言，与新提交摘要展示不符
node --test packages/ssh-client/tests/change-entries.test.cjs 更新断言后 9/9 通过；发起 PR 时再次复测 9/9 通过。没有将首次全量失败记录改写成全量通过
submodules-lfs.test.cjs 本地与真实 SSH/SFTP 9 项通过，包含嵌套子模块、缺失必需 filter、OID 校验和真实 LFS 提交／推拉
实际浏览器点击与 DOM 子模块新标签可正常读取状态；失败提示刷新后保留；脏文件未被覆盖；LFS 显示真实大小／OID；缓存 PNG 解码为 1×1 像素
commitlint、版本推送校验、git diff --check 通过
截图 Page.captureScreenshot 超时，无可发布截图；没有替代为伪造的视觉验收

风险与回退

无数据库迁移。未安装 git-lfs 时，水合 LFS 文件的状态判断可能不准确；预览不会自动修复安装或下载对象。网络认证与代理复用现有能力，独立部署现场组合仍待验收。子模块取消可能保留已经完成的步骤，须以刷新后的状态为准。

回退代码使用正常 revert；Wiki 为独立 Git 历史，需要单独核对和更新。

关联资料

设计文档首页 · Alune 品牌说明 · 维护约定 · 代码仓库

Alune

Clone this wiki locally