SuperAPI AI 工具集

jujutsu

编程与开发

查看项目

更新于 10-18 09:26

技能介绍

Jujutsu(jj)是一个版本控制系统。该技能规定:当工作检出的根目录存在 .jj/ 时,所有版本控制操作都应通过 jj 执行,GitHub 相关操作使用 gh,不要运行 git;具体规则由 CLAUDE.md 给出,其中包括 .jj/ 缺失时的处理方式。位于裸仓库下、自身没有 .jj/ 的 .worktrees/ 目录不属于 jj 工作区。

仓库布局

  • 非裸克隆为 coloc 布局:.jj/ 与 .git/ 共享同一个 Git 对象库,jj 会把变更导出到 Git refs,Git 的 HEAD 保持分离状态。读写都应使用 jj 命令。
  • 裸仓库 <repo>.git/ 在根目录保存 jj 存储,默认工作区为空稀疏、不跟踪文件。实际工作在 .worktrees/ 下的 jj 工作区中进行,这些工作区没有自己的 .git。如果某个检查工具通过 git 枚举文件(如 git ls-files 或 treefmt 默认遍历器),在这里会检查不到任何文件并返回 0;应确认其输入数量,或改用文件系统遍历(treefmt --walk filesystem)。

授权与基本模型 每次 jj 写操作(commit、describe、split、squash、absorb、rebase、bookmark、fetch、push、创建工作区)都需要获得当前授权。jj 没有暂存区;仓库命令通常会把磁盘文件快照进工作副本修订 @,因此 jj status 会记录并报告编辑。在与其他会话共享的检出中,这种快照会把别人的编辑也吸收进 @;在 describe、squash 或 push @ 之前,要阅读 jj diff --git 并确认每个 hunk 都属于自己。给只读命令加 --ignore-working-copy 可以避免快照共享编辑,但视图可能过期。每个变更有一个稳定的变更 ID(字母 k-z)和一个每次改写都会变的提交 ID,改写前后应使用变更 ID 引用变更。

命令对照

  • git status 对应 jj status;git log --oneline --graph 对应 jj log;git diff / --cached 对应 jj diff --git(无暂存,单一 diff);git show <rev> 对应 jj show --git <rev>。
  • git add + commit 对应 jj commit -m(描述 @ 并开始新的空 @);git commit --amend -m 对应 jj describe -m;git commit --amend --no-edit 对应 jj squash。
  • 部分文件提交对应 jj split -m <msg> <paths>;fixup+autosquash 对应 jj absorb;创建分支对应 jj bookmark create <b> -r @;移动分支对应 jj bookmark set。
  • fetch 对应 jj git fetch --remote <r> --branch <b>(始终写明两者);push 对应 jj git push -b <b>;rebase 对应 jj rebase -b @ -o <onto>;cherry-pick 对应 jj duplicate;revert 对应 jj revert -r <rev> -o @;checkout -- 对应 jj restore <path>;blame 对应 jj file annotate;reflog 对应 jj op log。

非交互式使用 commit、describe、split 始终传入 -m,否则会打开编辑器。jj split 带路径时直接选择这些文件而不打开 diff 编辑器;不带路径会打开编辑器。不要运行不带路径的 jj split、jj diffedit、不带 --list 的 jj resolve,或任何 -i/--interactive 形式;防护钩子拦不住这些情况,等待输入的编辑器会挂起调用。输出命令加 --no-pager,需解析的 diff 加 --git(默认 diff 格式器为 difftastic)。脚本化读取用 jj log --no-graph -r <revset> -T '<template>' 获得稳定输出。

只读方式 jj log -T 'json(self) ++ "\n"' 每个提交输出一个 JSON 对象;路径参数是 fileset,可用 glob 限制 diff 范围;jj file show / jj file list 查看指定修订中的文件内容或列表而不改动磁盘;jj --at-op <op> log 查看某次操作后的仓库状态而不恢复。

精确改写历史 squash --from/--into 加路径只移动部分变更;absorb 把 @ 的每个 hunk 分发到最近修改这些行的可变祖先,分配有歧义的 hunk 会保留在原处,用 jj op show -p 复查去向;rebase 的 -r 移动单个提交并把子提交重新挂到其父提交,-s 连同后代移动,-b 移动整条分支;jj parallelize 把线性提交变为同级;多数改写支持 -r 作用于非 @ 提交;jj new --no-edit -A/-B 可在不移动 @ 的情况下插入空提交;jj restore --from/--into 加路径在修订间复制内容;jj simplify-parents 清理合并中的冗余父提交。

恢复与冲突 防护钩子阻止 jj undo 和 jj op restore,应通过阅读旧状态向前改写:jj evolog 列出变更的早期提交及补丁,jj interdiff 比较两个版本,jj restore --from 或 jj duplicate 恢复旧内容。rebase 或 squash 发生冲突时仍以 0 退出,冲突记录在提交中并由后代继承,所以退出状态不能证明改写成功;任何改写后及推送前运行 jj log --no-graph -r 'conflicts()',必须无输出。冲突在 @ 时直接编辑冲突标记;冲突在祖先时可用 jj resolve -r <rev> --tool :ours/:theirs 整文件解决,否则报告冲突变更 ID 并请用户处理或授权单独工作区。

revset 与操作日志 常用查询包括 trunk()..@(未推送栈)、conflicts()、divergent()、empty()、files("<path>")、description(substring:...)、heads(mutable())、diff_lines 等;用 exactly(<revset>, 1) 确保只匹配一个提交。使用 trunk() 前先确认其解析结果,避免 trunk()..@ 意外覆盖全部历史。并发会话改写同一变更会出现 divergent(),不要单方面放弃,报告两个提交 ID 让用户选择。jj op log / op show -p / op diff 可查看操作记录,恢复或回退操作被防护钩子阻止,需报出操作 ID 询问。

共享工作副本与推送 防护钩子阻止改写其他会话文件的命令(jj edit、next、prev、new 到其他修订、abandon、无路径 restore、undo、redo、op restore/revert),替代方案是用 jj new 开始工作、jj restore <path> 丢弃单个文件、jj revert 撤销修订。别名不被接受,须写完整内置子命令。工作区隔离用 jj workspace add(配合 mkdir -p 与 --sparse-patterns full,否则不检出文件);其他工作区改写本工作区 @ 所在提交时用 jj workspace update-stale。jj bisect run 由于会切换工作副本,需用户确认后在专用工作区运行。jj 不运行 Git 钩子,pre-commit 与 pre-push 检查都不会执行;推送前应做 --dry-run、确认无冲突、按配置规则对该范围做 gitleaks 扫描、用 jj log 确认作者身份,全部通过并获授权后以 ALLOW_DESTRUCTIVE_GIT=1 前缀执行 jj git push -b <bookmark>。书签不会自动跟随新提交,推送栈中每个提交需各自的书签;书签冲突用 jj bookmark set 选定目标;trunk 移动后用 jj rebase -s 'roots(trunk()..@)' -o 'trunk()' 重整整条栈并在推送前检查冲突。