Manual Pages  — TAR

In extract or list mode, the entire command line is read and parsed before the archive is opened. The pathnames or patterns on the command line indicate which items in the archive should be processed. Patterns are shell-style globbing patterns as documented in tcsh(1).

The complete list of supported modules and keys for create and append modes is in archive_write_set_options(3) and for extract and list modes in archive_read_set_options(3).

Examples of supported options:

iso9660:joliet	Support Joliet extensions. This is enabled by default, use !joliet or iso9660:!joliet to disable.
iso9660:rockridge	Support Rock Ridge extensions. This is enabled by default, use !rockridge or iso9660:!rockridge to disable.
gzip:compression-level	A decimal integer from 1 to 9 specifying the gzip compression level.
gzip:timestamp	Store timestamp. This is enabled by default, use !timestamp or gzip:!timestamp to disable.
lrzip:compression=type	Use type as compression method. Supported values are bzip2, gzip, lzo (ultra fast), and zpaq (best, extremely slow).
lrzip:compression-level	A decimal integer from 1 to 9 specifying the lrzip compression level.
lz4:compression-level	A decimal integer from 1 to 9 specifying the lzop compression level.
lz4:stream-checksum	Enable stream checksum. This is by default, use lz4:!stream-checksum to disable.
lz4:block-checksum	Enable block checksum (Disabled by default).
lz4:block-size	A decimal integer from 4 to 7 specifying the lz4 compression block size (7 is set by default).
lz4:block-dependence	Use the previous block of the block being compressed for a compression dictionary to improve compression ratio.
zstd:compression-level	A decimal integer specifying the zstd compression level. Supported values depend on the library version, common values are from 1 to 22.
zstd:threads	Specify the number of worker threads to use. Setting threads to a special value 0 makes zstd(1) use as many threads as there are CPU cores on the system.
lzop:compression-level	A decimal integer from 1 to 9 specifying the lzop compression level.
xz:compression-level	A decimal integer from 0 to 9 specifying the xz compression level.
xz:threads	Specify the number of worker threads to use. Setting threads to a special value 0 makes xz(1) use as many threads as there are CPU cores on the system.
mtree:keyword	The mtree writer module allows you to specify which mtree keywords will be included in the output. Supported keywords include: cksum, device, flags, gid, gname, indent, link, md5, mode, nlink, rmd160, sha1, sha256, sha384, sha512, size, time, uid, uname. The default is equivalent to: "device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname".
mtree:all	Enables all of the above keywords. You can also use mtree:!all to disable all keywords.
mtree:use-set	Enable generation of /set lines in the output.
mtree:indent	Produce human-readable output by indenting options and splitting lines to fit into 80 columns.
zip:compression=type	Use type as compression method. Supported values are store (uncompressed) and deflate (gzip algorithm).
zip:encryption	Enable encryption using traditional zip encryption.
zip:encryption=type	Use type as encryption type. Supported values are zipcrypt (traditional zip encryption), aes128 (WinZip AES-128 encryption) and aes256 (WinZip AES-256 encryption).
read_concatenated_archives	Ignore zeroed blocks in the archive, which occurs when multiple tar archives have been concatenated together. Without this option, only the contents of the first concatenated archive would be read. This option is comparable to the -i -, -ignore-zeros option of GNU tar.

If a provided option is not supported by any module, that is a fatal error.

