如何在Git嵌套子模块中维护本地分支与自定义修改

已完成的Git子模块初始化操作 #

cd $HOME/project; export PROJECT="${PWD}"; export TOPREPO="${PROJECT}/subs/toprepo"
git submodule add https://public.com/TopRepo/toprepo.git ${TOPREPO}
git submodule update --init --recursive ${TOPREPO}
git submodule status --recursive | awk '{print $2}'
# 输出结果：
# subs/toprepo
# subs/toprepo/sub1
# subs/toprepo/sub1/subsub1
# subs/toprepo/sub2
# ...

核心问题与需求 #

• 修改主仓库project自有代码时Git状态正常，但修改嵌套子模块（如subsub1）文件后，仅子模块目录能看到具体变更，上层仓库仅提示子模块有改动但无细节。
• 需求明确：
  1. 自定义修改无法推送到TopRepo及其子模块的公共仓库；
  2. 拉取/合并上游子模块更新时不丢失自定义修改；
  3. 无需在上层子模块（如sub1）创建分支，仅通过主仓库project同步嵌套子模块的本地分支/修改，执行git submodule update --init --recursive时自动应用这些自定义变更，且借助Git原生的pull/merge实现自动化处理，避免手动维护脚本。

解决方案 #

1. 用主仓库锁定子模块的提交哈希（无需上层子模块分支） #

主仓库本质是通过子模块的提交哈希追踪其状态，而非分支。只需在嵌套子模块中维护本地修改分支，再让主仓库锁定该分支的最新提交即可：

• 进入嵌套子模块目录，创建并切换到基于上游的本地修改分支：

  cd ${PROJECT}/subs/toprepo/sub1/subsub1
  git checkout -b hack2 origin/main
  

• 提交自定义修改到本地分支：

  git add .
  git commit -m "add custom changes to subsub1"
  

• 返回主仓库，更新子模块的追踪状态：

  cd ${PROJECT}
  git add subs/toprepo/sub1/subsub1
  git commit -m "lock subsub1 to hack2 branch's latest commit"
  

此后执行git submodule update --init --recursive时，Git会自动拉取主仓库记录的该提交哈希对应的代码，自动应用你的自定义修改。

2. 拉取上游更新并合并自定义修改（自动化处理） #

要同步上游更新且不丢失本地修改，直接在子模块中用Git原生命令合并即可：

• 进入子模块目录，拉取上游最新代码并合并到本地修改分支：

  cd ${PROJECT}/subs/toprepo/sub1/subsub1
  git fetch origin
  # 用rebase保持提交线性，也可替换为git merge origin/main hack2
  git rebase origin/main hack2
  

• 若出现冲突，解决冲突后继续：

  git rebase --continue
  

• 返回主仓库，更新子模块的追踪哈希：

  cd ${PROJECT}
  git add subs/toprepo/sub1/subsub1
  git commit -m "update subsub1 with merged upstream + custom changes"
  

3. 配置子模块默认分支（优化update命令行为） #

如果希望git submodule update默认拉取你的本地修改分支，可修改子模块配置：

git config -f .gitmodules submodule.subs/toprepo/sub1/subsub1.branch hack2

之后执行git submodule update --remote --recursive时，会自动拉取hack2分支的最新代码（注意：上游更新仍需手动进入子模块合并后，再更新主仓库的哈希记录）。

4. 批量处理所有子模块的脚本（基于Git原生命令） #

若有大量子模块需要维护，可使用以下脚本自动化合并上游操作：

#!/bin/bash
PROJECT_DIR="$HOME/project"
cd "${PROJECT_DIR}"

# 递归遍历所有子模块，合并上游更新到自定义分支
git submodule foreach --recursive '
  LOCAL_BRANCH=$(git branch --show-current)
  # 跳过上游默认分支（main/master），只处理自定义分支
  if [[ "${LOCAL_BRANCH}" != "main" && "${LOCAL_BRANCH}" != "master" ]]; then
    echo "Updating submodule $name (branch: $LOCAL_BRANCH)"
    git fetch origin
    git rebase origin/main "${LOCAL_BRANCH}"
  fi
'

# 更新主仓库的子模块哈希记录
git submodule update --init --recursive
git add .gitmodules $(git submodule status --recursive | awk '{print $2}')
git commit -m "batch update all submodules with merged upstream changes"

内容的提问来源于stack exchange，提问作者Lance E.T. Compte