Синхронизация хранилища 1С с репозиторием git

Оглавление

• Синхронизация хранилища 1С с репозиторием git
• Оглавление
  • Введение
  • Установка
    • Через пакетный менеджер opm
    • Вручную
  • Требования
  • Особенности
    • Отличия от gitsync версий 2.x
    • Описание функциональности
  • Использование приложения gitsync
    • Подготовка
      • Подготовка нового репозитория (локального)
      • Установка соответствия пользователей
      • Установка номера начальной версии хранилища 1С для синхронизации
    • Синхронизация
      • Справка по использованию команды
      • Глобальные переменные окружения
      • Переменные окружения команды
      • Значения по умолчанию
      • Примеры использования
      • Настройка плагинов синхронизации
  • Использование библиотеки gitsync
  • Доработка и разработка плагинов
  • Механизм подписок на события
  • Сборка проекта
  • Доработка
  • Лицензия

Введение

Проект gitsync представляет собой:

1. Библиотеку gitsync (src/core) - которая реализует основные классы для синхронизации хранилища 1С с git
2. Приложение gitsync (src/cmd) - консольное приложение на основе библиотеки cli

Документация и описание публичного API библиотеки

Установка

Через пакетный менеджер opm

1. Установить командой opm install gitsync

Вручную

Запасной споcоб, например, когда на сервере нет доступа к Интернет

1. Скачать файл gitsync*.ospx из раздела releases
2. Установить командой: opm install -f <ПутьКФайлу>

Требования

• утилита ring и `` - для работы с 1С старше версии > 8.3.11

Особенности

Отличия от gitsync версий 2.x

• Полностью другая строка вызова приложения, а именно используется стандарт POSIX.
• Работа с хранилищем конфигурации реализована через библиотеку v8storage
• Реализована поддержка работы с хранилищем по протоколу http и tcp
• Функциональность работы через tool1CD - перенесена в предустановленный плагин tool1CD
• Вместо двух команд sync и export оставлена только одна команда sync, которая работает как команда export в предыдущих версиях, при этом функциональность синхронизации с удаленным репозиторием (команды git pull и git push ) перенесена в отдельный плагин sync-remote
• Прекращена поддержка выгрузки конфигурации в исходники в формате plain
• Прекращена поддержка использования файла renames.txt и переименования длинных файлов
• Расширен функционал за счет использования механизма подписок на события
• Пока не поддерживается синхронизация с несколькими хранилищами одновременно. (команда all)

Описание функциональности

Раздел документации в разработке

Использование приложения gitsync

Подготовка

Подготовка нового репозитория (локального)

Данный шаг можно пропустить, если у Вас уже есть локальный репозиторий git

a. Если у Вас уже есть удаленный репозиторий (ранее выполнялась синхронизация с сервером git) - используйте команду clone

Синтаксис команды: gitsync clone [ОПЦИИ] PATH URL [WORKDIR]

Пример использования:

gitsync clone --storage-user Администратор --storage-pwd Секрет <путь_к_хранилищу_1С> <адрес_удаленного_репозитория> <рабочий_каталог>(необязательный)

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

Справка по команде: gitsync clone --help

Больше примеров: gitsync usage clone

b. Если у Вас нет удаленного репозитория - используйте команду init

Синтаксис команды: gitsync init [ОПЦИИ] PATH [WORKDIR]

Пример использования:

• gitsync init --storage-user Администратор --storage-pwd Секрет C:/Хранилище_1С/ C:/GIT/src

  Команда создаст новый репозиторий (каталог) .git в каталоге C:/GIT/src, и наполнит его служебными файлами VERSION и AUTHORS.
  На данном этапе хранилище 1С по пути C:/Хранилище_1С/ используется для наполнения файла AUTHORS. Выгрузка хранилища 1С (синхронизация с репозиторием .git ) не выполняется.

• gitsync init --storage-user Администратор --storage-pwd Секрет http:/www.storages.1c.com/repository.1ccr/ИмяХранилища C:/GIT/src

  Вариант для подключения к хранилищу по протоколу http

Справка по команде: gitsync init --help

Больше примеров: gitsync usage init

Установка соответствия пользователей

Данный шаг можно пропустить, если у Вас уже установлено соответствие пользователей хранилища 1С и git

Для настройки соответствия между пользователями хранилища 1С и git-сервера предназначен файл AUTHORS.

Файл заполняется в формате ini.

Пример файла:

Администратор=Пользователь1 <admin-user@mail.com>
Вася Иванов=Другой Пользователь <user-user@mail.com>

слева указано имя пользователя хранилища 1С справа - представление имени пользователя репозитория git и его e-mail

С помощью e-mail выполняется связка пользователя с публичными репозиториями (например, Github или Bitbucket)

Установка номера начальной версии хранилища 1С для синхронизации

Данный шаг можно пропустить, если у Вас уже установлен номер версии в файле VERSION

