Why is my Git Submodule HEAD detached from master

Question

I am using Git submodules  After pulling changes from server  many times my submodule head gets detached from master branch    Why does it happen   I have to always do   git branch git checkout master   How can I make sure that my submodule is always pointing to master branch

User · Answer

Adding a branch option in  gitmodule is NOT related to the detached behavior of submodules at all  The old answer from  mkungla is incorrect  or obsolete  From git submodule --help  HEAD detached is the default behavior of git submodule update --remote  First  there s no need to specify a branch to be tracked  origin master is the default branch to be tracked   --remote Instead of using the superproject s recorded SHA-1 to update the submodule  use the status of the submodule s remote-tracking branch  The remote used is branch s remote  branch  lt name gt  remote   defaulting to origin  The remote branch used defaults to master   Why So why is HEAD detached after update  This is caused by the default module update behavior  checkout   --checkout Checkout the commit recorded in the superproject on a detached HEAD in the submodule  This is the default behavior  the main use of this option is to override submodule  name update when set to a value other than checkout   To explain this weird update behavior  we need to understand how do submodules work  Quote from Starting with Submodules in book Pro Git  Although sbmodule DbConnector is a subdirectory in your working directory  Git sees it as a submodule and doesn   t track its contents when you   re not in that directory  Instead  Git sees it as a particular commit from that repository   The main repo tracks the submodule with its state at a specific point  the commit id  So when you update modules  you re updating the commit id to a new one  How If you want the submodule merged with remote branch automatically  use --merge or --rebase   --merge This option is only valid for the update command  Merge the commit recorded in the superproject into the current branch of the submodule  If this option is given  the submodule s HEAD will not be detached  --rebase Rebase the current branch onto the commit recorded in the superproject  If this option is given  the submodule s HEAD will not be detached   All you need to do is  git submodule update --remote --merge   or git submodule update --remote --rebase  Recommended alias  git config alias supdate  submodule update --remote --merge     do submodule update with git supdate  There s also an option to make --merge or --rebase as the default behavior of git submodule update  by setting submodule  name update to merge or rebase  Here s an example about how to config the default update behavior of submodule update in  gitmodule   submodule  quot bash plugins dircolors-solarized quot       path   bash plugins dircolors-solarized     url   https   github com seebi dircolors-solarized git     update   merge    lt -- this is what you need to add  Or configure it in command line    replace  name with a real submodule name git config -f  gitmodules submodule  name update merge  References  git submodule --help Submodules tutorial from book Pro Git

User · Answer

The simplest solution is   git clone --recursive git github com name repo git   Then cd in the repo directory and   git submodule update --init git submodule foreach -q --recursive  git checkout   git config -f  toplevel  gitmodules submodule  name branch    echo master   git config --global status submoduleSummary true   Additional reading  Git submodules best practices

User · Answer

As other people have said  the reason this happens is that the parent repo only contains a reference to  the SHA1 of  a specific commit in the submodule     it doesn t know anything about branches  This is how it should work  the branch that was at that commit may have moved forward  or backwards   and if the parent repo had referenced the branch then it could easily break when that happens   However  especially if you are actively developing in both the parent repo and the submodule  detached HEAD state can be confusing and potentially dangerous  If you make commits in the submodule while it s in detached HEAD state  these become dangling and you can easily lose your work   Dangling commits can usually be rescued using git reflog  but it s much better to avoid them in the first place    If you re like me  then most of the time if there is a branch in the submodule that points to the commit being checked out  you would rather check out that branch than be in detached HEAD state at the same commit  You can do this by adding the following alias to your gitconfig file    alias      submodule-checkout-branch     f     git submodule -q foreach  branch   git branch --no-column --format     refname short    --points-at  git rev-parse HEAD    grep -v   HEAD detached     head -1   if      -z  branch  amp  amp  -z  git symbolic-ref --short -q HEAD      then git checkout -q    branch    fi      f    Now  after doing git submodule update you just need to call git submodule-checkout-branch  and any submodule that is checked out at a commit which has a branch pointing to it will check out that branch  If you don t often have multiple local branches all pointing to the same commit  then this will usually do what you want  if not  then at least it will ensure that any commits you do make go onto an actual branch instead of being left dangling   Furthermore  if you have set up git to automatically update submodules on checkout  using git config --global submodule recurse true  see this answer   you can make a post-checkout hook that calls this alias automatically     cat  git hooks post-checkout     bin sh git submodule-checkout-branch   Then you don t need to call either git submodule update or git submodule-checkout-branch  just doing git checkout will update all submodules to their respective commits and check out the corresponding branches  if they exist

User · Answer

I am also still figuring out the internals of git  and have figured out this so far   HEAD is a file in your  git  directory that normally looks something like this     cat  git HEAD ref  refs heads master   refs heads master is itself a file that normally has the hash value of the latest commit     cat  git refs heads master  cbf01a8e629e8d884888f19ac203fa037acd901f   If you git checkout a remote branch that is ahead of your master  this may cause your HEAD file to be updated to contain the hash of the latest commit in the remote master     cat  git HEAD 8e2c815f83231f85f067f19ed49723fd1dc023b7  This is called a detached HEAD  The remote master is ahead of your local master  When you do git submodule --remote myrepo to get the latest commit of your submodule  it will by default do a checkout  which will update HEAD  Since your current branch master is behind  HEAD becomes  detached  from your current branch  so to speak

User · Answer

