# 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` — Skips post-commands.
- `<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