Linux Command

Linux tar command

About tar

The tar program is used to create, maintain, modify, and extract files that are archived in the tar format.

Syntax

tar [-] A --catenate --concatenate | c --create | d --diff --compare | 
    --delete | r --append | t --list | --test-label | u --update | 
    x --extract --get [options] [pathname ...]

Description

"tar" stands for tape archive. It is an archiving file format.

tar was originally developed in the early days of Unix for the purpose of backing up files to tape-based storage devices. It was later formalized as part of the POSIX standard, and today is used to collect, distribute, and archive files, while preserving file system attributes such as user and group permissions, access and modification dates, and directory structures.

This documentation covers the GNU version of tar, which is included with most modern variants of the Linux operating system.

Operation

The first argument to tar should be a function specification: either one of the letters A, c, d, r, t, u, or x, or one of the long function names. A function letter does not need to be prefixed with a dash ("-"), and may be combined with other single-letter options. A long function name must be prefixed with a double dash ("--"). 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 "=value" to the option.

For example, the following commands are all equivalent:

tar --create --file=archive.tar file1 file2

tar -c -f archive.tar file1 file2

tar -cf archive.tar file1 file2

tar cf archive.tar file1 file2

Functions

Specifying one of the following functions selects what tar's main mode of operation will be:

A, --catenate, --concatenate	Append tar files to an archive.
c, --create	Create a new archive.
d, --diff, --compare	Calculate any differences between the archive and the file system.
--delete	Delete from the archive. (This function doesn't work on magnetic tapes).
r, --append	Append files to the end of a tar archive.
t, --list	List the contents of an archive.
--test-label	Test the archive label, and exit.
u, --update	Append files, but only those that are newer than the copy in the archive.
x, --extract, --get	Extract files from an archive.

Other Options

The following options specify the way tar operates:

-[0-7][lmh]	Specifies drive and density. (If you're not sure what this means, you don't need to use this option.)
-a, --auto-compress	Use the archive's suffix to determine the compression program. For example, if this option is specified, an archive with the extension .tar.gz will always be handled as if the --gzip option had been specified (see --gzip, below).
--add-file=file	Add file to the archive. (This option is especially useful when the name of the file begins with a dash.)
--anchored	Filename patterns must match from the begining of a file name.
--no-anchored	Filename patterns may match after any "/" (this is the default for excluding files; see --exclude, below).
--atime-preserve	Preserve access times on archived files, either by restoring the times, or (if the operating system sypports it) not changing them in the first place.
--no-auto-compress	Do not automatically determine the compression program using the archive filename suffix.
-b, --blocking-factor BLOCKS	Use BLOCKS x 512 bytes-per-record when handling the archive.
-B, --read-full-records	"Re-block" all input. This option can help read damaged archives.
--backup[=backup-method	Rather than deleting files from the file system, tar will back them up using the specified backup method backup-method, which may be one of the following: t, numbered Always make numbered backups. nil, existing Make numbered backups of files that already have them, and simple backups of the others. never, simple Always make simple backups. If not specified, backup-method defaults to the value of environment variable VERSION_CONTROL; if VERSION_CONTROL is undefined, backup-method defaults to existing.
-C, --directory DIR	Change to directory DIR before performing any operations.
--check-device	check device numbers when creating incremental archives. This is the default behavior.
--no-check-device	Do not check device numbers when creating incremental archives.
--checkpoint[=NUMBER]	Use "checkpoints": display a progress message every NUMBER records (default 10).
--checkpoint-action=ACTION	Execute ACTION at every checkpoint. ACTION may be one of the following: bell Play an audible bell at the console. dot, . Print a single dot. echo Display a text message at the console (to standard error). echo=string Display string string on standard error; before output, any metacharacters in string are expanded. 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 the order of their appearance on the command line. Using --checkpoint-action without --checkpoint will assume the default checkpoint interval of 10 records.
--delay-directory-restore	Delay setting modification times and permissions of extracted directories until the end of extraction.
--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.
--exclude=PATTERN	Avoid operating on files whose names match filename pattern PATTERN.
--exclude-backups	exclude backup and lock files from all operations.
--exclude-caches	Causes tar to exclude all directories that contain a cache directory tag. A cache directory tag is a short file with the name CACHEDIR.TAG and having a standard header specified in http://www.brynosaurus.com/cachedir/spec.html. This option excludes the contents of the directory, but archives the directory itself and the CACHEDIR.TAG file.
--exclude-caches-all	Omit directories containing a CACHEDIR.TAG file entirely.
--exclude-caches-under	Exclude everything under directories containing a CACHEDIR.TAG file, including the CACHEDIR.TAG file; but, archive the directory.
--exclude-tag=FILE	Exclude the contents of any directory containing file FILE, but archive the directory and the file FILE.
--exclude-tag-all=FILE	Omit directories containing file FILE entirely.
--exclude-tag-under=FILE	Exclude everything under directories containing file FILE including the file FILE; but, archive the directory.
--exclude-vcs	Exclude version control subdirectories. This option recognizes the files and directories used by many widely-used VCSs. The files excluded are: CVS/, and everything under it RCS/, and everything under it SCCS/, and everything under it .git/, and everything under it .gitignore .cvsignore .svn/, and everything under it .arch-ids/, and everything under it {arch}/, and everything under it =RELEASE-ID =meta-update =update .bzr .bzrignore .bzrtags .hg .hgignore .hgrags _darcs
-f, --file=ARCHIVE	Use archive file (or device) ARCHIVE.
-F, --info-script, --new-volume-script=NAME	run script NAME at the end of each tape (implies -M).
--force-local	Force tar to treat the archive file as a local file, even if its name contains a colon.
--full-time	Print the full resolution of all file times.
-g, --listed-incremental=FILE	During a --create operation, this option specifies that the archive be a new GNU-format incremental backup, using snapshot file FILE to determine which files to backup. With other operations, this option informs tar that the archive is in incremental format.
-G, --incremental	Handle old GNU-format incremental backups.
--group=NAME	Force NAME as group for added files.
-h, --dereference	Follow symlinks; archive the files they point to.
-H, --format=FORMAT	Create archive of the given format, where FORMAT is one of the following: gnu GNU tar 1.13.x format oldgnu GNU format used in tar versions 1.12 and lower pax POSIX 1003.1-2001 ("pax") format posix Same as pax ustar POSIX 1003.1-1988 ("ustar") format v7 old Unix Version 7 tar format
--hard-dereference	Follow hard links; archive the files they refer to.
-i, --ignore-zeros	Ignore zeroed blocks in archive. Normally an entire block of bytes with a value of zero indicates an end-of-archive; this option helps tar handle a damaged archive, or any other oddly-formed archive with blocks of zeros in its contents.
-I, --use-compress-program=PROG	Use external compression program PROG. Use this option if you are not happy with the compression program associated with the suffix at compile time, or if you have a compression program that GNU tar does not support. The PROG argument must be a valid command, as you would type it at the command line prompt, with any additional options as needed. Enclose it in quotes if it contains white space. PROG should follow two conventions: First, when invoked without additional options, it should read data from standard input, compress it and output it on standard output. Secondly, if invoked with the additional '-d' option, it should do exactly the opposite: read the compressed data from the standard input and produce uncompressed data on the standard output. The latter requirement means that you must not use the '-d' option as a part of the PROG command invocation itself.
--ignore-case	Ignore character case when matching patterns or file names.
--no-ignore-case	Use case-sensitive pattern and filename matching (this is the default).
--ignore-command-error	Ignore exit codes of subprocesses.
--no-ignore-command-error	Treat non-zero exit codes of subprocesses as an error.
--ignore-failed-read	Do not exit merely because an unreadable file was encountered.
--index-file=FILE	Send verbose output to file FILE for later use.
-j, --bzip2	This option tells tar to read or write archives using the bzip2 compressor.
-J, --xz	Tells tar to read or write archives using the xz compressor.
-k, --keep-old-files	Do not overwrite existing files when extracting files from an archive, and return an error if such files exist.
-K, --starting-file=NAME	This option affects extraction only; tar will skip extracting files in the archive until it finds one that matches name.
--keep-newer-files	Don't replace existing files that are newer than their archive copies.
-l, --check-links	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, print a warning message.
-L, --tape-length=size[suf]	Change tape after writing a certain number of bytes. If suf is not specified, SIZE is treated as a number of kilobytes (1024 bytes), which is equivalent to specifying suf as B. suf may be one of the following: suffix units byte equivalent b Blocks size x 512 B Kilobytes size x 1024 c Bytes size G Gigabytes size x 1024^3 K Kilobytes size x 1024 k Kilobytes size x 1024 M Megabytes size x 1024^2 P Petabytes size x 1024^5 T Terabytes size x 1024^4 w Words size x 2
--level=n	When using the --listed-incremental option, force an incremental backup of level n.
--lzip	Read or write archives through the lzip compressor.
--lzma	Read or write archives through the lzma compressor.
--lzop	Read or write archives through the lzop compressor.
-m, --touch	Sets the data modification time of extracted files to the extraction time, rather than the data modification time stored in the archive. In other words, touch all extracted files.
-M, --multi-volume	Create, list, or extract a multi-volume archive. Such archives are broken into parts so that they may fit on media too small to contain the entire archive.
--mode=permissions	When adding files to an archive, tar will assign permissions to the archive members, rather than the permissions from the files. permissions can be specified either as an octal number or as symbolic permissions, as with chmod.
--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 or a name of the existing file, starting with "/" or ".", in which case the modification time of that file is used.
-n, --seek	Assume that the archive media supports seeking 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 with "--list" or "--extract" options).
-N, --newer, --after-date=date	Only store files whose data or status has changed on or after date. If date is a filename, the date of that file is used.
--newer-mtime=date	Like --after-time, but looks at modification times only.
--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.
--no-null	Cancels any previous --null option specified.
--numeric-owner	Always use numberic IDs, rather than names, for user/group ownership information.
-O, --to-stdout	Extract files to standard output.
--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, --portability	Same as "--format=v7".
--one-file-system	Prevents tar from crossing file system boundaries when archiving. Can be used with any write operation.
--overwrite	Overwrite existing files when extracting.
--overwrite-dir	Overwrite metadata of existing directories when extracting (this is the default behavior).
--no-overwrite-dir	Preserve metadata of existing directories when extracting.
--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 can be a username, or a user's numeric ID, or both as "name:id".
-p, --preserve-permissions, --same-permissions	When tar is extracting an archive, it normally subtracts the user's 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.
-P, --absolute-names	Don't strip leading "/"s from file names.
--pax-option=keyword-list	Enables creation of the archive in POSIX.1-2001 format, where keyword-list is a comma-separated list of keyword options specific to that format.
--posix	Same as --format=posix.
--preserve	This is the same as specifying both "--preserve-permissions" and "--same-order".
--quote-chars=STRING	When displaying files and other members of an archive, tar treats file names in a special way to avoid ambiguities caused by certain characters that may occur in the filename; this is called name quoting. The --quote-chars option will, additionally, quote any characters occurring in STRING.
--no-quote-chars=STRING	When name quoting, tar will never quote any of the characters in STRING.
--quoting-style=STYLE	When name quoting, use name quoting style STYLE. Valid values of STYLE are: literal, shell, shell-always, c, escape, locale, and clocale. The default quoting style is escape, unless overridden while configuring the package.
-R, --block-number	With this option specified, tar prints error messages for read errors with the block number in the archive file.
--record-size=siz[suf]	Instructs tar to use size bytes-per-record when accessing the archive. The argument can be suffixed with a size suffix, e.g. "--record-size=10K" for 10 Kilobytes.
--recursion	Recurse into directories (this is the default).
--no-recursion	Do not recurse into subdirectories when archiving.
--recursive-unlink	Remove existing directory hierarchies before extracting directories of the same name from the archive.
--remove-files	Remove files after adding them to an archive.
--restrict	Disable use of some potentially harmful tar options. Currently this option disables shell invocation.
--rmt-command=cmd	In cases where tar is using a remote tape server, this option notifies tar that it should use cmd as the remote tape server program instead of the default, "/usr/libexec/rmt".
--rsh-command=cmd	In cases where tar is using a remote shell to communicate with non-local devices, this option notifies tar that it should use cmd instead of the default, rsh.
-s, --preserve-order, --same-order	This option helps when processing large lists of file names on machines with small amounts of memory. It is used in conjunction with --compare, --list or --extract. The --same-order option tells tar that the list of file names to be listed or extracted is sorted in the same order as the files in the archive. This allows a large list of names to be used, even on a small machine that would not otherwise be able to hold all the names in memory at the same time. Such a sorted list can easily be created by running tar -t on the archive and editing its output. This option is probably never needed on modern computer systems.
-S, --sparse	This option instructs tar to test each file for sparseness before attempting to archive it. If the file is found to be sparse it is treated specially, thus allowing to decrease the amount of space used by its image in the archive. This option is meaningful only when creating or updating archives. It has no effect on extraction.
--same-owner	Attempt to give extracted files the same ownership as exists in the archive (this is the default for superuser).
--no-same-owner	Do not attempt to restore ownership when extracting. This is the default behavior for ordinary users, so this option has an effect only for the superuser.
--no-same-permissions	Apply the user's umask when extracting permissions from the archive. This is the default behavior for ordinary users.
--no-seek	Do not attempt to seek to arbitrary locations within an archive.
--show-defaults	Display tar's default options. This can be useful in certain shell scripts.
--show-omitted-dirs	When listing or extracting, list each directory that does not match search criteria.
--show-transformed-names, --show-stored-names	Display file or member names after applying any name transformations. 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.
--sparse-version=version-number	Specifies the format version to use when archiving sparse files. Implies '--sparse'.
--strip-components=number	Strip given number of leading components from file names before extraction. For example, if archive "archive.tar" contained a member named "/some/file/name", then running: tar --extract --file archive.tar --strip-components=2 would extract this file to file "name".
--suffix=suffix	Uses the filename suffix suffix when backing up files. If --suffix is not specified, the default backup suffix is the value of the environment variable DEFAULT_BACKUP_SUFFIX, or if that variable is not defined, "~".
-T, --files-from=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.
--to-command=command	During extraction, tar will pipe extracted files to the standard input of command.
--totals[=signum]	Display byte totals when processing an archive. If signum is specified, these totals are displayed when tar receives signal number signum.
--transform, --xform=sed-expr	Replace filenames with sed replacement expression sed-expr. For example, tar cf archive.tar --transform 's,^\./,usr/,' will add to archive.tar files from the current working directory, replacing initial "./" prefix with "usr/".
-U, --unlink-first	Remove a corresponding file from the file system before extracting it from the archive, rather than simply overwriting it.
--unquote	Unquote filenames read in with -T; this is the default.
--no-unquote	Do not unquote filenames read in with -T.
--utc	Print all file times in UTC (universal time).
-v, --verbose	Operate verbosely.
-V, --label=name	When creating an archive, 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.
--volno-file=file	Used in conjunction with "--multi-volume", tar will keep track of which volume of a multi-volume archive it is working on in file file.
-w, --interactive, --confirmation	Ask for confirmation for every action.
-W, --verify	Attempt to verify the archive after writing it.
--warning=keyword	Control display of the warning messages identified by keyword. If keyword starts with the prefix "no-", such messages are suppressed. Otherwise, they are enabled. Multiple "--warning" specifications may be used. There are keywords for various warning messages available in tar. The two global keywords are: all Enable all warning messages. This is the default. none Disable all warning messages.
--wildcards	Use wildcards.
--wildcards-match-slash	When this option is specified, a wildcard like "*" in the pattern can match a "/" in the name. Otherwise, "/" is matched only by "/". This is the default when tar is excluding files.
--no-wildcards-match-slash	"/" can not be matched by a wildcard, only by "/".
--no-wildcards	Wildcards are not permitted. Filenames may only be matched verbatim.
-X, --exclude-from=file	Like --exclude, but excludes files matching the patterns listed in the file file.
-z, --gzip, --gunzip	This option tells tar to read or write archives through gzip, allowing tar to directly operate on several kinds of compressed archives transparently. This option should be used, for example, when operating on files with the extension .tar.gz.
-Z, --compress, --uncompress	tar will use the compress program when operating on files.

Environment

The following environment variables affect the operation of tar:

SIMPLE_BACKUP_SUFFIX	Filename suffix to use when backing up files, if --suffix is not specified. The default backup suffix is "~".
TAR_OPTIONS	Any options specified in this variable will be prepended to options specified to tar on the command line.
TAPE	The archiving tape or file to use if --file is not specified. If this variable is not defined, and no --file is specified, tar uses standard input and standard output instead.

Examples

tar cf archive.tar file1 file2

Create archive archive.tar containing files file1 and file2. Here, the c tells tar you will be creating an archive; the f tells tar that the next option (here it's archive.tar) will be the name of the archive it creates. file1 and file2, the final arguments, are the files to be archived.

tar tvf archive.tar

List the files in the archive archive.tar verbosely. Here, the t tells tar to list the contents of an archive; v tells tar to operate verbosely; and f indicates that the next argument will be the name of the archive file to operate on.

tar xf archive.tar

Extract the files from archive archive.tar. x tells tar to extract files from an archive; f tells tar that the next argument will be the name of the archive to operate on.

tar xzvf archive.tar.gz

Extract the files from gzipped archive archive.tar.gz verbosely. Here, the z tells tar that the archive will be compressed with gzip.

tar cf archive.tar mydir/

Creates an archive of the directory mydir.

tar czf archive.tar.gz mydir/

Creates an gzip-compressed archive of the directory mydir.

tar xvf archive.tar documents/work/budget.doc

Extract only the file documents/work/budget.doc from the archive archive.tar. Produce verbose output.

tar xvf archive.tar documents/work/

Extract only the directory documents/work/, and any files it contains, from the archive archive.tar. Produce verbose output.

tar xvf archive.tar --wildcards '*.doc'

Extract only files with the extension .doc from the archive archive.tar. The --wildcards option tells tar to interpret wildcards in the name of the files to be extracted; the filename (*.doc) is enclosed in single-quotes to protect the wildcard (*) from being expanded incorrectly by the shell.

tar rvf archive.tar documents/work/budget.doc

Add the file documents/work/budget.doc to the existing archive archive.tar. The r option is the same as the long option --append.

tar uvf archive.tar documents/work/budget.doc

Add the file documents/work/budget.doc to the archive archive.tar only if it is newer than the version already in the archive (or does not yet exist in the archive). Here, u is the same as the long option --update.

tar cf - documents/work/ | wc -c

Estimate the file size of an archive of the directory documents/work, but do not create the file. Here, the archive file is specified as a dash ("-"), which tells tar to send its archived output to the standard output rather than a file on disk. This output is then piped to the wc command, which reports how many bytes (-c) were in the input it received.