背景

正在開發的一個項目中引用了第三方庫的源碼，由于歷史原因，源碼的引用并不是很規范（直接下載下來后作為自己項目的部分源碼使用，還進行了一些修改），具體如下：

1. 我有一個本地git項目project_local，其基本目錄結構如下：

   project_local
   |-- CHANGELOG.md
   |-- CMakeLists.txt
   |-- README.md
   |-- jsoncpp
   |   |-- CMakeLists.txt
   |   |-- json
   |   `-- jsoncpp.cpp
   |-- thread_pool.h
   `-- vpf|-- CMakeLists.txt|-- FindVPF.cmake|-- PyNvCodec|-- PytorchNvCodec|-- VideoCapture.cpp|-- VideoCapture.h|-- VideoWriter.cpp`-- VideoWriter.h
   

   其中，vpf/PyNvCodec、vpf/PytorchNvCodec均為目錄，下面還有子目錄和各種文件，正是這兩個目錄來源于開源項目
2. 線上github源碼工程為project_online，其基本目錄結構為：

   project_online
   |-- CMakeLists.txt
   |-- LICENSE
   |-- PyNvCodec
   |   |-- CMakeLists.txt
   |   |-- TC
   |   |-- inc
   |   |-- pybind11-2.1.1
   |   `-- src
   |-- PytorchNvCodec
   |   |-- CMakeLists.txt
   |   `-- src
   |-- README.md
   |-- SampleDecode.py
   |-- SampleDecodeMultiThread.py
   |-- SampleDecodeSw.py
   |-- SampleDemuxDecode.py
   |-- SampleEncode.py
   |-- SampleEncodeMultiThread.py
   |-- SamplePyTorch.py
   |-- SampleTensorRTResnet.py
   |-- SampleTorchResnet.py
   `-- Tests.py
   

3. project_local項目中的vpf目錄使用了project_online工程，即vpf/PyNvCodec、vpf/PytorchNvCodec兩個目錄均來源于project_online項目下的PyNvCodec和PytorchNvCodec
4. 具體需要求是：project_online項目有更新了(新版本v1.1)，我想把這些更新應用在vpf/PyNvCodec、vpf/PytorchNvCodec這兩個目錄上，其他文件和目錄均保持不變

實現方法

推薦方法：推薦方法：使用子樹合并策略 (Subtree Merge)

# 進入本地項目目錄
cd /path/to/project_local# 1. 添加原始倉庫為遠程源
git remote add online https://github.com/original-owner/project_online.git
git fetch online# 2. 選擇要合并的版本（標簽或分支）
TARGET_VERSION="v1.1"  # 替換為實際版本# 3. 更新 PyNvCodec
git subtree pull --prefix=vpf/PyNvCodec online $TARGET_VERSION -m "Update PyNvCodec to $TARGET_VERSION"# 4. 更新 PytorchNvCodec
git subtree pull --prefix=vpf/PytorchNvCodec online $TARGET_VERSION -m "Update PytorchNvCodec to $TARGET_VERSION"# 5. 保留本地修改的文件（根據情況看是否執行）
git checkout HEAD -- vpf/PyNvCodec/local_settings.py
git checkout HEAD -- vpf/PytorchNvCodec/custom_config.h

這種方法確保：

1. 精確更新指定目錄
2. 保留本地其他文件的修改
3. 維護清晰的提交歷史
4. 支持后續持續更新
5. 提供沖突解決機制

其他

關于git subtree pull 命令詳解：

git subtree pull --prefix=vpf/PyNvCodec online $TARGET_VERSION -m "Update PyNvCodec to $TARGET_VERSION" 這個命令是 Git 子樹策略的核心操作之一，下面我將詳細解釋其工作原理和每個參數的作用。

命令結構解析

命令部分	說明
git subtree pull	子樹拉取操作
--prefix=vpf/PyNvCodec	指定本地目標目錄
online	遠程倉庫別名
$TARGET_VERSION	要拉取的遠程版本（分支/標簽）
-m "Update PyNvCodec to $TARGET_VERSION"	合并提交信息

工作原理詳解

1. 子樹合并的本質

git subtree 是一種將外部倉庫作為子目錄集成到當前倉庫的策略。與子模塊不同，子樹的內容直接屬于主倉庫，不需要額外的引用文件。

2. 命令執行流程

