Added man page for merge-overlay

diff --git a/merge-overlay.8 b/merge-overlay.8
new file mode 100644 (file)
index 0000000..549e9ec
--- /dev/null
+++ b/merge-overlay.8
@@ -0,0 +1,126 @@
+.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>