From 5487864df9d6d16838cdae951d467d8e913b4962 Mon Sep 17 00:00:00 2001
From: Anton Maklakov <anton@espressif.com>
Date: Mon, 1 Jul 2019 15:19:10 +0700
Subject: [PATCH] tools: Add a script for switching to real submodules in forks

---
 .gitmodules                       |  1 +
 README.md                         |  8 ++++++
 tools/ci/executable-list.txt      |  1 +
 tools/set-submodules-to-github.sh | 41 +++++++++++++++++++++++++++++++
 4 files changed, 51 insertions(+)
 create mode 100755 tools/set-submodules-to-github.sh

diff --git a/.gitmodules b/.gitmodules
index 0f840d07e5..ee843addc8 100644
--- a/.gitmodules
+++ b/.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"]
diff --git a/README.md b/README.md
index 55487c9b2c..bbb8d3a54b 100644
--- a/README.md
+++ b/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.
diff --git a/tools/ci/executable-list.txt b/tools/ci/executable-list.txt
index f912560430..594947413a 100644
--- a/tools/ci/executable-list.txt
+++ b/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
diff --git a/tools/set-submodules-to-github.sh b/tools/set-submodules-to-github.sh
new file mode 100755
index 0000000000..5495fb4a29
--- /dev/null
+++ b/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$'