jj

Jujutsu (jj) 版本控制

Jujutsu 是一款兼容 Git 的 VCS，支持可变提交、自动跟踪更改，并提供操作日志，让每项操作都可以撤销。

目标版本：jj 0.36+

主题

我需要……	深入了解
了解 jj 与 Git 的关系，或在 jj 仓库中使用原始 git	git-compatibility.md
编写 revset、fileset 或模板表达式	revsets.md
推送、拉取、管理书签，或使用 GitHub	bookmarks.md
拆分、变基、压缩提交，或解决冲突	conflicts.md
使用隔离的工作副本运行并行 Agent	parallel-agents.md
配置 jj、设置别名或自定义差异	config-reference.md

心智模型

工作副本就是一个提交。 没有暂存区。运行任何 jj 命令时，每项文件更改都会自动快照到 @ 中。不必“暂存 → 提交”，只需编写代码并描述更改。

更改 ID 稳定，提交 ID 不稳定。 每个提交都有两个标识符：

• 更改 ID — 重写后保持不变。由字母 k–z 组成（例如，tqpwlqmp）。优先使用此 ID。
• 提交 ID — 内容哈希，任何重写都会使其改变。由十六进制数字组成。在共置仓库中，它就是 Git 提交 ID。

历史记录可变。 提交可以自由重写。后代提交会自动变基。旧版本会保留在操作日志中。

书签不是分支。 创建新提交时，书签不会自动前移。重写时它们会跟随更新，但推送前必须显式设置。 → 深入了解：bookmarks.md

冲突不会阻止操作。 jj 允许提交含有冲突的文件。可以在方便时直接编辑冲突标记来解决冲突，然后用 jj st 验证。 → 深入了解：conflicts.md

Agent 规则

作为自动化 Agent 操作时，以下规则不可妥协：

1. 消息始终使用 -m。 绝不要调用会打开编辑器的命令。需要使用 -m 的命令：jj new、jj describe、jj commit、jj squash。
2. 绝不使用交互式命令。 jj split（不带文件路径）、jj squash -i、jj resolve 都会卡住。请使用带文件路径的参数或 jj restore 工作流。
3. 修改后进行验证。 执行 squash、abandon、rebase、restore 或任何破坏性操作后，运行 jj st。
4. 使用更改 ID，而不是提交 ID。 更改 ID 在重写后仍然有效。
5. 为 revset 加引号。 始终使用单引号：jj log -r 'mine() & ::@'。

Agent 专用配置

# agent-jj-config.toml
[user]
name = "Agent"
email = "[email protected]"

[ui]
editor = "TRIED_TO_RUN_AN_INTERACTIVE_EDITOR"
diff-formatter = ":git"
paginate = "never"

启动命令：JJ_CONFIG=/path/to/agent-jj-config.toml <agent-harness> → 深入了解：config-reference.md

核心工作流

日常循环：描述 → 编写代码 → new → 重复。

jj describe -m "feat: add user validation"
# make changes — auto-tracked, no `add` needed
jj st && jj diff
jj new -m "feat: add error handling"

整理历史记录

jj squash -m "feat: final clean message"   # fold working copy into parent
jj absorb                                   # auto-distribute hunks to right ancestor
jj abandon @                               # drop a failed experiment

→ 深入了解：command-gotchas.md

非线性工作

当新工作不依赖当前提交链时，从主干分支创建分支：

# Create sibling from trunk (doesn't move @)
jj new trunk() --no-edit -m "fix: correct timezone handling"
jj edit <bugfix-change-id>
# ... fix the bug ...

# Return to original work
jj log -r 'heads(trunk()..)'
jj edit <feature-change-id>

Agent 规则： 创建新提交之前，先判断它是否依赖当前提交链。如果不依赖，则从主干分支创建分支，并向用户说明这一分歧。

推送更改

jj bookmark set feat -r @
jj git push -b feat

推送前必须设置书签——书签不会自动前移。 → 深入了解：bookmarks.md

核心命令

任务	命令
检查状态	jj st
查看差异 / 日志	jj diff / jj log
描述当前提交	jj describe -m "message"
开始新工作	jj new -m "task description"
编辑较早的提交	jj edit <change-id>
合并到父提交	jj squash
自动分配更改	jj absorb
放弃提交	jj abandon <change-id>
撤销上次操作	jj undo
查看操作历史	jj op log
恢复到较早的状态	jj op restore <op-id>
创建 / 移动书签	jj bookmark create <n> -r @ / jj bookmark set <n> -r @
推送 / 获取	jj git push -b <bookmark> / jj git fetch

Git 命令转换：references/git-to-jj.md

恢复

jj undo                      # undo last op; repeatable
jj op log                    # full operation history
jj op restore <op-id>        # jump to any past state
jj evolog -r <change-id>     # see how a change evolved

检测 jj 仓库

.jj/ 目录 = jj 仓库。.jj/ 和 .git/ 同时存在 = 共置仓库。始终使用 jj 命令。在共置仓库中，Git 的“分离 HEAD”是正常现象——使用 jj log 查看实际状态。

常见错误

错误	修正方法
命令中省略 -m	始终传入 -m——编辑器会导致 Agent 卡住
不带文件路径使用 jj split	提供路径，或使用 jj restore 工作流
推送前忘记设置书签	先运行 jj bookmark set <name> -r @
使用提交 ID 而不是更改 ID	更改 ID（字母 k–z）在改写后仍然有效
revset 表达式未加引号	始终使用单引号：'mine() & ::@'
混淆 :: 与 .. 运算符	:: = 祖先路径，.. = 范围（参见 revsets.md）
将工作区创建为子目录	必须是同级目录，而不是子目录

参考索引

Git 互操作：

• references/git-to-jj.md — Git 到 jj 的命令映射
• references/git-experts.md — jj 相比 Git 的改进之处
• references/git-compatibility.md — Git 互操作与共置仓库

命令：

• references/command-gotchas.md — 标志语义、引号和已弃用的标志

Revset 与模板：

• references/revsets.md — 完整的 revset 语言规范
• references/filesets.md — 完整的 fileset 语言规范
• references/templates.md — 完整的模板语言规范

共享：

• references/bookmarks.md — 完整的书签参考
• references/github.md — GitHub/GitLab 工作流详情

历史记录：

• references/conflicts.md — 冲突处理和标记格式
• references/divergence.md — 分歧更改指南

配置：

• references/config-reference.md — 完整的配置参考

工作区：

• references/parallel-agents.md — 并行 Agent 设置指南