Обновлено описание, добавлена лицензия
This commit is contained in:
parent
60139a1874
commit
b2a0a9eeae
GPG key ID:
C8D8BE544A27C511
2 changed files with 575 additions and 42 deletions
279
README.md
279
README.md
|
|
@ -1,68 +1,263 @@
|
|||
# snag
|
||||
|
||||
Snapshot Git - система резервного копирования на основе фиксации состояния файлов с помощью Git.
|
||||
`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": "/tmp/testgit",
|
||||
"project": "/tmp/test",
|
||||
"git": "/path/to/git/repository/dir",
|
||||
"project": "/path/to/project",
|
||||
"email": "user@site.domain",
|
||||
"user": "snag"
|
||||
"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"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
1. **`"git"`**
|
||||
- *Тип:* Строка (путь)
|
||||
- *Назначение:* Указывает расположение Git-репозитория
|
||||
### Описание полей конфигурационного файла
|
||||
|
||||
2. **`"project"`**
|
||||
- *Тип:* Строка (путь)
|
||||
- *Назначение:* Корневая директория для отслеживания состояния файлов
|
||||
- **`git`** (`string`): Путь к репозиторию для хранения снимков. В примере: `/path/to/git/repository/dir`. Этот путь используется при инициализации репозитория (`snag init`) для определения места хранения метаданных и снимков.
|
||||
|
||||
3. **`"email"`**
|
||||
- *Тип:* Строка (email)
|
||||
- *Назначение:* Email автора коммитов в Git
|
||||
- **`project`** (`string`): Путь к проекту или директории, файлы которой отслеживаются утилитой. В примере: `/path/to/project`. Указывает корневую папку, в которой `snag` будет создавать, импортировать или восстанавливать снимки.
|
||||
|
||||
4. **`"user"`**
|
||||
- *Тип:* Строка
|
||||
- *Назначение:* Имя пользователя для Git-операций
|
||||
- **`email`** (`string`): Email автора снимков. Используется для метаданных снимков при выполнении команд, таких как `snag create` или `snag import`. В примере: `user@site.domain`. Может переопределяться опцией `-e` или `--email`.
|
||||
|
||||
### Описание программы `snag`
|
||||
- **`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` после завершения операции. Это может использоваться для восстановления работы сервиса после создания или импорта снимка.
|
||||
|
||||
```bash
|
||||
snag [ОПЦИИ] [ГЛАВНАЯ_КОМАНДА] [ОПЦИИ] [АРГУМЕНТЫ]
|
||||
```
|
||||
- **`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` должны быть корректными и доступными в системе, иначе выполнение операции может завершиться ошибкой.
|
||||
|
||||
| Команда | Описание |
|
||||
|------------|--------------------------------------------------------------------------|
|
||||
| `restore` | Восстановить проект до состояния указанного снимка |
|
||||
| `init` | Инициализировать репозиторий для хранения снимков |
|
||||
| `list` | Показать список доступных снимков |
|
||||
| `status` | Проверить состояние отслеживаемых файлов (изменения с последнего снимка) |
|
||||
| `create` | Создать новый снимок состояния проекта |
|
||||
## Лицензия
|
||||
|
||||
---
|
||||
Лицензия GPL-2.0. Подробности см. в файле `LICENSE`.
|
||||
|
||||
#### **Флаги и опции**
|
||||
## Контакты
|
||||
|
||||
| Опция | Описание |
|
||||
|---------------------|--------------------------------------------------------------------------|
|
||||
| `-h`, `--help` | Показать справку по команде |
|
||||
| `--version` | Показать версию программы |
|
||||
| `-c`, `--config` | Указать путь к файлу конфигурации (необязательно) |
|
||||
|
||||
---
|
||||
Для вопросов и предложений: alexander@zhirov.kz
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue