LearnGitBranching 源码解析交互式 Git 可视化教学应用的沙盒、关卡与构建体系【免费下载链接】learnGitBranchingAn interactive git visualization and tutorial. Aspiring students of git can use this app to educate and challenge themselves towards mastery of git!项目地址: https://gitcode.com/gh_mirrors/le/learnGitBranching导读LearnGitBranching下称 LGB是一个交互式 Git 仓库可视化、沙盒练习与系列化教学关卡集成的开源应用命令输入后旁边的提交树会实时更新以反映每条命令的效果。本文以仓库根目录的 README.md 为核心骨架结合 src/js/commands/index.js、src/js/git/index.js、src/js/git/commands.js、src/js/sandbox/commands.js、src/levels/index.js、gulpfile.js 等源码与配置文件系统讲解沙盒模式、关卡体系、永久链接分享、关卡构建器、Bug 复现辅助以及本地构建与 Docker 部署的完整方法。读完本文你将掌握 LGB 的功能全貌并能从命令解析、可视化引擎、关卡数据格式到构建流程的层面理解其工作原理。LGB 是什么用可视化弥补命令行缺失的所见即所得README 开篇即定义了项目定位LGB 是一个 git 仓库可视化器、沙盒以及一系列教育性教程与挑战a git repository visualizer, sandbox, and a series of educational tutorials and challenges。其核心价值在于借助可视化帮助开发者理解 Git——这是命令行交互方式所天然缺失的能力。这种可视化通过游戏化关卡来实现针对不同的 git 命令设计对应关卡玩家通过输入命令驱动提交树演进逐步熟悉各命令的行为。技术形态上README 明确强调这是一个100% 纯客户端应用没有后端数据库没有任何 AJAX 请求生产版本github.io 上托管仅仅是一个 HTML 页面加上若干 JS 与 CSS 文件。这一点在 package.json 的依赖列表中得到印证——全部依赖backbone、flux、jquery、raphael、react、react-dom、underscore、marked、q 等都是浏览器端库没有任何服务端框架或数据库驱动。Sandbox 沙盒模式自由试验的游乐场应用默认以sandbox mode沙盒模式启动并已预置一个基础仓库。在沙盒里你可以随意输入命令、任意折腾仓库状态。README 特别提示三个高频命令undo撤销上一条命令的效果reset以干净状态重新开始在关卡中也同样生效git clone模拟远程仓库从而练习 push / pull / fetch 等分布式操作。从源码看这些命令分属两条解析链路。undo、reset、sandbox、levels、import tree等是沙盒级命令它们的正则定义集中在 src/js/sandbox/commands.js 的regexMap中例如undo: /^undo($|\s)/、reset: /^reset( --forSolution)?$/而git clone、git commit等则是版本控制命令由 src/js/git/commands.js 的commandConfig注册。沙盒命令里还包含一批即时命令instantCommands例如locale zh_CN切换界面语言、flip翻转提交树视角、alias foogit commit自定义别名、echo hello输出文本等详见同一文件的 L18-L148。git clone的实现尤其值得关注在 src/js/git/commands.js 中它调用engine.makeOrigin(engine.printTree())把当前仓库的完整树状态复制出一份作为远程仓库origin。而 src/js/git/index.js 的makeOrigin会为远程仓库中的每个分支在本地生成对应的o/前缀追踪分支并建立本地分支对远程分支的追踪关系setLocalToTrackRemote。这意味着你在沙盒里跑git clone之后git remote、git fetch、git pull、git push、git fakeTeamwork等远程命令全部可以真实演练。Levels 关卡体系从基础到远程仓库的完整学习路径关卡总览与导航在沙盒或应用中输入levels即可看到全部课程/挑战列表以及已通关的关卡。README 说明每个关卡序列series都致力于讲解某个高阶 Git 概念界面中的多个标签页按信息领域切分世界例如远程仓库与本地仓库分属不同标签页。关卡序列的实际定义位于 src/levels/index.js共 8 个序列、30 余个关卡按顺序递进序列 key关卡内容示例主题introcommits、branching、merging、rebasing循序渐进地介绍 Git 主要命令rampupdetachedHead、relativeRefs、reversingChanges指针操作与撤销movecherryPick、interactiveRebase移动提交记录mixedgrabbingOneCommit、jugglingCommits、tags、describeGit 技术、技巧与贴士大集合advancedmanyRebases、multipleParents、selectiveRebase高级话题remoteclone、fetch、pull、push、fakeTeamwork 等Push Pull——Git 远程仓库remoteAdvancedpushManyFeatures、mergeManyFeatures、tracking、fetchArgs、pullArgs 等origin 及其周边的进阶操作每个序列还带有多语言displayName与about描述见 src/levels/index.js界面会据此渲染标签页标题。关卡文件的数据格式一个关卡就是一个 JS 文件导出exports.level对象。以第一个关卡 src/levels/intro/commits.js 为例其核心字段包括name多语言关卡名startTree起始提交树例如{branches:{main:{target:C1,id:main}},commits:{...},HEAD:{target:main,id:HEAD}}其中C0为根提交C1是其后继提交goalTreeString目标提交树用于判定玩家是否过关solutionCommand参考答案如git commit;git commithint多语言提示disabledMap本关卡禁用的命令如{git revert: true}startDialog多语言开场教程包含ModalAlert图文讲解与GitDemonstrationView可播放的演示如先展示git commit的执行效果再让玩家动手两类子视图。这种起始树 目标树的结构意味着过关判定本质上是树的等价比较——引擎执行完玩家命令后将当前树与goalTreeString做比较匹配即通关。Git Golf比拼命令数量的趣味机制README 提到一个有趣的 git golf 概念系统会记录你通关每个关卡用了多少条命令鼓励玩家挑战官方纪录。对应源码是 src/js/commands/index.js 的getCommandsThatCount——它会遍历所有命令配置跳过带dontCountForGolf: true标记的命令例如 src/js/git/commands.js 中的git add、git log、git show、git rev-list均不计数其余命令每执行一条就计入高尔夫计数。因此想拿到低分就要用尽可能少的有效命令完成目标树。分享永久链接Permalinks把任意命令序列打包进 URLREADME 提供了两种分享玩法其机制都来自 URL 参数command参数把一组命令放在 URL 中页面加载时自动按序执行。例如?NODEMOcommandecho hello; git commit其中;用于串联多条命令。注意参数值需要进行 URL 编码引号、空格与分号会被转义。NODEMO参数用于跳过开场的介绍对话框让分享链接直达演示状态适合配合command参数使用。另外还有一条由关卡构建器延伸出的分享链路?gist_level_idgist的ID——把构建好的关卡 JSON 存成 gist 后把 gist ID 放进 URL 参数朋友打开链接即可直接加载该自定义关卡。Level Builder在浏览器里可视化地构造关卡在沙盒中输入build level即可打开关卡构建器对话框。README 描述了这个交互流程对话框会一步步引导你完成关卡设计结束时弹出一段代表该关卡的JSON 数据。你可以把 JSON 粘贴到 gist 或 issue 中提交给维护者审核合并让朋友执行import level命令把 JSON 粘贴进弹出的输入框直接导入该关卡通过gist_level_id参数生成自定义分享链接。从源码看build level与import level都被注册在 src/js/sandbox/commands.js 的regexMap中/^build level\s?([a-zA-Z0-9]*)$/、/^import level$/且该文件通过getOptimisticLevelBuilderParse预解析了构建器专用命令对应 src/js/level/builder.js 的regexMap使得level intro1; show goal这类命令串不会被误报错。关卡 JSON 与关卡文件字段起始树、目标树、提示、多语言文案等一一对应因此用import level导入的数据与仓库内置关卡在数据结构上是同构的。报告 Bug 的辅助技巧debug_copyTree 与 importTreeNowREADME 针对 Bug 复现给出了非常实用的建议在复现 Bug 前先在 JS 控制台执行debug_copyTree()它会弹出窗口并复制当前提交树的完整状态字符串省去手动抄录全部命令的麻烦维护者拿到该字符串后用importTreeNow命令即可精准还原到那一时刻的仓库状态。对应到源码src/js/git/index.js 的printTree/printAndCopyTree实现了树的序列化导出exportTree会把分支、提交、标签、HEAD 以及可选的远程树originTree全部扁平化为 JSONimportTreeNow则调用loadTreeFromString做逆向恢复。日常使用中沙盒里直接输入import tree并按提示粘贴树字符串也能达到同样效果export tree则用于导出当前树。自行构建与二次开发从 clone 到打开浏览器标准构建工作流README 给出的开发工作流如下命令保持原样可执行git clone your fork of the repo cd learnGitBranching yarn install git checkout -b newAwesomeFeature vim ./src/js/git/index.js # 修改代码 yarn gulp fastBuild # 跳过测试与 lint快速构建 # 构建完成后打开仓库根目录的 index.html open ./index.html vim ./src/js/git/index.js # 继续修改 yarn gulp build # 运行测试与 lint git commit -am My new sweet feature! git push # 提交 Pull Request其中yarn install用于下载全部依赖依赖清单见 package.jsonyarn gulp fastBuild对应 gulpfile.js 的fastBuild series(clean, ifyBuild, style, buildIndex, jshint)——依次执行清理构建目录、打包 JS、合并压缩样式、生成index.html、运行 jshintyarn gulp build对应 L280-L285 的完整build任务额外包含生产压缩terser cleanCSS、git add build/、Jasmine 单元测试与国际化字符串检查。仓库也保留了npm test即gulp test→ jasmine 测试与npm run devvite 开发服务器配置见 vite.config.js两条快捷入口。快速构建 vs 生产构建构建核心逻辑在 gulpfile.js所有src/**/*.js与src/**/*.jsx经 browserify babelifyReact preset打包为单一bundle.js见getBundleL123-L133所有样式经 gulp-concat 合并为main.cssstyleL167-L177生产模式下 CSS 与 JS 文件会被gulp-hash 加上内容哈希用于缓存失效HTML 模板 src/template.index.html 中的占位符会被替换为带哈希的文件名buildIndexL72-L121最终在仓库根目录生成index.html若NODE_ENVproduction输出 HTML 还会被 html-minifier 压缩。因此 README 的结论是本地构建后只需直接打开根目录的index.html即可运行整个应用——无需任何服务器。Docker 方式README 提供了两条 Docker 命令# 运行最近构建的稳定镜像 docker run -p 8080:80 ghcr.io/pcottle/learngitbranching:main # 本地构建应用并打包镜像 docker build -t ghcr.io/pcottle/learngitbranching:latest启动后通过http://localhost:8080/访问。仓库 Dockerfile 采用多阶段构建先用node:14.20.0-alpine3.16执行yarn install与yarn gulp build生成产物再通过scratch导出阶段复制index.html与build/目录最终放入nginx:stable-alpine镜像由 nginx 托管。Makefile 还封装了基于 Docker 的build容器内跑 yarn 与 gulp、build_docker打多个 tag 并导出产物目录、run映射 8080 端口等目标可直接make run一键启动。命令体系源码深潜一条 git 命令是如何被执行的理解 LGB 的关键在于其命令解析与执行链路这也是扩展新命令时最需要掌握的模块。第一层命令解析src/js/commands/index.js 的parse函数维护了一个git/hg双命名空间的regexMap由getRegexMap从各命令配置中提取regex字段生成。它依次尝试用每条命令的正则匹配输入字符串匹配成功后用str.match(/(.*?|.*?|\S)/g).slice(2)剥离出VCS 名 命令名之后的参数即 generalArgs 与选项交由CommandOptionParserL163-L205解析以-开头的 token 视为选项对照supportedMap校验合法性非法选项会抛出option-not-supported错误并就近吸收下一个非选项 token 作为该选项的值其余 token 归入 generalArgs。所有 git 命令的正则与选项表集中在 src/js/git/commands.js 的commandConfig。例如commit命令L126-L188支持--amend、-a、--all、-am、-m等选项执行时会对-am/-m校验参数个数恰好为 1并限制-am与-a/-m不能混用branch命令L445-L525支持-d/-D删除、-u设置追踪、-f/--force强制移动、-a/-r列出全部分支/远程分支、--contains反查包含某提交的分支fetchL390-L443与pullL227-L304支持--force、--rebase以及source:destination冒号 refspec 写法resetL538-L571支持--hard/--soft其中--soft会被拒绝并提示暂存区概念在沙盒中未建模rebaseL690 起支持-i交互式、--onto、--solution-ordering等。第二层执行与动画解析结果会触发processGitCommand事件由 src/js/git/index.js 中GitEngine的dispatch接管。GitEngine 是可视化引擎的大脑持有commitCollection、branchCollection、tagCollection、HEAD引用以及克隆后origin引擎核心状态与操作包括commit()在当前 HEAD 指向的位置创建新提交由makeCommit生成全局唯一 ID 如C2merge/rebase/cherrypick/revert重写提交图fetchL1229-L1275与pushL1061-L1200先通过getTargetGraphDifferenceL972-L1059计算本地与远程之间的提交差集并按依赖拓扑顺序逐个在目标引擎中重放提交配合动画工厂playCommitBirthPromiseAnimation依次展示每个提交诞生的过程makeOriginclone 时的远程引擎创建逻辑会自动为远程各分支生成o/追踪分支exportTree/loadTree提交树的序列化与反序列化是关卡起始树、目标树判定与import tree的底层支撑。所有命令执行完毕后动画队列AnimationQueue驱动 src/js/visuals/ 目录下的可视化组件visNode、visBranch、visEdge、visTag、visBase 等基于 raphael 绘制刷新提交树玩家得以看见每条命令的真实效果。可扩展性hg 与双 VCS 支持值得注意 src/js/commands/index.js 中commandConfigs {git: GitCommands.commandConfig, hg: MercurialCommands.commandConfig}——LGB 不止支持 git还通过同一套解析器支持了 mercurialhg命令配置见 src/js/mercurial/commands.js。GitEngine 的handleModeChange/setModesrc/js/git/index.js负责在切换 VCS 时做树结构适配与垃圾回收。这意味着新增 VCS 只需实现同构的commandConfig并注册即可。工程质量测试、国际化与文档生成单元测试tests/ 目录下以 Jasmine 编写了大量规格测试覆盖命令解析git.spec.js、远程操作remote.spec.js、simpleRemote.spec.js、树比较treeCompare.spec.js、动画animation.spec.js、各类 StoreCommandLineStore.spec.js、GlobalStateStore.spec.js、LevelStore.spec.js、LocaleStore.spec.js等。构建任务build会强制运行 jasmine测试不通过即构建失败。国际化src/js/intl/ 实现多语言字符串管理gulpfile.js 的lintStrings会运行node src/js/intl/checkStrings校验翻译完整性界面语言可用locale 语言码命令切换。关卡文档自动生成gulp 提供generateLevelDocs任务gulpfile.js遍历 src/levels/index.js 的所有序列与关卡把startDialog中的 Markdown 讲解与GitDemonstrationView演示命令渲染为 generatedDocs/levels.html实现关卡内容文档化。总结一个适合读源码学 Git的迷你教科书从用户视角LGB 是沙盒、关卡、关卡构建器、永久链接分享四件套的组合从开发者视角它又是一个结构清晰、无后端依赖、测试完备的纯前端应用——命令解析器src/js/commands/index.js、Git 引擎src/js/git/index.js、关卡数据src/levels/与构建管线gulpfile.js各自职责单一、边界分明。无论你是想练习 Git 命令、为教学团队搭建可视化演示还是打算阅读或扩展一个中型 React Backbone Flux 应用LGB 都是一个值得把玩与研读的范本。进一步的贡献规范可参阅 CONTRIBUTING.md。【免费下载链接】learnGitBranchingAn interactive git visualization and tutorial. Aspiring students of git can use this app to educate and challenge themselves towards mastery of git!项目地址: https://gitcode.com/gh_mirrors/le/learnGitBranching创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考