Go to the first, previous, next, last section, table of contents.

Invoking GNU tar

@UNREVISED

General Synopsis of tar

The usual way to invoke tar is:

tar option... [name]...

You can actually type in arguments in any order, but 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.

There are surely many options to tar, and three different style for writing them: mnemonic options, short options, and old options. These styles are discussed below. Some options make sense with any main command, while others are meaningful only with particular main commands. One option should state the main command, all others are truly optional.

Beware that tar options are case sensitive. For example, or options are not equivalent to `--list' (`-t'), in fact, they do not even exist. Options `-T' and `-t' are different options, the first requires an argument for stating the name of a file providing a list of names, the second does not require an argument and is another way to write `--list' (`-t').

Each name in the synopsis above is interpreted as an archive member name when the main command is one of `--compare' (`-d'), `--delete', `--extract' (`-x'), `--list' (`-t') or `--update' (`-u'). For all other main commands, names are interpreted as the names of files (including directories) in the file system. tar interprets relative file names as being relative to the working directory.

tar will make all file names relative (by removing leading `/'s when archiving or restoring files), unless you specify otherwise (using the `--absolute-names' (`-P') option). See section Absolute File Names, for more information about `--absolute-names' (`-P').

@FIXME{yet another node name that is probably wrong.}

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. Globbing is the operation by which wildcard characters, `*' or `?' for example, are replaced and expanded into all existing files matching the given pattern. The problem is that shells may only glob using existing files in the file system. Only tar 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.

Each of the following subsection groups some options under a common functionality.

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, which specify the files tar is to act on. The typical tar command line syntax is:

Besides successful exits, GNU tar may fail for many reasons. Some reasons correspond to bad usage, that is, when the tar command is improperly written. Errors may be encountered later, while encountering an error 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 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.

which should always be clearly given on stderr.

GNU tar returns only a few exit statuses. I'm really aiming simplicity in that area, for now. If you are not using the `--compare' (`-d') option, zero means that everything went well, besides maybe innocuous warnings. Nonzero means that something went wrong. Right now, as of today, "nonzero" is almost always 2, except for remote operations, where it may be 128.

Many Styles for Options

There are mainly three styles for writing options to the command line invoking tar, which appeared at various epochs of its history. These styles will be presented below, from the youngest to the oldest.

Mnemonic Option Style

Each option has at least one mnemonic option name starting with two dashes in a row, v.g. `--list' (`-t'). The mnemonic option names are more legible than the corresponding short or old option names, you may prefer them if you highly praise clarity. It sometimes happens that a single mnemonic option has many different different names, which are then synonymous. In addition, mnemonic option names can be given unique abbreviations. For example, `--cre' can be used in place of `--create' because there is no other mnemonic option which begins with `cre'.