При выгрузке изменений хранилища 1С в каталог проекта (в рабочий каталог), gitsync ориентируется на номер последней выгруженной версии, указанный в файле VERSION. Номер версии в файле надо указать если Вы не хотите выгружать в git все версии хранилища 1С.

Файл заполняется в формате xml.

Пример файла, в котором указано, что выгружено 10 версий:

<?xml version="1.0" encoding="UTF-8"?>
<VERSION>10</VERSION>

Файл можно отредактировать вручную или использовать команду set-version.
Пример использования команды:

gitsync set-version <номер_версии> <рабочий_каталог>(необязательный)

Справка по команде: gitsync set-version --help

Для удобства использования команда set-version имеет короткое название sv.

Больше примеров: gitsync usage set-version

Синхронизация

Команда sync (синоним s) - выполняет синхронизацию хранилища 1С с git-репозиторием

Подробную справку по опциям и аргументам см. gitsync sync --help. Важно: описание опций команды sync при использовании плагина выводится только после активации этого плагина.

Справка по использованию команды

Команда: sync, s
 Выполняет синхронизацию хранилища 1С с git-репозиторием

Строка запуска: gitsync sync [ОПЦИИ] PATH [WORKDIR]

Аргументы:
  PATH          Путь к хранилищу конфигурации 1С. (env $GITSYNC_STORAGE_PATH)
  WORKDIR       Каталог исходников внутри локальной копии git-репозитория. (env $GITSYNC_WORKDIR)

Опции:
  -u, --storage-user    пользователь хранилища конфигурации (env $GITSYNC_STORAGE_USER) (по умолчанию Администратор)
  -p, --storage-pwd     пароль пользователя хранилища конфигурации (env $GITSYNC_STORAGE_PASSWORD, $GITSYNC_STORAGE_PWD)

Глобальные переменные окружения

Имя	Описание
GITSYNC_V8VERSION	маска версии платформы (8.3, 8.3.5, 8.3.6.2299 и т.п.)
GITSYNC_V8_PATH	путь к исполняемому файлу платформы 1С (Например, /opt/1C/v8.3/x86_64/1cv8)
GITSYNC_VERBOSE	вывод отладочной информации в процессе выполнения
GITSYNC_TEMP	путь к каталогу временных файлов
GITSYNC_EMAIL	домен почты для пользователей git

Переменные окружения команды

Имя	Описание
GITSYNC_WORKDIR	рабочий каталог для команды
GITSYNC_STORAGE_PATH	путь к хранилищу конфигурации 1С.
GITSYNC_STORAGE_USER	пользователь хранилища конфигурации
GITSYNC_STORAGE_PASSWORD	пароль пользователя хранилища конфигурации

Значения по умолчанию

WORKDIR	текущая рабочая директория
-u, --storage-user	пользователь Администратор

Примеры использования

• Примитивный вариант

  gitsync sync C:/Хранилище_1С/ C:/GIT/src

  Команда выполнит выгрузку версий хранилища 1С из C:/Хранилище_1С/ в репозиторий git в каталоге C:/GIT/src. Пример учебный, на практике обычно требуется указать также имя пользователя хранилища и пароль.

• Вариант вызова команды в текущем рабочем каталоге

  переменная окружения GITSYNC_WORKDIR не должна быть задана

  cd C:/work_dir/
  gitsync sync C:/Хранилище_1С/

  Команда выполнит выгрузку версий хранилища 1С из C:/Хранилище_1С/ в репозиторий git в каталоге C:/work_dir

• Вариант с указанием пользователя хранилища и пароля

  gitsync sync --storage-user Admin --storage-pwd Secret C:/Хранилище_1С/ C:/work_dir/

  Имя пользователя = Admin, пароль = Secret.

• Использование синонимов (короткая версия предыдущего примера)

  gitsync s -u Admin -p Secret C:/Хранилище_1С/ C:/work_dir/
  # возможны варианты
  # gitsync s -uAdmin -pSecret C:/Хранилище_1С/ C:/work_dir/
  # gitsync s -u=Admin -p=Secret C:/Хранилище_1С/ C:/work_dir/

• Указание исполняемого файла нужной версии платформы

  gitsync --v8-path /opt/1C/v8.3/x86_64/1cv8 s -uAdmin -p=Secret C:/Хранилище_1С/ C:/work_dir/

  Команда синхронизации будет выполнена с использованием исполняемого файла платформы /opt/1C/v8.3/x86_64/1cv8 (приведен синтаксис для linux; вариант для Windows см. ниже).

