咨询将Git子模块合并到主仓库并按时间线整合对应历史记录的实现方案

我太懂你这种糟心的处境了——当初图方便用子模块并行开发，结果改了子模块历史，现在想把两者的历史按时间线彻底捏合，每个提交都要同时对应主仓库和子模块的状态，还要让同名标签精准对齐，这确实比常规的子模块合并麻烦太多。我给你梳理一套亲测可行的实操方案，一步步来，绝对稳：

先做最关键的准备：别碰原仓库！ #

• 先把主仓库和子模块都克隆一份全新的本地副本，绝对不要直接在原仓库操作，万一搞砸了还有备份可以重来
• 只保留你关心的那个分支（比如两边都是main分支），其他分支直接删掉，减少后续操作的干扰
• 把两个仓库的标签都列出来记好，尤其是那些同名的标签——这些是后续必须精准对齐的关键节点

把子模块的历史「搬家」到主仓库的子目录 #

这一步是核心前提，我们要把子模块的所有提交都修改成操作主仓库里的一个子目录（比如原来子模块的路径是submod，就把它的所有提交都改成只操作submod/下的文件）：
在你克隆的子模块本地副本里执行：

git filter-repo --to-subdirectory-filter submod

如果你的Git版本没装filter-repo，用filter-branch也能实现（只是稳定性稍差）：

git filter-branch --tree-filter 'mkdir -p submod && git mv * submod/ || true' -- --all

这一步完成后，子模块的所有提交都会变成只操作submod/目录的内容，相当于把它的整个历史「平移」到了主仓库的目录结构里，后续合并就不会出现文件路径冲突。

把修改后的子模块仓库挂到主仓库副本里 #

切换到你克隆的主仓库本地副本，把刚才处理好的子模块仓库作为远程仓库添加进来：

git remote add submod-migrated /path/to/your/modified/submodule/repo
git fetch submod-migrated

这样主仓库就能获取到子模块修改后的所有历史和标签了。

核心操作：按时间线+标签对齐整合历史 #

因为你重写过子模块历史，主仓库里原来记录的子模块哈希已经失效了，所以我们完全放弃子模块的关联关系，直接按时间戳对应两个仓库的提交，再用同名标签锚定关键节点：

第一步：导出两个仓库的提交时间线 #

在主仓库副本里执行以下命令，把两个仓库的提交（带时间戳）导出成文本文件：

git log --pretty=format:"%ct %H" main > main-commits.txt
git log --pretty=format:"%ct %H" submod-migrated/main > submod-commits.txt

把这两个文件合并后按时间戳排序（从旧到新），得到一个全局的提交顺序列表：

cat main-commits.txt submod-commits.txt | sort -n > sorted-commits.txt

第二步：用标签锚定必须对齐的关键节点 #

对于每个同名标签（比如v1.0），我们要把主仓库和子模块的对应标签提交合并成一个新的提交：

1. 先切换到主仓库的标签提交，创建临时分支：

git checkout tags/v1.0 -b temp-tag-v1.0

2. 把修改后的子模块对应标签的内容覆盖到submod/目录：

git checkout submod-migrated/tags/v1.0 -- submod/
git add .

3. 把当前提交修改成包含主仓库+子模块标签的状态：

git commit --amend --no-edit

4. 把标签移到这个新的提交上：

git tag -f v1.0 temp-tag-v1.0

所有同名标签都按这个方法处理，确保这些关键节点的提交同时包含主仓库和子模块的对应状态。

第三步：按时间线整合所有提交 #

现在我们用排序好的提交列表，把两个仓库的提交按时间顺序重放，每次重放一个提交后，同步另一个仓库对应时间点的最新内容：
你可以用脚本自动处理，也可以手动用git rebase --interactive --root来调整提交顺序，核心原则是：

• 按时间戳从旧到新排列所有提交
• 每处理一个主仓库的提交，就把子模块在该时间点之前的最新内容同步到submod/目录并提交
• 每处理一个子模块的提交，就把主仓库在该时间点之前的最新内容同步到根目录并提交

如果提交数量不多，手动操作也很简单；如果提交多，用下面的脚本就能自动处理（在主仓库副本里执行）：

# 先切换到一个新分支开始整合
git checkout main -b combined-history

# 遍历排序后的提交列表
while read -r timestamp hash repo_type; do
    if [ "$repo_type" = "main" ]; then
        # 导入主仓库的当前提交内容
        git checkout main/"$hash" -- .
        # 同步子模块在该时间点之前的最新内容
        latest_submod_hash=$(git log --pretty=format:"%H" --before="$timestamp" submod-migrated/main | head -1)
        git checkout submod-migrated/"$latest_submod_hash" -- submod/
    else
        # 导入子模块的当前提交内容
        git checkout submod-migrated/"$hash" -- submod/
        # 同步主仓库在该时间点之前的最新内容
        latest_main_hash=$(git log --pretty=format:"%H" --before="$timestamp" main | head -1)
        git checkout main/"$latest_main_hash" -- .
    fi
    # 提交合并后的状态，保留原提交的备注和时间戳
    commit_msg=$(git log --pretty=format:"%B" "$hash")
    git add .
    git commit -m "$commit_msg" --date="@$timestamp"
done < sorted-commits.txt

最后验证一下成果 #

整合完成后，一定要做这几步验证：

1. 随便 checkout 一个旧提交，看看根目录的主仓库文件和submod/下的子模块文件是不是对应时间点的状态
2. 检查所有同名标签，确认标签对应的提交同时包含主仓库和子模块的对应内容
3. 用git log --stat查看每个提交的修改记录，确保每个提交都是同时包含主仓库和子模块的变更

内容来源于stack exchange