TAR(1)

Option styles

Options to GNU tar can be given in three different styles. In traditional style, the first argument is a cluster of option letters and all subsequent arguments supply parameters to those options that require them. The arguments are read in the same order as the option letters. Any command line words that remain after all options have been processed are treated as non-optional arguments: file or archive member names.

For example, the c option requires creating the archive, the v option requests verbose output, and the f option takes an argument that sets the name of the archive. The following command, written in traditional style, instructs tar to store all files from the directory /etc into the archive file etc.tar while listing the files being archived:

tar cfv etc.tar /etc

In UNIX (short-option) style, each option letter is prefixed with a single dash, as in other command-line utilities. If an option takes an argument, the argument follows it, either as a separate word or immediately after the option. However, if the option takes an optional argument, it must follow the option letter without any intervening whitespace, as in -g/tmp/snar.db.

Any number of options not taking arguments can be clustered together after a single dash (e.g. -vkp). Options that take arguments (whether mandatory or optional) can appear at the end of such a cluster (e.g. -vkpf a.tar).

The example command above written in short-option style could look like:

    tar -cvf etc.tar /etc
    tar -c -v -f etc.tar /etc
  

In GNU (long-option) style, each option begins with two dashes and has a meaningful name consisting of lowercase letters and dashes. Long options can be abbreviated to their initial letters, provided this does not create ambiguity. Arguments to long options are supplied either as a separate command-line word or separated from the option by an equals sign with no intervening whitespace. Optional arguments must always use the latter method.

Here are several ways of writing the example command in this style:

    tar --create --file etc.tar --verbose /etc
    tar --cre --file=etc.tar --verb /etc
  

The options in all three styles can be intermixed, although doing so with traditional options is not encouraged.

Operation mode

The options listed in the table below tell GNU tar what operation it is to perform. Exactly one of them must be given. Meaning of non-optional arguments depends on the operation mode requested.

-A, --catenate, --concatenate

Append archives to the end of another archive. The arguments are treated as names of archives to append. All archives must be of the same format as the target archive, otherwise the result may be unusable with non-GNU tar. When multiple archives are given, members from all but the first are only accessible when using -i (--ignore-zeros).

Compressed archives cannot be concatenated.

-c, --create

Create a new archive. Arguments specify the files to include. Directories are archived recursively unless --no-recursion is used.

-d, --diff, --compare

Find differences between the archive and the file system. Arguments are optional and specify archive members to compare. If omitted, the current directory is used.

--delete

Delete members from the archive. Arguments specify the names of members to remove. At least one argument is required.

This option does not work on compressed archives. No short option exists.

-r, --append

Append files to the end of an archive. Arguments behave the same as for -c (--create).

-t, --list

List archive contents. Arguments are optional and specify which members to list.

--test-label

Test the archive volume label and exit. Without arguments, prints the label (if any) and exits with status 0. With arguments, compares the label against each one and exits with 0 if a match is found, otherwise 1. No output is shown unless used with -v (--verbose).

No short option exists.

-u, --update

Append files that are newer than their archived versions. Arguments are the same as for -c and -r. Newer files do not replace old ones; they are appended, so multiple versions of the same file may exist.

-x, --extract, --get

Extract files from an archive. Arguments are optional and specify which members to extract.

--show-defaults

Show built-in defaults for various tar options and exit. No arguments allowed.

-?, --help

Display a short help summary and exit. No arguments allowed.

--usage

Display a list of available options and exit. No arguments allowed.

--version

Print version and copyright information and exit.

Operation modifiers

--check-device

Check device numbers when creating incremental archives (default).

-g, --listed-incremental=FILE

Handle new GNU-format incremental backups. FILE is a snapshot file used to store metadata about changed files since the last dump.

If FILE does not exist, it is created and all files are archived (level 0 dump). For incremental level N, use a copy of the snapshot file from level N−1.

When listing or extracting, the contents of FILE are not used; it is only required syntactically. Common practice is to use /dev/null.

--hole-detection=METHOD

