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:

dub build --build=release

Usage

Basic command format:

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.

snag init [-h] [-f]

• -f, --force — Overwrites an existing repository.

snag create

Creates a new snapshot.

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.

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.

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.

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.

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.

snag diff

snag status

Checks the status of tracked files.

snag status

snag size

Displays snapshot sizes.

snag size

snag rules

Manages tracking rules.

snag rules [-h] save|show|update|reset|clear

• save — Saves rules.
• show — Displays rules.

  snag rules show [-h] [-c]
  

  • -c, --config — Show rules from the configuration file.
• update — Updates rules.

  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:

   snag init
   

2. Create a snapshot with a comment:

   snag create -c "Initial snapshot" -a "John Doe" -e "john@example.com"
   

3. Import a snapshot from an archive:

   snag import archive.tar.gz
   

4. Export a snapshot:

   snag export -s abc123 /path/to/output
   

5. Restore a snapshot:

   snag restore abc123
   

6. View snapshot list with comments:

   snag list -c
   

7. Update tracking rules:

   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:

snag -c /path/to/config.json create

Example Configuration File

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