Jujutsu 入门指南
本指南为熟悉 Git 的读者简要(算是吧)介绍 Jujutsu(jj)版本控制系统(VCS)。
为什么要试试 Jujutsu?
jj 提供的版本控制基础原语简单易学,却能优雅地组合成强大的工作流。自动 rebase 和原生 undo 等特性磨平了 Git 的锋利边角。最终,你会自然而然地发现一些新的强大工作流——这些工作流在大多数其他 VCS 工具中尝试起来会过于繁琐。
如果你在一个 Git 仓库中工作,今天就可以试用它。Jujutsu 和 Git 可以在同一个仓库中并排使用,因此你可以在自己的 git 仓库上试用 jj,而无需完全脱离 git。
就我个人而言,我认为 jj 大幅提升了我的效率,因为它让我可以把版本控制的簿记工作挡在工作记忆之外。自动 rebase 还让 stacked diff 工作流变得相当轻松,并减少了我工作记忆的反复折腾。它用起来也很有趣。
安装 jj
官方安装说明在这里,不过这里列出几种常见方法:
# macOS
brew install jj
# Arch Linux
pacman -S jujutsu
# NixOS (最好从 nixpkgs-unstable 安装)
nix-shell -p jujutsu
# 从源码安装
# (需要较新的 Rust,且 ~/.cargo/bin 在你的 PATH 中)
cargo install --locked --bin jj jj-cli
设置与配置
在已有的 git 仓库中,运行:
此后,jj 与 git 的仓库状态将自动同步。
要全局设置你的用户信息,运行如下命令:
jj config set --user user.name "Some One"
jj config set --user user.email "[email protected]"
你可以用编辑器编辑当前用户的 jj TOML 配置:
jj config edit --user
除了 --user 作用域,jj config 还有 --repo 和 --workspace 作用域。查看合并后的配置:
jj config list
提交与变更
commit,也叫 revision,本质上与 git commit 是同一回事。它表示仓库状态的一个快照,该快照派生自一个或多个父仓库快照。它通常被可视化为相对单个父 commit 的 diff,或者对于 merge commit 而言,是合并后相对多个父 commit 的 diff。
当使用 Git 仓库作为后端时,jj 的 commit ID 与 git 的 commit ID 相同:一个以十六进制字符串表示的哈希。在下面 jj log 的输出中,右侧的十六进制哈希 2bea5e3d 和 849165bc 就是 commit ID。
$ jj log
@ kpqxywon [email protected] 2026-11-15 12:17:12 849165bc
│ (empty) (no description set)
◆ royxmykx [email protected] 2026-11-15 12:10:46 main 2bea5e3d
│ Adjust config
~
左侧的 ID(royxmykx 和 kpqxywon)是 change ID,它们是逻辑变更在物理上随时间演变过程中的稳定标识符。我们将在下一节进一步讨论这些内容。
Commit ID 和 change ID 都可以用无歧义(唯一)的前缀来简写引用。jj 会贴心地高亮大多数 ID 的最短唯一前缀,方便你手动输入。例如,我们不必复制粘贴 kpqxywon,只需输入一个前缀,最短到唯一前缀 k 即可。
我们可以用 jj show 查看 commit 2bea5e3d,使用它的短前缀 2。
$ jj show 2
Commit ID: 2bea5e3d1992a60ba9ee52c6ce37c55adba9e8fb
Change ID: royxmykxtrkrqppotnrvutxlvrvqyxmy
Bookmarks: main main@git main@origin
Author : Ethan Lowman <[email protected]> (2026-11-15 12:10:46)
Committer: Ethan Lowman <[email protected]> (2026-11-15 12:10:46)
Adjust config
diff --git a/config.py b/config.py
index 7366a4e31d..174ffea06b 100644
--- a/config.py
+++ b/config.py
@@ -1,1 +1,1 @@
-DEFAULT_LIMIT = 10
+DEFAULT_LIMIT = 20
很多人会配置自定义的 diff 格式化工具,比如 Delta。如果你感兴趣,请参阅配置文档。
创建与演进变更
让我们再看一眼我们的 commit 图:
$ jj log
@ kpqxywon [email protected] 2026-11-15 12:17:12 849165bc
│ (empty) (no description set)
◆ royxmykx [email protected] 2026-11-15 12:10:46 main 2bea5e3d
│ Adjust config
~
在提交 849165bc 上,你会看到图节点上有一个符号 @。它代表我们工作副本的快照,也就是我们本地目录中实际检出的代码。我们可以通过多种方式检查这个特殊的提交指针:
jj show 显示提交详情和差异,此处差异为空。
$ jj show
Commit ID: 849165bca19639dbd6ccb53e8c1340e78c36d59a
Change ID: kpqxywonksrltlrkyqukqqsxpltznztk
Author : Ethan Lowman <[email protected]> (2026-11-15 12:17:12)
Committer: Ethan Lowman <[email protected]> (2026-11-15 12:17:12)
(no description set)
jj status 显示仓库状态及差异统计。
$ jj status
The working copy has no changes.
Working copy (@) : kpqxywon 849165bc (empty) (no description set)
Parent commit (@-): royxmykx 2bea5e3d main | Adjust config
jj diff 的用法与 git diff 类似。此处输出为空,因为当前工作副本相对于父提交没有变更。
这个输出没什么意思,因为 @ 没有任何变更。让我们做一个示例变更来观察会发生什么。如果我们编辑 main.py 并重新运行 jj show,就会看到:
$ jj show
Commit ID: 66b59f20c534705cfb753c722222290e9185b22c
Change ID: kpqxywonksrltlrkyqukqqsxpltznztk
Author : Ethan Lowman <[email protected]> (2026-11-15 12:26:43)
Committer: Ethan Lowman <[email protected]> (2026-11-15 12:26:43)
(no description set)
diff --git a/main.py b/main.py
new file mode 100644
index 0000000000..c74cd2e0e0
--- /dev/null
+++ b/main.py
@@ -0,0 +1,2 @@ def my_new_feature():
+def my_new_feature():
+ pass
$ jj log
@ kpqxywon [email protected] 2026-11-15 12:26:43 66b59f20
│ (no description set)
◆ royxmykx [email protected] 2026-11-15 12:10:46 main 2bea5e3d
│ Adjust config
~
你会注意到几处变化。工作副本已被自动提交,@ 不再标记为 (empty)。@ 的新提交 ID 是 66b59f20,因为我们添加了变更,但 66b59f20 的变更 ID 仍然是 kpqxywon。jj 没有像 git 那样的暂存区,因此我们不必手动添加文件。当我们在编辑文件后运行 jj 命令来检查或修改仓库状态时,jj 会自动将工作副本快照为对应逻辑变更的新物理提交。
让我们为这个变更添加描述(也称为提交信息)。我们可以运行 jj desc 打开编辑器,或者直接用 -m 提供描述。
$ jj desc -m "Implement the feature"
Working copy (@) now at: kpqxywon 6b89ffb2 Implement the feature
Parent commit (@-) : royxmykx 2bea5e3d main | Adjust config
再次注意,提交 ID 已经改变,因为哈希覆盖了提交信息,但变更 ID 保持不变。
现在,假设我们准备使用这个新功能,并且希望把这个变更整理到一个单独的提交中。我们可以用 jj new 创建一个新提交:
$ jj new
Working copy (@) now at: nlrtlrxv 6cca2add (empty) (no description set)
Parent commit (@-) : kpqxywon 6b89ffb2 Implement the feature
$ jj log
@ nlrtlrxv [email protected] 2026-11-15 12:35:49 6cca2add
│ (empty) (no description set)
○ kpqxywon [email protected] 2026-11-15 12:33:23 6b89ffb2
│ Implement the feature
◆ royxmykx [email protected] 2026-11-15 12:10:46 main 2bea5e3d
│ Adjust config
~
我们在 kpqxywon 之上创建了一个空变更 nlrtlrxv。jj status 反映出我们正在编辑这个新修订,它目前与其父提交没有差异。
$ jj status
The working copy has no changes.
Working copy (@) : nlrtlrxv 6cca2add (empty) (no description set)
Parent commit (@-): kpqxywon 6b89ffb2 Implement the feature
jj commit 是这一常见 jj desc 与 jj new 组合的简写。让我们再做一次变更来使用我们的新功能,并提交它。
Jujutsu 入门
$ jj commit -m "Use the feature"
Working copy (@) now at: qmkrwlvp 91067ad0 (empty) (no description set)
Parent commit (@-) : nlrtlrxv e1b06678 Use the feature
$ jj log
@ qmkrwlvp [email protected] 2026-11-15 12:41:30 91067ad0
│ (empty) (no description set)
○ nlrtlrxv [email protected] 2026-11-15 12:41:30 e1b06678
│ Use the feature
○ kpqxywon [email protected] 2026-11-15 12:33:23 6b89ffb2
│ Implement the feature
◆ royxmykx [email protected] 2026-11-15 12:10:46 main 2bea5e3d
│ Adjust config
~
要查看我们刚刚创建的提交(n),不能再使用裸的 jj show,它默认显示 @。我们必须传入想要查看的修订版本:
$ jj show n
Commit ID: e1b066782aa1a565c1e5d38ef27a308aa58e7e4c
Change ID: nlrtlrxvuuskxprvtuznquqzqzzwvnzk
Author : Ethan Lowman <[email protected]> (2026-11-15 12:41:30)
Committer: Ethan Lowman <[email protected]> (2026-11-15 12:41:30)
Use the feature
diff --git a/main.py b/main.py
index c74cd2e0e0..0714ec450b 100644
--- a/main.py
+++ b/main.py
@@ -1,2 +1,4 @@ def my_new_feature():
def my_new_feature():
pass
+
+do_something(my_new_feature())
我们可以通过描述空提交来在开始工作之前记录意图。让我们在 k 之上创建一个新提交,以提醒自己需要为这个功能编写文档。
$ jj new k -m "Document the feature"
Working copy (@) now at: qwyusntz 46a2ffda (empty) Document the feature
Parent commit (@-) : kpqxywon 6b89ffb2 Implement the feature
Added 0 files, modified 1 files, removed 0 files
单独使用 jj desc 也完全可以,而不必在 jj new 上使用 -m 标志。以下是当前的提交图:
$ jj log
@ qwyusntz [email protected] 2026-11-15 12:46:35 46a2ffda
│ (empty) Document the feature
│ ○ nlrtlrxv [email protected] 2026-11-15 12:41:30 e1b06678
├─┘ Use the feature
○ kpqxywon [email protected] 2026-11-15 12:33:23 6b89ffb2
│ Implement the feature
◆ royxmykx [email protected] 2026-11-15 12:10:46 main 2bea5e3d
│ Adjust config
~
注意,我们在没有创建命名分支的情况下创建了分叉的提交。这凸显了 jj 的无分支模型与 git 以分支为中心的工作流组织模型之间的一个重大差异。你不必在工作进行中的多个分支之间周旋,而是在一个提交图上工作。一旦准备好共享,你就从提交图向 Git forge 推送分支(稍后会详细介绍)。
Revsets
revset 是借自 Mercurial 的一个概念,它是一种从提交图中选择一组修订版本的表达式。大多数 jj 命令在其参数中接受 revset。当我们运行 jj new k 时,参数 k 实际上是一个简单的 revset,它解析为 ID 为 kpqxywon 的单个变更。jj log 命令有一个 -r <REVSET> 标志,我们可以用它来预览一个 revset。下面是一些示范性的例子。
@ 的父提交:
$ jj log -r @-
○ kpqxywon [email protected] 2026-11-15 12:33:23 6b89ffb2
│ Implement the feature
~
r 的孙提交:
$ jj log -r r++
@ qwyusntz [email protected] 2026-11-15 12:51:45 5b55579a
│ Document the feature
~
○ nlrtlrxv [email protected] 2026-11-15 12:41:30 e1b06678
│ Use the feature
~
r 与 @ 之间的提交(含两端):
$ jj log -r r::@
@ qwyusntz [email protected] 2026-11-15 12:51:45 5b55579a
│ Document the feature
○ kpqxywon [email protected] 2026-11-15 12:33:23 6b89ffb2
│ Implement the feature
◆ royxmykx [email protected] 2026-11-15 12:10:46 main 2bea5e3d
│ Adjust config
~
提交 k 及其所有后代:
$ jj log -r k::
@ qwyusntz [email protected] 2026-11-15 12:51:45 5b55579a
│ Document the feature
│ ○ nlrtlrxv [email protected] 2026-11-15 12:41:30 e1b06678
├─┘ Use the feature
○ kpqxywon [email protected] 2026-11-15 12:33:23 6b89ffb2
│ Implement the feature
~
由 [email protected] 创作且 ID 为 k 或 q 的提交:
$ jj log -r 'author("[email protected]") & (k | q)'
@ qwyusntz [email protected] 2026-11-15 12:51:45 5b55579a
│ Document the feature
○ kpqxywon [email protected] 2026-11-15 12:33:23 6b89ffb2
│ Implement the feature
~
详尽细节我将以官方文档为准。Revsets 语言规范大概是我查阅最多的 jj 文档页面,因此我建议略读一下,看看都能做些什么。
浏览提交图
假设在 qwyusntz 中记录功能的过程中,我们意识到在父变更 kpqxywon 的实现中犯了一个错误。我们无需手动提交或暂存更改就能切换任务。只需用 jj edit 将工作副本切换到 kpqxywon:
$ jj edit k
Working copy (@) now at: kpqxywon 6b89ffb2 Implement the feature
Parent commit (@-) : royxmykx 2bea5e3d main | Adjust config
Added 0 files, modified 0 files, removed 1 files
我们的工作副本再次显示 kpqxywon 中的更改。
$ jj show
Commit ID: 6b89ffb2a250f622a8638145d65fe8c9bb308dbf
Change ID: kpqxywonksrltlrkyqukqqsxpltznztk
Author : Ethan Lowman <[email protected]> (2026-11-15 12:26:43)
Committer: Ethan Lowman <[email protected]> (2026-11-15 12:33:23)
Implement the feature
diff --git a/main.py b/main.py
new file mode 100644
index 0000000000..c74cd2e0e0
--- /dev/null
+++ b/main.py
@@ -0,0 +1,2 @@ def my_new_feature():
+def my_new_feature():
+ pass
jj 并没有丢失工作副本之上的更改,包括我们对 q 的最新编辑:
$ jj log
○ qwyusntz [email protected] 2026-11-15 12:51:45 5b55579a
│ Document the feature
│ ○ nlrtlrxv [email protected] 2026-11-15 12:41:30 e1b06678
├─┘ Use the feature
@ kpqxywon [email protected] 2026-11-15 12:33:23 6b89ffb2
│ Implement the feature
◆ royxmykx [email protected] 2026-11-15 12:10:46 main 2bea5e3d
│ Adjust config
~
除了用 jj edit k 切换提交,我们也可以运行 jj edit @-。revset @- 在切换工作副本之前求值,因此这会移动到父提交。内置命令 jj next [--edit] 和 jj prev [--edit] 提供了另一种在提交栈中上下移动的方式。
自动变基
如果在工作副本中编辑文件,后代提交将在下次调用 jj 时自动变基。例如,如果我们在 main.py 中编辑 my_new_feature 的实现,然后运行 jj log,就会看到变更 k、n 和 q 都获得了新的提交 ID。jj 还会告诉我们它执行了变基。
$ jj log
Rebased 2 descendant commits onto updated working copy.
○ qwyusntz [email protected] 2026-11-15 13:03:41 7d293f19
│ Document the feature
│ ○ nlrtlrxv [email protected] 2026-11-15 13:03:41 41a43a84
├─┘ Use the feature
@ kpqxywon [email protected] 2026-11-15 13:03:41 d9f35831
│ Implement the feature
◆ royxmykx [email protected] 2026-11-15 12:10:46 main 2bea5e3d
│ Adjust config
~
处理冲突
如果自动变基恰好导致合并冲突,jj 不像 git rebase 那样要求我们立即修复。相反,jj 会记录该提交处于冲突状态,让你继续当前任务。随着堆叠提交变得越来越复杂,这对减少思维上下文切换有极大帮助。
$ jj log
Rebased 2 descendant commits onto updated working copy.
○ qwyusntz [email protected] 2026-11-15 13:05:35 b96f8df4
│ Document the feature
│ × nlrtlrxv [email protected] 2026-11-15 13:05:35 e562bff4 (conflict)
├─┘ Use the feature
@ kpqxywon [email protected] 2026-11-15 13:05:35 c501c0bd
│ Implement the feature
◆ royxmykx [email protected] 2026-11-15 12:10:46 main 2bea5e3d
│ Adjust config
~
要查看冲突,我们可以编辑这个有冲突的提交……
$ jj edit n
工作副本 (@) 现在位于:nlrtlrxv e562bff4 (冲突) Use the feature
父提交 (@-) :kpqxywon c501c0bd Implement the feature
新增 0 个文件,修改 1 个文件,删除 0 个文件
警告:以下路径存在未解决的冲突:
main.py 双边冲突
然后检查 main.py。
def my_new_feature():
print("Hello from the new feature!")
<<<<<<< conflict 1 of 1
%%%%%%% diff from: kpqxywon d9f35831 "Implement the feature" (parents of rebased revision)
\\\\\\\ to: kpqxywon c501c0bd "Implement the feature" (rebase destination)
- pass
+ return 42
+++++++ nlrtlrxv 41a43a84 "Use the feature" (rebased revision)
pass
do_something(my_new_feature())
>>>>>>> conflict 1 of 1 ends
在文本编辑器中,我们可以解决这些冲突,下次运行任何 jj 命令时,就会看到 jj 已将该提交标记为无冲突:
$ jj status
工作副本变更:
M main.py
工作副本 (@) :nlrtlrxv 34f2e2a1 Use the feature
父提交 (@-):kpqxywon c501c0bd Implement the feature
撤销与操作日志
假设我们在那次冲突解决中犯了错误,想要撤销它。在 git 中,撤销一个操作——如果可能的话——通常很复杂。在 jj 中,我们随时可以运行 jj undo:
$ jj undo
已撤销操作:35beb0741f17 (2026-11-15 13:08:39) snapshot working copy
已恢复到操作:f134ca987b59 (2026-11-15 13:07:18) edit commit e562bff4876f3ea76248c3f730e9e74d3e28e8a0
工作副本 (@) 现在位于:nlrtlrxv e562bff4 (冲突) Use the feature
父提交 (@-) :kpqxywon c501c0bd Implement the feature
新增 0 个文件,修改 1 个文件,删除 0 个文件
警告:以下路径存在未解决的冲突:
main.py 双边冲突
1 个提交中出现了新冲突:
nlrtlrxv e562bff4 (冲突) Use the feature
提示:要解决冲突,请先在冲突的提交之上创建一个提交:
jj new nlrtlrxv
然后使用 `jj resolve`,或直接编辑文件中的冲突标记。
冲突解决后,可以用 `jj diff` 检查结果。
然后运行 `jj squash` 将解决方案移入冲突的提交。
更一般地说,jj 在 jj op log 中维护所有操作的历史。我们可以查看此日志,并用 jj op restore 恢复到该历史中的某个点,或用 jj op revert 还原单个操作。如果 jj undo 本身是个错误,我们可以用 jj redo。
上面输出中的提示多少剧透了我们的下一个主题:squash 工作流。
Squash 工作流
编辑有后代提交的提交有时会让人感觉不踏实。如果你正在迭代一个已经超出工作记忆的大 diff,把新改动与现有 diff 分开会很有帮助。例如,我们可能想单独检查解决 rebase 冲突的那个 diff。
让我们按照上面输出中的说明操作。首先在冲突的提交之上创建一个新提交:
$ jj new n
工作副本 (@) 现在位于:wqxolloz b878878a (冲突) (空) (无描述)
父提交 (@-) :nlrtlrxv e562bff4 (冲突) Use the feature
警告:以下路径存在未解决的冲突:
main.py 双边冲突
$ jj log -r n::
@ wqxolloz [email protected] 2026-11-15 13:11:44 b878878a (冲突)
│ (空) (无描述)
× nlrtlrxv [email protected] 2026-11-15 13:05:35 e562bff4 (冲突)
│ Use the feature
~
现在我们可以在编辑器中解决 main.py 里的冲突,然后重新运行 jj log:
$ jj log -r n::
@ wqxolloz [email protected] 2026-11-15 13:14:12 91181aec
│ (无描述)
× nlrtlrxv [email protected] 2026-11-15 13:05:35 e562bff4 (冲突)
│ Use the feature
~
如果愿意,我们可以检查 @ 中的 diff;当我们对冲突解决方案满意时,可以将其 squash 到父提交中:
$ jj squash
Working copy (@) now at: vkywoywq f6b548b3 (empty) (no description set)
Parent commit (@-) : nlrtlrxv 7208deb7 Use the feature
Existing conflicts were resolved or abandoned from 1 commits.
$ jj log -r n::
@ vkywoywq [email protected] 2026-11-15 13:15:39 f6b548b3
│ (empty) (no description set)
○ nlrtlrxv [email protected] 2026-11-15 13:15:39 7208deb7
│ Use the feature
~
冲突现已解决,我们可以继续工作了。
更多提交图操作
jj 的强大特性之一,是它让 diff 像黏土一样可塑。借助自动 rebase 以及 jj undo 带来的信心,我们可以轻松地移动、合并、丢弃和拆分 diff。
让我们在当前提交图上尝试几个操作。以下是起点。
$ jj log
@ vkywoywq [email protected] 2026-11-15 13:15:39 f6b548b3
│ (empty) (no description set)
○ nlrtlrxv [email protected] 2026-11-15 13:15:39 7208deb7
│ Use the feature
│ ○ qwyusntz [email protected] 2026-11-15 13:05:35 b96f8df4
├─┘ Document the feature
○ kpqxywon [email protected] 2026-11-15 13:05:35 c501c0bd
│ Implement the feature
◆ royxmykx [email protected] 2026-11-15 12:10:46 main 2bea5e3d
│ Adjust config
~
Rebase
让我们用 jj rebase 将分叉的提交图强制变为线性历史。假设文档提交(q)应该位于实现(k)和使用(n)之间。我们可以通过将 nlrtlrxv(及其空的子提交)移到 qwyusntz 之上来实现:
$ jj rebase -s n -o q
Rebased 2 commits to destination.
Working copy (@) now at: vkywoywq 0405560c (empty) (no description set)
Parent commit (@-) : nlrtlrxv 9920235b Use the feature
Added 1 files, modified 0 files, removed 0 files
$ jj log
@ vkywoywq [email protected] 2026-11-15 13:20:18 0405560c
│ (empty) (no description set)
○ nlrtlrxv [email protected] 2026-11-15 13:20:18 9920235b
│ Use the feature
○ qwyusntz [email protected] 2026-11-15 13:05:35 b96f8df4
│ Document the feature
○ kpqxywon [email protected] 2026-11-15 13:05:35 c501c0bd
│ Implement the feature
◆ royxmykx [email protected] 2026-11-15 12:10:46 main 2bea5e3d
│ Adjust config
~
实现同样效果的另一种方式是使用 jj rebase -r q --before n。许多 jj 命令都有多种指定 revsets 的方式。jj rebase --help 对此有很好的说明。
由于 jj rebase 标志的参数都是 revsets,我们可以编写一个 revset 来选择一串提交或提交子图,并将其移动到图中的其他位置。
如果我们想在 k 之下插入一个提交,最直接的方式是 jj new --before k,但为了演示,我们也可以选择在 r 之上创建一个新提交,然后将 k:: rebase 到其上:
$ jj new r -m "Prepare for the feature"
Working copy (@) now at: wxzmtyol be5ca29b (empty) Prepare for the feature
Parent commit (@-) : royxmykx 2bea5e3d main | Adjust config
Added 0 files, modified 0 files, removed 2 files
$ jj log
@ wxzmtyol [email protected] 2026-11-15 13:23:29 be5ca29b
│ (empty) Prepare for the feature
│ ○ nlrtlrxv [email protected] 2026-11-15 13:20:18 9920235b
│ │ Use the feature
│ ○ qwyusntz [email protected] 2026-11-15 13:05:35 b96f8df4
│ │ Document the feature
│ ○ kpqxywon [email protected] 2026-11-15 13:05:35 c501c0bd
├─┘ Implement the feature
◆ royxmykx [email protected] 2026-11-15 12:10:46 main 2bea5e3d
│ Adjust config
~
$ jj rebase -s k -o w
Rebased 3 commits to destination.
$ jj log
○ nlrtlrxv [email protected] 2026-11-15 13:28:02 cda0de88
│ Use the feature
○ qwyusntz [email protected] 2026-11-15 13:28:02 ec9de16f
│ Document the feature
○ kpqxywon [email protected] 2026-11-15 13:28:02 722e7268
│ Implement the feature
@ wxzmtyol [email protected] 2026-11-15 13:23:29 be5ca29b
│ (empty) Prepare for the feature
◆ royxmykx [email protected] 2026-11-15 12:10:46 main 2bea5e3d
│ Adjust config
~
如果你喜欢使用 TUI,jj arrange 提供了一个类似 git rebase -i 的提交图编辑器,用于重新排列提交。
Squash
如果我们决定文档应该与实现放在同一个提交中,我们可以进行 squash:
$ jj squash --from q --into k
Rebased 1 descendant commits.
jj 会打开一个编辑器,让我们有机会编写合并后的提交信息。
$ jj log
○ nlrtlrxv [email protected] 2026-11-15 13:31:30 cb468825
│ Use the feature
○ kpqxywon [email protected] 2026-11-15 13:31:30 b93e4ef7
│ Implement and document the feature
@ wxzmtyol [email protected] 2026-11-15 13:23:29 be5ca29b
│ (empty) Prepare for the feature
◆ royxmykx [email protected] 2026-11-15 12:10:46 main 2bea5e3d
│ Adjust config
~
Abandon
要从图中删除一个提交,我们可以使用 jj abandon。让我们删除那个准备提交:
$ jj abandon w
Abandoned 1 commits:
wxzmtyol be5ca29b (empty) Prepare for the feature
Rebased 2 descendant commits onto parents of abandoned commits.
Working copy (@) now at: xzwrrwyv d460fbd4 (empty) (no description set)
Parent commit (@-) : royxmykx 2bea5e3d main | Adjust config
$ jj log
@ xzwrrwyv [email protected] 2026-11-15 13:33:49 d460fbd4
│ (empty) (no description set)
│ ○ nlrtlrxv [email protected] 2026-11-15 13:33:49 b1284f61
│ │ Use the feature
│ ○ kpqxywon [email protected] 2026-11-15 13:33:49 df93f0a6
├─┘ Implement and document the feature
◆ royxmykx [email protected] 2026-11-15 12:10:46 main 2bea5e3d
│ Adjust config
~
要放弃提交中的部分内容(hunk 或对整个文件的更改),我们可以使用 jj diffedit TUI(见文档)。
Split
jj split TUI 允许我们取一个提交,通过选择哪些文件或 hunk 应该进入第一个提交,将其拆分为两个连续的提交。让我们再次使用它来拆分实现和文档,命令为 jj split -r k:
jj-hunk 项目提供了一种自动化提交拆分的方式。如果你有兴趣,agent 非常擅长使用这个工具将提交拆分成一系列更小的更改,以便更容易审查。
Bookmarks 和 Git 分支
jj 没有原生的分支概念,但它有一个称为 bookmark 的原语,可以映射到 Git 分支。当我们需要操作 Git 分支时,我们通过 bookmark 来完成。
你可以在使用 Git 时走得很远而不会意识到这一点,但 Git 分支只是一个指向提交的指针。jj 明确地以这种方式对 bookmark 建模。jj bookmark 本质上是一个附加到提交上的命名标签,我们可以在修改提交图时移动它,并与远程仓库进行 push/pull。
我们将在下面讨论一些围绕 Git 分支的基本工作流,但你可以在 jj 文档的 Working with GitHub 中找到更完整的指南。
推送一个新分支
假设我们在一个有远程仓库的 git 仓库中初始化了 jj,我们应该会看到 jj git remote list 的一些输出。
$ jj git remote list
origin [email protected]:ethanal/example.git
由于 jj 是无分支的,我们在本地创建的提交没有分支名。幸运的是,jj 不要求我们选择一个,而是为我们生成一个。生成的分支名让你不必再费心去想一个唯一的分支名,从而可以专注于编写好的提交信息(这通常是更改更持久的描述符)。
要为变更 ID nlrtlrxv 创建一个生成的 bookmark,并推送对应的 Git 分支,我们可以运行类似下面的命令:
$ jj git push -c n
Creating bookmark push-nlrtlrxvuusk for revision nlrtlrxv
Changes to push to origin:
bookmark: push-nlrtlrxvuusk [add to b1284f61]
git: Enumerating objects: 17, done.
git: Counting objects: 100% (17/17), done.
git: Delta compression using up to 32 threads
git: Compressing objects: 100% (14/14), done.
git: Writing objects: 100% (16/16), 25.21 KiB | 6.30 MiB/s, done.
git: Total 16 (delta 1), reused 5 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
remote:
remote: Create a pull request for 'push-nlrtlrxvuusk' on GitHub by visiting:
remote: https://github.com/ethanal/example/pull/new/push-nlrtlrxvuusk
remote:
现在 jj log 会显示我们的变更,并关联一个名称对应的书签 push-nlrtlrxvuusk:
$ jj log -r n
○ nlrtlrxv [email protected] 2026-11-15 13:33:49 push-nlrtlrxvuusk b1284f61
│ Use the feature
~
现在我们可以自由地在 GitHub 上从这个分支创建 PR 了。你可以通过这里记录的 git_push_bookmark 模板配置来自定义书签命名方案。一种常见的做法是将分支名称格式化为 <author name>/<change ID>。
由于 jj git push -c 会创建一个与变更 ID 对应的分支名,它似乎鼓励每个 PR 对应一个持续演进的变更。我认为通常最好顺应这些人体工学设计,让每个 PR 对应一个变更。
更新分支
要更新分支,一般流程是将提交 squash 到已经带有书签的变更中,或者创建新提交并将书签向前移动。
书签 squash 流程
如果你选择将提交 squash 到现有书签中(推荐,以保持每个 PR 对应一个变更),流程如下。
首先,在我们的分支之上创建一个新提交。
$ jj new push-nlrtlrxvuusk
Working copy (@) now at: stzvpxow f14a0cf7 (empty) (no description set)
Parent commit (@-) : nlrtlrxv b1284f61 push-nlrtlrxvuusk | Use the feature
Added 2 files, modified 0 files, removed 0 files
然后进行我们的修改。
$ jj status
Working copy changes:
M README.md
Working copy (@) : stzvpxow 6bdd43dc (no description set)
Parent commit (@-): nlrtlrxv b1284f61 push-nlrtlrxvuusk | Use the feature
将它们 squash 到书签分支中。
$ jj squash --from @ --into push-nlrtlrxvuusk
Working copy (@) now at: xryuuprx 04d65a03 (empty) (no description set)
Parent commit (@-) : nlrtlrxv aeb869ae push-nlrtlrxvuusk* | Use the feature
我们现在看到 push-nlrtlrxvuusk 旁边有一个星号,表示它有尚未推送到远端的变更。那么让我们推送它们。
$ jj git push -b push-nlrtlrxvuusk
Changes to push to origin:
bookmark: push-nlrtlrxvuusk [move sideways from b1284f61c417 to aeb869aef99b]
远端分支现在反映了新的变更。上面的输出说我们将分支从一个提交横向移动到另一个提交,这反映我们执行了强制推送。jj git push 运行的是等价于 git push --force-with-lease 的操作,所以如果你不确定某个推送操作会做什么,可以使用 jj git push --dry-run 标志。jj 会保护你免受大多数危险的强制推送,拒绝重写可配置的不可变提交 revset。默认的不可变 revset 是合理的,但你可以通过配置自己的 immutable heads 来让它更保守或更宽松。
书签前进流程
在这个流程中,我们在书签之上添加新提交,然后将书签移动指向我们的新提交。
首先准备新提交。
$ jj new push-nlrtlrxvuusk
Working copy (@) now at: pptrztmx 6e49ff1f (empty) (no description set)
Parent commit (@-) : nlrtlrxv aeb869ae push-nlrtlrxvuusk | Use the feature
然后进行我们的修改。
$ jj status
Working copy changes:
M README.md
Working copy (@) : pptrztmx 89027165 (no description set)
Parent commit (@-): nlrtlrxv aeb869ae push-nlrtlrxvuusk | Use the feature
$ jj commit -m "Add a usage example"
Working copy (@) now at: wunttkrp 044f2d98 (empty) (no description set)
Parent commit (@-) : pptrztmx 2341ee4a Add a usage example
bookmark 不会自动移动到我们的新 commit 上。这是 bookmark 与 Git branch 之间最大的区别。目前 push-nlrtlrxvuusk 仍然指向下面的 commit:
$ jj log -r n::
@ wunttkrp [email protected] 2026-11-15 13:51:57 044f2d98
│ (empty) (no description set)
○ pptrztmx [email protected] 2026-11-15 13:51:57 2341ee4a
│ Add a usage example
○ nlrtlrxv [email protected] 2026-11-15 13:43:16 push-nlrtlrxvuusk aeb869ae
│ Use the feature
~
有几种方法可以把 bookmark 移动到新 commit 上。最简单的大概是 jj bookmark advance,它会把最接近的 bookmark 移动到指定的 commit:
$ jj bookmark advance --to @-
Advanced 1 bookmarks to pptrztmx 2341ee4a push-nlrtlrxvuusk* | Add a usage example
现在可以推送移动后的 bookmark 了。
$ jj git push -b push-nlrtlrxvuusk
Changes to push to origin:
bookmark: push-nlrtlrxvuusk [move forward from aeb869aef99b to 2341ee4aa554]
检出一个远程分支
严格来说,由于 jj 是无分支的,我们并不会“检出”一个分支,但我们可以在远程分支之上创建一个 commit。首先做相当于 git fetch 的操作,导入远程 bookmark:
$ jj git fetch
然后在远程分支之上创建一个新的空 commit:
$ jj new some-cool-feature@origin
现在我们的工作副本包含了远程分支上的所有 commit。不过,如果我们切回 git,会发现从 git 的角度看,我们处于 detached head 状态,不在任何分支上。
$ git status
Not currently on any branch.
nothing to commit, working tree clean
这是因为 jj 正在编辑 bookmark 之上的一个 commit,它没有与 git 的“当前分支”状态等价的概念。
从 trunk 拉取变更
与 trunk(例如 main)同步只是这一流程的一个具体例子。我们会用 jj git fetch 把 main 更新到上游的 main,然后把我们的 commit rebase 到上面。例如,下面这条命令会把 my-branch rebase 到新的 main 之上:
jj rebase -b my-branch -o main
在图中保持方向感
当屏幕上有一个实时更新的 commit 图时,jj 的 commit 图操作最为容易。有几种方法可以做到这一点。
jjui 是一个 jj 的 TUI,允许你直接编辑可视化图形。我个人没用过,但我认识喜欢它的人。
我更喜欢借助 viddy(一个更好用的 watch,支持颜色)让一个始终实时更新的 jj log 显示在屏幕角落:
viddy -t -n1 jj log --ignore-working-copy --color=always
我建议把这个 log 过滤到一个代表你当前工作的 revset。下面是一个起点:
visible() & (trunk() | (tracked_remote_bookmarks() & ~::trunk()) | (mutable() & mine())::)
你也可以考虑试试我的实验性项目 jj-stamp,它是一个面向 squash 工作流的本地代码审查 GUI。即使你不使用 squash 审查工作流,它也是一个相当不错的 diff 查看器,旁边有一个实时更新的 jj log,还有一个用于运行 jj 操作的终端。
简谈堆叠 PR
jj 带来的最大生产力提升之一,是它支持堆叠 PR 工作流的能力。这值得单独写一篇文章,所以我在这里简要说明。
大型变更如果被拆分成一系列合乎逻辑的步骤,会更容易理解。把一个大变更拆分成更小的、按顺序排列的审查原子单元,能让整个变更更容易理解。堆叠 PR 试图利用这一点来优化合并吞吐量,同时消除审查流程中的流水线停滞。
假设我们正在构建一个新功能。我们可以决定把实现拆分成三个阶段:
- 重构,使该功能更容易实现
- 实现该功能
- 在另一个系统中使用该功能
jj 能够以自动变基的方式处理堆叠变更,这使其天然适合实现这三个阶段。三个阶段各自对应一个提交,每个提交都关联一个 bookmark/分支/PR:
$ jj log -r oomyzqmz::sxummoow
○ sxummoow [email protected] 2026-11-15 14:10:48 ethan/sxummoow b5f0af21
│ Use the feature
○ vqpzktsp [email protected] 2026-11-15 14:06:27 ethan/vqpzktsp fe52c25f
│ Implement the feature
○ oomyzqmz [email protected] 2026-11-15 14:01:19 ethan/oomyzqmz 07f69717
│ Refactor for the feature
~
实现第一个变更后,你就可以提交 PR 送审,并立即开始处理下一个变更。你的工作流变成一条长队列:PR 可以合并时从底部弹出,新工作从顶部压入,流水线不会停滞。
用 jj 和 GitHub 手动搭建小型 PR 堆栈相当容易,但一旦你迷上这种技巧(把堆栈做到 5–10 个 PR 深),你就会想要一个工具。jj-pancake 是我进入堆叠 PR 工具擂台的作品。稍后详述。
资源
- Jujutsu 官方文档。我最常查阅的是 revset spec。
- Steve Klabnik 的 jj 教程是我初次接触 jj 的入口。我不认为它被作为长期资源维护(我也不保证我的教程会!),但它仍然值得一读。
- 我订阅了 jj 的发布 RSS 源。最近几次发布都塞满了新功能。总体而言 jj 相当稳定,偶发的 bug 也会被迅速修复。
- Jujutsu 的 discord 很活跃,也很友好!
- East River Source Control 的博客,这家公司正在构建一个新的 forge 和代码审查平台,旨在良好支持 Jujutsu。Jujutsu 的创造者 Martin von Zweigbergk 已加入担任 CTO,他们还有许多其他聪明人。也许有朝一日会成为 GitHub 的继任者?我为他们加油。
- 我个人的 jj 配置。你可能会在这里找到一些有用的 alias 或技巧,但我没有试图让它可读。
- jj 维护者 Austin Seipp 的 jj 配置。酷技巧尽在其中。