Linux and Unix tar command
tar [-] A --catenate --concatenate | c --create | d --diff --compare | --delete | r --append | t --list | --test-label | u --update | x --extract --get [options] [pathname ...]
"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.
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
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.|
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:
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:
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:
|-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:
|--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:
|--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 filenamewill 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=2would 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:
|--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.|
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.|
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.
ar — GNU utility for basic manipulation of archives
basename — Strip the directory components from pathnames
cd — Change the working directory
chown — Change the owner of a file or files
cpio — Copy files into or out of an archive
dirname — Strip the filename component from pathnames
ls — Output a list of files or directories, and their properties
mt — Control a magnetic tape device
zcat — Display the contents of a gzip archive