让版本控制变简单：Jujutsu (jj、git威力加强版) 使用手册

什么是 Jujutsu？

Jujutsu (jj) 是一个用 Rust 编写的现代版本控制系统，专门设计来解决 Git 使用过程中的令人头疼的问题。

使用 jj 后，再也不用担心 git add 忘记暂存文件，也不用再纠结 rebase 操作，更不用因为合并冲突去烦恼。

同时 jj 保持与 Git 100% 的兼容性，我们可以在任何 Git 仓库中使用它，而且更适合与同事丝滑协作，享受更优雅的开发体验。

写这篇文章一是为了介绍这个优秀的工具，二是为了给自己做个完整的命令参考手册。花点时间把所有常用命令整理在一起，后面就不用到处翻文档了。

为什么选择 jj？

告别 Git 的痛点：

• 忘记 git add？ jj 自动追踪所有修改，不需要手动暂存
• 焦虑 git rebase？ jj 的历史操作安全直观，支持无痛撤销
• 分支切换丢失代码？ jj 的每个修改都是一个变更，永不丢失
• 合并冲突头疼？ jj 提供更智能的冲突解决机制
• 多人协作混乱？ jj 的 Change ID 让协作追踪变得清晰

实际的开发体验提升：

• 修改文件后直接 jj describe 添加提交信息，不用 add
• 想修改历史提交？jj edit 切换过去修改，再切换回来
• 需要同时开发多个功能？创建多个工作区并行进行
• 担心操作失误？jj 记录所有操作，任何时候都能回滚

既是尝鲜，也是日常开发效率的提升。

安装与初始化

安装方式

通过包管理器安装：

# macOS (Homebrew)
brew install jj

# Arch Linux
pacman -S jujutsu

# Ubuntu/Debian
cargo install --locked --bin jj jj-cli

# Windows (Cargo)
cargo install --locked --bin jj jj-cli

基本配置

# 配置用户信息
jj config set --user user.name "你的名字"
jj config set --user user.email "your@email.com"

# 查看配置
jj config list

核心概念速成

变更 (Change) vs 提交 (Commit)

• 变更 (Change): jj 的核心概念，每个变更都有唯一的 Change ID
• 提交 (Commit): Git 概念，一个变更可能对应多个提交

工作区 (Working Copy)

• jj 可以有多个工作区
• 每个工作区对应一个变更
• 支持同时在不同分支上工作

核心命令大全

1. 仓库初始化和克隆

# 初始化新的 jj 仓库
jj git init [路径]

# 从 Git 仓库克隆
jj git clone <url> [路径]

# 从现有 Git 仓库初始化
jj git init --git-repo=.

# 初始化裸仓库
jj init --bare [路径]

2. 基本工作流命令

查看状态和历史

# 查看当前状态
jj status
jj st

# 查看变更历史
jj log
jj log -r 'all()'

# 查看特定变更的历史
jj log -r <change-id>

# 图形化显示历史
jj log --graph
jj log -G

# 查看简洁历史
jj log --oneline
jj log --summary

创建和管理变更

# 创建新变更 (自动执行)
# jj 会自动为工作目录的修改创建变更

# 手动创建空变更
jj new
jj new -m "提交消息"

# 从特定变更创建新变更
jj new <change-id>

# 从多个父变更创建合并变更
jj new <change1> <change2>

描述变更

# 添加或编辑变更描述
jj describe
jj describe -m "新的描述"

# 为特定变更添加描述
jj describe <change-id> -m "描述"

# 使用编辑器编辑描述
jj describe --editor

3. 分支管理

# 创建分支
jj branch create <分支名>
jj branch create <分支名> -r <change-id>

# 列出分支
jj branch list
jj branch list -a  # 包括远程分支

# 删除分支
jj branch delete <分支名>

# 重命名分支
jj branch rename <旧名> <新名>

# 设置分支指向特定变更
jj branch set <分支名> -r <change-id>

