Go to the previous, next section.

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).

FIXME: xref File Name
, 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:

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.

Go to the previous, next section.