borg-export-tar(1)

Name
borg-export-tar - Export archive contents as a tarball

SYNOPSIS

borg [common options] export-tar [options] NAME FILE [PATH...]

DESCRIPTION

This command creates a tarball from an archive.

When giving '-' as the output FILE, Borg will write a tar stream to standard output.

By default (--tar-filter=auto) Borg will detect whether the FILE should be compressed based on its file extension and pipe the tarball through an appropriate filter before writing it to FILE:

•   .tar.gz or .tgz: gzip

•   .tar.bz2 or .tbz: bzip2

•   .tar.xz or .txz: xz

•   .tar.zstd, .tar.zst or .tzst: zstd (in-process, level 3)

•   .tar.lz4: lz4

    For zstd, Borg compresses in-process using libzstd instead of piping through an external program (set BORG_ZSTD_MT_WORKERS to use multiple compression threads). The other formats are piped through the respective external filter program.

    Alternatively, a --tar-filter program may be explicitly specified. It should read the uncompressed tar stream from stdin and write a compressed/filtered tar stream to stdout.

    Depending on the --tar-format option, these formats are created:
    --tar-format | Specification | Metadata
    BORG | BORG specific, like PAX | all as supported by borg
    PAX | POSIX.1-2001 (pax) format | GNU + atime/ctime/mtime ns + xattrs
    GNU | GNU tar format | mtime s, no atime/ctime, no ACLs/xattrs/bsdflags

    With --sparse, files whose content contains runs of all-zero chunks are written as sparse tar members (GNU sparse format 1.0, as GNU tar creates it in POSIX mode), storing only a hole map and the non-zero data. This requires --tar-format BORG or PAX. Such tarballs can be much smaller for sparse files (e.g. disk images) and extract to sparse files again with GNU tar's or bsdtar's sparse support (as well as with borg import-tar / borg extract --sparse). Notes: hole detection works at the granularity of borg's content chunks (it does not depend on the original file having been a sparse file - but some short or unaligned zero runs may be stored literally); sparse-unaware tar implementations will extract a member as GNUSparseFile.0/<name> containing the raw hole map and data (the same caveat applies to tarballs created by GNU tar); for members needing >= 8 GiB of stored (non-hole) data, the stored size is base-256 encoded in the tar header (the GNU/star encoding of big numbers, understood by GNU tar, libarchive/bsdtar and python) - logical file sizes are unlimited anyway.

    By default the entire archive is extracted but a subset of files and directories can be selected by passing a list of PATHs as arguments. The file selection can further be restricted by using the --exclude option.

    For more help on include/exclude patterns, see the borg_patterns command output.

    --progress can be slower than no progress display, since it makes one additional pass over the archive metadata.

OPTIONS

See borg-common(1) for common options of Borg commands.

  arguments

NAME
    specify the archive name

FILE
    output tar file. "-" to write to stdout instead.

PATH
    paths to extract; patterns are supported

  options

--tar-filter
    filter program to pipe data through

--list
    output verbose list of items (files, dirs, ...)

--tar-format FMT
    select tar format: BORG, PAX or GNU

--sparse
    write sparse tar members (GNU sparse format 1.0) for files containing all-zero chunks (BORG and PAX formats only)

  Include/Exclude options

-e PATTERN, --exclude PATTERN
    exclude paths matching PATTERN

--exclude-from EXCLUDEFILE
    read exclude patterns from EXCLUDEFILE, one per line

--pattern PATTERN
    include/exclude paths matching PATTERN

--patterns-from PATTERNFILE
    read include/exclude patterns from PATTERNFILE, one per line

--strip-components NUMBER
    Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.

SEE ALSO

borg-common(1)

Author
The Borg Collective