Typically, tar performs most operations without reporting any
information to the user except error messages. When using tar
with many options, particularly ones with complicated or
difficult-to-predict behavior, it is possible to make serious mistakes.
tar provides several options that make observing tar
easier. These options cause tar to print information as it
progresses in its job, and you might want to use them just for being
more careful about what is going on, or merely for entertaining
yourself. If you have encountered a problem when operating on an
archive, however, you may need more information than just an error
message in order to solve the problem. The following options can be
helpful diagnostic tools.
Normally, the --list (-t) command to list an archive
prints just the file names (one per line) and the other commands are
silent. When used with most operations, the --verbose
(-v) option causes tar to print the name of each
file or archive member as it is processed. This and the other options
which make tar print status information can be useful in
With --create or --extract, --verbose used
once just prints the names of the files or members as they are processed.
Using it twice causes tar to print a longer listing
(reminiscent of ‘ls -l’) for each member. Since --list
already prints the names of the members, --verbose used once
with --list causes tar to print an ‘ls -l’
type listing of the files in the archive. The following examples both
extract members with long list output:
$ tar --extract --file=archive.tar --verbose --verbose
$ tar xvvf archive.tar
Verbose output appears on the standard output except when an archive is
being written to the standard output, as with ‘tar --create
--file=- --verbose’ (‘tar cfv -’, or even ‘tar cv’—if the
installer let standard output be the default archive). In that case
tar writes verbose output to the standard error stream.
If --index-file=file is specified, tar sends
verbose output to file rather than to standard output or standard
The --totals option—which is only meaningful when used with
--create (-c)—causes tar to print the total
amount written to the archive, after it has been fully created.
The --checkpoint option prints an occasional message
as tar reads or writes the archive. In fact, it prints
a message each 10 records read or written. It is designed for
those who don't need the more detailed (and voluminous) output of
--block-number (-R), but do want visual confirmation that tar
is actually making forward progress.
The --show-omitted-dirs option, when reading an archive—with
--list or --extract, for example—causes a message
to be printed for each directory in the archive which is skipped.
This happens regardless of the reason for skipping: the directory might
not have been named on the command line (implicitly or explicitly),
it might be excluded by the use of the --exclude=pattern option, or
some other reason.
If --block-number (-R) is used, tar prints, along with
every message it would normally produce, the block number within the
archive where the message was triggered. Also, supplementary messages
are triggered when reading blocks full of NULs, or when hitting end of
file on the archive. As of now, if the archive if properly terminated
with a NUL block, the reading of the file may stop before end of file
is met, so the position of end of file will not usually show when
--block-number (-R) is used. Note that GNU tar
drains the archive before exiting when reading the
archive from a pipe.
This option is especially useful when reading damaged archives, since
it helps pinpoint the damaged sections. It can also be used with
--list (-t) when listing a file-system backup tape, allowing you to
choose among several backup tapes when retrieving a file later, in
favor of the tape where the file appears earliest (closest to the
front of the tape). See backup.
Published under the terms of the GNU General Public License