| TAR(1) | General Commands Manual | TAR(1) |
tar — manipulate
tape archives
tar |
[bundled-flags ⟨args⟩] [⟨file⟩ | ⟨pattern⟩ ...] |
tar |
{-c} [options]
[files | directories] |
tar |
{-r | -u}
-f archive-file
[options] [files |
directories] |
tar |
{-t | -x}
[options] [patterns] |
tar creates and manipulates streaming
archive files. This implementation can extract from tar, pax, cpio, zip,
jar, ar, xar, rpm, 7-zip, and ISO 9660 cdrom images and can create tar, pax,
cpio, ar, zip, 7-zip, and shar archives.
The first synopsis form shows a “bundled” option word. This usage is provided for compatibility with historical implementations. See COMPATIBILITY below for details.
The other synopsis forms show the preferred usage. The first
option to tar is a mode indicator from the following
list:
-c--create.-r-c, but new entries are appended to the
archive. Note that this only works on uncompressed archives stored in
regular files. The -f option is required. The long
option form is --append.-t--list.-u-r, but new entries are added only if they
have a modification date newer than the corresponding entry in the
archive. Note that this only works on uncompressed archives stored in
regular files. The -f option is required. The long
form is --update.-x--extract.In -c, -r, or
-u mode, each specified file or directory is added
to the archive in the order specified on the command line. By default, the
contents of each directory are also archived.
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).
Unless specifically stated otherwise, options are applicable in all operating modes.
@archivetar
-c -f
- newfile
@original.tartar
-c -f
- newfile
original.tartar
-czf -
--format pax
@-tar can be used to convert
archives from one format to another.-a,
--auto-compresstar
-a -cf
archive.tgz source.c source.htar
-a -cf
archive.tar.bz2.uu source.c source.htar
-a -cf
archive.zip source.c source.htar
-a -jcf
archive.tgz source.c source.htar
-a -jcf
archive.xxx source.c source.h--acls--no-acls and the default behavior
in c, r, and u modes (except on Mac OS X) or if
tar is run in x mode as root. On Mac OS X this
option translates extended ACLs to NFSv4 ACLs. To store extended ACLs the
--mac-metadata option is preferred.-B,
--read-full-blocks-b
blocksize, --block-size
blocksize-C
directory, --cd
directory, --directory
directory--chrootchroot()
to the current directory after processing any -C
options and before extracting any files.--clear-nochange-fflags--exclude
pattern--exclude-vcs--fflags--no-fflags and the default behavior in c, r, and
u modes or if tar is run in x mode as root.--format
format-f
file, --file
file--gid
id--gname is not also specified, the group name will
be set to match the group id.--gname
name--gid
option) will be used instead. On create, this sets the group name that
will be stored in the archive; the name will not be verified against the
system group database.--group
name[:gid]--gname option for details.-H-h-L.-I-T.--help--hfsCompression--ignore-zeros--options
read_concatenated_archives for compatibility with
GNU tar.--include
pattern--exclude take
precedence over inclusions. If no inclusions are explicitly specified, all
entries are processed by default. The --include
option is especially useful when filtering archives. For example, the
command
tar
-c -f
new.tar --include='*foo*'
@old.tgz-J,
--xztar
implementation recognizes XZ compression automatically when reading
archives.-j,
--bzip, --bzip2,
--bunzip2tar
implementation recognizes bzip2 compression automatically when reading
archives.-k,
--keep-old-files--keep-newer-files-L,
--dereference-l,
--check-links--lrziptar
implementation recognizes lrzip compression automatically when reading
archives.--lz4tar implementation recognizes lz4 compression
automatically when reading archives.--zstdtar implementation recognizes zstd
compression automatically when reading archives.--lzma--xz instead. Note that this
tar implementation recognizes LZMA compression
automatically when reading archives.--lzoptar
implementation recognizes LZO compression automatically when reading
archives.-m,
--modification-time--mac-metadata--no-mac-metadata. and the
default behavior in c, r, and u modes or if tar is
run in x mode as root. Currently supported only for pax formats (including
"pax restricted", the default tar format for bsdtar.)-n,
--norecurse,
--no-recursion--newer
date--newer-mtime
date--newer, except it
compares mtime entries instead of ctime entries.--newer-than
file--newer-mtime-than
file--newer-than, except it
compares mtime entries instead of ctime entries.--nodump--nopreserveHFSCompression--null-I or -T)
Filenames or patterns are separated by null characters, not by newlines.
This is often used to read filenames output by the
-print0 option to
find(1).--no-acls--acls and the default
behavior if tar is run as non-root in x mode (on
Mac OS X as any user in c, r, u and x modes).--no-fflags--fflags and the
default behavior if tar is run as non-root in x
mode.--no-mac-metadata--mac-metadata. and the
default behavior if tar is run as non-root in x
mode.--no-read-sparse--read-sparse.--no-safe-writes--safe-writes.--no-same-owner--same-owner and the default behavior if
tar is run as non-root.--no-same-permissions-p and the default behavior if
tar is run as non-root.--no-xattrs--xattrs and
the default behavior if tar is run as non-root in
x mode.--numeric-owner--uname ""
--gname "". On extract, it causes user
and group names in the archive to be ignored in favor of the numeric user
and group ids. On create, it causes user and group names to not be stored
in the archive.-O,
--to-stdout-o-p is specified, and the program is being
run by the root user. In this case, the file modes and flags from the
archive will be restored, but ACLs or owner information in the archive
will be discarded.-o--format
ustar--older
date--older-mtime
date--older, except it
compares mtime entries instead of ctime entries.--older-than
file--older-mtime-than
file--older-than, except it
compares mtime entries instead of ctime entries.--one-file-system--options
options=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!joliet or
iso9660:!joliet to disable.iso9660:rockridge!rockridge or
iso9660:!rockridge to disable.gzip:compression-levelgzip:timestamp!timestamp or
gzip:!timestamp to disable.lrzip:compression=typelrzip:compression-levellz4:compression-levellz4:stream-checksumlz4:!stream-checksum to disable.lz4:block-checksumlz4:block-sizelz4:block-dependencezstd:compression-level=Nzstd:threads=Nzstd:frame-per-filezstd:min-frame-in=Nzstd:frame-per-file, do
not start a new compression frame unless the uncompressed size of the
current frame is at least N bytes. The number
may be followed by k /
kB, M /
MB, or G /
GB to indicate kilobytes, megabytes or
gigabytes respectively.zstd:min-frame-out=N,
zstd:min-frame-size=Nzstd:frame-per-file, do
not start a new compression frame unless the compressed size of the
current frame is at least N bytes. The number
may be followed by k /
kB, M /
MB, or G /
GB to indicate kilobytes, megabytes or
gigabytes respectively.zstd:max-frame-in=N,
zstd:max-frame-size=Nk /
kB, M /
MB, or G /
GB to indicate kilobytes, megabytes or
gigabytes respectively. Values less than 1,024 will be rejected.zstd:max-frame-out=Nk /
kB, M /
MB, or G /
GB to indicate kilobytes, megabytes or
gigabytes respectively. Values less than 1,024 will be rejected.lzop:compression-levelxz:compression-levelxz:threadsmtree:keywordcksum, 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:allmtree:!all to disable all keywords.mtree:use-set/set lines in the
output.mtree:indentzip:compression=typezip:encryptionzip:encryption=typeread_concatenated_archives-i,
--ignore-zeros option of GNU tar.-P,
--absolute-pathstar 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--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--posix--format
pax-q,
--fast-read--read-sparse--no-read-sparse and the default
behavior.-S-s
pattern--safe-writestar 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--no-same-owner and the default behavior if
tar is run as root.--strip-components
count-T
filename, --files-from
filenametar 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-U,
--unlink,
--unlink-firsttar to remove intervening directory symlinks
instead of reporting an error. See the SECURITY section below for more
details.--uid
id--uname is not also specified, the
user name will be set to match the user id.--uname
name--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--owner
name[:uid]--uname option for details.-v,
--verbosetar 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.--versiontar and
libarchive, and exit.-w,
--confirmation,
--interactive-X
filename, --exclude-from
filename--exclude for more information about the handling
of exclusions.--xattrs--no-xattrs and the default
behavior in c, r, and u modes or if tar is run in
x mode as root.-ytar
implementation recognizes bzip2 compression automatically when reading
archives.-Z,
--compress,
--uncompresstar
implementation recognizes compress compression automatically when reading
archives.-z,
--gunzip, --gziptar
implementation recognizes gzip compression automatically when reading
archives.The following environment variables affect the execution of
tar:
TAR_READER_OPTIONS--options option overrides this.TAR_WRITER_OPTIONS--options option overrides this.LANGTAPE-f option overrides this.
Please see the description of the -f option above
for more details.TZThe tar utility exits 0 on success,
and >0 if an error occurs.
The following creates a new archive called file.tar.gz that contains two files source.c and source.h:
tar
-czf file.tar.gz
source.c source.hTo view a detailed table of contents for this archive:
tar
-tvf file.tar.gzTo extract all entries from the archive on the default tape drive:
tar
-xTo examine the contents of an ISO 9660 cdrom image:
tar
-tf image.isoTo move file hierarchies, invoke tar
as
tar
-cf -
-C srcdir . |
tar -xpf
- -C
destdircd srcdir ;
tar -cf -
. | (cd destdir ; tar
-xpf -In create mode, the list of files and directories to be archived
can also include directory change instructions of the form
-Cfoo/baz and archive
inclusions of the form
@archive-file. For example,
the command line
tar
-c -f
new.tar foo1
@old.tgz
-C/tmp
foo2tar will read the file foo1
from the current directory and add it to the output archive. It will then read
each entry from old.tgz and add those entries to the
output archive. Finally, it will switch to the /tmp
directory and add foo2 to the output archive.
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:
tar
-cf file.tar
--format=mtree
--options='!all,type,time,uid'
dirtar
-czf file.tar
--options='compression-level=9'archive_read_set_options() and
archive_write_set_options() API calls that are
described in archive_read(3) and
archive_write(3).
The bundled-arguments format is supported for compatibility with historic implementations. It consists of an initial word (with no leading - character) in which each character indicates an option. Arguments follow as separate words. The order of the arguments must match the order of the corresponding characters in the bundled command word. For example,
tar
tbf 32 file.tart, b, and
f. The b and
f flags both require arguments, so there must be two
additional items on the command line. The 32 is the
argument to the b flag, and
file.tar is the argument to the
f flag.
The mode options c, r, t, u, and x and the options b, f, l, m, o, v, and w comply with SUSv2.
For maximum portability, scripts that invoke
tar should use the bundled-argument format above,
should limit themselves to the c,
t, and x modes, and the
b, f,
m, v, and
w options.
Additional long options are provided to improve compatibility with other tar implementations.
Certain security issues are common to many archiving programs,
including tar. In particular, carefully-crafted
archives can request that tar extract files to
locations outside of the target directory. This can potentially be used to
cause unwitting users to overwrite files they did not intend to overwrite.
If the archive is being extracted by the superuser, any file on the system
can potentially be overwritten. There are three ways this can happen.
Although tar has mechanisms to protect against each
one, savvy users should be aware of the implications:
tar removes the leading /
character from filenames before restoring them to guard against this
problem.tar will not extract files
containing .. components in their pathname.tar checks each extracted path for symlinks.
If the final path element is a symlink, it will be removed and replaced
with the archive entry. If -U is specified, any
intermediate symlink will also be unconditionally removed. If neither
-U nor -P is specified,
tar will refuse to extract the entry.tar
-tf filename-k option to
ensure that tar will not overwrite any existing files
or the -U option to remove any pre-existing files. You
should generally not extract archives while running with super-user
privileges. Note that the -P option to
tar disables the security checks above and allows you
to extract an archive while preserving any absolute pathnames,
.. components, or symlinks to other directories.
bzip2(1), compress(1), cpio(1), gzip(1), pax(1), shar(1), xz(1), libarchive(3), libarchive-formats(5), tar(5)
There is no current POSIX standard for the tar command; it appeared in ISO/IEC 9945-1:1996 (“POSIX.1”) but was dropped from IEEE Std 1003.1-2001 (“POSIX.1”). The options supported by this implementation were developed by surveying a number of existing tar implementations as well as the old POSIX specification for tar and the current POSIX specification for pax.
The ustar and pax interchange file formats are defined by IEEE Std 1003.1-2001 (“POSIX.1”) for the pax command.
A tar command appeared in Seventh Edition
Unix, which was released in January, 1979. There have been numerous other
implementations, many of which extended the file format. John Gilmore's
pdtar public-domain implementation (circa November,
1987) was quite influential, and formed the basis of GNU tar. GNU tar was
included as the standard system tar in FreeBSD
beginning with FreeBSD 1.0.
This is a complete re-implementation based on the libarchive(3) library. It was first released with FreeBSD 5.4 in May, 2005.
This program follows ISO/IEC 9945-1:1996
(“POSIX.1”) for the definition of the
-l option. Note that GNU tar prior to version 1.15
treated -l as a synonym for the
--one-file-system option.
The -C dir option
may differ from historic implementations.
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
tar
-czf - filetar
-cf - file |
gzipThe 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.)
| April 23, 2024 | macOS 15.6 |