Unison 的 `delete.project` 命令:项目删除语义与实现原理完全指南
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 的关键行为可归纳如下:
- 语法:
delete.project <项目名>,别名project.delete与rm.project,参数恰好一个; - 删除任意项目:既可以删除当前所在项目,也可以删除其他项目;
- 删除当前项目时自动切换:系统会先切换到代码库中任意其他项目的分支;若无其他项目则自动补位创建新项目;
- 补位命名:最后一个项目被删除时自动创建
scratch;若被删项目本身叫scratch,则创建scratch2; - 不存在的项目报错:返回
LocalProjectDoesntExist错误信息,事务回滚,不产生副作用; - 数据库层面:删除由
Queries.deleteProject按项目 ID 完成,所有相关项目数据在事务内一并清理。
这套“删除—切换—补位”的设计保证了 UCM 中始终存在至少一个可操作的项目上下文,避免了删除最后一个项目后提示符无处可去的状态。读者可在本地代码库中直接运行上述转录脚本(delete-project.md 本身即位于 idempotent 转录目录 中,属于幂等测试集的一部分,可在任意全新代码库中反复执行验证)。