如何跟踪已引入项目的Git文件/文件夹的上游变更？

刚好我之前处理过一模一样的场景——把上游仓库的单个文件/目录复制到自己项目里，不想改它但要同步上游更新，完全不用每次手动替换新版本，Git本身就有几种原生方案能搞定，给你详细说说：

1. git subtree（首推，无额外依赖，对仓库使用者友好） #

git subtree就是专门为这种“引入其他仓库子目录并持续同步”的场景设计的，它不需要像submodule那样让克隆你仓库的人额外执行命令，体验和普通文件目录几乎一致。

操作步骤：

• 先把上游仓库加为你的远程仓库（如果还没加）：

  git remote add upstream <上游仓库的URL>
  

• 把上游的目标子目录拉到你本地项目的指定路径（比如你已经放好的./third-party/tool）：

  git subtree add --prefix=./third-party/tool upstream main --squash
  

  这里--squash是把上游的所有相关提交压缩成一个，避免你的仓库提交记录被上游的历史填满；如果需要保留上游完整提交历史，可以去掉这个参数。
• 之后要同步上游变更时，只需要跑这一行：

  git subtree pull --prefix=./third-party/tool upstream main --squash
  

  Git会自动帮你合并上游的最新变更到你的目录里，因为你说不会修改这个目录，基本不会有冲突，就算有也和普通Git合并冲突的处理方式一样。

2. git submodule（适合需要独立跟踪版本的场景） #

如果这个子目录需要单独锁定某个特定版本，或者你希望它和上游仓库的版本关联更透明，可以用submodule。不过要注意，其他人克隆你的仓库时，需要额外执行git submodule init和git submodule update才能拉取到这个子目录的内容。

操作步骤：

• 添加子模块，指定上游仓库地址和本地存放路径：

  git submodule add --name tool-submodule <上游仓库URL> ./third-party/tool
  

  执行完后，你的仓库里会多出一个.gitmodules文件，记录子模块的关联信息。
• 同步上游变更时，进入子目录拉取最新代码，再回到主仓库提交版本更新：

  cd ./third-party/tool
  git pull origin main
  cd ../..
  git add ./third-party/tool
  git commit -m "Update tool submodule to latest upstream version"
  

3. Sparse Checkout（轻量方案，适合只需要极少量文件/目录的场景） #

你之前疑惑sparse checkout能不能解决，答案是肯定的——只要配置得当，它可以让你只拉取上游仓库的指定子目录，然后轻松同步更新。

操作步骤：

• 先添加上游远程仓库：

  git remote add upstream <上游仓库URL>
  

• 启用sparse checkout功能：

  git config core.sparseCheckout true
  

• 配置只拉取你需要的那个子目录（比如上游仓库里的/src/utils/）：

  echo "/src/utils/" >> .git/info/sparse-checkout
  

• 拉取上游分支到本地的一个专门跟踪分支：

  git fetch upstream
  git checkout -b upstream-track upstream/main
  

• 之后要同步上游变更时，先更新跟踪分支：

  git checkout upstream-track
  git pull upstream main
  

• 再把变更合并到你的主分支的目标目录里：

  git checkout main
  git merge upstream-track --strategy=ours --no-commit
  git read-tree --prefix=./third-party/utils/ -u upstream-track:src/utils
  git commit -m "Sync utils directory with upstream latest"
  

  这里--strategy=ours是确保主分支的其他文件不受影响，read-tree命令专门把上游子目录的内容同步到你指定的本地路径。

小提醒 #

如果你已经手动把文件复制到仓库里了，建议先把这些文件临时移走或者删除，再用上面的方法拉取，避免出现不必要的冲突。三个方案里，git subtree是最省心的，推荐优先尝试；submodule适合需要独立版本控制的场景；sparse checkout则更轻量，但操作步骤稍微繁琐一点。

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