Merge pull request #9386 from Felixoid/doc_submodules

Add commands for working with submodules

docs/en/development/developer_instruction.md

@@ -76,6 +76,41 @@ git remote add upstream git@github.com:ClickHouse/ClickHouse.git
 After successfully running this command you will be able to pull updates from the main ClickHouse repo by running `git pull upstream master`.
 
 
+## Working with submodules
+
+Working with submodules in git could be painful. Next commands will help to manage it:
+
+```
+# ! each command accepts --recursive
+# Update remote URLs for submodules. Barely rare case
+git submodule sync
+# Add new submodules
+git submodule init
+# Update existing submodules to the current state
+git submodule update
+# Two last commands could be merged together
+git submodule update --init
+```
+
+The next commands would help you to reset all submodules to the initial state (!WARING! - any chenges inside will be deleted):
+
+```
+# Synchronizes submodules' remote URL with .gitmodules
+git submodule sync --recursive
+# Update the registered submodules with initialize not yet initialized
+git submodule update --init --recursive
+# Reset all changes done after HEAD
+git submodule foreach git reset --hard
+# Clean files from .gitignore
+git submodule foreach git clean -xfd
+# Repeat last 4 commands for all submodule
+git submodule foreach git submodule sync --recursive
+git submodule foreach git submodule update --init --recursive
+git submodule foreach git submodule foreach git reset --hard
+git submodule foreach git submodule foreach git clean -xfd
+```
+
+
 # Build System
 
 ClickHouse uses CMake and Ninja for building.

docs/ru/development/developer_instruction.md

@@ -76,6 +76,43 @@ git remote add upstream git@github.com:yandex/ClickHouse.git
 После этого, вы сможете добавлять в свой репозиторий обновления из репозитория Яндекса с помощью команды `git pull upstream master`.
 
 
+## Работа с сабмодулями git
+
+Работа с сабмодулями git может быть достаточно болезненной. Следующие команды позволят содержать их в порядке:
+
+```
+# ! Каждая команда принимает аргумент --recursive
+# Обновить URLs удалённого репозитория для каждого сабмодуля, используется относительно редко
+git submodule sync
+# Добавить новые сабмодули
+git submodule init
+# Обновить сабмодули до актуального состояния
+git submodule update
+# Две последние команды могут быть объединены вместе:
+git submodule update --init
+```
+
+The next commands would help you to reset all submodules to the initial state (!WARING! - any chenges inside will be deleted):
+Следующие команды помогут сбросить все сабмодули в изначальное состояние (!ВНИМАНИЕ! - все изменения в сабмодулях будут утеряны):
+
+```
+# Synchronizes submodules' remote URL with .gitmodules
+# Обновить URLs удалённого репозитория для каждого сабмодуля
+git submodule sync --recursive
+# Обновить существующие модули и добавить отсутствующие
+git submodule update --init --recursive
+# Удалить все изменения в сабмодуле относительно HEAD
+git submodule foreach git reset --hard
+# Очистить игнорируемые файлы
+git submodule foreach git clean -xfd
+# Повторить последние 4 команды для каждого из сабмодулей
+git submodule foreach git submodule sync --recursive
+git submodule foreach git submodule update --init --recursive
+git submodule foreach git submodule foreach git reset --hard
+git submodule foreach git submodule foreach git clean -xfd
+```
+
+
 # Система сборки
 
 ClickHouse использует систему сборки CMake и Ninja.

docs/zh/development/developer_instruction.md

@@ -78,6 +78,40 @@ git remote add upstream git@github.com:ClickHouse/ClickHouse.git
 命令执行成功后，可以通过执行`git pull upstream master`，从ClickHouse的主分支中拉去更新。
 
 
+## Working with submodules
+
+Working with submodules in git could be painful. Next commands will help to manage it:
+
+```
+# ! each command accepts --recursive
+# Update remote URLs for submodules. Barely rare case
+git submodule sync
+# Add new submodules
+git submodule init
+# Update existing submodules to the current state
+git submodule update
+# Two last commands could be merged together
+git submodule update --init
+```
+
+The next commands would help you to reset all submodules to the initial state (!WARING! - any chenges inside will be deleted):
+
+```
+# Synchronizes submodules' remote URL with .gitmodules
+git submodule sync --recursive
+# Update the registered submodules with initialize not yet initialized
+git submodule update --init --recursive
+# Reset all changes done after HEAD
+git submodule foreach git reset --hard
+# Clean files from .gitignore
+git submodule foreach git clean -xfd
+# Repeat last 4 commands for all submodule
+git submodule foreach git submodule sync --recursive
+git submodule foreach git submodule update --init --recursive
+git submodule foreach git submodule foreach git reset --hard
+git submodule foreach git submodule foreach git clean -xfd
+```
+
 # 构建系统
 
 ClickHouse使用 CMake 和 Ninja 来构建系统。