3.7 Checking tar progress

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 monitoring tar.

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 (See verbose member listing, for the description) 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 error.

The --totals option causes tar to print on the standard error the total amount of bytes transferred when processing an archive. When creating or appending to an archive, this option prints the number of bytes written to the archive and the average speed at which they have been written, e.g.:

     $ tar -c -f archive.tar --totals /home
     Total bytes written: 7924664320 (7.4GiB, 85MiB/s)

When reading an archive, this option displays the number of bytes read:

     $ tar -x -f archive.tar --totals
     Total bytes read: 7924664320 (7.4GiB, 95MiB/s)

Finally, when deleting from an archive, the --totals option displays both numbers plus number of bytes removed from the archive:

     $ tar --delete -f foo.tar --totals --wildcards '*~'
     Total bytes read: 9543680 (9.2MiB, 201MiB/s)
     Total bytes written: 3829760 (3.7MiB, 81MiB/s)
     Total bytes deleted: 1474048

You can also obtain this information on request. When --totals is used with an argument, this argument is interpreted as a symbolic name of a signal, upon delivery of which the statistics is to be printed:

--totals=signo

Print statistics upon delivery of signal signo. Valid arguments are: SIGHUP, SIGQUIT, SIGINT, SIGUSR1 and SIGUSR2. Shortened names without ‘SIG’ prefix are also accepted.

Both forms of --totals option can be used simultaneously. Thus, tar -x --totals --totals=USR1 instructs tar to extract all members from its default archive and print statistics after finishing the extraction, as well as when receiving signal SIGUSR1.

The --checkpoint option prints an occasional message as tar reads or writes the archive. 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. By default it prints a message each 10 records read or written. This can be changed by giving it a numeric argument after an equal sign:

     $ tar -c --checkpoint=1000 /var
     tar: Write checkpoint 1000
     tar: Write checkpoint 2000
     tar: Write checkpoint 3000

This example shows the default checkpoint message used by tar. If you place a dot immediately after the equal sign, it will print a ‘.’ at each checkpoint. For example:

     $ tar -c --checkpoint=.1000 /var
     ...

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.