关于git子仓问题之 git checkout * error: pathspec ‘test‘ did not match any file(s) known to git

关于为啥子仓下git fetch test 最新点，但是git checkout test时却报错：error: pathspec ‘develop_6521_t22’ did not match any file(s) known to git的问题解决

✅ 你能顺利 fetch 分支，但无法 checkout 分支

原因是：

git fetch origin test --depth=1

只会把分支下载成FETCH_HEAD，不会在本地创建origin/test引用。

这就是你 checkout 会失败的根本原因。

🔥【根本原因】

git fetch origin test --depth=1
不会创建远程跟踪分支（remote-tracking branch）

例如：

origin/test❌ 不会出现 FETCH_HEAD ✔️ 会出现

所以你看到这个：

git checkout test error: pathspec did not match

不是你写错，而是Git 根本没有这条分支。

🔥【解决方法】两种可选方式

✅ 方案 1：创建本地分支，基于 FETCH_HEAD（推荐）

这是最干净、无副作用的方式：

git fetch origin test --depth=1 git checkout -b test FETCH_HEAD

这样：

• 拉最新 commit
• 基于 FETCH_HEAD 创建本地分支
• 不依赖 remote tracking branch

✔ 完美切换成功
✔ 不需要 origin/test 存在
✔ Jenkins 最稳定

❤️ 推荐你在 Jenkins 写成这样：

- call: Git.cmd credentialsId: BCC1WX_SSH_KEY exec: | echo "===== Update Submodule =====" cd asw/mw/camera/board # Fetch the specific branch (shallow) git fetch origin test --depth=1 || { echo "Fetch failed"; exit 1; } # Checkout local branch based on FETCH_HEAD git checkout -B test FETCH_HEAD || { echo "Checkout failed"; exit 1; } echo "===== Latest Commit =====" git log --oneline -1 fromPath: .

✔ 永远成功
✔ 不依赖 remote tracking branch
✔ 适合 CI

✅ 方案 2：强制创建 remote tracking branch（不推荐，但可以）

git fetch origin test:refs/remotes/origin/test --depth=1 git checkout test

但一般 Jenkins 子模块不建议这么写。

📌 结论（非常重要）

你现在 fetch 能成功，但 checkout 失败，是因为你拉下来的只是：

FETCH_HEAD

不是：

origin/test

所以应该这么写：

git fetch origin test--depth=1 git checkout -B test FETCH_HEAD

问题1 ：

root$ git fetch origin test Warning: Permanently added '[ssss2vsad94.qq.dssf.com]:2991' (RSA) to the list of known hosts. remote: Enumerating objects: 1595, done. remote: Counting objects: 100% (716/716), done. remote: Compressing objects: 100% (396/396), done. remote: Total 408 (delta 295), reused 2 (delta 0), pack-reused 0 Receiving objects: 100% (408/408), 91.10 KiB | 4.55 MiB/s, done. Resolving deltas: 100% (295/295), completed with 101 local objects. From ssh://ssss2vsad94.qq.dssf.com:2991/lucj/caoeko * branch test-> FETCH_HEAD root$ git checkout test error: pathspec 'test' did not match any file(s) known to git

这不是你命令写错，而是子模块本身的 Git 仓库状态导致的。

1️⃣ 现象回顾

你执行：

gitfetch origintest

输出：

* branch test-> FETCH_HEAD

然后：

gitcheckouttest

报错：

error: pathspec 'test' did not match any file(s) known to git

2️⃣ 根本原因

(A) FETCH_HEAD ≠ remote-tracking branch

• git fetch origin test只把远端最新 commit 拉下来到FETCH_HEAD
• 不会在本地创建 remote-tracking branchorigin/test
• 所以直接git checkout test会失败（本地没有这个分支）

(B) 子模块的特殊性

• 子模块一般初始化后默认是 detached HEAD
• 本地没有完整分支结构
• .gitmodules并不一定记录远端分支，只记录 commit
• 你即使 fetch，也不会自动创建本地分支或 remote-tracking branch

所以在子模块里 fetch 后，想直接checkout <branch>就会失败，这是子模块特有的坑。

3️⃣ 正确做法

💡 方法 1：checkout FETCH_HEAD（最简单、稳妥）

cdaaa/bb/ccccc/dddddddgitfetch origintestgitcheckout -BtestFETCH_HEAD

• -B：如果本地已有同名分支，会强制重建
• FETCH_HEAD：保证你切到最新 commit
• 不会依赖 remote-tracking branch
• 完全适合 Jenkins / CI / 子模块环境

💡 方法 2：创建 remote-tracking branch（可选）

gitfetch origin test:refs/remotes/origin/testgitcheckout -btestorigin/test

• 会在本地创建 remote-tracking branch
• 可以直接 checkout
• 但是在子模块 + shallow clone 下，CI 环境容易报错，不推荐

4️⃣ 为什么即使不加--depth=1也不行

即使你执行：

gitfetch origintest

• 你仍然看到FETCH_HEAD
• 子模块默认处于 detached HEAD
• Git不会自动把远端分支写入 origin/
• 因此git checkout test仍然失败

✅ 所以这不是 fetch 深度的问题，也不是命令错
❌ 这是子模块本地状态决定的行为

5️⃣ 推荐 Jenkins 子模块更新脚本（100% 稳定）

