git submodule update "no-fetch"

Question

When I issue a sub-module update and include "--no-fetch" like so:

git submodule update --remote --no-fetch

The documentation states:

In order to ensure a current tracking branch state, update --remote fetches the submodule’s remote repository before calculating the SHA-1. If you don’t want to fetch, you should use submodule update --remote --no-fetch.

I'm a bit confused about the "--no-fetch" part. If I call update without it:

git submodule update --remote

I understand that a fetch will not be performed - but this also means I am not guaranteed a "current tracking branch state" ? What exactly does that mean?

Under what scenario would I not want the guarantee of a current tracking branch state?

Answer 1

git submodule update does several things under the hood. From git help submodule:

Update the registered submodules to match what the superproject expects by cloning missing submodules, fetching missing commits in submodules and updating the working tree of the submodules.

So running git submodule update --remote is roughly equivalent to (inside the submodule):

$ git fetch origin  # update remote-tracking branches
$ git checkout origin/HEAD  # update working tree

origin/HEAD is a remote-tracking branch that follows the branch from the remote repository (it is normally hidden, but you can see it with git branch --remotes). Note that the git fetch incurs network activity, but the git checkout happens entirely locally.

--no-fetch skips the first step, but will still update your submodule working tree to the remote tracking branch.

I don't think there is a common situation when you would prefer --no-fetch, but it would probably be most useful in situations of limited connectivity. For example, before you go on an airplane, you can git fetch --recurse-submodules. Then during the flight you can use git submodule update --remote --no-fetch (update to submodule remote-tracking branch) or git submodule update --no-fetch (update to commit recorded in superproject) without accessing the network. However this would not have the "current tracking branch state," since your remote-tracking branch will only be as recent as your last fetch.