如何使用git filter-branch移除裸Git仓库中的单个子模块？

我明白你现在的困扰——之前用git filter-branch清理过文件，但要在裸仓库里精准移除单个不该存在的子模块（比如你的「Phooey」），而不是把所有子模块都删掉，确实需要更针对性的操作。下面是一步步的可行方案：

步骤1：创建临时非裸仓库来处理 #

因为裸仓库没有工作区，直接操作filter-branch容易踩坑，所以先克隆你的裸仓库到一个临时本地仓库：

git clone /path/to/Donald.git temp-Donald
cd temp-Donald

步骤2：用git filter-branch移除「Phooey」的所有痕迹 #

我们需要清理三个地方：根目录下的「Phooey」子模块引用、.gitmodules里的「Phooey」配置块，以及历史提交中相关的记录。执行下面的命令：

git filter-branch --tree-filter '
  # 删除当前提交中的Phooey子模块目录
  if [ -d "Phooey" ]; then rm -rf Phooey; fi
  # 从.gitmodules中移除Phooey的配置段
  if [ -f ".gitmodules" ]; then
    # 用awk删除从[submodule "Phooey"]到下一个[开头行的所有内容
    awk "/\[submodule \"Phooey\"\]/,/^\[/{next}1" .gitmodules > .gitmodules.tmp
    mv .gitmodules.tmp .gitmodules
    # 如果处理后.gitmodules为空，直接删除它
    if [ ! -s .gitmodules ]; then rm .gitmodules; fi
  fi
' -- --all

命令解释： #

• --tree-filter：会在每个提交的工作树中执行脚本，修改后自动生成新的提交
• awk命令精准定位并删除「Phooey」的子模块配置，不会影响其他子模块（Huey/Dewey/Louie）的配置
• 最后检查并删除空的.gitmodules，避免留下无用文件

步骤3：验证清理结果 #

在推送回裸仓库前，一定要确认清理效果：

• 搜索是否还有和「Phooey」相关的提交：git log --oneline --grep="Phooey"
• 查看之前包含「Phooey」的提交，确认内容已移除：git show <目标提交ID>

步骤4：推送清理后的历史回裸仓库 #

因为我们重写了提交历史，需要强制推送所有分支和标签：

git push /path/to/Donald.git --force --all
# 如果仓库有标签，也需要强制推送标签
git push /path/to/Donald.git --force --tags

步骤5：收尾工作 #

• 删除临时仓库：

  cd ..
  rm -rf temp-Donald
  

• 通知所有克隆过「Donald」仓库的团队成员：他们需要重新克隆仓库，或者在本地执行以下命令同步新历史：

  git fetch origin
  git reset --hard origin/<你的分支名>
  

可选：用更高效的git filter-repo替代filter-branch #

官方已经标记git filter-branch为废弃，推荐使用更高效的git filter-repo（需要Python 3环境）。操作步骤类似：

git filter-repo --tree-filter '
  if [ -d "Phooey" ]; then rm -rf Phooey; fi
  if [ -f ".gitmodules" ]; then
    awk "/\[submodule \"Phooey\"\]/,/^\[/{next}1" .gitmodules > .gitmodules.tmp
    mv .gitmodules.tmp .gitmodules
    [ ! -s .gitmodules ] && rm .gitmodules
  fi
'

之后同样执行推送和收尾步骤即可。

内容的提问来源于stack exchange，提问作者Peter Toft