From 5b2b107e9a44b712864a21bc597c5cc652c1642d Mon Sep 17 00:00:00 2001 From: Philippe Blain Date: Mon, 27 Jan 2020 20:33:25 -0500 Subject: [PATCH 1/2] 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//config. Add a note concerning this command at the end of the 'Pulling Upstream Changes from the Project Remote' section. --- book/07-git-tools/sections/submodules.asc | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/book/07-git-tools/sections/submodules.asc b/book/07-git-tools/sections/submodules.asc index ea22f995..3e21bbeb 100644 --- a/book/07-git-tools/sections/submodules.asc +++ b/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). From 84299a2e35b3390d6e280c65806a016231387124 Mon Sep 17 00:00:00 2001 From: Philippe Blain <44212482+phil-blain@users.noreply.github.com> Date: Thu, 30 Jan 2020 09:44:40 -0500 Subject: [PATCH 2/2] Submodules: fix grammar as suggested by Ben See https://github.com/progit/progit2/pull/1368#discussion_r372679235 Co-Authored-By: Ben Straub --- book/07-git-tools/sections/submodules.asc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/07-git-tools/sections/submodules.asc b/book/07-git-tools/sections/submodules.asc index 3e21bbeb..be5c3613 100644 --- a/book/07-git-tools/sections/submodules.asc +++ b/book/07-git-tools/sections/submodules.asc @@ -437,7 +437,7 @@ 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. +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: