企业官网建设流程全解析

kohya_ss 仓库中 sd-scripts 子模块的更新实战指南（dev / main 分支）

【免费下载链接】kohya_ss项目地址: https://gitcode.com/GitHub_Trending/ko/kohya_ss

导读

kohya_ss 是一个基于 Gradio 的 Stable Diffusion / SDXL / FLUX 训练图形界面，它的训练引擎并不在本仓库内，而是通过git 子模块（submodule）方式将上游kohya-ss/sd-scripts嵌入到sd-scripts/目录中。本文以 examples/pull kohya_ss sd-scripts updates in.md 为核心，完整讲解如何把本地子模块更新到上游最新的 dev 或 main 分支、如何在父仓库中记录这次更新，并结合仓库内的.gitmodules配置、启动脚本与 AGENTS.md 约定，帮你安全、可复现地完成每一次训练引擎升级。

为什么 kohya_ss 要把 sd-scripts 做成子模块

在动手执行命令之前，先理解这个仓库的结构，能避免更新过程中的大部分困惑。

子模块的定义与指向

仓库根目录下的 .gitmodules 明确定义了这个子模块：

[submodule "sd-scripts"] path = sd-scripts url = https://github.com/kohya-ss/sd-scripts.git

也就是说，sd-scripts/目录并不是 kohya_ss 自己维护的代码，而是上游kohya-ss/sd-scripts仓库的一个固定提交（commit）的检出版本。父仓库只记录"应该指向哪个提交"，并不把子模块的代码直接纳入自身版本控制。

官方对子模块的边界约定

仓库根目录的 AGENTS.md 中明确写着：

sd-scripts/is agit submodulepointing at upstream kohya-ss/sd-scripts. Never edit files inside it — GUI-side changes only. If a fix requires a sd-scripts change, describe it as a snippet in the PR body instead of committing to the submodule.

这告诉我们两条重要规则：

1. 不要直接修改sd-scripts/内部的文件，GUI 侧的改动只应发生在 kohya_ss 自身的代码里；
2. 如果某个修复需要改动 sd-scripts，正确的做法是在 PR 描述中以代码片段形式给出，而不是把改动提交进子模块。

更新子模块的目标是跟随上游最新代码，而不是在其上做本地定制。此外 AGENTS.md 还强调 GUI 代码应当通过 sd-scripts 的 CLI / 库接口来调用，不要从kohya_gui/直接触及子模块内部实现，这也是更新后 GUI 依然稳定的前提。

首次获取：为什么安装时要带 --recursive

子模块的内容默认不会随父仓库自动检出，因此 kohya_ss 的所有安装文档（如 docs/Installation/pip_linux.md、docs/Installation/uv_linux.md、docs/installation_docker.md）都要求使用递归克隆：

git clone --recursive https://github.com/bmaltais/kohya_ss.git

启动脚本也内置了子模块的初始化兜底逻辑。以 gui-uv.sh 为例，脚本在启动前会执行：

git submodule update --init --recursive

gui-uv.bat 中同样有一句注释Make sure we are on the right sd-scripts commit，随后执行git submodule update --init --recursive。这条命令的作用是把子模块初始化并检出到父仓库记录的提交，保证你拿到的是与当前 GUI 版本匹配的训练引擎。理解这一点后，下面的更新流程就顺理成章了："更新" = 把 sd-scripts 切到上游新提交 + 让父仓库记下新提交。

更新到上游 dev 分支（推荐流程）

examples/pull kohya_ss sd-scripts updates in.md 给出的第一套命令，用于把子模块更新到上游最新的开发分支：

cd sd-scripts git fetch git checkout dev git pull origin dev cd .. git add sd-scripts git commit -m "Update sd-scripts submodule to the latest on dev"

逐条拆解这套命令的实际作用：

更新到上游 main 分支（稳定版流程）