EDIT   See  Simba Answer for valid solution     submodule  lt name gt  update is what you want to change  see the docs  - default checkout   submodule  lt name gt  branch specify remote branch to be tracked - default master       OLD ANSWER   Personally I hate answers here which direct to external links which may stop working over time and check my answer here  Unless question is duplicate  - directing to question which does cover subject between the lines of other subject  but overall equals   I m not answering  read the documentation    So back to the question  Why does it happen   Situation you described      After pulling changes from server  many times my submodule head gets detached from master branch    This is a common case when one does not use submodules too often or has just started with submodules  I believe that I am correct in stating  that we all  have been there at some point where our submodule s HEAD gets detached     Cause  Your submodule is not tracking correct branch  default master   Solution  Make sure your submodule is tracking the correct branch     cd  lt submodule-path gt    if the master branch already exists locally     From git docs - branch    -u  lt upstream gt    --set-upstream-to  lt upstream gt       Set up  lt branchname gt  s tracking information so  lt upstream gt       is considered  lt branchname gt  s upstream branch       If no  lt branchname gt  is specified  then it defaults to the current branch    git branch -u  lt origin gt   lt branch gt   lt branch gt    else    git checkout -b  lt branch gt  --track  lt origin gt   lt branch gt     Cause  Your parent repo is not configured to track submodules branch  Solution  Make your submodule track its remote branch by adding new submodules with the following two commands    First you tell git to track your remote  lt branch gt   you tell git to perform rebase or merge instead of checkout you tell git to update your submodule from remote           git submodule add -b  lt branch gt   lt repository gt    lt submodule-path gt         git config -f  gitmodules submodule  lt submodule-path gt  update rebase       git submodule update --remote    If you haven t added your existing submodule like this you can easily fix that    First you want to make sure that your submodule has the branch checked out which you want to be tracked            cd  lt submodule-path gt        git checkout  lt branch gt        cd  lt parent-repo-path gt         lt submodule-path gt  is here path releative to parent repo root       without starting path separator       git config -f  gitmodules submodule  lt submodule-path gt  branch  lt branch gt        git config -f  gitmodules submodule  lt submodule-path gt  update  lt rebase merge gt    In the common cases  you already have fixed by now your DETACHED HEAD since it was related to one of the configuration issues above   fixing DETACHED HEAD when  update   checkout    cd  lt submodule-path gt    and make modification to your submodule   git add     git commit -m Your modification    Let s say you forgot to push it to remote    cd  lt parent-repo-path gt    git status   you will get Your branch is up-to-date with   lt origin gt   lt branch gt    Changes not staged for commit      modified    path to submodule  new commits    As normally you would commit new commit hash to your parent repo   git add -A   git commit -m Updated submodule    git push  lt origin gt   lt branch gt     git status Your branch is up-to-date with   lt origin gt   lt branch gt    nothing to commit  working directory clean   If you now update your submodule   git submodule update --remote Submodule path  path to submodule   checked out  commit-hash    git status   will show again that  submodule has new commits    cd  lt submodule-path gt    git status HEAD detached at  lt hash gt    as you see you are DETACHED and you are lucky if you found out now   since at this point you just asked git to update your submodule   from remote master which is 1 commit behind your local branch   since you did not push you submodule chage commit to remote     Here you can fix it simply by   in submodules path    git checkout  lt branch gt    git push  lt origin gt   lt branch gt    which will fix the states for both submodule and parent since    you told already parent repo which is the submodules commit hash    to track so you don t see it anymore as untracked    But if you managed to make some changes locally already for submodule and commited  pushed these to remote then when you executed  git checkout    Git notifies you     git checkout  lt branch gt  Warning  you are leaving 1 commit behind  not connected to any of your branches  If you want to keep it by creating a new branch  this may be a good time to do so with    The recommended option to create a temporary branch can be good  and then you can just merge these branches etc  However I personally would use just git cherry-pick  lt hash gt  in this case     git cherry-pick  lt hash gt    hash which git showed you related to DETACHED HEAD   if you get  error  could not apply     run mergetool and fix conflicts   git mergetool   git status   since your modifications are staged just remove untracked junk files   rm -rf  lt untracked junk file s  gt    git commit   without arguments   which should open for you commit message from DETACHED HEAD   just save it or modify the message    git push  lt origin gt   lt branch gt    cd  lt parent-repo-path gt    git add -A   or just the unstaged submodule   git commit -m Updated  lt submodule gt     git push  lt origin gt   lt branch gt    Although there are some more cases you can get your submodules into DETACHED HEAD state  I hope that you understand now a bit more how to debug your particular case

User · Answer

Check out my answer here  Git submodules  Specify a branch tag  If you want  you can add the  branch   master  line into your  gitmodules file manually  Read the link to see what I mean    EDIT  To track an existing submodule project at a branch  follow VonC s instructions here instead   Git submodules  Specify a branch tag

User · Answer

The other way to make your submodule to check out the branch is to go the  gitmodules file in the root folder and add the field branch in the module configuration as following   branch    lt branch-name-you-want-module-to-checkout gt

User · Answer

i got tired of it always detaching so i just use a shell script to build it out for all my modules  i assume all submodules are on master  here is the script      bin bash echo  Good Day Friend  building all submodules while checking out from MASTER branch    git submodule update  git submodule foreach git checkout master  git submodule foreach git pull origin master    execute it from your parent module

[git] Why is my Git Submodule HEAD detached from master?

Why

How

References

Examples related to git

Examples related to git-submodules