143 lines
3.9 KiB
Markdown
143 lines
3.9 KiB
Markdown
---
|
|
slug: git-large-project-split
|
|
title: "Git 大工程拆分：保留历史提交记录的详细指南"
|
|
authors: lxy
|
|
tags: [ Git, 版本控制, 项目管理, 代码重构, DevOps ]
|
|
---
|
|
|
|
在项目迭代过程中，随着代码量与模块复杂度不断攀升，将一个大型 Git 工程拆分为多个独立工程，能让项目结构更清晰，便于团队协作与维护。关键是要保留完整的提交历史，这就需要借助 Git 的 `filter-branch` 工具来实现。
|
|
|
|
## 一、准备工作
|
|
|
|
### 使用 filter-branch
|
|
`git filter-branch` 是 Git 内置的强大工具，无需额外安装，可以直接使用。虽然相比 `filter-repo` 效率稍低，但功能完整且稳定可靠。
|
|
|
|
**验证可用性：**
|
|
```bash
|
|
git filter-branch --help
|
|
```
|
|
|
|
### 备份原仓库
|
|
拆分前务必备份原仓库，防止操作失误导致数据丢失：
|
|
```bash
|
|
git clone --mirror 原仓库地址 备份仓库地址
|
|
```
|
|
|
|
## 二、拆分示例
|
|
|
|
假设原仓库有两个独立模块，需拆分为：
|
|
- **工程 A**：只保留 `module-a/` 目录及相关历史
|
|
- **工程 B**：只保留 `module-b/` 目录及相关历史
|
|
|
|
## 三、具体步骤
|
|
|
|
### 拆分工程 A
|
|
|
|
#### 1. 克隆原仓库
|
|
```bash
|
|
git clone 原仓库地址 工程A
|
|
cd 工程A
|
|
```
|
|
|
|
#### 2. 使用 filter-branch 保留指定目录
|
|
```bash
|
|
git filter-branch --prune-empty --subdirectory-filter module-a master
|
|
```
|
|
|
|
**参数说明：**
|
|
- `--subdirectory-filter module-a`：将 `module-a` 目录作为新仓库的根目录
|
|
- `--prune-empty`：删除空提交
|
|
- `master`：指定要重写历史的分支
|
|
|
|
#### 3. 清理无关分支（可选）
|
|
```bash
|
|
# 查看所有分支
|
|
git branch -a
|
|
|
|
# 删除不需要的分支
|
|
git branch -D 无关分支名
|
|
git branch -dr origin/无关分支名
|
|
```
|
|
|
|
#### 4. 提交到新仓库
|
|
```bash
|
|
# 关联新仓库
|
|
git remote add origin 工程A的新仓库地址
|
|
|
|
# 推送所有分支和标签
|
|
git push -u origin --all
|
|
git push --tags
|
|
```
|
|
|
|
### 拆分工程 B
|
|
|
|
按照相同步骤操作：
|
|
```bash
|
|
# 重新克隆原仓库
|
|
git clone 原仓库地址 工程B
|
|
cd 工程B
|
|
|
|
# 只保留 module-b 目录
|
|
git filter-branch --prune-empty --subdirectory-filter module-b master
|
|
|
|
# 关联工程 B 的远程仓库并推送
|
|
git remote add origin 工程B的新仓库地址
|
|
git push -u origin --all
|
|
git push --tags
|
|
```
|
|
|
|
## 四、重要说明
|
|
|
|
### 历史完整性
|
|
`filter-branch` 会重写提交历史，只保留与指定目录相关的提交（包括修改、删除、重命名等操作），其他提交会被过滤，最终历史记录"干净"且相关。
|
|
|
|
### 处理大型仓库
|
|
若仓库体积大（含大量大文件），可先清理超大文件：
|
|
```bash
|
|
# 使用 filter-branch 清理大文件
|
|
git filter-branch --tree-filter 'rm -f large_file.zip' HEAD
|
|
```
|
|
|
|
### 高级用法
|
|
`filter-branch` 提供了多种过滤方式：
|
|
|
|
**按文件大小过滤：**
|
|
```bash
|
|
git filter-branch --tree-filter 'find . -size +10M -delete' HEAD
|
|
```
|
|
|
|
**按文件类型过滤：**
|
|
```bash
|
|
git filter-branch --tree-filter 'rm -rf *.log' HEAD
|
|
```
|
|
|
|
**保留多个目录：**
|
|
```bash
|
|
git filter-branch --index-filter 'git rm -r --cached --ignore-unmatch module-c module-d' HEAD
|
|
```
|
|
|
|
## 五、高级用法
|
|
|
|
### 复杂目录结构拆分
|
|
如果需要拆分更复杂的目录结构，可使用以下方法：
|
|
|
|
**使用 tree-filter 进行复杂操作：**
|
|
```bash
|
|
# 只保留特定文件类型
|
|
git filter-branch --tree-filter 'find . -name "*.js" -o -name "*.ts" | xargs rm -f' HEAD
|
|
|
|
# 排除特定目录
|
|
git filter-branch --tree-filter 'rm -rf temp/ build/ node_modules/' HEAD
|
|
|
|
# 重命名目录结构
|
|
git filter-branch --tree-filter 'mkdir -p new_structure && mv module-a/* new_structure/' HEAD
|
|
```
|
|
|
|
**使用 index-filter 提高性能：**
|
|
```bash
|
|
# 只保留指定目录（性能更好）
|
|
git filter-branch --index-filter 'git rm -r --cached --ignore-unmatch module-b module-c' HEAD
|
|
```
|
|
|
|
通过以上步骤，两个新工程会分别保留原仓库中与自身模块相关的完整提交历史，且相互独立。这样既保持了代码的连续性，又实现了模块的独立管理。
|