tar: verbose

1 
1 3.7 Checking 'tar' progress
1 ===========================
1 
1 Typically, 'tar' performs most operations without reporting any
1 information to the user except error messages.  When using 'tar' with
1 many options, particularly ones with complicated or difficult-to-predict
1 behavior, it is possible to make serious mistakes.  'tar' provides
1 several options that make observing 'tar' easier.  These options cause
1 'tar' to print information as it progresses in its job, and you might
1 want to use them just for being more careful about what is going on, or
1 merely for entertaining yourself.  If you have encountered a problem
1 when operating on an archive, however, you may need more information
1 than just an error message in order to solve the problem.  The following
1 options can be helpful diagnostic tools.
1 
1    Normally, the '--list' ('-t') command to list an archive prints just
1 the file names (one per line) and the other commands are silent.  When
1 used with most operations, the '--verbose' ('-v') option causes 'tar' to
1 print the name of each file or archive member as it is processed.  This
1 and the other options which make 'tar' print status information can be
1 useful in monitoring 'tar'.
1 
1    With '--create' or '--extract', '--verbose' used once just prints the
1 names of the files or members as they are processed.  Using it twice
1 causes 'tar' to print a longer listing (⇒verbose member listing,
1 for the description) for each member.  Since '--list' already prints the
1 names of the members, '--verbose' used once with '--list' causes 'tar'
1 to print an 'ls -l' type listing of the files in the archive.  The
1 following examples both extract members with long list output:
1 
1      $ tar --extract --file=archive.tar --verbose --verbose
1      $ tar xvvf archive.tar
1 
1    Verbose output appears on the standard output except when an archive
1 is being written to the standard output, as with 'tar --create --file=-
1 --verbose' ('tar cvf -', or even 'tar cv'--if the installer let standard
1 output be the default archive).  In that case 'tar' writes verbose
1 output to the standard error stream.
1 
1    If '--index-file=FILE' is specified, 'tar' sends verbose output to
1 FILE rather than to standard output or standard error.
1 
1    The '--totals' option causes 'tar' to print on the standard error the
1 total amount of bytes transferred when processing an archive.  When
1 creating or appending to an archive, this option prints the number of
1 bytes written to the archive and the average speed at which they have
1 been written, e.g.:
1 
1      $ tar -c -f archive.tar --totals /home
1      Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
1 
1    When reading an archive, this option displays the number of bytes
1 read:
1 
1      $ tar -x -f archive.tar --totals
1      Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
1 
1    Finally, when deleting from an archive, the '--totals' option
1 displays both numbers plus number of bytes removed from the archive:
1 
1      $ tar --delete -f foo.tar --totals --wildcards '*~'
1      Total bytes read: 9543680 (9.2MiB, 201MiB/s)
1      Total bytes written: 3829760 (3.7MiB, 81MiB/s)
1      Total bytes deleted: 1474048
1 
1    You can also obtain this information on request.  When '--totals' is
1 used with an argument, this argument is interpreted as a symbolic name
1 of a signal, upon delivery of which the statistics is to be printed:
1 
1 '--totals=SIGNO'
1      Print statistics upon delivery of signal SIGNO.  Valid arguments
1      are: 'SIGHUP', 'SIGQUIT', 'SIGINT', 'SIGUSR1' and 'SIGUSR2'.
1      Shortened names without 'SIG' prefix are also accepted.
1 
1    Both forms of '--totals' option can be used simultaneously.  Thus,
1 'tar -x --totals --totals=USR1' instructs 'tar' to extract all members
1 from its default archive and print statistics after finishing the
1 extraction, as well as when receiving signal 'SIGUSR1'.
1 
1    The '--checkpoint' option prints an occasional message as 'tar' reads
1 or writes the archive.  It is designed for those who don't need the more
1 detailed (and voluminous) output of '--block-number' ('-R'), but do want
1 visual confirmation that 'tar' is actually making forward progress.  By
1 default it prints a message each 10 records read or written.  This can
1 be changed by giving it a numeric argument after an equal sign:
1 
1      $ tar -c --checkpoint=1000 /var
1      tar: Write checkpoint 1000
1      tar: Write checkpoint 2000
1      tar: Write checkpoint 3000
1 
1    This example shows the default checkpoint message used by 'tar'.  If
1 you place a dot immediately after the equal sign, it will print a '.' at
1 each checkpoint(1).  For example:
1 
1      $ tar -c --checkpoint=.1000 /var
1      ...
1 
1    The '--checkpoint' option provides a flexible mechanism for executing
11 arbitrary actions upon hitting checkpoints, see the next section (⇒
 checkpoints), for more information on it.
1 
1    The '--show-omitted-dirs' option, when reading an archive--with
1 '--list' or '--extract', for example--causes a message to be printed for
1 each directory in the archive which is skipped.  This happens regardless
1 of the reason for skipping: the directory might not have been named on
1 the command line (implicitly or explicitly), it might be excluded by the
1 use of the '--exclude=PATTERN' option, or some other reason.
1 
1    If '--block-number' ('-R') is used, 'tar' prints, along with every
1 message it would normally produce, the block number within the archive
1 where the message was triggered.  Also, supplementary messages are
1 triggered when reading blocks full of NULs, or when hitting end of file
1 on the archive.  As of now, if the archive is properly terminated with a
1 NUL block, the reading of the file may stop before end of file is met,
1 so the position of end of file will not usually show when
1 '--block-number' ('-R') is used.  Note that GNU 'tar' drains the archive
1 before exiting when reading the archive from a pipe.
1 
1    This option is especially useful when reading damaged archives, since
1 it helps pinpoint the damaged sections.  It can also be used with
1 '--list' ('-t') when listing a file-system backup tape, allowing you to
1 choose among several backup tapes when retrieving a file later, in favor
1 of the tape where the file appears earliest (closest to the front of the
1 tape).  ⇒backup.
1 
1    ---------- Footnotes ----------
1 
1    (1) This is actually a shortcut for '--checkpoint=N
1 --checkpoint-action=dot'.  ⇒dot checkpoints.
1