如何重写.gitmodule历史以全局修改所有历史中的子模块源

要永久修改所有历史提交里的.gitmodules文件内容，替换子模块旧地址为新地址，可使用官方推荐的git filter-repo工具（替代老旧的git filter-branch），具体步骤如下：

1. 备份仓库 #

重写历史属于破坏性操作，务必先完整复制仓库目录做备份，防止数据丢失。

2. 安装git filter-repo #

部分Git版本默认未集成该工具，可通过以下方式安装：

• 包管理器：Debian/Ubuntu用apt install git-filter-repo，macOS用brew install git-filter-repo
• 从官方源码编译安装

3. 替换.gitmodules中的旧地址 #

方法一：用替换文本文件 #

创建replace.txt文件，每行写一组旧地址与新地址的替换对（空格分隔）：

https://old-domain/submodule1.git https://new-domain/submodule1.git
https://old-domain/submodule2.git https://new-domain/submodule2.git

运行命令执行替换：

git filter-repo --replace-text replace.txt --path .gitmodules

方法二：用Python回调脚本 #

如果需要正则匹配等灵活替换逻辑，直接使用--blob-callback参数：

git filter-repo --blob-callback '
if blob.path == b".gitmodules":
    new_content = blob.data.decode("utf-8") \
        .replace("https://old-domain/submodule1.git", "https://new-domain/submodule1.git") \
        .replace("https://old-domain/submodule2.git", "https://new-domain/submodule2.git") \
        .encode("utf-8")
    blob.data = new_content
'

4. 推送修改后的历史 #

重写完成后所有提交哈希值会改变，需强制推送到远程仓库：

git push --force origin <分支名>

注意事项 #

• 若为多人协作仓库，必须通知所有协作者丢弃本地旧仓库，重新克隆新仓库，否则基于旧历史的提交会与新历史产生冲突。
• 需确保子模块本身已完成迁移，新地址的子模块仓库可正常访问，否则检出历史提交时可能无法拉取子模块内容。

内容的提问来源于stack exchange，提问作者Rich Maes