Some options require an argument. This is the case of the `--file=archive-name' (`-f archive-name') option, which tells the name of the tar archive. The argument of a mnemonic option is usually given right after the option itself, and introduced by an equal sign. For example, the `--file=archive-name' (`-f archive-name') option is given the `archive.tar' file as argument by using the notation `--file=archive.tar' for the mnemonic option.

Mnemonic options are meant to be obvious and easy to remember, possibly more so than their corresponding short options, below. For example:

tar --create --verbose --blocking-factor=20 --file=/dev/rmt0

gives a fairly good set of hints about what the command does, even for those not fully acquainted with tar.

Short Option Style

Most options, but not all of them, also have a short option name starting with a single dash, and followed by a single character, v.g. `-t'. In fact, `-t' is exactly the short option name for the mnemonic option `--list' (`-t'), both having exactly the same meaning. The forms are absolutely identical in function.

The short option names are faster to type than mnemonic option names. All along this manual, whenever a mnemonic option name is given, its equivalent short option name follows between parentheses, if such a short option name exists.

Short options which require arguments use the immediately following argument, so it may be thought as being merely introduced right after it, usually separate by white space. It is also possible to stick the argument right after the short option name, using no intervening space. So one might write `-f archive.tar' or `-farchive.tar' instead of using `--file=archive.tar'. Both `--file=archive-name' and `-f archive-name' denote the option to give the archive a non-default name, which in the example is `archive.tar'. When the option is given separately, its argument follows it, as is usual for Unix programs. For example:

tar -c -v -b 20 -f /dev/rmt0

Short options letters may be lumped together, but contrary to old options, they do not necessarily have to. When short options are nevertheless coalesced, use a single dash for them all. Only the last one in such a set is allowed to have an argument. (Clustering many options, the last of which taking an argument, seems to be fairly opaque writing to me. I would even like that GNU getopt be helpful enough to make this illegal.)

If you move short options in the command, be sure to move their arguments along with them, if any.

Old Option Style

@UNREVISED

Old options are single letters not preceeded by any dash at all, and appearing only in the position immediately following the `tar' keyword in the command, after some white space. The letter of an old option is exactly the same letter as the corresponding short option. For example, the old option `t' is the same as the short option `-t', and consequently, the same as long option `--list' (`-t').

As far as we know, all tar programs, GNU and non-GNU, support old options. GNU tar supports them not only for historical reasons, but also because many people are used to them.

All old options should be written as a single argument, without separating spaces, by lumping together all letters specifying these options. This set of letters should be the first to appear on the command line, after the tar program name; old options cannot appear anywhere else. Then, for any old option required an argument, the argument should follow on the command line. Arguments to the options should appear in the same order as the letters to which they correspond. The tar command synopsis might be rewritten:

tar letter... [argument]... [option]... [name]...

when old options are being used.

This command syntax is useful because it lets you type the single letter forms of the operation and options as a single argument to tar, without writing preceding `-'s or inserting spaces between letters. `tar cv' or `tar -cv' are equivalent to `tar -c -v'.

For compatibility with Unix tar, the first argument can contain an option letter (or a cluster of option letters) not introduced by a dash; for example, `tar cv' specifies the option `-v' in addition to the command `-c'. When options that need arguments are given together with the command, all the associated arguments follow, in the same order as the options. Thus, the example above could also be written in the old style as follows:

tar cvbf 20 /dev/rmt0

Here `20' is the argument of `-b' and `/dev/rmt0' is the argument of `-f'.

On the other hand, this old style syntax makes it difficult to match option letters with their corresponding arguments, and is often confusing. In the command `tar cvbf 20 /dev/rmt0', for example, `20' is the argument for `-b', `/dev/rmt0' is the argument for `-f', and `-v' does not have a corresponding argument. Even using short options like in `tar -c -v -b 20 -f /dev/rmt0' is clearer, putting all arguments next to the option they pertain to.

If you want to reorder the letters in the old option argument, be sure to appropriately reorder any corresponding argument.

This old way of writing tar options can surprise even experienced users. For example, the two commands:

tar cfz archive.tar.gz file
tar -cfz archive.tar.gz file

are quite different. The first example uses `archive.tar.gz' as the value for option `f' and recognizes the option `z'. The second example, however, uses `z' as the value for option `f'---probably not what was intended. (I find it quite inelegant that getopt batches the remaining `z' as the value for `f'. I think that clarity dictates that clustering of option letters, when some require arguments, should be diagnosed and disallowed. But compatibility with traditional systems dictates it.) This second example could be corrected in many ways, among which:

tar -czf archive.tar.gz file
tar -cf archive.tar.gz -z file
tar cf archive.tar.gz -z file

Mixing Option Styles

All three styles may be intermixed in a single tar command, as long as the rules for each style are fully respected.

In GNU tar up to 1.11.6, using old style options was cutting out the possibility of using many options not having short forms. Many users rightly expressed their frustration at fighting with the current tar option decoder, so I changed it. However, GNU tar needs to be compatible with other tars, in the things that other tars can do. Short options should provide upward compatibility. So, if the current option decoding raises incompatibilities, please let me know.

Old style options and modern options may be mixed on a single call to the tar program. However, old style options should be introduced in the first argument only; modern options may be given only after all arguments to old style options have been collected. If this rule is not respected, a modern option might be falsely interpreted as the value of the argument to one of the old style options.

For example, currently, all the following commands are wholly equivalent, and illustrate many combinations and orderings of option styles.

tar --create --file=archive.tar
tar --create -f archive.tar
tar --create -farchive.tar
tar --file=archive.tar --create
tar --file=archive.tar -c
tar -c --file=archive.tar
tar -c -f archive.tar
tar -c -farchive.tar
tar -cf archive.tar
tar -cfarchive.tar
tar -f archive.tar --create
tar -f archive.tar -c
tar -farchive.tar --create
tar -farchive.tar -c
tar c --file=archive.tar
tar c -f archive.tar
tar c -farchive.tar
tar cf archive.tar
tar f archive.tar --create
tar f archive.tar -c
tar fc archive.tar

On the other hand, the following commands are not equivalent to the previous set:

tar -f -c archive.tar
tar -fc archive.tar
tar -fcarchive.tar
tar -farchive.tarc
tar cfarchive.tar

These last examples mean something completely different of what the user might have intended. The first four specify that the tar archive would be a file named `-c', `c', `carchive.tar' or `archive.tarc', respectively. The first two examples also specify a single non-option, name argument having value `archive.tar'. The last example contains only old style option letters (repeating option `c' twice) and no argument value.

All Available Options

@UNREVISED

Options change the way tar performs an operation.

`--absolute-names'
`--after-date=date'
Limit the operation to files changed after the given date. See section Excluding Some Files.
`--blocking-factor=number'
Specify the blocking factor of an archive. @FIXME-xref{Blocking Factor}.
`--compress'
Specify a compressed archive. See section Using Less Space through Compression.
`--compress-block.'
Create a whole block sized compressed archive. See section Using Less Space through Compression.
`--confirmation'
Solicit confirmation for each file. See section Asking for Confirmation During Operations @FIXME{--selective should be a synonym. }
`--dereference'
Treat a symbolic link as an alternate name for the file the link points to. See section Symbolic Links.
`--directory=`directory''
Change the working directory. See section Changing Directory.
`--exclude=pattern'
Exclude files which match the regular expression pattern. See section Excluding Some Files.
`--exclude-from=`file''
Exclude files which match any of the regular expressions listed in the file `file'. See section Excluding Some Files.
`--file=archive-name'
Name the archive. See section Changing the Archive Name).
`--files-from=`file''
Read file name arguments from a file on the file system. See section Reading Names from a File.
`--ignore-umask'
Set modes of extracted files to those recorded in the archive. See section Changing How tar Writes Files.
`--ignore-zeros'
Ignore end-of-archive entries. See section Options to Help Read Archives. @FIXME{this should be changed to --ignore-end}
`--tape-length=n (-L)'
@FIXME{Alternate way of doing multi archive, will go to that length and prompts for new tape, automatically turns on multi-volume. This needs to be written into main body as well.}
`--info-script=program-file'
Create a multi-volume archive via a script. @FIXME-xref{Multi-Volume Archives}.
`--interactive'
Ask for confirmation before performing any operation on a file or archive member.
`--keep-old-files'
Prevent overwriting during extraction. See section Changing How tar Writes Files.
`--label=archive-label'
Include an archive-label in the archive being created. See section Including a Label in the Archive.
`--touch'
Set the modification time of extracted files to the time they were extracted. See section Changing How tar Writes Files.
`--multi-volume'
Specify a multi-volume archive. @FIXME-xref{Multi-Volume Archives}.
`--newer=date'
Limit the operation to files changed after the given date. See section Operating Only on New Files.
`--newer-mtime=date'
Limit the operation to files modified after the given date. See section Operating Only on New Files.
`--old'
Create an old format archive. See section Old V7 Archives. @FIXME{did we agree this should go away as a synonym?}
`--old-archive'
Create an old format archive. See section Old V7 Archives.
`--one-file-system'
Prevent tar from crossing file system boundaries when archiving. See section Crossing Filesystem Boundaries.
`--portability'
Create an old format archive. See section Old V7 Archives. @FIXME{was portability, may still need to be changed}
`--preserve-order'
Help process large lists of file names on machines with small amounts of memory. See section Options to Help Read Archives.
`--preserve-permission'
Set modes of extracted files to those recorded in the archive. See section Changing How tar Writes Files.
`--read-full-records'
Read an archive with a smaller than specified record size or which contains incomplete records. See section Options to Help Read Archives. @FIXME{should be --partial-blocks (!)}
`--block-number'
Print the block number where a message is generated. See section Checking tar progress.
`--same-order'
Help process large lists of file names on machines with small amounts of memory. See section Options to Help Read Archives.
`--same-permission'
Set the modes of extracted files to those recorded in the archive. See section Changing How tar Writes Files.
`--sparse'
Archive sparse files sparsely. See section Archiving Sparse Files.
`--starting-file=file name'
Begin reading in the middle of an archive. See section Coping With Scarce Resources.
`--to-stdout'
Write files to the standard output. See section Changing How tar Writes Files.
`--uncompress'
Specifdo a compressed archive. See section Using Less Space through Compression.
`-V archive-label'
Include an archive-label in the archive being created. See section Including a Label in the Archive. @FIXME{was --volume}
`--verbose'
Print the names of files or archive members as they are being operated on. See section Checking tar progress.
`--verify'
Check for discrepancies in the archive immediately after it is written. See section Verifying Data as It is Stored.
`-B'
Read an archive with a smaller than specified record size or which contains incomplete records. See section Options to Help Read Archives.
`-K file name'
Begin reading in the middle of an archive. See section Coping With Scarce Resources.
`-M'
Specify a multi-volume archive. @FIXME-xref{Multi-Volume Archives}.
`-N date'
Limit operation to files changed after the given date. See section Operating Only on New Files.
`-O'
Write files to the standard output. See section Changing How tar Writes Files. @FIXME{- P is absolute names, add when resolved.}
`-R'
Print the block number where a message is generated. See section Checking tar progress.
`-S'
Archive sparse files sparsely. See section Archiving Sparse Files.
`-T file'
Read file name arguments from a file on the file system. See section Reading Names from a File.
`-W'
Check for discrepancies in the archive immediately after it is written. See section Verifying Data as It is Stored.
`-Z'
Specify a compressed archive. See section Using Less Space through Compression.
`-b number'
Specify the blocking factor of an archive. @FIXME-xref{Blocking Factor}.
`-f archive-name'
Name the archive. See section Changing the Archive Name.
`-h'
Treat a symbolic link as an alternate name for the file the link points to. See section Symbolic Links.
`-i'
Ignore end-of-archive entries. See section Options to Help Read Archives.
`-k'
Prevent overwriting during extraction. See section Changing How tar Writes Files.
`-l'
Prevent tar from crossing file system boundaries when archiving. See section Crossing Filesystem Boundaries.
`-m'
Set the modification time of extracted files to the time they were extracted. See section Changing How tar Writes Files.
`-o'
Create an old format archive. See section Old V7 Archives.
`-p'
Set the modes of extracted files to those recorded in the archive. See section Changing How tar Writes Files.
`-s'
Help process large lists of file names on machines with small amounts of memory. See section Options to Help Read Archives.
`-v'
Print the names of files or archive members they are being operated on. See section Checking tar progress.
`-w'
See section Asking for Confirmation During Operations.
`-z'
Specify a compressed archive. See section Using Less Space through Compression.
`-z -z'
Create a whole block sized compressed archive. See section Using Less Space through Compression. @FIXME{It is one of the rare double letter short form. -v -v is another one.}
`-C `directory''
Change the working directory. See section Changing Directory.
`-F program-file'
Create a multi-volume archive via a script. @FIXME-xref{Multi-Volume Archives}.
`-X `file''
Exclude files which match any of the regular expressions listed in the file `file'. See section Excluding Some Files.

