| TAR(1) | General Commands Manual | TAR(1) | 
tar —
| tar | [bundled-flags ⟨args⟩] [⟨file⟩ | ⟨pattern⟩ ...] | 
| tar | { -c} [options]
      [files | directories] | 
| tar | { -r|-u}-farchive-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.4 |