gramax-sync
CLI инструмент для синхронизации и управления множеством Git-репозиториев проекта РИТМ (Gramax).
Описание
gramax-sync — консольный инструмент для работы с множеством Git-репозиториев, определённых в конфигурационном файле workspace.yaml. Инструмент позволяет выполнять массовые операции clone, pull, commit, push для всех репозиториев проекта.
Требования
- Python: 3.10 или выше
- Git: установленный и настроенный
- macOS/Linux/Windows: поддерживаются все платформы
Проверка требований
# Проверка версии Python
python3 --version # Должно быть 3.10+
# Проверка Git
git --version
Установка
Вариант 1: Установка через uv (рекомендуется)
uv — современный, быстрый менеджер пакетов Python.
Шаг 1: Установка uv
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Или через Homebrew (macOS)
brew install uv
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
После установки перезапустите терминал или выполните:
source ~/.bashrc # или ~/.zshrc для zsh
Шаг 2: Клонирование и установка проекта
# Клонировать репозиторий
git clone https://github.com/your-org/gramax-sync.git
cd gramax-sync
# Создать виртуальное окружение и установить зависимости
uv venv
source .venv/bin/activate # macOS/Linux
# или .venv\Scripts\activate # Windows
# Установить проект
uv pip install -e .
Шаг 3: Проверка установки
# Проверить, что команда доступна
gramax-sync --version
# Проверить справку
gramax-sync --help
Вариант 2: Установка через pip
# Клонировать репозиторий
git clone https://github.com/your-org/gramax-sync.git
cd gramax-sync
# Создать виртуальное окружение
python3 -m venv .venv
source .venv/bin/activate # macOS/Linux
# или .venv\Scripts\activate # Windows
# Установить проект
pip install -e .
Вариант 3: Установка для разработки
# Автоматическая настройка (рекомендуется)
make setup
source .venv/bin/activate
# Или вручную через uv:
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
pre-commit install
# Или вручную через pip:
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install -e ".[dev]"
pre-commit install
Подробнее см. DEVELOPMENT.md
Проверка установки
После установки выполните следующие команды для проверки:
# 1. Проверка версии
gramax-sync --version
# Ожидаемый вывод: gramax-sync, version 0.1.0
# 2. Проверка справки
gramax-sync --help
# Должен отобразиться список команд
# 3. Проверка доступности всех команд
gramax-sync auth --help
gramax-sync clone --help
gramax-sync status --help
Устранение проблем установки
Команда не найдена после установки
# Убедитесь, что виртуальное окружение активировано
source .venv/bin/activate
# Проверьте, что пакет установлен
pip list | grep gramax-sync
# Переустановите если нужно
pip install -e .
Ошибка "Python version not supported"
# Проверьте версию Python
python3 --version
# Если версия < 3.10, установите новую версию:
# macOS
brew install python@3.11
# Ubuntu/Debian
sudo apt install python3.11
Проблемы с keyring на Linux
# Установите необходимые библиотеки
sudo apt install libsecret-1-dev # Ubuntu/Debian
sudo dnf install libsecret-devel # Fedora
Использование
Первоначальная настройка
Перед использованием необходимо выполнить первоначальную настройку:
# Интерактивная настройка
gramax-sync init
# Или с параметрами
gramax-sync init \
--repo-url https://itsmf.gitlab.yandexcloud.net/ritm-authors/gramax-yaml-manager \
--branch master \
--catalog-branch private
Команда init выполняет:
- Подключение к репозиторию с конфигурациями
- Проверку доступа и наличия
workspace.yaml - Авторизацию в GitLab при необходимости
- Загрузку и отображение структуры секций и каталогов
- Интерактивный выбор секций/каталогов для работы
Важно: Для репозитория конфигураций используется ветка master (по умолчанию), а для каталогов (репозиториев с кодом) — ветка private.
Работа с репозиториями
# Клонирование всех репозиториев
gramax-sync clone
# Статус всех репозиториев
gramax-sync status
# Обновление всех репозиториев
gramax-sync pull
# Коммит изменений (с автогенерацией сообщения)
gramax-sync commit
# Коммит с кастомным сообщением
gramax-sync commit -m "Update documentation"
# Отправка изменений
gramax-sync push
# Полная синхронизация (pull + commit + push)
gramax-sync sync
# Синхронизация с предварительным просмотром
gramax-sync sync --dry-run
Фильтрация по секциям и каталогам
Все команды поддерживают glob-паттерны для фильтрации:
# Работа только с секциями, начинающимися на "1-"
gramax-sync status --section "1-*"
gramax-sync clone --section "1-методология"
# Работа только с определёнными каталогами
gramax-sync commit --catalog "ritm-*" -m "Fix typos"
# Комбинация фильтров
gramax-sync pull --section "1-*" --catalog "ritm-methodology"
Управление конфигурацией
# Просмотр текущей конфигурации
gramax-sync edit show
# Изменение директории для репозиториев
gramax-sync edit set-workspace-dir --workspace-dir ~/my-workspace
# или интерактивно
gramax-sync edit set-workspace-dir
# Добавление секции или каталога
gramax-sync edit add --section "1-методология" --catalog "ritm-methodology"
# или интерактивно
gramax-sync edit add
# Удаление секции или каталога
gramax-sync edit remove --section "1-методология" --catalog "ritm-methodology"
# Обновление конфигурации с сервера
gramax-sync update
Аутентификация
📖 Подробная информация о правах токена: TOKEN_PERMISSIONS.md
OAuth (рекомендуется)
⚠️ Перед использованием OAuth необходимо создать OAuth Application в GitLab!
-
Создайте OAuth Application:
- Откройте: https://itsmf.gitlab.yandexcloud.net/-/profile/applications
- Нажмите "Add new application"
- Name:
gramax-sync - Redirect URI:
http://localhost:8765/callback - Scopes:
read_api,read_repository,read_user - Скопируйте Application ID
-
Установите Application ID:
export GRAMAX_OAUTH_APPLICATION_ID="ваш_application_id"
Или используйте автоматическую настройку:
./scripts/setup_oauth.sh -
Выполните аутентификацию:
gramax-sync auth login --oauth --url https://itsmf.gitlab.yandexcloud.net
Подробная инструкция: OAUTH_SETUP.md
Personal Access Token (альтернатива)
Необходимые права токена:
read_api- чтение данных через APIread_repository- чтение содержимого репозиториевread_user- получение информации о пользователе
# Войти через Personal Access Token
gramax-sync auth login --pat --url https://itsmf.gitlab.yandexcloud.net
💡 Подробнее: См. TOKEN_PERMISSIONS.md для полной информации о настройке прав токена.
Управление аутентификацией
# Показать статус аутентификации
gramax-sync auth status
# Обновить токен
gramax-sync auth refresh
# Выйти из системы
gramax-sync auth logout --url https://itsmf.gitlab.yandexcloud.net
Конфигурация
Конфигурация хранится в ~/.config/gramax-sync/config.yaml и создаётся автоматически при выполнении команды init.
Репозиторий с конфигурациями должен содержать файл workspace.yaml:
workspace_dir: ~/ritm-workspace
sections:
- name: "1-методология"
catalogs:
- name: "ritm-methodology"
source:
url: "https://gitlab.example.com"
Ветки:
- Репозиторий конфигураций: ветка
master(по умолчанию) - Каталоги (репозитории с кодом): ветка
private(по умолчанию)
Директория для репозиториев:
- По умолчанию:
~/{name}-workspace(гдеname— имя проекта из workspace.yaml) - Можно изменить:
gramax-sync edit set-workspace-dir - Структура:
{workspace_dir}/{section}/{catalog}/
Разработка
Быстрый старт
# Настроить окружение
make setup
source .venv/bin/activate
# Запустить тесты
make test
# Проверить код
make check
# Отформатировать код
make format
Полезные команды
make help # Показать все команды
make test # Запустить тесты
make test-cov # Тесты с покрытием
make lint # Проверить линтерами
make format # Отформатировать код
make type-check # Проверить типы
make check # Проверить всё
make clean # Очистить временные файлы
Документация
- DEVELOPMENT.md — Руководство по разработке
- ARCHITECTURE_PRINCIPLES.md — Принципы архитектуры
- ROADMAP.md — Дорожная карта развития
- OAUTH_SETUP.md — Настройка OAuth
- MCP_SETUP.md — MCP Server для Claude Desktop
- TOKEN_PERMISSIONS.md — Права токенов GitLab
- CLAUDE.md — Контекст для Claude Code
MCP Server для Claude Desktop
gramax-sync включает MCP Server для интеграции с Claude Desktop.
Доступные инструменты:
list_repositories— список секций и каталоговget_repository_status— статус репозиториевclone_repositories— клонированиеpull_repositories— обновлениеcommit_changes— коммит измененийpush_changes— отправка измененийsync_repositories— полная синхронизация
Подробнее см. MCP_SETUP.md
Лицензия
MIT
Metadata
Release files for gramax-sync 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gramax_sync-0.1.1.tar.gz | 52.8 kB | Without provenance | Details for gramax_sync-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gramax_sync-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for gramax_sync-0.1.1-py3-none-any.whl |
Total release size: 117.1 kB
Release files / gramax_sync-0.1.1.tar.gz
| Download URL | gramax_sync-0.1.1.tar.gz |
|---|---|
| Size | 52.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
71892c55efa11d2b9a55006c3a75ff75d73c5309b2a960f6d4720cefb81aff04
|
|
BLAKE2b-256 checksum How to use checksums |
9e498ddb5cda99bc52322dcd132cd0fb1f89cdd6d9a4b03f1ae9f66518c9960b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Release files / gramax_sync-0.1.1-py3-none-any.whl
| Download URL | gramax_sync-0.1.1-py3-none-any.whl |
|---|---|
| Size | 64.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4c22ae6d40a9cc1a4ede9e0eb8cf657a0ee5774230b013e66fa472d8cf053b0c
|
|
BLAKE2b-256 checksum How to use checksums |
2099930612383418762d8ebb80ec50ed1c048368ee9f81b91442d0f9021bf11c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Security for gramax-sync 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.