Linux Tar Command

Linux and Unix tar command

Quick links

About tar
Syntax
Examples
Related commands
Linux and Unix main page

About tar

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

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-basedstorage 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 grouppermissions, access and modification dates, and directory structures. 

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

Operation

The first argument to tar should be a function specification: either one of the letters A, c, d, r, t, u, orx, 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, --concatenateAppend tar files to an archive.c, --createCreate a new archive.d, --diff, --compareCalculate any differences between the archive and the file system.--deleteDelete from the archive. (This function doesn't work on magnetic tapes).r, --appendAppend files to the end of a tar archive.t, --listList the contents of an archive.--test-labelTest the archive label, and exit.u, --updateAppend files, but only those that are newer than the copy in the archive.x, --extract, --getExtract 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-compressUse 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 --gzipoption had been specified (see --gzip, below).--add-file=fileAdd file to the archive. (This option is especially useful when the name of the file begins with a dash.)--anchoredFilename patterns must match from the begining of a file name.--no-anchoredFilename patterns may match after any "/" (this is the default for excluding files; see --exclude, below).--atime-preservePreserve 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-compressDo not automatically determine the compression program using the archive filename suffix.-b, --blocking-factorBLOCKSUse 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-methodRather 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,numberedAlways make numbered backups.nil,existingMake numbered backups of files that already have them, and simple backups of the others.never,simpleAlways make simple backups.
If not specified, backup-method defaults to the value of environment variableVERSION_CONTROL; if VERSION_CONTROL is undefined, backup-method defaults toexisting.-C, --directory DIRChange to directory DIR before performing any operations.--check-devicecheck device numbers when creating incremental archives. This is the default behavior.--no-check-deviceDo not check device numbers when creating incremental archives.--checkpoint[=NUMBER]Use "checkpoints": display a progress message every NUMBER records (default 10).--checkpoint-action=ACTIONExecute ACTION at every checkpoint. ACTION may be one of the following:

bellPlay an audible bell at the console.dot, .Print a single dot.echoDisplay a text message at the console (to standard error).echo=stringDisplay string string on standard error; before output, anymetacharacters in string are expanded.exec=commandExecute the given command.sleep=timeWait for time seconds.ttyout=stringOutput 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-restoreDelay setting modification times and permissions of extracted directories until the end of extraction.--no-delay-directory-restoreModification times and permissions of extracted directories are set when all files from this directory have been extracted. This is the default.--exclude=PATTERNAvoid operating on files whose names match filename pattern PATTERN.--exclude-backupsexclude backup and lock files from all operations.--exclude-cachesCauses 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-allOmit directories containing a CACHEDIR.TAG file entirely.--exclude-caches-underExclude everything under directories containing a CACHEDIR.TAG file, including theCACHEDIR.TAG file; but, archive the directory.--exclude-tag=FILEExclude the contents of any directory containing file FILE, but archive the directory and the file FILE.--exclude-tag-all=FILEOmit directories containing file FILE entirely.--exclude-tag-under=FILEExclude everything under directories containing file FILE including the file FILE; but, archive the directory.--exclude-vcsExclude 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=ARCHIVEUse archive file (or device) ARCHIVE.-F, --info-script, --new-volume-script=NAMErun script NAME at the end of each tape (implies -M).--force-localForce tar to treat the archive file as a local file, even if its name contains a colon.--full-timePrint the full resolution of all file times.-g, --listed-incremental=FILEDuring 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, --incrementalHandle old GNU-format incremental backups.--group=NAMEForce NAME as group for added files.-h, --dereferenceFollow symlinks; archive the files they point to.-H, --format=FORMATCreate archive of the given format, where FORMAT is one of the following:

gnuGNU tar 1.13.x formatoldgnuGNU format used in tar versions 1.12 and lowerpaxPOSIX 1003.1-2001 ("pax") formatposixSame as paxustarPOSIX 1003.1-1988 ("ustar") formatv7old Unix Version 7 tar format--hard-dereferenceFollow hard links; archive the files they refer to.-i, --ignore-zerosIgnore 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=PROGUse 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 PROGcommand invocation itself.--ignore-caseIgnore character case when matching patterns or file names.--no-ignore-caseUse case-sensitive pattern and filename matching (this is the default).--ignore-command-errorIgnore exit codes of subprocesses.--no-ignore-command-errorTreat non-zero exit codes of subprocesses as an error.--ignore-failed-readDo not exit merely because an unreadable file was encountered.--index-file=FILESend verbose output to file FILE for later use.-j, --bzip2This option tells tar to read or write archives using the bzip2 compressor.-J, --xzTells tar to read or write archives using the xz compressor.-k, --keep-old-filesDo not overwrite existing files when extracting files from an archive, and return an error if such files exist.-K, --starting-file=NAMEThis option affects extraction only; tar will skip extracting files in the archive until it finds one that matches name.--keep-newer-filesDon't replace existing files that are newer than their archive copies.-l, --check-linksCheck 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:

suffixunitsbyte equivalentbBlockssize x 512BKilobytessize x 1024cBytessizeGGigabytessize x 1024^3KKilobytessize x 1024kKilobytessize x 1024MMegabytessize x 1024^2PPetabytessize x 1024^5TTerabytessize x 1024^4wWordssize x 2--level=nWhen using the --listed-incremental option, force an incremental backup of level n.--lzipRead or write archives through the lzip compressor.--lzmaRead or write archives through the lzma compressor.--lzopRead or write archives through the lzop compressor.-m, --touchSets 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-volumeCreate, 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=permissionsWhen 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 octalnumber or as symbolic permissions, as with chmod.--mtime=dateWhen 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, --seekAssume that the archive media supports seeking to arbitrary locations. Usually tardetermines 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=dateOnly 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=dateLike --after-time, but looks at modification times only.--nullWhen 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-nullCancels any previous --null option specified.--numeric-ownerAlways use numberic IDs, rather than names, for user/group ownership information.-O, --to-stdoutExtract 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, --portabilitySame as "--format=v7".--one-file-systemPrevents tar from crossing file system boundaries when archiving. Can be used with any write operation.--overwriteOverwrite existing files when extracting.--overwrite-dirOverwrite metadata of existing directories when extracting (this is the default behavior).--no-overwrite-dirPreserve metadata of existing directories when extracting.--owner=userSpecifies 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-permissionsWhen 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-namesDon't strip leading "/"s from file names.--pax-option=keyword-listEnables creation of the archive in POSIX.1-2001 format, where keyword-list is a comma-separated list of keyword options specific to that format.--posixSame as --format=posix.--preserveThis is the same as specifying both "--preserve-permissions" and "--same-order".--quote-chars=STRINGWhen 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=STRINGWhen name quoting, tar will never quote any of the characters in STRING.--quoting-style=STYLEWhen 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-numberWith 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.--recursionRecurse into directories (this is the default).--no-recursionDo not recurse into subdirectories when archiving.--recursive-unlinkRemove existing directory hierarchies before extracting directories of the same name from the archive.--remove-filesRemove files after adding them to an archive.--restrictDisable use of some potentially harmful tar options. Currently this option disables shellinvocation.--rmt-command=cmdIn cases where tar is using a remote tape server, this option notifies tar that it should usecmd as the remote tape server program instead of the default, "/usr/libexec/rmt".--rsh-command=cmdIn 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-orderThis 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, --sparseThis 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-ownerAttempt to give extracted files the same ownership as exists in the archive (this is the default for superuser).--no-same-ownerDo 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-permissionsApply the user's umask when extracting permissions from the archive. This is the default behavior for ordinary users.--no-seekDo not attempt to seek to arbitrary locations within an archive.--show-defaultsDisplay tar's default options. This can be useful in certain shell scripts.--show-omitted-dirsWhen listing or extracting, list each directory that does not match search criteria.--show-transformed-names, --show-stored-namesDisplay 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-numberSpecifies the format version to use when archiving sparse files. Implies '--sparse'.--strip-components=numberStrip 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=suffixUses 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=filetar 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=commandDuring 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-exprReplace 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-firstRemove a corresponding file from the file system before extracting it from the archive, rather than simply overwriting it.--unquoteUnquote filenames read in with -T; this is the default.--no-unquoteDo not unquote filenames read in with -T.--utcPrint all file times in UTC (universal time).-v, --verboseOperate verbosely.-V, --label=nameWhen 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=fileUsed 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, --confirmationAsk for confirmation for every action.-W, --verifyAttempt to verify the archive after writing it.--warning=keywordControl 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:


allEnable all warning messages. This is the default.noneDisable all warning messages.--wildcardsUse wildcards.--wildcards-match-slashWhen 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-wildcardsWildcards are not permitted. Filenames may only be matched verbatim.-X, --exclude-from=fileLike --exclude, but excludes files matching the patterns listed in the file file.-z, --gzip, --gunzipThis 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, --uncompresstar will use the compress program when operating on files.

Environment

The following environment variables affect the operation of tar:

SIMPLE_BACKUP_SUFFIXFilename suffix to use when backing up files, if --suffix is not specified. The default backup suffix is "~".TAR_OPTIONSAny options specified in this variable will be prepended to options specified to tar on the command line.TAPEThe 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 tarto 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.

Related commands

ar — Create, modify, and extract files from archives.
basename — Strip directory information and suffixes from filenames.
cd — Change the working directory.
chown — Change the ownership of files or directories.
cpio — Copy files to or from archives.
dirname — Strip the filename from a pathname, leaving only the directory component.
ls — List the contents of a directory or directories.
mt — Control magnetic tapes.
zcat — Print the uncompressed contents of compressed files.