dlang/snag
1
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions
snag/README.md

12 KiB
Raw Permalink Blame History

snag

snag (snapshot git) — это утилита командной строки для создания, управления и восстановления снимков данных. Она позволяет импортировать, экспортировать, создавать и восстанавливать снимки, а также управлять правилами отслеживания файлов.

Сборка

Для сборки необходим предустановленный комплятор языка D (dmd/ldc/gdc), для удобства использовать пакетный менеджер dub:

dub build --build=release

Использование

Основной формат команды:

snag [флаги] [опции] команда

Флаги

  • -h, --help — Выводит справку.
  • --version — Выводит версию утилиты.

Опции

  • -c, --config <путь> — Указывает путь к файлу конфигурации.

Команды

  • init — Инициализация репозитория для хранения снимков.
  • create — Создание нового снимка.
  • import — Импорт снимка из архива tar.gz.
  • export — Экспорт снимка в архив tar.gz.
  • restore — Восстановление состояния из указанного снимка.
  • list — Вывод списка снимков.
  • diff — Показ изменённых данных.
  • status — Проверка статуса отслеживаемых файлов.
  • rules — Управление правилами отслеживания.
  • size — Отображение размера снимков.

Подробное описание команд

snag init

Инициализирует репозиторий для хранения снимков.

snag init [-h] [-f]
  • -f, --force — Перезаписывает существующий репозиторий.

snag create

Создаёт новый снимок.

snag create [-h] [--no-pre] [--no-post] [-c <комментарий>] [-a <автор>] [-e <email>]
  • --no-pre — Выполнение без предкоманд.
  • --no-post — Выполнение без посткоманд.
  • -c, --comment <значение> — Указывает комментарий к снимку.
  • -a, --author <значение> — Указывает автора снимка.
  • -e, --email <значение> — Указывает email автора.

snag import

Импортирует снимок из архива tar.gz.

snag import [-h] [--no-pre] [--no-post] [-c <комментарий>] [-a <автор>] [-e <email>] <путь_к_архиву>
  • --no-pre — Без выполнения предкоманд.
  • --no-post — Без выполнения посткоманд.
  • -c, --comment <значение> — Комментарий к снимку.
  • -a, --author <значение> — Автор снимка.
  • -e, --email <значение> — Email автора.
  • <путь_к_архиву> — Путь к файлу tar.gz.

snag export

Экспортирует снимок в архив tar.gz.

snag export [-h] [-s <хэш_снимка>] <путь_к_папке>
  • -s, --snapshot <хэш> — Указывает хэш снимка.
  • <путь_к_папке> — Путь к папке для сохранения архива.

snag restore

Восстанавливает состояние из указанного снимка.

snag restore [-h] [--no-pre] [--no-post] <хэш_снимка>
  • --no-pre — Без выполнения предкоманд.
  • --no-post — Без выполнения посткоманд.
  • <хэш_снимка> — Хэш восстанавливаемого снимка.

snag list

Выводит список снимков.

snag list [-h] [-c] [-a] [-e]
  • -c, --comment — Показать комментарии к снимкам.
  • -a, --author — Показать авторов снимков.
  • -e, --email — Показать email авторов.

snag diff

Показывает изменённые данные.

snag diff

snag status

Проверяет статус отслеживаемых файлов.

snag status

snag size

Отображает размер снимков.

snag size

snag rules

Управление правилами отслеживания.

snag rules [-h] save|show|update|reset|clear
  • save — Сохраняет правила.
  • show — Показывает правила. 
    snag rules show [-h] [-c]
    • -c, --config — Показать правила из файла конфигурации.
  • update — Обновляет правила. 
    snag rules update [-h] [-r]
    • -r, --remove — Удаляет игнорируемые файлы из отслеживания (Требуется повышенная осторожность!).
  • reset — Сбрасывает правила до состояния внесенных изменений.
  • clear — Очищает правила.

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

  1. Инициализация репозитория:

    snag init

  2. Создание снимка с комментарием:

    snag create -c "Начальный снимок" -a "Иван Иванов" -e "ivan@example.com"

  3. Импорт снимка из архива:

    snag import archive.tar.gz

  4. Экспорт снимка:

    snag export -s abc123 /path/to/output

  5. Восстановление снимка:

    snag restore abc123

  6. Просмотр списка снимков с комментариями:

    snag list -c

  7. Обновление правил отслеживания:

    snag rules update

