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. See absolute.

--after-date

(See --newer, see after)

--anchored

A pattern must match an initial subsequence of the name's components. See 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 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[=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. For a detailed description, see Progress information.

--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 ¹.

--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. See gzip.

--confirmation

(See --interactive.) See interactive.

--delay-directory-restore

Delay setting modification times and permissions of extracted directories until the end of extraction. See 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. 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.

--exclude-tag=file

Exclude all directories, containing file named file. 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

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

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. See 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. See gzip.

--help

-?

tar will print out a short message summarizing the operations and options to tar and exit. See help.

--ignore-case

Ignore case when matching member or file names with patterns. See controlling pattern-matching.

--ignore-command-error

Ignore exit codes of subprocesses. See Writing to an External Program.

--ignore-failed-read

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. See 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. 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. See Incremental Dumps.

--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. See 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 (see 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. See override.

--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). See after.

--no-anchored

An exclude pattern can match any subsequence of the name's components. See controlling pattern-matching.

--no-delay-directory-restore

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.

--no-ignore-case

Use case-sensitive matching. See controlling pattern-matching.

--no-ignore-command-error

Print warnings about subprocesses terminated with a non-zero exit code. See Writing to an External Program.

--no-overwrite-dir

Preserve metadata of existing directories when extracting files from an archive. See 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 (see quoting styles).

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

--no-unquote

Treat all input file or member names literally, do not interpret escape sequences. See input name quoting.

--no-wildcards

Do not use wildcards. See controlling pattern-matching.

--no-wildcards-match-slash

Wildcards do not match ‘/’. See controlling pattern-matching.

--null

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

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 the future releases.

See 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. 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. See override.

This option does not affect extraction from archives.

--transform=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, See transform.

To see transformed member names in verbose listings, use --show-transformed-names option (see show-transformed-names).

--quote-chars=string

Always quote characters from string, even if the selected quoting style would not quote them (see quoting styles).

--quoting-style=style

Set quoting style to use when printing member and file names (see 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.

--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. See 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. See Setting Access Permissions.

--preserve-order

(See --same-order; see 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. 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 invocation 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.

--same-permissions

(See --preserve-permissions; see Setting Access Permissions.)

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

--show-omitted-dirs

Instructs tar to mention directories its skipping over when operating on a tar archive. See show-omitted-dirs.

--show-transformed-names

--show-stored-names

Display file or member names after applying any transformations (see transform). In particular, 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.

--sparse-version=version

Specified the format version to use when archiving sparse files. Implies --sparse. See sparse. For the description of the supported sparse formats, See 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. See 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.

, summary

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

--to-command=command

During extraction tar will pipe extracted files to the standard input of command. See Writing to an External Program.

--to-stdout

-O

During extraction, tar will extract files to stdout rather than to the file system. See 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. See 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. See Data Modification Times.

--uncompress

(See --compress. see gzip)

--ungzip

(See --gzip. see gzip)

--unlink-first

-U

Directs tar to remove the corresponding file from the file system before extracting it from the archive. See Unlink First.

--unquote

Enable unquoting input file or member names (default). See input name quoting.

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

--wildcards

Use wildcards when matching member names with patterns. See controlling pattern-matching.

--wildcards-match-slash

Wildcards match ‘/’. See controlling pattern-matching.