onevcat-jj

jj (Jujutsu) — 面向 Agent 工作流的版本控制

jj 是一款与 Git 共存的版本控制工具。你在本地使用 jj；远端仍然是标准 Git。GitHub 和协作者看到的仍是普通的 git 提交和分支。

本技能将教你如何正确且地道地使用 jj，尤其是在 Agent 辅助的开发工作流中。

核心心智模型

jj 围绕**变更（change）**而非分支运转。与 Git 的关键区别：

• 没有暂存区。 文件修改会自动成为当前变更的一部分。没有 git add。
• 没有 stash。 只需 jj new 即可开始新的工作；之前的变更留在原处。
• 没有 detached HEAD。 jj edit 让你跳转到任意变更并继续工作；后代变更会自动 rebase。
• 分支被称为 bookmark，且仅在推送到远程时才需要。

工作副本本身就是一个变更。每一次文件修改都会立即被记录到当前变更中。

检测 jj 仓库

在执行版本控制操作之前，检查该仓库是否使用 jj：

# If .jj/ exists, use jj commands — not git commands
test -d .jj && echo "jj repo"

当一个仓库同时拥有 .jj/ 和 .git/（共置模式）时，本地操作请始终优先使用 jj 命令。

设置

在现有 Git 仓库中初始化 jj（共置模式 — 让 .git/ 与 .jj/ 并存）：

jj git init --colocate

初始化后，你可能需要跟踪远程 bookmark，以便 jj 了解远程分支：

jj bookmark track master@origin        # Track a specific remote branch

如果需要，jj 通常会给出相关提示。

常用命令

查看状态

jj log                    # Show change graph + status (replaces git log + git status)
jj diff                   # Show diff of current change vs parent
jj diff -r <change>       # Show diff of a specific change

jj log 的输出会以 @ 标记当前变更，并显示简短的 Change ID（例如 kxryzmsp）。Change ID 在 rebase 后保持稳定 — 可以放心用作引用。只要不产生歧义，你可以使用唯一前缀（例如用 kx 代替 kxryzmsp）。

处理变更

jj describe -m "feat: add auth module"   # Set/update description of current change
jj describe -r <change> -m "new msg"     # Update description of any change
jj new                                    # Finish current change, start a new empty one
jj new <change>                           # Start new work branching from a specific change
jj commit -m "feat: ..."                  # Shorthand: describe current + start new (equivalent to describe + new)
jj edit <change>                          # Jump to an existing change and continue editing it
jj abandon                                # Discard the current change entirely
jj abandon <change>                       # Discard a specific change

jj new 是你主要的“下一项任务”命令。 它会封存当前变更，并为你提供全新的工作区。无需 add，也无需提交仪式。

jj abandon 会彻底丢弃一个变更。该变更的修改会被吸收到其父变更中。用它来清理空变更、丢弃不想要的工作，或从变更链中移除某个变更。

jj edit 是安全的： 如果目标变更是不可变的（已推送到远程），jj 会报错拒绝。你无需自行检查这一点。

执行 jj edit 后，修改文件会就地修改该变更。所有后代变更都会自动 rebase — 编辑祖先变更后，你永远不需要手动 rebase。

重组历史

jj split                                 # Interactively split current change into two (or more)
jj split -r <change>                     # Split a specific change
jj rebase -s <source> -d <destination>   # Move a change (and its descendants) to a new parent
jj rebase -d <destination>               # Rebase current branch onto destination
jj undo                                  # Undo the last jj operation (any operation)
jj op log                                # View operation-level history
jj op restore <operation-id>             # Restore repo to any previous operation state

jj split 默认会打开交互式编辑器（未给定 fileset 时）。选择哪些文件/hunk 属于第一个变更；其余部分自动成为第二个变更。重复操作可继续拆分。

jj undo 会撤销上一次操作，无论它是什么 — rebase、split、describe，任何操作皆可。它始终是安全的。在 jj 中，没有任何东西会真正丢失。

远程交互（Git 桥接）

jj git fetch                             # Fetch from remote (like git fetch)
jj rebase -d master                      # Rebase current work onto latest master
jj bookmark track master@origin          # Track a remote branch (needed after init or for new remotes)
jj bookmark create my-feature -r @       # Create a bookmark (= git branch) pointing at current change
jj bookmark create my-feature -r <chg>   # Create a bookmark pointing at a specific change
jj bookmark set my-feature -r <change>   # Move an existing bookmark to a different change
jj git push                              # Push all changed bookmarks to remote
jj git push --bookmark my-feature        # Push only a specific bookmark
jj git push --deleted                    # Push bookmark deletions to remote (after jj abandon)

获取（fetch）时，远程 Git 分支会自动映射为 jj 的 bookmark。你在 jj log 中看到的 master（或 main）就是远程分支，通过 bookmark 访问。

