用途:安全地同步(pull)父仓库并按父仓库锁定的提交更新 Git 子模块,同时处理子模块存在本地改动(脏状态)的情况。
主要能力:查看根仓库与子模块的脏状态;在指定子模块内用 stash 暂存改动以放行更新;拉取根仓库并递归同步、初始化、更新子模块;可选地恢复暂存的改动;识别并处理子模块 pin 不可达(not our ref)等常见问题。
使用方式:先查看脏状态,命令为 git status --porcelain 与 git submodule foreach --recursive 'echo "--- $name ($path)"; git status --porcelain'。若子模块脏,进入该子模块暂存,例如 git -C _repos/openwork stash push -u -m "wip: allow submodule update"。随后执行 git pull、git submodule sync --recursive、git submodule update --init --recursive。需要恢复时用 git -C _repos/openwork stash list 与 git -C _repos/openwork stash pop。
限制与注意:stash 按仓库独立,必须在子模块内执行;有未跟踪文件时用 -u。常规同步不要用 git submodule foreach --recursive 'git pull',因为子模块通常锁定在特定提交,内部 pull 会使其偏离 pin 并让根仓库变脏。若要把子模块升级到上游新提交,属于另一操作:git submodule update --remote --recursive。遇到 not our ref 时,可先 git pull --recurse-submodules=no,再将子模块移到可达引用并 git add 该 gitlink;更规范的做法是提交 PR 重新 pin 到可达提交,避免对作为 pin 的分支或标签强制推送。资料未提供安装方式、收费与平台信息。