diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 126 |
1 files changed, 116 insertions, 10 deletions
@@ -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 +``` |