How can I specify a branch/tag when adding a Git submodule?

git, git-submodules

Solution

Note: Git 1.8.2 added the possibility to track branches. See some of the answers below.

It's a little confusing to get used to this, but submodules are not on a branch. They are, like you say, just a pointer to a particular commit of the submodule's repository.

This means, when someone else checks out your repository, or pulls your code, and does git submodule update, the submodule is checked out to that particular commit.

This is great for a submodule that does not change often, because then everyone on the project can have the submodule at the same commit.

If you want to move the submodule to a particular tag:

cd submodule_directory
git checkout v1.0
cd ..
git add submodule_directory
git commit -m "moved submodule to v1.0"
git push

Then, another developer who wants to have submodule_directory changed to that tag, does this

git pull
git submodule update --init

`git pull` changes which commit their submodule directory points to. `git submodule update` actually merges in the new code.

Problem

How does `git submodule add -b` work? After adding a submodule with a specific branch, a new cloned repository (after `git submodule update --init`) will be at a specific commit, not the branch itself (`git status` on the submodule shows "Not currently on any branch"). I can't find any information on `.gitmodules` or `.git/config` about the submodule's branch or any specific commit, so how does Git figure it out? Also, is it possible to specify a tag instead of a branch?

Original source

Related problems