tar Man page

TAR(1) BSD General Commands Manual TAR(1)

NAME

tar — The GNU version of the tar archiving utility

SYNOPSIS

tar [-] A –catenate –concatenate | c –create | d –diff –compare |
–delete | r –append | t –list | –test-label | u –update | x
–extract –get [options] [pathname …]

DESCRIPTION

Tar stores and extracts files from a tape or disk archive.

The first argument to tar should be a function; either one of the letters
Acdrtux, or one of the long function names. A function letter need not
be prefixed with “-”, and may be combined with other single-letter
options. A long function name must be prefixed with –. Some options
take a parameter; with the single-letter form these must be given as sep‐
arate arguments. With the long form, they may be given by appending
=value to the option.

FUNCTION LETTERS
Main operation mode:

-A, –catenate, –concatenate
append tar files to an archive

-c, –create
create a new archive

-d, –diff, –compare
find differences between archive and file system

–delete
delete from the archive (not on mag tapes!)

-r, –append
append files to the end of an archive

-t, –list
list the contents of an archive

–test-label
test the archive volume label and exit

-u, –update
only append files newer than copy in archive

-x, –extract, –get
extract files from an archive

OTHER

OPTIONS

Operation modifiers:

-[0-7][lmh] specify drive and density

-a, –auto-compress
use archive suffix to determine the compression program

–acls
Enable the POSIX ACLs support

–no-acls
Disable the POSIX ACLs support

–add-file=FILE
add given FILE to the archive (useful if its name starts with a
dash)

–anchored
patterns match file name start

–no-anchored
patterns match after any ‘/’ (default for exclusion)

–atime-preserve
preserve access times on dumped files, either by restoring the
times after reading (METHOD=’replace’; default) or by not setting
the times in the first place (METHOD=’system’)

–no-auto-compress
do not use archive suffix to determine the compression program

-b, –blocking-factor BLOCKS
BLOCKS x 512 bytes per record

-B, –read-full-records
reblock as we read (for 4.2BSD pipes)

–backup
backup before removal, choose version CONTROL

-C, –directory DIR
change to directory DIR

–check-device
check device numbers when creating incremental archives (default)

–no-check-device
do not check device numbers when creating incremental archives

–checkpoint
display progress messages every NUMBERth record (default 10)

–checkpoint-action=ACTION
execute ACTION on each checkpoint

–clamp-mtime
only set time when the file is more recent than what was given with
–mtime

–delay-directory-restore
delay setting modification times and permissions of extracted
directories until the end of extraction

–no-delay-directory-restore
cancel the effect of –delay-directory-restore option

–exclude=PATTERN
exclude files, given as a PATTERN

–exclude-backups
exclude backup and lock files

–exclude-caches
exclude contents of directories containing CACHEDIR.TAG, except for
the tag file itself

–exclude-caches-all
exclude directories containing CACHEDIR.TAG

–exclude-caches-under
exclude everything under directories containing CACHEDIR.TAG

–exclude-ignore=FILE
read exclude patterns for each directory from FILE, if it exists

–exclude-ignore-recursive=FILE
read exclude patterns for each directory and its subdirectories
from FILE, if it exists

–exclude-tag=FILE
exclude contents of directories containing FILE, except for FILE
itself

–exclude-tag-all=FILE
exclude directories containing FILE

–exclude-tag-under=FILE
exclude everything under directories containing FILE

–exclude-vcs
exclude version control system directories

–exclude-vcs-ignores
read exclude patterns from the VCS ignore files

-f, –file ARCHIVE
use archive file or device ARCHIVE

-F, –info-script, –new-volume-script

NAME

run script at end of each tape (implies -M)

–force-local
archive file is local even if it has a colon

–full-time
print file time to its full resolution

-g, –listed-incremental FILE
handle new GNU-format incremental backup

-G, –incremental
handle old GNU-format incremental backup

–group=

NAME

force NAME as group for added files

-h, –dereference
follow symlinks; archive and dump the files they point to

