README.adoc

   1 fusefile
   2 ========
   3 :colon: :
   4 :noop:
   5
   6 This project implements a "fuse" device to mount as a single file that
   7 is a concatenation of fragments of one or more files. The fused file
   8 allows overwriting the parts files, but not changing their sizes, and
   9 only for parts files that are writable upon first access.
  10
  11 FUSE file mount for combining file fragments.
  12
  13 == SYNOPSIS
  14
  15 ====
  16 *fusefile* [ _fuse options_ ] *mountpoint*  [ _overlay_ ] +_filename_/from:to+ ...
  17 ====
  18
  19 ## DESCRIPTION
  20
  21 *fusefile* is FUSE file mount that presents a series of fragments of
  22 other files as a contiguous concatenation. It bind mounts a driver on
  23 top of the file mountpoint to present the nominated file fragments as
  24 a single, contiguous file. single, contiguous file. It accepts
  25 over-writing on the fused file which gets distributed accordingly to
  26 the fragments, but cannot change size.
  27
  28 An optional overlay file is declared with an
  29 **-overlay:**__filename__ argument between the mount point and
  30 the fragments. This file is then set up as an overlay for capturing
  31 writes to the fused file. The overlay file will contain the written
  32 fused file regions, followed by meta data to distinguish between
  33 written content and "holes" (where content comes from the fused
  34 fragments).
  35
  36 The fragment arguments include the filename of a source file, and
  37 optionally start and end byte positions. All in all there five
  38 variations:
  39
  40  * __filename__ include all of the file.
  41
  42  * __filename/__ include all of the file named with "/" in the pathname. This case requires a final "/", since the last "/" separates the filename from the position details.
  43
  44  * __filename/from__ include the file from the given start position, to end.
  45
  46  * __filename/-to__ include the file from beginning to the given end position (not included).
  47
  48  * __filename/from:to__ include the file from the given start position, up to the given end position (not included).
  49
  50 ## EXAMPLES
  51
  52 .Insert file "y" into file "x" at position 1200:
  53
  54     $ fusefile -ononempty x x/:1200 y x/1200:
  55
  56 That mount will shadow the original file "x", and presents the
  57 fused file instead.
  58
  59 .Make file y be a swap of the beginning and end of file "x", at position 2442:
  60
  61     $ fusefile y x/2442: x/:2442
  62
  63 .Replace a partition in an image file with a different file
  64
  65     $ partx -oNR,START,SECTORS disk.raw
  66     NR   START  SECTORS
  67      1    2048  2097152
  68      2 2099200   409600
  69      3 2508800 14268383
  70     # Replace partition 2 of 409600 sectors from 2099200 with
  71     # the file "insert.fat" clipped to 409600 sectors.
  72     $ fusefile -ononempty disk.raw \
  73          disk.raw/0:$(( 2099200*512 )) \
  74          insert.fat/0:$(( 409600*512 )) \
  75          disk.raw/$(( (2099200+409600)*512 )):
  76
  77 .Protect raw disk image file with an overlay:
  78     $ fusefile -ononempty disk.raw -overlay:today disk.raw
  79
  80 By that set up, the overlay file, "today", will protect the disk image
  81 file, "disk.raw" from changes, and also override the pathname
  82 "disk.raw" to be the fused file.
  83
  84
  85 ## NOTES
  86
  87 Note that **fusefile** opens the nominated source file(s) before bind
  88 mounting. With the fuse option __-ononempty__ it will bind over an
  89 non-empty file, which may be useful. The source file descriptors
  90 remain open, but the source fragments are not recomputed. If a source
  91 file changes or reduces in size "behind" the fused file, then anything
  92 may happen.
  93
  94 If the mountpoint file doesn't exist, then **fusefile** creates it.
  95
  96 Unmounting is done with "**fusermount -u** __mountpoint__" as usual.
  97
  98 Using an overlay file makes the fused file writable regardless of the
  99 fused fragments with the overlay file containing any changes to the
 100 original. The overlay file is reusable for subsequent fusing of the
 101 same fragments for reconstructing a prior session with changes.
 102
 103 ## AUTHOR
 104
 105 Ralph Rönnquist <ralph.ronnquist@gmail.com>.