CMake FetchContent克隆特定GIT哈希时出现‘reference is not a tree’错误

为什么需要额外执行git fetch命令 #

• 默认的git clone --no-checkout操作只会拉取仓库默认分支（通常为main或master）的提交数据，不会主动拉取其他分支或不在默认分支历史中的孤立提交。
• 你的目标提交哈希c06d39b285754e62f421b5f36e123ca620a5482d不在默认分支的历史链中，导致克隆后的本地仓库没有该提交的对象数据，因此直接执行git checkout会报错。
• git fetch --depth 1 origin <commit-hash>的作用是从远程仓库精准拉取该特定提交的完整数据，让本地仓库能够识别并检出这个提交。

解决FetchContent报错的方案 #

以下几种方法可以让CMake自动处理提交拉取的问题：

方法1：添加GIT_FETCH_ARGS参数 #

在FetchContent_Declare中指定拉取目标提交的参数，让CMake在克隆后自动执行fetch操作：

FetchContent_Declare(
    MyExternal
    PREFIX prefix TMP_DIR tmp STAMP_DIR stamp LOG_DIR log DOWNLOAD_DIR download SOURCE_DIR source BINARY_DIR binary INSTALL_DIR install 
    GIT_REPOSITORY https://myexternal.com/myexternal.git
    GIT_TAG c06d39b285754e62f421b5f36e123ca620a5482d
    GIT_PROGRESS TRUE
    GIT_CONFIG http.sslVerify=false
    GIT_SHALLOW FALSE
    GIT_FETCH_ARGS --depth 1 origin c06d39b285754e62f421b5f36e123ca620a5482d
)
FetchContent_MakeAvailable(MyExternal)

方法2：拉取所有分支的提交数据 #

如果仓库体积不大，可以添加--no-single-branch参数让克隆操作获取所有分支的历史数据，确保目标提交被包含在内：

FetchContent_Declare(
    MyExternal
    PREFIX prefix TMP_DIR tmp STAMP_DIR stamp LOG_DIR log DOWNLOAD_DIR download SOURCE_DIR source BINARY_DIR binary INSTALL_DIR install 
    GIT_REPOSITORY https://myexternal.com/myexternal.git
    GIT_TAG c06d39b285754e62f421b5f36e123ca620a5482d
    GIT_PROGRESS TRUE
    GIT_CONFIG http.sslVerify=false
    GIT_SHALLOW FALSE
    GIT_CLONE_ARGS --no-single-branch
)

方法3：清理本地缓存后重试 #

如果之前的克隆操作留下了不完整的缓存数据，删除source目录和CMake的FetchContent缓存目录（通常在CMakeCache.txt所在目录的_deps文件夹下），再重新运行CMake配置，确保从干净状态开始拉取。

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