Для чего используются Git-субмодули?

Git-субмодуль — это способ встроить один Git-репозиторий внутрь другого, сохранив при этом независимую историю обоих. Родительский репозиторий не копирует файлы дочернего, а хранит лишь ссылку на конкретный коммит вложенного репозитория. Это позволяет переиспользовать общий код, библиотеки или конфигурации между несколькими проектами без дублирования.

Как это работает

Внутри родительского репозитория создаётся специальная запись в .gitmodules, где указан URL и путь вложенного репозитория. Сам вложенный репозиторий остаётся отдельным проектом со своей историей, ветками и тегами. Родитель фиксирует только конкретный коммит, что даёт воспроизводимость сборки.

Основные команды

• git submodule add <url> <path> — добавить субмодуль.
• git clone --recurse-submodules <url> — клонировать проект вместе с субмодулями.
• git submodule update --init --recursive — инициализировать и обновить субмодули.
• git submodule update --remote — подтянуть последние изменения из удалённого репозитория субмодуля.

Пример

# Добавляем общую библиотеку как субмодуль
git submodule add https://github.com/org/shared-lib.git libs/shared

# Клонируем проект с субмодулями
git clone --recurse-submodules git@github.com:org/main-app.git

# Обновляем субмодули до зафиксированных коммитов
git submodule update --init --recursive

# Перейти в субмодуль и зафиксировать новую версию
cd libs/shared
git checkout v2.1.0
cd ../..
git add libs/shared
git commit -m "Bump shared-lib to v2.1.0"

Когда это полезно

Субмодули хорошо подходят, когда общий код развивается отдельно и должен использоваться в нескольких проектах с явным контролем версии. Однако они усложняют работу: разработчики часто забывают обновить субмодули, а CI требует дополнительных шагов. Для простых случаев часто удобнее пакетный менеджер (npm, pip, Maven) или монорепозиторий.

Итог: применяйте субмодули, когда нужна жёсткая привязка к конкретной версии внешнего репозитория и независимое версионирование, но будьте готовы к дополнительной дисциплине в команде и настройке CI.