jj-vcs

Jujutsu（jj）版本控制系统

Jujutsu 是新一代版本控制系统，它使用 Git 仓库作为存储，同时提供截然不同且更强大的用户体验。本技能包含 jj 仓库中的完整官方文档。

快速入门： 阅读 tutorial.md，通过实践了解基本用法。Git 用户迁移到 jj 时，请参阅 git-comparison.md。

什么是 Jujutsu？

Jujutsu（命令：jj）是一款 VCS，旨在让新手和经验丰富的用户都能轻松使用。其主要创新包括：

• 工作副本即提交：更改会自动记录为提交，并在每次更改时自动修订
• 操作日志与撤销：每次操作都会被记录，且可以撤销（就像为版本控制本身提供版本控制！）
• 自动变基：修改提交时，其后代会自动变基
• 一等冲突：冲突会作为对象进行跟踪，可以提交、稍后解决，并向下传播
• 无需暂存区：无需处理 Git 索引和暂存区的复杂性，工作流更加简单
• 兼容 Git：可与现有 Git 仓库以及 GitHub 等代码托管平台配合使用

文档结构

开始使用

• README.md - 项目概述、主要功能和简介
• index.md - 文档主页及实用链接
• install-and-setup.md - 所有平台的安装说明和初始配置
• tutorial.md - 全面的实践教程（假定读者了解 Git）
• FAQ.md - 常见问题和常见故障
• glossary.md - jj 专有术语定义

核心概念

• working-copy.md - 工作副本如何作为提交运作
• operation-log.md - 了解操作日志和撤销功能
• conflicts.md - jj 如何将合并冲突作为一等对象处理
• revsets.md - 用于选择修订版本的强大语言（类似 Mercurial 的 revsets）
• templates.md - 使用模板语言自定义输出格式
• bookmarks.md - 使用书签（类似 Git 分支）
• filesets.md - 用于选择文件的语言

配置

• config.md - 完整的配置参考和选项
• config.toml - 配置文件示例
• cli-reference.md - 命令行界面参考

Git 集成

• git-compatibility.md - jj 如何与 Git 仓库和 Git 功能配合使用
• git-comparison.md - jj 与 Git 的工作流和命令对比
• git-command-table.md - Git 命令与 jj 对应命令的速查表
• github.md - 使用 GitHub 仓库和拉取请求
• gerrit.md - 使用 Gerrit 代码审查系统

指南

• guides/divergence.md - 了解并解决变更分歧
• guides/multiple-remotes.md - 使用多个远程仓库

技术文档

• technical/architecture.md - 高层架构和设计决策
• technical/concurrency.md - jj 如何安全地处理并发操作
• technical/conflicts.md - 冲突处理的技术细节

开发与贡献

• contributing.md - 如何为 jj 开发作出贡献
• code-of-conduct.md - 社区行为准则
• core_tenets.md - 指导 jj 设计的核心原则
• roadmap.md - 开发路线图和计划中的功能
• community_tools.md - 社区维护的工具和集成
• releasing.md - 发布流程文档
• design_docs.md - 设计文档索引
• design_doc_blueprint.md - 编写设计文档的模板

对比与背景

• sapling-comparison.md - 与 Meta 的 Sapling VCS 对比
• related-work.md - 其他相关版本控制系统
• testimonials.md - 用户评价和使用体验

特定平台

• windows.md - Windows 平台的注意事项和设置

项目信息

• CHANGELOG.md - 版本历史和发行说明
• GOVERNANCE.md - 项目治理结构
• SECURITY.md - 安全政策和问题报告

常见使用模式

当用户要求：

• 开始使用 jj → 查看 tutorial.md 和 install-and-setup.md
• 从 Git 迁移 → 查看 git-comparison.md 和 git-command-table.md
• 理解概念 → 查看 glossary.md 和相关概念文档（working-copy、conflicts 等）
• 配置 jj → 查看 config.md
• 使用 GitHub → 查看 github.md
• 选择修订版本 → 查看 revsets.md
• 自定义输出 → 查看 templates.md
• 处理冲突 → 查看 conflicts.md
• 排查问题 → 查看 FAQ.md
• 撤销错误操作 → 查看 operation-log.md
• 了解架构 → 查看 technical/architecture.md

