jj-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

jj Workflow

jj 工作流程

CRITICAL: Avoid Interactive Mode

重要提示：避免使用交互模式

Always use
-m
flag to prevent jj from opening an editor:

bash

undefined

始终使用
-m
参数以防止jj打开编辑器：

bash

undefined

WRONG - opens editor, blocks AI

错误示例 - 会打开编辑器，阻塞AI

jj new jj describe jj squash

CORRECT - non-interactive

正确示例 - 非交互模式

jj new -m "message" jj describe -m "message" jj squash -m "message"


**Never use these interactive commands:**

- `jj split` - inherently interactive, no non-interactive mode

jj new -m "message" jj describe -m "message" jj squash -m "message"


**切勿使用以下交互命令：**

- `jj split` - 本质为交互模式，无对应非交互版本

Mental Model

思维模型

No staging area. Your working directory is always a commit. Every save is tracked.

```
@
```
= your current change (the working copy)
```
@-
```
= parent of current change
Changes are mutable until pushed

无暂存区。你的工作目录始终是一个提交。每次保存都会被追踪。

```
@
```
= 当前变更（工作副本）
```
@-
```
= 当前变更的父提交
变更在推送前都是可修改的

When to Use What

场景对应操作

Situation	Do This
Starting new work	`jj new -m "what I'm trying"`
Forgot to start with jj new	`jj describe -m "what I'm doing"` (do this immediately)
Work is done, move on	`jj new -m "next task"`
Annotate what you did	`jj describe -m "feat: auth"`
Broke something	`jj op log` → `jj op restore <id>`
Undo one file	`jj restore --from @- <path>`
Combine messy commits	`jj squash -m "combined message"`
Try something risky	`jj new -m "experiment"` , then `jj abandon @` if it fails

场景	操作方式
开始新工作	`jj new -m "我的任务内容"`
忘记先执行jj new	`jj describe -m "我正在做的工作"` （立即执行此命令）
工作完成，切换到下一个任务	`jj new -m "下一个任务"`
为已完成工作添加说明	`jj describe -m "feat: 权限功能"`
出现问题需要回滚	`jj op log` → `jj op restore <id>`
撤销单个文件的变更	`jj restore --from @- <path>`
合并零散的提交	`jj squash -m "合并后的提交信息"`
尝试有风险的变更	`jj new -m "实验性变更"` ，如果失败则执行 `jj abandon @`

AI Coding Pattern

AI 编码模式

Always have a description. The working copy should never stay "(no description set)".

bash

undefined

始终添加提交描述。工作副本绝不能保持“(no description set)”状态。

bash

undefined

BEFORE starting work - declare intent

开始工作前 - 声明意图

jj new -m "feat: add user logout button"

jj new -m "feat: 添加用户退出按钮"

Now implement... jj tracks everything automatically

现在开始实现... jj会自动追踪所有变更

FORGOT to start with jj new? Describe immediately

忘记先执行jj new？立即添加描述

jj describe -m "feat: what I'm working on"


**Why this matters:**

- `jj log` shows meaningful history while working
- Easier to understand what each change does
- Simpler to curate/squash later
- Teammates can follow progress

```bash

jj describe -m "feat: 我正在开发的功能"


**为什么这很重要：**

- `jj log` 会显示有意义的工作历史
- 更容易理解每个变更的作用
- 后续整理/合并提交更简单
- 团队成员可以跟进进度

```bash

Checkpoint before risky changes

进行风险变更前创建检查点

jj describe -m "checkpoint: auth works" jj new -m "trying OAuth integration"

jj describe -m "checkpoint: 权限功能正常" jj new -m "尝试集成OAuth"

If it breaks

如果出现问题

jj op log # Find good state jj op restore <id> # Go back

jj op log # 找到正常状态 jj op restore <id> # 回滚到该状态

When done, curate history

完成后，整理提交历史

jj squash -m "feat: OAuth support"

undefined

jj squash -m "feat: 支持OAuth"

undefined

Push to GitHub

推送到GitHub

Pushed commits are immutable. You can't squash into or modify them. The safe pattern:

bash

undefined

已推送的提交是不可变的。你无法合并或修改已推送的提交。安全操作模式：

bash

undefined

1. Abandon empty checkpoint commits cluttering history

1. 清理历史中的空检查点提交

jj log -r '::@' # Find checkpoints jj abandon <change-ids> # Remove empty ones

jj log -r '::@' # 找到检查点 jj abandon <change-ids> # 删除空提交

2. Describe your work (don't try to squash into immutable parent)

2. 为工作添加描述（不要尝试合并到不可变的父提交中）

jj describe -m "feat: what you did"

jj describe -m "feat: 完成的工作内容"

3. Move bookmark to your commit and push

3. 将书签指向当前提交并推送

jj bookmark set master -r @ jj git push


**For feature branches (new):**

```bash
jj bookmark create feature-x -r @
jj git push --bookmark feature-x

jj bookmark set master -r @ jj git push


**对于新的功能分支：**

```bash
jj bookmark create feature-x -r @
jj git push --bookmark feature-x

If refused, configure auto-tracking once:

如果被拒绝，先配置一次自动追踪：

jj config set --user 'remotes.origin.auto-track-bookmarks' 'glob:*'

Then retry: jj git push --bookmark feature-x

然后重试：jj git push --bookmark feature-x


**For feature branches (updating):**

```bash
jj bookmark set feature-x -r @
jj git push

Teammates see clean git. They don't know you used jj.


**对于已有的功能分支（更新）：**

```bash
jj bookmark set feature-x -r @
jj git push

团队成员看到的是整洁的git提交历史，他们不会知道你使用了jj。

Recovery

恢复操作

The oplog records every operation. Nothing is lost.

bash

jj op log                      # See all operations
jj undo                        # Undo last operation
jj op restore <id>             # Jump to any past state

操作日志会记录所有操作。不会丢失任何内容。

bash

jj op log                      # 查看所有操作
jj undo                        # 撤销上一次操作
jj op restore <id>             # 跳转到任意历史状态

Bail Out

紧急退出

bash

rm -rf .jj    # Delete jj, keep git unchanged

bash

rm -rf .jj    # 删除jj相关文件，保留git内容不变