Конфигурация

Утилита snag поддерживает настройку через конфигурационный файл в формате JSON, который задаётся с помощью опции -c или --config. Этот файл определяет параметры работы утилиты, включая пути, автора, команды для выполнения до и после создания снимков, а также правила отслеживания файлов.

Пример использования конфигурационного файла:

snag -c /path/to/config.json create

Пример конфигурационного файла

{
	"git": "/path/to/git/repository/dir",
	"project": "/path/to/project",
	"email": "user@site.domain",
	"author": "snag",
	"presnag": [
		"systemctl stop my.service"
	],
	"postsnag": [
		"systemctl start my.service"
	],
	"rules": {
		"tracking": [
			"/first_dir/",
			"/second_dir/*.conf",
			"/second_dir/more/"
		],
		"ignore": [
			"/second_dir/more/*.so"
		]
	}
}

Описание полей конфигурационного файла

  • git (string): Путь к репозиторию для хранения снимков. В примере: /path/to/git/repository/dir. Этот путь используется при инициализации репозитория (snag init) для определения места хранения метаданных и снимков.

  • project (string): Путь к проекту или директории, файлы которой отслеживаются утилитой. В примере: /path/to/project. Указывает корневую папку, в которой snag будет создавать, импортировать или восстанавливать снимки.

  • email (string): Email автора снимков. Используется для метаданных снимков при выполнении команд, таких как snag create или snag import. В примере: user@site.domain. Может переопределяться опцией -e или --email.

  • author (string): Имя автора снимков. Используется для метаданных снимков. В примере: snag. Может переопределяться опцией -a или --author.

  • presnag (array of strings): Список команд, выполняемых перед созданием или импортом снимка (если не указан флаг --no-pre). В примере:

    • systemctl stop my.service — останавливает сервис my.service перед выполнением операции. Это может быть полезно для временной остановки сервиса, чтобы обеспечить целостность данных во время создания снимка.

  • postsnag (array of strings): Список команд, выполняемых после создания или импорта снимка (если не указан флаг --no-post). В примере:

    • systemctl start my.service — запускает сервис my.service после завершения операции. Это может использоваться для восстановления работы сервиса после создания или импорта снимка.

  • rules (object): Определяет правила отслеживания файлов.

    • tracking (array of strings): Список шаблонов файлов или директорий, которые отслеживаются утилитой. В примере:
      • /first_dir/ — отслеживается вся директория /first_dir и её содержимое.
      • /second_dir/*.conf — отслеживаются все файлы с расширением .conf в директории /second_dir.
      • /second_dir/more/ — отслеживается вся директория /second_dir/more и её содержимое.
    • ignore (array of strings): Список файлов или директорий, которые исключаются из отслеживания. В примере:
      • /second_dir/more/*.so — игнорируются все файлы с расширением .so в директории /second_dir/more.

Примечания

  • Правила в разделе rules можно обновлять с помощью команды snag rules update или просматривать с помощью snag rules show -c.
  • Если параметры, такие как email или author, указаны в командной строке (например, через -e или -a), они имеют приоритет над значениями из конфигурационного файла.
  • Убедитесь, что пути, указанные в git и project, существуют и доступны для записи/чтения перед выполнением операций.
  • Команды в presnag и postsnag должны быть корректными и доступными в системе, иначе выполнение операции может завершиться ошибкой.

Лицензия

Лицензия GPL-2.0. Подробности см. в файле LICENSE.

Контакты

Для вопросов и предложений: alexander@zhirov.kz