入门指南

Jujutsu 是一个实验性的版本控制系统（version control system）。虽然它对 Git 的兼容性已经很稳定，绝大多数开发者每天都会用它完成各种需求，但它仍可能包含一些开发中的功能、不够理想的用户体验，或工作流上的空白，这些可能会让它暂时不适合你的特定使用场景。

请按照 安装指南 获取并配置 jj。

最好的入门方式是阅读这份 教程。你也可以查看这份 Git 对比表，其中列出了 jj 和 git 命令的对照表。

随着你对 Jujutsu 的熟悉程度提升，下面这些资源也可能对你有帮助：

如果你正在使用 jj 的 预发布版本（prerelease），请参考 预发布版本文档。你也可以在官网页面顶部使用“版本切换器”进入该文档版本。

功能特色

与 Git 兼容

Jujutsu 的底层数据和存储模型是抽象设计的。目前，仅 Git 后端是正式可用的生产级别实现。Git 后端基于 Rust 编写的 gitoxide 库构建。

这个 Git 后端功能完整并持续维护，允许你将 Jujutsu 与任何 Git 远程仓库搭配使用。你创建的提交看起来就像普通的 Git 提交一样。你可以从标准的 Git 远程仓库拉取分支，也可以推送分支到远程。你随时都可以切换回 Git。

你甚至可以创建一个 “共存的”本地仓库（co-located local repository），在其中同时使用 jj 和 git 命令交替操作。

入门指南 - 图1

工作区自动作为提交保存

Jujutsu 使用一个真实的提交对象（commit）来表示工作区（working copy）。每次检出某个提交时，系统会在目标提交的基础上创建一个新的工作区提交。几乎所有命令都会自动修改这个工作区提交。

由于工作区本身就是一个提交对象，这意味着命令永远不会因为“工作区未提交（dirty）”而失败（不会出现 “error: Your local changes to the following files…” 这类报错），你也不再需要 git stash。而且由于工作区是一个普通提交，你可以像操作其他提交一样操作它，比如在改动还没完成时就先写好提交信息。

入门指南 - 图2

仓库是唯一的“真实来源（source of truth）”

在 Jujutsu 中，工作区的作用比在 Git 中要小得多。命令执行前会先对工作区做一个快照，然后更新仓库数据，最后再更新工作区（如果工作区提交有被修改的话）。几乎所有命令（甚至包括 checkout）都只操作仓库中的提交，快照和更新工作区的功能被集中在一段通用代码中处理。

比如，jj restore（类似于 git restore）可以从任意提交恢复到任意提交，而 jj describe 可以设置任意提交的提交信息（默认操作当前工作区提交）。

整个仓库都在版本控制之下

你在仓库中执行的每一个操作，都会被记录下来，并附带操作完成后的仓库状态快照。这意味着你可以轻松恢复到早期的仓库状态，或者撤销某个特定操作（不一定是最近的一次）。

入门指南 - 图3

冲突信息可被记录到提交中

如果某个操作导致了 冲突（conflicts），相关的冲突信息会被写入到提交中，操作本身仍会成功执行。你可以稍后再去解决冲突。

这种设计有一个好处是：不需要中断操作后再恢复流程。无论是哪个命令导致冲突，解决它的流程都是统一的。此外，这种设计还允许 Jujutsu 正确地 rebase 合并提交（merge commits） —— 这是 Git 和 Mercurial 都做不到的。

基本冲突处理：

入门指南 - 图4

复杂冲突处理（Juggling conflicts）：

入门指南 - 图5

自动 rebase

每当你修改一个提交时，它的所有子提交都会自动 rebase 到新的提交上。由于上述的冲突机制，这项操作即便存在冲突也能完成。所有指向被 rebase 提交的书签（bookmark）也会被更新。如果你的工作区当前正好指向该提交，它也会自动更新。

完整支持历史重写

除了常规的 rebase 命令，Jujutsu 还提供 jj describe 来修改任意提交的提交信息。你也可以使用 jj diffedit 来编辑提交内容，而无需检出该提交。

如果你想把一个提交拆分成两个，可以使用 jj split。你甚至可以使用 jj squash -i --from X --into Y 将一个提交中的部分变更合并（squash）进另一个提交中。