• Вызов команды без указания параметров, с использованием переменных окружения

  linux:

  export GITSYNC_WORKDIR=./work_dir/
  export GITSYNC_STORAGE_PATH=./Хранилище_1С/
  
  export GITSYNC_STORAGE_USER=Admin
  export GITSYNC_STORAGE_PASSWORD=Secret
  export GITSYNC_V8VERSION=8.3.7
  # Указание конкретного исполняемого файла платформы 1С. Путь надо обернуть в кавычки если он содержит пробелы.
  #export GITSYNC_V8_PATH=/opt/1C/v8.3/x86_64/1cv8
  export GITSYNC_VERBOSE=true #Можно использовать Да/Ложь/Нет/Истина
  export GITSYNC_TEMP=./temp/sync
  gitsync s

  windows:

  set GITSYNC_WORKDIR=./work_dir/
  set GITSYNC_STORAGE_PATH=./Хранилище_1С/
  
  set GITSYNC_STORAGE_USER=Admin
  set GITSYNC_STORAGE_PASSWORD=Secret
  set GITSYNC_V8VERSION=8.3.7
  # Указание конкретного исполняемого файла платформы 1С. Путь надо обернуть в кавычки если он содержит пробелы.
  #set GITSYNC_V8_PATH="C:\Program Files (x86)\1cv8\8.3.12.1567\bin\1cv8.exe"
  set GITSYNC_VERBOSE=true #Можно использовать Да/Ложь/Нет/Истина
  set GITSYNC_TEMP=./temp/sync
  
  gitsync s

Настройка плагинов синхронизации

Данный пункт можно пропустить, если Вам не требуется дополнительная функциональность синхронизации

Для расширения функциональности синхронизации предлагается механизм плагинов. Данный механизм реализован через подписки на события синхронизации, с возможностью переопределения стандартной обработки.

Для обеспечения управления плагинами реализована подкоманда plugins, а так же ряд вложенных команд:

1. init - Инициализация предустановленных плагинов (установка из поставляемого пакета)
2. list - Вывод списка плагинов
3. enable - Активизация установленных плагинов
4. disable - Деактивизация установленных плагинов
5. install - Установка новых плагинов
6. clear - Удаление установленных плагинов
7. help - Вывод справки по выбранным плагинам

Пример использования:

• gitsync plugins enable limit - будет активирован плагин limit
• gitsync plugins enable -a - будут активированы все предустановленные плагины
• gitsync plugins enable - будет выведен список всех установленных плагинов для интерактивного выбора и активации выбранных
• gitsync plugins list - будет выведен список всех активированных плагинов
• gitsync plugins list -a - будет выведен список всех установленных плагинов

Справка по команде: gitsync plugins --help

Для удобства использования команда plugins имеет короткое название p.

Больше примеров: gitsync usage plugins

Для хранения установленных плагинов и списка активных плагинов используется каталог локальных данных приложения - для Windows это C:\Users\UserName\AppData\Local\gitsync\plugins

Список предустановленных плагинов:

Для инициализации предустановленных плагинов необходимо выполнить команду gitsync plugins init. Описание используемых плагинами опций см. в справке к команде sync.

1. increment - включает режим инкрементальной выгрузки конфигурации в исходники.
   Выгружается не вся конфигурация, а только те объекты, версия которых отличается от версии, имеющейся в каталоге. См. DumpConfigToFiles, опция update.
2. sync-remote - добавляет опции команды sync для синхронизации с удаленным репозиторием git (команды git pull и git push)
3. limit - позволяет ограничить количество выгружаемых версий за один запуск, а так же указать минимальную и/или максимальную версию хранилища для выгрузки
4. check-authors - блокирует выгрузку версии, если автор версии хранилища отсутствует в файле AUTHORS
5. check-comments - добавляет опции команды sync для проверки наличия комментария у версии хранилища, а также для проверки заполнения комментария
6. smart-tags - устанавливает тег равный версии конфигурации при смене версии конфигурации (не путать с версией хранилища). А также добавляет опции команды sync для автоматической установки метки git (команда git tag) равной версии хранилища (в формате "v.номер").
7. unpackForm - выполняет распаковку обычных форм на исходники. Добавляет опции команды sync для переименования объектов обычных форм.
8. tool1CD - заменяет использование штатных механизмов 1С на приложение tool1CD при выгрузке
9. disable-support - снимает конфигурацию с поддержки перед выгрузкой в исходники
10. edtExport - добавляет возможность выгрузки в формате EDT. Для работы плагина необходимо установить EDT.

Использование библиотеки gitsync

Раздел документации в разработке

Доработка и разработка плагинов

• Как создать свой плагин
• Доработка предустановленных плагинов производится в отдельном репозитории gitsync-plugins

Механизм подписок на события

Раздел документации в разработке

Проект gitsync поддерживает ряд подписок на события

Сборка проекта

Сборка производится в 2-х режимах:

1. Сборка обычного пакета (без зависимостей)

   opm build .

   В этом варианте в сборку не добавляются предустановленные пакеты. Их надо будет устанавливать отдельно.

2. Сборка пакета с зависимостями

   opm build -mf ./build_packagedef .

   В сборку будут добавлены пакеты из репозиториев:

   • opm - из ветки develop
   • gitsync-pre-plugins - из ветки develop

Доработка

Доработка проводится по git-flow. Жду ваших PR.

Лицензия

Смотри файл LICENSE.