jj-vcs/jj

## 介绍 Jujutsu 是一个强大的 [version control system](https://en.wikipedia.org/wiki/Version_control)（版本控制系统），专为软件项目设计。你可以使用它来获取代码副本、跟踪代码变更，并最终发布这些变更供他人查看和使用。它从一开始就设计得易于使用——无论你是新手还是经验丰富的开发者，是独自开发全新项目，还是参与拥有庞大历史和团队的大规模软件项目。 Jujutsu 与大多数其他系统不同，因为在其内部，它将用户界面和版本控制算法与服务于内容的*存储系统*进行了抽象分离。这使其能够作为一种 VCS，适配多种可能的物理后端，这些后端可能拥有各自的数据或网络模型——例如 [Mercurial] 或 [Breezy]，或者是像 Google 基于云端的设计 [Piper/CitC] 这样的混合系统。 如今，我们使用 Git 仓库作为存储层来服务和跟踪内容，这使得它**目前与许多你喜欢的基于 Git 的工具兼容！** 然而，请注意，只有提交和文件存储在 Git 中；书签（分支）和其他高级元数据存储在 Git 之外的自定义存储中。所有核心开发者都在 GitHub 上使用 Jujutsu 来开发 Jujutsu。但它应该也能在你喜欢的 Git 托管平台上正常工作。 我们将来自其他版本控制系统的许多独特设计选择和概念整合到一个工具中。其中一些灵感来源包括： - **Git**：我们致力于 [保持快速][perf]——拥有流畅的 UX、高效的算法、正确的数据结构以及对细节的一丝不苟。默认存储后端使用 Git 仓库进行“物理存储”，以实现广泛的互操作性和易于上手。 - **Mercurial & Sapling**：有许多受 Mercurial 启发的功能，例如用于选择提交的 [revset] 语言。[没有显式的索引][no-index] 或暂存区。分支像 Mercurial 一样是“匿名的”，因此你不需要为每个小改动编造一个名称。重写历史的基本操作既强大又简单。输出格式化是通过一种健壮的模板语言完成的，用户可以对其进行配置。 - **Darcs**：Jujutsu 在其模型中将冲突作为 [一等对象][conflicts] 进行跟踪；它们与提交一样是一等的，而像 Git 这样的替代方案仅仅将冲突视为文本差异。虽然不像 Darcs（基于形式化的补丁理论，而非快照）那样严格，但其效果是许多形式的冲突解决可以自动执行和传播。 并且它增加了几个创新且有用的自有功能： - **工作副本即提交**：文件变更会被 [自动记录][wcc] 为普通提交，并在随后的每次更改中进行修正。这种“快照”设计简化了面向用户的数据模型（提交是唯一可见的对象），简化了内部算法，并完全涵盖了 Git 的 stash 或索引/暂存区等功能。 - **操作日志与撤销**：Jujutsu 记录在仓库上执行的每一个操作，从提交到拉取再到推送。这使得调试诸如“刚刚发生了什么？”或“我怎么走到这一步的？”之类的问题变得更加容易，*特别是*当你帮助同事回答关于他们仓库的这些问题时！因为所有内容都被记录下来，你可以轻松撤销刚才犯的错误。版本控制终于进入了 [20 世纪 60 年代][undo-history]！ - **自动变基与冲突解决**：当你修改一个提交时，每个后代提交都会自动变基到 freshly-modified 之上。这使得“基于补丁”的工作流变得轻而易举。如果你在提交中解决了冲突，该冲突的*解决方案*也会传播给后代。实际上，这是 `git rebase --update-refs` 结合 `git rerere` 的完全透明版本，且由设计原生支持。 - **安全、并发的复制**：你是否曾想将版本控制的仓库存储在 Dropbox 文件夹中？或者持续将仓库备份到 S3？不？嗯，现在你可以了！ 在典型的 Git/Mercurial 仓库上使用像 Dropbox 这样的文件系统和像 `rsync` 这样的备份工具的根本问题在于，它们依赖于*本地文件系统操作*相对于其他读写是原子、序列化且非并发的——这在分布式文件系统上操作时，或者在持有锁文件时发生并发文件复制（用于备份）等操作时是_不_成立的。 Jujutsu 的设计旨在 [在并发场景下保持安全][conc-safety]；简单地使用 rsync 或 Dropbox，然后使用生成的仓库，绝不应导致仓库处于*损坏状态*。最坏的情况_应该_只是它会暴露本地和远程状态之间的冲突，留待你解决。 命令行工具目前称为 `jj`，因为它易于输入且易于替换（这在英语中很少见）。该项目被称为“Jujutsu”（柔术），因为它与“jj”相匹配。 Jujutsu 相对年轻，仍有大量工作要做。如果你有任何问题，或想谈论未来计划，请加入我们的 Discord [](https://discord.gg/dkmfj3aGQN)，发起一个 [GitHub Discussion](https://github.com/jj-vcs/jj/discussions)，或向 [`#jujutsu` on Libera Chat](https://web.libera.chat/?channel=#jujutsu) 发送 IRC 消息。开发者们会监控所有这些渠道[^bridge]。 [^bridge]: 更准确地说，`#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"](CHANGELOG.md#0140---2024-02-07)，以及 `jj init --git`，现在直接称为 `jj git init`。 - **2023 年 10 月**：发布 0.10.0 版本！现在包含适用于所有平台的捆绑合并和差异编辑器，用于避免意外 `edit` 错误修订版本的“immutable revsets”，以及许多改进。 - **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 Tutorial][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 还包含更详尽的 [媒体参考资料列表][wiki-media]。 ## 入门指南 按照 [安装说明](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 时，以下资源可能会有所帮助： - [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` 查看可用的关键词。 如果你使用的是 `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 仓库的方式。 你甚至可以拥有一个 [并置本地工作区](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）。 基本冲突解决： 处理冲突： ### 自动变基 每当你修改一个提交时，旧提交的任何后代都将被变基到新提交上。多亏了上述冲突设计，即使存在冲突也可以执行此操作。指向变基提交的书签将被更新。如果工作副本指向变基提交，它也会被更新。 ### 全面的历史重写支持 除了常规的变基命令外，还有 `jj describe` 用于编辑任意提交的描述（提交消息）。还有 `jj diffedit`，它允许你在不检出的情况下编辑提交中的更改。要将提交拆分为两个，请使用 `jj split`。你甚至可以使用 `jj squash -i --from X --into Y` 将提交中的部分更改移动到任何其他提交。 ## 状态 该工具的功能已相当完善，但一些重要的功能（如对 Git submodules 的支持）尚未完成。还存在一些性能错误。很可能核心开发者未使用的工作流和设置没有得到很好的支持，例如，没有对基于电子邮件的工作流的原生支持。 如今，所有核心开发者都使用 `jj` 来开发 `jj`。我自 2021 年 1 月初几乎完全使用 `jj` 来开发该项目本身。我不必从源重新克隆（我认为我甚至不需要从备份恢复）。 在 1.0.0 版本之前，工作流程和磁盘格式_将_会有更改，且这些更改可能不向后兼容。对于任何格式更改，我们将尝试实施透明升级（正如我们在最近的更改中所做的那样），或者在需要时提供升级命令或脚本。 ## 相关工作 有几个工具正在尝试解决与 Jujutsu 类似的问题。有关详细信息，请参阅 [相关工作](https://docs.jj-vcs.dev/latest/related-work)。 ## 贡献 我们欢迎外部贡献，有很多事情可以做，所以不要害羞。如果你想获得关于可以帮助什么方面的指点，请提问，希望我们能共同找到方向。 我们确实为贡献者制定了 [一些政策和建议](https://docs.jj-vcs.dev/prerelease/contributing/)。大致的要点如下： - 非常欢迎错误报告！ - 每个进入 `main` 分支的提交都经过了代码审查。 - 请保持自律，并遵守社区准则。 - **确实**有一个你必须同意的强制性 CLA。重要的是，它**不**会将版权所有权转让给 Google 或任何其他人；它只是赋予我们安全地重新分发和使用你的更改的权利。 ### 强制性 Google 声明 我在 2019 年底作为业余项目启动了 Jujutsu，后来它演变成了我在 Google 的全职项目，现在有几名其他 Googler 以各种身份协助开发。 也就是说，虽然 Google 是主要贡献者之一，但这**不是受支持的 Google 产品**，即支持由社区提供。 ## 许可证 Jujutsu 作为开源软件提供，采用 Apache 2.0 许可证。有关版权和重新分发的详细信息，请参阅 [`LICENSE`](./LICENSE)。 `jj` logo 由 J. Jennings 贡献，并在知识共享许可下授权，请参阅 [`docs/images/LICENSE`](docs/images/LICENSE)。

标签：CLI, Git兼容, jj, Jujutsu, Mercurial, Rust, VCS, WiFi技术, 代码管理, 分布式版本控制, 协作开发, 可视化界面, 存储抽象, 开发效率, 源代码管理, 版本控制系统, 网络可观测性, 网络安全研究, 网络流量审计, 通知系统, 通知系统, 重构工具