Unison 的 `delete.project` 命令:项目删除语义与实现原理完全指南

原创2026-10-08 21:38:501,700 阅读
文章标签:编程语言编译器语言运行时开发工具

Unison 的 delete.project 命令:项目删除语义与实现原理完全指南

本指南基于 Unison 代码库管理工具(UCM)的行为转录文档 delete-project.md 编写,系统讲解 delete.project 命令的语法、别名、参数解析、五种典型删除场景以及“删除最后一个项目后自动补位”的特殊语义。通过对照 DeleteProject.hs 的源码实现,读者可以深入理解该命令从命令行解析、输入分派到数据库事务执行的完整调用链,从而在自己的 Unison 项目中安全地管理项目生命周期。

命令概览:语法、别名与参数

delete.project 是 UCM 中用于删除本地项目的命令。它的命令模式定义在 InputPatterns.hs 中,核心要素如下:

项目 值
主命令名 delete.project
别名 project.delete、rm.project
可见性 可见(I.Visible,会在命令帮助与补全中展示)
参数 必填一个 project to delete(项目名),使用 projectNameArg 解析器
参数数量约束 wrongArgsLength "exactly one argument",多传或漏传参数都会报错
帮助文本 `delete.project foo` → “deletes the local project foo”

从解析逻辑看,命令只接收一个项目名参数:parse 分支中 name : _ -> Input.DeleteProjectI <$> handleProjectArg name 会提取首个参数并交给 handleProjectArg 完成项目名的校验与规范化;其余分支(参数个数不对)统一报“exactly one argument”错误。

命令解析成功后生成 Input.DeleteProjectI ProjectName 指令,该指令类型定义于 Input.hs。在 HandleInput.hs 中,DeleteProjectI name -> handleDeleteProject name 将该指令分派给实际的处理器。

五种删除场景逐项演示

转录文档 delete-project.md 通过一段连续的 UCM 会话,完整覆盖了 delete.project 的五种行为。下面逐项复现并解释其语义。

准备:创建两个空项目

会话首先创建两个空项目:

scratch/main> project.create-empty foo
scratch/main> project.create-empty bar

project.create-empty 命令定义于 InputPatterns.hs,其命令名为 project.create-empty,别名为 create.empty-project(内部隐藏命令),可携带可选的 project name 参数;不传参数时生成随机项目名,传参时创建指定名称的项目。命令成功后提示符随之切换为 scratch/main> 中的对应项目(此处创建 foo、bar 两个空项目,但会话仍停留在 scratch/main)。

场景一:删除当前所在项目

scratch/main> delete.project scratch
foo/main> projects

在 scratch/main 提示符下执行 delete.project scratch,删除的是当前正处于其中的 scratch 项目。删除成功后,UCM 自动将当前上下文切换到一个仍然存在的项目——本例中切换到了 foo/main。

执行 projects 列出全部项目,输出为:

  1. bar
  2. foo

即 scratch 已被删除,剩余 foo 与 bar 两个项目。

场景二:删除一个非当前项目

foo/main> delete.project bar
foo/main> projects

在 foo/main 中删除另一个项目 bar。注意此时当前项目是 foo,被删除对象是 bar,删除后不需要切换上下文,仍停留在 foo/main。projects 输出:

  1. foo

说明可以随时删除任意指定的本地项目,无论它是否就是当前项目。

场景三:删除最后一个项目,系统自动补位

foo/main> delete.project foo
project/main> projects

此时 foo 是最后一个剩余项目。删除它之后,UCM 的提示符切换成了 project/main,而 projects 列表显示:

  1. project
  2. scratch

这说明:当被删除的项目是最后一个项目时,UCM 会自动创建一个名为 scratch 的占位项目(并切换到该项目),以保证代码库中始终至少存在一个可用的项目上下文。这个自动补位的 scratch 项目同样拥有 main 分支,因此提示符为 project/main。

场景四:最后项目是 scratch 时,补位项目命名为 scratch2

scratch/main> delete.project project
scratch/main> delete.project scratch
project/main> projects

会话继续:先删掉 project,剩余项目是 scratch,仍在 scratch/main;随后删除 scratch——它是最后一个项目且名字恰为 scratch。此时自动补位逻辑为了避免与“标准占位名”冲突,创建的项目被命名为 scratch2:

  1. project
  2. scratch2

即系统先补位创建了 project?并非如此——注意输出同时包含 project 与 scratch2:执行 delete.project project 后剩余 scratch;执行 delete.project scratch 后,由于它是最后一个项目,系统自动创建 scratch2 并保留原 scratch 已被删除的事实,最终列表为 project 与 scratch2。实际上这里的 project 正是第一次补位(场景三)时由系统创建的占位项目,再次被删除后又补位创建了 scratch2。

源码级实现:handleDeleteProject 的完整逻辑

