git submodule HEAD detached 的问题

最新推荐文章于 2026-06-14 00:02:49 发布

原创

最新推荐文章于 2026-06-14 00:02:49 发布 · 2.8k 阅读

收录于

本文详细解析了在使用Git子模块时遇到的游离头问题原因及解决方法，包括重新建立子模块和使用特定命令修复所有子模块的游离头状态。

在使用git submodule 的时候，常常会遇到执行完以下操作后发现子仓库的head 指针处于游离状态

git clone xxxxx.git
git submodule update --init

然后切换到子仓库，查看当前分支的状态如下
在这里插入图片描述
原因是之前同事在子仓库中修改并提交后，没有在父仓库中更新子仓库的最新提交记录
正常情况下，修改子仓库的内容并在子仓库提交后会在父仓库执行 git diff会有如下输出

解决git submodule head detached的方法：

重新建立submodule，加入时使用-b参数，使得母项目追踪子项目的指定branch（否则默认不追踪）：

git submodule add -b <branch> <repository> [<submodule-path>]
git submodule update --remote

简单的一行命令递归修复所有子项目的detached head（其中默认都追踪子项目的master branch）：

git submodule foreach -q --recursive 'git checkout $(git config -f $toplevel/.gitmodules submodule.$name.branch || echo master)

最低0.47元/天解锁文章

确定要放弃本次机会？

福利倒计时

: :

立减 ¥

普通VIP年卡可用

立即使用

YuZhuQue

关注关注

2
点赞
踩
7

收藏

觉得还不错? 一键收藏
0
评论
分享

复制链接

分享到 QQ

分享到新浪微博

扫一扫
举报

举报

专栏目录

详解git submodule HEAD detached 的问题

10-14

主要介绍了详解git submodule HEAD detached 的问题，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧

Git Submodule 的更新与管理策略

m0_62153576的博客

11-29

摘要：本文探讨了Git子模块(Submodule)的更新与管理策略，重点解决子模块处于"detached HEAD"状态的常见问题。文章介绍了子模块的基本概念和初始状态，详细讲解了克隆和初始化子模块的正确方法，并提供了两种更新策略：使用--merge/--rebase选项自动处理更新，或手动拉取变更后同步主项目引用。通过具体实例演示了如何避免"detached HEAD"状态，确保子模块与主项目同步更新。这些方法能有效提升Git子模块管理的效率。

参与评论您还未登录，请先登录后发表或查看评论

修复git submodule引起的detached head

silent56_th的博客

11-07

5184

总结自： Why is my GIT Submodule HEAD detached from master? Git submodules best practices 上文记录了在子项目内修复detached head的方法，使用中发现是因为submodule使用不当引起的，当clone项目到其他位置时子项目内仍然是detached head。若对每个子项目都是用上文方法修复太过于麻烦，所...

Git - submodule 小记

幻世

03-11

2180

一些对 submodule 疑惑的整理

【Git】Git submodule常用指令

All_In_gzx_cc的博客

12-13

7789

文章出自个人博客 https://knightyun.github.io/2021/03/21/git-submodule，总结的很详细，本文只做学习记录，方便自己查阅~

git submodule 使用

liubangbo的专栏

10-19

1992

文章转自：https://segmentfault.com/a/1190000020297996?utm_source=tag-newest 背景在做不同的项目，但是又都会使用到一些常用的方法组件代码块等等。作为一个追求优雅的开发人员，肯定不能接受一段代码到处复制粘贴的操作。而且一旦这段代码日后需要更新，到处粘贴的话就需要全局搜索然后含泪修改了。那么有没有一种办法，能够作为一些公共代码的“栖息地”，可以做到一处编写，到处使用呢？答案是有的，使用git内置功能submodule即可。什么是Su

submodule切换分支_使用Git Submodule可能遇到的坑

weixin_39949413的博客

12-21

3149

前言对于一些比较大的工程，为了便于复用，常常需要抽取子项目。例如我开发的猿题库客户端现在包括3门考试，客户端涉及的公共UI、公共底层逻辑、公共的第三方库、以及公共的答题卡扫描算法就被我分别抽取成了子项目。这些子项目都以git submodule的形式，增加到工程中。在使用了git submodule一段时间后，我发现了一些submodule的问题，在此分享给大家。更新submodule的坑subm...

Git Submodule 深度避坑指南

专注Android开发与面试题深度解析。分享源码、性能优化、Jetpack、Compose等进阶干货，以及大厂真题解题思路。拒绝废话，直击重点，帮你建立完整知识体系。

04-20

508

Git Submodule深度避坑指南摘要： Submodule本质是主仓库记录子仓库特定提交的指针而非完整代码，这导致常见8大问题：克隆后子模块为空、更新不同步、分支切换混乱、CI失败等。关键要理解主仓库和子模块的双重提交机制：子模块更新后必须同步更新主仓库指针。核心命令包括递归初始化(--recursive)、同步配置(sync)和状态检查。团队需规范克隆、更新流程，特别注意CI环境和权限问题，避免因指针不一致导致的协作问题。掌握子模块引用机制能有效解决90%的同步和版本控制难题。

第6章：子模块与子树——大仓拆小仓的陷阱

最新发布

sfishfly的博客

06-14

223