在执行 jj git init --colocate 后，或当出现新的远程分支时，你可能需要 jj bookmark track <name>@<remote> 来告诉 jj 跟踪它。需要时 jj 会给出提示。

推送工作流：

1. 完成你的工作（describe 该变更）
2. jj bookmark create <name> -r <change> — 为其指定一个 Git 分支名
3. jj git push — 推送到远程（或使用 --bookmark <name> 只推送一个）

放弃已推送变更后的清理： 当你 jj abandon 一个其 bookmark 已推送到远程的变更时，该 bookmark 会在本地被删除。使用 jj git push --deleted 将该删除同步到远程。

并行工作区

jj workspace add ../workspace-name       # Create a parallel workspace (like git worktree)

每个工作区都有自己的目录，但共享底层的仓库存储。多个 Agent 可以从同一个基点在不同的工作区中同时工作，然后用 jj new <change1> <change2> ... 合并结果。

Agent 工作流模式

这些模式利用 jj 的优势来支持 Agent 辅助开发。

模式 1：开始下一项任务

只需 jj new 并开始。无需先 add、commit、push 或创建分支。之前的变更会自动保留。

jj new
jj describe -m "feat: implement avatar upload"
# start working...

模式 2：中断并恢复

要在工作过程中处理紧急任务：

jj new master            # Branch off master for the urgent fix
# ... do the fix ...
jj describe -m "fix: critical auth bug"
jj edit <previous-change> # Jump back to where you were
# ... resume previous work ...

无需 stash，无需切换分支，无需恢复状态。

模式 3：事后拆分

在产生一个大型变更后，将其拆分为逻辑片段：

jj split                 # Interactive: pick files/hunks for first change, rest goes to second
jj split                 # Split again if needed

如果拆分出错，执行 jj undo 后重试。

模式 4：骨架规划（推荐用于复杂任务）

创建空变更作为计划，然后按顺序填充：

jj commit -m "refactor: extract auth module"
jj commit -m "feat: add token refresh logic"
jj commit -m "test: update auth tests"
jj commit -m "docs: update API documentation"

然后逐个完成它们：

jj edit <first-change>   # Jump to first skeleton change
# ... implement ...
jj edit <next-change>    # Jump to next (previous work auto-rebases descendants)
# ... implement ...

每个变更的描述既作为提交信息，也作为验收标准。在继续之前，请验证你的实现与描述相符。

描述字段支持与 git 提交信息相同的格式：第一行是标题，空行，然后是正文。你可以用 -m 在正文中编写详细的规格或提示词。

模式 5：撤销与恢复

jj undo                  # Undo last operation, no questions asked
jj op log                # See full operation history if you need to go further back
jj op restore <op-id>    # Jump to any point in operation history

优先使用 jj undo，而不是尝试手动反向修改。它始终正确且安全。

应避免的常见错误

• 不要在 jj 仓库中使用 git add、git commit、git stash 或 git checkout。 请改用 jj 的等价命令。
• 不要在没有充分理由的情况下尝试 jj edit 一个不可变（已发布）的变更。 jj 会阻止这样做。如果你需要修复已发布历史中的某些内容，请使用 jj new <change> 创建一个后续变更。
• 不要为仅限本地的工作创建书签。 只有在推送到远程时才需要书签。本地工作由 Change ID 跟踪。
• 不要担心“丢失”变更。 jj 的操作日志会保留一切。使用 jj undo 或 jj op restore 可从任何错误中恢复。

快速参考

任务	jj 命令
在现有 git 仓库中初始化	jj git init --colocate
查看当前情况	jj log
描述当前变更	jj describe -m "..."
开始下一项任务	jj new
从特定变更分支	jj new <change>
编辑较旧的变更	jj edit <change>
丢弃一个变更	jj abandon / jj abandon <change>
拆分一个变更	jj split
撤销任何操作	jj undo
获取远程	jj git fetch
跟踪远程分支	jj bookmark track <name>@<remote>
变基到 master	jj rebase -d master
为推送创建书签	jj bookmark create <name> -r @
移动现有书签	jj bookmark set <name> -r <change>
推送到远程	jj git push
推送特定书签	jj git push --bookmark <name>
推送书签删除	jj git push --deleted
合并多个变更	jj new <chg1> <chg2> ...
并行工作区	jj workspace add <path>

超越本技能

本技能涵盖最常见的操作。对于此处未涵盖的高级用法，请使用：

jj help                  # List all commands
jj help <command>        # Detailed help for a specific command
jj help -k <keyword>     # Search help by keyword

jj 具有丰富的功能（revsets、模板、自定义别名、冲突解决等），你可以通过 jj help 探索并根据情况应用。官方文档位于 https://jj-vcs.github.io/jj/。