-call:Git.cmdcredentialsId:BBBBBBexec:|echo "===== Update Submodule =====" cd aaa/bb/ccccc/ddddddd git fetch origin test # 切换到最新 commit（不依赖 remote-tracking branch） git checkout -B develop_6521_t22 FETCH_HEAD echo "===== Latest Commit ====="fromPath:.

• ✅ 不依赖 remote-tracking branch
• ✅ 适合 detached HEAD 的子模块
• ✅ 永远指向远端最新 commit
• ✅ Jenkins CI 最稳

问题二：

+ git fetch origin test --depth=1 Warning: cddsas From ssh://ssss2vsad94.qq.dssf.com:2991/lucj/caoeko * branch test -> FETCH_HEAD + git checkout -b test FETCH_HEAD fatal: a branch named 'test ' already exists

还是会报错 fatal

fatal: a branch named 'develop_6521_t22' already exists

也就是说Jenkins 上这个子模块里本地已经有一个同名分支test，而你之前用的命令是：

gitcheckout -btestFETCH_HEAD

• -b表示创建新分支
• 如果本地已经有同名分支，就会失败 → 所以出现这个 fatal 错误

🔹 解决办法

方法 1：使用-B强制重建分支（推荐）

gitcheckout -BtestFETCH_HEAD

• -B=--force -b
• 如果分支不存在，就创建
• 如果分支存在，就重置到 FETCH_HEAD
• 在 Jenkins CI / 子模块环境最稳妥

完整示例：

-call:Git.cmdcredentialsId:BBBBBBBBBBBBexec:|cd aaaa/bb/cccccc/ddddd git fetch origin test--depth=1 git checkout-B testFETCH_HEADfromPath:.

方法 2：先删除已有分支（可选，不推荐）

gitbranch -Dtestgitcheckout -btestFETCH_HEAD

• 效果和-B一样
• 但是多了一条命令
• 如果其他地方引用该分支，可能不安全

问题三

方式一： - call: Git.cmd credentialsId: BBBBBB exec: | echo "===== Update Submodule =====" cd aaa/bb/ccccc/ddddddd git fetch origin test # 切换到最新 commit（不依赖 remote-tracking branch） git checkout -B develop_6521_t22 FETCH_HEAD echo "===== Latest Commit =====" fromPath: . 方式二 - call: Git.cmd credentialsId: BBBBBBBBBBBB exec: git submodule set-branch --branch test aaaa/bb/cccccc/ddddd fromPath: . - call: Git.cmd credentialsId: BBBBBBBBBBBB exec: git submodule sync aaaa/bb/cccccc/ddddd fromPath: . - call: Git.cmd credentialsId: BBBBBBBBBBBB exec: git submodule update --remote --checkout aaaa/bb/cccccc/ddddd fromPath: .

两种方式的差别Jenkins CI 里操作 Git 子模块的方法，但本质上逻辑和可靠性有明显区别。

1️⃣ 第一种写法（手动 fetch + checkout）

-call:Git.cmdcredentialsId:BBBBBBexec:|cd aaa/bb/ccccc/ddddddd git fetch origin test git checkout -B test FETCH_HEADfromPath:.

特点

1. 直接操作子模块目录

   • cd aaa/bb/ccccc/ddddddd进入子模块目录

2. fetch 特定分支最新 commit

   • git fetch origin test只拉这个分支

3. 强制切换本地分支到 FETCH_HEAD

   • git checkout -B develop_6521_t22 FETCH_HEAD
   • 如果本地分支已存在，会重置到最新 commit

4. 不依赖子模块远程-tracking branch

   • FETCH_HEAD 是最新 commit，不管本地分支历史

优点

• 最稳妥：总能指向最新 commit
• 可控性高：你明确知道 fetch 哪个分支，checkout 到哪一 commit
• 不会依赖 submodule 的默认行为（比如.gitmodules配置的 branch）

缺点

• 需要手动写 cd
• 多子模块重复操作麻烦
• 需要你自己保证 fetch 的分支名称正确

2️⃣ 第二种写法（使用 submodule set-branch / sync / update）

-call:Git.cmdcredentialsId:BBBBBBBBBBBBexec:git submodule set-branch--branch test aaaa/bb/cccccc/dddddfromPath:.-call:Git.cmdcredentialsId:BBBBBBBBBBBBexec:git submodule sync aaaa/bb/cccccc/dddddfromPath:.-call:Git.cmdcredentialsId:BBBBBBBBBBBBexec:git submodule update--remote--checkout aaaa/bb/cccccc/dddddfromPath:.

特点

1. 依赖 Git submodule 自带命令

   • set-branch指定子模块要跟踪的分支
   • sync同步 URL
   • update --remote --checkout拉取远端分支最新 commit 并 checkout

2. 不需要手动 cd，Git 会自动处理

3. 依赖.gitmodules的路径配置

优点

• 简洁：子模块命令一次性搞定
• 维护简单：多个子模块可统一管理

缺点

• 不够可控：如果远端分支不存在或者 fetch 出现问题，可能 checkout 不成功
• 历史问题：update --remote默认是 fetch + merge，如果有本地修改可能失败
• 有时不可靠：在 Jenkins CI + shallow clone 环境下，可能抓不到远端最新 commit，或者 checkout 成功率低

3️⃣ 对比总结

✅ 建议

• Jenkins CI / 自动化构建环境：
  推荐方法 1（手动 fetch + checkout）

  • 明确指向远端 commit
  • 可控、稳妥
  • 支持 shallow clone

• 如果只是本地开发或多人开发：
  方法 2 更方便，命令简单