jujutsu-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Jujutsu Workflow

Jujutsu 工作流

Prefer
jj
(Jujutsu) over raw
git
whenever a
.jj/
repo is present. Git stays the canonical remote/PR/CI/audit interface: mutate with
jj
, verify with read-only Git.
**只要仓库中存在
.jj/
,就优先使用
jj
(Jujutsu),而非直接执行
git
。Git 仍作为规范的远程仓库/PR/CI/审计接口:使用
jj
修改状态,使用只读 Git 进行验证。

1. Detect & gate first

1. 首先检测并执行门禁

Run
${CLAUDE_SKILL_DIR}/scripts/detect_jj_state.sh
, or check manually:
  • .jj/
    present → jj repo: use
    jj
    , never mutating raw
    git
    .
  • .jj/
    and
    .git/
    → colocated: mutate with
    jj
    , read with git, never touch the git index/staging.
  • only
    .git/
    → plain Git repo: do not introduce
    jj
    unless asked.
  • in a git worktree,
    jj root
    ≠
    git rev-parse --show-toplevel
    → shadowed (exit 3): jj answers for the parent repo. Run no
    jj
    ; use git, then ask.
See references/git-interop.md.
运行
${CLAUDE_SKILL_DIR}/scripts/detect_jj_state.sh
,或手动检查:
  • .jj/
    存在 → jj 仓库:使用
    jj
    ,绝不执行会修改状态的原生
    git
    。
  • .jj/
    且
    .git/
    存在 → 共置仓库:使用
    jj
    修改,使用 git 读取,绝不触碰 git index/staging。
  • 只有
    .git/
    → 普通 Git 仓库:除非用户要求,否则不要引入
    jj
    。
  • 在 git worktree 中,
    jj root
    ≠
    git rev-parse --show-toplevel
    → 被遮蔽(退出码 3):jj 返回的是父仓库的结果。不运行任何
    jj
    ;使用 git,然后询问。
参见 references/git-interop.md。

2. Agent-safety rules (non-negotiable)

2. Agent 安全规则(不可协商)

  • Always
    --no-pager
    on commands that print. Do not write
    ui.paginate
    into the user's config —
    --user
    outlives the session and takes paging away from their interactive
    jj
    too.
  • Always
    -m
    . Never run editor/TUI forms — bare
    jj describe|commit|squash
    ,
    jj split
    (interactive),
    jj squash -i
    ,
    jj resolve
    ,
    jj diffedit
    — they hang agents.
  • jj
    snapshots the working copy only when a jj command runs, not on every file write.
See references/agent-safety.md.
  • 对会输出内容的命令,始终使用
    --no-pager
    。不要将
    ui.paginate
    写入用户配置——
    --user
    的设置会持续到会话结束之后,并且会让用户交互式使用
    jj
    时也失去分页。
  • 始终使用
    -m
    。绝不运行需要编辑器或 TUI 的形式——不帶参数的
    jj describe|commit|squash
    、交互式
    jj split
    、
    jj squash -i
    、
    jj resolve
    、
    jj diffedit
    ——这些命令会让 Agent 卡住。
  • jj
    仅在运行 jj 命令时对 working copy 创建快照,而不是在每次文件写入时创建。
参见 references/agent-safety.md。

3. Edit loop

3. 编辑循环

bash
jj --no-pager status
bash
jj --no-pager status

edit files (snapshotted on the next jj command)

edit files (snapshotted on the next jj command)

jj --no-pager diff jj describe -m "<project-conventional message>" jj new -m "<next unit>" # one change per logical unit

Split non-interactively: `jj split <path> -m "<msg>"`. See [references/command-map.md](references/command-map.md).
jj --no-pager diff jj describe -m "<project-conventional message>" jj new -m "<next unit>" # one change per logical unit

以非交互方式拆分:`jj split <path> -m "<msg>"`。参见 [references/command-map.md](references/command-map.md)。

4. Recover (reversible)

4. 恢复(可逆)

jj --no-pager op log
→
jj undo
or
jj op restore <id>
. Conflicts are first-class:
jj status
flags them; edit markers, then verify. See references/recovery-playbook.md.
jj --no-pager op log
→
jj undo
或
jj op restore <id>
。冲突被视为一等公民:
jj status
会标记冲突;编辑标记,然后验证。参见 references/recovery-playbook.md。

5. Hand off via Git

5. 通过 Git 移交

bash
jj git fetch
jj rebase -d <default-branch>
jj bookmark create <branch> -r @-    # every pushed commit needs a description
jj git push --bookmark <branch>      # new bookmarks push directly
Never push to a protected/default branch; never rewrite public history unless allowed. Open the PR with
gh
/
glab
. See references/pr-handoff.md.
bash
jj git fetch
jj rebase -d <default-branch>
jj bookmark create <branch> -r @-    # every pushed commit needs a description
jj git push --bookmark <branch>      # new bookmarks push directly
绝不推送到受保护的分支或默认分支;除非获得允许,否则绝不重写公开历史。使用
gh
/
glab
创建 PR。参见 references/pr-handoff.md。

6. Parallel agents

6. 并行 Agent

One
jj workspace
per concurrent agent — never share a working copy. See references/parallel-agents.md.
每个并发 Agent 使用一个
jj workspace
——绝不共享 working copy。参见 references/parallel-agents.md。

7. Verify before "done"

7. 声称“完成”前进行验证

Run
${CLAUDE_SKILL_DIR}/scripts/verify_handoff.sh
, or report
jj --no-pager status
,
jj --no-pager log --limit 10
,
jj --no-pager diff --stat
,
git status --short --branch
. Never claim "done/tested/ready" without that output; disclose force-pushes, recoveries, conflicts.
When jj helps, and when it doesn't: references/why-jj-for-agents.md.
运行
${CLAUDE_SKILL_DIR}/scripts/verify_handoff.sh
,或者报告
jj --no-pager status
、
jj --no-pager log --limit 10
、
jj --no-pager diff --stat
、
git status --short --branch
的输出。在未输出上述结果前,绝不要声称“已完成/已测试/已就绪”;应披露 force-push、恢复操作和冲突。
何时 jj 有帮助,何时无帮助:references/why-jj-for-agents.md。