指定--branch与--depth 1添加Git子模块失败问题排查

问题重现 #

执行以下命令添加指定分支的浅克隆子模块时，出现检出错误：

GIT_TRACE=true git submodule add -b branch_1.1.0 --depth 1 https://oauth2:****@gitlab.test.ir/repo.git path

报错信息：

fatal: 'origin/branch_1.1.0' is not a commit and a branch 'branch_1.1.0' cannot be created from it
fatal: unable to checkout submodule 'path'

从Git追踪日志可以看到，底层执行的克隆命令没有携带--branch branch_1.1.0参数：

git clone --no-checkout --depth 1 --separate-git-dir /tmp/repo/.git/modules/path -- https://oauth2:****@gitlab.test.ir/repo.git /tmp/repo/path

核心原因 #

这是Git版本兼容性问题：在Git 2.22版本之前，git submodule add命令存在bug，当同时使用--depth（浅克隆）和-b（指定分支）参数时，不会将-b参数传递给底层的git clone命令。

这导致浅克隆只会拉取远程仓库的默认分支（如main/master），而不是你指定的branch_1.1.0。后续执行checkout -B branch_1.1.0 origin/branch_1.1.0时，本地仓库中根本没有origin/branch_1.1.0的引用，自然会报错。

解决方法 #

方法1：升级Git版本 #

将Git升级到2.22及以上版本，该版本修复了git submodule add传递--branch参数给克隆命令的问题，升级后直接执行原命令即可正常工作。

方法2：手动分步操作（无需升级Git） #

如果无法升级Git，可以通过手动分步操作实现需求：

1. 先在主项目中初始化子模块条目：

   git submodule add --name path https://oauth2:****@gitlab.test.ir/repo.git path
   

2. 编辑.gitmodules文件，为该子模块添加分支配置：

   [submodule "path"]
       path = path
       url = https://oauth2:****@gitlab.test.ir/repo.git
       branch = branch_1.1.0
   

3. 执行浅克隆更新子模块：

   git submodule update --init --depth 1 --remote path
   

或者直接先手动克隆子模块到目标路径，再添加到主项目：

# 先手动克隆指定分支的浅版本
git clone --depth 1 -b branch_1.1.0 https://oauth2:****@gitlab.test.ir/repo.git path
# 将该目录添加为子模块
git submodule add https://oauth2:****@gitlab.test.ir/repo.git path

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