Scroll to navigation

borg-export-tar(1) borg backup tool 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

specify the archive name
output tar file. "-" to write to stdout instead.
paths to extract; patterns are supported

options

filter program to pipe data through
output verbose list of items (files, dirs, ...)
select tar format: BORG, PAX or GNU
write sparse tar members (GNU sparse format 1.0) for files containing all-zero chunks (BORG and PAX formats only)

Include/Exclude options

exclude paths matching PATTERN
read exclude patterns from EXCLUDEFILE, one per line
include/exclude paths matching PATTERN
read include/exclude patterns from PATTERNFILE, one per line
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

2026-10-07