Device selection and switching

@UNREVISED

-f [hostname:]file
--file=[hostname:]file
Use archive file or device file on hostname. @FIXME-xref{Device}.
--force-local
Archive file is local even if it contains a colon. @FIXME-xref{Device}.
--rsh-command=command
Use remote command instead of rsh. @FIXME-xref{Device}.
-[0-7][lmh]
Specify drive and density. @FIXME-xref{Device}.
-M
--multi-volume
Create/list/extract multi-volume archive. @FIXME-xref{Multi}.
-L num
--tape-length=num
Change tape after writing num x 1024 bytes. @FIXME-xref{Multi}.
-F file
--info-script=file
--new-volume-script=file
Execute `file' at end of each tape. This implies `--multi-volume' (`-M')). @FIXME-xref{Multi}.

Device blocking

@UNREVISED

-b blocks
--blocking-factor=blocks
Set record size to @math{blocks * 512} bytes. @FIXME-xref{Blocking}.
-i
--ignore-zeros
Ignore blocks of zeros in archive (means EOF). @FIXME-xref{Blocking}.
-B
--read-full-records
Reblock as we read (for reading 4.2BSD pipes). @FIXME-xref{Blocking}.

Old classification of options

@UNREVISED

The information here is to be revised and merged into the remainder of this document, possibly altering its structure.