當執行 git subtree pull 時，Git 會執行以下操作：

1. 創建臨時分支：在后臺創建一個臨時分支，包含遠程倉庫指定版本的內容
2. 提取子樹歷史：從臨時分支中提取與指定目錄相關的提交歷史
3. 重寫路徑：將遠程路徑重寫為本地 --prefix 指定的路徑
   • 遠程：PyNvCodec/file.txt → 本地：vpf/PyNvCodec/file.txt
4. 合并到當前分支：將重寫后的提交合并到當前分支
5. 創建合并提交：使用 -m 指定的消息創建合并提交
6. 清理臨時對象：刪除臨時分支和相關對象

3. 路徑映射機制

原始遠程結構：         本地映射后結構：
PyNvCodec/            vpf/PyNvCodec/
├── src/              ├── src/
├── inc/              ├── inc/
└── CMakeLists.txt    └── CMakeLists.txt

Git 會自動處理路徑轉換，確保遠程文件放入正確的本地目錄。

關鍵特性與優勢

1. 歷史保留

• 保留完整的提交歷史（包括作者、日期等信息）
• 可以通過 git log vpf/PyNvCodec 查看子樹歷史
• 保持原始提交哈希不變（通過重寫實現）

2. 雙向同步

• 拉取更新：git subtree pull
• 推送修改：git subtree push --prefix=... online branch
• 允許將本地修改推送回原始倉庫

3. 沖突處理

當子樹目錄有本地修改時：

1. Git 會自動嘗試合并
2. 如果自動合并失敗，會暫停并提示解決沖突
3. 解決沖突后使用 git commit 完成合并

4. 與普通合并的區別

特性	git subtree pull	普通 git merge
影響范圍	僅指定目錄	整個倉庫
歷史處理	重寫路徑后保留原始歷史	保留原始路徑
沖突概率	更低（僅限子樹目錄）	更高（整個倉庫）
工作目錄	不需要干凈狀態	需要干凈狀態

使用示例場景

初始添加子樹

# 首次添加子樹（創建初始提交）
git subtree add --prefix=vpf/PyNvCodec online v1.0.0 -m "添加PyNvCodec v1.0.0"

更新子樹

# 更新到新版本
git subtree pull --prefix=vpf/PyNvCodec online v1.2.0 -m "更新PyNvCodec到v1.2.0"

處理沖突

# 如果發生沖突
git mergetool -t vscode  # 使用VS Code解決沖突
git commit -m "解決PyNvCodec合并沖突"

查看子樹歷史

git log --graph --oneline --decorate -- vpf/PyNvCodec

高級選項

1. 壓縮歷史 (--squash)

git subtree pull --prefix=... --squash -m "更新"

• 優點：創建一個合并提交，不引入外部歷史，保持倉庫整潔
• 缺點：丟失詳細提交歷史，無法追溯子樹內部變更

2. 指定合并策略

git subtree pull --prefix=... -X theirs  # 優先使用遠程版本
git subtree pull --prefix=... -X ours    # 優先使用本地版本

3. 拆分子樹歷史

# 查看子樹歷史
git subtree split --prefix=vpf/PyNvCodec --rejoin

常見問題解決方案

1. 目錄不存在錯誤

   mkdir -p vpf/PyNvCodec  # 確保目標目錄存在
   touch vpf/PyNvCodec/.gitkeep  # 添加占位文件
   git add vpf/PyNvCodec/.gitkeep
   git commit -m "創建PyNvCodec目錄"
   

2. 權限拒絕錯誤

   # 確保沒有未提交的修改
   git status# 暫存當前修改
   git stash# 執行子樹拉取
   git subtree pull ...# 恢復暫存修改
   git stash pop
   

3. 大型倉庫優化

   # 淺層克隆歷史
   git subtree pull --prefix=... --squash# 限制歷史深度
   git config subtree.online.shallow true
   

與替代方案的比較

方案	優點	缺點
子樹策略	無需外部依賴，完整歷史	學習曲線較陡峭
子模塊	明確分離，易于更新	需要額外命令，協作復雜
手動復制	簡單直觀	丟失歷史，難以更新
倉庫合并	保留完整歷史	污染主倉庫歷史

git subtree pull 是管理項目內嵌外部代碼庫的專業解決方案，特別適合需要保留歷史同時精確控制更新范圍的情況。