Что такое git submodules?

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

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

Когда вы добавляете сабмодуль, Git создаёт файл .gitmodules с описанием URL и пути, а также специальную запись в индексе, указывающую на конкретный коммит внешнего репозитория. При клонировании родительского проекта папка сабмодуля будет пустой, пока вы не выполните инициализацию.

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

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

Пример

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

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

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

# Переходим в сабмодуль и обновляем его вручную
cd libs/shared
git checkout main
git pull
cd ../..
git add libs/shared
git commit -m "Update shared submodule"

Особенности и подводные камни

• Сабмодуль всегда фиксируется на конкретном коммите, а не на ветке — это обеспечивает воспроизводимость сборок.
• Изменения внутри сабмодуля нужно коммитить отдельно в его репозитории, а затем обновлять ссылку в родительском.
• Команда git pull в родительском репозитории не обновляет содержимое сабмодулей автоматически.
• Для команд часто удобнее использовать git submodule foreach для массовых операций.

Сабмодули стоит применять, когда нужно подключить внешнюю библиотеку или общий код с собственной историей и версионированием, и при этом важно фиксировать конкретную версию. Если же требуется просто скопировать код без истории, лучше подойдёт subtree или обычная зависимость пакетного менеджера.