Issue 185 - ShaoClean/Alune GitHub Wiki
Issue #185：Git 标签管理
- 类型：功能
- 状态：已实现，本地验证通过，待 PR 审阅
- Issue：https://github.com/ShaoClean/Alune/issues/185
- PR：https://github.com/ShaoClean/Alune/pull/197
- 最近更新：2026-10-06（北京时间）
- 代码基线：
development/c567e48；实现提交：01416cdbca85407ba892fd4c063e505d141fa117
背景与问题
提交图能显示标签，但应用中缺少创建、删除和单独推送入口，用户发布版本时仍需使用终端。
目标与范围
在分支页管理本地 Git 标签：显示名称、提交、轻量／附注类型和说明，支持搜索、创建、推送、确认删除及检出。在提交详情中允许基于任意历史提交创建标签。对本地、Worktree 与 SSH 使用一致的操作。
本次不包含标签签名和 GitHub／GitLab Release。远程只支持单个推送地址；不提供覆盖远程同名标签的强制推送入口。
方案与取舍
入口与交互
- “分支”页增加标签分组，按 Git 版本名称倒序排列。搜索覆盖名称、提交哈希及附注。
- “创建标签”默认指向 HEAD，历史详情中的入口固定到所选提交哈希。附注标签必须填写说明，重名和非法名称会提示；成功后刷新提交图。
- 独立查询所选远程的标签状态，区分未推送、远程已存在、同名对象不同及状态未知。网络错误不会清空本地列表。
- 删除确认可选择同时删除远程同名标签。远程状态未知时，必须先刷新才能勾选；远程对象不同会额外提示。同一仓库的所有 Worktree 共享标签。
- 检出默认引导创建新分支；选择直接检出时明确提示游离 HEAD 风险。指向非提交对象的标签仍显示，但不提供检出。
执行与接口
新增 GitTags，复用 RepositoryTransport 和 runGit。本地使用参数数组执行 Git，SSH 使用现有安全参数引用。服务端写入沿用仓库操作互斥、超时及取消机制；读取标签设置 30 秒上限。
| 接口 | 用途 |
|---|---|
GET /repositories/:id/tags |
本地标签列表 |
GET /repositories/:id/tags/remote?remote=origin |
所选远程推送地址上的标签 |
POST /repositories/:id/tags |
创建轻量／附注标签 |
POST /repositories/:id/tags/push |
单个或全部标签推送 |
POST /repositories/:id/tags/delete |
确认删除本地及可选远程同名标签 |
POST /repositories/:id/tags/checkout |
基于标签创建分支或检出游离 HEAD |
使用完整 refs/tags/... 引用，推送指定 refspec 并关闭隐式 follow-tags，避免影响同名分支或其他标签。远程状态以推送 URL 为准，而不是 fetch URL。
本地删除校验确认时的对象哈希，并用 update-ref 的旧对象条件删除；远程删除使用明确的 force-with-lease 条件。远程删除失败时保留本地标签。远程成功、本地失败时明确报告部分完成，不伪装回滚。检出保留 Git 对未提交修改的保护。
验收标准
- 查看、搜索标签及其指向的提交，显示类型和附注。
- 从 HEAD 与历史提交创建轻量／附注标签，提交图随即更新；校验重名与非法名称。
- 本地与远程删除均需确认，结果与
git tag、git ls-remote --tags一致。 - 单个与全部标签推送可用，失败显示原因，同名分支不受影响。
- 本地、Worktree、回环 SSH、SSH Worktree 的真实 Git 流程验证通过。
- 创建新分支或明确确认游离 HEAD；保护可能被覆盖的未提交修改。
验证记录
以下记录均为 2026-10-05，macOS ARM64、Node.js 25.5.0，对应上述代码提交。SSH 验证使用本机回环 SSH 测试服务和临时仓库，不代表生产 SSH 主机或 Windows/Linux 原生桌面现场验收。
| 命令或场景 | 结果与证据 |
|---|---|
npm test -w web |
240 项通过。开发中曾因组件直接引入 CSS 导致测试加载失败，调整到统一样式入口后重跑通过。 |
npm run test -w @alune/ssh-client |
155 项通过，2 项仅在 Windows 执行的测试在当前平台跳过。 |
node --test packages/ssh-client/tests/tags.test.cjs |
6 项通过，覆盖本地／Worktree／SSH／SSH Worktree，另验证重名、非法输入、历史提交、附注、多行中文、签名配置、同名分支、不同 push URL、远程冲突、旧确认哈希、离线读取、未提交修改及非提交对象。 |
npm test -w server -- --runInBand git/local-git.spec.ts git/git.controller.spec.ts |
28 项通过，使用真实 Git、SQLite 和 HTTP；验证参数错误、确认条件、Worktree 共享标签及本地／远程删除。 |
npm run desktop:build |
6 个构建任务通过；构建保留已有大 chunk 提示。未运行完整安装包现场验收。 |
| 桌面宽度浏览器操作 | 创建多行附注标签、搜索、单独推送、从标签创建分支、同时删除本地与远程标签均通过；用 Git 命令核对删除结果。 |
| 历史提交创建与校验 | 在历史提交创建轻量标签，提交图立即出现新引用；重名及非法名称提示通过。 |
| 390px 窄窗口与游离 HEAD | 搜索、标签信息和操作按钮可见；确认提示明确，检出后 Git 状态为 HEAD (no branch)。 |
| 提交检查 | git diff --check 与 commitlint 通过。 |
界面证据
变更前：分支页只有本地、远程分支操作，没有标签管理分组；未采集变更前截图。以下为本次实现和验收过程中的实际截图，宽窗口截图采集后去掉了标题旁仅统计分支的数字，最终标题见窄窗口截图。
2026-10-06：同步 development 后的回归
合并提交：420dd6fd55bc7663da2494d58edc3d9b10487c46，同步 development / aaaa4bc45e4e6d404beb0dafd62b5f408d765692。解决 7 个文件中的类型导入、API、样式入口和操作提示冲突，保留标签管理、冲突处理与交互式变基功能。
本次验证环境为 macOS ARM64、Node.js 25.5.0；真实 Git、临时仓库与回环 SSH 服务。
| 命令或场景 | 结果与证据 |
|---|---|
npm run desktop:build |
6 个构建任务通过；已有大 chunk 提示仍存在。 |
npm test -w web |
248 项通过。 |
node --test packages/ssh-client/tests/tags.test.cjs packages/ssh-client/tests/conflict-resolution.test.cjs packages/ssh-client/tests/interactive-rebase.test.cjs |
40 项通过，覆盖标签、冲突处理和交互式变基。 |
npm test -w server -- --runInBand git/local-git.spec.ts git/git.controller.spec.ts git/interactive-rebase.spec.ts |
35 项通过。补充标签与变基保护的集成回归：暂停时允许列出标签，创建、删除、推送、创建分支与游离检出均返回 409；HEAD、工作区状态、标签引用不变，中止后恢复创建标签。 |
git diff --check、commitlint |
通过，无未解决的冲突。 |
此次未重新执行浏览器现场验收；上方界面证据保留为 2026-10-05 的历史记录。Windows/Linux 原生桌面与生产 SSH 主机仍未现场验证。
风险、未决事项与回退
- 多推送地址的远程暂不支持；需选择只有一个推送地址的远程。远程访问使用当前执行主机的 Git 认证配置。
- Windows/Linux 原生桌面、生产 SSH 主机、签名标签创建未验证；签名和 Release 创建属于明确排除范围。
- 本地与远程删除跨两次 Git 操作，无法保证跨仓库原子回滚；错误信息和刷新用于揭示部分完成。
- 无数据库迁移。可回退代码提交恢复原入口；已创建、删除、推送或检出的 Git 状态不会随代码回退自动撤销。Wiki 与代码使用独立历史，应分别回退。