tools: Add a script for switching to real submodules in forks

.gitmodules

@@ -1,5 +1,6 @@
 #
 # All the relative URL paths are intended to be GitHub ones
+# For Espressif's public projects please use '../../espressif/proj', not a '../proj'
 #
 
 [submodule "components/esp32/lib"]

README.md

@@ -13,6 +13,14 @@ See setup guides for detailed instructions to set up the ESP-IDF:
 * [Getting Started Guide for the stable ESP-IDF version](https://docs.espressif.com/projects/esp-idf/en/stable/get-started/)
 * [Getting Started Guide for the latest (master branch) ESP-IDF version](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/)
 
+### Non-GitHub forks
+
+ESP-IDF uses relative locations as its submodules URLs ([.gitmodules](.gitmodules)). So they link to GitHub.
+If ESP-IDF is forked to a Git repository which is not on GitHub, you will need to run the script
+[tools/set-submodules-to-github.sh](tools/set-submodules-to-github.sh) after git clone.
+The script sets absolute URLs for all submodules, allowing `git submodule update --init --recursive` to complete.
+If cloning ESP-IDF from GitHub, this step is not needed.
+
 ## Finding a Project
 
 As well as the [esp-idf-template](https://github.com/espressif/esp-idf-template) project mentioned in Getting Started, ESP-IDF comes with some example projects in the [examples](examples) directory.

tools/ci/executable-list.txt

@@ -48,6 +48,7 @@ tools/kconfig/mconf
 tools/kconfig/merge_config.sh
 tools/kconfig/streamline_config.pl
 tools/mass_mfg/mfg_gen.py
+tools/set-submodules-to-github.sh
 tools/test_idf_monitor/run_test_idf_monitor.py
 tools/unit-test-app/unit_test.py
 tools/windows/eclipse_make.sh

tools/set-submodules-to-github.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+#
+# Explicitly switches the relative submodules locations on GitHub to the original public URLs
+#
+#       '../../group/repo.git' to 'https://github.com/group/repo.git'
+#
+# This can be useful for non-GitHub forks to automate getting of right submodules sources.
+#
+
+#
+# It makes sense to do
+#
+#       git submodule deinit --force .
+#       git submodule init
+#
+# before running this, and
+#
+#       git submodule update --recursive
+#
+# after that. These were not included over this script deliberately, to use the script flexibly
+#
+
+set -o errexit
+set -o pipefail
+set -o nounset
+
+DEBUG_SHELL=${DEBUG_SHELL:-"0"}
+[ "${DEBUG_SHELL}" = "1" ] && set -x
+
+### '../../' relative locations
+
+for LINE in $(git config -f .gitmodules --list | grep "\.url=../../[^.]")
+do
+    SUBPATH=$(echo "${LINE}" | sed "s|^submodule\.\([^.]*\)\.url.*$|\1|")
+    LOCATION=$(echo "${LINE}" | sed 's|.*\.url=\.\./\.\./\(.*\)$|\1|')
+    SUBURL="https://github.com/$LOCATION"
+
+    git config submodule."${SUBPATH}".url "${SUBURL}"
+done
+
+git config --get-regexp '^submodule\..*\.url$'