3.1 General Synopsis of tar

The GNU tar program is invoked as either one of:

tar option… [name]…
tar letter… [argument]… [option]… [name]…

The second form is for when old options are being used.

You can use tar to store files in an archive, to extract them from an archive, and to do other types of archive manipulation. The primary argument to tar, which is called the operation, specifies which action to take. The other arguments to tar are either options, which change the way tar performs an operation, or file names or archive members, which specify the files or members tar is to act on.

You can actually type in arguments in any order, even if in this manual the options always precede the other arguments, to make examples easier to understand. Further, the option stating the main operation mode (the tar main command) is usually given first.

Each name in the synopsis above is interpreted as an archive member name when the main command is one of ‘--compare’ (‘--diff’, ‘-d’), ‘--delete’, ‘--extract’ (‘--get’, ‘-x’), ‘--list’ (‘-t’) or ‘--update’ (‘-u’). When naming archive members, you must give the exact name of the member in the archive, as it is printed by ‘--list’. For ‘--append’ (‘-r’) and ‘--create’ (‘-c’), these name arguments specify the names of either files or directory hierarchies to place in the archive. These files or hierarchies should already exist in the file system, prior to the execution of the tar command.

tar interprets relative file names as being relative to the working directory. tar will make all file names relative (by removing leading slashes when archiving or restoring files), unless you specify otherwise (using the ‘--absolute-names’ option). See section Absolute File Names, for more information about ‘--absolute-names’.

If you give the name of a directory as either a file name or a member name, then tar acts recursively on all the files and directories beneath that directory. For example, the name ‘/’ identifies all the files in the file system to tar.

The distinction between file names and archive member names is especially important when shell globbing is used, and sometimes a source of confusion for newcomers. See section Wildcards Patterns and Matching, for more information about globbing. The problem is that shells may only glob using existing files in the file system. Only tar itself may glob on archive members, so when needed, you must ensure that wildcard characters reach tar without being interpreted by the shell first. Using a backslash before ‘*’ or ‘?’, or putting the whole argument between quotes, is usually sufficient for this.

Even if names are often specified on the command line, they can also be read from a text file in the file system, using the ‘--files-from=file-of-names’ (‘-T file-of-names’) option.

If you don’t use any file name arguments, ‘--append’ (‘-r’), ‘--delete’ and ‘--concatenate’ (‘--catenate’, ‘-A’) will do nothing, while ‘--create’ (‘-c’) will usually yield a diagnostic and inhibit tar execution. The other operations of tar (‘--list’, ‘--extract’, ‘--compare’, and ‘--update’) will act on the entire contents of the archive.

Besides successful exits, GNU tar may fail for many reasons. Some reasons correspond to bad usage, that is, when the tar command line is improperly written. Errors may be encountered later, while processing the archive or the files. Some errors are recoverable, in which case the failure is delayed until tar has completed all its work. Some errors are such that it would be not meaningful, or at least risky, to continue processing: tar then aborts processing immediately. All abnormal exits, whether immediate or delayed, should always be clearly diagnosed on stderr, after a line stating the nature of the error.

Possible exit codes of GNU tar are summarized in the following table:

0

‘Successful termination’.

1

‘Some files differ’. If tar was invoked with ‘--compare’ (‘--diff’, ‘-d’) command line option, this means that some files in the archive differ from their disk counterparts (see section Comparing Archive Members with the File System). If tar was given ‘--create’, ‘--append’ or ‘--update’ option, this exit code means that some files were changed while being archived and so the resulting archive does not contain the exact copy of the file set.

2

‘Fatal error’. This means that some fatal, unrecoverable error occurred.

If tar has invoked a subprocess and that subprocess exited with a nonzero exit code, tar exits with that code as well. This can happen, for example, if tar was given some compression option (see section Creating and Reading Compressed Archives) and the external compressor program failed. Another example is rmt failure during backup to the remote device (see section Remote Tape Server).

This document was generated on August 23, 2023 using texi2html 5.0.