git submodule add 路径必须是当前仓库中不存在的空目录，否则会报错或静默失败；子模块更新需两步：先在子模块内拉取代码，再在父仓库中提交新 commit hash。
submodule add 时路径写错会导致嵌套失败
Git 子模块不是“下载完就自动挂载”，git submodule add 的最后一个参数是目标路径，它必须是当前仓库里**不存在的空目录名**。如果该路径已存在且非空（比如你手动生成过同名文件夹），命令会直接报错：Repository not found 或静默失败——实际没创建 .gitmodules 条目，后续 git submodule update --init 也拉不下来。
实操建议：
- 加之前先
ls -la确认路径干净，别用mkdir预建目录 - 路径尽量用相对路径（如
libs/axios），避免绝对路径或以../开头 - 远程 URL 推荐用 SSH（
git@github.com:user/repo.git）而非 HTTPS，否则每次 push/pull 子模块都可能卡在凭据输入
子模块 commit hash 固定，但父仓库不提交就会丢失引用
子模块本质是父仓库中一个“指向某次 commit 的指针”，这个指针值（即子模块目录的 SHA-1）只存于父仓库的索引和工作区，**不会自动进父仓库的 commit**。你改了子模块代码、git commit 了子模块，但忘了在父仓库 git add libs/axios && git commit，那这次更新就只存在于你本地，别人 git clone 后 git submodule update 拉到的还是旧版本。
常见错误现象：
- 同事说“我刚更新了子模块”，你
git pull && git submodule update --init却没变 -
git status在父仓库显示modified: libs/axios (new commits)，但你没注意这行提示
关键点：子模块更新 = 两步操作，缺一不可：cd libs/axios && git pull origin main → 回到父目录 git add libs/axios && git commit -m "update axios to v1.6.0"
git submodule update --init --recursive 不等于全自动同步
这个命令只做三件事：初始化未克隆的子模块、检出它们记录的 commit、递归处理子模块里的子模块。它**不会拉取远程最新代码，也不会自动合并或 rebase**。如果你期望“一键同步所有依赖到最新版”，它做不到。
使用场景与风险：
- CI 构建时适合用它确保环境一致，但前提是父仓库 commit 已明确指定各子模块的精确 commit
- 开发中想升级子模块？得手动进子模块目录
git pull，再回到父目录git add提交新 hash - 若子模块远程分支有 force push，而你本地还缓存着旧 commit，
git submodule update仍会检出旧 hash，不会报错也不会覆盖——你得主动git submodule foreach git fetch && git reset --hard origin/main（慎用）
子模块里改代码却无法 push？检查 .git 文件是否被覆盖
子模块目录下没有独立的 .git 文件夹，而是由父仓库在 .git/modules/ 下统一管理其 Git 数据。当你用 IDE 或脚本误删、覆盖了子模块目录下的 .git 文件（它其实是个文本文件，内容类似 gitdir: ../.git/modules/libs/axios），子模块就变成普通文件夹，git status 在子模块内失效，git push 报错 fatal: not a git repository。
恢复方法很简单：
- 先确认父仓库中该子模块条目是否还在：
git config --file .gitmodules --get-regexp path - 删掉损坏的子模块目录：
rm -rf libs/axios - 重新初始化：
git submodule update --init libs/axios
这个细节容易被忽略：子模块的“可 Git 操作性”完全依赖那个小小的 .git 文件是否存在且指向正确——它不像普通仓库那样健壮。
