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

Обсудить

Оглавление

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

Введение

Возможно данный проект примут как следующую версию в gitsync

Проект является форком проекта gitsync см. https://github.com/oscript-library/gitsync и результатом глубокого рефакторинга начального проекта

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

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

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

Установка

Вручную

1. Скачать файл gitsync*.ospx из раздела releases
2. Воспользоваться командой:

$ opm install -f <ПутьКФайлу>

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

1. командой opm install gitsync
2. Запустить командой gitsync

Требования

• утилита 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 репозитория

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

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

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

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

Больше примеров можно увидеть, использовав команду gitsync usage clone

2. Если у Вас нет удаленного репозитория, тогда стоит воспользоваться командой init для выполнения начальной настройки и наполнения данными рабочего каталог

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

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

  Данная команда создаст новый репозиторий git в каталоге C:/GIT/src из хранилища 1С по пути C:/Хранилище_1С/ и наполнил его служебными файлами VERSION и AUTHORS

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

  Тоже самое только для http хранилищем по адресу http:/www.storages.1c.com/repository.1ccr/ИмяХранилища

Справка по команде init: 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С служит файл VERSION.

Данный файл имеет формат xml

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

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

Данный файл можно отредактировать в ручную или воспользовавшись командой set-version.

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

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

Данная команда установит указанную версию <номер_версии> в файл VERSION, который лежит в каталоге <рабочий_каталог>

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

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

Больше примеров можно увидеть, использовав команду gitsync usage set-version

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

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

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

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

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

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

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

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

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

Больше примеров можно увидеть, использовав команду gitsync usage plugins

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

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

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

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

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

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

Подробную справку по опциям и аргументам см. gitsync sync --help

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

Команда: 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/

  Данная команда выполнить синхронизацию хранилища 1С по пути C:/Хранилище_1С/ и репозитория git в каталоге C:/work_dir Используя для подключения к хранилищу 1С пользователя Admin и пароль Secret

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

  gitsync s -uAdmin -p=Secret C:/Хранилище_1С/ C:/work_dir/

  Данная команда выполнить синхронизацию хранилища 1С по пути C:/Хранилище_1С/ и репозитория git в каталоге C:/work_dir Используя для подключения к хранилищу 1С пользователя Admin и пароль Secret

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

  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 для хранилища 1С по пути C:/Хранилище_1С/ и репозитория git в каталоге C:/work_dir Используя для подключения к хранилищу 1С пользователя Admin и пароль Secret

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

  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

  Данная команда выполнить синхронизацию хранилища 1С по пути C:/Хранилище_1С/ и репозитория git в каталоге C:/work_dir Используя для подключения к хранилищу 1С пользователя Admin и пароль Secret

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

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

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

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

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

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

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

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

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

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

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

   opm build .

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

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

   opm build -mf ./build_packagedef .

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

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

Доработка

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

Лицензия

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