TAR

 

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

–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-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

-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

–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

–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 filenames read with -T (default)

–no-unquote

do not unquote filenames read with -T

–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

   

HISTORY

The tar command appeared in AT&T System v7 .  

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.