borg-export-tar(1)

🌸 NAME 🌸

borg-export-tar — bestie, this one exports an archive's contents as a tarball 💖

(Also known as: this is the borg-export-tar(1) page from the borg backup tool, and yes we are doing the whole thing, no skimming, periodt.)

---

✨ SYNOPSIS ✨

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

---

🦋 DESCRIPTION 🦋

Okay so, this command creates a tarball from an archive. That's it, that's the mission 🎀

When you hand it '-' as the output FILE, Borg will write a tar stream to standard output. Iconic behavior honestly.

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. So zstd is the one doing it all in-house, no external help needed 💅

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:

• BORG — Specification: BORG specific, like PAX. Metadata: all as supported by borg.
• PAX — Specification: POSIX.1-2001 (pax) format. Metadata: GNU + atime/ctime/mtime ns + xattrs.
• GNU — Specification: GNU tar format. Metadata: 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, and bestie please read these: 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. iykyk 🧚

--progress can be slower than no progress display, since it makes one additional pass over the archive metadata. Worth it though? Your call boo 😭

---

👑 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

---

and that's the whole page, bestie, we ate and left no crumbs 💖 this was the borg-export-tar(1) manual from the borg backup tool, dated 2026-10-07 — go forth and tar up your archives, you absolute main character ✨🎀