jj-vcs/jj 来源：https://github.com/jj-vcs/jj

Jujutsu——版本控制系统

发布版本（https://github.com/jj-vcs/jj/releases）
发布日期（https://github.com/jj-vcs/jj/releases）
许可证（https://github.com/jj-vcs/jj/blob/main/LICENSE）
Discord（https://discord.gg/dkmfj3aGQN）
IRC（https://web.libera.chat/?channel=#jujutsu）

[主页] • [安装] • [入门指南] • [开发路线图] • 贡献指南
[主页]: https://www.jj-vcs.dev
[安装]: https://docs.jj-vcs.dev/latest/install-and-setup
[入门指南]: https://docs.jj-vcs.dev/latest/tutorial
[开发路线图]: https://docs.jj-vcs.dev/latest/roadmap

简介

Jujutsu 是一款强大的软件项目版本控制系统。您可以用它来获取代码副本、跟踪代码变更，并最终发布这些变更以供他人查看和使用。它的设计从一开始就注重易用性——无论您是新手还是经验丰富的开发者，无论是在独自开发全新项目，还是参与具有庞大历史记录和团队协作的大型软件项目。

Jujutsu 与众不同之处在于，它在内部将用户界面和版本控制算法与用于存储内容的存储系统进行了抽象分离。这使其能够作为支持多种物理后端的版本控制系统，这些后端可能拥有各自的数据或网络模型——例如 Mercurial 或 Breezy，或是像 Google 基于云的设计 Piper/CitC 这样的混合系统。

目前，我们使用 Git 仓库作为存储层来服务和跟踪内容，使其从现在起就能与您喜爱的许多基于 Git 的工具兼容！ 但请注意，Git 中仅存储提交（commit）和文件；书签（branch，即分支）和其他高层元数据则存储在 Git 之外的自定义存储中。

所有核心开发者都在 GitHub 上使用 Jujutsu 来开发 Jujutsu 本身。它也应该能与您喜爱的 Git 托管平台（forge）配合工作。我们将其他版本控制系统中的许多不同设计选择和概念融合到了一个工具中。部分灵感来源包括：

• Git：我们努力做到快速——提供流畅的用户体验、高效的算法、正确的数据结构，并注重细节。默认存储后端使用 Git 仓库进行“物理存储”，以实现广泛的互操作性和易上手性。
• Mercurial & Sapling：许多功能受 Mercurial 启发，例如用于选择提交的 revset（修订集）语言。没有显式的索引（index）或暂存区（staging area）。分支像 Mercurial 一样是“匿名”的，因此您无需为每个小更改命名。重写历史记录的基本操作强大而简洁。输出格式化通过一个健壮的模板语言完成，用户可自行配置。
• Darcs：Jujutsu 在其模型中将冲突（conflict）作为一等对象来跟踪；它们与提交一样是一等公民，而像 Git 这样的替代方案则仅将冲突视为文本差异。虽然不像 Darcs 那样严格（Darcs 基于形式化的补丁理论，而非快照），但其效果是许多形式的冲突解决可以自动执行和传播。

此外，它还添加了一些自身创新且实用的功能：

• 工作副本即提交（Working-copy-as-a-commit）：文件的更改会自动记录为普通提交，并在后续每次更改时进行修订。这种“快照”设计简化了面向用户的数据模型（提交是唯一可见的对象），简化了内部算法，并完全取代了 Git 的 stash 或索引/暂存区等功能。
• 操作日志与撤销（Operation log & undo）：Jujutsu 记录对仓库执行的每一次操作，从提交、拉取到推送。这使得调试“刚刚发生了什么？”或“我怎么会到这里？”这类问题更加容易，尤其是当您帮助同事解答他们仓库的这些问题时！而且因为所有操作都被记录，您可以轻松撤销刚刚犯下的错误。版本控制终于进入了20 世纪 60 年代！
• 自动变基与冲突解决：当您修改一个提交时，所有后代都会自动变基到新修改的提交之上。这使得基于补丁的工作流程变得轻而易举。如果您在某个提交中解决了冲突，该冲突的_解决方案_也会通过后代传播。实际上，这相当于一个完全透明版本的 git rebase --update-refs 结合 git rerere，通过设计提供支持。

以下功能可用，但属于实验性质；它们可能存在 bug、向后不兼容的存储更改以及用户界面更改！

