From 0d99f4429162f92dbba590c526bb50a48b32ea64 Mon Sep 17 00:00:00 2001 From: Alexander Zhirov Date: Thu, 29 May 2025 20:14:05 +0300 Subject: [PATCH] 0.1.0-alpha.1 --- README.en.md | 257 +++++++++++++++++++++++++++++++++++++++++ dub.json | 2 +- source/snag/version_.d | 2 +- 3 files changed, 259 insertions(+), 2 deletions(-) create mode 100644 README.en.md diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..622616c --- /dev/null +++ b/README.en.md @@ -0,0 +1,257 @@ +# snag + +`snag` (snapshot git) is a command-line utility for creating, managing, and restoring data snapshots. It allows importing, exporting, creating, and restoring snapshots, as well as managing file tracking rules. + +## Build + +To build, a pre-installed D language compiler (dmd/ldc/gdc) is required. For convenience, use the dub package manager: + +```sh +dub build --build=release +``` + +## Usage + +Basic command format: + +```bash +snag [flags] [options] command +``` + +### Flags +- `-h, --help` — Displays help. +- `--version` — Displays the utility version. + +### Options +- `-c, --config ` — Specifies the path to the configuration file. + +### Commands +- `init` — Initializes a repository for storing snapshots. +- `create` — Creates a new snapshot. +- `import` — Imports a snapshot from a tar.gz archive. +- `export` — Exports a snapshot to a tar.gz archive. +- `restore` — Restores state from a specified snapshot. +- `list` — Lists snapshots. +- `diff` — Shows changed data. +- `status` — Checks the status of tracked files. +- `rules` — Manages tracking rules. +- `size` — Displays snapshot sizes. + +## Detailed Command Description + +### `snag init` +Initializes a repository for storing snapshots. + +```bash +snag init [-h] [-f] +``` + +- `-f, --force` — Overwrites an existing repository. + +### `snag create` +Creates a new snapshot. + +```bash +snag create [-h] [--no-pre] [--no-post] [-c ] [-a ] [-e ] +``` + +- `--no-pre` — Skips pre-commands. +- `--no-post` — Skips post-commands. +- `-c, --comment ` — Specifies a comment for the snapshot. +- `-a, --author ` — Specifies the snapshot author. +- `-e, --email ` — Specifies the author's email. + +### `snag import` +Imports a snapshot from a tar.gz archive. + +```bash +snag import [-h] [--no-pre] [--no-post] [-c ] [-a ] [-e ] +``` + +- `--no-pre` — Skips pre-commands. +- `--no-post` — Skips post-commands. +- `-c, --comment ` — Comment for the snapshot. +- `-a, --author ` — Snapshot author. +- `-e, --email ` — Author's email. +- `` — Path to the tar.gz file. + +### `snag export` +Exports a snapshot to a tar.gz archive. + +```bash +snag export [-h] [-s ] +``` + +- `-s, --snapshot ` — Specifies the snapshot hash. +- `` — Path to the output directory for the archive. + +### `snag restore` +Restores state from a specified snapshot. + +```bash +snag restore [-h] [--no-pre] [--no-post] +``` + +- `--no-pre` — Skips pre-commands. +- `--no-post` —焦性 +- `` — Hash of the snapshot to restore. + +### `snag list` +Lists snapshots. + +```bash +snag list [-h] [-c] [-a] [-e] +``` + +- `-c, --comment` — Show snapshot comments. +- `-a, --author` — Show snapshot authors. +- `-e, --email` — Show authors' emails. + +### `snag diff` +Shows changed data. + +```bash +snag diff +``` + +### `snag status` +Checks the status of tracked files. + +```bash +snag status +``` + +### `snag size` +Displays snapshot sizes. + +```bash +snag size +``` + +### `snag rules` +Manages tracking rules. + +```bash +snag rules [-h] save|show|update|reset|clear +``` + +- `save` — Saves rules. +- `show` — Displays rules. + ```bash + snag rules show [-h] [-c] + ``` + - `-c, --config` — Show rules from the configuration file. +- `update` — Updates rules. + ```bash + snag rules update [-h] [-r] + ``` + - `-r, --remove` — Removes ignored files from tracking (use with caution!). +- `reset` — Resets rules to the state of committed changes. +- `clear` — Clears rules. + +## Usage Examples + +1. **Initialize a repository:** + ```bash + snag init + ``` + +2. **Create a snapshot with a comment:** + ```bash + snag create -c "Initial snapshot" -a "John Doe" -e "john@example.com" + ``` + +3. **Import a snapshot from an archive:** + ```bash + snag import archive.tar.gz + ``` + +4. **Export a snapshot:** + ```bash + snag export -s abc123 /path/to/output + ``` + +5. **Restore a snapshot:** + ```bash + snag restore abc123 + ``` + +6. **View snapshot list with comments:** + ```bash + snag list -c + ``` + +7. **Update tracking rules:** + ```bash + snag rules update + ``` + +## Configuration + +The `snag` utility supports configuration via a JSON configuration file specified with the `-c` or `--config` option. This file defines the utility’s operating parameters, including paths, author details, pre- and post-snapshot commands, and file tracking rules. + +Example of using a configuration file: + +```bash +snag -c /path/to/config.json create +``` + +### Example Configuration File + +```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" + ] + } +} +``` + +### Configuration File Fields + +- **`git`** (`string`): Path to the repository for storing snapshots. Example: `/path/to/git/repository/dir`. Used during `snag init` to specify the storage location for metadata and snapshots. +- **`project`** (`string`): Path to the project or directory whose files are tracked. Example: `/path/to/project`. Specifies the root directory for creating, importing, or restoring snapshots. +- **`email`** (`string`): Email of the snapshot author. Used for snapshot metadata in commands like `snag create` or `snag import`. Example: `user@site.domain`. Can be overridden by `-e` or `--email`. +- **`author`** (`string`): Name of the snapshot author. Used for snapshot metadata. Example: `snag`. Can be overridden by `-a` or `--author`. +- **`presnag`** (`array of strings`): Commands executed before creating or importing a snapshot (unless `--no-pre` is specified). Example: + - `systemctl stop my.service` — Stops the `my.service` service before the operation to ensure data integrity. +- **`postsnag`** (`array of strings`): Commands executed after creating or importing a snapshot (unless `--no-post` is specified). Example: + - `systemctl start my.service` — Starts the `my.service` service after the operation. +- **`rules`** (`object`): Defines file tracking rules. + - **`tracking`** (`array of strings`): Patterns of files or directories to track. Example: + - `/first_dir/` — Tracks the entire `/first_dir` directory and its contents. + - `/second_dir/*.conf` — Tracks all `.conf` files in `/second_dir`. + - `/second_dir/more/` — Tracks the entire `/second_dir/more` directory and its contents. + - **`ignore`** (`array of strings`): Files or directories excluded from tracking. Example: + - `/second_dir/more/*.so` — Ignores all `.so` files in `/second_dir/more`. + +### Notes + +- Rules in the `rules` section can be updated with `snag rules update` or viewed with `snag rules show -c`. +- Command-line parameters like `email` or `author` (e.g., via `-e` or `-a`) take precedence over configuration file values. +- Ensure paths specified in `git` and `project` exist and are readable/writable before operations. +- Commands in `presnag` and `postsnag` must be valid and accessible in the system, or the operation may fail. + +## License + +GPL-2.0 License. See the `LICENSE` file for details. + +## Contact + +For questions and suggestions: alexander@zhirov.kz diff --git a/dub.json b/dub.json index f63ef25..42aa163 100644 --- a/dub.json +++ b/dub.json @@ -3,7 +3,7 @@ "Alexander Zhirov" ], "copyright": "Copyright © 2025, Alexander Zhirov", - "description": "A backup system based on tracking file states using Git", + "description": "Сommand-line utility for creating, managing, and restoring data snapshots", "license": "GPL-2.0-or-later", "name": "snag", "targetPath": "bin", diff --git a/source/snag/version_.d b/source/snag/version_.d index b4f3fd3..3dcb82b 100644 --- a/source/snag/version_.d +++ b/source/snag/version_.d @@ -1,3 +1,3 @@ module snag.version_; -enum snagVersion = "0.0.13"; +enum snagVersion = "0.1.0-alpha.1";