From 0d8095b44504f144e144c4c8fd1503cfdaef7fb4 Mon Sep 17 00:00:00 2001 From: Matteo Croce Date: Wed, 2 Oct 2024 00:23:18 +0200 Subject: [PATCH 3/4] reflink: add documentation Document the new --reflink option in the man page, in the texinfo manual and in NEWS. * doc/tar.1: Document --reflink. * doc/tar.texi (Option Summary): Likewise. * NEWS: Mention it, with the expected performance gains. --- NEWS | 19 +++++++++++++++++++ doc/tar.1 | 27 +++++++++++++++++++++++++++ doc/tar.texi | 19 +++++++++++++++++++ 3 files changed, 65 insertions(+) diff --git a/NEWS b/NEWS index 8e18040d..a433631b 100644 --- a/NEWS +++ b/NEWS @@ -24,6 +24,25 @@ as argument to --mtime option (see GNU tar manual, chapter 4 Defines output format for the COMMAND set by the above option. If used, command output will be parsed using strptime(3). +* New option: --reflink + +When creating an archive, align member data on a 4 kilobyte boundary +by padding the pax extended headers (implies --format=posix). When +extracting such an archive on a filesystem supporting copy-on-write +clones (e.g. Btrfs, XFS), clone the member data from the archive +using reflinks instead of copying it: no file data is read or +written, and the extracted files share their disk blocks with the +archive, taking no extra disk space. Extracting a linux source tree +this way is a few times faster (about 2.8x on NVMe), and for archives +dominated by large members the gain is far larger -- a game-data +archive of big files extracts roughly a thousand times faster on a +spinning disk. + +This helps only when the archive is a seekable uncompressed file on +the same reflink-capable filesystem as the destination: compressed +or piped archives, or foreign filesystems, are extracted the usual +way with a regular copy. + * Changes to behavior ** Skip file or archive member if transformed name is empty diff --git a/doc/tar.1 b/doc/tar.1 index 7258381f..3ad005b8 100644 --- a/doc/tar.1 +++ b/doc/tar.1 @@ -318,6 +318,33 @@ database files created by such systems as \fBDBM\fR). When given this option, \fBtar\fR attempts to determine if the file is sparse prior to archiving it, and if so, to reduce the resulting archive size by not dumping empty parts of the file. +.TP +\fB\-\-reflink\fR +Enable copy-on-write extraction. +.br +On archive creation, this option pads the file data to a 4k boundary +using the "comment" pax keyword, which is ignored on extraction. +For this reason, this option implies \fB\-\-format=pax\fR; a warning +is printed if the alignment cannot be performed, e.g. because another +format was selected explicitly, or the archive is compressed, +multi-volume, or being appended to. + +On archive extraction, this option makes \fBtar\fR try to reflink data +from the tar archive to the destination file using the +\fBFICLONERANGE\fR ioctl. +For this to work, the following conditions must be met: +.br +\- the archive must have the data aligned to a 4k boundary +(like one created with this option) +.br +\- the archive file must be on the same filesystem as the destination file +.br +\- the archive must not come from a pipe (which implies it's uncompressed) +.br +\- the filesystem must support reflinks (currently Btrfs, +XFS and a few other filesystems support them). +.br +If the reflink fails, \fBtar\fR falls back to a standard copy. .SS Overwrite control These options control \fBtar\fR actions when extracting a file over an existing copy on disk. diff --git a/doc/tar.texi b/doc/tar.texi index f5b09cab..cc23d86c 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -3414,6 +3414,25 @@ Remove existing directory hierarchies before extracting directories of the same name from the archive. @xref{Recursive Unlink}. +@opsummary{reflink} +@item --reflink + +When creating an archive, align the data of each member on a 4 +kilobyte boundary by padding its extended header with a @samp{comment} +keyword, which is ignored on extraction. This option implies +@option{--format=posix}; the alignment is only useful for archives +that are stored as plain uncompressed files. + +When extracting, attempt to create copy-on-write clones (@dfn{reflinks}) +of the member data directly from the archive file instead of copying +it, using the @code{FICLONERANGE} @code{ioctl}. This requires an +archive with aligned member data (such as one created with this +option), residing on the same filesystem as the extracted files, and a +filesystem supporting reflinks (e.g., Btrfs or XFS). Extraction is +then much faster, and the extracted files share their disk blocks with +the archive until they are modified. If a member cannot be cloned, +@command{tar} silently falls back to a regular copy. + @opsummary{remove-files} @item --remove-files -- 2.50.1