快速命令参考

基本操作

# Clone a Git repository
jj git clone <url>

# Check status
jj st  # or jj status

# Create a new change
jj new

# Edit a change description
jj describe

# Show change log
jj log

# Undo last operation
jj undo

# Show operation log
jj op log

使用更改

# Abandon a change
jj abandon

# Move changes between commits
jj squash  # move changes into parent
jj move    # move changes to another commit

# Rebase changes
jj rebase -r <revision> -d <destination>

# Resolve conflicts
jj resolve  # interactive conflict resolution

Git 集成

# Fetch from Git remote
jj git fetch

# Push to Git remote
jj git push

# Import Git branches as bookmarks
jj bookmark track <name>@<remote>

选择修订版本（Revsets）

# Common revset expressions
@              # working copy commit
@-             # parent of working copy
main@origin    # bookmark from remote
::@            # ancestors of working copy
@::            # descendants of working copy
~empty()       # non-empty changes

需要理解的关键概念

工作副本即提交

• 工作副本始终是一个提交（显示为 @）
• 工作期间，更改会自动提交
• 无需显式使用 commit 命令（使用 jj describe 添加说明）
• 使用 jj new 开始新的更改

Revsets

• 用于选择提交的强大语言（类似于 Mercurial）
• 许多命令都会用到：jj log -r、jj show、jj rebase 等
• 支持布尔运算、函数和组合
• 完整参考请参阅 revsets.md

操作日志

• 每个 jj 操作都会被记录（提交、变基、推送等）
• 使用 jj op log 查看操作历史
• 使用 jj undo 撤销上一个操作
• 使用 jj op restore 恢复到任意之前的状态

书签与分支

• jj 使用“书签”，与 Git 分支类似，但更简单
• 更改可以不关联书签而存在（匿名分支）
• 书签只是指针，并非工作流所必需
• Git 分支会作为书签导入

冲突

• 冲突存储在提交中，而不仅仅是在工作副本中
• 可以提交存在冲突的更改，之后再解决
• 冲突解决结果会通过变基传播
• 使用 jj resolve 以交互方式解决冲突

文件组织

• README.md - 项目主 README，包含概览
• docs/ - 所有文档文件
  • tutorial.md - 入门教程
  • config.md - 配置参考
  • revsets.md - Revset 语言参考
  • templates.md - 模板语言参考
  • git-*.md - Git 集成文档
  • guides/ - 特定工作流的操作指南
  • technical/ - 技术架构文档
  • design/ - 功能设计文档

提示

• 从教程开始，了解 jj 的思维模型
• 使用 jj help <command> 查看详细的命令帮助
• 操作日志是你的安全网——放心尝试
• Revsets 功能强大——学会使用它们，提高工作效率
• 冲突很常见，可以轻松处理
• 充分运用 jj 的理念（工作副本即提交、自动变基），效果最佳
• 遇到意外行为时，请查看 FAQ
• 使用模板按个人偏好自定义 jj log 的输出

重要说明

• Jujutsu 仍处于实验阶段，但正在积极开发，开发者也在日常使用
• Git 兼容性稳定，可安全用于现有 Git 工作流
• 某些功能仍处于实验阶段（请查看 README 中的警告）
• 可能会有破坏性变更，但都会记录在 CHANGELOG 中
• 社区在 Discord、GitHub Discussions 和 IRC（Libera Chat 上的 #jujutsu）活跃

资源

• 主页：https://jj-vcs.github.io/jj
• GitHub：https://github.com/jj-vcs/jj
• Discord：https://discord.gg/dkmfj3aGQN
• 文档：https://jj-vcs.github.io/jj/latest/
• Steve Klabnik 编写的教程：https://steveklabnik.github.io/jujutsu-tutorial/
• Chris Krycho 的 YouTube 系列：https://www.youtube.com/playlist?list=PLelyiwKWHHAq01Pvmpf6x7J0y-yQpmtxp