如何将Git仓库中已与上游（upstream）产生分歧的现有文件夹转换为git submodule，并通过变基（rebase）保留分歧提交？

开发者阿泽

2026-4-30

把已分叉的本地文件夹转为Git Submodule并保留提交（Rebase方式）

嘿，这个需求确实有点绕，但咱们一步步来，肯定能搞定。核心思路是先把你本地文件夹的提交历史单独抽出来，再替换成submodule，最后把你的提交rebase到上游仓库的最新版本上。

第一步：备份主仓库（重中之重！）

不管操作多熟练，先备份总没错，防止手抖翻车：

cp -r your-main-repo/ your-main-repo-backup/

咱们需要把原来混在主仓库里的文件夹提交，单独拎成一个独立的仓库历史：

进入你的主仓库：
```
cd your-main-repo/
```
使用git filter-repo（比旧的filter-branch更可靠）提取目标文件夹的历史，执行后当前分支就只剩这个文件夹的所有提交了：
```
git filter-repo --path your-target-folder/ --subdirectory-filter your-target-folder/
```
创建一个本地临时裸仓库，用来暂存这些提取出来的提交：
```
git init --bare ../temp-folder-repo.git
```
把提取好的提交推到这个临时仓库：
```
git push ../temp-folder-repo.git HEAD:main
```

现在回到原始的主仓库（用刚才备份的版本更稳妥）：

删除原来的文件夹并提交：

git rm -r your-target-folder/
git commit -m "Remove existing folder to replace with submodule"

添加上游仓库作为submodule，指定原来的文件夹路径：
```
git submodule add https://your-upstream-repo-url.git your-target-folder/
```
这时候submodule会默认拉取上游仓库的最新commit。
进入submodule目录：
```
cd your-target-folder/
```
添加之前的临时仓库作为本地远程：
```
git remote add local ../temp-folder-repo.git
```
拉取你本地的提交历史：
```
git fetch local
```
把你的提交rebase到上游的最新分支上（假设上游默认分支是main）：
```
git rebase main local/main
```
这时候如果有冲突，Git会提示你处理。解决完每个冲突文件后，执行：
```
git add <resolved-files>
git rebase --continue
```
重复这个过程直到rebase完成。
（可选）如果你有权限推送到上游仓库，可以把rebased后的提交推上去：
```
git push origin main
```

回到主仓库，提交submodule的更新：

cd ..
git add your-target-folder/
git commit -m "Add submodule with rebased local changes"

最后把临时仓库删掉就行：

rm -rf ../temp-folder-repo.git

如果你的目标文件夹原来的提交历史里有跨文件夹的操作，filter-repo的--subdirectory-filter会自动调整路径，把文件夹内容变成根目录，完美适配submodule的结构。
Rebase过程中冲突是正常的，耐心解决每一处冲突就行，Git会帮你把提交线性化到上游最新版本之上。
操作完成后，记得让团队其他成员执行git submodule update --init --recursive来同步submodule。

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