ZFS Snapshot Utils:
===================

Instead of operating at a dataset level, `zsu` provides extra tools
for operating on single files within a snapshot.

This is useful when you:
- Accidentally deleted a file
- Wish to identify the changes within a file over time

```
zsu list [--with-paths|-p] <reference>
zsu cat <reference> <snap>
zsu diff <reference>  <snap>..<snap>
```

## Build and install

Requirements:
- diff (likely installed)
- go
- zfs snapshots directory
  + Enable it with `sudo zfs set snapdir=visible pool/dataset`

```
git clone https://www.git.flu0r1ne.net/zsu.git/
cd zsu
go install
```

## Examples:

The `list` subcommand will search for a pathspec in all ZFS snapshots. The `@` 
refers to the current version. It only shows snapshots where a file has been 
found at that pathspec. (E.g. if the file was moved, it will not automatically
detect the location of the new version.) The path need not exist within the
live version of the file system.

### List
```
[#] zsu list cabinet/file.txt
...
autosnap_2021-07-29_07:00:19_hourly
autosnap_2021-07-29_08:00:18_hourly
autosnap_2021-07-29_09:00:18_hourly
autosnap_2021-07-29_10:00:19_hourly
autosnap_2021-07-29_11:00:18_hourly
autosnap_2021-07-29_12:00:18_hourly
autosnap_2021-07-29_13:00:19_hourly
autosnap_2021-07-29_14:00:18_hourly
autosnap_2021-07-29_15:00:19_frequently
autosnap_2021-07-29_15:00:19_hourly
autosnap_2021-07-29_15:15:18_frequently
autosnap_2021-07-29_15:30:18_frequently
autosnap_2021-07-29_15:45:18_frequently
autosnap_2021-07-29_16:00:19_frequently
autosnap_2021-07-29_16:00:19_hourly
autosnap_2021-07-29_16:15:18_frequently
autosnap_2021-07-29_16:30:18_frequently
autosnap_2021-07-29_16:45:18_frequently
@
```

```
[#] zsu list deleted.txt
autosnap_2021-07-01_00:00:03_monthly
autosnap_2021-07-02_00:00:23_daily
autosnap_2021-07-03_00:00:00_daily
autosnap_2021-07-04_00:00:28_daily autosnap_2021-07-05_00:00:25_daily autosnap_2021-07-06_00:00:19_daily
```

### Cat
The `cat` command will write the contents of a file to `stdout`. A snapshot can
be specified to obtain the version within a snapshot. It behaves more like GNU
paste than GNU cat.

```
[#] zsu cat deleted.txt autosnap_2021-07-29_15:45:18_frequently
This is the contents of the file at 29-07-2021
```

### Specifying snapshots relative to each other
With any commend, a snapshot can be specified a number of ways. As shown above, 
it can be specified using the name of the snapshot. A snapshot can also be specified 
relative to another. For example, `autosnap_2021-07-29_15:45:18_frequently-` 
means "the snapshot before autosnap_2021-07-29_15:45:18_frequently" and 
`autosnap_2021-07-29_15:45:18_frequently+` means "the snapshot after 
autosnap_2021-07-29_15:45:18_frequently" Any number of `+` or `-` can be appended 
to the snapshot. If the snapshot ends with a special symbol, it can be specified by name 
using quotes `'"snap-"'`. There are two special references provided for convenience. `@` 
refers to the latest snapshot at the given path.  If the file exists within the 
current file system, it will refer to this file.  `%` refers to the first snapshot 
including the file.

Examples:
```
[#] zsu cat deleted.txt @    # the current file
[#] zsu cat deleted.txt @-   # the most recent snapshot
[#] zsu cat deleted.txt @--  # the snapshot before the most recent
[#] zsu cat deleted.txt @-2  # also the snapshot before the most recent
[#] zsu cat deleted.txt %+   # the second snapshot which exists with this path
[#] zsu cat deleted.txt %    # the first snapshot
```

### Diff

The diff subcommand shows the `diff` of two snapshots. `diff` must be present and in your `PATH`.

```
# Specify the snapshots directly
zsu diff changing.md autosnap_2021-07-29_17:15:18_frequently..autosnap_2021-07-29_17:30:18_frequently
27a28
> Added this line
70a73
< Removed this line

# Or use the relative syntax
zsu diff changing.txt @--..@-
27a28
> Added this line
70a73
< Removed this line
```