`git submodule` 的完整生命周期——添加、更新、克隆、删除。子模块 detached HEAD 状态的成因与解决方案。`git subtree` 与 `git submodule` 的对比与选型决策树。 > **配套资源**：一个包含三个子模块的复杂依赖仓库 Docker 镜像、子模块批量更新脚本、subtree 合并推送脚本。 > **真实踩坑**：我曾修改子模块代码后忘记提交，主仓库记录了不存在的 commit hash，导致 CI/CD 全线飘红；还曾因为子模块嵌套过深，`git

git submodule update 游离分支临时分支问题记录解决办法

qq_38292379的博客

05-24

1687

git submodule update --init git pull origin master --recuresive-submodule 拉取子模块代码，子模块显示在临时分支上 $ git branch * (HEAD detached at da3251f) branch01 master 可以理解为submodule update拉取代码使用了checkout命令，而不关注具体是什么分支 git checkout xxx 因此在拉取子模块代码后，如果要进行开发，记得执行 $

Git Submodule 使用简介

allanGold

11-01

937

D瓜哥从去年开始，将所有的笔记都整合到了自建的 Wiki 中。整理分析，确实方便很多。最近有两个部分，比较独立，自成系统。其中，有一个模块还考虑和其他小伙伴合作来搞。所以，就将这两部分抽取出来，独立成单独的项目来维护。但是，为方便查看和随时随地同步更新，正好可以使用 Git Submodule 特性。另外，还有一种场景：开发的项目使用了第三方或者公司的基础库，使用同一个版本库肯定不

git clone命令_Git Submodule 命令与理解

weixin_39943370的博客

11-29

4142

TL;DR# Add submodule git submodule add 定义git submodule允许用户将一个 Git 仓库作为另一个 Git 仓库的子目录。它能让你将另一个仓库克隆到自己的项目中，同时还保持提交的独立性。作用在我这里，它的作用非常明确，即给在各个项目中都会用到的代码段一个公共栖息地，做到“一处改，处处改”。常用命令添加git submodule add# 直接c...

Git Submodule 使用

q752933833的博客

05-23

4975

himg git 的 submodule 作为一个独立的 repo, 其拥有普通 repo 全部的功能, 我们可以完全按照普通的 repo 管理命令来进入 submodule 中进行手动管理. 不过如果存在多个 submodule 位于同一 superproject 下时, 掌握一些 git submodule ... 命令就变得尤为重要了. 本文列出了常用的一些 git submodule 管理命令, 并举出实际应用中遇到的问题及解决方案. submodule 介绍在 git 仓库 superproj

git提醒---HEAD detached

Andy的博客

12-09

1455

git提醒---HEAD detached detached HEAD：表示HEAD指针已经是游离状态，没有指向Master分支，或者本地的任何一个具体分支，而是指向了一个commit_id。

Git游离指针状态

Hello World ^—^

01-10

2215

问题描述：有次在idea中提交git发生了这样的情况，当初上一个操作之前还提示了stash changes的，然后就进入了游离指针状态在这里可以发现这里的git分支指向的不是当前任何分支游离状态本质上是本地的HEAD 指向了一个未知的分支，HEAD不会指向任何分支,严谨的说是HEAD指向了一个没有分支名字的修订版本 git checkout本质上是修改HEAD里面的内容来让它指向...

超详细的Git submodule讲解以及出现分离头指针（detached HEAD）的解决方法

Gu_n_ian_的博客

10-22

1838

Git submodule 是对父仓库中的子仓库进行管理的命令命令用于管理包含其他 Git 仓库的项目。命令对于大型项目或需要将外部库集成到项目中的情况非常有用。通过使用子模块，你可以将外部库作为你的项目的一部分来管理，而不必将其直接合并到主仓库中。

git submodule 操作

ox0080的博客

03-20

788

Git 使用submodule 管理外链库 submodule 是固定conle 的commit，默认是head 执行执行```git submodule add```或对于新clone下来宿主项目执行 ```git submodule update```后，得到的submodule是处于头指针脱离状态，在其目录中执行git branch可以看到当前没有指向任何分支。去.git/modu...

TortoiseGit对submodule进行commit、push的问题：Current HEAD Detached

玄冬Wong

05-04

3006

如果提交submodule的时候提示这个信息：Current HEAD Detached，说明submodule已经和远程仓库脱离开了，如果你submodule中有未提交的改动，一定要手动备份下。然后在submodule所在的目录下，右键-》TortoiseGit-》switch/checkout-》Branch选择：Master，然后点击确定，然后再在当前submodule下进...

git问题记录--如何从从detached HEAD状态解救出来

积硅步

03-21

8868

今天使用git的时候在终端发现这样一条信息 HEAD detached at head 分析心里一惊,艾玛这是什么状态? 其实我们知道,git checkout本质上是修改HEAD里面的内容来让它指向不同分支的,而HEAD文件指向的分支就是我们当前的分支,但是有时候HEAD不会指向任何分支,严谨的说是HEAD指向了一个没有分支名字的修订版本,此时恭喜你,已经处于游离状态了(detache

git submodule使用方法

蚂蚁搬家

03-17

6227

1. submodule简介 submodule是一种git特性，用以将一部分公共代码从主项目中抽离出来成为一个独立的git工程，并以submodule的形式被主项目使用，submodule和主项目（或者叫主模块）充分解耦，这样做的好处是作为submodule的公共代码可以被多个主项目工程使用，减少了开发量和版本控制负担。同时，submodule作为独立的git工程，也使得权限管理、版本迭代更加灵...