verbose tutorial (GNU tar 1.35)

#### The `--verbose` Option

`--verbose`
`-v`

  Show the files being worked on as `tar` is running.

`--verbose` (`-v`) shows details about the results of running `tar`. This can be especially useful when the results might not be obvious. For example, if you want to see the progress of `tar` as it writes files into the archive, you can use the `--verbose` option. In the beginning, you may find it useful to use `--verbose` at all times; when you are more accustomed to `tar`, you will likely want to use it at certain times but not at others. We will use `--verbose` at times to help make something clear, and we will give many examples both using and not using `--verbose` to show the differences.

Each instance of `--verbose` on the command line increases the verbosity level by one, so if you need more details on the output, specify it twice.

When reading archives (`--list`, `--extract`, `--diff`), `tar` by default prints only the names of the members being extracted. Using `--verbose` will show a full, `ls` style member listing.

In contrast, when writing archives (`--create`, `--append`, `--update`), `tar` does not print file names by default. So, a single `--verbose` option shows the file names being added to the archive, while two `--verbose` options enable the full listing.

For example, to create an archive in verbose mode:

    $ tar -cvf afiles.tar apple angst aspic
    apple
    angst
    aspic

Creating the same archive with the verbosity level 2 could give:

    $ tar -cvvf afiles.tar apple angst aspic
    -rw-r--r-- gray/staff    62373 2006-06-09 12:06 apple
    -rw-r--r-- gray/staff    11481 2006-06-09 12:06 angst
    -rw-r--r-- gray/staff    23152 2006-06-09 12:06 aspic

This works equally well using short or long forms of options. Using long forms, you would simply write out the mnemonic form of the option twice, like this:

    $ tar --create --verbose --verbose …

Note that you must double the hyphens properly each time.

Later in the tutorial, we will give examples using `--verbose --verbose`.

The `--verbose` option also enables several warning messages, that tar does not issue otherwise, such as the warning about record size being used (see The Blocking Factor of an Archive), selecting the decompress program and the like. If these are of no interest to you, you can suppress them using the `--warning` option after `--verbose`, e.g.:

    $ tar -c -v --warning=no-verbose -f afiles.tar apple angst aspic

See verbose, for details.

The full output consists of six fields:

- File type and permissions in symbolic form. These are displayed in the same format as the first column of `ls -l` output (see Verbose listing in GNU file utilities).
- Owner name and group separated by a slash character. If these data are not available (for example, when listing a ‘`v7`’ format archive), numeric ID values are printed instead.
- Size of the file, in bytes.
- File modification date in ISO 8601 format.
- File modification time.
- File name. If the name contains any special characters (white space, newlines, etc.) these are displayed in an unambiguous form using so called quoting style. For the detailed discussion of available styles and on how to use them, see Quoting Member Names.

  Depending on the file type, the name can be followed by some additional information, described in the following table:

  ‘`-> link-name`’

    The file or archive member is a symbolic link and link-name is the name of file it links to.

  ‘`link to link-name`’

    The file or archive member is a hard link and link-name is the name of file it links to.

  ‘`--Long Link--`’

    The archive member is an old GNU format long link. You will normally not encounter this.

  ‘`--Long Name--`’

    The archive member is an old GNU format long name. You will normally not encounter this.

  ‘`--Volume Header--`’

    The archive member is a GNU volume header (see Tape Files).

  ‘`--Continued at byte n--`’

    Encountered only at the beginning of a multi-volume archive (see Using Multiple Tapes). This archive member is a continuation from the previous volume. The number n gives the offset where the original file was split.

  ‘`unknown file type c`’

    An archive member of unknown type. c is the type character from the archive header. If you encounter such a message, it means that either your archive contains proprietary member types GNU `tar` is not able to handle, or the archive is corrupted.

For example, here is an archive listing containing most of the special suffixes explained above:

    V--------- 0/0            1536 2006-06-09 13:07 MyVolume--Volume Header--
    -rw-r--r-- gray/staff   456783 2006-06-09 12:06 aspic--Continued at byte 32456--
    -rw-r--r-- gray/staff    62373 2006-06-09 12:06 apple
    lrwxrwxrwx gray/staff        0 2006-06-09 13:01 angst -> apple
    -rw-r--r-- gray/staff    35793 2006-06-09 12:06 blues
    hrw-r--r-- gray/staff        0 2006-06-09 12:06 music link to blues