Submodules и subtrees

Submodule — это закреплённый указатель на один точный коммит внешнего репо, а не копия его файлов. Когда ты добавляешь submodule, твой репозиторий записывает особую запись под названием gitlink: одну строку в дереве, говорящую «по этому пути живёт внешний репо X на коммите abc123». Внешний репо клонируется в подкаталог, но твой репо хранит лишь указатель плюс файл .gitmodules, сопоставляющий путь с URL upstream.

git submodule add https://example.com/design-system.git vendor/design-system
git commit -m "Add design-system submodule"

Твой коммит теперь содержит gitlink (закреплённый SHA) и .gitmodules — а не реальные файлы design-system. Именно это держит родительский репо маленьким.

Клон репо с submodules по умолчанию не подтягивает их — нужно их инициализировать. Свежий клон оставляет каталоги submodule пустыми; родитель знает только указатель, а не содержимое. Закреплённые коммиты подтягиваются явно:

# Одним шагом, при клонировании:
git clone --recursive https://example.com/app.git

# Или после обычного клона:
git submodule update --init --recursive

--init читает .gitmodules, update выгружает каждый submodule на точный коммит, который закрепляет родитель (не верхушку его ветки). Это сердце модели: родитель точно контролирует, какую версию зависимости получает каждый чекаут.

Подвох: submodule отслеживает коммит, и его обновление — это двухшаговый коммит, который легко забыть. Чтобы сдвинуть зависимость вперёд, ты заходишь внутрь submodule, выгружаешь более новый коммит, затем возвращаешься и коммитишь сдвинутый указатель в родителе:

cd vendor/design-system
git checkout main
git pull            # submodule теперь на более новом коммите
cd ../..
git add vendor/design-system   # подготовить новый указатель
git commit -m "Bump design-system to latest main"

Если пропустить этот последний git add + commit, твой локальный submodule обновлён, но родитель всё ещё закрепляет старый SHA — и коллеги, делающие submodule update, получают старую версию. Обратная ловушка: подтянуть изменение родителя, сдвинувшее указатель, и забыть запустить submodule update — и твоя рабочая копия тихо работает на устаревшей зависимости. Submodules точны, но остры.

Subtree сливает содержимое внешнего репо прямо в твоё дерево — без указателя, без лишнего шага для потребителей. Вместо ссылки git subtree копирует внешнюю историю в подкаталог твоего репо как настоящие файлы и настоящие коммиты:

# Добавить внешний репо под vendor/design-system
git subtree add --prefix=vendor/design-system \
  https://example.com/design-system.git main --squash

# Позже подтянуть изменения upstream
git subtree pull --prefix=vendor/design-system \
  https://example.com/design-system.git main --squash

Теперь любой, кто клонирует твой репо, получает файлы design-system сразу — без --recursive, без submodule update, без .gitmodules. Цена — в твоей истории: коммиты subtree (или сжатый снимок) сливаются в твой репо, делая его объёмнее, а отправка изменений обратно в upstream (git subtree push) возни́стее, чем чистое разделение submodule.