GNU Info

(tar.info)Synopsis

---

Next: using tar options Up: tar invocation

---

Enter node , (file) or (file)node

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' (`-t').  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' (`-P') option).
Note: absolute, for more information about `--absolute-names' (`-P').

   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 filesystem 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.  Note: Wildcards, 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' (`-t'),
`--extract' (`--get', `-x'), `--compare' (`--diff', `-d'), and
`--update' (`-u')) 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 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.

   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'
(`--diff', `-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.