257 lines
7.2 KiB
Markdown
257 lines
7.2 KiB
Markdown
# 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
|