core/tar/tar.1

.\" generated by script on Wed Mar 10 17:01:09 2010
.Dd Mar 10, 2010
.Dt TAR 1
.Sh NAME
.Nm tar
.Nd The GNU version of the tar archiving utility
.Sh SYNOPSIS
.Nm tar
.Oo Fl Oc Cm A Fl \-catenate \-concatenate Cm \||\| c Fl \-create Cm \||\| d Fl \-diff \-compare Cm \||\| Fl \-delete Cm \||\| r Fl \-append Cm \||\| t Fl \-list Cm \||\| Fl \-test\-label Cm \||\| u Fl \-update Cm \||\| x Fl \-extract \-get
.Op Ar options
.Op Ar pathname ...
.Sh DESCRIPTION
.Nm Tar
stores and extracts files from a tape or disk archive.
.Pp
The first argument to
tar
should be a function; either one of the letters
.Cm 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
.Cm \\-\\- .
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
.Cm = Ns Ar value
to the option.
.Sh FUNCTION LETTERS
Main operation mode:
.Bl -tag -width flag
.It Fl A , Fl \-catenate , Fl \-concatenate
append tar files to an archive
.It Fl c , Fl \-create
create a new archive
.It Fl d , Fl \-diff , Fl \-compare
find differences between archive and file system
.It Fl \-delete
delete from the archive (not on mag tapes!)
.It Fl r , Fl \-append
append files to the end of an archive
.It Fl t , Fl \-list
list the contents of an archive
.It Fl \-test\-label
test the archive volume label and exit
.It Fl u , Fl \-update
only append files newer than copy in archive
.It Fl x , Fl \-extract , Fl \-get
extract files from an archive
.El
.Sh OTHER OPTIONS
Operation modifiers:
.Bl -tag -width flag
.It \-[0\-7][lmh]
specify drive and density
.It Fl a , Fl \-auto\-compress
use archive suffix to determine the compression program
.It Fl \-add\-file Ns \= Ns Ar FILE
add given FILE to the archive (useful if its name starts with a dash)
.It Fl \-anchored
patterns match file name start
.It Fl \-no\-anchored
patterns match after any `/' (default for exclusion)
.It Fl \-atime\-preserve
preserve access times on dumped files, either by restoring the times
.It Fl \-no\-auto\-compress
do not use archive suffix to determine the compression program
.It Fl b , Fl \-blocking\-factor Ar BLOCKS
BLOCKS x 512 bytes per record
.It Fl B , Fl \-read\-full\-records
reblock as we read (for 4.2BSD pipes)
.It Fl \-backup
backup before removal, choose version CONTROL
.It Fl C , Fl \-directory Ar DIR
change to directory DIR
.It Fl \-check\-device
check device numbers when creating incremental archives (default)
.It Fl \-no\-check\-device
do not check device numbers when creating incremental archives
.It Fl \-checkpoint
display progress messages every NUMBERth record (default 10)
.It Fl \-checkpoint\-action Ns \= Ns Ar ACTION
execute ACTION on each checkpoint
.It Fl \-delay\-directory\-restore
delay setting modification times and permissions of extracted
.It Fl \-no\-delay\-directory\-restore
cancel the effect of --delay-directory-restore option
.It Fl \-exclude Ns \= Ns Ar PATTERN
exclude files, given as a PATTERN
.It Fl \-exclude\-backups
exclude backup and lock files
.It Fl \-exclude\-caches
exclude contents of directories containing CACHEDIR.TAG, 
.It Fl \-exclude\-caches\-all
exclude directories containing CACHEDIR.TAG
.It Fl \-exclude\-caches\-under
exclude everything under directories containing CACHEDIR.TAG
.It Fl \-exclude\-tag Ns \= Ns Ar FILE
exclude contents of directories containing FILE, except
.It Fl \-exclude\-tag\-all Ns \= Ns Ar FILE
exclude directories containing FILE
.It Fl \-exclude\-tag\-under Ns \= Ns Ar FILE
exclude everything under directories containing FILE
.It Fl \-exclude\-vcs
exclude version control system directories
.It Fl f , Fl \-file Ar ARCHIVE
use archive file or device ARCHIVE
.It Fl F , Fl \-info\-script , Fl \-new\-volume\-script Ar NAME
run script at end of each tape (implies -M)
.It Fl \-force\-local
archive file is local even if it has a colon
.It Fl g , Fl \-listed\-incremental Ar FILE
handle new GNU-format incremental backup
.It Fl G , Fl \-incremental
handle old GNU-format incremental backup
.It Fl \-group Ns \= Ns Ar NAME
force NAME as group for added files
.It Fl h , Fl \-dereference
follow symlinks; archive and dump the files they point to
.It Fl H , Fl \-format Ar FORMAT
create archive of the given formatFORMAT is one of the following:
.Bl -tag -width flag
.It Fl \-format=gnu
GNU tar 1.13.x format
.It Fl \-format=oldgnu
GNU format as per tar <= 1.12
.It Fl \-format=pax
POSIX 1003.1-2001 (pax) format
.It Fl \-format=posix
same as pax
.It Fl \-format=ustar
POSIX 1003.1-1988 (ustar) format
.It Fl \-format=v7
old V7 tar format
.El
.It Fl \-hard\-dereference
follow hard links; archive and dump the files they refer to
.It Fl i , Fl \-ignore\-zeros
ignore zeroed blocks in archive (means EOF)
.It Fl I , Fl \-use\-compress\-program Ar PROG
filter through PROG (must accept -d)
.It Fl \-ignore\-case
ignore case
.It Fl \-no\-ignore\-case
case sensitive matching (default)
.It Fl \-ignore\-command\-error
ignore exit codes of children
.It Fl \-no\-ignore\-command\-error
treat non-zero exit codes of children as error
.It Fl \-ignore\-failed\-read
do not exit with nonzero on unreadable files
.It Fl \-index\-file Ns \= Ns Ar FILE
send verbose output to FILE
.It Fl j , Fl \-bzip2

.It Fl J , Fl \-xz

.It Fl k , Fl \-keep\-old\-files
don't replace existing files when extracting
.It Fl K , Fl \-starting\-file Ar MEMBER-NAME
begin at member MEMBER-NAME in the archive
.It Fl \-keep\-newer\-files
don't replace existing files that are newer than their archive copies
.It Fl l , Fl \-check\-links
print a message if not all links are dumped
.It Fl L , Fl \-tape\-length Ar NUMBER
change tape after writing NUMBER x 1024 bytes
.It Fl \-level Ns \= Ns Ar NUMBER
dump level for created listed-incremental archive
.It Fl \-lzip

.It Fl \-lzma

.It Fl \-lzop

.It Fl m , Fl \-touch
don't extract file modified time
.It Fl M , Fl \-multi\-volume
create/list/extract multi-volume archive
.It Fl \-mode Ns \= Ns Ar CHANGES
force (symbolic) mode CHANGES for added files
.It Fl \-mtime Ns \= Ns Ar DATE-OR-FILE
set mtime for added files from DATE-OR-FILE
.It Fl n , Fl \-seek
archive is seekable
.It Fl N , Fl \-newer , Fl \-after\-date Ar DATE-OR-FILE
only store files newer than DATE-OR-FILE
.It Fl \-newer\-mtime Ns \= Ns Ar DATE
compare date and time when data changed only
.It Fl \-null
-T reads null-terminated names, disable -C
.It Fl \-no\-null
disable the effect of the previous --null option
.It Fl \-numeric\-owner
always use numbers for user/group names
.It Fl O , Fl \-to\-stdout
extract files to standard output
.It Fl \-occurrence
process only the NUMBERth occurrence of each file in the archive;
.It Fl \-old\-archive , Fl \-portability
same as --format=v7
.It Fl \-one\-file\-system
stay in local file system when creating archive
.It Fl \-overwrite
overwrite existing files when extracting
.It Fl \-overwrite\-dir
overwrite metadata of existing directories when extracting (default)
.It Fl \-no\-overwrite\-dir
preserve metadata of existing directories
.It Fl \-owner Ns \= Ns Ar NAME
force NAME as owner for added files
.It Fl p , Fl \-preserve\-permissions , Fl \-same\-permissions
extract information about file permissions (default for superuser)
.It Fl P , Fl \-absolute\-names
don't strip leading `/'s from file names
.It Fl \-pax\-option Ns \= Ns Ar keyword[[:]=value][,keyword[[:]=value]]...
control pax keywords
.It Fl \-posix
same as --format=posix
.It Fl \-preserve
same as both -p and -s
.It Fl \-quote\-chars Ns \= Ns Ar STRING
additionally quote characters from STRING
.It Fl \-no\-quote\-chars Ns \= Ns Ar STRING
disable quoting for characters from STRING
.It Fl \-quoting\-style Ns \= Ns Ar STYLE
set name quoting style; see below for valid STYLE values
.It Fl R , Fl \-block\-number
show block number within archive with each message
.It Fl \-record\-size Ns \= Ns Ar NUMBER
NUMBER of bytes per record, multiple of 512
.It Fl \-recursion
recurse into directories (default)
.It Fl \-no\-recursion
avoid descending automatically in directories
.It Fl \-recursive\-unlink
empty hierarchies prior to extracting directory
.It Fl \-remove\-files
remove files after adding them to the archive
.It Fl \-restrict
disable use of some potentially harmful options
.It Fl \-rmt\-command Ns \= Ns Ar COMMAND
use given rmt COMMAND instead of rmt
.It Fl \-rsh\-command Ns \= Ns Ar COMMAND
use remote COMMAND instead of rsh
.It Fl s , Fl \-preserve\-order , Fl \-same\-order
sort names to extract to match archive
.It Fl S , Fl \-sparse
handle sparse files efficiently
.It Fl \-same\-owner
try extracting files with the same ownership as exists in the archive (default for superuser)
.It Fl \-no\-same\-owner
extract files as yourself (default for ordinary users)
.It Fl \-no\-same\-permissions
apply the user's umask when extracting permissions from the archive (default for ordinary users)
.It Fl \-no\-seek
archive is not seekable
.It Fl \-show\-defaults
show tar defaults
.It Fl \-show\-omitted\-dirs
when listing or extracting, list each directory that does not match search criteria
.It Fl \-show\-transformed\-names , Fl \-show\-stored\-names
show file or archive names after transformation
.It Fl \-sparse\-version Ns \= Ns Ar MAJOR[.MINOR]
set version of the sparse format to use (implies --sparse)
.It Fl \-strip\-components Ns \= Ns Ar NUMBER
strip NUMBER leading components from file names on extraction
.It Fl \-suffix Ns \= Ns Ar STRING
backup before removal, override usual suffix ('~' unless overridden by environment variable SIMPLE_BACKUP_SUFFIX)
.It Fl T , Fl \-files\-from Ar FILE
get names to extract or create from FILE
.It Fl \-to\-command Ns \= Ns Ar COMMAND
pipe extracted files to another program
.It Fl \-totals
print total bytes after processing the archive; 
.It Fl \-transform , Fl \-xform Ar EXPRESSION
use sed replace EXPRESSION to transform file names
.It Fl U , Fl \-unlink\-first
remove each file prior to extracting over it
.It Fl \-unquote
unquote filenames read with -T (default)
.It Fl \-no\-unquote
do not unquote filenames read with -T
.It Fl \-utc
print file modification dates in UTC
.It Fl v , Fl \-verbose
verbosely list files processed
.It Fl V , Fl \-label Ar TEXT
create archive with volume name TEXT; at list/extract time, use TEXT as a globbing pattern for volume name
.It Fl \-volno\-file Ns \= Ns Ar FILE
use/update the volume number in FILE
.It Fl w , Fl \-interactive , Fl \-confirmation
ask for confirmation for every action
.It Fl W , Fl \-verify
attempt to verify the archive after writing it
.It Fl \-warning Ns \= Ns Ar KEYWORD
warning control
.It Fl \-wildcards
use wildcards (default for exclusion)
.It Fl \-wildcards\-match\-slash
wildcards match `/' (default for exclusion)
.It Fl \-no\-wildcards\-match\-slash
wildcards do not match `/'
.It Fl \-no\-wildcards
verbatim string matching
.It Fl X , Fl \-exclude\-from Ar FILE
exclude patterns listed in FILE
.It Fl z , Fl \-gzip , Fl \-gunzip Fl \-ungzip

.It Fl Z , Fl \-compress , Fl \-uncompress

.El
.Sh ENVIRONMENT
The behavior of tar is controlled by the following environment variables,
among others:
.Bl -tag -width Ds
.It Ev SIMPLE_BACKUP_SUFFIX
Backup prefix to use when extracting, if
.Fl \-suffix
is not specified.
The backup suffix defaults to `~' if neither is specified.
.It Ev 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.
.It Ev TAPE
Device or file to use for the archive if 
.Fl \-file
is not specified.
If this environment variable is unset, use stdin or stdout instead.
.El
.Sh EXAMPLES
Create archive.tar from files foo and bar.
.Bd -literal -offset indent -compact
tar \-cf archive.tar foo bar
.Ed
List all files in archive.tar verbosely.
.Bd -literal -offset indent -compact
tar \-tvf archive.tar
.Ed
Extract all files from archive.tar.
.Bd -literal -offset indent -compact
tar \-xf archive.tar
.Ed
.Sh SEE ALSO
.\" libarchive
.Xr tar 5 ,
.\" man-pages
.Xr symlink 7 ,
.Xr rmt 8
.Sh HISTORY
The
.Nm tar
command appeared in
.At v7 .
.Sh 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.