-H, –format FORMAT
create archive of the given formatFORMAT is one of the following:

–format=gnu
GNU tar 1.13.x format

–format=oldgnu
GNU format as per tar <= 1.12 --format=pax POSIX 1003.1-2001 (pax) format --format=posix same as pax --format=ustar POSIX 1003.1-1988 (ustar) format --format=v7 old V7 tar format --hard-dereference follow hard links; archive and dump the files they refer to -i, --ignore-zeros ignore zeroed blocks in archive (means EOF) -I, --use-compress-program PROG filter through PROG (must accept -d) --ignore-case ignore case --no-ignore-case case sensitive matching (default) --ignore-command-error ignore exit codes of children --no-ignore-command-error treat non-zero exit codes of children as error --ignore-failed-read do not exit with nonzero on unreadable files --index-file=FILE send verbose output to FILE -j, --bzip2 -J, --xz -k, --keep-old-files don't replace existing files when extracting, treat them as errors -K, --starting-file MEMBER-

NAME

begin at member MEMBER-NAME when reading the archive

–keep-directory-symlink
preserve existing symlinks to directories when extracting

–keep-newer-files
don’t replace existing files that are newer than their archive
copies

-l, –check-links
print a message if not all links are dumped

-L, –tape-length NUMBER
change tape after writing NUMBER x 1024 bytes

–level=NUMBER
dump level for created listed-incremental archive

–lzip

–lzma

–lzop

-m, –touch
don’t extract file modified time

-M, –multi-volume
create/list/extract multi-volume archive

–mode=CHANGES
force (symbolic) mode CHANGES for added files

–mtime=DATE-OR-FILE
set mtime for added files from DATE-OR-FILE

-n, –seek
archive is seekable

-N, –newer, –after-date DATE-OR-FILE
only store files newer than DATE-OR-FILE

–newer-mtime=DATE
compare date and time when data changed only

–null
-T reads null-terminated names, disable -C

–no-null
disable the effect of the previous –null option

–numeric-owner
always use numbers for user/group names

-O, –to-stdout
extract files to standard output

–occurrence
process only the NUMBERth occurrence of each file in the archive;
this option is valid only in conjunction with one of the subcom‐
mands –delete, –diff, –extract or –list and when a list of
files is given either on the command line or via the -T option;
NUMBER defaults to 1

–old-archive, –portability
same as –format=v7

–one-file-system
stay in local file system when creating archive

–one-top-level
create a subdirectory to avoid having loose files extracted

–overwrite
overwrite existing files when extracting

–overwrite-dir
overwrite metadata of existing directories when extracting
(default)

–no-overwrite-dir
preserve metadata of existing directories

–owner=

NAME

force NAME as owner for added files

-p, –preserve-permissions, –same-permissions
extract information about file permissions (default for superuser)

-P, –absolute-names
don’t strip leading ‘/’s from file names

–pax-option=keyword[[:]=value][,keyword[[:]=value]]…
control pax keywords

–posix
same as –format=posix

–preserve
same as both -p and -s

–quote-chars=STRING
additionally quote characters from STRING

–no-quote-chars=STRING
disable quoting for characters from STRING

–quoting-style=STYLE
set name quoting style; see below for valid STYLE values

-R, –block-number
show block number within archive with each message

–record-size=NUMBER
NUMBER of bytes per record, multiple of 512

–recursion
recurse into directories (default)

–no-recursion
avoid descending automatically in directories

–recursive-unlink
empty hierarchies prior to extracting directory

–remove-files
remove files after adding them to the archive

–restrict
disable use of some potentially harmful options

–rmt-command=COMMAND
use given rmt COMMAND instead of rmt

–rsh-command=COMMAND
use remote COMMAND instead of rsh

-s, –preserve-order, –same-order
member arguments are listed in the same order as the files in the
archive

-S, –sparse
handle sparse files efficiently

–same-owner
try extracting files with the same ownership as exists in the ar‐
chive (default for superuser)

