merge-overlay(8)

NAME
merge-overlay - Utility to "merge down" a fusefile overlay.

SYNOPSIS
merge-overlay fusefile overlayfile

DESCRIPTION
merge-overlay is an administration utility for writing the data blocks of a fusefile overlay into a current fusefile (or ordinary file of matching size).

EXAMPLE
This section illustrates a use of merge-overlay via a use case scenario that involves a succession of steps where fusefile is used with successive overlays for the purpose of capturing revisions of a fused file. Notably the fusefile must be of the same size throughout the scenario, and in this example case it is a raw disk image file, vm.raw, for a virtual machine.

  first day
First a file a is set up as overlay for vm.raw to be vmx.raw for use during the day, and then the fusefile is torn down at the end of the day.
    $ fusefile vmx.raw -overlay:a vm.raw
    $ ... using vmx.raw for the virtual machine ...
    $ umount -u vmx.raw
By doing so, vmx.raw represents the original image file vm.raw initially but changes (i.e. data writes) are collated into the overlay file a while vm.raw remains unchanged.

  second day
The next day file b is set up as overlay stacked over a for vm.raw to again be vmx.raw. Then that is used over the day before the fusefile is torn down at the end of the day.
    $ fusefile vmx.raw -overlay:a:b vm.raw
    $ ... using vmx.raw for the virtual machine ...
    $ umount -u vmx.raw
By doing so, vmx.raw represents the original image file vm.raw including yesterday's changes collated in a, and any further changes are collated into the overlay file b while both vm.raw and a remain unchanged.

  some days later
By adding an additional overlay each day, at the end of the sixth day there is a stack of overlays, a:b:c:d:e:f. Here the last overlay file fthe last day's changes relative the overkay stack a:b:c:d:e and so forth. One may now wish to, say, merge a:b:c into a single overlay file A, and d:e:f into another file B. This could be done as follows:
    ### First merge a, b and c into A
    $ fusefile vmx.raw -overlay:A vm.raw
    $ merge-overlay vmx.raw a
    $ merge-overlay vmx.raw b
    $ merge-overlay vmx.raw c
    $ umount -u vmx.raw
    ### Second merge d, e and f into B
    $ fusefile vmx.raw -overlay:A:B vm.raw
    $ for f in d e f ; do merge-overlay vmx.raw $f ; done
    $ umount -u vmx.raw
Note that including A for the second fusefile setup is not needed for the merging but it's will be needed for using vmx.raw further used after the merge.

NOTES
The fusefile overlay file contains the written data only; it does not track the order of changes but rather only keeps the last written data blocks, which also are combined into larger blocks when possible. The merging of this means to write the resulting blocks into the target file in order of byte positions.

SEE ALSO
fusefile

COPYRIGHT
Copyright 2023 Ralph Rönnquist <rrq@rrq.au>