Detect holes in sparse files using METHOD. Implies --sparse. Valid values are seek (default) and raw, with automatic fallback.

-G, --incremental

Handle old GNU-format incremental backups.

--ignore-failed-read

Do not exit with a nonzero status on unreadable files.

--level=NUMBER

Set dump level for listed-incremental archives. Currently only --level=0 is meaningful; it truncates the snapshot file, forcing a full (level 0) dump.

-n, --seek

Assume the archive is seekable. Normally detected automatically. This option is useful when detection fails and applies only when reading archives (e.g. with --list or --extract).

--no-check-device

Do not check device numbers when creating incremental archives.

--no-seek

Assume the archive is not seekable.

--occurrence[=N]

Process only the Nth occurrence of each file in the archive. Valid only with --delete, --diff, --extract, or --list, and when a file list is provided (via command line or -T). Default is 1.

--restrict

Disable the use of some potentially harmful options.

--sparse-version=MAJOR[.MINOR]

Set the sparse file format version (implies --sparse). Valid values are 0.0, 0.1, and 1.0. See the GNU Tar manual, appendix “Sparse Formats” for details.

-S, --sparse

Handle sparse files efficiently. Detects files with unwritten (empty) regions and avoids storing those regions in the archive, reducing size.

Overwrite control

-k, --keep-old-files

Don't replace existing files when extracting.

--keep-newer-files

Don't replace existing files that are newer than their archive copies.

--keep-directory-symlink

Don't replace existing symlinks to directories when extracting.

--no-overwrite-dir

Preserve metadata of existing directories.

--one-top-level[=DIR]

Extract all files into DIR, or, if used without argument, into a subdirectory named by the base name of the archive (minus standard compression suffixes recognizable by --auto-compress).

--overwrite

Overwrite existing files when extracting.

--overwrite-dir

Overwrite metadata of existing directories when extracting (default).

--recursive-unlink

Recursively remove all files in the directory prior to extracting it.

--remove-files

Remove files from disk after adding them to the archive.

--skip-old-files

Don't replace existing files when extracting, silently skip over them.

-U, --unlink-first

Remove each file prior to extracting over it.

-W, --verify

Verify the archive after writing it.

Output stream selection

--ignore-command-error

Ignore subprocess exit codes.

--no-ignore-command-error

Treat non-zero exit codes of children as error (default).

-O, --to-stdout

Extract files to standard output.

--to-command=COMMAND

Pipe extracted files to COMMAND. The argument is the pathname of an external program, optionally with command line arguments. The program will be invoked and the contents of the file being extracted supplied to it on its standard input. Additional data will be supplied via the following environment variables:

TAR_FILETYPE

Type of the file.

f

Regular file

d

Directory

l

Symbolic link

h

Hard link

b

Block device

c

Character device

Currently only regular files are supported.

TAR_MODE

File mode, an octal number.

TAR_FILENAME

The name of the file.

TAR_REALNAME

Name of the file as stored in the archive.

TAR_UNAME

Name of the file owner.

TAR_GNAME

Name of the file owner group.

TAR_ATIME

Time of last access. It is a decimal number, representing seconds since the Epoch. If the archive provides times with nanosecond precision, the nanoseconds are appended to the timestamp after a decimal point.

TAR_MTIME

Time of last modification.

TAR_CTIME

Time of last status change.

TAR_SIZE

Size of the file.

TAR_UID

UID of the file owner.

TAR_GID

GID of the file owner.

Additional tar variables

Additionally, the following variables contain information about tar operation mode and the archive being processed:

TAR_VERSION

GNU tar version number.

TAR_ARCHIVE

The name of the archive tar is processing.

TAR_BLOCKING_FACTOR

Current blocking factor, i.e. number of 512-byte blocks in a record.

TAR_VOLUME

Ordinal number of the volume tar is processing (set if reading a multi-volume archive).

TAR_FORMAT

Format of the archive being processed. One of: gnu, oldgnu, posix, ustar, v7.

TAR_SUBCOMMAND

A short option (with a leading dash) describing the operation tar is executing.

Size suffixes