create: --map and --reuse-from for efficient block device snapshot backups

docs/man/borg-create.1

@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "borg-create" "1" "2026-08-15" "" "borg backup tool"
+.TH "borg-create" "1" "2026-08-17" "" "borg backup tool"
 .SH Name
 borg-create \- Creates a new archive.
 .SH SYNOPSIS
@@ -320,6 +320,15 @@ open and read block and char device files as well as FIFOs as if they were regul
 .TP
 .BI \-\-read\-special\-timeout \ SECONDS
 when reading from FIFOs or character devices (see \-\-read\-special): skip the file with an error if no data arrives for more than SECONDS (this includes waiting for a FIFO\(aqs writer to connect). Give 0 to wait forever. default: 1800 seconds.
+.TP
+.BI \-\-map \ MAPFILE
+give a map file describing the content ranges of the (single) input file, so borg does not need to read all of it. See the \fIInput maps\fP section below.
+.TP
+.BI \-\-reuse\-from \ ARCHIVE
+reuse the chunks of this reference archive for the input map\(aqs \fBsame\fP ranges (requires \-\-map). See the \fIInput maps\fP section below.
+.TP
+.BI \-\-reuse\-path \ PATH
+archive\-internal path of the reference item in the \-\-reuse\-from archive (only needed if that archive contains more than one file item).
 .UNINDENT
 .SS Archive options
 .INDENT 0.0
@@ -581,6 +590,53 @@ creation a bit.
 .sp
 By default, the content read from stdin is stored in a file called \(aqstdin\(aq.
 Use \fB\-\-stdin\-name\fP to change the name.
+.SS Input maps
+.sp
+Usually, borg reads the complete input to determine its contents. If you already
+know the contents of parts of the input from an external source of truth, you can
+give that information via \fB\-\-map MAPFILE\fP and borg will not read the known parts.
+The primary use case is backing up snapshots of large block devices (e.g. LVM thin
+volumes), where the storage layer knows which ranges are in use.
+.sp
+\fB\-\-map\fP requires giving exactly one input path, which must be a regular file or
+(with \fB\-\-read\-special\fP) a block device.
+.sp
+The map file must describe the whole input: one range per line, in the form
+\fBSTART LENGTH STATE\fP (byte values, decimal or 0x\-prefixed hexadecimal). The
+ranges must be sorted, non\-overlapping and contiguous, starting at offset 0 and
+covering the exact input size. \fB#\fP starts a comment, empty lines are ignored.
+STATE is one of:
+.INDENT 0.0
+.IP \(bu 2
+\fBdata\fP: the range\(aqs contents are read and backed up.
+.IP \(bu 2
+\fBzero\fP: the range is known to read as all\-zero bytes. borg stores a hole
+(all\-zero range) of that size without reading the range.
+.IP \(bu 2
+\fBsame\fP: the range is known to be identical to the same range of the input
+backed up in the \fB\-\-reuse\-from REFARCHIVE\fP reference archive (usually: the
+previous backup of an earlier snapshot of the same device). borg reuses the
+reference archive\(aqs chunks for such ranges without reading them. This state
+requires \fB\-\-reuse\-from\fP\&.
+.UNINDENT
+.sp
+The reference archive must contain exactly one file item; if it contains more,
+select the reference item with \fB\-\-reuse\-path PATH\fP (its archive\-internal path).
+Reference chunks that only partially overlap \fBsame\fP ranges are re\-read from
+the input, so any chunker gives correct results \- but a fixed block size chunker
+(e.g. \fB\-\-chunker\-params fixed,4194304\fP, same parameters as used for the
+reference archive) avoids re\-reading at the edges of changed ranges and gives
+stable chunk boundaries across backups.
+.sp
+\fBThe map is trusted\fP: if it is wrong (e.g. a range marked \fBzero\fP actually
+contains data, or a range marked \fBsame\fP actually changed), the archive will
+not match the input and borg cannot detect that. Independently verify the
+source producing the maps, and consider doing a periodic full read backup
+(without \fB\-\-map\fP).
+.sp
+For LVM thin volume snapshots, maps can be generated from \fBthin_dump\fP /
+\fBthin_delta\fP XML with the \fBscripts/lvm\-thin\-map.py\fP converter from the
+borg sources; its docstring shows the complete workflow.
 .SS Feeding all file paths from externally
 .sp
 Usually, you give a starting path (recursion root) to borg and then borg

docs/usage/create.rst.inc

@@ -99,6 +99,12 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--read-special-timeout SECONDS``                | when reading from FIFOs or character devices (see --read-special): skip the file with an error if no data arrives for more than SECONDS (this includes waiting for a FIFO's writer to connect). Give 0 to wait forever. default: 1800 seconds. |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--map MAPFILE``                                 | give a map file describing the content ranges of the (single) input file, so borg does not need to read all of it. See the *Input maps* section below.                                                                                         |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--reuse-from ARCHIVE``                          | reuse the chunks of this reference archive for the input map's ``same`` ranges (requires --map). See the *Input maps* section below.                                                                                                           |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--reuse-path PATH``                             | archive-internal path of the reference item in the --reuse-from archive (only needed if that archive contains more than one file item).                                                                                                        |
+    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **Archive options**                                                                                                                                                                                                                                                                                                                                        |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--comment COMMENT``                             | add a comment text to the archive                                                                                                                                                                                                              |
@@ -173,6 +179,9 @@ borg create
         --files-changed MODE      specify how to detect if a file has changed during backup (ctime, mtime, disabled). default: ctime (on Windows: mtime, because ctime is file creation time there).
         --read-special            open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.
         --read-special-timeout SECONDS    when reading from FIFOs or character devices (see --read-special): skip the file with an error if no data arrives for more than SECONDS (this includes waiting for a FIFO's writer to connect). Give 0 to wait forever. default: 1800 seconds.
+        --map MAPFILE             give a map file describing the content ranges of the (single) input file, so borg does not need to read all of it. See the *Input maps* section below.
+        --reuse-from ARCHIVE      reuse the chunks of this reference archive for the input map's ``same`` ranges (requires --map). See the *Input maps* section below.
+        --reuse-path PATH         archive-internal path of the reference item in the --reuse-from archive (only needed if that archive contains more than one file item).
 
 
     Archive options
@@ -445,6 +454,51 @@ creation a bit.
 By default, the content read from stdin is stored in a file called 'stdin'.
 Use ``--stdin-name`` to change the name.
 
+Input maps
+++++++++++
+
+Usually, borg reads the complete input to determine its contents. If you already
+know the contents of parts of the input from an external source of truth, you can
+give that information via ``--map MAPFILE`` and borg will not read the known parts.
+The primary use case is backing up snapshots of large block devices (e.g. LVM thin
+volumes), where the storage layer knows which ranges are in use.
+
+``--map`` requires giving exactly one input path, which must be a regular file or
+(with ``--read-special``) a block device.
+
+The map file must describe the whole input: one range per line, in the form
+``START LENGTH STATE`` (byte values, decimal or 0x-prefixed hexadecimal). The
+ranges must be sorted, non-overlapping and contiguous, starting at offset 0 and
+covering the exact input size. ``#`` starts a comment, empty lines are ignored.
+STATE is one of:
+
+- ``data``: the range's contents are read and backed up.
+- ``zero``: the range is known to read as all-zero bytes. borg stores a hole
+  (all-zero range) of that size without reading the range.
+- ``same``: the range is known to be identical to the same range of the input
+  backed up in the ``--reuse-from REFARCHIVE`` reference archive (usually: the
+  previous backup of an earlier snapshot of the same device). borg reuses the
+  reference archive's chunks for such ranges without reading them. This state
+  requires ``--reuse-from``.
+
+The reference archive must contain exactly one file item; if it contains more,
+select the reference item with ``--reuse-path PATH`` (its archive-internal path).
+Reference chunks that only partially overlap ``same`` ranges are re-read from
+the input, so any chunker gives correct results - but a fixed block size chunker
+(e.g. ``--chunker-params fixed,4194304``, same parameters as used for the
+reference archive) avoids re-reading at the edges of changed ranges and gives
+stable chunk boundaries across backups.
+
+**The map is trusted**: if it is wrong (e.g. a range marked ``zero`` actually
+contains data, or a range marked ``same`` actually changed), the archive will
+not match the input and borg cannot detect that. Independently verify the
+source producing the maps, and consider doing a periodic full read backup
+(without ``--map``).
+
+For LVM thin volume snapshots, maps can be generated from ``thin_dump`` /
+``thin_delta`` XML with the ``scripts/lvm-thin-map.py`` converter from the
+borg sources; its docstring shows the complete workflow.
+
 Feeding all file paths from externally
 ++++++++++++++++++++++++++++++++++++++
 

docs/usage/notes.rst

@@ -180,6 +180,26 @@ Now, let's see how to restore some LVs from such a backup.
     $ borg extract --stdout arch dev/vg0/root-snapshot > /dev/vg0/root
     $ borg extract --stdout arch dev/vg0/home-snapshot > /dev/vg0/home
 
+Efficient backups of LVM thin volume snapshots
+++++++++++++++++++++++++++++++++++++++++++++++
+
+Backing up a block device as shown above reads the whole device every time.
+For snapshots of LVM *thin* volumes, the thin pool's metadata already knows
+which ranges are allocated and which ranges changed between two snapshots,
+so most of the reading can be skipped: see the ``--map`` and ``--reuse-from``
+options of ``borg create`` (section *Input maps* in ``borg create --help``)
+and the ``scripts/lvm-thin-map.py`` converter in the borg sources, which
+turns ``thin_dump`` / ``thin_delta`` XML into borg input maps. The script's
+docstring shows the complete workflow: an initial full backup using the
+allocation map (unallocated ranges are stored as holes without reading them),
+then incremental backups that only read the ranges that changed since the
+previous snapshot, while reusing the previous archive's chunks for everything
+else. Use ``--chunker-params fixed,4194304`` (or similar) for such backups.
+
+Note that borg trusts these maps - it cannot detect a wrong or stale map, so
+keep the snapshot discipline described in the script's docstring and consider
+doing a periodic full read backup (without ``--map``).
+
 
 .. _separate_compaction: