🔄 Git Submodules: Организация без боли и как не сломать сборку тестов

1. Введение (2-3 предложения)

«Если вы когда-нибудь клонировали репозиторий, а внутри — пустые папки с намёком на код, првиет submodules 😏. Рассказываю, как использовать их, чтобы не плодить “матрёшки” и не тратить часы на отладку CI».

2. Когда подмодули нужны (а когда — нет)

✅ Хорошо:

· Общие тестовые данные (фикстуры, JSON-схемы) для нескольких проектов. · Внутренние фреймворки/утилиты (например, кастомный TestNG-репортер). · API-коллекции (Postman/Bruno) как отдельный репозиторий.

❌ Плохо:

· Для часто меняющегося кода (каждые 10 минут). · В микросервисах с жёсткой связанностью (лучше монорепозиторий).

3. Базовая организация (как настроить с нуля)

Команда:

git submodule add https://github.com/your/common-tests.git tests/common

Что важно:

· Всегда используйте HTTPS/SSH-ссылки, а не локальные пути. · Добавьте .gitmodules в репозиторий (он автоматически создаётся).

Структура в идеале:

project/ ├── tests/ │ ├── common/ # подмодуль (фикстуры, хелперы) │ └── e2e/ ├── .gitmodules └── README.md (обязательно укажите, что проект использует submodules!)

4. Как использовать (главные команды для QA): Клонирование проекта с подмодулями (сразу всё): git clone --recursive https://github.com/your/project.git

Если уже склонировали без --recursive (типичная ошибка): git submodule update --init --recursive Обновление подмодуля до последнего коммита его master:

cd tests/common git checkout master && git pull origin master cd …/… git add tests/common git commit -m “chore: update common tests submodule”

Важно: Подмодуль всегда привязан к конкретному коммиту, не к ветке. Обновили вручную — закоммитьте новую ссылку в основном репозитории.

—

5. Как не наступить на грабли (QA лайфхаки)

🔹 Перед запуском тестов в CI всегда делайте:

git submodule update --init --recursive --remote

Это тянет последние изменения из удалённых веток подмодулей.

🔹 Если подмодуль изменил API — тесты упадут. Решение: В основном проекте зафиксируйте коммит подмодуля, с которым всё работает, и обновляйте контролируемо (через PR с проверкой).

🔹 Как посмотреть, на каком коммите сейчас каждый подмодуль:

git submodule status

🔹 Проблема: «У меня локально тесты проходят, а в CI — нет». Скорее всего, CI тянет старый коммит подмодуля. Сравните вывод git submodule status локально и в логах билда.

6. Золотое правило для команды

Никто не обновляет подмодуль в основном репозитории без соответствующего PR, где проверены все тесты с этим новым коммитом.

Добавьте в CONTRIBUTING.md раздел про submodules.

7. Полезные команды (шпаргалка)

# Потянуть изменения из всех подмодулей (но не обновлять ссылки) git submodule foreach git pull origin main

# Удалить подмодуль (аккуратно, 3 шага) git submodule deinit -f tests/common git rm -f tests/common rm -rf .git/modules/tests/common

—

Финальный призыв: 📌 Сохраните эту статью, чтобы не гуглить «git submodule update» в 3 часа ночи. А в комментариях поделитесь своей болью от подмодулей — устроим сессию взаимопомощи.