(tar)Synopsis

Option Styles

Invoking tar

Invoking tar

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, {No
Value For "List"} or {No Value For "List"} 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
Interpretation
   , 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.