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 separate 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 subcommands --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 archive (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 without 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 specified. The backup suffix defaults to `~' if neither is specified.

TAR_OPTIONS
    Options to prepend to those specified on the command line, separated 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 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.