Merge pull request #1368 from phil-blain/submodule-sync

Submodules: mention `git submodule sync`

Author: ben

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: it could be that the upstream repository has changed 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).