jujutsu

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Jujutsu (jj) Version Control System

Jujutsu (jj) 版本控制系统

This skill helps you work with Jujutsu, a Git-compatible VCS with mutable commits and automatic rebasing.

Tested with jj v0.37.0 - Commands may differ in other versions.

本技能可帮助你使用Jujutsu（jj），这是一款与Git兼容的版本控制系统，支持可变提交和自动变基。

已在jj v0.37.0版本测试——其他版本的命令可能有所不同。

Important: Automated/Agent Environment

重要提示：自动化/Agent环境

When running as an agent:

Always use
-m
flags to provide messages inline rather than relying on editor prompts:

bash

undefined

在Agent环境中运行时：

始终使用
-m
参数，直接在命令行提供消息，而非依赖编辑器弹窗：

bash

undefined

Always use -m to avoid editor prompts

始终使用-m以避免编辑器弹窗

jj desc -m "message" # NOT: jj desc jj squash -m "message" # NOT: jj squash (which opens editor)


Editor-based commands will fail in non-interactive environments.

2. **Verify operations with `jj st`** after mutations (`squash`, `abandon`, `rebase`, `restore`) to confirm the operation succeeded.

jj desc -m "message" # 不要使用：jj desc jj squash -m "message" # 不要使用：jj squash（会打开编辑器）


基于编辑器的命令在非交互式环境中会执行失败。

2. **在执行变更操作（`squash`、`abandon`、`rebase`、`restore`）后，使用`jj st`验证操作结果**，确认操作已成功完成。

Core Concepts

核心概念

The Working Copy is a Commit

工作副本即提交

In jj, your working directory is always a commit (referenced as

). Changes are automatically snapshotted when you run any jj command. There is no staging area.

There is no need to run

jj commit

在jj中，你的工作目录始终是一个提交（用

引用）。当你运行任何jj命令时，变更会被自动快照保存。jj没有暂存区。

无需执行

jj commit

命令。

Commits Are Mutable

提交是可变的

CRITICAL: Unlike git, jj commits can be freely modified. This enables a high-quality commit workflow:

Use
```
jj new
```
to initialize a new, blank commit.
Describe your intended changes first with
```
jj desc -m"Message"
```
Make your changes
When complete, use
```
jj new
```
to initialize a new, blank commit and begin the process again.

You may refine the commit using

jj squash

jj absorb

as needed

关键提示：与Git不同，jj的提交可自由修改。这实现了高质量的提交工作流：

使用
```
jj new
```
初始化一个新的空白提交。
先用
```
jj desc -m"Message"
```
描述你计划的变更
进行代码修改
完成后，使用
```
jj new
```
初始化一个新的空白提交，重复上述流程。

你可根据需要使用

jj squash

或

jj absorb

优化提交。

Change IDs vs Commit IDs

变更ID vs 提交ID

Change ID: A stable identifier (like
```
tqpwlqmp
```
) that persists when a commit is rewritten
Commit ID: A content hash (like
```
3ccf7581
```
) that changes when commit content changes

Prefer using Change IDs when referencing commits in commands.

变更ID：稳定的标识符（如
```
tqpwlqmp
```
），在提交被重写时仍保持不变
提交ID：内容哈希值（如
```
3ccf7581
```
），当提交内容变更时会随之改变

在命令中引用提交时，优先使用变更ID。

Essential Workflow

核心工作流

Starting Work: Describe First, Then Code

开始工作：先描述，再编码

Always create your commit message before writing code:

bash

undefined

务必在编写代码前创建提交信息：

bash

undefined

First, describe what you intend to do

首先，描述你要完成的工作

jj desc -m "Add user authentication to login endpoint"

jj desc -m "为登录端点添加用户认证"

Then make your changes - they automatically become part of this commit

然后进行修改——变更会自动成为该提交的一部分

... edit files ...

... 编辑文件 ...

Check status

查看状态

jj st

undefined

jj st

undefined

Creating Atomic Commits

创建原子提交

Each commit should represent ONE logical change. Use this format for commit messages:

Examples:
- "Add validation to user input forms"
- "Fix null pointer in payment processor"
- "Remove deprecated API endpoints"
- "Update dependencies to latest versions"

每个提交应代表一个逻辑变更。提交信息请使用以下格式：

示例：
- "为用户输入表单添加验证"
- "修复支付处理器中的空指针问题"
- "移除已废弃的API端点"
- "将依赖更新至最新版本"

Viewing History

查看历史

bash

undefined

bash

undefined

View recent commits

查看近期提交

jj log

View with patches

查看带补丁的历史

jj log -p

View specific commit

查看特定提交

jj show <change-id>

View diff of working copy

查看工作副本的差异

jj diff

undefined

jj diff

undefined

Moving Between Commits

在提交间切换

bash

undefined

bash

undefined

