From 2c10158ce92f102280d4d87406ebeea3e05bf915 Mon Sep 17 00:00:00 2001
From: flu0r1ne <flu0r1ne@flu0r1ne.net>
Date: Thu, 29 Jul 2021 13:09:23 -0500
Subject: Added README, Licence, and fixed issue with modules

---
 README.md | 126 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 116 insertions(+), 10 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 1cd5b1e..f820cef 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,122 @@
-ZFS File Diff:
-==============
+ZFS Snapshot Utils:
+===================
 
-Instead of operating at a dataset level, ZFS File Diff provides extra tools
+Instead of operating at a dataset level, `zsu` provides extra tools
 for operating on single files within a snapshot.
 
 This is useful when you:
-- Accedently deleted a file
-- Identify the changes file over time
+- Accidentally deleted a file
+- Wish to identify the changes within a file over time
 
 ```
-zfdiff list [--with-paths|-p] <reference>
-zfdiff cat <snap> <reference>
-zfdiff overwrite <snap> <reference>
-zfdiff diff <snap>..<snap> <reference>
-```
\ No newline at end of file
+zsu list [--with-paths|-p] <reference>
+zsu cat <reference> <snap>
+zsu diff <reference>  <snap>..<snap>
+```
+
+## Build and install
+
+Requirements:
+- diff (likely installed)
+- zfs snapshots directory
+  + Enable it with `sudo zfs set snapdir=visible pool/dataset`
+
+```
+git clone path
+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
+```
-- 
cgit v1.2.3