Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/oscript-library/gitsync

Синхронизация хранилища 1С с репозиторием git
https://github.com/oscript-library/gitsync

hacktoberfest

Last synced: 3 days ago
JSON representation

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

Host: GitHub
URL: https://github.com/oscript-library/gitsync
Owner: oscript-library
License: mpl-2.0
Created: 2016-09-09T12:58:57.000Z (about 8 years ago)
Default Branch: develop
Last Pushed: 2024-02-29T03:51:36.000Z (9 months ago)
Last Synced: 2024-02-29T04:35:30.710Z (9 months ago)
Topics: hacktoberfest
Language: 1C Enterprise
Homepage:
Size: 1.49 MB
Stars: 245
Watchers: 41
Forks: 87
Open Issues: 86
Metadata Files:
- Readme: readme.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE

Awesome Lists containing this project

awesome-1c - gitsync - Синхронизация хранилища 1С с репозиторием git (Репозитории / Репозитории сообщества)

README

Синхронизация хранилища 1С с репозиторием git
=============================================
[![Last release](https://img.shields.io/github/v/release/oscript-library/gitsync?include_prereleases&label=last%20release&style=badge)](https://github.com/oscript-library/gitsync/releases/latest)
[![GitHub issues](https://img.shields.io/github/issues-raw/oscript-library/gitsync?style=badge)](https://github.com/oscript-library/gitsync/issues)
[![oscript_library](https://img.shields.io/badge/chat-telegram-blue)](https://t.me/oscript_library)

Оглавление
==========

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

## Введение

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

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

[Документация и описание публичного API библиотеки](docs/README.md)

## Установка

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

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

### Вручную
> Запасной споcоб, например, когда на сервере нет доступа к Интернет
1. Скачать файл `gitsync*.ospx` из раздела [releases](https://github.com/khorevaa/gitsync/releases)
2. Установить командой: `opm install -f <ПутьКФайлу>`

## Требования

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

## Особенности

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

* Полностью другая строка вызова приложения, а именно используется стандарт POSIX.
* Работа с хранилищем конфигурации реализована через библиотеку [`v8storage`](https://github.com/khorevaa/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`.

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

```ini
Администратор=Пользователь1
Вася Иванов=Другой Пользователь
```

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

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

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

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

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

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

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

```xml

10
```

Файл можно отредактировать вручную или использовать команду `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)
-e, --ext имя расширения для работы с хранилищем расширения(env $GITSYNC_EXTENSION)
```

#### Глобальные переменные окружения
| Имя | Описание |
| ------------------- | --------------------------------------------------------------------------- |
| `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` | пароль пользователя хранилища конфигурации |
| `GITSYNC_EXTENSION` | имя расширения |

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

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

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

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

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

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

* Вариант для расширения конфигурации

`gitsync sync --ext ИМЯ_Расширения C:/Хранилище_1С/ C:/GIT/src`

Команда выполнит выгрузку версий хранилища расширения 1С из `C:/Хранилище_1С/` для расширения `ИМЯ_Расширения` в репозиторий git в каталоге `C:/GIT/src`.

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

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

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

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

```sh
gitsync sync --storage-user Admin --storage-pwd Secret C:/Хранилище_1С/ C:/work_dir/
```
Имя пользователя = Admin, пароль = Secret.

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

```sh
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/
```

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

```sh
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:
```sh
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:
```cmd
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` - Инициализация предустановленных плагинов (установка из поставляемого пакета)
1. `list` - Вывод списка плагинов
1. `enable` - Активизация установленных плагинов
1. `disable` - Деактивизация установленных плагинов
1. `install` - Установка новых плагинов
1. `clear` - Удаление установленных плагинов
1. `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](https://its.1c.ru/db/v8319doc#bookmark:adm:TI000000493: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`

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

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

* [Как создать свой плагин](./create-new-plugin.md)
* Доработка предустановленных плагинов производится в отдельном репозитории [gitsync-plugins](https://github.com/khorevaa/gitsync-plugins)

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

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

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

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

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

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

`opm build .`

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

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

`opm build -mf ./build_packagedef .`

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

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

## Доработка

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

## Лицензия

Смотри файл [`LICENSE`](./LICENSE).