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 是一款功能强大的版本控制系统 (https://zh.wikipedia.org/wiki/版本控制)，用于软件项目。你可以用它获取代码副本、跟踪代码变更，并最终将这些变更发布出去，供他人查看和使用。它从设计之初就致力于易用性——无论你是新手还是资深开发者，无论你是独自开发全新项目，还是参与具有庞大历史和团队规模的大型软件项目。 Jujutsu 与大多数其他系统不同，因为它在内部将用户界面和版本控制算法与用于提供内容的存储系统抽象分离。这使其能够成为一个支持多种物理后端的 VCS，这些后端可能拥有各自的数据或网络模型——如 [Mercurial] 或 [Breezy]，或像 Google 的云端设计 [Piper/CitC] 这样的混合系统。 [Mercurial]: https://www.mercurial-scm.org/ [Breezy]: https://www.breezy-vcs.org/ [Piper/CitC]: https://youtu.be/W71BTkUbdqE?t=645 目前，我们使用 Git 仓库作为存储层来提供和跟踪内容，这使其能够兼容许多你喜欢的基于 Git 的工具，就在现在！ 但请注意，只有提交（commit）和文件存储在 Git 中；书签（branch）和其他更高层次的元数据存储在 Git 之外的自定义存储中。 所有核心开发者都使用 Jujutsu 来开发 Jujutsu，就在 GitHub 上。但它也应该能与你喜欢的 Git 托管平台配合使用。 我们将许多来自其他版本控制系统的独特设计选择和概念整合到单一工具中。其中一些灵感来源包括： - Git：我们努力[追求速度][perf]——拥有敏捷的用户体验、高效的算法、正确的数据结构和传统的一丝不苟的细节关注。默认存储后端使用 Git 仓库作为“物理存储“，以实现广泛的互操作性和易于上手。 - Mercurial & Sapling：有许多受 Mercurial 启发的功能，例如用于选择提交的 [revset] 语言。[没有显式的索引][no-index]或暂存区。分支是“匿名“的，就像 Mercurial 一样，因此你不需要为每个小改动起名字。重写历史的原语强大而简洁。输出格式化通过健壮的模板语言完成，可由用户配置。 - Darcs：Jujutsu 在其模型中将冲突作为[一等对象][conflicts]来跟踪；它们与提交一样是一等公民，而像 Git 这样的替代品则仅仅将冲突视为文本差异。虽然不如 Darcs 等系统严谨（Darcs 基于形式化的补丁理论，而非快照），但其效果是许多形式的冲突解决可以自动执行和传播。 [perf]: https://github.com/jj-vcs/jj/discussions/49 [revset]: https://docs.jj-vcs.dev/latest/revsets/ [no-index]: https://docs.jj-vcs.dev/latest/git-comparison/#the-index [conflicts]: https://docs.jj-vcs.dev/latest/conflicts/ 它还添加了几项自身创新且实用的功能： - 工作副本即提交：文件变更会被[wcc]自动记录为普通提交，并在每次后续变更时被修正。这种“快照“设计简化了面向用户的数据模型（提交是唯一可见的对象），简化了内部算法，并完全涵盖了 Git 的 stash 或索引/暂存区等功能。 - 操作日志与撤销：Jujutsu 记录对仓库执行的每项操作，从提交、拉取到推送。这使得调试“刚才发生了什么？“或“我怎么到这个状态的？“等问题变得更加容易，尤其是当你帮同事解答他们仓库上的这些问题时！而且由于所有操作都被记录，你可以轻松撤销刚才犯的错误。版本控制终于进入了[1960 年代][undo-history]！ - 自动变基与冲突解决：当你修改一个提交时，该提交的所有后代都会自动变基到最新修改的版本之上。这让“基于补丁“的工作流程变得轻而易举。如果你在提交中解决了冲突，该冲突的解决方案也会传播到所有后代。实际上，这是 git rebase --update-refs 与 git rerere 的完全透明版本，由设计原生支持。 > [!WARNING] > 以下功能可用，但处于实验阶段；可能存在 bug、向后不兼容的存储变更，以及用户界面变更！ - 安全的并发复制：你是否曾希望将版本控制仓库放在 Dropbox 文件夹中？或者持续备份仓库到 S3？没有？好吧，现在你可以了！在 Dropbox 等文件系统或 rsync 等备份工具上操作典型的 Git/Mercurial 仓库的根本问题是，它们依赖本地文件系统操作的原子性、串行化和非并发性——而这在分布式文件系统上操作时，或在持有锁文件的同时发生并发文件复制（用于备份）等操作时，是不成立的。Jujutsu 的设计则[在并发场景下保持安全][conc-safety]；简单地使用 rsync 或 Dropbox，然后使用该仓库，永远不会导致仓库处于损坏状态。最糟糕的应该只是它会暴露本地和远程状态之间的冲突，留给你来解决。 [wcc]: https://docs.jj-vcs.dev/latest/working-copy/ [undo-history]: https://en.wikipedia.org/wiki/Undo#History [conc-safety]: https://docs.jj-vcs.dev/latest/technical/concurrency/ 命令行工具目前称为 jj，因为它容易输入也容易替换（在英语中很少见）。项目名为 “Jujutsu”，因为它匹配 “jj”。Jujutsu 相对年轻，仍有许多工作要做。如果你有任何问题，或想讨论未来计划，请加入我们的 Discord (https://discord.gg/dkmfj3aGQN)，发起 GitHub Discussion (https://github.com/jj-vcs/jj/discussions)，或在 Libera Chat 的 #jujutsu 频道发送 IRC 消息 (https://web.libera.chat/?channel=#jujutsu)。开发者会监控所有这些频道¹。 ¹: 更准确地说，#jujutsu Libera IRC 频道与 jj 的 Discord 上的一个频道桥接。部分开发者留在 Discord，通过桥接关注 IRC。 ### 新闻与更新 📣 - 2024 年 12 月：jj 仓库已迁移至 jj-vcs GitHub 组织。 - 2024 年 11 月：发布 0.24 版本，新增 jj file annotate，等同于 git blame 或 hg annotate。 - 2024 年 9 月：Martin 在 Git Merge 2024 上做了关于 Jujutsu 的[演讲][merge-vid-2024]。 - 2024 年 2 月：发布 0.14 版本，弃用了 “jj checkout” 和 “jj merge”，以及 jj init --git，现在改称为 jj git init。 - 2023 年 10 月：发布 0.10.0 版本！现在包含适用于所有平台的捆绑合并和差异编辑器，“不可变 revsets“以避免意外 edit 错误的修订版本，以及大量优化。 - 2023 年 1 月：Martin 在 Git Merge 2022 上做了关于 Google 对 Jujutsu 规划的演讲！请参阅[幻灯片][merge-slides]或[录像][merge-talk]。 ### 相关媒体 - 2024 年 3 月：Chris Krycho 开始了[关于 Jujutsu 的 YouTube 系列][krycho-yt]。 - 2024 年 2 月：Chris Krycho 发表了一篇关于 Jujutsu 的文章 [jj init][krycho]，Steve Klabnik 随后撰写了 [Jujutsu 教程][klabnik]。 - 2024 年 1 月：Jujutsu 在 LWN.net 的文章 [Jujutsu: a new, Git-compatible version control system][lwn] 中被专题报道。 - 2023 年 1 月：Martin 在 Git Merge 2022 上关于 Jujutsu 的演讲，[视频][merge-talk]和相关的[幻灯片][merge-slides]。 维基上还包含更详尽的[媒体引用][wiki-media]列表。 [krycho-yt]: https://www.youtube.com/playlist?list=PLelyiwKWHHAq01Pvmpf6x7J0y-yQpmtxp [krycho]: https://v5.chriskrycho.com/essays/jj-init/ [klabnik]: https://steveklabnik.github.io/jujutsu-tutorial/ [lwn]: https://lwn.net/Articles/958468/ [merge-talk]: https://www.youtube.com/watch?v=bx_LGilOuE4 [merge-slides]: https://docs.google.com/presentation/d/1F8j9_UOOSGUN9MvHxPZX_L4bQ9NMcYOp1isn17kTC_M/view [merge-vid-2024]: https://www.youtube.com/watch?v=LV0JzI8IcCY [wiki-media]: https://github.com/jj-vcs/jj/wiki/Media ## 快速入门 > [!IMPORTANT] > Jujutsu 是一款实验性版本控制系统。虽然 Git 兼容性稳定，且大多数开发者日常用于所有需求，但仍可能存在进行中的功能、次优的用户体验和工作流缺口，使其无法满足你的特定使用场景。 按照安装说明 (https://docs.jj-vcs.dev/latest/install-and-setup) 获取和配置 jj。 入门的最佳方式可能是通读教程 (https://docs.jj-vcs.dev/latest/tutorial)。 另请参阅 Git 对比 (https://docs.jj-vcs.dev/latest/git-comparison)，其中包含 jj 与 git 命令的对照表。 随着你对 Jujutsu 越来越熟悉，以下资源可能会有所帮助： - 常见问题 (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 查看可用的关键词 如果你使用的是 jj 的预发布版本，你可能需要查阅预发布（main 分支）版本的文档 (https://docs.jj-vcs.dev/prerelease/)。你也可以从最新发布版本的文档通过网站的版本切换器进入。版本切换器位于网站页面顶部滚动后的标题栏中。 ## 功能特性 ### 兼容 Git Jujutsu 的设计使其底层数据和存储模型具有抽象性。目前，只有 Git 后端达到生产就绪状态。Git 后端使用 gitoxide (https://github.com/Byron/gitoxide) Rust 库。 [backends]: https://docs.jj-vcs.dev/latest/glossary#backend Git 后端功能完整且持续维护，允许你将 Jujutsu 与任何 Git 远程仓库配合使用。你创建的提交看起来就像普通的 Git 提交。你可以从普通 Git 远程仓库获取分支，也可以向远程推送分支。你随时可以切换回 Git。 以下是如何使用 jj 探索 GitHub 仓库的方法。你甚至可以拥有共存的本地工作区 (https://docs.jj-vcs.dev/latest/git-compatibility#colocated-jujutsugit-repos)，在其中可以交替使用 jj 和 git 命令。 ### 工作副本自动提交 Jujutsu 使用真实提交来表示工作副本。检出提交会在目标提交之上生成一个新的工作副本提交。几乎所有命令都会自动修正工作副本提交。 工作副本即提交意味着命令永远不会因为工作副本“脏“而失败（不会出现“error: Your local changes to the following files…”），也不需要 git stash。此外，由于工作副本是一个提交，命令对工作副本提交和其他任何提交的作用方式相同，因此你可以在变更完成前设置提交信息。 ### 仓库是真相来源 在 Jujutsu 中，工作副本的作用比 Git 更小。命令在执行前会快照工作副本，然后更新仓库，最后更新工作副本（如果工作副本提交被修改）。几乎所有命令（甚至包括 checkout！）都作用于仓库中的提交，将快照和更新工作副本的通用功能留给集中式代码处理。 例如，jj restore（类似于 git restore）可以从任何提交恢复到任何提交，jj describe 可以设置任何提交的提交信息（默认为工作副本提交）。 ### 整个仓库处于版本控制之下 你在仓库中执行的所有操作都会被记录，同时记录操作后仓库状态的快照。这意味着你可以轻松恢复到早期的仓库状态，简单地逐个撤销操作，甚至还原某个不一定是最近的操作。 ### 冲突可记录在提交中 如果操作产生冲突 (https://docs.jj-vcs.dev/latest/glossary#conflict)，有关这些冲突的信息将记录在提交中。操作会成功完成。你可以稍后解决冲突。 这种设计的一个后果是不需要继续中断的操作。相反，你获得了一个统一的冲突解决工作流，无论哪个命令导致了冲突。这种设计还让 Jujutsu 能够正确变基合并提交（Git 和 Mercurial 都做不到）。 基本冲突解决： 处理冲突： ### 自动变基 每当你修改一个提交，旧提交的任何后代都会自动变基到新提交上。得益于上述冲突设计，即使存在冲突也能完成。指向已变基提交的书签会被更新。如果工作副本指向已变基提交，它也会被更新。 ### 全面的历史重写支持 除了常规的 rebase 命令外，还有 jj describe 用于编辑任意提交的描述（提交信息）。还有 jj diffedit，让你无需检出即可编辑提交中的变更。要将提交拆分为两个，使用 jj split。你甚至可以使用 jj squash -i --from X --into Y 将提交中的部分变更移动到任何其他提交。 ## 状态 该工具功能相当完整，但一些重要功能如 Git 子模块支持尚未完成。也存在若干性能问题。与核心开发者不同的工作流和配置可能支持不佳，例如没有原生的邮件工作流支持。 目前，所有核心开发者都使用 jj 来开发 jj。我（Martin von Zweigbergk）自 2021 年 1 月初以来几乎只使用 jj 开发本项目。我不需要从源代码重新克隆（我认为我甚至不需要从备份恢复）。 在 1.0.0 版本之前，将会有工作流变更和磁盘格式的向后不兼容变更。对于任何格式变更，我们将尝试实现透明升级（如近期的变更所做的），或根据请求提供升级命令或脚本。 ## 相关工作 有多个工具试图解决与 Jujutsu 类似的问题。详情请参见相关项目 (https://docs.jj-vcs.dev/latest/related-work)。 ## 贡献指南 我们欢迎外部贡献，而且有很多事情可以做，所以不要害羞。如果你想知道可以帮忙做什么，请尽管询问，希望我们能一起找出方向。 我们确实有一些政策建议 (https://docs.jj-vcs.dev/prerelease/contributing/) 供贡献者参考。简要的 TL;DR： - 非常欢迎提交 bug 报告！ - 进入 main 分支的每个提交都会经过代码审查。 - 请自律，遵守社区准则。 - 有你必须同意的强制性 CLA。重要的是，它不会将版权所有权转让给 Google 或任何其他方；它只是赋予我们安全地重新分发和使用你变更的权利。