Add doc about b2restore-create-dummy-files script

Makefile

@@ -15,7 +15,7 @@
 DOC = README.md
 
 NAME = b2restore
-SCRIPT = make-dummy-files
+SCRIPT = b2restore-create-dummy-files
 DOCOUT = $(DOC:.md=.html)
 
 all:

README.md

@@ -1,8 +1,9 @@
 ## B2RESTORE
 
 [b2restore](http://github.com/bulletmark/b2restore) is a command line
-utility which you can use to manually restore a [Backblaze
-B2](https://www.backblaze.com/b2/) archive for a given date and time.
+utility which can be used with [rclone](https://rclone.org/) to
+manually restore a [Backblaze B2](https://www.backblaze.com/b2/) archive
+for any given date and time.
 
 ### INSTALLATION
 
@@ -21,7 +22,7 @@ $ sudo make install
 
 ### USAGE
 
-This utilty is typically used with [Rclone](https://rclone.org/).
+This utility is typically used with [rclone](https://rclone.org/).
 Simply `rclone sync` or `rclone copy` the B2 bucket or sub-paths from
 the bucket which you want to restore. You **MUST** specify
 `--b2-versions` to include all file versions, e.g:
@@ -48,24 +49,26 @@ E.g. to recreate the tree of files at a specified time:
 b2restore -t 2018-01-01T09:10:00 b2files outdir
 ```
 
-Just keep selecting different times to incrementally recreate `outdir`.
-The utility prints a line for each file updated, created, or deleted in
-`outdir` compared to the previous contents. The date and time of each
-updated/created/deleted file is also listed. The target files are all
-hard-linked from the files in the source directory so the `outdir` tree
-is created very quickly since files do not need to be actually copied.
-Thus you can conveniently experiment with the time string to quickly see
-file differences.
+Just keep selecting different times to incrementally recreate `outdir`
+as it existed at that time. The utility prints a line for each file
+updated, created, or deleted in `outdir` compared to the previous
+contents. The date and time of each updated/created/deleted file is also
+listed. The target files are all hard-linked from the files in the
+source directory so the `outdir` tree is created very quickly since
+files do not need to be actually copied. Thus you can conveniently
+experiment with the time string to quickly see file differences.
 
 Rather than specifying an explicit time string using `-t/--time`, you
-can instead choose to use `-f/--filetime` to specify any one file's last
-modification time at which to recreate the target tree of files.
+can instead choose to use `-f/--filetime` to specify any one specific
+file's modification time at which to recreate the target tree of files.
 
 Note that this utility does not recreate empty directory hierarchies.
 All empty directories in the target tree are deleted.
 
+#### B2RESTORE COMMAND LINE OPTIONS
+
 ```
-usage: b2restore [-h] [-t TIME] [-f FILETIME] indir outdir
+usage: b2restore [-h] [-t TIME | -f FILETIME] indir outdir
 
 Program to recreate Backblaze B2 file archive at specified date and time.
 
@@ -81,6 +84,46 @@ optional arguments:
                         set time based on specified file
 ```
 
+### TEST RUN UTILITY
+
+A command line utility `b2restore-create-dummy-files` is included to
+facilitate testing `b2restore` on your restored file tree without
+actually downloading any files from your B2 archive(!). This utility
+parses `rclone lsl` output to recreate your B2 bucket directory and
+hierarchy of file versions. Only the file names are recreated of course,
+the file contents are set to their actual byte size but with random byte
+contents (or zero filled if you specify `-z`, or to zero length if you
+specify `-s`).
+
+This utility requires almost nothing to download from your B2 archive
+and runs extremely quickly. You can then run `b2restore` against this
+dummy archive to simulate what files are changed between versions, etc.
+It is also good to get a feel for how `b2restore` works, what it does,
+and whether it suits your needs without requiring you to first perform
+an onerous huge download of your entire B2 archive.
+
+Here is an example usage:
+
+```
+rclone lsl --b2-versions B2:mybucket | b2restore-create-dummy-files -d allfiles
+b2restore allfiles b2
+du -shl b2 # (see how much storage tree of latest versions uses)
+b2restore -t 2018-05-10T12:00.00 allfiles b2
+du -shl b2 # (see how much storage tree of yesterdays versions uses)
+```
+
+#### B2RESTORE-CREATE-DUMMY-FILES COMMAND LINE OPTIONS
+
+```
+Usage: b2restore-create-dummy-files [-options]
+Reads B2 file list (from lsl output) from standard input to create
+dummy tree of files.
+Options:
+-d <outdir> default = current dir
+-z (zero fill files, not with random content which is default)
+-s (set files to zero length, not their actual size)
+```
+
 ### LICENSE
 
 Copyright (C) 2018 Mark Blakeney. This program is distributed under the

make-dummy-files → b2restore-create-dummy-files

@@ -1,22 +1,27 @@
 #!/bin/bash
 # Can be used to make a dummy B2 repo for testing, e.g.
-# rclone lsl --b2-versions B2:mybucket | ./make-dummy-files -d outdir
+# rclone lsl --b2-versions B2:mybucket | b2restore-create-dummy-files -d outdir
 # M.Blakeney, May 2018.
 
 usage() {
-    echo "Usage: $(basename $0) [-options] [host]"
-    echo "Options"
+    echo "Usage: $(basename $0) [-options]"
+    echo "Reads B2 file list (from lsl output) from standard input to create"
+    echo "dummy tree of files."
+    echo "Options:"
     echo "-d <outdir> default = current dir"
-    echo "-s (also set file to actual size)"
+    echo "-z (zero fill files, not with random content which is default)"
+    echo "-s (set files to zero length, not their actual size)"
     exit 1
 }
 
 OUTDIR=""
-SETSIZE=0
-while getopts d:s c; do
+NOSIZE=0
+ZERO=""
+while getopts d:zs c; do
     case $c in
     d) OUTDIR=$OPTARG;;
-    s) SETSIZE=1;;
+    z) ZERO="-z";;
+    s) NOSIZE=1;;
     \?) usage;;
     esac
 done
@@ -33,9 +38,9 @@ fi
 
 while read size date time file; do
     mkdir -p "$OUTDIR""$(dirname $file)"
-    if [[ $SETSIZE -ne 0 ]]; then
+    if [[ $NOSIZE -eq 0 ]]; then
 	echo "creating ($size bytes):" "$OUTDIR""$file"
-	fallocate -l $size "$OUTDIR""$file"
+	fallocate $ZERO -l $size "$OUTDIR""$file"
     else
 	echo creating: "$OUTDIR""$file"
     fi

b2restore.py

@@ -114,9 +114,10 @@ def main():
 
     # Process command line options
     opt = argparse.ArgumentParser(description=__doc__.strip())
-    opt.add_argument('-t', '--time',
+    grp = opt.add_mutually_exclusive_group()
+    grp.add_argument('-t', '--time',
             help='set time YYYY-MM-DDTHH:MM.SS, default=latest')
-    opt.add_argument('-f', '--filetime',
+    grp.add_argument('-f', '--filetime',
             help='set time based on specified file')
     opt.add_argument('indir',
             help='input B2 archive containing all file versions '

setup.py

@@ -2,17 +2,18 @@
 # Setup script to install this package.
 # M.Blakeney, Mar 2018.
 
-import re
+import re, stat
 from pathlib import Path
 from setuptools import setup
 
 here = Path(__file__).resolve().parent
 name = re.sub(r'-.*', '', here.stem)
 readme = here.joinpath('README.md').read_text()
+executable = stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH
 
 setup(
     name=name,
-    version='1.6',
+    version='1.7',
     description='Program to recreate Backblaze B2 file archive at'
             'specified date+time',
     long_description=readme,
@@ -30,5 +31,6 @@
     data_files=[
         (f'share/doc/{name}', ['README.md']),
     ],
-    scripts=[name],
+    scripts=[f.name for f in here.iterdir()
+        if f.is_file() and f.stat().st_mode & executable]
 )