Newshot

Jujutsu 入门

Translation(model translation, not the source's own text)

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 配置。酷技巧尽在其中。

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by Lobsters
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