• 安全、并发的复制（Safe, concurrent replication）：您是否曾想将版本控制的仓库存储在 Dropbox 文件夹中？或者持续备份仓库到 S3？不？现在您可以了！在典型的 Git/Mercurial 仓库上使用 Dropbox 等文件系统或 rsync 等备份工具的根本问题在于，它们依赖本地文件系统操作是原子的、串行的，并且与其他读写操作并发时是安全的——但在分布式文件系统上操作，或者在锁文件被持有期间发生并发文件复制（用于备份）等情况时，这_并不_成立。Jujutsu 的设计则旨在在并发场景下保持安全；仅仅使用 rsync 或 Dropbox 然后使用该结果仓库，永远不应导致仓库处于损坏状态。最坏_可能_发生的情况是它会暴露本地和远程状态之间的冲突，留给您去解决。

命令行工具目前称为 jj，因为它易于输入且易于替换（在英语中不常见）。项目名称为“Jujutsu”，因为它与“jj”相匹配。Jujutsu 相对年轻，仍有大量工作需要完成。如果您有任何问题，或想讨论未来计划，请加入我们的 Discord（https://discord.gg/dkmfj3aGQN），在 GitHub 上发起讨论（https://github.com/jj-vcs/jj/discussions），或在 Libera Chat 的 #jujutsu 频道发送 IRC 消息（https://web.libera.chat/?channel=#jujutsu）。开发者会监控所有这些渠道¹。

新闻与更新 📣

• 2024 年 12 月：jj 仓库已迁移至 jj-vcs GitHub 组织。
• 2024 年 11 月：发布 0.24 版本，新增 jj file annotate，相当于 git blame 或 hg annotate。
• 2024 年 9 月：Martin 在 Git Merge 2024 上做了关于 Jujutsu 的演讲。
• 2024 年 2 月：发布 0.14 版本，废弃了 “jj checkout” 和 “jj merge”，以及 jj init --git，后者现在称为 jj git init。
• 2023 年 10 月：发布 0.10.0 版本！现在包含适用于所有平台的捆绑合并和差异编辑器、“不可变修订集”以避免意外 edit 错误修订，以及大量改进。
• 2023 年 1 月：Martin 在 Git Merge 2022 上做了关于 Google 对 Jujutsu 计划的演讲！查看幻灯片或录像。

相关媒体

• 2024 年 3 月：Chris Krycho 开始制作关于 Jujutsu 的 YouTube 系列。
• 2024 年 2 月：Chris Krycho 发表了一篇关于 Jujutsu 的文章，名为 jj init，Steve Klabnik 随后发布了 [Jujutsu 教程][klabnik]。
• 2024 年 1 月：Jujutsu 在 LWN.net 的文章 Jujutsu: a new, Git-compatible version control system 中被介绍。
• 2023 年 1 月：Martin 关于 Jujutsu 在 Git Merge 2022 上的演讲，视频 及相关幻灯片。
  Wiki 上还有一个更广泛的媒体参考列表。

入门指南

Jujutsu 是一个实验性的版本控制系统。虽然 Git 兼容性是稳定的，且大多数开发者每天使用它满足所有需求，但仍可能存在进行中的功能、次优的用户体验和工作流程缺口，使其不适合您的特定用途。

请遵循安装说明获取并配置 jj。入门的最佳方式可能是完成教程。另请参阅 Git 比较，其中包含 jj 与 git 命令的对照表。

随着您对 Jujutsu 更加熟悉，以下资源可能有所帮助：

• 常见问题解答（FAQ）（https://docs.jj-vcs.dev/latest/FAQ）。
• 术语表（https://docs.jj-vcs.dev/latest/glossary）。
• jj help 命令（例如 jj help rebase）。
• jj help -k 命令（例如 jj help -k config）。使用 jj help --help 查看可用关键字。

如果您使用的是 prerelease（预发布）版本的 jj，您需要查阅预发布（main 分支）版本的文档（https://docs.jj-vcs.dev/prerelease/）。您也可以通过最新发布版本的文档，使用网站上的版本切换器访问该页面。版本切换器在您滚动到任何页面顶部时，在网站头部可见。

功能

与 Git 兼容

Jujutsu 的设计使得底层数据和存储模型是抽象的。目前，只有 Git 后端已准备好用于生产。Git 后端使用 gitoxide（https://github.com/Byron/gitoxide）Rust 库。

