Submodules: mention git submodule sync

This command is required if the submodule URL recorded in the
superproject changes, in order to synchronize this URL from .gitmodules
to the local configuration files .git/config and
.git/modules/<name>/config.

Add a note concerning this command at the end of the 'Pulling Upstream
Changes from the Project Remote' section.

Author: phil-blain

book/07-git-tools/sections/submodules.asc

@@ -437,6 +437,19 @@ This will make Git run `git submodule update` right after the pull, putting the
 Moreover, if you want to make Git always pull with `--recurse-submodules`, you can set the configuration option `submodule.recurse` to true (this works for `git pull` since Git 2.15).
 This option will make Git use the `--recurse-submodules` flag for all commands that support it (except `clone`).
 
+There is a special situation that can happen when pulling superproject updates : maybe the upstream repository changes the URL of the submodule in the `.gitmodules` file in one of the commits you pull.
+This can happen for example if the submodule project changes its hosting platform.
+In that case, it is possible for `git pull --recurse-submodules`, or `git submodule update`, to fail if the superproject references a submodule commit that is not found in the submodule remote locally configured in your repository.
+In order to remedy this situation, the `git submodule sync` command is required:
+
+[source,console]
+----
+# copy the new URL to your local config
+$ git submodule sync --recursive
+# update the submodule from the new URL
+$ git submodule update --init --recursive
+----
+
 ===== Working on a Submodule
 
 It's quite likely that if you're using submodules, you're doing so because you really want to work on the code in the submodule at the same time as you're working on the code in the main project (or across several submodules).