Добавлена сборка в пакет для Debian дистрибутива

files/snag.8

@@ -0,0 +1,324 @@
+.\" Man-страница для snag
+.\" Сгенерирована из документации Markdown
+.TH SNAG 1 "30 мая 2025" "1.0" "Команды пользователя"
+.SH НАЗВАНИЕ
+snag \- утилита для создания, управления и восстановления снимков данных
+.SH СИНТАКСИС
+.B snag
+[\fIфлаги\fR] [\fIопции\fR] \fIкоманда\fR
+.SH ОПИСАНИЕ
+.B snag
+(snapshot git) — это утилита командной строки для создания, управления и восстановления снимков данных. Она позволяет импортировать, экспортировать, создавать и восстанавливать снимки, а также управлять правилами отслеживания файлов.
+.SH ФЛАГИ
+.TP
+.BR \-h ", " \-\-help
+Выводит справку.
+.TP
+.BR \-\-version
+Выводит версию утилиты.
+.SH ОПЦИИ
+.TP
+.BR \-c ", " \-\-config " <путь>"
+Указывает путь к файлу конфигурации.
+.SH КОМАНДЫ
+.TP
+.B init
+Инициализация репозитория для хранения снимков.
+.RS
+.B snag init
+[\-h] [\-f]
+.TP
+.BR \-f ", " \-\-force
+Перезаписывает существующий репозиторий.
+.RE
+.TP
+.B create
+Создание нового снимка.
+.RS
+.B snag create
+[\-h] [\-\-no\-pre] [\-\-no\-post] [\-c <комментарий>] [\-a <автор>] [\-e <email>]
+.TP
+.BR \-\-no\-pre
+Выполнение без предкоманд.
+.TP
+.BR \-\-no\-post
+Выполнение без посткоманд.
+.TP
+.BR \-c ", " \-\-comment " <значение>"
+Указывает комментарий к снимку.
+.TP
+.BR \-a ", " \-\-author " <значение>"
+Указывает автора снимка.
+.TP
+.BR \-e ", " \-\-email " <значение>"
+Указывает email автора.
+.RE
+.TP
+.B import
+Импорт снимка из архива tar.gz.
+.RS
+.B snag import
+[\-h] [\-\-no\-pre] [\-\-no\-post] [\-c <комментарий>] [\-a <автор>] [\-e <email>] <путь_к_архиву>
+.TP
+.BR \-\-no\-pre
+Без выполнения предкоманд.
+.TP
+.BR \-\-no\-post
+Без выполнения посткоманд.
+.TP
+.BR \-c ", " \-\-comment " <значение>"
+Комментарий к снимку.
+.TP
+.BR \-a ", " \-\-author " <значение>"
+Автор снимка.
+.TP
+.BR \-e ", " \-\-email " <значение>"
+Email автора.
+.TP
+.BR <путь_к_архиву>
+Путь к файлу tar.gz.
+.RE
+.TP
+.B export
+Экспорт снимка в архив tar.gz.
+.RS
+.B snag export
+[\-h] [\-s <хэш_снимка>] <путь_к_папке>
+.TP
+.BR \-s ", " \-\-snapshot " <хэш>"
+Указывает хэш снимка.
+.TP
+.BR <путь_к_папке>
+Путь к папке для сохранения архива.
+.RE
+.TP
+.B restore
+Восстановление состояния из указанного снимка.
+.RS
+.B snag restore
+[\-h] [\-\-no\-pre] [\-\-no\-post] <хэш_снимка>
+.TP
+.BR \-\-no\-pre
+Без выполнения предкоманд.
+.TP
+.BR \-\-no\-post
+Без выполнения посткоманд.
+.TP
+.BR <хэш_снимка>
+Хэш восстанавливаемого снимка.
+.RE
+.TP
+.B list
+Вывод списка снимков.
+.RS
+.B snag list
+[\-h] [\-c] [\-a] [\-e]
+.TP
+.BR \-c ", " \-\-comment
+Показать комментарии к снимкам.
+.TP
+.BR \-a ", " \-\-author
+Показать авторов снимков.
+.TP
+.BR \-e ", " \-\-email
+Показать email авторов.
+.RE
+.TP
+.B diff
+Показ изменённых данных.
+.RS
+.B snag diff
+.RE
+.TP
+.B status
+Проверка статуса отслеживаемых файлов.
+.RS
+.B snag status
+.RE
+.TP
+.B size
+Отображение размера снимков.
+.RS
+.B snag size
+.RE
+.TP
+.B rules
+Управление правилами отслеживания.
+.RS
+.B snag rules
+[\-h] save|show|update|reset|clear
+.TP
+.B save
+Сохраняет правила.
+.TP
+.B show
+Показывает правила.
+.RS
+.B snag rules show
+[\-h] [\-c]
+.TP
+.BR \-c ", " \-\-config
+Показать правила из файла конфигурации.
+.RE
+.TP
+.B update
+Обновляет правила.
+.RS
+.B snag rules update
+[\-h] [\-r]
+.TP
+.BR \-r ", " \-\-remove
+Удаляет игнорируемые файлы из отслеживания (требуется осторожность).
+.RE
+.TP
+.B reset
+Сбрасывает правила до состояния внесенных изменений.
+.TP
+.B clear
+Очищает правила.
+.RE
+.SH ПРИМЕРЫ
+.TP
+Инициализация репозитория:
+.RS
+.B snag init
+.RE
+.TP
+Создание снимка с комментарием:
+.RS
+.B snag create -c \(dqНачальный снимок\(dq -a \(dqИван Иванов\(dq -e \(dqivan@example.com\(dq
+.RE
+.TP
+Импорт снимка из архива:
+.RS
+.B snag import archive.tar.gz
+.RE
+.TP
+Экспорт снимка:
+.RS
+.B snag export -s abc123 /path/to/output
+.RE
+.TP
+Восстановление снимка:
+.RS
+.B snag restore abc123
+.RE
+.TP
+Просмотр списка снимков с комментариями:
+.RS
+.B snag list -c
+.RE
+.TP
+Обновление правил отслеживания:
+.RS
+.B snag rules update
+.RE
+.SH КОНФИГУРАЦИЯ
+.B snag
+поддерживает настройку через конфигурационный файл в формате JSON, который задаётся с помощью опции
+.B -c
+или
+.B --config.
+Этот файл определяет параметры работы утилиты, включая пути, автора, команды для выполнения до и после создания снимков, а также правила отслеживания файлов.
+
+Пример использования конфигурационного файла:
+.RS
+.B snag -c /path/to/config.json create
+.RE
+
+.SS Пример конфигурационного файла
+.nf
+{
+    "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"
+        ]
+    }
+}
+.fi
+
+.SS Описание полей конфигурационного файла
+.TP
+.B git (строка)
+Путь к репозиторию для хранения снимков (например, /path/to/git/repository/dir).
+.TP
+.B project (строка)
+Путь к проекту или директории, файлы которой отслеживаются (например, /path/to/project).
+.TP
+.B email (строка)
+Email автора снимков (например, user@site.domain). Переопределяется опцией
+.B -e
+или
+.B --email.
+.TP
+.B author (строка)
+Имя автора снимков (например, snag). Переопределяется опцией
+.B -a
+или
+.B --author.
+.TP
+.B presnag (массив строк)
+Список команд, выполняемых перед созданием или импортом снимка (если не указан
+.B --no-pre).
+Пример: systemctl stop my.service.
+.TP
+.B postsnag (массив строк)
+Список команд, выполняемых после создания или импорта снимка (если не указан
+.B --no-post).
+Пример: systemctl start my.service.
+.TP
+.B rules (объект)
+Определяет правила отслеживания файлов.
+.RS
+.TP
+.B tracking (массив строк)
+Список шаблонов файлов или директорий для отслеживания (например, /first_dir/, /second_dir/*.conf, /second_dir/more/).
+.TP
+.B ignore (массив строк)
+Список файлов или директорий, исключаемых из отслеживания (например, /second_dir/more/*.so).
+.RE
+.SS Примечания
+.IP \(bu 4
+Правила в разделе
+.B rules
+можно обновлять с помощью
+.B snag rules update
+или просматривать с помощью
+.B snag rules show -c.
+.IP \(bu 4
+Параметры командной строки, такие как
+.B -e
+или
+.B -a,
+имеют приоритет над значениями из конфигурационного файла.
+.IP \(bu 4
+Убедитесь, что пути, указанные в
+.B git
+и
+.B project,
+существуют и доступны для записи/чтения.
+.IP \(bu 4
+Команды в
+.B presnag
+и
+.B postsnag
+должны быть корректными и доступными в системе, иначе операция может завершиться ошибкой.
+.SH ЛИЦЕНЗИЯ
+GPL-2.0. Подробности см. в файле LICENSE.
+.SH КОНТАКТЫ
+Для вопросов и предложений: alexander@zhirov.kz