如果你希望跟随稳定分支而不是开发分支，使用 examples/pull kohya_ss sd-scripts updates in.md 给出的第二套命令：

cd sd-scripts git fetch git checkout main git pull origin main cd .. git add sd-scripts git commit -m "Update sd-scripts submodule to the latest on main"

与 dev 流程的唯一区别是把分支从dev换成了main。main 通常是 sd-scripts 的稳定主线，dev 则包含较新的开发特性；选择哪条取决于你需要的功能是否已合入 stable。例如 README.md 的更新记录中提到"Upgraded thesd-scriptssubmodule to v0.11.1"，说明子模块版本是跟随上游发版节奏迭代的——若你只想要稳定的训练行为，优先跟随 main；若需要实验性功能或上游最新修复，再考虑 dev。

更新前后的检查与验证

更新不是"执行完命令就结束"，建议配合以下检查确认状态正确。

查看当前子模块指向

在父仓库根目录执行：

git submodule status

输出格式为<commit> <path>。如果 commit 前没有前缀-号，说明子模块已正确检出；若出现-前缀则代表尚未初始化或未检出。例如当前仓库实际检出的状态形如：

-6721028c79ee85a78b3a06dfd8954dae310a1cce sd-scripts

查看父仓库中子模块指针的差异

更新并git add sd-scripts之后，可以用：

git diff --submodule=log

这条命令会显示父仓库中记录的 sd-scripts 指针从哪个提交变到了哪个提交，并列出期间的提交日志，方便确认这次升级究竟带来了哪些训练引擎改动。

更新后强制刷新子模块内容

如果在别的机器上拉取了父仓库的新提交，但sd-scripts/目录没有随之更新，可以使用：

git submodule update --init --recursive

这与 gui-uv.sh / gui-uv.bat 启动前执行的命令完全一致，是"把子模块同步到父仓库记录版本"的通用手段。

常见问题与避坑要点

结合仓库约定与 git 子模块的通用行为，以下是更新过程中最容易踩的坑：

1. 直接改了子模块内部文件：AGENTS.md 明确禁止在sd-scripts/内做本地修改。若只是跟随上游，不要在任何文件上做本地改动，否则git pull可能因本地冲突而失败；若确实发现上游 bug，应在 kohya_ss 的 PR 中给出修复片段，而不是提交到子模块。
2. 忘记在父仓库提交指针变化：只执行cd sd-scripts && git pull而不做cd .. && git add sd-scripts && git commit，父仓库记录的仍然是旧提交，下次git submodule update会把子模块"打回原形"。原文档把"回到父仓库并提交"作为固定一步，正是为此。
3. 游离 HEAD（detached HEAD）状态：如果之前用git checkout <commit>而不是分支名，会进入游离 HEAD。此时执行git checkout dev（或main）即可切回分支再拉取，避免更新丢失。
4. 子模块未初始化：如果克隆时没带--recursive，sd-scripts/目录是空的，任何在其内部的 git 操作都会失败。先执行git submodule update --init --recursive完成初始化。
5. 更新后 GUI 行为异常：dev 分支变化较快，可能与当前 GUI 版本存在参数不兼容。升级后建议先在测试配置上跑一轮训练（仓库 test/config 下提供了 dataset 等示例配置）验证，再用于正式训练。

小结

在 kohya_ss 中更新 sd-scripts 子模块的本质是两步操作：子模块内部切分支并 pull 上游最新代码，父仓库git add+git commit记录新的指针。dev 与 main 两套流程命令几乎一致，只是目标分支不同；配合git submodule status、git submodule update --init --recursive等命令即可完成从获取、更新到验证的完整闭环。遵循仓库 AGENTS.md 的边界约定——只跟随上游、不修改子模块内部——就能长期、安全地保持训练引擎与 GUI 的同步更新。

【免费下载链接】kohya_ss项目地址: https://gitcode.com/GitHub_Trending/ko/kohya_ss