diff --git a/README.md b/README.md index 9475aa5..46f5f4d 100644 --- a/README.md +++ b/README.md @@ -12,12 +12,17 @@ 1. `limit` - добавляет возможность ограничения на минимальный, максимальный номер версии хранилища, а так же на лимит на количество выгружаемых версий за один запуск 1. `replace-authors` - добавляет возможность замены автора коммита 1. `robo-copy` - заменяет механизм переноса исходников из временного каталога в рабочий на robocopy, чтобы избежать ошибок с длиной пути к файлу -1. `smart-tags` - при смене версии конфигурации (не путать с версией хранилища) устанавливает тег, равный версии конфигурации. Добавляет опции команды `sync` для автоматической установки метки git (команда `git tag`) равной версии хранилища (в формате "v.номер"). +1. `smart-tags` - при смене версии конфигурации (не путать с версией хранилища) устанавливает тег, равный версии конфигурации. Добавляет опции команды `sync` для автоматической установки метки git (команда `git tag`) равной версии хранилища (в формате "v.номер"). Параметр `--tags-prefix` задает префикс для всех создаваемых тегов. 1. `sync-remote` - добавляет функциональность синхронизации с удаленным репозиторием git (команды `git pull` и `git push`) 1. `tool1CD` - заменяет использование штатных механизмов 1С на приложение `tool1CD` при выгрузке конфигурации в исходники 1. `unpackForm` - выполняет распаковку обычных форм на исходники. Добавляет опции команды `sync` для переименования объектов обычных форм. 1. `use-ibcmd` - включает использование утилиты управления автономным сервером `ibcmd` для выгрузки конфигурации/расширения в файлы +## Документация + +- [Пользовательская документация](./docs/user-guide.md) — описание каждого плагина и его параметров +- [Техническая документация](./docs/technical.md) — архитектура, хуки, добавление плагинов + ## Доработка Доработка проводится по github-flow. Жду ваших PR. diff --git a/docs/technical.md b/docs/technical.md new file mode 100644 index 0000000..dcece51 --- /dev/null +++ b/docs/technical.md @@ -0,0 +1,285 @@ +# Техническая документация gitsync-plugins + +## Архитектура + +Проект `gitsync-plugins` — набор встроенных плагинов для [gitsync](https://github.com/oscript-library/gitsync), инструмента синхронизации конфигураций 1С с git. + +Плагины написаны на **OneScript (OScript)** — русскоязычном диалекте, совместимом со встроенным языком 1С:Предприятие. + +### Жизненный цикл плагина + +Плагин реализует интерфейс, определённый в `src/Классы/plugin.os.template`. Хостовое приложение `gitsync` вызывает хуки плагинов в фиксированной последовательности. + +### Обязательные экспортные функции + +| Функция | Назначение | +|---|---| +| `Версия()` | Строка версии плагина | +| `Приоритет()` | Числовой приоритет (0 — по умолчанию) | +| `Описание()` | Краткое описание | +| `Справка()` | Подробная справочная информация с параметрами | +| `Имя()` | Уникальное имя плагина (используется для включения/отключения) | +| `ИмяЛога()` | Имя логера, формат `oscript.lib.gitsync.plugins.` | + +### Жизненные хуки (в порядке вызова) + +#### Хуки регистрации + +| Хук | Когда вызывается | Назначение | +|---|---|---| +| `ПриАктивизации(СтандартныйОбработчик)` | При включении плагина | Сохранение ссылки на стандартный обработчик, инициализация | +| `ПриРегистрацииКомандыПриложения(ИмяКоманды, КлассРеализации)` | При парсинге аргументов команды | Регистрация опций CLI через `КлассРеализации.Опция()` | +| `ПриПолученииПараметров(ПараметрыКоманды)` | После разбора аргументов | Чтение значений параметров из `ПараметрыКоманды.Параметр()` | + +#### Хуки синхронизации (для команды `sync`) + +| Хук | Когда вызывается | Назначение | +|---|---|---| +| `ПередНачаломВыполнения(ПутьКХранилищу, КаталогРабочейКопии)` | Перед началом основного цикла | Чтение контекста, подготовка | +| `ПередВыгрузкойКонфигурациюВИсходники(Конфигуратор, КаталогРабочейКопии, КаталогВыгрузки, ПутьКХранилищу, НомерВерсии, Формат)` | Перед каждой выгрузкой версии | Модификация конфигурации перед выгрузкой | +| `ПриВыгрузкеКонфигурациюВИсходники(Конфигуратор, КаталогВыгрузки, Формат, СтандартнаяОбработка)` | Вместо штатной выгрузки | Переопределение механизма выгрузки | +| `ПослеВыгрузкиКонфигурациюВИсходники(Конфигуратор, КаталогРабочейКопии, КаталогВыгрузки, ПутьКХранилищу, НомерВерсии, Формат)` | После выгрузки | Дополнительная обработка выгруженных файлов | +| `ПередПеремещениемВКаталогРабочейКопии(КаталогВыгрузки, КаталогРабочейКопии)` | Перед копированием из врем. каталога | Преобразование файлов (распаковка форм, EDT) | +| `ПриОчисткеКаталогаРабочейКопии(КаталогРабочейКопии, СтандартнаяОбработка)` | При очистке рабочей копии | Переопределение очистки | +| `ПриПеремещенииВКаталогРабочейКопии(КаталогВыгрузки, КаталогРабочейКопии, СтандартнаяОбработка)` | При копировании в рабочую копию | Переопределение копирования | +| `ПередОбработкойВерсииХранилища(СтрокаВерсии, СледующаяВерсия)` | Перед обработкой очередной версии | Чтение данных версии | +| `ПередНачаломЦиклаОбработкиВерсий(ТаблицаИсторииХранилища, ТекущаяВерсия, СледующаяВерсия, МаксимальнаяВерсияДляРазбора)` | Перед циклом по версиям | Корректировка границ цикла | +| `ПередКоммитом(ГитРепозиторий, КаталогРабочейКопии)` | Перед git-коммитом | Добавление файлов, изменение `.gitignore` | +| `ПослеКоммита(ГитРепозиторий, КаталогРабочейКопии)` | После коммита | Теги, промежуточный push | +| `ПослеОкончанияВыполнения(ГитРепозиторий, КаталогРабочейКопии)` | После завершения основного цикла | Финальные операции (push, очистка) | + +#### Хуки расширенного жизненного цикла + +| Хук | Когда вызывается | Назначение | +|---|---|---| +| `ПриКоммите(ГитРепозиторий, КаталогРабочейКопии)` | Вместо штатного коммита | Переопределение коммита | +| `ПослеПолученияТаблицыАвторов(ПутьКФайлуАвторов, ТаблицаАвторов)` | После загрузки `AUTHORS` | Проверка/дополнение таблицы авторов | +| `ПослеПолученияТаблицыВерсий(ТаблицаВерсий)` | После получения списка версий | Модификация таблицы версий | +| `ПослеПолученияТаблицыПользователей(ТаблицаПользователей)` | После получения списка пользователей | Дополнение пользователей | +| `ПриЗагрузкеВерсииХранилищаВКонфигурацию(Конфигуратор, ПутьКХранилищу, НомерВерсии)` | При загрузке версии | Переопределение загрузки версии | +| `ПриПолученииТаблицыВерсий(ПутьКХранилищу, НачальнаяВерсия, КонечнаяВерсия, СтандартнаяОбработка)` | Вместо получения таблицы версий | Переопределение чтения истории | + +### Регистрация опций CLI + +В хуке `ПриРегистрацииКомандыПриложения` плагин регистрирует параметры: + +```oscript +// Флаговый параметр с переменной окружения +КлассРеализации.Опция("S skip-exists-tags", Ложь, "[*smart-tags] флаг пропуска ошибок") + .Флаговый() + .ВОкружении("GITSYNC_SKIP_EXISTS_TAGS"); + +// Строковый параметр с переменной окружения +КлассРеализации.Опция("b branch", "master", "[*sync-remote] Имя ветки") + .ВОкружении("GITSYNC_REMOTE_BRANCH"); + +// Числовой параметр +КлассРеализации.Опция("min-task-count", 0, "[*check-comments] Минимальное количество задач") + .ТЧисло(); +``` + +Сигнатура `.Опция(Спецификация, ЗначениеПоУмолчанию, Описание)`: +- `Спецификация`: `"короткийФлаг длинноеИмя"` или просто `"длинноеИмя"` +- `ЗначениеПоУмолчанию`: определяет тип параметра (булев, строка, число) +- `Описание`: текст справки с префиксом категории `[*имя-плагина]` + +### Фильтрация команд + +Переменная `КомандыПлагина` (массив строк) определяет, для каких команд плагин регистрирует опции. Устанавливается в `Инициализация()`: + +```oscript +КомандыПлагина = Новый Массив; +КомандыПлагина.Добавить("sync"); +``` + +Если `КомандыПлагина` отсутствует — плагин подключается неявно ко всем командам. + +### Несовместимость плагинов + +Некоторые плагины (`drop-config-dump`, `use-ibcmd`) отключают несовместимые. Реализуется в `ПриАктивизации`: + +```oscript +СтандартныйОбработчик.МенеджерПлагинов.ОтключитьПлагин("increment"); +``` + +### Соглашение об именах логов + +Формат: `oscript.lib.gitsync.plugins.` + +--- + +## Добавление нового плагина + +### 1. Создать файл плагина + +Скопировать `src/Классы/plugin.os.template` в `src/Классы/newPlugin.os`. + +### 2. Реализовать интерфейс + +Обязательные функции: +- `Версия()`, `Приоритет()`, `Описание()`, `Справка()`, `Имя()`, `ИмяЛога()` + +Опционально — хуки, в которых плагин должен участвовать. + +### 3. Зарегистрировать класс + +В `packagedef` добавить: +```oscript +.ОпределяетКласс("Плагин_НовыйПлагин", "src/Классы/newPlugin.os") +``` + +### 4. Написать BDD-тесты + +- Создать `features/new-plugin.feature` с Gherkin-сценариями +- При необходимости добавить шаги в `features/step_definitions/new-plugin.os` +- Шаг регистрируется в `ПолучитьСписокШагов()`: +```oscript +ВсеШаги.Добавить("ИмяНовогоШага"); +``` + +### 5. Обновить документацию + +- `README.md` — добавить описание плагина в список +- `docs/user-guide.md` — детальное описание с параметрами + +### 6. Запустить тесты + +```bash +export GITSYNC_V8VERSION=8.3.24.1691 +export EDT_VERSION=2024.2.5 +opm install --dev +opm install gitsync +opm run install-gitsync +opm test +``` + +--- + +## Структура проекта + +``` +gitsync-plugins/ +├── packagedef # Манифест пакета opm: версия, зависимости, классы +├── src/ +│ └── Классы/ +│ ├── *.os # Плагины (один файл — один плагин) +│ ├── plugin.os.template # Шаблон для новых плагинов +│ └── internal/ # Вспомогательные библиотеки +│ ├── tool1cd/ # Чтение файловой БД хранилища 1С +│ └── v8unpack/ # Распаковка контейнеров метаданных +├── features/ +│ ├── *.feature # Сценарии BDD (Gherkin) +│ └── step_definitions/ +│ ├── shared.os # Общие шаги для всех тестов +│ └── *.os # Шаги конкретных плагинов +├── tests/ +│ └── fixtures/ # Тестовые данные +│ ├── *.1CD # Файловые хранилища 1С +│ ├── *.cf # Файлы конфигураций +│ ├── *.mxl # Отчёты по версиям +│ └── edtWorkspace/ # Тестовая рабочая область EDT +├── tasks/ +│ ├── test.os # Запуск BDD-тестов +│ ├── coverage.os # Запуск с покрытием кода +│ ├── install-gitsync.os # Установка gitsync из исходников +│ └── install-plugins.os # Установка плагинов для тестов +├── docs/ # Документация +│ ├── user-guide.md # Пользовательская документация +│ └── technical.md # Техническая документация (этот файл) +└── .github/workflows/ # CI/CD + ├── testing.yml # Матрица тестов (Windows/Linux, 1C/EDT версии) + ├── qa.yml # SonarQube + покрытие кода + └── release.yml # Сборка и публикация .ospx +``` + +## Внутренние библиотеки + +### `internal/tool1cd/` + +Библиотека для чтения файловой базы данных хранилища 1С (`1cv8ddb.1CD`): +- `ЧтениеХранилищаКонфигурации` — выгрузка версий конфигурации из хранилища +- `ЧтениеТаблицФайловойБазыДанных` — чтение таблиц `VERSIONS` и `USERS` +- `СконвертироватьФайлКонфигурации` — конвертация между форматами 1C + +### `internal/v8unpack/` + +Распаковщик контейнеров метаданных обычных форм: +- `Распаковщик.Распаковать()` — извлекает содержимое `Form.bin` + +## Тестирование + +### Инфраструктура + +Тесты построены на BDD-фреймворке [1bdd](https://github.com/artbear/1bdd). Каждый плагин имеет свой `.feature`-файл. Общие шаги вынесены в `features/step_definitions/shared.os`. + +### Требования к окружению + +- Платформа 1С:Предприятие (версия из `GITSYNC_V8VERSION`) +- EDT (версия из `EDT_VERSION`, по умолчанию `2022.2.5`) +- Java 11 (для EDT ≤2023) или Java 17 (для EDT ≥2024) +- Локаль `ru_RU` + +### Запуск + +```bash +# Все тесты +opm test + +# С покрытием кода +opm run coverage + +# Отдельный тестовый файл (через oscript напрямую) +oscript ./tasks/test.os +``` + +### Тестовые фикстуры + +- `ТестовыйФайлХранилища1С.1CD` — файловое хранилище с несколькими версиями (используется большинством тестов) +- `ТестовыйФайлКонфигурации.cf` — выгруженная конфигурация +- `ТестовыйФайлКонфигурации_8_2_17.cf` — конфигурация в старом формате +- `edtWorkspace/` — тестовая рабочая область EDT +- `ОтчетПоВерсиямХранилища.mxl` — эталонный отчёт по версиям + +## CI/CD + +### Тестирование (`.github/workflows/testing.yml`) + +Матрица: OScript `[1.9.2, 2.0.0]` × 1C `[8.3.21, 8.3.24]` × EDT `[2023.3.6, 2024.2.5]` × OS `[windows, ubuntu]`. + +Особенности Linux: +- Требуется `libenchant1c2a` для 1C 8.3.21 +- Wine для работы `tool1CD` +- XVFB для headless-тестов + +### QA (`.github/workflows/qa.yml`) + +- Запускается только для репозитория `oscript-library/gitsync-plugins` +- Собирает покрытие кода через `opm run coverage` +- Отправляет результаты в SonarQube +- Версия пакета извлекается из `packagedef` для SonarQube + +### Релиз (`.github/workflows/release.yml`) + +- Триггер: GitHub Release (published/edited) +- Собирает `.ospx` пакет через `opm build` +- Публикует артефакт в релиз и на hub.oscript.io + +## Процесс выпуска версии + +1. Поднять версию в `packagedef` (`.Версия("X.Y.Z")`) +2. Создать PR, получить аппрув и мёрдж в `master` +3. Создать GitHub Release — CI соберёт пакет и опубликует его +4. Обновить ссылку на версию в репозитории [gitsync](https://github.com/oscript-library/gitsync) в файле `tasks/get_plugins.os` +5. Выпустить новую версию gitsync + +## Конвенции кода + +- Язык комментариев и идентификаторов — русский +- Максимальная длина строки: 150 символов (см. `.bsl-language-server.json`) +- Имена логов: `oscript.lib.gitsync.plugins.` +- `Приоритет()` = 0, если плагину не требуется особый порядок выполнения +- Файл — один плагин, имя файла совпадает с `Имя()` +- Переменная `Лог` инициализируется в `Инициализация()` или `ПриАктивизации()`: + ```oscript + Лог = Логирование.ПолучитьЛог(ИмяЛога()); + ``` diff --git a/docs/user-guide.md b/docs/user-guide.md new file mode 100644 index 0000000..815a551 --- /dev/null +++ b/docs/user-guide.md @@ -0,0 +1,410 @@ +# Пользовательская документация gitsync-plugins + +## Общие сведения + +Плагины gitsync расширяют возможности синхронизации конфигураций 1С с git-репозиторием. Каждый плагин решает свою задачу: проверка авторов, установка тегов, выгрузка в формате EDT и т.д. + +### Управление плагинами + +Плагинами управляют через утилиту `gitsync`: + +``` +gitsync p e <имя_плагина> — включить плагин +gitsync p d <имя_плагина> — отключить плагин +gitsync p d -a — отключить все плагины +gitsync p l — список включённых плагинов +gitsync p l -a — список всех доступных плагинов (включая отключённые) +gitsync p i -f <файл.ospx> — установить плагин из пакета +``` + +**Важно:** `gitsync p l` без ключа `-a` показывает **только включённые** плагины. Чтобы увидеть полный перечень, используйте `gitsync p l -a`. + +Большинство параметров плагинов можно задать двумя способами: через аргумент командной строки `gitsync` и через переменную окружения. + +--- + +## Плагин `check-authors` + +**Назначение:** блокирует синхронизацию, если автор версии хранилища отсутствует в файле `AUTHORS`. + +**Команды:** `sync` + +**Параметры:** нет. + +**Принцип работы:** перед началом цикла обработки версий проверяет таблицу истории хранилища — каждый автор версии должен быть сопоставлен git-пользователю в файле `AUTHORS`. Несопоставленные авторы вызывают исключение с указанием количества проблемных версий. + +--- + +## Плагин `check-comments` + +**Назначение:** проверка заполнения и содержимого комментариев к версиям хранилища. + +**Команды:** `sync` + +**Поведение без `--error-comment`:** при обнаружении проблем (пустой комментарий, нехватка упоминаний задач) в лог пишется `КРИТИЧНАЯОШИБКА`, но синхронизация **продолжается**. Код возврата — 0. Это позволяет вести мониторинг без прерывания процесса. + +**С `--error-comment`:** при любой из проверок синхронизация **останавливается** с исключением и кодом возврата 1. + +### Параметры + +| Параметр | Кратко | По умолчанию | Переменная окружения | Описание | +|---|---|---|---|---| +| `--error-comment` | `-C` | `false` | — | Вызывать ошибку при отсутствии комментария | +| `--task-prefix` | — | `""` | `GITSYNC_TASK_PREFIX` | Префикс задачи для поиска в комментарии | +| `--task-pattern` | — | `""` | `GITSYNC_TASK_PATTERN` | Паттерн задачи (регулярное выражение) | +| `--min-task-count` | — | `0` | — | Минимальное количество упоминаний задач | +| `--max-task-count` | — | `0` | — | Максимальное количество упоминаний задач | +| `--author-presentation` | — | `false` | `GITSYNC_AUTHOR_PRESENTATION` | Использовать представление автора в сообщениях | +| `--repair-quotes` | — | `false` | `GITSYNC_REPAIR_QUOTES` | Заменять Unicode-кавычки на ASCII | + +### Примеры + +``` +# Требовать комментарий (с ошибкой) +gitsync sync --error-comment /path/to/storage /path/to/src + +# Проверить наличие префикса задачи "RM-12345" в комментарии +gitsync sync --task-prefix RM + +# Заменить кавычки-ёлочки на прямые +gitsync sync --repair-quotes /path/to/storage /path/to/src +``` + +--- + +## Плагин `disable-support` + +**Назначение:** снимает конфигурацию с поддержки перед выгрузкой в исходники — через API конфигуратора (`СнятьКонфигурациюСПоддержки`). + +**Команды:** все (подключается неявно) + +**Параметры:** нет. + +**Зачем снимать поддержку:** конфигурация на поддержке поставщика содержит в выгрузке большой бинарный `.cf`-файл с полной конфигурацией вендора. Снятие поддержки исключает его из исходников, что: +- В разы сокращает размер git-репозитория +- Делает diff читаемым (нет изменений от обновлений поставщика) +- Разблокирует объекты конфигурации для редактирования + +Снятие поддержки выполняется **перед** каждой выгрузкой версии — конфигурация в хранилище остаётся на поддержке, меняется только выгруженное состояние. + +--- + +## Плагин `drop-config-dump` + +**Назначение:** отключает версионирование `ConfigDumpInfo.xml` и удаляет его после выгрузки. + +**Команды:** `init`, `sync` + +**Параметры:** нет. + +**Принцип работы:** +1. При активизации отключает несовместимый плагин `increment` +2. Удаляет `ConfigDumpInfo.xml` из каталога рабочей копии и каталога выгрузки +3. Добавляет `ConfigDumpInfo.xml` в `.gitignore` +4. Коммитит изменение `.gitignore` + +--- + +## Плагин `drop-support` + +**Назначение:** удаляет информацию о поддержке из выгруженных исходников — напрямую, без использования конфигуратора. Решает ту же задачу, что и `disable-support`, но работает с папкой `Ext/ParentConfigurations/`. + +**Команды:** `sync` + +**Параметры:** нет. + +**Отличие от `disable-support`:** `disable-support` требует отдельное действие в конфигураторе — вызов `СнятьКонфигурациюСПоддержки`. `drop-support` делает то же самое прямыми файловыми операциями — удаляет `*.cf` из `Ext/ParentConfigurations/` и затирает `ParentConfigurations.bin`. + +**Принцип работы:** +1. Удаляет `*.cf` из `Ext/ParentConfigurations/` +2. Записывает в `ParentConfigurations.bin` пустую информацию о поддержке +3. Добавляет `Ext/ParentConfigurations/*.cf` в `.gitignore` +4. Коммитит изменение `.gitignore` + +--- + +## Плагин `edtExport` + +**Назначение:** выгрузка конфигурации в формате EDT (1C:Enterprise Development Tools). + +**Требования:** установленные EDT и утилита `ring` или `1cedtcli`. + +**Команды:** `sync` + +### Параметры + +| Параметр | Кратко | По умолчанию | Переменная окружения | Описание | +|---|---|---|---|---| +| `--project-name` | `-PN` | `""` | `GITSYNC_PROJECT_NAME` | Имя проекта в EDT | +| `--workspace-location` | `-W` | `""` | `GITSYNC_WORKSPACE_LOCATION` | Путь к рабочей области EDT | +| `--base-project-name` | `-BP` | `""` | `GITSYNC_BASE_PROJECT_NAME` | Базовый проект (для расширений) | +| `--edt-version` | `-EDT` | `""` | `GITSYNC_EDT_VERSION` | Версия EDT. Если не задана — автоопределение | + +### Примеры + +``` +# Выгрузка конфигурации в формате EDT +gitsync sync --project-name MyConfig --workspace-location /path/to/workspace /path/to/storage /path/to/src + +# Для расширения с указанием базового проекта +gitsync sync --project-name MyExt --workspace-location /path/to/ws --base-project-name BaseConfig /path/to/storage /path/to/src + +# С указанием версии EDT +gitsync sync --project-name MyConfig --workspace-location /path/to/ws --edt-version 2024.2.5 /path/to/storage /path/to/src +``` + +--- + +## Плагин `increment` + +**Назначение:** инкрементальная выгрузка конфигурации в исходники. Выгружаются только изменённые объекты. + +**Команды:** все (подключается неявно) + +**Параметры:** нет. + +**Принцип работы:** +1. Проверяет наличие `ConfigDumpInfo.xml` в рабочей копии +2. Через `DumpConfigToFiles -getChanges` определяет возможность инкрементальной выгрузки +3. При выгрузке использует флаг `-update` и дамп изменений `ConfigDumpInfo.xml` +4. Сохраняет список изменённых файлов в `dumplist.txt` для использования другими плагинами + +**Несовместимость с другими плагинами:** + +- **`drop-config-dump`** — удаляет `ConfigDumpInfo.xml`, который необходим `increment` для отслеживания изменений. При включении `drop-config-dump` автоматически отключает `increment`. +- **`use-ibcmd`** — предоставляет собственную реализацию инкрементальной выгрузки (через флаг `--increment`). При включении `use-ibcmd` автоматически отключает `increment` и включает свой параметр `--increment`. + +Не рекомендуется включать `increment` одновременно с этими плагинами. + +--- + +## Плагин `limit` + +**Назначение:** ограничение номеров выгружаемых версий хранилища. + +**Команды:** `sync` + +### Параметры + +| Параметр | Кратко | По умолчанию | Переменная окружения | Описание | +|---|---|---|---|---| +| `--limit` | `-l` | `0` | `GITSYNC_LIMIT` | Не более N версий от текущей | +| `--minversion` | — | `0` | — | Минимальный номер версии | +| `--maxversion` | — | `0` | — | Максимальный номер версии | + +### Примеры + +``` +# Выгрузить не более 3 версий +gitsync sync --limit 3 /path/to/storage /path/to/src + +# Выгрузить версии с 5 по 10 +gitsync sync --minversion 5 --maxversion 10 /path/to/storage /path/to/src +``` + +--- + +## Плагин `replace-authors` + +**Назначение:** замена автора коммита через специальный маркер в комментарии к версии хранилища. + +**Команды:** все (подключается неявно) + +**Параметры:** нет. + +**Принцип работы:** при синхронизации ищет в комментариях версий строку `--GitSyncAuthor НовыйАвтор`. Если находит — заменяет автора коммита на указанного. Новый автор должен быть в файле `AUTHORS`. Строка с командой замены удаляется из комментария. + +### Пример + +В хранилище версия от пользователя «Администратор» с комментарием: +``` +Исправление ошибки №12345 +--GitSyncAuthor Иванов +``` + +В git коммит будет создан от имени «Иванов» с комментарием: +``` +Исправление ошибки №12345 +``` + +--- + +## Плагин `roboCopy` + +**Назначение:** (Windows) заменяет штатный механизм копирования исходников на `robocopy` для обхода ограничения на длину пути. + +**Команды:** `sync` + +**Параметры:** нет. + +**Принцип работы:** при очистке и перемещении файлов в каталог рабочей копии использует `robocopy` вместо стандартных файловых операций. Это позволяет работать с путями длиннее 260 символов. + +--- + +## Плагин `smart-tags` + +**Назначение:** автоматическая расстановка тегов git при изменении версии конфигурации. + +**Команды:** `sync`, `export` + +### Параметры + +| Параметр | Кратко | По умолчанию | Переменная окружения | Описание | +|---|---|---|---|---| +| `--skip-exists-tags` | `-S` | `false` | `GITSYNC_SKIP_EXISTS_TAGS` | Пропускать ошибку, если тег уже существует | +| `--numerator` | `-N` | `false` | `GITSYNC_NUMERATOR` | Добавлять тег `v.X` по номеру версии хранилища | +| `--tags-prefix` | `-T` | `""` | `GITSYNC_TAGS_PREFIX` | Префикс для всех создаваемых тегов | + +### Примеры + +``` +# Тег по версии конфигурации с префиксом +gitsync sync --tags-prefix vendor/ /path/to/storage /path/to/src +# Результат: тег vendor/1.3.220.1 + +# Тег-нумератор версий хранилища +gitsync sync --numerator /path/to/storage /path/to/src +# Результат: теги v.1, v.2, ... + +# Комбинация префикса и нумератора +gitsync sync --numerator --tags-prefix release/ /path/to/storage /path/to/src +# Результат: тег release/1.3.220.1 и release/v.1, release/v.2, ... +``` + +--- + +## Плагин `sync-remote` + +**Назначение:** синхронизация с удалённым git-репозиторием (pull/push). + +**Команды:** `sync` + +### Параметры + +| Параметр | Кратко | По умолчанию | Переменная окружения | Описание | +|---|---|---|---|---| +| `--push` | `-PS` | `false` | `GITSYNC_REMOTE_PUSH` | Отправлять изменения на удалённый репозиторий | +| `--pull` | `-G` | `false` | `GITSYNC_REMOTE_PULL` | Получать изменения перед синхронизацией | +| `--branch` | `-b` | `"master"` | `GITSYNC_REMOTE_BRANCH` | Имя ветки | +| `--push-tags` | `-T` | `false` | `GITSYNC_REMOTE_PUSH_TAGS` | Отправлять теги | +| `--push-n-commits` | `-n` | `0` | `GITSYNC_REMOTE_PUSH_N_COMMITS` | Промежуточный push через N коммитов | +| `--push-options` | `-O` | `""` | `GITSYNC_PUSH_OPTIONS` | Дополнительные параметры push (через `;`) | +| аргумент `URL` | — | — | `GITSYNC_REPO_URL` | URL удалённого репозитория | + +### Примеры + +``` +# Получить изменения и отправить после синхронизации +gitsync sync --pull --push /path/to/storage /path/to/src https://github.com/user/repo.git + +# С указанием ветки и отправкой тегов +gitsync sync --push --branch develop --push-tags /path/to/storage /path/to/src https://github.com/user/repo.git + +# Промежуточный push каждые 10 коммитов +gitsync sync --push --push-n-commits 10 /path/to/storage /path/to/src https://github.com/user/repo.git +``` + +--- + +## Плагин `tool1CD` + +**Назначение:** выгрузка конфигурации через утилиту `tool1CD` вместо штатных механизмов 1С. + +**Ограничения:** не работает с серверными хранилищами (`TCP:` и `HTTP`). Неприменим для расширений. + +**Команды:** `sync`, `clone`, `init` + +**Параметры:** нет. + +**Принцип работы:** читает таблицы версий (`VERSIONS`) и пользователей (`USERS`) напрямую из файловой базы хранилища (`1cv8ddb.1CD`), минуя конфигуратор 1С. + +--- + +## Плагин `unpackForm` + +**Назначение:** распаковка обычных форм 1С в исходные файлы. + +**Команды:** `sync` + +### Параметры + +| Параметр | Кратко | По умолчанию | Переменная окружения | Описание | +|---|---|---|---|---| +| `--rename-module` | `-R` | `false` | `GITSYNC_RENAME_MODULE` | Переименовать `module` → `Module.bsl` | +| `--rename-form` | `-F` | `false` | `GITSYNC_RENAME_FORM` | Переименовать `form` → `form.txt` | + +### Примеры + +``` +# Распаковать формы с переименованием модулей +gitsync sync --rename-module /path/to/storage /path/to/src +``` + +--- + +## Плагин `use-ibcmd` + +**Назначение:** выгрузка конфигурации через утилиту `ibcmd` (автономный сервер 1С). + +**Примечание:** при активизации отключает плагин `increment`, перенимая его функцию инкрементальной выгрузки. + +**Команды:** `sync` + +### Параметры + +| Параметр | Кратко | По умолчанию | Переменная окружения | Описание | +|---|---|---|---|---| +| `--ibcmd-data` | — | `""` | `GITSYNC_IBCMD_DATA` | Рабочий каталог ibcmd | +| `--ibcmd-dbms` | `-t` | `"MSSQLServer"` | `GITSYNC_IBCMD_DBMS` | Тип СУБД | +| `--ibcmd-db-server` | `-s` | `""` | `GITSYNC_IBCMD_DB_SERVER` | Адрес сервера БД | +| `--ibcmd-db-name` | `-n` | `""` | `GITSYNC_IBCMD_DB_NAME` | Имя БД | +| `--ibcmd-db-user` | `-U` | `""` | `GITSYNC_IBCMD_DB_USER` | Пользователь БД | +| `--ibcmd-db-pwd` | `-P` | `""` | `GITSYNC_IBCMD_DB_PWD` | Пароль пользователя БД | +| `--ibcmd-threads` | `-j` | `0` | `GITSYNC_IBCMD_THREADS` | Количество потоков | +| `--increment` | `-i` | `false` | `GITSYNC_IBCMD_INCREMENT` | Инкрементальная выгрузка | + +### Примеры + +``` +# Выгрузка из файловой БД +gitsync sync --ibcmd-data /path/to/data /path/to/storage /path/to/src + +# Выгрузка из серверной БД с 4 потоками +gitsync sync --ibcmd-db-server myserver --ibcmd-db-name mydb --ibcmd-db-user admin --ibcmd-db-pwd secret --ibcmd-threads 4 /path/to/storage /path/to/src +``` + +--- + +## Сводная таблица переменных окружения + +| Переменная | Плагин | Параметр | +|---|---|---| +| `GITSYNC_SKIP_EXISTS_TAGS` | smart-tags | `--skip-exists-tags` | +| `GITSYNC_NUMERATOR` | smart-tags | `--numerator` | +| `GITSYNC_TAGS_PREFIX` | smart-tags | `--tags-prefix` | +| `GITSYNC_TASK_PREFIX` | check-comments | `--task-prefix` | +| `GITSYNC_TASK_PATTERN` | check-comments | `--task-pattern` | +| `GITSYNC_AUTHOR_PRESENTATION` | check-comments | `--author-presentation` | +| `GITSYNC_REPAIR_QUOTES` | check-comments | `--repair-quotes` | +| `GITSYNC_LIMIT` | limit | `--limit` | +| `GITSYNC_PROJECT_NAME` | edtExport | `--project-name` | +| `GITSYNC_WORKSPACE_LOCATION` | edtExport | `--workspace-location` | +| `GITSYNC_BASE_PROJECT_NAME` | edtExport | `--base-project-name` | +| `GITSYNC_EDT_VERSION` | edtExport | `--edt-version` | +| `GITSYNC_REMOTE_PUSH` | sync-remote | `--push` | +| `GITSYNC_REMOTE_PULL` | sync-remote | `--pull` | +| `GITSYNC_REMOTE_BRANCH` | sync-remote | `--branch` | +| `GITSYNC_REMOTE_PUSH_TAGS` | sync-remote | `--push-tags` | +| `GITSYNC_REMOTE_PUSH_N_COMMITS` | sync-remote | `--push-n-commits` | +| `GITSYNC_PUSH_OPTIONS` | sync-remote | `--push-options` | +| `GITSYNC_REPO_URL` | sync-remote | аргумент `URL` | +| `GITSYNC_RENAME_MODULE` | unpackForm | `--rename-module` | +| `GITSYNC_RENAME_FORM` | unpackForm | `--rename-form` | +| `GITSYNC_IBCMD_DATA` | use-ibcmd | `--ibcmd-data` | +| `GITSYNC_IBCMD_DBMS` | use-ibcmd | `--ibcmd-dbms` | +| `GITSYNC_IBCMD_DB_SERVER` | use-ibcmd | `--ibcmd-db-server` | +| `GITSYNC_IBCMD_DB_NAME` | use-ibcmd | `--ibcmd-db-name` | +| `GITSYNC_IBCMD_DB_USER` | use-ibcmd | `--ibcmd-db-user` | +| `GITSYNC_IBCMD_DB_PWD` | use-ibcmd | `--ibcmd-db-pwd` | +| `GITSYNC_IBCMD_THREADS` | use-ibcmd | `--ibcmd-threads` | +| `GITSYNC_IBCMD_INCREMENT` | use-ibcmd | `--increment` | diff --git a/features/smart-tags.feature b/features/smart-tags.feature index 238fbd0..85f75f6 100644 --- a/features/smart-tags.feature +++ b/features/smart-tags.feature @@ -43,4 +43,37 @@ Тогда Вывод команды "gitsync" содержит "Завершена синхронизации с git" И Вывод команды "gitsync" не содержит "Внешнее исключение" И Код возврата команды "gitsync" равен 0 - И Тег "1.1.0.1" должен присутствовать в репозитории \ No newline at end of file + И Тег "1.1.0.1" должен присутствовать в репозитории + +Сценарий: Cинхронизация c префиксом тегов + Допустим Я добавляю параметр "--tags-prefix vendor/" для команды "gitsync" + И Я добавляю позиционный параметр для команды "gitsync" из переменной "КаталогХранилища1С" + И Я добавляю позиционный параметр для команды "gitsync" из переменной "ПутьКаталогаИсходников" + И Я записываю "9" в файл VERSION + Когда Я выполняю команду "gitsync" + Тогда Вывод команды "gitsync" содержит "Завершена синхронизации с git" + И Вывод команды "gitsync" не содержит "Внешнее исключение" + И Код возврата команды "gitsync" равен 0 + И Тег "vendor/1.1.0.1" должен присутствовать в репозитории + +Сценарий: Cинхронизация c префиксом тегов через переменную окружения + Допустим Я устанавливаю переменную окружения "GITSYNC_TAGS_PREFIX" равной "vendor/" + И Я добавляю позиционный параметр для команды "gitsync" из переменной "КаталогХранилища1С" + И Я добавляю позиционный параметр для команды "gitsync" из переменной "ПутьКаталогаИсходников" + И Я записываю "9" в файл VERSION + Когда Я выполняю команду "gitsync" + Тогда Вывод команды "gitsync" содержит "Завершена синхронизации с git" + И Вывод команды "gitsync" не содержит "Внешнее исключение" + И Код возврата команды "gitsync" равен 0 + И Тег "vendor/1.1.0.1" должен присутствовать в репозитории + +Сценарий: Cинхронизация с нумератором через переменную окружения + Допустим Я устанавливаю переменную окружения "GITSYNC_NUMERATOR" равной "true" + И Я добавляю позиционный параметр для команды "gitsync" из переменной "КаталогХранилища1С" + И Я добавляю позиционный параметр для команды "gitsync" из переменной "ПутьКаталогаИсходников" + И Я записываю "9" в файл VERSION + Когда Я выполняю команду "gitsync" + Тогда Вывод команды "gitsync" содержит "Завершена синхронизации с git" + И Вывод команды "gitsync" не содержит "Внешнее исключение" + И Код возврата команды "gitsync" равен 0 + И Тег "v.10" должен присутствовать в репозитории \ No newline at end of file diff --git a/features/step_definitions/smart-tags.os b/features/step_definitions/smart-tags.os index f44ed17..4bd2c68 100644 --- a/features/step_definitions/smart-tags.os +++ b/features/step_definitions/smart-tags.os @@ -13,6 +13,7 @@ ВсеШаги = Новый Массив; ВсеШаги.Добавить("ТегДолженПрисутствоватьВРепозитории"); + ВсеШаги.Добавить("ЯУстанавливаюПеременнуюОкружения"); Возврат ВсеШаги; КонецФункции @@ -45,3 +46,10 @@ Ожидаем.Что(Вывод).Содержит(ОжидаемыйВыводКоманды); КонецПроцедуры + +//Я устанавливаю переменную окружения "GITSYNC_TAGS_PREFIX" равной "vendor/" +Процедура ЯУстанавливаюПеременнуюОкружения(Знач ИмяПеременной, Знач Значение) Экспорт + + УстановитьПеременнуюСреды(ИмяПеременной, Значение); + +КонецПроцедуры diff --git a/packagedef b/packagedef index 2f28f64..c1326d5 100644 --- a/packagedef +++ b/packagedef @@ -35,7 +35,7 @@ КонецПроцедуры Описание.Имя("gitsync-plugins") - .Версия("2.0.3") + .Версия("2.1.0") .Автор("Khorev A.A. and SilverBulleters") .АдресАвтора("khorevaa@gmail.com,help@silverbulleters.org") .Описание("Набор предустановленных плагинов для gitsync") diff --git "a/src/\320\232\320\273\320\260\321\201\321\201\321\213/smartTags.os" "b/src/\320\232\320\273\320\260\321\201\321\201\321\213/smartTags.os" index f8f52ef..cb2b8c7 100644 --- "a/src/\320\232\320\273\320\260\321\201\321\201\321\213/smartTags.os" +++ "b/src/\320\232\320\273\320\260\321\201\321\201\321\213/smartTags.os" @@ -9,6 +9,7 @@ Перем НумероватьВерсии; Перем ТекущаяВерсияХранилища1С; +Перем ПрефиксТегов; #Область Интерфейс_плагина @@ -36,7 +37,7 @@ // Строка - описание функциональности плагина // Функция Описание() Экспорт - Возврат "Плагин добавляет функциональность автоматической расстановки меток в git"; + Возврат "Плагин добавляет функциональность автоматической расстановки меток в git. Поддерживает префикс тегов через --tags-prefix"; КонецФункции // Возвращает подробную справку к плагину @@ -45,7 +46,11 @@ // Строка - подробная справка для плагина // Функция Справка() Экспорт - Возврат "Справка плагина"; + Возврат "Плагин при изменении версии конфигурации автоматически создает тег git. +|Параметры: +| --skip-exists-tags - пропуск ошибок создания уже существующих тегов (env: GITSYNC_SKIP_EXISTS_TAGS) +| --numerator - добавляет тег вида v.X по номеру версии хранилища 1С (env: GITSYNC_NUMERATOR) +| --tags-prefix - префикс, добавляемый к каждому автоматически создаваемому тегу, например vendor/ (env: GITSYNC_TAGS_PREFIX)"; КонецФункции // Возвращает имя плагина @@ -92,7 +97,11 @@ .ВОкружении("GITSYNC_SKIP_EXISTS_TAGS"); КлассРеализации.Опция("N numerator", Ложь, "[*smart-tags] флаг добавляет номер хранилища 1С как тег вида v.X") - .Флаговый(); + .Флаговый() + .ВОкружении("GITSYNC_NUMERATOR"); + + КлассРеализации.Опция("T tags-prefix", "", "[*smart-tags] префикс автоматически создаваемых тегов, например vendor/") + .ВОкружении("GITSYNC_TAGS_PREFIX"); КонецПроцедуры @@ -102,6 +111,8 @@ НумероватьВерсии = ПараметрыКоманды.Параметр("numerator", Ложь); + ПрефиксТегов = ПараметрыКоманды.Параметр("tags-prefix", ""); + КонецПроцедуры Процедура ПередНачаломВыполнения(ПутьКХранилищу, КаталогРабочейКопии) Экспорт @@ -136,16 +147,18 @@ Лог.Информация("Определена новая версия конфигурации: %1. Будет установлен новый тег", ТекущаяВерсияКонфигурации); + ИмяТега = ПрефиксТегов + СтрЗаменить(ТекущаяВерсияКонфигурации, " ", ""); + ПараметрыКоманды = Новый Массив; ПараметрыКоманды.Добавить("tag"); - ПараметрыКоманды.Добавить(СтрЗаменить(ТекущаяВерсияКонфигурации, " ", "")); + ПараметрыКоманды.Добавить(ИмяТега); Попытка ГитРепозиторий.ВыполнитьКоманду(ПараметрыКоманды); Исключение ТекстОшибки = ОписаниеОшибки(); Если ПропускатьСуществующиеТеги - И ЭтоОшибкаТегУжеСуществует(ТекстОшибки, ТекущаяВерсияКонфигурации) Тогда + И ЭтоОшибкаТегУжеСуществует(ТекстОшибки, ИмяТега) Тогда Лог.Ошибка(ТекстОшибки); Иначе ТребуетсяВызовИсключения = Истина; @@ -162,16 +175,18 @@ Если ЗначениеЗаполнено(ТекущаяВерсияХранилища1С) Тогда Лог.Информация("Устанавливаем тег-нумератор версии хранилища 1С: 'v.%1'", ТекущаяВерсияХранилища1С); + ИмяТега = ПрефиксТегов + "v." + Строка(ТекущаяВерсияХранилища1С); + ПараметрыКоманды = Новый Массив; ПараметрыКоманды.Добавить("tag"); - ПараметрыКоманды.Добавить("v." + Строка(ТекущаяВерсияХранилища1С)); + ПараметрыКоманды.Добавить(ИмяТега); Попытка ГитРепозиторий.ВыполнитьКоманду(ПараметрыКоманды); Исключение ТекстОшибки = ОписаниеОшибки(); Если ПропускатьСуществующиеТеги - И ЭтоОшибкаТегУжеСуществует(ТекстОшибки, ТекущаяВерсияХранилища1С) Тогда + И ЭтоОшибкаТегУжеСуществует(ТекстОшибки, ИмяТега) Тогда Лог.Ошибка(ТекстОшибки); Иначе ТребуетсяВызовИсключения = Истина; @@ -281,6 +296,7 @@ ПоследняяВерсияКонфигурации = ""; ТекущаяВерсияКонфигурации = ""; ТекущаяВерсияХранилища1С = ""; + ПрефиксТегов = ""; КонецПроцедуры