如何迁移已重命名文件至新仓库并恢复完整提交历史？

操作步骤 #

1. 准备源仓库本地副本 #

• 克隆源仓库（若未本地存储）：

  git clone <源仓库URL> source-repo
  cd source-repo
  

• 拉取最新分支代码：git pull origin <分支名>

2. 过滤目标文件的完整历史 #

使用git filter-repo（替代老旧的filter-branch，更稳定可靠），同时指定文件的旧路径和新路径，确保重命名前后的提交都被保留：

git filter-repo --path <旧文件路径> --path <新文件路径>

示例：如果文件从docs/old-guide.md移到docs/new-guide.md，命令为：

git filter-repo --path docs/old-guide.md --path docs/new-guide.md

此命令会重写仓库历史，仅保留与指定文件相关的所有提交（包括重命名操作本身）。

3. 临时中转处理 #

• 创建临时裸仓库作为中转：

  git init --bare ../temp-bare-repo
  git push ../temp-bare-repo <分支名>
  

4. 导入到目标仓库 #

• 进入目标仓库目录：

  cd ../target-repo
  

• 添加临时仓库为远程源：

  git remote add temp-source ../temp-bare-repo
  

• 拉取完整历史（允许无关历史合并）：

  git pull temp-source <分支名> --allow-unrelated-histories
  

• 若需将文件放到目标仓库的指定目录，可在步骤2中添加--path-rename参数调整路径：

  git filter-repo --path docs/old-guide.md --path docs/new-guide.md --path-rename docs/: target/docs/
  

• 完成后移除临时远程：

  git remote remove temp-source
  

5. 验证历史完整性 #

在目标仓库中执行以下命令，查看文件的完整追踪历史：

git log --follow -- <目标路径下的文件名>

此命令会自动关联重命名记录，显示该文件从创建到当前的所有提交。

问题原因说明 #

之前的操作仅指定了文件的新路径，Git无法识别重命名前的旧路径关联记录，因此只保留了重命名后的提交。通过同时指定新旧路径，git filter-repo能完整提取所有相关历史，让Git可以追踪文件的完整变更轨迹。

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