# 追踪远程分支
jj branch track <branch>@<remote>

4. 工作区管理

# 列出工作区
jj workspace list

# 添加新工作区
jj workspace add <路径> [--name <名称>]

# 切换到不同的变更
jj edit <change-id>

# 检出到新工作区
jj new <change-id>

# 忘记工作区 (不删除文件)
jj workspace forget [路径]

# 更新到最新变更
jj workspace update-stale

5. 文件操作

# 查看文件状态
jj files
jj files -r <change-id>

# 查看修改内容
jj diff
jj diff -r <change-id>
jj diff --git  # Git 格式输出

# 比较两个变更
jj diff -r <from> -r <to>

# 查看特定文件的修改
jj diff <文件名>

# 显示文件内容
jj cat <文件名>
jj cat -r <change-id> <文件名>

# 恢复文件
jj restore <文件名>
jj restore -r <change-id> <文件名>

# 添加文件到版本控制
jj track <文件名>

# 取消追踪文件
jj untrack <文件名>

6. 历史重写和修改

# 修改变更 (amend)
jj squash  # 将当前变更合并到父变更

# 拆分变更
jj split -r <change-id>

# 编辑历史变更
jj edit <change-id>

# 复制变更 (cherry-pick)
jj duplicate <change-id>

# 移动变更到新的父变更上
jj rebase -d <destination> <change-id>

# 压缩多个变更
jj squash -r <change1> -r <change2> -d <destination>

# 放弃变更
jj abandon <change-id>

# 还原已放弃的变更
jj restore --from <change-id>

7. 远程仓库操作

# 添加远程仓库
jj git remote add <名称> <URL>

# 列出远程仓库
jj git remote list

# 从远程仓库获取更新
jj git fetch
jj git fetch --remote <远程名>

# 推送到远程仓库
jj git push
jj git push --remote <远程名>
jj git push --branch <分支名>

# 推送所有分支
jj git push --all

# 推送并创建远程分支
jj git push --remote <远程名> --branch <分支名>

# 设置上游分支
jj branch track <branch>@<remote>

8. 冲突解决

# 查看冲突状态
jj status

# 列出冲突文件
jj resolve --list

# 解决冲突 (启动合并工具)
jj resolve
jj resolve <文件名>

# 手动标记冲突已解决
jj resolve --mark-resolved <文件名>

# 重新开始冲突解决
jj resolve --restart <文件名>

9. 高级查询和过滤

# 使用修订集 (revset) 查询
jj log -r 'heads()'           # 所有头部变更
jj log -r 'roots()'           # 所有根变更
jj log -r 'branches()'        # 所有分支头部
jj log -r 'remote_branches()' # 所有远程分支头部

# 按作者查询
jj log -r 'author("name")'

# 按描述查询
jj log -r 'description("关键词")'

# 按日期查询
jj log -r 'committer_date("2024-01-01".."2024-12-31")'

# 查看祖先
jj log -r 'ancestors(<change-id>)'

# 查看后代
jj log -r 'descendants(<change-id>)'

# 复杂查询组合
jj log -r 'heads() & branches()'
jj log -r '~empty() & mine()'

10. 配置管理

# 查看所有配置
jj config list

# 设置用户配置
jj config set --user <key> <value>

# 设置仓库配置
jj config set --repo <key> <value>

# 编辑配置文件
jj config edit --user
jj config edit --repo

# 常用配置项
jj config set --user ui.default-command "log"
jj config set --user ui.editor "code --wait"
jj config set --user ui.diff.tool "vimdiff"
jj config set --user ui.merge-tool "vscode"

11. 调试和故障排除

# 显示详细信息
jj --verbose <命令>
jj -v <命令>

# 调试模式
jj --debug <命令>

# 检查仓库完整性
jj debug reindex

# 显示原始对象信息
jj debug cat <object-id>

# 显示变更信息
jj debug change-id <change-id>