Git 后端功能齐全且维护良好，允许您将 Jujutsu 与任何 Git 远程仓库配合使用。您创建的提交将看起来像常规的 Git 提交。您可以从常规 Git 远程仓库获取分支，也可以将分支推送到远程仓库。您始终可以切换回 Git。

以下是如何使用 jj 探索 GitHub 仓库。您甚至可以拥有一个共置的本地工作区，在其中您可以交替使用 jj 和 git 命令。

工作副本自动提交

Jujutsu 使用一个真实的提交来表示工作副本。签出一个提交会在目标提交之上产生一个新的工作副本提交。几乎所有命令都会自动修订工作副本提交。

工作副本是一个提交意味着命令永远不会因为工作副本不干净而失败（没有“error: Your local changes to the following files…”），并且不需要 git stash。此外，因为工作副本是一个提交，命令在工作副本提交上的操作方式与在任何其他提交上相同，所以您可以在完成更改之前设置提交消息。

仓库是事实的来源

与 Git 相比，在 Jujutsu 中工作副本的作用较小。命令在开始前会快照工作副本，然后更新仓库，最后（如果工作副本提交被修改）更新工作副本。几乎所有命令（甚至是 checkout！）都对仓库中的提交进行操作，将快照和更新工作副本的常见功能留给集中的代码处理。例如，jj restore（类似于 git restore）可以从任何提交恢复到任何提交，jj describe 可以设置任何提交的提交消息（默认为工作副本提交）。

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

您在仓库中执行的所有操作都会被记录，连同操作后的仓库状态快照。这意味着您可以轻松恢复到早期的仓库状态，只需逐个撤销您的操作，甚至可以_撤销_一个特定的操作，该操作不一定是最新的。

冲突可以记录在提交中

如果一个操作导致冲突（https://docs.jj-vcs.dev/latest/glossary#conflict），关于这些冲突的信息将被记录在提交中。该操作将成功。您可以稍后解决这些冲突。

这种设计的一个结果是，不需要继续被中断的操作。相反，无论哪个命令导致了冲突，您都有一套统一的冲突解决工作流程。这种设计还使 Jujutsu 能够正确地变基合并提交（不像 Git 和 Mercurial 那样）。

基本的冲突解决：
操作冲突：

自动变基

每当您修改一个提交时，该提交的所有后代都将被变基到新提交上。得益于上述冲突设计，即使存在冲突也可以这样做。指向已变基提交的书签将被更新。如果工作副本指向已变基的提交，它也会被更新。

全面的历史重写支持

除了常规的变基命令外，还有 jj describe 用于编辑任意提交的描述（提交消息）。还有 jj diffedit，允许您在不签出提交的情况下编辑提交中的更改。要将一个提交拆分为两个，使用 jj split。您甚至可以使用 jj squash -i --from X --into Y 将提交中的部分更改移动到任何其他提交。

状态

该工具功能相当完善，但一些重要功能（如对 Git 子模块的支持）尚未完成。还存在一些性能 bug。很可能，与核心开发者不同的工作流程和设置得不到很好支持，例如，没有对基于电子邮件的工作流程的原生支持。

目前，所有核心开发者都使用 jj 来开发 jj。我（Martin von Zweigbergk）自 2021 年初以来几乎完全使用 jj 来开发项目本身。我没有从源重新克隆过（我想我甚至没有从备份恢复过）。在 1.0.0 版本之前，工作流程和磁盘上格式将会有向后不兼容的更改。对于任何格式更改，我们将尝试实施透明升级（就像我们最近所做的那样），或者在需要时提供升级命令或脚本。

相关工作

有多个工具试图解决与 Jujutsu 类似的问题。详情请参阅相关工作。

贡献指南

我们欢迎外部贡献，有很多事情可以做，所以不要害羞。如果您需要关于可以帮助的事项的指引，请提出问题，希望我们都能找到解决办法。我们确实有一些贡献者的政策和建议。简而言之：

• 非常欢迎错误报告！
• 每个进入 main 分支的提交都会经过代码审查。
• 请举止得体，遵守社区准则。
• 必须同意一份强制性的许可协议（CLA）。重要的是，它不会将版权所有权转让给 Google 或任何其他人；它只是赋予我们安全地重新分发和使用您更改的权利。