| TAR(1) | General Commands Manual | TAR(1) |
tar —
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).
@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.-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.-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-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.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-levellzop:compression-levelxz:compression-levelmtree: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-S-s
pattern--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-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.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.TZtar utility exits 0 on success,
and >0 if an error occurs.
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).
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.
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.
The ustar and pax interchange file formats are defined by IEEE Std 1003.1-2001 (“POSIX.1”) for the pax command.
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.
-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.)
| June 3, 2019 | NetBSD 9.0 |