X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=README.adoc;h=efd47b29e2abdf2ca069ced8eaa028496b30744f;hb=3c141b07c64b7cafc3362d523b6c6e5c8542e0ab;hp=00ce11b9ed4a6414f35624391431c93acb1e71b6;hpb=d7e225ba17002eec13f528e33fe4fc7c54788388;p=rrq%2Ffusefile.git

diff --git a/README.adoc b/README.adoc
index 00ce11b..efd47b2 100644
--- 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
@@ -9,15 +11,28 @@ only for parts files that are writable upon first access.
 FUSE file mount for combining file fragments.
  
 == SYNOPSIS
- *fusefile* [_fuse options_] *mountpoint* _filename/from-to_ ...
+
+====
+*fusefile* [ _fuse options_ ] *mountpoint*  [ _overlay_ ] +_filename_/from:to+ ...
+====
 
 ## DESCRIPTION
 
 *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:
@@ -30,20 +45,42 @@ variations:
 
  * __filename/-to__ include the file from beginning to the given end position (not included).
 
- * __filename/from-to__ include the file from the given start position, up to the given end position (not included). 
+ * __filename/from:to__ include the file from the given start position, up to the given end position (not included). 
 
 ## EXAMPLES
 
-Insert file "y" into file "x" at position 1200:
+.Insert file "y" into file "x" at position 1200:
   
-    $ fusefile -ononempty x x/-1200 y x/1200
-The bind mount shadows the original file "x", and presents the
-composite instead.
+    $ fusefile -ononempty x x/:1200 y x/1200:
+
+That mount will shadow the original file "x", and presents the
+fused file instead.
+
+.Make file y be a swap of the beginning and end of file "x", at position 2442:
+
+    $ fusefile y x/2442: x/:2442
 
-Make file y be a swap of the beginning and end of file "x", at
-position 2442:
+.Replace a partition in an image file with a different file
+
+    $ partx -oNR,START,SECTORS disk.raw
+    NR   START  SECTORS
+     1    2048  2097152
+     2 2099200   409600
+     3 2508800 14268383
+    # Replace partition 2 of 409600 sectors from 2099200 with
+    # the file "insert.fat" clipped to 409600 sectors.
+    $ fusefile -ononempty disk.raw \
+         disk.raw/0:$(( 2099200*512 )) \
+         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.
 
-    $ fusefile y x/2442 x/-2442
 
 ## NOTES
 
@@ -51,11 +88,18 @@ Note that **fusefile** opens the nominated source file(s) before bind
 mounting. With the fuse option __-ononempty__ it will bind over an
 non-empty file, which may be useful. The source file descriptors
 remain open, but the source fragments are not recomputed. If a source
-file changes or reduces in size, anything may happen.
+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.
+
+Unmounting is done with "**fusermount -u** __mountpoint__" as usual.
 
-If the mountpoint file doesn't exist, then **fusefile** creates it,
-and removes it when unmounted.
+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>.