Attempt to preserve the access time of files when reading them. This
option currently is effective only on files that you own, unless you
have superuser privileges.
--atime-preserve=replace remembers the access time of a file
before reading it, and then restores the access time afterwards. This
may cause problems if other programs are reading the file at the same
time, as the times of their accesses will be lost. On most platforms
restoring the access time also requires tar to restore the
data modification time too, so this option may also cause problems if
other programs are writing the file at the same time. (Tar attempts
to detect this situation, but cannot do so reliably due to race
conditions.) Worse, on most platforms restoring the access time also
updates the status change time, which means that this option is
incompatible with incremental backups.
--atime-preserve=system avoids changing time stamps on files,
without interfering with time stamp updates
caused by other programs, so it works better with incremental backups.
However, it requires a special O_NOATIME option from the
underlying operating and file system implementation, and it also requires
that searching directories does not update their access times. As of
this writing (November 2005) this works only with Linux, and only with
Linux kernels 2.6.8 and later. Worse, there is currently no reliable
way to know whether this feature actually works. Sometimes
tar knows that it does not work, and if you use
--atime-preserve=system then tar complains and
exits right away. But other times tar might think that the
option works when it actually does not.
Currently --atime-preserve with no operand defaults to
--atime-preserve=replace, but this may change in the future
as support for --atime-preserve=system improves.
If your operating system does not support
--atime-preserve=system, you might be able to preserve access
times reliably by by using the mount command. For example,
you can mount the file system read-only, or access the file system via
a read-only loopback mount, or use the ‘noatime’ mount option
available on some systems. However, mounting typically requires
superuser privileges and can be a pain to manage.
--backup=backup-type
Rather than deleting files from the file system, tar will
back them up using simple or numbered backups, depending upon
backup-type. See backup.
--block-number
-R
With this option present, tar prints error messages for read errors
with the block number in the archive file. See block-number.
--blocking-factor=blocking
-b blocking
Sets the blocking factor tar uses to blocking x 512 bytes per
record. See Blocking Factor.
--bzip2
-j
This option tells tar to read or write archives through
bzip2. See gzip.
--checkpoint
This option directs tar to print periodic checkpoint messages as it
reads through the archive. Its intended for when you want a visual
indication that tar is still running, but don't want to see
--verbose output.
--check-links
-l
If this option was given, tar will check the number of links
dumped for each processed file. If this number does not match the
total number of hard links for the file, a warning message will be
output.
Future versions will take -l as a short version of
--check-links. However, current release still retains the old
semantics for -l.
When creating a tar archive, tar will archive the
file that a symbolic link points to, rather than archiving the
symlink. See dereference.
--directory=dir
-C dir
When this option is specified, tar will change its current directory
to dir before performing any operations. When this option is used
during archive creation, it is order sensitive. See directory.
--exclude=pattern
When performing operations, tar will skip files that match
pattern. See exclude.
--exclude-from=file
-X file
Similar to --exclude, except tar will use the list of
patterns in the file file. See exclude.
--exclude-caches
Automatically excludes all directories
containing a cache directory tag. See exclude.
--file=archive
-f archive
tar will use the file archive as the tar archive it
performs operations on, rather than tar's compilation dependent
default. See file tutorial.
--files-from=file
-T file
tar will use the contents of file as a list of archive members
or files to operate on, in addition to those specified on the
command-line. See files.
--force-local
Forces tar to interpret the filename given to --file
as a local file, even if it looks like a remote tape drive name.
See local and remote archives.
--format=format
Selects output archive format. Format may be one of the
following:
‘v7’
Creates an archive that is compatible with Unix V7 tar.
‘oldgnu’
Creates an archive that is compatible with GNU tar version
1.12 or earlier.
‘gnu’
Creates archive in GNU tar 1.13 format. Basically it is the same as
‘oldgnu’ with the only difference in the way it handles long
numeric fields.
‘ustar’
Creates a POSIX.1-1988 compatible archive.
‘posix’
Creates a POSIX.1-2001 archive.
See Formats, for a detailed discussion of these formats.
--group=group
Files added to the tar archive will have a group id of group,
rather than the group from the source file. group is first decoded
as a group symbolic name, but if this interpretation fails, it has to be
a decimal numeric group ID.
Also see the comments for the --owner=user option.
--gzip
--gunzip
--ungzip
-z
This option tells tar to read or write archives through
gzip, allowing tar to directly operate on several
kinds of compressed archives transparently. See gzip.
--help
tar will print out a short message summarizing the operations and
options to tar and exit. See help.
Do not exit unsuccessfully merely because an unreadable file was encountered.
See Reading.
--ignore-zeros
-i
With this option, tar will ignore zeroed blocks in the
archive, which normally signals EOF. See Reading.
--incremental
-G
Used to inform tar that it is working with an old
GNU-format incremental backup archive. It is intended
primarily for backwards compatibility only. .
--index-file=file
Send verbose output to file instead of to standard output.
--info-script=script-file
--new-volume-script=script-file
-F script-file
When tar is performing multi-tape backups, script-file is run
at the end of each tape. If script-file exits with nonzero status,
tar fails immediately. See info-script, for a detailed
discussion of script-file.
--interactive
--confirmation
-w
Specifies that tar should ask the user for confirmation before
performing potentially destructive options, such as overwriting files.
See interactive.
--keep-newer-files
Do not replace existing files that are newer than their archive copies
when extracting files from an archive.
--keep-old-files
-k
Do not overwrite existing files when extracting files from an archive.
See Keep Old Files.
--label=name
-V name
When creating an archive, instructs tar to write name
as a name record in the archive. When extracting or listing archives,
tar will only operate on archives that have a label matching
the pattern specified in name. See Tape Files.
--listed-incremental=snapshot-file
-g snapshot-file
During a --create operation, specifies that the archive that
tar creates is a new GNU-format incremental
backup, using snapshot-file to determine which files to backup.
With other operations, informs tar that the archive is in
incremental format. .
--mode=permissions
When adding files to an archive, tar will use
permissions for the archive members, rather than the permissions
from the files. The program chmod and this tar
option share the same syntax for what permissions might be.
See Permissions. This reference also has useful
information for those not being overly familiar with the Unix
permission system.
Of course, permissions might be plainly specified as an octal number.
However, by using generic symbolic modifications to mode bits, this allows
more flexibility. For example, the value ‘a+rw’ adds read and write
permissions for everybody, while retaining executable bits on directories
or on any other file already marked as executable.
--multi-volume
-M
Informs tar that it should create or otherwise operate on a
multi-volume tar archive. See Using Multiple Tapes.
--new-volume-script
(see –info-script)
--seek
-n
Assume that the archive media supports seeks to arbitrary
locations. Usually tar determines automatically whether
the archive can be seeked or not. This option is intended for use
in cases when such recognition fails.
--newer=date
--after-date=date
-N
When creating an archive, tar will only add files that have changed
since date. If date begins with ‘/’ or ‘.’, it
is taken to be the name of a file whose data modification time specifies
the date. See after.
--newer-mtime=date
Like --newer, but add only files whose
contents have changed (as opposed to just --newer, which will
also back up files for which any status information has changed).
Setting modification times and permissions of extracted
directories when all files from this directory has been
extracted. This is the default. See Directory Modification Times and Permissions.
Do not quote characters from string, even if the selected
quoting style implies they should be quoted ().
--no-recursion
With this option, tar will not recurse into directories.
See recurse.
--no-same-owner
-o
When extracting an archive, do not attempt to preserve the owner
specified in the tar archive. This the default behavior
for ordinary users.
--no-same-permissions
When extracting an archive, subtract the user's umask from files from
the permissions specified in the archive. This is the default behavior
for ordinary users.
When tar is using the --files-from option, this option
instructs tar to expect filenames terminated with NUL, so
tar can correctly work with file names that contain newlines.
See nul.
--numeric-owner
This option will notify tar that it should use numeric user
and group IDs when creating a tar file, rather than names.
See Attributes.
-o
When extracting files, this option is a synonym for
--no-same-owner, i.e. it prevents tar from
restoring ownership of files being extracted.
When creating an archive, -o is a synonym for
--old-archive. This behavior is for compatibility
with previous versions of GNU tar, and will be
removed in the future releases.
This option can be used in conjunction with one of the subcommands
--delete, --diff, --extract or
--list when a list of files is given either on the command
line or via -T option.
This option instructs tar to process only the numberth
occurrence of each named file. Number defaults to 1, so
tar -x -f archive.tar --occurrence filename
will extract the first occurrence of filename from archive.tar
and will terminate without scanning to the end of the archive.
--old-archive
Synonym for --format=v7.
--one-file-system
-l
Used when creating an archive. Prevents tar from recursing into
directories that are on different file systems from the current
directory.
Earlier versions of GNU tar understood -l as a
synonym for --one-file-system. Although such usage is still
allowed in the present version, it is strongly discouraged.
The future versions of GNU tar will use -l as
a synonym for --check-links.
Overwrite existing files and directory metadata when extracting files
from an archive. See Overwrite Old Files.
--overwrite-dir
Overwrite the metadata of existing directories when extracting files
from an archive. See Overwrite Old Files.
--owner=user
Specifies that tar should use user as the owner of members
when creating archives, instead of the user associated with the source
file. user is first decoded as a user symbolic name, but if
this interpretation fails, it has to be a decimal numeric user ID.
There is no value indicating a missing number, and ‘0’ usually means
root. Some people like to force ‘0’ as the value to offer in
their distributions for the owner of files, because the root user is
anonymous anyway, so that might as well be the owner of anonymous archives.
This option does not affect extraction from archives.
--quote-chars=string
Always quote characters from string, even if the selected
quoting style would not quote them ().
--quoting-style=style
Set quoting style to use when printing member and file names
(). Valid style values are:
literal, shell, shell-always, c,
escape, locale, and clocale. Default quoting
style is escape, unless overridden while configuring the
package.
--pax-option=keyword-list
This option is meaningful only with POSIX.1-2001 archives
(see posix). It modifies the way tar handles the
extended header keywords. Keyword-list is a comma-separated
list of keyword options, each keyword option taking one of
the following forms:
delete=pattern
When used with one of archive-creation commands,
this option instructs tar to omit from extended header records
that it produces any keywords matching the string pattern.
When used in extract or list mode, this option instructs tar
to ignore any keywords matching the given pattern in the extended
header records. In both cases, matching is performed using the pattern
matching notation described in POSIX 1003.2, 3.13
(See glob(7)). For example:
--pax-option delete=security.*
would suppress security-related information.
exthdr.name=string
This keyword allows user control over the name that is written into the
ustar header blocks for the extended headers. The name is obtained
from string after substituting the following meta-characters:
Meta-character
Replaced By
%d
The directory name of the file, equivalent to the
result of the dirname utility on the translated pathname.
%f
The filename of the file, equivalent to the result
of the basename utility on the translated pathname.
%p
The process ID of the tar process.
%%
A ‘%’ character.
Any other ‘%’ characters in string produce undefined
results.
If no option ‘exthdr.name=string’ is specified, tar
will use the following default value:
%d/PaxHeaders.%p/%f
globexthdr.name=string
This keyword allows user control over the name that is written into
the ustar header blocks for global extended header records. The name
shall will be obtained from the contents of string, after the
following character substitutions have been made:
Meta-character
Replaced By
%n
An integer that represents the
sequence number of the global extended header record in the archive,
starting at 1.
%p
The process ID of the tar process.
%%
A ‘%’ character.
Any other ‘%’ characters in string produce undefined results.
If no option ‘globexthdr.name=string’ is specified, tar
will use the following default value:
$TMPDIR/GlobalHead.%p.%n
where ‘$TMPDIR’ represents the value of the TMPDIR
environment variable. If TMPDIR is not set, tar
uses ‘/tmp’.
keyword=value
When used with one of archive-creation commands, these keyword/value pairs
will be included at the beginning of the archive in a global extended
header record. When used with one of archive-reading commands,
tar will behave as if it has encountered these keyword/value
pairs at the beginning of the archive in a global extended header
record.
keyword:=value
When used with one of archive-creation commands, these keyword/value pairs
will be included as records at the beginning of an extended header for
each file. This is effectively equivalent to keyword=value
form except that it creates no global extended header records.
When used with one of archive-reading commands, tar will
behave as if these keyword/value pairs were included as records at the
end of each extended header; thus, they will override any global or
file-specific extended header record keywords of the same names.
For example, in the command:
tar --format=posix --create \
--file archive --pax-option gname:=user .
the group name will be forced to a new value for all files
stored in the archive.
--portability
--old-archive
Synonym for --format=v7.
--posix
Same as --format=posix.
--preserve
Synonymous with specifying both --preserve-permissions and
--same-order. See Setting Access Permissions.
When tar is extracting an archive, it normally subtracts the
users' umask from the permissions specified in the archive and uses
that number as the permissions to create the destination file.
Specifying this option instructs tar that it should use the
permissions directly from the archive. See Setting Access Permissions.
--read-full-records
-B
Specifies that tar should reblock its input, for reading
from pipes on systems with buggy implementations. See Reading.
--record-size=size
Instructs tar to use size bytes per record when accessing the
archive. See Blocking Factor.
--recursion
With this option, tar recurses into directories.
See recurse.
--recursive-unlink
Remove existing
directory hierarchies before extracting directories of the same name
from the archive. See Recursive Unlink.
--remove-files
Directs tar to remove the source file from the file system after
appending it to an archive. See remove files.
--restrict
Disable use of some potentially harmful tar options.
Currently this option disables shell invocaton from multi-volume menu
(see Using Multiple Tapes).
--rmt-command=cmd
Notifies tar that it should use cmd instead of
the default /usr/libexec/rmt (see Remote Tape Server).
--rsh-command=cmd
Notifies tar that is should use cmd to communicate with remote
devices. See Device.
--same-order
--preserve-order
-s
This option is an optimization for tar when running on machines with
small amounts of memory. It informs tar that the list of file
arguments has already been sorted to match the order of files in the
archive. See Reading.
--same-owner
When extracting an archive, tar will attempt to preserve the owner
specified in the tar archive with this option present.
This is the default behavior for the superuser; this option has an
effect only for ordinary users. See Attributes.
Displays the default options used by tar and exits
successfully. This option is intended for use in shell scripts.
Here is an example of what you can see using this option:
$ tar --show-defaults
--format=gnu -f- -b20 --quoting-style=escape \
--rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
--show-omitted-dirs
Instructs tar to mention directories its skipping over when
operating on a tar archive. See show-omitted-dirs.
--show-stored-names
This option has effect only when used in conjunction with one of
archive creation operations. It instructs tar to list the member names
stored in the archive, as opposed to the actual file
names. See listing member and file names.
--sparse
-S
Invokes a GNU extension when adding files to an archive that handles
sparse files efficiently. See sparse.
--starting-file=name
-K name
This option affects extraction only; tar will skip extracting
files in the archive until it finds one that matches name.
See Scarce.
--strip-components=number
Strip given number of leading components from file names before
extraction.1 For example, if archive archive.tar contained
/some/file/name, then running
tar --extract --file archive.tar --strip-components=2
would extracted this file to file name.
--suffix=suffix
Alters the suffix tar uses when backing up files from the default
‘~’. See backup.
--tape-length=num
-L num
Specifies the length of tapes that tar is writing as being
num x 1024 bytes long. See Using Multiple Tapes.
--test-label
Reads the volume label. If an argument is specified, test whether it
matches the volume label. See –test-label option.
During extraction, tar will extract files to stdout rather
than to the file system. See Writing to Standard Output.
--totals
Displays the total number of bytes written after creating an archive.
See verbose.
--touch
-m
Sets the data modification time of extracted files to the extraction time,
rather than the data modification time stored in the archive.
See Data Modification Times.
Directs tar to remove the corresponding file from the file
system before extracting it from the archive. See Unlink First.
--use-compress-program=prog
Instructs tar to access the archive through prog, which is
presumed to be a compression program of some sort. See gzip.
--utc
Display file modification dates in UTC. This option implies
--verbose.
--verbose
-v
Specifies that tar should be more verbose about the operations its
performing. This option can be specified multiple times for some
operations to increase the amount of information displayed.
See verbose.
--verify
-W
Verifies that the archive was correctly written when creating an
archive. See verify.
--version
Print information about the program's name, version, origin and legal
status, all on standard output, and then exit successfully.
See help.
--volno-file=file
Used in conjunction with --multi-volume. tar will keep track
of which volume of a multi-volume archive its working in file.
See volno-file.
