git子模块--命令--表格版

Git子模块指令查询手册

---

基本操作指令

指令	功能	说明	示例
git submodule add <仓库地址> [路径]	添加子模块	将外部仓库作为子模块添加到主项目，生成.gitmodules。	git submodule add https://github.com/user/repo.git submodule_folder
git clone --recursive <主仓库地址>	克隆含子模块项目	克隆主仓库及其所有子模块。	git clone --recursive https://github.com/user/main-repo.git
git submodule init	初始化子模块	将.gitmodules配置写入.git/config。	git submodule init
git submodule update	更新子模块	拉取子模块代码并检出记录的提交。	git submodule update
git submodule sync	同步子模块URL	更新子模块URL配置。	git submodule sync
git rm <子模块路径> git deinit <子模块路径>	删除子模块	删除子模块记录并解除初始化。	git rm submodule_folder git deinit submodule_folder

状态查看指令

指令	功能	说明	示例
git submodule status	查看子模块状态	显示子模块路径、提交哈希和分支信息。	git submodule status
git submodule summary	查看子模块更新摘要	显示子模块与主仓库记录的差异。	git submodule summary
git status --submodules	查看项目状态（含子模块）	显示主仓库和子模块状态。	git status --submodules
git diff --submodule	查看子模块差异	显示主仓库与子模块差异。	git diff --submodule

更新与同步指令

指令	功能	说明	示例
git submodule update --remote	更新子模块到远程最新	拉取子模块远程分支最新提交。	git submodule update --remote
git submodule foreach git pull	拉取所有子模块最新代码	遍历子模块执行git pull。	git submodule foreach git pull
git pull --recurse-submodules	拉取主仓库并更新子模块	同时更新主仓库和子模块。	git pull --recurse-submodules
git submodule foreach git fetch	获取子模块最新元数据	拉取子模块最新元数据。	git submodule foreach git fetch

分支管理指令

指令	功能	说明	示例
git submodule add -b <分支名> <仓库地址> [路径]	添加子模块并指定分支	添加子模块并设置跟踪分支。	git submodule add -b main https://github.com/user/repo.git submodule_folder
git config -f .gitmodules submodule.<name>.branch <分支名>	设置子模块跟踪分支	在.gitmodules中设置跟踪分支。	git config -f .gitmodules submodule.submodule_folder.branch main
git submodule foreach git checkout <分支名>	切换子模块分支	遍历子模块切换分支。	git submodule foreach git checkout main
git checkout --recurse-submodules <分支名>	切换主仓库分支并同步子模块	切换主仓库分支并更新子模块。	git checkout --recurse-submodules feature-branch

高级操作指令

指令	功能	说明	示例
git submodule foreach --recursive <命令>	递归遍历子模块	递归执行命令于所有子模块。	git submodule foreach --recursive git status
git submodule foreach --init <命令>	初始化并执行命令	初始化未初始化的子模块并执行命令。	git submodule foreach --init git pull
git submodule absorbgitdirs	合并子模块.git目录	将子模块.git目录合并到主仓库。	git submodule absorbgitdirs
git submodule deabsorb	恢复子模块独立.git目录	恢复子模块独立.git目录。	git submodule deabsorb

协同操作指令

指令	功能	说明	示例
git add <子模块路径>	记录子模块变更	记录子模块新提交哈希到主仓库。	git add submodule_folder
git push --recurse-submodules=check	推送前检查子模块	确保子模块变更已推送。	git push --recurse-submodules=check
git push --recurse-submodules=on-demand	推送主仓库并自动推送子模块	推送主仓库并自动推送子模块变更。	git push --recurse-submodules=on-demand

配置设置指令

指令	功能	说明	示例
git config submodule.<name>.update <策略>	设置子模块更新策略	设置更新策略（none、checkout、rebase、merge）。	git config submodule.submodule_folder.update rebase
git config submodule.<name>.branch <分支名>	设置子模块跟踪分支	设置跟踪分支。	git config submodule.submodule_folder.branch main
git config submodule.recurse true	全局启用子模块递归	启用子模块命令默认递归。	git config submodule.recurse true

实用组合指令

指令	功能	说明	示例
git submodule foreach --recursive 'git checkout main && git pull origin main'	批量更新子模块到主分支	遍历子模块切换到main并拉取最新代码。	git submodule foreach --recursive 'git checkout main && git pull origin main'
`git submodule foreach --recursive 'git fetch origin main && [ “$(gitrev-parseHEAD)"="$(git rev-parse origin/main)” ] && echo “✅ $name 一致”		echo “❌ $name 不一致”'`	检查子模块与远程主分支同步
git clone --recursive <主仓库地址> git submodule update --init --recursive	递归克隆并更新子模块	克隆主仓库并初始化、更新所有子模块。	git clone --recursive https://github.com/user/main-repo.git git submodule update --init --recursive
git config -f .gitmodules submodule.<name>.branch main git submodule update --remote git add <子模块路径> git commit -m "Update submodule"	设置跟踪分支并更新子模块	设置跟踪main分支，更新子模块并记录变更。	git config -f .gitmodules submodule.submodule_folder.branch main git submodule update --remote git add submodule_folder git commit -m "Update submodule to latest main"