Options could be regrouped in three categories:

General Options
Options that are always meaningful.
Creation Options
Options for creating or updating an archive.
Extraction Options
Options for listing or extracting files.

Here are the options that are always meaningful.

`-B number', `--blocking-factor number'
`-f filename', `--file filename'
`-C dir', `--directory dir'
`-M', `--multi-volume'
`-N date', `--after-date date'
`-R', `--block-number' (`-R')
`-T filename', `--files-from filename'
`-v', `--verbose' (`-v')
`-w', `--interactive'
`-X file', `--exclude file'
`-z', `-Z', `--compress', `--uncompress'

Here are the options for creating or updating an archive. These options are used to control which files tar puts in an archive, or to control the format the archive is written in, section Controlling the Archive Format. Except as noted elsewhere, these options are useful with the `--create' (`-c'), `--append' (`-r'), `--update' (`-u'), `--concatenate' (`-A'), and `--delete' commands. Also note that the option (see section Extracting Archive Members), is also useful with the `--append' (`-r'), `--update' (`-u'), `--concatenate' (`-A'), and `--delete' commands.

`-G', `--incremental'
`-h', `--dereference' (`-h')
`-l', `--one-file-system'
`-o', `--old-archive' (`-o')
`--old', `--portability'
`-S', `--sparse'
`-V NAME', `--volume NAME'
`-W', `--verify'