Create a new empty commit on top of current

在当前提交之上创建一个新的空提交

jj new

Create new commit with message

创建带消息的新提交

jj new && jj desc -m "Commit message"

Edit an existing commit (working copy becomes that commit)

编辑现有提交（工作副本会切换为该提交）

jj edit <change-id>

Edit the previous commit

编辑上一个提交

jj prev -e

Edit the next commit

编辑下一个提交

jj next -e

undefined

jj next -e

undefined

Refining Commits

优化提交

Squashing Changes

合并提交

Move changes from current commit into its parent:

bash

undefined

将当前提交的变更合并到其父提交：

bash

undefined

Squash all changes into parent

将所有变更合并到父提交

jj squash


**Note**: `jj squash -i` opens an interactive UI and will hang in agent environments. Avoid it.

jj squash


**注意**：`jj squash -i`会打开交互式界面，在Agent环境中会挂起，请避免使用。

Splitting Commits

拆分提交

Warning:

jj split

is interactive and will hang in agent environments. To divide a commit, use

jj restore

to move changes out, then create separate commits manually.

警告：

jj split

是交互式命令，在Agent环境中会挂起。如需拆分提交，请使用

jj restore

将变更移出，然后手动创建独立的提交。

Absorbing Changes

自动分配变更

Automatically distribute changes to the commits that last modified those lines:

bash

undefined

自动将变更分配到最后修改对应代码行的提交中：

bash

undefined

Absorb working copy changes into appropriate ancestor commits

将工作副本的变更自动分配到合适的祖先提交

jj absorb

undefined

jj absorb

undefined

Abandoning Commits

废弃提交

Remove a commit entirely (descendants are rebased to its parent):

bash

jj abandon <change-id>

完全移除一个提交（其后代会被变基到其父提交）：

bash

jj abandon <change-id>

Undoing Operations

撤销操作

Reverse the last jj operation:

bash

jj undo

This reverts the repository to its state before the previous command. Useful for recovering from mistakes like accidental

abandon

squash

, or

rebase

撤销上一次jj操作：

bash

jj undo

这会将版本库恢复到执行上一个命令前的状态。适用于从意外的

abandon

、

squash

或

rebase

操作中恢复。

Restoring Files

恢复文件

Discard changes to specific files or restore files from another revision:

bash

undefined

丢弃特定文件的变更，或从其他版本恢复文件：

bash

undefined

Discard all uncommitted changes in working copy (restore from parent)

丢弃工作副本中所有未提交的变更（从父提交恢复）

jj restore

Discard changes to specific files

丢弃特定文件的变更

jj restore path/to/file.txt

Restore files from a specific revision

从特定版本恢复文件

jj restore --from <change-id> path/to/file.txt

undefined

jj restore --from <change-id> path/to/file.txt

undefined

Working with Bookmarks (Branches)

使用书签（分支）

Bookmarks are jj's equivalent to git branches:

bash

undefined

书签是jj中与Git分支对应的概念：

bash

undefined

Create a bookmark at current commit

在当前提交创建书签

jj bookmark create my-feature -r@

Move bookmark to a different commit

将书签移动到另一个提交

jj bookmark move my-feature --to <change-id>

List bookmarks

列出所有书签

jj bookmark list

Delete a bookmark

删除书签

jj bookmark delete my-feature

undefined

jj bookmark delete my-feature

undefined

Git Integration

Git集成

Working with Existing Git Repos

处理现有Git版本库

bash

undefined

bash

undefined

Clone a git repository

克隆Git版本库

jj git clone <url>

Initialize jj in an existing git repo

在现有Git版本库中初始化jj

jj git init --colocate

undefined

jj git init --colocate

undefined

Switching Between jj and git (Colocated Repos)

在jj和Git间切换（共存版本库）

In a colocated repository (where both

.jj/

and

.git/

exist), you can use both jj and git commands. However, there are important considerations:

Switching to git mode (e.g., for merge workflows):

bash

undefined

在共存版本库中（同时存在

.jj/

和

.git/

目录），你可以同时使用jj和Git命令，但有一些重要注意事项：

切换到Git模式（例如用于合并工作流）：

bash

undefined

First, ensure your jj working copy is clean

首先，确保jj工作副本是干净的

jj st

Then checkout a branch with git

然后用Git检出分支

git checkout <branch-name>


**Switching back to jj mode**:
```bash

git checkout <branch-name>


**切换回jj模式**：
```bash

Use jj edit to resume working with jj

使用jj edit恢复jj工作

jj edit <change-id>


**Important notes:**
- Git may complain about uncommitted changes if jj's working copy differs from the git HEAD
- ALWAYS ensure your work is committed in jj before switching to git
- After git operations, jj will detect and incorporate the changes on next command

jj edit <change-id>


