.mso www.tmac
.TH merge-overlay 8
.SH NAME
merge-overlay \- Utility to "merge down" a fusefile overlay.

.SH SYNOPSIS
.B merge-overlay \fIfusefile\fR \fIoverlayfile\fR

.SH DESCRIPTION

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

.SH EXAMPLE

This section illustrates a use of \fBmerge-overlay\fR via a use case
scenario that involves a succession of steps where \fBfusefile\fR 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, \fIvm.raw\fR, for a virtual machine.

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

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

.SS some days later
By adding an additional overlay each day, at the end of the sixth day
there is a stack of overlays,
\fIa\fR:\fIb\fR:\fIc\fR:\fId\fR:\fIe\fR:\fIf\fR. Here the last overlay
file \fIf\R has the last day's changes relative the overkay stack
\fIa\fR:\fIb\fR:\fIc\fR:\fId\fR:\fIe\fR and so forth.

One may now wish to, say, merge \fIa\fR:\fIb\fR:\fIc\fR into a single
overlay file \fIA\fR, and \fId\fR:\fIe\fR:\fIf\fR into another file
\fIB\fR. This could be done as follows:

.RS
### First merge \fIa\fR, \fIb\fR and \fIc\fR into \fIA\fR
.RE
.RS
\fB$ fusefile \fIvmx.raw\fB -overlay:\fIA\fB \fIvm.raw\fR
.RE
.RS
\fB$ merge-overlay \fIvmx.raw\fB \fIa\fR
.RE
.RS
\fB$ merge-overlay \fIvmx.raw\fB \fIb\fR
.RE
.RS
\fB$ merge-overlay \fIvmx.raw\fB \fIc\fR
.RE
.RS
\fB$ umount -u \fIvmx.raw\fR
.RE

.RS
### Second merge \fId\fE, \fIe\fR and \fIf\fR into \fIB\fR
.RE
.RS
\fB$ fusefile \fIvmx.raw\fB
-overlay:\fIA\fB:\fIB\fB
\fIvm.raw\fR
.RE
.RS
\fB$ for f in \fId\fB \fIe\fB \fIf\fB ; do
merge-overlay \fIvmx.raw\fB $f ; done\fR
.RE
.RS
\fB$ umount -u \fIvmx.raw\fR
.RE
Note that including \fIA\fR for the second fusefile setup is not
needed for the merging but it's will be needed for using \fIvmx.raw\fR
further used after the merge.

.SH 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.

.SH SEE ALSO

.B fusefile

.SH COPYRIGHT

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