-P -, -absolute-paths	Preserve pathnames. By default, absolute pathnames (those that begin with a / character) have the leading slash removed both when creating archives and extracting from them. Also, tar will refuse to extract archive entries whose pathnames contain .. or whose target directory would be altered by a symlink. This option suppresses these behaviors.
-p -, -insecure -, -preserve-permissions	(x mode only) Preserve file permissions. Attempt to restore the full permissions, including file modes, file attributes or file flags, extended file attributes and ACLs, if available, for each item extracted from the archive. This is the reverse of -no-same-permissions and the default if tar is being run as root. It can be partially overridden by also specifying -no-acls, -no-fflags, -no-mac-metadata or -no-xattrs.
-passphrase passphrase	The passphrase is used to extract or create an encrypted archive. Currently, zip is the only supported format that supports encryption. You shouldn't use this option unless you realize how insecure use of this option is.
-posix	(c, r, u mode only) Synonym for -format pax
-q -, -fast-read	(x and t mode only) Extract or list only the first archive entry that matches each pattern or filename operand. Exit as soon as each specified pattern or filename has been matched. By default, the archive is always read to the very end, since there can be multiple entries with the same name and, by convention, later entries overwrite earlier entries. This option is provided as a performance optimization.
-read-sparse	(c, r, u modes only) Read sparse file information from disk. This is the reverse of -no-read-sparse and the default behavior.
-S	(x mode only) Extract files as sparse files. For every block on disk, check first if it contains only NULL bytes and seek over it otherwise. This works similar to the conv=sparse option of dd.
-s pattern	Modify file or archive member names according to pattern. The pattern has the format /old/new/[ghHprRsS] where old is a basic regular expression, new is the replacement string of the matched part, and the optional trailing letters modify how the replacement is handled. If old is not matched, the pattern is skipped. Within new, ~ is substituted with the match, \1 to \9 with the content of the corresponding captured group. The optional trailing g specifies that matching should continue after the matched part and stop on the first unmatched pattern. The optional trailing s specifies that the pattern applies to the value of symbolic links. The optional trailing p specifies that after a successful substitution the original path name and the new path name should be printed to standard error. Optional trailing H, R, or S characters suppress substitutions for hardlink targets, regular filenames, or symlink targets, respectively. Optional trailing h, r, or s characters enable substitutions for hardlink targets, regular filenames, or symlink targets, respectively. The default is hrs which applies substitutions to all names. In particular, it is never necessary to specify h, r, or s.
-safe-writes	(x mode only) Extract files atomically. By default tar unlinks the original file with the same name as the extracted file (if it exists), and then creates it immediately under the same name and writes to it. For a short period of time, applications trying to access the file might not find it, or see incomplete results. If -safe-writes is enabled, tar first creates a unique temporary file, then writes the new contents to the temporary file, and finally renames the temporary file to its final name atomically using rename(2). This guarantees that an application accessing the file, will either see the old contents or the new contents at all times.
-same-owner	(x mode only) Extract owner and group IDs. This is the reverse of -no-same-owner and the default behavior if tar is run as root.
-strip-components count	Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped. Note that the pathname is edited after checking inclusion/exclusion patterns but before security checks.
-T filename , -files-from filename	In x or t mode, tar will read the list of names to be extracted from filename. In c mode, tar will read names to be archived from filename. The special name "-C" on a line by itself will cause the current directory to be changed to the directory specified on the following line. Names are terminated by newlines unless -null is specified. Note that -null also disables the special handling of lines containing "-C". Note: If you are generating lists of files using find(1), you probably want to use -n as well.
-totals	(c, r, u modes only) After archiving all files, print a summary to stderr.
-U -, -unlink -, -unlink-first	(x mode only) Unlink files before creating them. This can be a minor performance optimization if most files already exist, but can make things slower if most files do not already exist. This flag also causes tar to remove intervening directory symlinks instead of reporting an error. See the SECURITY section below for more details.
-uid id	Use the provided user id number and ignore the user name from the archive. On create, if -uname is not also specified, the user name will be set to match the user id.
-uname name	Use the provided user name. On extract, this overrides the user name in the archive; if the provided user name does not exist on the system, it will be ignored and the user id (from the archive or from the -uid option) will be used instead. On create, this sets the user name that will be stored in the archive; the name is not verified against the system user database.
-use-compress-program program	Pipe the input (in x or t mode) or the output (in c mode) through program instead of using the builtin compression support.
-v -, -verbose	Produce verbose output. In create and extract modes, tar will list each file name as it is read from or written to the archive. In list mode, tar will produce output similar to that of ls(1). An additional -v option will also provide ls-like details in create and extract mode.
-version	Print version of tar and libarchive, and exit.
-w -, -confirmation -, -interactive	Ask for confirmation for every action.
-X filename , -exclude-from filename	Read a list of exclusion patterns from the specified file. See -exclude for more information about the handling of exclusions.
-xattrs	(c, r, u, x modes only) Archive or extract extended file attributes. This is the reverse of -no-xattrs and the default behavior in c, r, and u modes or if tar is run in x mode as root.
-y	(c mode only) Compress the resulting archive with bzip2(1). In extract or list modes, this option is ignored. Note that this tar implementation recognizes bzip2 compression automatically when reading archives.
-Z -, -compress -, -uncompress	(c mode only) Compress the resulting archive with compress(1). In extract or list modes, this option is ignored. Note that this tar implementation recognizes compress compression automatically when reading archives.
-z -, -gunzip -, -gzip	(c mode only) Compress the resulting archive with gzip(1). In extract or list modes, this option is ignored. Note that this tar implementation recognizes gzip compression automatically when reading archives.

An input file in mtree(5) format can be used to create an output archive with arbitrary ownership, permissions, or names that differ from existing data on disk:

$ cat input.mtree
#mtree
usr/bin uid=0 gid=0 mode=0755 type=dir
usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls
$ tar -cvf output.tar @input.mtree

The -newer and -newer-mtime switches accept a variety of common date and time specifications, including "12 Mar 2005 7:14:29pm", "2005-03-12 19:14", "5 minutes ago", and "19:14 PST May 1".

The -options argument can be used to control various details of archive generation or reading. For example, you can generate mtree output which only contains type, time, and uid keywords:

    Fl

or you can set the compression level used by gzip or xz compression:

    Fl.

For more details, see the explanation of the archive_read_set_options() and archive_write_set_options() API calls that are described in archive_read(3) and archive_write(3).

This is a complete re-implementation based on the libarchive(3) library. It was first released with FreeBSD 5.4 in May, 2005.

All archive output is written in correctly-sized blocks, even if the output is being compressed. Whether or not the last output block is padded to a full block size varies depending on the format and the output device. For tar and cpio formats, the last block of output is padded to a full block size if the output is being written to standard output or to a character or block device such as a tape drive. If the output is being written to a regular file, the last block will not be padded. Many compressors, including gzip(1) and bzip2(1), complain about the null padding when decompressing an archive created by tar, although they still extract it correctly.

The compression and decompression is implemented internally, so there may be insignificant differences between the compressed output generated by

    Fl

and that generated by

    Fl

The default should be to read and write archives to the standard I/O paths, but tradition (and POSIX) dictates otherwise.

The r and u modes require that the archive be uncompressed and located in a regular file on disk. Other archives can be modified using c mode with the @archive-file extension.

To archive a file called @foo or -foo you must specify it as ./@foo or ./-foo, respectively.

In create mode, a leading ./ is always removed. A leading / is stripped unless the -P option is specified.

There needs to be better support for file selection on both create and extract.

There is not yet any support for multi-volume archives.

Converting between dissimilar archive formats (such as tar and cpio) using the @ - convention can cause hard link information to be lost. (This is a consequence of the incompatible ways that different archive formats store hardlink information.)