Подмодуль Git для общих модулей 1С: проверка на «Нано-УТ», платформа пропустила 28 вызовов

Команда ведёт два проекта на одной базе кода, и общие модули надо держать в одном месте. Подмодуль Git для этого выглядит естественно, но выгрузка конфигурации 1С устроена иначе, чем обычный каталог с исходниками: пути в ней задаёт платформа. Я проверила на платформе 8.3.27, что остаётся рабочим, когда каталог общих модулей становится подмодулем, и какие ошибки Git молча доходят до базы.

Стенд

Один прогон каждого сценария, повторов и средних значений нет. Сеть, авторизация на сервере Git и большие репозитории не проверялись.

Как устроена выгрузка и что из этого следует для подмодуля

Выгрузка конфигурации в XML имеет фиксированные пути. Configuration.xml перечисляет общие модули в ChildObjects, а для каждого модуля платформа ищет два объекта: файл CommonModules/Имя.xml и каталог CommonModules/Имя/Ext/Module.bsl. Файл описания лежит рядом с каталогом модуля, вне его.

Из этого следует, что подмодуль можно смонтировать в src/CommonModules целиком: тогда файл описания и каталог каждого модуля библиотеки оказываются на нужных местах. Схема «один подмодуль на один модуль» по этой структуре не складывается: описание Имя.xml остаётся за пределами каталога Имя/, и в подмодуль на уровне каталога модуля оно не попадёт. Эту схему я отдельно не проверяла. Подмодуль на уровень глубже, лишний модуль и свой модуль в каталоге библиотеки я прогнала на платформе (раздел про структуру ниже).

Опыт построен так. Репозиторий nano-lib содержит каталог CommonModules «Нано-УТ» (16 модулей) в корне. Два проекта, retail и wholesale, содержат остальную выгрузку и подключают nano-lib подмодулем в src/CommonModules с веткой main в .gitmodules. Проекты отличаются только именем конфигурации в Configuration.xml (НаноУТ и НаноОпт): других различий в коде у них нет, поэтому опыт не показывает, как подмодуль ведёт себя при реальных расхождениях проектов.

Версии библиотеки: v1 (исходные модули), v2 (комментарий в начале модуля ЦеныУчет), v3 (в модуле УчетСервер экспортная процедура Пересчитать переименована в ПересчитатьУчет, в документах и формах проекта 28 вызовов УчетСервер.Пересчитать).

Что именно загрузила платформа, видно только по содержимому базы. Поэтому после каждой загрузки скрипт делает обратную выгрузку /DumpConfigToFiles, считает хеш каждого Module.bsl и сопоставляет набор хешей с известной версией библиотеки. Хеши считаются после приведения переводов строк к LF и снятия BOM. В первом прогоне я этого не делала и увидела совпадение с диском для 13-14 модулей из 16: Git с autocrlf=true кладёт в рабочую копию CRLF, а выгрузка платформы использует LF. Прогон я прервала, исправила сравнение и повторила; журнал прерванного прогона приложен отдельно.

Эталон и клон с --recursive

Выгрузка без подмодулей загрузилась командой /LoadConfigFromFiles за 41,7 с, /CheckModules отработала за 23,5 с, оба кода возврата равны 0.

Клон проекта retail с --recursive занял 20,2 с. Платформа загрузила его без замечаний: код 0 и у загрузки, и у проверки, а обратная выгрузка по хешам совпала с версией v1 для всех 16 модулей. Файл .git, который подмодуль кладёт в каталог src/CommonModules, платформе не мешает.

Клон без --recursive

Обычный git clone проекта занял 2,5 с, и каталог src/CommonModules после него пуст. Команда git submodule status показывает перед хешем минус: подмодуль не инициализирован.

Платформа на таком клоне остановилась на загрузке с кодом 1. В журнале 32 строки вида «Файл объекта не существует» с путём к файлу ПродажиСервер.xml и остальным модулям: по одному сообщению на каждый из 16 модулей, и каждое сообщение повторено дважды. Начало текста сообщений указывает на путь в src/CommonModules, но не говорит, что причина в Git.

Команда git submodule update --init заняла 11,0 с, после неё загрузка и проверка прошли, версия в базе v1. Этот сбой заметен сразу: база не собирается. Остальные сценарии опаснее тем, что платформа молчит.

Правка внутри подмодуля: от файла до клона коллеги

В клоне retail я добавила строку комментария в модуль ЦеныУчет внутри src/CommonModules и прошла по шагам, фиксируя состояние Git, ответ скрипта проверки и содержимое базы.

