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

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_directorygit checkout v1.0cd ..git add submodule_directorygit 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 pullgit submodule update --init

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

I'd like to add an answer here that is really just a conglomerate of other answers, but I think it may be more complete.

You know you have a Git submodule when you have these two things.

1. Your .gitmodules has an entry like so:

   [submodule "SubmoduleTestRepo"]    path = SubmoduleTestRepo    url = https://github.com/jzaccone/SubmoduleTestRepo.git

2. You have a submodule object (named SubmoduleTestRepo in this example) in your Git repository. GitHub shows these as "submodule" objects. Or do git submodule status from a command line. Git submodule objects are special kinds of Git objects, and they hold the SHA information for a specific commit.

   Whenever you do a git submodule update, it will populate your submodule with content from the commit. It knows where to find the commit because of the information in the .gitmodules.

   Now, all the -b does is add one line in your .gitmodules file. So following the same example, it would look like this:

   [submodule "SubmoduleTestRepo"]    path = SubmoduleTestRepo    url = https://github.com/jzaccone/SubmoduleTestRepo.git    branch = master

   Note: only branch name is supported in a .gitmodules file, but SHA and TAG are not supported! (instead of that, the branch's commit of each module can be tracked and updated using "git add .", for example like git add ./SubmoduleTestRepo, and you do not need to change the .gitmodules file each time)

   The submodule object is still pointing at a specific commit. The only thing that the -b option buys you is the ability to add a --remote flag to your update as per Vogella's answer:

   git submodule update --remote

   Instead of populating the content of the submodule to the commit pointed to by the submodule, it replaces that commit with the latest commit on the master branch, THEN it populates the submodule with that commit. This can be done in two steps by djacobs7 answer. Since you have now updated the commit the submodule object is pointing to, you have to commit the changed submodule object into your Git repository.

   git submodule add -b is not some magically way to keep everything up to date with a branch. It is simply adds information about a branch in the .gitmodules file and gives you the option to update the submodule object to the latest commit of a specified branch before populating it.

(Git 2.22, Q2 2019, has introduced git submodule set-branch --branch aBranch -- <submodule_path>)

Note that if you have an existing submodule which isn't tracking a branch yet, then (if you have git 1.8.2+):

• Make sure the parent repo knows that its submodule now tracks a branch:

    cd /path/to/your/parent/repo  git config -f .gitmodules submodule.<path>.branch <branch>

• Make sure your submodule is actually at the latest of that branch:

    cd path/to/your/submodule  git checkout -b branch --track origin/branch    # if the master branch already exist:    git branch -u origin/master master

        (with 'origin' being the name of the upstream remote repo the submodule has been cloned from.
        A git remote -v inside that submodule will display it. Usually, it is 'origin')

• Don't forget to record the new state of your submodule in your parent repo:

    cd /path/to/your/parent/repo  git add path/to/your/submodule  git commit -m "Make submodule tracking a branch"

• Subsequent update for that submodule will have to use the --remote option:

    # update your submodule  # --remote will also fetch and ensure that  # the latest commit from the branch is used  git submodule update --remote  # to avoid fetching use  git submodule update --remote --no-fetch 

Note that with Git 2.10+ (Q3 2016), you can use '.' as a branch name:

The name of the branch is recorded as submodule.<name>.branch in .gitmodules for update --remote.
A special value of . is used to indicate that the name of the branch in the submodule should be the same name as the current branch in the current repository.

But, as commented by LubosD

With git checkout, if the branch name to follow is ".", it will kill your uncommitted work!
Use git switch instead.

That means Git 2.23 (August 2019) or more.

See "Confused by git checkout"

If you want to update all your submodules following a branch:

    git submodule update --recursive --remote

Note that the result, for each updated submodule, will almost always be a detached HEAD, as Dan Cameron note in his answer.

(Clintm notes in the comments that, if you run git submodule update --remote and the resulting sha1 is the same as the branch the submodule is currently on, it won't do anything and leave the submodule still "on that branch" and not in detached head state.)

To ensure the branch is actually checked out (and that won't modify the SHA1 of the special entry representing the submodule for the parent repo), he suggests:

git submodule foreach -q --recursive 'branch="$(git config -f $toplevel/.gitmodules submodule.$name.branch)"; git switch $branch'

Each submodule will still reference the same SHA1, but if you do make new commits, you will be able to push them because they will be referenced by the branch you want the submodule to track.
After that push within a submodule, don't forget to go back to the parent repo, add, commit and push the new SHA1 for those modified submodules.

Note the use of $toplevel, recommended in the comments by Alexander Pogrebnyak.
$toplevel was introduced in git1.7.2 in May 2010: commit f030c96.

it contains the absolute path of the top level directory (where .gitmodules is).

dtmland adds in the comments:

The foreach script will fail to checkout submodules that are not following a branch.
However, this command gives you both:

 git submodule foreach -q --recursive 'branch="$(git config -f $toplevel/.gitmodules submodule.$name.branch)"; [ "$branch" = "" ] && git checkout master || git switch $branch' –

The same command but easier to read:

git submodule foreach -q --recursive \    'branch="$(git config -f $toplevel/.gitmodules submodule.$name.branch)"; \     [ "$branch" = "" ] && \     git checkout master || git switch $branch' –  

umläute refines dtmland's command with a simplified version in the comments:

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

multiple lines:

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

Before Git 2.26 (Q1 2020), a fetch that is told to recursively fetch updates in submodules inevitably produces reams of output, and it becomes hard to spot error messages.

The command has been taught to enumerate submodules that had errors at the end of the operation.

See commit 0222540 (16 Jan 2020) by Emily Shaffer (nasamuffin).
^{(Merged by Junio C Hamano -- gitster -- in commit b5c71cc, 05 Feb 2020)}

fetch: emphasize failure during submodule fetch

^{Signed-off-by: Emily Shaffer}

In cases when a submodule fetch fails when there are many submodules, the error from the lone failing submodule fetch is buried under activity on the other submodules if more than one fetch fell back on fetch-by-oid.
Call out a failure late so the user is aware that something went wrong, and where.

Because fetch_finish() is only called synchronously by run_processes_parallel, mutexing is not required around submodules_with_errors.

Note that, with Git 2.28 (Q3 2020), Rewrite of parts of the scripted "git submodule" Porcelain command continues; this time it is "git submodule set-branch" subcommand's turn.

See commit 2964d6e (02 Jun 2020) by Shourya Shukla (periperidip).
^{(Merged by Junio C Hamano -- gitster -- in commit 1046282, 25 Jun 2020)}

submodule: port subcommand 'set-branch' from shell to C

^{Mentored-by: Christian Couder
Mentored-by: Kaartic Sivaraam
Helped-by: Denton Liu
Helped-by: Eric Sunshine
Helped-by: Đoàn Trần Công Danh
Signed-off-by: Shourya Shukla}

Convert submodule subcommand 'set-branch' to a builtin and call it via git submodule.sh.