263 lines
12 KiB
Markdown
263 lines
12 KiB
Markdown
# snag
|
||
|
||
`snag` (snapshot git) — это утилита командной строки для создания, управления и восстановления снимков данных. Она позволяет импортировать, экспортировать, создавать и восстанавливать снимки, а также управлять правилами отслеживания файлов.
|
||
|
||
## Сборка
|
||
|
||
Для сборки необходим предустановленный комплятор языка D (dmd/ldc/gdc), для удобства использовать пакетный менеджер dub:
|
||
|
||
```sh
|
||
dub build --build=release
|
||
```
|
||
|
||
## Использование
|
||
|
||
Основной формат команды:
|
||
|
||
```bash
|
||
snag [флаги] [опции] команда
|
||
```
|
||
|
||
### Флаги
|
||
- `-h, --help` — Выводит справку.
|
||
- `--version` — Выводит версию утилиты.
|
||
|
||
### Опции
|
||
- `-c, --config <путь>` — Указывает путь к файлу конфигурации.
|
||
|
||
### Команды
|
||
- `init` — Инициализация репозитория для хранения снимков.
|
||
- `create` — Создание нового снимка.
|
||
- `import` — Импорт снимка из архива tar.gz.
|
||
- `export` — Экспорт снимка в архив tar.gz.
|
||
- `restore` — Восстановление состояния из указанного снимка.
|
||
- `list` — Вывод списка снимков.
|
||
- `diff` — Показ изменённых данных.
|
||
- `status` — Проверка статуса отслеживаемых файлов.
|
||
- `rules` — Управление правилами отслеживания.
|
||
- `size` — Отображение размера снимков.
|
||
|
||
## Подробное описание команд
|
||
|
||
### `snag init`
|
||
Инициализирует репозиторий для хранения снимков.
|
||
|
||
```bash
|
||
snag init [-h] [-f]
|
||
```
|
||
|
||
- `-f, --force` — Перезаписывает существующий репозиторий.
|
||
|
||
### `snag create`
|
||
Создаёт новый снимок.
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
snag export [-h] [-s <хэш_снимка>] <путь_к_папке>
|
||
```
|
||
|
||
- `-s, --snapshot <хэш>` — Указывает хэш снимка.
|
||
- `<путь_к_папке>` — Путь к папке для сохранения архива.
|
||
|
||
### `snag restore`
|
||
Восстанавливает состояние из указанного снимка.
|
||
|
||
```bash
|
||
snag restore [-h] [--no-pre] [--no-post] <хэш_снимка>
|
||
```
|
||
|
||
- `--no-pre` — Без выполнения предкоманд.
|
||
- `--no-post` — Без выполнения посткоманд.
|
||
- `<хэш_снимка>` — Хэш восстанавливаемого снимка.
|
||
|
||
### `snag list`
|
||
Выводит список снимков.
|
||
|
||
```bash
|
||
snag list [-h] [-c] [-a] [-e]
|
||
```
|
||
|
||
- `-c, --comment` — Показать комментарии к снимкам.
|
||
- `-a, --author` — Показать авторов снимков.
|
||
- `-e, --email` — Показать email авторов.
|
||
|
||
### `snag diff`
|
||
Показывает изменённые данные.
|
||
|
||
```bash
|
||
snag diff
|
||
```
|
||
|
||
### `snag status`
|
||
Проверяет статус отслеживаемых файлов.
|
||
|
||
```bash
|
||
snag status
|
||
```
|
||
|
||
### `snag size`
|
||
Отображает размер снимков.
|
||
|
||
```bash
|
||
snag size
|
||
```
|
||
|
||
### `snag rules`
|
||
Управление правилами отслеживания.
|
||
|
||
```bash
|
||
snag rules [-h] save|show|update|reset|clear
|
||
```
|
||
|
||
- `save` — Сохраняет правила.
|
||
- `show` — Показывает правила.
|
||
```bash
|
||
snag rules show [-h] [-c]
|
||
```
|
||
- `-c, --config` — Показать правила из файла конфигурации.
|
||
- `update` — Обновляет правила.
|
||
```bash
|
||
snag rules update [-h] [-r]
|
||
```
|
||
- `-r, --remove` — Удаляет игнорируемые файлы из отслеживания (Требуется повышенная осторожность!).
|
||
- `reset` — Сбрасывает правила до состояния внесенных изменений.
|
||
- `clear` — Очищает правила.
|
||
|
||
## Примеры использования
|
||
|
||
1. **Инициализация репозитория:**
|
||
```bash
|
||
snag init
|
||
```
|
||
|
||
2. **Создание снимка с комментарием:**
|
||
```bash
|
||
snag create -c "Начальный снимок" -a "Иван Иванов" -e "ivan@example.com"
|
||
```
|
||
|
||
3. **Импорт снимка из архива:**
|
||
```bash
|
||
snag import archive.tar.gz
|
||
```
|
||
|
||
4. **Экспорт снимка:**
|
||
```bash
|
||
snag export -s abc123 /path/to/output
|
||
```
|
||
|
||
5. **Восстановление снимка:**
|
||
```bash
|
||
snag restore abc123
|
||
```
|
||
|
||
6. **Просмотр списка снимков с комментариями:**
|
||
```bash
|
||
snag list -c
|
||
```
|
||
|
||
7. **Обновление правил отслеживания:**
|
||
```bash
|
||
snag rules update
|
||
```
|
||
|
||
## Конфигурация
|
||
|
||
Утилита `snag` поддерживает настройку через конфигурационный файл в формате JSON, который задаётся с помощью опции `-c` или `--config`. Этот файл определяет параметры работы утилиты, включая пути, автора, команды для выполнения до и после создания снимков, а также правила отслеживания файлов.
|
||
|
||
Пример использования конфигурационного файла:
|
||
|
||
```bash
|
||
snag -c /path/to/config.json create
|
||
```
|
||
|
||
### Пример конфигурационного файла
|
||
|
||
```json
|
||
{
|
||
"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
|