tar@UNREVISED
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.
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.
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.
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.
@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
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.
@UNREVISED
Options change the way tar performs an operation.
tar Writes Files.
tar Writes Files.
tar Writes Files.
tar from crossing file system boundaries when
archiving. See section Crossing Filesystem Boundaries.
tar Writes Files.
tar progress.
tar Writes Files.
tar Writes Files.
tar progress.
tar Writes Files.
@FIXME{- P is absolute names, add when resolved.}
tar progress.
tar Writes Files.
tar from crossing file system boundaries when
archiving. See section Crossing Filesystem Boundaries.
tar Writes Files.
tar Writes Files.
tar progress.
@UNREVISED
-f [hostname:]file
--file=[hostname:]file
--force-local
--rsh-command=command
rsh. @FIXME-xref{Device}.
-[0-7][lmh]
-M
--multi-volume
-L num
--tape-length=num
-F file
--info-script=file
--new-volume-script=file
@UNREVISED
-b blocks
--blocking-factor=blocks
-i
--ignore-zeros
-B
--read-full-records
@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:
Here are the options that are always meaningful.
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.
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.
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}