Git-подмодули

Что такое подмодуль

Подмодуль (submodule) — это отдельный Git-репозиторий, подключённый внутрь вашего основного репозитория (далее — суперпроект) как зависимость. В суперпроекте хранится ссылка на конкретный коммит подмодуля (а не его файлы). Такой подход обеспечивает стабильность и предсказуемость совместной работы с подмодулями проекта.

Применение:

общие библиотеки и шаблоны, переиспользуемые в нескольких проектах;
«вендоринг» внешних репозиториев без копирования файлов.

Добавление подмодулей

# В корне проекта
git submodule add https://gitflic.ru/project/user/repo.git path/to/submodule
git add .gitmodules path/to/submodule
git commit -m "Добавлен подмодуль <submodule>"

В репозитории появится:

файл .gitmodules — хранит путь, URL и ветку.
ссылка (gitlink) на коммит подмодуля в основном репозитории.

Пример .gitmodules:

[submodule "submodule"]
    path = path/to/submodule
    url = https://gitflic.ru/project/user/repo.git
    branch = master

Клонирование подмодулей

Клонирование проекта включая подмодули

git clone --recurse-submodules https://gitflic.ru/project/user/repo.git

Если ранее проект был склонирован без подмодулей

git submodule update --init --recursive

Клонирование подмодулей на последние изменения из ветки

Чтобы при инициализации подмодули обновлялись не на зафиксированный коммит, а на последний коммит ветки, указанной в .gitmodules, используйте команду:

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

Обновление подмодулей

Автоматически (на последний коммит ветки)

git submodule update --remote --recursive
git commit -am "Обновлен подмодуль"

Вручную (на конкретный коммит или тег)

cd path/to/submodule
git fetch
git checkout <commit-or-tag>
cd ../..
git add path/to/submodule
git commit -m "Зафиксирован новый коммит подмодуля"

Удаление подмодулей

git submodule deinit -f path/to/submodule
git rm -f path/to/submodule
rm -rf .git/modules/submodule
git commit -m "Удален подмодуль"

Дополнительные настройки

Автоматическое управление подмодулями в суперпроекте

git config --global submodule.recurse true

Синхронизация измененного URL

Если вы поменяли URL в .gitmodules вручную — выполните:

git submodule sync --recursive

Shallow-обновление для ускорения работы

git submodule update --init --recursive --depth 1

Опция --depth 1 клонирует подмодули только с последним коммитом, без всей истории. Это значительно экономит место и время при клонировании, особенно в CI/CD.

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

Действие	Команда
Добавить подмодуль	`git submodule add <url> <path>`
Клонировать с подмодулями	`git clone --recurse-submodules <url>`
Инициализация	`git submodule update --init --recursive`
Обновить	`git submodule update --remote --recursive`
Удалить	`git submodule deinit -f <path> && git rm -f <path>`

Для работы с подмодулями в GitFlic CI/CD обратитесь к данной статье