(tar.info.gz) Option Summary
Info Catalog
(tar.info.gz) Operation Summary
(tar.info.gz) All Options
(tar.info.gz) Short Option Summary
3.4.2 `tar' Options
-------------------
`--absolute-names'
`-P'
Normally when creating an archive, `tar' strips an initial `/'
from member names. This option disables that behavior.
absolute.
`--acls'
Causes `tar' to store ACL's. Attributes.
`--after-date'
(See `--newer', after)
`--anchored'
A pattern must match an initial subsequence of the name's
components. controlling pattern-matching.
`--atime-preserve'
`--atime-preserve=replace'
`--atime-preserve=system'
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 or file system does not support
`--atime-preserve=system', you might be able to preserve access
times reliably 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.
`--auto-compress'
`-a'
During a `--create' operation, enables automatic compressed format
recognition based on the archive suffix. The effect of this
option is cancelled by `--no-auto-compress'. gzip.
`--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. backup.
`--block-number'
`-R'
With this option present, `tar' prints error messages for read
errors with the block number in the archive file.
block-number.
`--blocking-factor=BLOCKING'
`-b BLOCKING'
Sets the blocking factor `tar' uses to BLOCKING x 512 bytes per
record. Blocking Factor.
`--bzip2'
`-j'
This option tells `tar' to read or write archives through `bzip2'.
gzip.
`--check-device'
Check device numbers when creating a list of modified files for
incremental archiving. This is the default. device
numbers, for a detailed description.
`--checkpoint[=NUMBER]'
This option directs `tar' to print periodic checkpoint messages as
it reads through the archive. It is intended for when you want a
visual indication that `tar' is still running, but don't want to
see `--verbose' output. You can also instruct `tar' to execute a
list of actions on each checkpoint, see `--checkpoint-action'
below. For a detailed description, see checkpoints.
`--checkpoint-action=ACTION'
Instruct `tar' to execute an action upon hitting a breakpoint.
Here we give only a brief outline. checkpoints, for a
complete description.
The ACTION argument can be one of the following:
bell
Produce an audible bell on the console.
dot
.
Print a single dot on the standard listing stream.
echo
Display a textual message on the standard error, with the
status and number of the checkpoint. This is the default.
echo=STRING
Display STRING on the standard error. Before output, the
string is subject to meta-character expansion.
exec=COMMAND
Execute the given COMMAND.
sleep=TIME
Wait for TIME seconds.
ttyout=STRING
Output STRING on the current console (`/dev/tty').
Several `--checkpoint-action' options can be specified. The
supplied actions will be executed in order of their appearance in
the command line.
Using `--checkpoint-action' without `--checkpoint' assumes default
checkpoint frequency of one checkpoint per 10 records.
`--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 (1).
hard links.
`--compress'
`--uncompress'
`-Z'
`tar' will use the `compress' program when reading or writing the
archive. This allows you to directly act on archives while saving
space. gzip.
`--confirmation'
(See `--interactive'.) interactive.
`--delay-directory-restore'
Delay setting modification times and permissions of extracted
directories until the end of extraction. Directory
Modification Times and Permissions.
`--dereference'
`-h'
When creating a `tar' archive, `tar' will archive the file that a
symbolic link points to, rather than archiving the symlink.
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.
directory.
`--exclude=PATTERN'
When performing operations, `tar' will skip files that match
PATTERN. exclude.
`--exclude-backups'
Exclude backup and lock files. exclude-backups exclude.
`--exclude-from=FILE'
`-X FILE'
Similar to `--exclude', except `tar' will use the list of patterns
in the file FILE. exclude.
`--exclude-caches'
Exclude from dump any directory containing a valid cache directory
tag file, but still dump the directory node and the tag file
itself.
exclude-caches exclude.
`--exclude-caches-under'
Exclude from dump any directory containing a valid cache directory
tag file, but still dump the directory node itself.
exclude.
`--exclude-caches-all'
Exclude from dump any directory containing a valid cache directory
tag file. exclude.
`--exclude-tag=FILE'
Exclude from dump any directory containing file named FILE, but
dump the directory node and FILE itself. exclude-tag
exclude.
`--exclude-tag-under=FILE'
Exclude from dump the contents of any directory containing file
named FILE, but dump the directory node itself.
exclude-tag-under exclude.
`--exclude-tag-all=FILE'
Exclude from dump any directory containing file named FILE.
exclude-tag-all exclude.
`--exclude-vcs'
Exclude from dump directories and files, that are internal for some
widely used version control systems.
exclude-vcs 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.
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. files.
`--force-local'
Forces `tar' to interpret the file name given to `--file' as a
local file, even if it looks like a remote tape drive name.
local and remote archives.
`--format=FORMAT'
`-H 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.
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. override.
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. gzip.
`--hard-dereference'
When creating an archive, dereference hard links and store the
files they refer to, instead of creating usual hard link members.
hard links.
`--help'
`-?'
`tar' will print out a short message summarizing the operations and
options to `tar' and exit. help.
`--ignore-case'
Ignore case when matching member or file names with patterns.
controlling pattern-matching.
`--ignore-command-error'
Ignore exit codes of subprocesses. Writing to an External
Program.
`--ignore-failed-read'
Do not exit unsuccessfully merely because an unreadable file was
encountered. Reading.
`--ignore-zeros'
`-i'
With this option, `tar' will ignore zeroed blocks in the archive,
which normally signals EOF. Reading.
`--incremental'
`-G'
Informs `tar' that it is working with an old GNU-format
incremental backup archive. It is intended primarily for
backwards compatibility only. Incremental Dumps, for a
detailed discussion of incremental archives.
`--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. 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. 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. Return error if such files exist. See also
--skip-old-files.
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. Tape Files.
`--level=N'
Force incremental backup of level N. As of GNU `tar' version
1.23, the option `--level=0' truncates the snapshot file, thereby
forcing the level 0 dump. Other values of N are effectively
ignored. --level=0, for details and examples.
The use of this option is valid only in conjunction with the
`--listed-incremental' option. Incremental Dumps, for a
detailed description.
`--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. Incremental Dumps.
`--lzip'
This option tells `tar' to read or write archives through `lzip'.
gzip.
`--lzma'
This option tells `tar' to read or write archives through `lzma'.
gzip.
`--lzop'
This option tells `tar' to read or write archives through `lzop'.
gzip.
`--mode=PERMISSIONS'
When adding files to an archive, `tar' will use PERMISSIONS for
the archive members, rather than the permissions from the files.
PERMISSIONS can be specified either as an octal number or as
symbolic permissions, like with `chmod'. override.
`--mtime=DATE'
When adding files to an archive, `tar' will use DATE as the
modification time of members when creating archives, instead of
their actual modification times. The value of DATE can be either
a textual date representation ( Date input formats) or a
name of the existing file, starting with `/' or `.'. In the
latter case, the modification time of that file is used.
override.
`--multi-volume'
`-M'
Informs `tar' that it should create or otherwise operate on a
multi-volume `tar' archive. Using Multiple Tapes.
`--new-volume-script'
(see `--info-script')
`--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. 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). after.
`--no-acls'
Causes `tar' not to store and not to extract ACL's.
Attributes.
`--no-anchored'
An exclude pattern can match any subsequence of the name's
components. controlling pattern-matching.
`--no-auto-compress'
Disables automatic compressed format recognition based on the
archive suffix. --auto-compress. gzip.
`--no-check-device'
Do not check device numbers when creating a list of modified files
for incremental archiving. device numbers, for a detailed
description.
`--no-delay-directory-restore'
Modification times and permissions of extracted directories are
set when all files from this directory have been extracted. This
is the default. Directory Modification Times and
Permissions.
`--no-ignore-case'
Use case-sensitive matching. controlling pattern-matching.
`--no-ignore-command-error'
Print warnings about subprocesses that terminated with a nonzero
exit code. Writing to an External Program.
`--no-null'
If the `--null' option was given previously, this option cancels
its effect, so that any following `--files-from' options will
expect their file lists to be newline-terminated.
`--no-overwrite-dir'
Preserve metadata of existing directories when extracting files
from an archive. Overwrite Old Files.
`--no-quote-chars=STRING'
Remove characters listed in STRING from the list of quoted
characters set by the previous `--quote-chars' option (
quoting styles).
`--no-recursion'
With this option, `tar' will not recurse into directories.
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.
`--no-seek'
The archive media does not support seeks to arbitrary locations.
Usually `tar' determines automatically whether the archive can be
seeked or not. Use this option to disable this mechanism.
`--no-selinux'
Causes `tar' not to store and not to extract SELinux security
context. Attributes.
`--no-unquote'
Treat all input file or member names literally, do not interpret
escape sequences. input name quoting.
`--no-xattrs'
Causes `tar' not to store and not to extract xattrs. This option
also enables `--no-selinux' and `--no-acls'. Attributes.
`--no-wildcards'
Do not use wildcards. controlling pattern-matching.
`--no-wildcards-match-slash'
Wildcards do not match `/'. controlling pattern-matching.
`--null'
When `tar' is using the `--files-from' option, this option
instructs `tar' to expect file names terminated with NUL, so `tar'
can correctly work with file names that contain newlines.
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.
Attributes.
`-o'
The function of this option depends on the action `tar' is
performing. When extracting files, `-o' is a synonym for
`--no-same-owner', i.e., it prevents `tar' from restoring
ownership of files being extracted.
When creating an archive, it is a synonym for `--old-archive'.
This behavior is for compatibility with previous versions of GNU
`tar', and will be removed in future releases.
Changes, for more information.
`--occurrence[=NUMBER]'
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 the member `filename' from
`archive.tar' and will terminate without scanning to the end of
the archive.
`--old-archive'
Synonym for `--format=v7'.
`--one-file-system'
Used when creating an archive. Prevents `tar' from recursing into
directories that are on different file systems from the current
directory.
`--overwrite'
Overwrite existing files and directory metadata when extracting
files from an archive. Overwrite Old Files.
`--overwrite-dir'
Overwrite the metadata of existing directories when extracting
files from an archive. 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.
override.
This option does not affect extraction from archives.
`--pax-option=KEYWORD-LIST'
This option enables creation of the archive in POSIX.1-2001 format
( posix) and modifies the way `tar' handles the extended
header keywords. KEYWORD-LIST is a comma-separated list of
keyword options. PAX keywords, for a detailed discussion.
`--portability'
`--old-archive'
Synonym for `--format=v7'.
`--posix'
Same as `--format=posix'.
`--preserve'
Synonymous with specifying both `--preserve-permissions' and
`--same-order'. Setting Access Permissions.
`--preserve-order'
(See `--same-order'; Reading.)
`--preserve-permissions'
`--same-permissions'
`-p'
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. Setting Access
Permissions.
`--quote-chars=STRING'
Always quote characters from STRING, even if the selected quoting
style would not quote them ( quoting styles).
`--quoting-style=STYLE'
Set quoting style to use when printing member and file names
( quoting styles). Valid STYLE values are: `literal',
`shell', `shell-always', `c', `escape', `locale', and `clocale'.
Default quoting style is `escape', unless overridden while
configuring the package.
`--read-full-records'
`-B'
Specifies that `tar' should reblock its input, for reading from
pipes on systems with buggy implementations. Reading.
`--record-size=SIZE'
Instructs `tar' to use SIZE bytes per record when accessing the
archive. Blocking Factor.
`--recursion'
With this option, `tar' recurses into directories (default).
recurse.
`--recursive-unlink'
Remove existing directory hierarchies before extracting
directories of the same name from the archive. Recursive
Unlink.
`--remove-files'
Directs `tar' to remove the source file from the file system after
appending it to an archive. remove files.
`--restrict'
Disable use of some potentially harmful `tar' options. Currently
this option disables shell invocation from multi-volume menu
( Using Multiple Tapes).
`--rmt-command=CMD'
Notifies `tar' that it should use CMD instead of the default
`/usr/libexec/rmt' ( Remote Tape Server).
`--rsh-command=CMD'
Notifies `tar' that is should use CMD to communicate with remote
devices. 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. 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. Attributes.
`--same-permissions'
(See `--preserve-permissions'; Setting Access Permissions.)
`--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. It takes effect only if the
archive is open for reading (e.g. with `--list' or `--extract'
options).
`--selinux'
Causes `tar' to store SElinux security context.
Attributes.
`--show-defaults'
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
Notice, that this option outputs only one line. The example output
above has been split to fit page boundaries.
`--show-omitted-dirs'
Instructs `tar' to mention the directories it is skipping when
operating on a `tar' archive. show-omitted-dirs.
`--show-transformed-names'
`--show-stored-names'
Display file or member names after applying any transformations
( transform). In particular, when used in conjunction with
one of the archive creation operations it instructs `tar' to list
the member names stored in the archive, as opposed to the actual
file names. listing member and file names.
`--skip-old-files'
Do not overwrite existing files when extracting files from an
archive. Keep Old Files.
This option differs from `--keep-old-files' in that it does not
treat such files as an error, instead it just silently avoids
overwriting them.
The `--warning=existing-file' option can be used together with
this option to produce warning messages about existing old files
( warnings).
`--sparse'
`-S'
Invokes a GNU extension when adding files to an archive that
handles sparse files efficiently. sparse.
`--sparse-version=VERSION'
Specifies the "format version" to use when archiving sparse files.
Implies `--sparse'. sparse. For the description of the
supported sparse formats, Sparse Formats.
`--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.
Scarce.
`--strip-components=NUMBER'
Strip given NUMBER of leading components from file names before
extraction. For example, if archive `archive.tar' contained
`/some/file/name', then running
tar --extract --file archive.tar --strip-components=2
would extract this file to file `name'.
`--suffix=SUFFIX'
Alters the suffix `tar' uses when backing up files from the default
`~'. backup.
`--tape-length=NUM'
`-L NUM'
Specifies the length of tapes that `tar' is writing as being
NUM x 1024 bytes long. Using Multiple Tapes.
`--test-label'
Reads the volume label. If an argument is specified, test whether
it matches the volume label. --test-label option.
`--to-command=COMMAND'
During extraction `tar' will pipe extracted files to the standard
input of COMMAND. Writing to an External Program.
`--to-stdout'
`-O'
During extraction, `tar' will extract files to stdout rather than
to the file system. Writing to Standard Output.
`--totals[=SIGNO]'
Displays the total number of bytes transferred when processing an
archive. If an argument is given, these data are displayed on
request, when signal SIGNO is delivered to `tar'. totals.
`--touch'
`-m'
Sets the data modification time of extracted files to the
extraction time, rather than the data modification time stored in
the archive. Data Modification Times.
`--transform=SED-EXPR'
`--xform=SED-EXPR'
Transform file or member names using `sed' replacement expression
SED-EXPR. For example,
$ tar cf archive.tar --transform 's,^\./,usr/,' .
will add to `archive' files from the current working directory,
replacing initial `./' prefix with `usr/'. For the detailed
discussion, transform.
To see transformed member names in verbose listings, use
`--show-transformed-names' option ( show-transformed-names).
`--uncompress'
(See `--compress'. gzip)
`--ungzip'
(See `--gzip'. gzip)
`--unlink-first'
`-U'
Directs `tar' to remove the corresponding file from the file
system before extracting it from the archive. Unlink
First.
`--unquote'
Enable unquoting input file or member names (default).
input name quoting.
`--use-compress-program=PROG'
`-I=PROG'
Instructs `tar' to access the archive through PROG, which is
presumed to be a compression program of some sort. gzip.
`--utc'
Display file modification dates in UTC. This option implies
`--verbose'.
`--verbose'
`-v'
Specifies that `tar' should be more verbose about the operations
it is performing. This option can be specified multiple times for
some operations to increase the amount of information displayed.
verbose.
`--verify'
`-W'
Verifies that the archive was correctly written when creating an
archive. verify.
`--version'
Print information about the program's name, version, origin and
legal status, all on standard output, and then exit successfully.
help.
`--volno-file=FILE'
Used in conjunction with `--multi-volume'. `tar' will keep track
of which volume of a multi-volume archive it is working in FILE.
volno-file.
`--warning=KEYWORD'
Enable or disable warning messages identified by KEYWORD. The
messages are suppressed if KEYWORD is prefixed with `no-'.
warnings.
`--xattrs'
Causes `tar' to store xattrs. This option also enables `--selinux'
and `--acls'. Attributes.
`--wildcards'
Use wildcards when matching member names with patterns.
controlling pattern-matching.
`--wildcards-match-slash'
Wildcards match `/'. controlling pattern-matching.
`--xz'
`-J'
Use `xz' for compressing or decompressing the archives.
gzip.
---------- Footnotes ----------
(1) Earlier versions of GNU `tar' understood `-l' as a synonym for
`--one-file-system'. The current semantics, which complies to UNIX98,
was introduced with version 1.15.91. Changes, for more
information.
Info Catalog
(tar.info.gz) Operation Summary
(tar.info.gz) All Options
(tar.info.gz) Short Option Summary
automatically generated by
info2html