**重要说明**：
- 如果jj工作副本与Git HEAD不一致，Git可能会提示存在未提交的变更
- **切换到Git前，务必确保所有工作已在jj中提交**
- 执行Git操作后，jj会在下次命令执行时检测并合并这些变更

Pushing Changes

推送变更

When the user asks you to push changes:

bash

undefined

当用户要求你推送变更时：

bash

undefined

Push a specific bookmark to the remote

将特定书签推送到远程

jj git push -b <bookmark-name>

Example: push the main bookmark

示例：推送main书签

jj git push -b main


**Before pushing, ensure:**
1. Your bookmark points to the correct commit (bookmarks don't auto-advance like git branches)
2. The commits are refined and atomic
3. The user has explicitly requested the push

**IMPORTANT**: Unlike git branches, jj bookmarks do not automatically move when you create new commits. You must manually update them before pushing:

```bash

jj git push -b main


**推送前请确认**：
1. 你的书签指向正确的提交（书签不会像Git分支那样自动推进）
2. 提交已优化且是原子化的
3. 用户已明确要求推送

**重要提示**：与Git分支不同，jj书签不会在你创建新提交时自动移动。推送前你必须手动更新书签：

```bash

Move an existing bookmark to the current commit

将现有书签移动到当前提交

jj bookmark move my-feature --to @

Then push it

然后推送

jj git push -b my-feature


If no bookmark exists for your changes, create one first:

```bash

jj git push -b my-feature


如果你的变更没有对应的书签，请先创建一个：

```bash

Create a bookmark at the current commit

在当前提交创建书签

jj bookmark create my-feature

Then push it

然后推送

jj git push -b my-feature

undefined

jj git push -b my-feature

undefined

Handling Conflicts

处理冲突

jj allows committing conflicts — you can resolve them later:

bash

undefined

jj允许提交冲突——你可以稍后解决它们：

bash

undefined

View conflicts

查看冲突

jj st


**Agent conflict resolution**: Do not use `jj resolve` (interactive). Instead, edit the conflicted files directly to remove conflict markers, then run `jj st` to verify resolution.

jj st


**Agent冲突解决**：不要使用`jj resolve`（交互式命令）。请直接编辑冲突文件以移除冲突标记，然后运行`jj st`验证是否已解决。

Preserving Commit Quality

保持提交质量

IMPORTANT: Because commits are mutable, always refine them:

Review your commit:
```
jj show @
```
or
```
jj diff
```
Is it atomic? One logical change per commit
Is the message clear? Use imperative verb phrase in sentence case format with no full stop: "Verb object"
Are there unrelated changes? Use
```
jj restore
```
to move changes out, then create separate commits
Should changes be elsewhere? Use
```
jj squash
```
or
```
jj absorb
```

重要提示：由于提交是可变的，请始终优化你的提交：

检查提交：使用
```
jj show @
```
或
```
jj diff
```
**是否原子化？**每个提交对应一个逻辑变更
**消息是否清晰？**使用祈使句短语，首字母大写，无句号："动词+对象"
**是否存在无关变更？**使用
```
jj restore
```
将变更移出，然后创建独立提交
**变更是否应该放在其他提交？**使用
```
jj squash
```
或
```
jj absorb
```

Quick Reference

快速参考

Action	Command
Describe commit	`jj desc -m "message"`
View status	`jj st`
View log	`jj log`
View diff	`jj diff`
New commit	`jj new && jj desc -m "message"`
Edit commit	`jj edit <id>`
Squash to parent	`jj squash`
Auto-distribute	`jj absorb`
Abandon commit	`jj abandon <id>`
Undo last operation	`jj undo`
Restore files	`jj restore [paths]`
Create bookmark	`jj bookmark create <name>`
Push bookmark	`jj git push -b <name>`

操作	命令
描述提交	`jj desc -m "message"`
查看状态	`jj st`
查看历史	`jj log`
查看差异	`jj diff`
新建提交	`jj new && jj desc -m "message"`
编辑提交	`jj edit <id>`
合并到父提交	`jj squash`
自动分配变更	`jj absorb`
废弃提交	`jj abandon <id>`
撤销上一次操作	`jj undo`
恢复文件	`jj restore [paths]`
创建书签	`jj bookmark create <name>`
推送书签	`jj git push -b <name>`

Best Practices Summary

最佳实践总结

Describe first: Set the commit message before coding
One change per commit: Keep commits atomic and focused
Use change IDs: They're stable across rewrites
Refine commits: Leverage mutability for clean history
Embrace the workflow: No staging area, no stashing - just commits

先描述：编写代码前设置提交信息
每个提交对应一个变更：保持提交原子化且聚焦
使用变更ID：它们在重写后仍保持稳定
优化提交：利用可变性实现清晰的历史记录
遵循工作流：没有暂存区，无需暂存——只需提交