# 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