delete.project 的处理器 handleDeleteProject :: ProjectName -> Cli () 位于 DeleteProject.hs,其执行流程分为三个关键阶段:

1. 校验目标项目是否存在

projectToDelete <-
  Cli.runTransactionWithRollback \rollback -> do
    Queries.loadProjectByName projectName & onNothingM do
      rollback (Output.LocalProjectDoesntExist projectName)

处理器在数据库事务中调用 Queries.loadProjectByName 按名加载目标项目;若项目不存在,则回滚事务并输出 LocalProjectDoesntExist 错误。该错误类型定义于 Output.hs,并已在 isFailure 判定中被标记为失败结果(见 Output.hs),意味着删除不存在的项目会得到明确的报错反馈。

2. 删除当前项目时先切换上下文

when (projectToDelete.projectId == currentProject.projectId) do
  nextLoc <- Cli.runTransaction $
    findAnyBranchInCodebaseNotInProject (projectToDelete.projectId)
      `whenNothingM` createDummyProjectExcept projectToDelete.name
  Cli.switchProject nextLoc

如果待删除项目正是当前项目,UCM 必须先把用户“挪走”,否则删除后当前上下文会指向不存在的项目。具体做法是:

  • findAnyBranchInCodebaseNotInProject:遍历 Queries.loadAllProjectBranchNamePairs 返回的所有项目-分支对,用 List.find 找到第一个 项目 ID 不等于待删除项目 ID 的分支;
  • 如果代码库中还存在其他项目分支,就切换到该分支;
  • 如果找不到(即这是最后一个项目),则调用 createDummyProjectExcept 补位创建占位项目,再切换过去。

3. 补位项目命名规则

createDummyProjectExcept 实现了文档中观察到的 scratch / scratch2 命名规律:

createDummyProjectExcept (UnsafeProjectName "scratch") = do
  (_, emptyCausalHashId) <- Codebase.emptyCausalHash
  Ops.insertProjectAndBranch (UnsafeProjectName "scratch2") defaultBranchName emptyCausalHashId
    <&> \(proj, branch) -> ProjectAndBranch proj.projectId branch.branchId
createDummyProjectExcept _ = do
  (_, emptyCausalHashId) <- Codebase.emptyCausalHash
  Ops.insertProjectAndBranch (UnsafeProjectName "scratch") defaultBranchName emptyCausalHashId
    <&> \(proj, branch) -> ProjectAndBranch proj.projectId branch.branchId
  • 若当前被删项目名恰为 scratch,补位项目命名为 scratch2;
  • 其余情况一律补位命名为 scratch。

补位项目通过 Ops.insertProjectAndBranch 以空因果哈希(Codebase.emptyCausalHash)创建,并挂载 defaultBranchName(即默认的 main 分支),因此新项目是一个包含空 main 分支的全新项目。这与转录中 project/main 的提示符表现完全吻合。

4. 执行删除

Cli.runTransaction do
  Queries.deleteProject (projectToDelete ^. #projectId)

最后在事务中按项目 ID 调用 Queries.deleteProject 完成物理删除。

与其他命令的协同

delete.project 并不是孤立命令,它与以下 UCM 项目生命周期命令配套使用:

  • project.create-empty:创建空项目,是本文转录会话中构造删除对象的准备命令;
  • projects:列出全部项目,别名 list.project、ls.project、project.list,用于验证删除结果(转录中每次删除后都通过它确认);
  • project.rename(rename.project)、switch 等命令共同构成项目管理的完整命令族。

值得一提的对比是 delete.branch(InputPatterns.hs,别名 branch.delete、rm.branch):它删除的是项目内的分支(形如 foo/bar),粒度比 delete.project 更细,二者共同覆盖了“项目—分支”两级结构的管理需求。

行为要点小结

综合转录文档与源码实现,delete.project 的关键行为可归纳如下:

  1. 语法:delete.project <项目名>,别名 project.delete 与 rm.project,参数恰好一个;
  2. 删除任意项目:既可以删除当前所在项目,也可以删除其他项目;
  3. 删除当前项目时自动切换:系统会先切换到代码库中任意其他项目的分支;若无其他项目则自动补位创建新项目;
  4. 补位命名:最后一个项目被删除时自动创建 scratch;若被删项目本身叫 scratch,则创建 scratch2;
  5. 不存在的项目报错:返回 LocalProjectDoesntExist 错误信息,事务回滚,不产生副作用;
  6. 数据库层面:删除由 Queries.deleteProject 按项目 ID 完成,所有相关项目数据在事务内一并清理。

这套“删除—切换—补位”的设计保证了 UCM 中始终存在至少一个可操作的项目上下文,避免了删除最后一个项目后提示符无处可去的状态。读者可在本地代码库中直接运行上述转录脚本(delete-project.md 本身即位于 idempotent 转录目录 中,属于幂等测试集的一部分,可在任意全新代码库中反复执行验证)。

登录后查看全文
unison