jj 项目 Demos 指南用可复现脚本生成终端截图展示 Jujutsu 核心特性【免费下载链接】jjA Git-compatible VCS that is both simple and powerful项目地址: https://gitcode.com/GitHub_Trending/jj/jjdemos目录是 Jujutsujj项目随仓库自带的可复现演示与截图生成工具集。它以demo_*.sh脚本形式逐个演练jj的 Git 兼容、工作副本自动提交、操作日志与撤销、冲突解决等核心功能并通过run_scripts.sh在标准化环境中运行这些脚本、自动生成 SVG/PNG 图片供文档与主页展示。读完本篇你将掌握如何在自己的机器上重放这些演示、如何复现官方仓库中的终端截图以及每个演示脚本背后的jj命令调用链与设计意图。一、demos 目录里有什么先看一下目录构成demos/README.md 即本指南的说明文档demo_*.sh演示脚本每个脚本针对jj的一个特性运行后会在终端输出带 ANSI 颜色的命令回放demo_git_compat.sh演示jj与 Git 的兼容性克隆、书签跟踪、日志、diff、git format-patch兼容输出demo_working_copy.sh演示工作副本即提交working copy as a commit模型demo_operation_log.sh演示操作日志operation log与jj op revert/jj op restore/--at-opdemo_resolve_conflicts.sh演示冲突记录在提交中并在工作副本解决demo_juggle_conflicts.sh演示重新排序提交、制造冲突并验证顶提交无冲突的冲突传播特性。run_scripts.sh批量运行演示脚本并生成 SVG/PNG 的编排器。helpers.sh被各演示脚本source的公共工具函数new_tmp_dir、run_command、comment、blank等。setup_standard_config.sh为演示生成隔离的JJ_CONFIG与GIT_CONFIG_GLOBAL保证输出可复现。产物*.svg与*.png如git_compat.png、working_copy.png、operation_log.png、resolve_conflicts.png、juggle_conflicts.png其中 PNG 直接用于 README.md 特性章节配图。二、快速上手一条命令跑完所有演示run_scripts.sh可以接收任意数量的demo_*.sh作为参数。文档给出的推荐用法是把输出管道交给less边看边检查cd demos ./run_scripts.sh demo_*.sh |less对每个传入的脚本run_scripts.sh会依次完成三件事对应 run_scripts.sh以term-transcript capture捕获脚本在终端中的彩色输出生成script_base.svg如demo_git_compat.sh→git_compat.svg把捕获的原始输出通过tee同时回显到当前终端方便你直接观察演示过程若检测到 ImageMagick 的magick命令可用则进一步把 SVG 转换为 PNG。2.1 前置依赖term-transcript-cli必备。它是把 ANSI 终端输出渲染成 SVG 的工具。缺少时会报错并给出安装提示如cargo binstall term-transcript-cli。run_scripts.sh通过which term-transcript检查缺失时直接失败退出。ImageMagick 的magick可选仅用于生成 PNG。缺失时脚本会打印提示只有 SVG 会被生成但不会中断 SVG 流程。Inkscape在 Debian 类系统上推荐sudo apt install inkscape因为 ImageMagick 生成 PNG 时可能依赖 Inkscape 或其依赖库源码注释里也说明可以用 Inkscape 手工完成 SVG→PNG 转换。Fira Code 字体推荐sudo apt install fonts-firacode。默认在 Debian 上生成截图时使用 Fira Code未安装时回退到 Liberation Mono效果也可以再不行则按 CSS 字体栈回退到系统monospace。2.2 一条命令、两种产物每个演示脚本最终产出同名的.svg与.png两个文件二者的定位在文档中有明确说明PNG仓库中自带的 PNG 可能略微过时因为体积较大不便于频繁更新提交SVG差异diff是人类可读的、便于维护但不同机器因安装字体不同渲染可能略有差异。三、脚本如何保证可复现标准化环境3.1setup_standard_config.sh注入隔离配置演示的输出必须在不同机器上尽量一致为此 setup_standard_config.sh 为每次运行注入两份临时配置文件通过环境变量指向mktemp生成的临时文件不污染用户的真实配置# JJ_CONFIGjujutsu 用户配置 [user] name JJ Fan email jjfanexample.com [operation] hostname jujube username jjfan [ui] coloralways paginatenever log-word-wraptrue # 需要配合 COLUMNS 使用要点说明[user]固定作者身份保证提交元数据一致[operation]固定操作记录的 hostname 与 username保证操作日志渲染一致[ui] coloralways强制输出 ANSI 颜色终端截图必需paginatenever关闭分页避免交互卡住脚本log-word-wraptrue配合RUN_COMMAND_COLUMNS80实现日志换行。同时生成GIT_CONFIG_GLOBAL并设置[color] uialways确保底层 Git 命令如git log --graph也输出颜色与jj侧保持一致。3.2helpers.sh演示脚本的脚手架helpers.sh 提供四个关键函数new_tmp_dir用mktemp -d创建一次性临时目录并cd进入脚本退出时自动清理trap ... EXIT保证演示不污染用户环境run_command先回显$ 命令再以COLUMNS${RUN_COMMAND_COLUMNS:-80}执行命令。80 列是既定的换行宽度——term-transcript在 80 列处换行而 80 也恰好是移动设备上可读的最大宽度run_command_output_redacted执行命令但把真实输出替换成灰色提示... (output redacted) ...用于隐藏会破坏演示对仗的输出如工作副本描述的变更run_command_allow_broken_pipe把jj在管道破裂时的退出码 3 视为成功对应jj | head场景comment/blank输出绿色注释行与空行构成截图中的解说文案。从源码结构看run_scripts.sh之所以用RUN_COMMAND_COLUMNS而非COLUMNS是因为bash会重置$COLUMNS改用自定义变量后由helpers.sh中的run_command()解释从而稳定控制换行。四、各演示脚本详解命令调用链与设计意图4.1demo_git_compat.shGit 兼容性脚本核心流程demo_git_compat.shjj git clone https://github.com/octocat/Hello-World cd Hello-World jj bookmark list --all jj bookmark track octocat-patch-1 --remoteorigin jj log jj log -r all() jj diff -r b1 jj diff -r b3 jj show --git --template git_format_patch_email_headers git log --graph --all --decorate --oneline它演示的要点用jj git clone直接克隆 GitHub 仓库克隆后默认只为远程master创建本地书签master并跟踪远程分支其余远程分支仅以远程跟踪书签形式存在jj bookmark track octocat-patch-1 --remoteorigin把某个远程分支纳入本地跟踪默认jj log会排除未跟踪的远程分支聚焦我们自己的提交jj log -r all()则显示全部提交all()是 revset 表达式jj diff -r b1查看指定提交的差异jj show --git --template git_format_patch_email_headers生成与git format-patch兼容的补丁输出最后用原生git log --graph --all --decorate --oneline证明仓库底层就是真实的 Git 仓库Jujutsu 以 Git 仓库作为存储后端见 README.md 的 Compatible with Git 一节。4.2demo_working_copy.sh工作副本即提交该脚本用jj git clone进入 Hello-World 仓库然后依次演示demo_working_copy.sh初始时工作副本位于master之上、标记为(empty)修改README、新增new-file后jj status显示工作副本不再为空且其提交 ID以蓝色字符开头发生变化——因为工作副本本身就是一个提交每次快照都会生成新的提交 IDjj bookmark create goodbye为当前工作副本提交打上书签jj new master从 master 开出新的空提交原goodbye提交保留——无需git stash切换即干净jj describe -m可设置任意提交的描述不只是工作副本体现提交是唯一可见对象、工作副本并无特权的设计对应 README 中 The working copy is automatically committed 一节。4.3demo_operation_log.sh操作日志与撤销/恢复脚本先克隆并做一点清理随后执行demo_operation_log.shjj op log # 查看操作日志 echo stuff new-file jj describe -m stuff jj rebase --onto test jj new master jj describe -m other stuff jj op log --limit 4 rebase_op$(jj --colornever op log --no-graph -T id.short(5) --limit 1 --at-op --) jj op revert $rebase_op # 只撤销那次 rebase jj --at-op $rebase_op log # 查看 rebase 之后、后续操作之前的仓库状态 jj op restore $rebase_op # 恢复整个仓库到 rebase 之后的状态演示意图jj op log展示 Jujutsu 记录每一次操作快照、describe、rebase、new 等jj op revert op精确撤销某一次操作——示例中只回退了 rebase而后续的 other stuff 提交不受影响jj --at-op op log以只读方式查看某个历史时点的仓库视图jj op restore op则把整个仓库状态回滚到该操作之后对应 README 中 Entire repo is under version control 一节——整个仓库都在版本控制之下可以逐条撤销或定向恢复。4.4demo_resolve_conflicts.sh冲突的提交内记录与解决流程demo_resolve_conflicts.sh克隆后清理测试书签在工作副本修改READMEHello Earth!并 describejj rebase --onto b1——rebase 成功返回但提示产生冲突jj log/jj status显示冲突被记录在提交中工作副本的README呈现冲突标记内容直接echo Hello earth! README解决冲突jj status不再报告冲突。要点冲突不会导致操作失败而是作为提交的一部分被记录first-class conflict参见 README.md 的 Conflicts can be recorded in commits 一节与 docs/conflicts.md。无论哪个命令引发冲突都收敛到在提交里记录冲突、稍后统一解决这一条工作流无需git rebase --continue之类的中断续接机制。4.5demo_juggle_conflicts.sh冲突的腾挪这是最能体现 Jujutsu 冲突传播能力的演示demo_juggle_conflicts.sh先用jj debug init-simple在临时目录初始化一个简单后端仓库创建三个连续提交first/second/third都修改同一行文件jj rebase -s third --onto first与jj rebase -s second --onto third交换二、三提交的顺序——结果third 提交出现预期冲突而最顶上的提交没有冲突因为它聚合了三个提交的全部变更jj new second后cat file验证内容确为third的最终状态换个玩法让second与third成为兄弟提交并用jj new second third -m merged合并——合并提交同样因聚合了全部变更而无冲突。这个演示背后是 Jujutsu 将冲突作为一等对象建模的机制rebase 时冲突信息被携带并传播到后代提交当某个提交聚合了冲突各方的全部变更时冲突自动消失。这也是 Automatic rebase and conflict resolutionREADME.md中透明版的git rebase --update-refsgit rerere能力的直观体现底层实现可参考 lib/src/conflicts.rs、lib/src/merged_tree.rs 与 cli/src/commands/rebase.rs。五、run_scripts.sh生成图片的技术细节5.1 SVG 生成term-transcript capturerun_scripts.sh 中关键调用term-transcript capture \ --no-inputs --pure-svg --palette powershell \ --font Fira Code, Liberation Mono, SFMono-Regular, Consolas, Menlo \ --out $script_base.svg $script_base $outfile之所以用term-transcript capture而非term-transcript exec是为了能通过tee把脚本输出同时展示出来--palette powershell指定配色--font指定字体优先级列表——term-transcript的默认字体栈是SFMono-Regular, Consolas, Liberation Mono, Menlo脚本把经验证包含全部相关 Unicode 符号的 Fira Code 等字体排在前面脚本里有关于字体渲染的注释说明。5.2 PNG 生成magickSVG 默认按 1 SVG 单位 1 像素输出宽度 720 单位。转 PNG 时magick -background black $script_base.svg \ -type Palette -colors 63 -resize 100% \ $script_base.png-background black很关键SVG 用透明实现圆角若不指定背景透明区域默认会变成白色-type Palette -colors 63做调色板量化压缩-resize 100%目前是空操作改为-resize 700x10000可把宽度压到 700px 并保持宽高比脚本注释特别提醒PNG 透明与这里的操作顺序是反直觉的编辑时需小心并引用了 ImageMagick 的讨论线索。最终README.md中各个特性小节直接引用了这些产物图片demos/git_compat.png 用于 Compatible with Gitdemos/working_copy.png 用于 The working copy is automatically committeddemos/operation_log.png 用于 Entire repo is under version controldemos/resolve_conflicts.png 与 demos/juggle_conflicts.png 用于 Conflicts can be recorded in commits。六、字体与输出差异的注意事项文档明确提醒PNG 的最终渲染取决于本机安装的字体。官方截图通常在 Debian Linux 上生成使用 Fira Code 字体convert -list Fonts可以列出 ImageMagick 能识别到的所有字体。如果某台机器没有 Fira Code会退而使用 Liberation Mono也够用SVG 在网页上查看时则依赖 CSS 字体栈逐级回退。因此如果你在本地重新生成截图看到的字体渲染可能与仓库内置 PNG 略有不同——这是预期行为不必视为异常。七、小结这套 Demos 的价值demos/是一套自带文档的演示基础设施其价值在于可重放任何人在装好term-transcript 可选magick后都能一键复现与官方完全一致的演示输出可校验脚本中的每条命令都真实执行若某条jj命令行为变化导致输出异常脚本会以退出码或异常输出暴露问题配合set -euo pipefail即文档helpers.sh的comment()把解说词直接嵌入脚本截图本身就是图文并茂的教程而 README.md 又把这些截图作为特性说明的配图形成脚本 → 截图 → 文档的闭环。如果你想深入了解这些演示涉及的jj命令的完整参数可查阅 cli/docs/cli-reference.mdjj help的文本版与 cli/docs/tutorial.md入门教程想研究底层冲突机制可从 lib/src/conflicts.rs 与 docs/conflicts.md 入手。【免费下载链接】jjA Git-compatible VCS that is both simple and powerful项目地址: https://gitcode.com/GitHub_Trending/jj/jj创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考