Git - submodule operation instructions
1. add add submodule
# git submodule add -b master https://github.com/coolsnowwolf/lede.git ./lede
git submodule add -b <branch-name]> <git-repository-url> [local-path]
# 本地提交
git commit -m "add submodule xxxx"
# 推送到远程仓库
git push
2. checkout submodule checkout
# 有两种方式：
# 1. 使用 --recursive 参数，跟随主仓库递归 clone
git clone <your main repository url> --recursive # 此时 clone 下来的主项目会直接 clone 远程仓库中记录的 commit id 版本的子模块
# 2. 单独 checkout 子模块
git clone <your main repository url> # 不带 --recursive 递归参数时，submodule 无法被一起 clone 下来
git submodule update --init --recursive # 将 submodule 更新到远程仓库中记录的 commit id 版本
3. update update/switch submodule commit id and current branch
There is a big pitfall here. The submodule checked out by default does not belong to any branch, but a "detached head". Although changes can be submitted, there is no local branch to track the submitted changes, which means that the next time you update the submodule Modules lose these changes .
Therefore, before developing and modifying a submodule, please switch its branch and corresponding commit id.
# 默认添加的 submodule 的 commit id 是 add 时默认分支当前的一个 commit id，当子模块原始仓库更新后，期望切换到指定的 commit id 版本，或者像要切换分支
git pull
git submodule update # 更新本地仓库，避免出现冲突
cd <submodule dir>
git checkout <branch name> # 切换分支
git pull # 拉取新分支源码
git checkout <commit id> # 更新子模块版本
# 回到主仓库目录，提交子模块的引用版本修改
cd ..
git add . # 暂存 submodule 的引用版本修改
git commit -m "update submodule xxx from xxx to xxx" # 提交
git push # 推送到远程仓库
4. commit Submit submodule
git pull
git submodule update # 确保提交前已将本地仓库更新到远程仓库最新版本，避免提交出现冲突
cd <submodulde dir>
git add .
git commit -am "submodule modify"
git push # 将子模块提交的更改推送至远程仓库
Since the submodule and the main module are two independent warehouses, the main module only uses the url and commit id of the submodule. Therefore, when the submodule pushes the change, a new commit id is generated, but the reference configuration of the submodule from the main module has not changed, so the commit change needs to be made synchronously in the main module.
cd ../ # 回到主模块目录
git add .
git commit -am "submodule reference modify"
git push # 推送主模块对子模块的引用记录更改到远程仓库
It can be seen that for the modification of the submodule, we need to submit and push the changes of the submodule and the main block separately. Of course, we can also merge the "push to the remote warehouse" step:
cd <main module dir> # 进入主模块目录
# 使用 --recurse-submodules=on-demand 选项，可以在推送主模块更改时，自动推送未推送的子模块
git push --recurse-submodules=on-demand
If the submodule submits the change record, but it is not pushed to the remote warehouse, the main module submits the change of the submodule reference record and completes the operation of pushing to the remote warehouse. At this time, it is no problem to pull the main module, but when pulling the submodule, an error of "not our ref" will appear. This is because the main module references a submodule with an undocumented commit id version in the remote repository. You need to complete the push in the submodule that submitted the change record. in order to avoidForgot to push the submodule modification, only the reference record change of the main module was pushed, you can modify the push command of the main module to:
# 使用 --recurse-submodule=check 选项可以自动检查子模块未 push 的错误
git push --recurse-submodule=check
When the “–recurse-submodule=check” option is used, if the submodule is not pushed, the current push operation will alarm; and if the submodule fails to push, an error will also be reported. It can be directly written into the git configuration to reduce duplication of work:
git config push.recurseSubmodules check
5. modify modify submodule remote warehouse url
cd <main module dir> # 进入主模块目录
# 修改主模块中 .gitmodules 中的 url
# 使用 sync 命令同步修改至 .git/config 中
git submodule sync
git commit -am "modify submodule url" # 提交修改
git push # 推送到主模块远程仓库
If someone else modifies the submodule url, after pulling the update of the main module, use the sync command to synchronize to the local .git/config:
cd <main module dir> # 进入主模块目录
git pull # 拉取主模块更新，即获取 .gitmodule 中 url 的修改
git submodule sync # 将 .gitmodule 中的修改同步到本地仓库的配置中 .git/config
6. deinit removes the existing submodule
git submodule deinit <submodule name>
git rm <submodule dir>
git commit -am "remove submodule xxx"
git push