Changing an existing submodule's branch

Question

When I initially added my submodule, I specified a particular branch, as seen in the .gitmodule file:

[submodule "externals/grpc/grpc"]
    path = externals/grpc/grpc
    url = [email protected]:me/grpc.git
    branch = release-1.0

I want to change to the master branch of my submodule, so I changed the branch in .gitmodules from release-1.0 to master, and for good measure, just deleted the submodule from my parent git tree:

cd $submodules
rm -rf grpc
cd $gitroot
git submodule sync
git submodule update --init --recursive

Now, when I go back to my submodule, it's still checked out from a commit on the release-1.0 branch, not the latest master commit.

What steps am I missing to switch my submodule's branch?

Logroll

Answer 1

Go into the directory where the submodule resides and git checkout the correct branch/commit. Then go up one level and git add and git commit the directory. This will check in the submodule with the correct commit.

And don't forget to run git submodule update --recursive on the other clients after updating them.

Symbology

It is interesting that while git still points to the right commit (in the branch), the .gitmodules file does not include the branch field. It seems to work regardless of that, though. – Fifine

.gitmodules shows the branch you initially checked out. It is not updated when you change the branch, and has no effect. The actual branch you are on is stored int he submodule itself, not in this file - fwiw. – Hannie

Answer 2

Since v2.22(Q3 2019) (thanks to @VonC in comments)

Suppose you have submodule xyz, the .gitmodules looks like

$ cat .gitmodules
[submodule "xyz"]
        path = xyz
        url = [email protected]:xyz.git
        branch = main

And you can check it with

$ git config --file=.gitmodules -l
submodule.xyz.path=xyz
[email protected]:xyz.git
submodule.xyz.branch=main

Now you want to ref branch v1.0.0 for xyz, you can run

git submodule set-branch -b v1.0.0 xyz

Then to sync the conf

git submodule sync

To update content for submodule xyz

git submodule update --init --remote xyz

To update ALL submodules regardless of local changes

git submodule update --init --recursive --remote

Monocyclic

Note: it was introduced with Git 2.22 (Q3 2019). – Cadi

git submodule sync is what I was missing (not mentioned in a number of other answers)! – Dost

If you have other submodules, the git submodule update --init --recursive --remote command can sometimes mess them up, if somewhere they rely on being pinned to a specific commit. – Runstadler

Answer 3

If you want to switch to a branch you've never tracked before.

After you have changed the branch in .gitmodules, do the following:

git submodule update --init --recursive --remote
cd submodule_name
git checkout new_branch_name

Bifocal

For me the first line (git update) was enough – Ilocano

This almost worked for me. My error message included the line Unable to find current origin/origin/main revision in submodule path. My .gitmodules had the branch as branch = origin/main, so I changed it to just branch = main, then all was well. – Ambitious

Answer 4

The answer above (@milgner) didn't work me (git version 2.17.0). Maybe I did something wrong.

The below is what worked for me:

nano .gitmodules # substitute the needed branch here
git submodule update submodule_name # update the submodule
git add .gitmodules && git commit -m 'some comment' # add and commit
git submodule status # check that changes have been applied

Huntsman