# 查看操作日志
jj op log
jj operation log

# 撤销操作
jj op undo
jj operation undo

# 恢复操作
jj op restore <operation-id>

12. 模板和输出自定义

# 使用自定义模板显示日志
jj log -T 'change_id ++ " " ++ description'

# 显示更多信息
jj log -T 'builtin_log_detailed'

# 自定义状态显示
jj status -T 'if(conflict, "CONFLICT", "OK")'

# 设置默认模板
jj config set --user templates.log 'builtin_log_compact'

实用技巧

1. 工作流建议

日常开发流程：

# 1. 获取最新更新
jj git fetch

# 2. 创建新功能分支
jj new main -m "开始新功能"
jj branch create feature/新功能

# 3. 进行修改并描述
jj describe -m "实现新功能的第一部分"

# 4. 继续开发
jj new -m "完善新功能"

# 5. 推送到远程
jj git push --branch feature/新功能

2. 高级技巧

并行开发多个功能：

# 为每个功能创建工作区
jj workspace add ../feature1 --name feat1
jj workspace add ../feature2 --name feat2

# 在不同工作区之间切换开发
cd ../feature1
jj edit <feature1-change-id>

cd ../feature2  
jj edit <feature2-change-id>

智能历史清理：

# 合并相关的小变更
jj squash -r 'description("临时提交")'

# 重新组织提交历史
jj rebase -d main 'branches() & ~main'

3. 迁移指南

从 Git 迁移：

1. 在现有 Git 仓库中运行 jj git init --git-repo=.
2. 继续正常开发，jj 会自动同步到 Git
3. 逐步采用 jj 工作流
4. 团队其他成员可以继续使用 Git

常见命令对照表

Git 命令	jj 等价命令	说明
git init	jj git init	初始化仓库
git clone	jj git clone	克隆仓库
git status	jj status	查看状态
git log	jj log	查看历史
git add .	(自动)	jj 自动追踪变更
git commit	jj describe	添加提交消息
git checkout	jj edit	切换到变更
git branch	jj branch	分支操作
git merge	jj new <a> <b>	创建合并
git rebase	jj rebase	变基操作
git fetch	jj git fetch	获取远程更新
git push	jj git push	推送到远程
git diff	jj diff	查看差异
git cherry-pick	jj duplicate	复制变更
git reset	jj abandon	放弃变更

注意事项

1. 实验性特性: jj 仍然是一个实验性系统，可能存在进行中的功能、次优的用户体验和工作流程空白
2. 学习曲线: 虽然 jj 更简洁，但仍需要理解其独特的概念
3. 团队采用: 建议先在个人项目中尝试，再考虑团队迁移
4. 备份重要数据: 在重要项目中使用前，确保有适当的备份

资源链接

• 官方文档 : jj-vcs.github.io/jj/latest/
• GitHub 仓库 : github.com/jj-vcs/jj
• 安装指南 : jj-vcs.github.io/jj/latest/i...
• 教程 : jj-vcs.github.io/jj/latest/t...

🌟 写在最后

为什么我推荐 jj？因为它真正解决了我在 Git 中遇到的实际问题。不用再为忘记 git add 而苦恼，不用再小心翼翼地处理 rebase，更不用再担心切换分支时丢失代码。jj 让版本控制回归本质：专注于代码本身，而不用关注工具的复杂性。

虽然 jj 目前还是实验性质，但它的 Git 兼容性让我们可以安全地在实际项目中使用。你可以随时回到 Git，也可以与使用 Git 的同事无缝协作。这种渐进式的迁移方式，让我们能够在保持稳定性的同时，体验更先进的版本控制。

整理这份命令手册，希望能帮助到想要尝试 jj 的朋友们。

独乐乐不如众乐乐。

如果你是GUI用户的话，也可以去看看 gitbutler ，同样是Rust编写的一款极具创意的Git GUI工具。