al-folio 如何用 upgrade CLI 跟踪本地 override 与插件 gem 更新的漂移【免费下载链接】al-folioA beautiful, simple, clean, and responsive Jekyll theme for academics项目地址: https://gitcode.com/GitHub_Trending/al/al-folioal-folio 的 v1.x 站点是一个薄 starterlayouts、includes 和核心资产都由al_folio_core等al_*插件 gem 提供而你的站点仓库仍然可以保留同路径的本地 override例如_layouts/bib.liquid、_includes/repository/repo.liquid来覆盖 gem 里的文件。问题在于当 gem 更新了自己拥有的上游文件时Git 不会为你的本地副本产生任何冲突——本地副本遮蔽了 gem 文件更新悄无声息地发生。al_folio_upgrade这个 upgrade CLI 就是用来把这个缺失的审查信号补回来的它记录你审查过的上游文件校验和在你下次bundle update之后告诉你哪些本地 override 的上游已经变了。适用前提基于 v1.x starter 创建的站点保留theme: al_folio_core本地确实存在有意为之的 override。注意区分两种情况——docs/ARCHITECTURE.md 指出在用户站点里本地 override 完全受支持但在 al-folio starter 仓库本身这些目录_includes/、_layouts/、_sass/等不允许存在。本文只讨论你自己的站点。准备工作确认本地 override 与依赖更新入口先确认站点里哪些文件是有意保留的本地 override。docs/FAQ.md 给出的原则是站点专属内容、数据、Sass 和有意的本地 override 保留在站点仓库已被 v1 gem 接管的旧拷贝运行时文件如_includes/head.liquid、_includes/scripts.liquid、assets/js/distillpub/**、assets/js/search/**应当删除。更新依赖时有一个容易踩的坑docs/releases/v1.2.md 和 docs/releases/v1.1.md 都强调bundle update本身不会升级你。Gemfile把每个插件都钉在精确版本上Bundler 会尊重你Gemfile里已有的 pin——所以 v1.0 站点跑bundle update会原封不动没有任何报错。必须先编辑 pin再执行更新。这也是 upgrade CLI 工作流要配合 pin 修改使用的背景。跟踪漂移的三步命令在站点仓库根目录使用 docs/INSTALL.md Tracking local override drift 一节给出的命令# 1) 审查本地 override生成/更新认可文件 bundle exec al-folio upgrade overrides audit # 2) 查看某个 override 与上游 gem 文件的差异 bundle exec al-folio upgrade overrides diff _includes/repository/repo.liquid # 3) 确认审查过某个 override把当前上游校验和记为已审阅 bundle exec al-folio upgrade overrides accept _includes/repository/repo.liquid其中diff和accept命令后的路径是你站点中实际的 override 文件路径文档以_includes/repository/repo.liquid为例替换成你要审查的具体文件即可。overrides audit会把每个已审查 override 的以下信息写入.al-folio-overrides.yml拥有该文件的 gemowning gem及其版本上游文件 SHA256 校验和与本地文件 SHA256 校验和见 docs/ARCHITECTURE.md。这个文件要提交进你的站点仓库Commit that file。它是整个漂移跟踪机制的锚点audit 比对的是你当时审查过的上游校验和而不是最新上游。后续每次依赖更新后如何判断漂移当bundle update改变了某个上游插件文件后重新运行bundle exec al-folio upgrade overrides auditaudit 会把本地 override 与已安装al-*gem 携带的文件逐一对比如果某个上游文件自你上次accept之后发生了变化audit 会标记该 override 为stale过期提示你去对齐reconcile。判断结果就看这一点没有新标记说明你的 override 覆盖的文件在上游没变出现 stale 标记则用overrides diff path查看上游改了什么再决定是合并上游改动、保留本地版本并accept刷新校验和还是放弃本地副本。docs/FAQ.md 把这件事总结为When a future gem update changes that upstream file, the audit marks your local override as stale so you can reconcile it.放进完整升级流程里执行单独盯 override 漂移之外v1.x 的完整升级流程见 docs/INSTALL.md Recommended workflow 与 docs/FAQ.md How do I upgrade from v1.0 to v1.1 with minimal friction?是# 1) 更新依赖记得先改 Gemfile 里的插件版本 pin bundle update # 2) 审查站点中的破坏性/弃用模式 bundle exec al-folio upgrade audit # 3) 审查本地 override 漂移 bundle exec al-folio upgrade overrides audit # 4) 应用确定性 codemod可选 bundle exec al-folio upgrade apply --safe # 5) 生成需要人工跟进的报告 bundle exec al-folio upgrade reportreport输出写入al-folio-upgrade-report.md把发现分为两类Blocking目标升级视为完成之前必须解决Non-blocking可以随时间逐步迁移的弃用模式。依赖更新后的验证方式按 docs/INSTALL.md Maintaining Dependencies重建 Docker 镜像应用改动docker compose up --build然后docker compose up本地测试访问http://localhost:8080确认站点渲染正常如果更新后站点构建失败查 docs/FAQ.md 排查。限制与后续处理规则override 审查不是替代修复docs/ARCHITECTURE.md 明确指出对所有人都有益的修复应当移植到拥有该文件的 gem 中而不是保留为本地 override。本地 override 的定位是一次性的站点定制docs/INSTALL.md 也建议只在行为变更属于某个插件时才 fork 或 pin 插件。非定制站点不需要提交.al-folio-overrides.yml它只服务于审查过 override 的定制站点让未来的 gem 更新能显式标记过期的本地副本docs/FAQ.md、docs/BOUNDARIES.md 的表述一致。如果站点在 v1.0 前后经历过重度定制override audit 要在al-folio upgrade audit之前尽早跑docs/INSTALL.md Migrating heavily customized pre-v1 sites并最终以al-folio-upgrade-report.md中所有 Blocking 发现被清零、本地构建通过作为部署前的完成标准。【免费下载链接】al-folioA beautiful, simple, clean, and responsive Jekyll theme for academics项目地址: https://gitcode.com/GitHub_Trending/al/al-folio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考