0.1.0-alpha.1

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 <path>` — 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 <comment>] [-a <author>] [-e <email>]
+```
+
+- `--no-pre` — Skips pre-commands.
+- `--no-post` — Skips post-commands.
+- `-c, --comment <value>` — Specifies a comment for the snapshot.
+- `-a, --author <value>` — Specifies the snapshot author.
+- `-e, --email <value>` — Specifies the author's email.
+
+### `snag import`
+Imports a snapshot from a tar.gz archive.
+
+```bash
+snag import [-h] [--no-pre] [--no-post] [-c <comment>] [-a <author>] [-e <email>] <archive_path>
+```
+
+- `--no-pre` — Skips pre-commands.
+- `--no-post` — Skips post-commands.
+- `-c, --comment <value>` — Comment for the snapshot.
+- `-a, --author <value>` — Snapshot author.
+- `-e, --email <value>` — Author's email.
+- `<archive_path>` — Path to the tar.gz file.
+
+### `snag export`
+Exports a snapshot to a tar.gz archive.
+
+```bash
+snag export [-h] [-s <snapshot_hash>] <output_path>
+```
+
+- `-s, --snapshot <hash>` — Specifies the snapshot hash.
+- `<output_path>` — Path to the output directory for the archive.
+
+### `snag restore`
+Restores state from a specified snapshot.
+
+```bash
+snag restore [-h] [--no-pre] [--no-post] <snapshot_hash>
+```
+
+- `--no-pre` — Skips pre-commands.
+- `--no-post` —焦性
+- `<snapshot_hash>` — 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

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",

source/snag/version_.d

@@ -1,3 +1,3 @@
 module snag.version_;
 
-enum snagVersion = "0.0.13";
+enum snagVersion = "0.1.0-alpha.1";