Шаг 1 показывает главное свойство платформы: она загружает рабочую копию без оглядки на коммиты. Правка, которой нет ни в одном коммите, попала в базу, и проверка модулей её приняла.

На шаге 2 разработчик видит рабочую базу с правкой, а коллега получает v1. Git при этом не сообщает ничего тревожного: изменение указателя видно только в git status как «M src/CommonModules», и его легко пропустить в списке файлов.

На шаге 3 проект с указателем на несуществующий для сервера коммит успешно отправлен. Клон у коллеги остановился с сообщениями «not our ref» и «Fetched in submodule path, but it did not contain» с хешем коммита. Результат клона остался в промежуточном состоянии: скрипт проверки показал POINTER_DIFF:OTHER (записан один коммит, выбран другой) и DIRTY на 32 файла в подмодуле. Такой клон нельзя использовать, пока библиотека не отправлена и подмодуль не обновлён.

Переключение веток с разными версиями библиотеки

В проекте retail на ветке main указатель стоит на v2, а на ветке old-lib, созданной от предыдущего коммита, на v1.

Первая строка таблицы важна: после обычного переключения ветки Git оставил подмодуль на v2, платформа загрузила v2, хотя ветка записывает v1, и сборка прошла без ошибок. С параметром submodule.recurse=true переключение само перемещает подмодуль, но занимает на стенде около 30 с вместо долей секунды. Что перемещение занимает именно столько и при других условиях, я не проверяла.

Обновление версии библиотеки в одном проекте

Библиотека получила v3 с переименованной процедурой. До обновления скрипт с ключом --fetch показал для обоих проектов LAGGING: wholesale отстал на 2 коммита, retail на 1.

Обновление retail командой git submodule update --remote заняло 65,5 с. Платформа загрузила v3, код возврата и загрузки, и /CheckModules равен 0. Это важный результат: в проекте остались 28 вызовов УчетСервер.Пересчитать, процедуры с таким именем в v3 уже нет, а проверка модулей на стенде ничего не сообщила. Тот же эффект наблюдался в опыте с хуком pre-commit на этой же выгрузке: вызов несуществующей процедуры общего модуля из другого модуля не останавливает /CheckModules. Выполнение этих вызовов в режиме предприятия я не запускала.

Проект wholesale при этом остался на v1: записан и выбран один и тот же коммит, платформа загрузила v1, скрипт показал LAGGING на 2 коммита. Подмодуль закрепляет версию на проект, а обновлять её приходится по проектам вручную. Это и есть смысл подмодуля, но он требует, чтобы кто-то заметил отставание. Для этого и нужна проверка из архива.

Что допускает загрузка: структура выгрузки

Все предположения проверены на отдельных копиях выгрузки.

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

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

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

Если проекту нужны собственные общие модули, остаётся копирование. Скрипт sync_lib.py копирует Имя.xml и каталог Имя/ каждого модуля библиотеки в src/CommonModules и ничего не делает с чужими модулями. На стенде скрипт скопировал 32 объекта (16 файлов описания и 16 каталогов). Свой модуль ОптовыеЦены, добавленный в проект рядом, загрузился вместе с библиотекой: на диске и в базе по 17 модулей.

Копии отслеживает уже сам проект, поэтому главный вопрос: заметит ли кто-нибудь правку в копии. Режим sync_lib.py --check до правки не нашёл расхождений, после добавления строки в копию ЦеныУчет назвал этот модуль. Обновление копий остаётся ручным действием, а история библиотеки существует только в её репозитории.

Расширение вместо подмодуля

Другой путь: вынести общие модули в расширение конфигурации. Для проверки я написала выгрузку расширения с двумя собственными общими модулями и префиксом имён «Рс_» и загрузила её командой /LoadConfigFromFiles с ключом -Extension. Загрузка прошла с кодом 0, /CheckModules с ключом -Extension тоже (код 0).

Затем я проверила видимость модуля расширения. Вызов модуля основной конфигурации из модуля расширения (Рс_Вызов обращается к ЦеныСервер.ЦенаНаДату) прошёл проверку. Обратный вызов, из модуля ПродажиСервер основной конфигурации к модулю Рс_Цены, остановил /CheckModules с кодом 101 и сообщением «Переменная не определена (Рс_Цены)» в строке 10, колонке 13. Основная конфигурация не видит общих модулей расширения при компиляции.

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

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

Скрипт check_submodules.py читает индекс проекта и для каждого подмодуля называет состояния, которые встретились в сценариях выше.