Here are the options for listing or extracting files. The options in this section are meaningful with the `--extract' (`-x') command. Unless otherwise stated, they are also meaningful with the `--list' (`-t') command.

`-B', `--read-full-records'
`-G', `--incremental'
`-i', `--ignore-zeros'
`-k', `--keep-old-files'
`-K filename', `--starting-file filename'
`-m', `--touch'
`-O', `--to-stdout'
`-p', `--same-permissions', `--preserve-permissions'
`-P', `--absolute-names' (`-P')
`-s', `--same-order', `--preserve-order'
`--preserve'

Notable tar Usages

@UNREVISED

@FIXME{Using Unix file linking capability to recreate directory structures--linking files into one subdirectory and then tarring that directory.}

@FIXME{Nice hairy example using absolute-names, newer, etc.}

Piping one tar to another is an easy way to copy a directory's contents from one disk to another, while preserving the dates, modes, owners and link-structure of all the files therein.

cd sourcedirectory; tar cf - . | (cd targetdir; tar xf -)

or

@FIXME{The following using standard input/output correct??}

cd sourcedirectory; tar --create --file=- . | (cd targetdir; tar --extract --file=-)

Archive files can be used for transporting a group of files from one system to another: put all relevant files into an archive on one computer system, transfer the archive to another, and extract the contents there. The basic transfer medium might be magnetic tape, Internet FTP, or even electronic mail (though you must encode the archive with uuencode in order to transport it properly by mail). Both machines do not have to use the same operating system, as long as they both support the tar program. @FIXME{mention uuencode on a paragraph of its own}

@FIXME{end construction}


Go to the first, previous, next, last section, table of contents.