new version

[rrq/fusefile.git] / README.adoc

diff --git a/README.adoc b/README.adoc
index 500e81bb528e3abffbff7e2c968a738ec75b5fc4..efd47b29e2abdf2ca069ced8eaa028496b30744f 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -1,5 +1,7 @@
 fusefile
 ========
+:colon: :
+:noop:
 
 This project implements a "fuse" device to mount as a single file that
 is a concatenation of fragments of one or more files. The fused file
@@ -11,7 +13,7 @@ FUSE file mount for combining file fragments.
 == SYNOPSIS
 
 ====
-*fusefile* [ _fuse options_ ] *mountpoint*  +_filename_/from:to+ ...
+*fusefile* [ _fuse options_ ] *mountpoint*  [ _overlay_ ] +_filename_/from:to+ ...
 ====
 
 ## DESCRIPTION
@@ -19,8 +21,18 @@ FUSE file mount for combining file fragments.
 *fusefile* is FUSE file mount that presents a series of fragments of
 other files as a contiguous concatenation. It bind mounts a driver on
 top of the file mountpoint to present the nominated file fragments as
-a single, contiguous file.
-
+a single, contiguous file. single, contiguous file. It accepts
+over-writing on the fused file which gets distributed accordingly to
+the fragments, but cannot change size.
+
+An optional overlay file is declared with an
+**-overlay:**__filename__ argument between the mount point and
+the fragments. This file is then set up as an overlay for capturing
+writes to the fused file. The overlay file will contain the written
+fused file regions, followed by meta data to distinguish between
+written content and "holes" (where content comes from the fused
+fragments).
+       
 The fragment arguments include the filename of a source file, and
 optionally start and end byte positions. All in all there five
 variations:
@@ -62,6 +74,13 @@ fused file instead.
          insert.fat/0:$(( 409600*512 )) \
          disk.raw/$(( (2099200+409600)*512 )):
 
+.Protect raw disk image file with an overlay:
+    $ fusefile -ononempty disk.raw -overlay:today disk.raw
+
+By that set up, the overlay file, "today", will protect the disk image
+file, "disk.raw" from changes, and also override the pathname
+"disk.raw" to be the fused file.
+
 
 ## NOTES
 
@@ -72,11 +91,15 @@ remain open, but the source fragments are not recomputed. If a source
 file changes or reduces in size "behind" the fused file, then anything
 may happen.
 
-If the mountpoint file doesn't exist, then **fusefile** creates it and
-removes it when unmounted.
+If the mountpoint file doesn't exist, then **fusefile** creates it.
+
+Unmounting is done with "**fusermount -u** __mountpoint__" as usual.
 
-Unmounting is done with "fusermount -u __fused file__" as usual.
+Using an overlay file makes the fused file writable regardless of the
+fused fragments with the overlay file containing any changes to the
+original. The overlay file is reusable for subsequent fusing of the
+same fragments for reconstructing a prior session with changes.
 
 ## AUTHOR
 
-Ralph Rönnquist <ralph.ronnquist@gmail.com> 
+Ralph Rönnquist <ralph.ronnquist@gmail.com>.