Запуск: python -X utf8 subs/check_submodules.py путь/к/проекту [--fetch] [--json]. Код возврата 0 при чистом состоянии, 1 при замечаниях, 2 если путь не репозиторий. Скрипт ничего не меняет, кроме git fetch в подмодулях при ключе --fetch.

Скрипт сравнивает коммиты и не читает содержимое модулей. Совместимость версий библиотеки с вызывающим кодом он не проверяет, как показал сценарий v3.

Сколько занимают операции

Одна и та же выгрузка загружалась от 15,8 до 61,1 с. Столько вносит нагрузка от других процессов на машине, поэтому разницу между сценариями по времени платформы я не интерпретирую. Времена Git тоже отдельные измерения на загруженной машине.

Практические правила по результатам опыта

1. Подмодуль подходит, если библиотека занимает весь src/CommonModules и у проекта нет собственных общих модулей. В остальных случаях копирование с проверкой расхождений в опыте оставило меньше состояний, за которыми надо следить: грязных подмодулей в нём нет.
2. Клонируйте с --recursive или выполняйте git submodule update --init сразу после клона. Сообщение платформы не называет причину.
3. Коммитьте в подмодуле, отправляйте библиотеку и только затем отправляйте проект с новым указателем. В обратном порядке коллеги получают клон с ошибкой.
4. Включите submodule.recurse=true или запускайте git submodule update после каждого переключения ветки. Иначе платформа получит версию библиотеки от предыдущей ветки.
5. Запускайте проверку состояния перед загрузкой в базу в сборочном шаге. Платформа сама эту ошибку не покажет.
6. Совместимость версий библиотеки с вызывающим кодом нужна отдельная проверка: /CheckModules на стенде её не дал.

Что не проверено

Одна платформа (8.3.27.2130 x86), одна конфигурация, файловая база. Клиент-серверный вариант, EDT, графические клиенты Git, Linux и macOS не проверялись. Подмодули были по локальному пути; удалённый сервер Git, авторизация и сеть не проверялись. Вложенные подмодули (подмодуль внутри подмодуля), символические ссылки и точки соединения Windows не проверялись. Оба проекта различаются только именем конфигурации. Исполнение вызовов в режиме предприятия не запускалось. Обновление платформы и поведение расширения в рабочей базе не проверялись.

Файл к статье

В архиве submodules-22-1-companion.zip находятся:

• subs/check_submodules.py: проверка состояния подмодулей проекта;
• subs/sync_lib.py: копирование модулей библиотеки и проверка расхождений;
• subs/onec.py: запуск платформы: база, загрузка, проверка, обратная выгрузка, хеши модулей;
• subs/run_scenarios.py: сценарии этой статьи с платформой (нужна выгрузка «Нано-УТ 2.0», в архив она не входит);
• subs/ext_experiment.py: опыт с расширением;
• tests: тесты без платформы на настоящих репозиториях Git;
• evidence: журналы прогонов за 24.10.2026, вывод тестов лежит там же;
• README.md: запуск и пределы.

Для проверки из чистой распаковки:

1

python -X utf8 -m unittest discover -s tests -t . -v

Тесты не требуют платформы и удаляют свои временные каталоги. На загруженной машине они идут несколько минут: каждый тест создаёт репозитории и подмодуль. Для повторения опыта с платформой передайте run_scenarios.py путь --src к выгрузке «Нано-УТ 2.0», новый каталог --work и путь журнала --out. Существующий --work скрипт не удаляет и завершается с ошибкой.

Итог

Подмодуль Git и выгрузка конфигурации 1С совместимы при одном условии: библиотека занимает весь каталог CommonModules. Платформа грузит то, что лежит на диске, и не знает про указатели Git, поэтому клон без --recursive даёт явную ошибку, а забытый указатель, неотправленная библиотека и смена ветки без обновления подмодуля дают базу не той версии без единого сообщения платформы. Скрипт из архива ловит такие состояния, но не ловит несовместимость версий: переименованная процедура прошла /CheckModules при 28 вызовах. Для проектов со своими общими модулями проще копирование с проверкой расхождений, а расширение не видно основной конфигурации.

Источники

• Git: git-submodule
• Git: gitsubmodules
• Git: git-config, параметр submodule.recurse
• Git: git-clone, ключ --recurse-submodules

 

Нинель Адольевна Щербакова (Ninel_S)

Архитектор • SRE & DevOps инженер • HighLoad 1С

Автор технических публикаций на Infostart. Разработчик NOPik, SRE-Suite-for-1C и мультиагентных ассистентов для экосистемы 1С:Предприятие.

Каталог статей и открытых репозиториев Ninel_S