Git分支同步超时主因是历史中残留大文件，即使已删除仍需传输完整对象链；应先用git rev-list排查，再通过--depth=1浅克隆或git filter-repo清洗历史。
Git分支同步超时，八成不是网络慢，而是你在拉一个“历史包袱很重”的分支——哪怕它现在干干净净，只要某次旧提交塞过 target/、dist/、.zip 或大模型权重文件，git 就得把整条对象链完整传输一遍。
查分支有没有历史大文件残留
直接进项目根目录跑这行命令：
git rev-list --objects --all | grep "$(git verify-pack -v .git/objects/pack/*.idx | sort -k3 -n | tail -5 | awk '{print $1}')" | head -10
看输出里是否出现 lib/、doc/、assets/large.bin 这类路径。如果有，说明问题不在当前分支代码，而在它的某个祖先提交里埋了雷。
- 别用
git rm --cached或git reset --hard——它们删不掉已打包进.git/objects的对象 - 临时救急？跳过历史：用
--depth=1；长期治理？用git filter-repo清洗（务必先备份整个.git目录） - 某些老 Git 版本（如 2.15 以下）不支持对单分支
fetch --depth=1，只能重新git clone --depth=1 -b branch-name
用 --depth=1 浅拉分支（最常用解法）
你不需要完整历史时，就别让 git 白算几万次 delta。CI/CD、临时调试、只跑构建，--depth=1 足够。
- 全新克隆：
git clone --depth=1 -b feature/x https://gitee.com/team/repo.git - 已有仓库想“变浅”：
git fetch --depth=1 origin feature/x，再git checkout -b feature/x origin/feature/x - 注意：
--depth=1后不能用git log --all或git blame跨提交追溯，但日常开发、测试、部署完全不受影响
确认 Git LFS 是否启用（团队协作高频坑）
如果别人 push 了 .psd、.bin 等大文件，而你拉不到，大概率是没装 Git LFS 客户端——LFS 文件在仓库里只是文本指针，内容存在 LFS 服务器上。
- 查远程是否启用了 LFS：
git ls-files | grep '\.gitattributes'，再看.gitattributes里有没有类似*.psd filter=lfs diff=lfs merge=lfs -text的规则 - 本地没装 LFS？运行
git lfs install（全局只需一次）；若提示command not found，得去https://git-lfs.github.com下对应平台二进制包 - 装完后执行
git lfs pull才能真正下载大文件内容，否则你看到的只是version https://git-lfs.github.com/spec/v1这样的空壳
Jenkins 或 CI 场景下调整超时与拉取策略
Jenkins 默认 10 分钟超时，对大仓库根本不够用，而且默认是全量 fetch。
- 在 Pipeline 中显式加
timeout: 30（单位分钟），比如：git branch: 'main', url: 'https://...', timeout: 30 - 启用浅克隆：
shallow: true，等价于--depth=1，大幅减少数据传输量 - 避免在 Jenkins 节点上反复
git pull——历史越积越多，下次更慢；建议每次构建都用新 workspace +shallow: true
真正难处理的从来不是“怎么拉下来”，而是“为什么必须拉全部历史”。很多团队卡在超时，是因为没人去翻 git rev-list 看一眼那几个被遗忘的提交里到底塞了什么——那个 dist/ 目录，可能早在三年前就被 rm -rf 了，但它还在 pack 文件里躺着，等着每一次 git pull 把它重新搬运一遍。
