Merge pull request #51 from stephen679/readme-with-tar

readme: update details about go-mtree in readme

README.md

@@ -4,7 +4,7 @@
 This is a library and simple cli tool for [mtree(8)][mtree(8)] support.
 
 While the traditional `mtree` cli utility is primarily on BSDs (FreeBSD,
-openBSD, etc), but even broader support for the `mtree` specification format is
+openBSD, etc), even broader support for the `mtree` specification format is
 provided with libarchive ([libarchive-formats(5)][libarchive-formats(5)]).
 
 There is also an [mtree port for Linux][archiecobbs/mtree-port] though it is
@@ -20,9 +20,14 @@ files are often a critical aspect of the file, holding ACLs, capabilities, etc.
 While FreeBSD filesystem do support `extattr`, this feature has not made its
 way into their `mtree`.
 
-This implementation of mtree supports an additional "keyword" of `xattr`. If
+This implementation of mtree supports a few non-upstream "keyword"s, such as:
-you include this keyword, then the FreeBSD `mtree` will fail as it is an
+`xattr` and `tar_time`. If you include these keywords, the FreeBSD `mtree`
-unknown keyword to that implementation.
+will fail, as they are unknown keywords to that implementation.
+
+To have `go-mtree` produce specifications that will be 
+strictly compatible with the BSD `mtree`, use the `-bsd-keywords` flag when
+creating a manifest. This will make sure that only the keywords supported by
+BSD `mtree` are used in the program.
 
 
 ### Typical form
@@ -70,6 +75,37 @@ avoids issues with encoding, as well as issues of information leaking. The
 designation of SHA1 is arbitrary and seen as a general "good enough" assertion
 of the value.
 
+### Tar form
+
+```mtree
+# .
+/set type=file mode=0664 uid=1000 gid=1000
+. type=dir mode=0775 tar_time=1468430408.000000000
+
+# samedir
+samedir type=dir mode=0775 tar_time=1468000972.000000000
+    file2 size=0 tar_time=1467999782.000000000
+    file1 size=0 tar_time=1467999781.000000000
+    
+[...]
+```
+
+While `go-mtree` serves mainly as a library for upstream `mtree` support,
+`go-mtree` is also compatible with [tar archives][tar] (which is not an upstream feature).
+This means that we can now create and validate a manifest by specifying a tar file.
+More interestingly, this also means that we can create a manifest from an archive, and then
+validate this manifest against a filesystem hierarchy that's on disk, and vice versa.
+
+Notice that for the output of creating a validation manifest from a tar file, the default behavior
+for evaluating a notion of time is to use the `tar_time` keyword. In the 
+"filesystem hierarchy" format of mtree, `time` is being evaluated with 
+nanosecond precision. However, GNU tar truncates a file's modification time
+to 1-second precision. That is, if a file's full modification time is 
+123456789.123456789, the "tar time" equivalent would be 123456789.000000000.
+This way, if you validate a manifest created using a tar file against an
+actual root directory, there will be no complaints from `go-mtree` so long as the
+1-second precision time of a file in the root directory is the same.
+
 
 ## Usage
 
@@ -83,13 +119,25 @@ To use the command line tool, first [build it](#Building), then the following.
 This will also include the sha512 digest of the files.
 
 ```bash
-gomtree -c -K sha512digest -p . > /tmp/mtree.txt
+gomtree -c -K sha512digest -p . > /tmp/root.mtree
+```
+
+With a tar file: 
+
+```bash
+gomtree -c -K sha512digest -T sometarfile.tar > /tmp/tar.mtree
 ```
 
 ### Validate a manifest
 
 ```bash
-gomtree -p . -f /tmp/mtree.txt
+gomtree -p . -f /tmp/root.mtree
+```
+
+With a tar file:
+
+```bash
+gomtree -T sometarfile.tar -f /tmp/root.mtree
 ```
 
 ### See the supported keywords
@@ -97,30 +145,32 @@ gomtree -p . -f /tmp/mtree.txt
 ```bash
 gomtree -list-keywords
 Available keywords:
-  rmd160
+ uname
-  ripemd160digest
+ sha1
-  type  (default)
+ sha1digest
-  link  (default)
+ sha256digest
-  cksum
+ xattrs (not upstream)
-  md5
+ link (default)
-  md5digest
+ nlink (default)
-  sha256digest
+ md5digest
-  sha512
+ rmd160digest
-  time  (default)
+ mode (default)
-  gid  (default)
+ cksum
-  mode  (default)
+ md5
-  sha1
+ rmd160
-  sha1digest
+ type (default)
-  size  (default)
+ time (default)
-  uid  (default)
+ uid (default)
-  sha256
+ gid (default)
-  sha384
+ sha256
-  sha512digest
+ sha384
-  nlink  (default)
+ sha512
-  uname
+ xattr (not upstream)
-  rmd160digest
+ tar_time (not upstream)
-  sha384digest
+ size (default)
-  xattr
+ ripemd160digest
+ sha384digest
+ sha512digest
 ```
 
 
@@ -146,3 +196,4 @@ go build .
 [archiecobbs/mtree-port]: https://github.com/archiecobbs/mtree-port
 [godoc]: https://godoc.org/github.com/vbatts/go-mtree
 [sha1]: https://tools.ietf.org/html/rfc3174
+[tar]: http://man7.org/linux/man-pages/man1/tar.1.html