–no-same-owner
extract files as yourself (default for ordinary users)

–no-same-permissions
apply the user’s umask when extracting permissions from the archive
(default for ordinary users)

–no-seek
archive is not seekable

–selinux
Enable the SELinux context support

–no-selinux
Disable the SELinux context support

–show-defaults
show tar defaults

–show-omitted-dirs
when listing or extracting, list each directory that does not match
search criteria

–show-snapshot-field-ranges
show valid ranges for snapshot-file fields

–show-transformed-names, –show-stored-names
show file or archive names after transformation

–skip-old-files
don’t replace existing files when extracting, silently skip over
them

–sort=ORDER
directory sorting order: none (default), name or inodedirectory
sorting order: none (default) or name

–sparse-version=MAJOR[.MINOR] set version of the sparse format to use (implies –sparse)

–strip-components=NUMBER
strip NUMBER leading components from file names on extraction

–suffix=STRING
backup before removal, override usual suffix (‘~’ unless overridden
by environment variable SIMPLE_BACKUP_SUFFIX)

-T, –files-from FILE
get names to extract or create from FILE

–to-command=COMMAND
pipe extracted files to another program

–totals
print total bytes after processing the archive; with an argument –
print total bytes when this SIGNAL is delivered; Allowed signals
are: SIGHUP, SIGQUIT, SIGINT, SIGUSR1 and SIGUSR2; the names with‐
out SIG prefix are also accepted

–transform, –xform EXPRESSION
use sed replace EXPRESSION to transform file names

-U, –unlink-first
remove each file prior to extracting over it

–unquote
unquote input file or member names (default)

–no-unquote
do not unquote input file or member names

–utc
print file modification times in UTC

-v, –verbose
verbosely list files processed

-V, –label TEXT
create archive with volume name TEXT; at list/extract time, use
TEXT as a globbing pattern for volume name

–volno-file=FILE
use/update the volume number in FILE

-w, –interactive, –confirmation
ask for confirmation for every action

-W, –verify
attempt to verify the archive after writing it

–warning=KEYWORD
warning control

–wildcards
use wildcards (default for exclusion)

–wildcards-match-slash
wildcards match ‘/’ (default for exclusion)

–no-wildcards-match-slash
wildcards do not match ‘/’

–no-wildcards
verbatim string matching

-X, –exclude-from FILE
exclude patterns listed in FILE

–xattrs
Enable extended attributes support

–xattrs-exclude=MASK
specify the exclude pattern for xattr keys

–xattrs-include=MASK
specify the include pattern for xattr keys

–no-xattrs
Disable extended attributes support

-z, –gzip, –gunzip –ungzip

-Z, –compress, –uncompress

ENVIRONMENT
The behavior of tar is controlled by the following environment variables,
among others:

TAR_LONGLINK_100

PRISTINE_TAR_COMPAT

SIMPLE_BACKUP_SUFFIX
Backup prefix to use when extracting, if –suffix is not speci‐
fied. The backup suffix defaults to `~’ if neither is specified.

TAR_

OPTIONS

Options to prepend to those specified on the command line, sepa‐
rated by whitespace. Embedded backslashes may be used to escape
whitespace or backslashes within an option.

TAPE Device or file to use for the archive if –file is not specified.
If this environment variable is unset, use stdin or stdout
instead.

EXAMPLES
Create archive.tar from files foo and bar.
tar -cf archive.tar foo bar
List all files in archive.tar verbosely.
tar -tvf archive.tar
Extract all files from archive.tar.
tar -xf archive.tar

SEE ALSO

tar(5), symlink(7), rmt(8)

HISTORY
The tar command appeared in Version 7 AT&T UNIX.

BUGS

The GNU folks, in general, abhor man pages, and create info documents
instead. Unfortunately, the info document describing tar is licensed
under the GFDL with invariant cover texts, which makes it impossible to
include any text from that document in this man page. Most of the text
in this document was automatically extracted from the usage text in the
source. It may not completely describe all features of the program.

Nov 17, 2016