list (GNU tar 1.35)

### 2.7 How to List Archives

Frequently, you will find yourself wanting to determine exactly what a particular archive contains. You can use the `--list` (`-t`) operation to get the member names as they currently appear in the archive, as well as various attributes of the files at the time they were archived. For example, assuming `practice` is your working directory, you can examine the archive `collection.tar` that you created in the last section with the command,

    $ tar --list --file=collection.tar

The output of `tar` would then be:

    blues
    folk
    jazz

Be sure to use a `--file=archive-name` (`-f archive-name`) option just as with `--create` (`-c`) to specify the name of the archive.

You can specify one or more individual member names as arguments when using ‘`list`’. In this case, `tar` will only list the names of members you identify. For example, `tar --list --file=collection.tar folk` would only print `folk`:

    $ tar --list --file=collection.tar folk
    folk

If you use the `--verbose` (`-v`) option with `--list`, then `tar` will print out a listing reminiscent of ‘`ls -l`’, showing owner, file size, and so forth. This output is described in detail in verbose member listing.

If you had used `--verbose` (`-v`) mode, the example above would look like:

    $ tar --list --verbose --file=collection.tar folk
    -rw-r--r-- myself/user      62 1990-05-23 10:55 folk

It is important to notice that the output of `tar --list --verbose` does not necessarily match that produced by `tar --create --verbose` while creating the archive. It is because GNU `tar`, unless told explicitly not to do so, removes some directory prefixes from file names before storing them in the archive (See Absolute File Names, for more information). In other words, in verbose mode GNU `tar` shows file names when creating an archive and member names when listing it. Consider this example, run from your home directory:

    $ tar --create --verbose --file practice.tar ~/practice
    tar: Removing leading '/' from member names
    /home/myself/practice/
    /home/myself/practice/blues
    /home/myself/practice/folk
    /home/myself/practice/jazz
    /home/myself/practice/collection.tar
    $ tar --list --file practice.tar
    home/myself/practice/
    home/myself/practice/blues
    home/myself/practice/folk
    home/myself/practice/jazz
    home/myself/practice/collection.tar

This default behavior can sometimes be inconvenient. You can force GNU `tar` show member names when creating archive by supplying `--show-stored-names` option.

`--show-stored-names`

  Print member (as opposed to file) names when creating the archive.

With this option, both commands produce the same output:

    $ tar --create --verbose --show-stored-names \
               --file practice.tar ~/practice
    tar: Removing leading '/' from member names
    home/myself/practice/
    home/myself/practice/blues
    home/myself/practice/folk
    home/myself/practice/jazz
    home/myself/practice/collection.tar
    $ tar --list --file practice.tar
    home/myself/practice/
    home/myself/practice/blues
    home/myself/practice/folk
    home/myself/practice/jazz
    home/myself/practice/collection.tar

Since `tar` preserves file names, those you wish to list must be specified as they appear in the archive (i.e., relative to the directory from which the archive was created). Continuing the example above:

    $ tar --list --file=practice.tar folk
    tar: folk: Not found in archive
    tar: Exiting with failure status due to previous errors

the error message is produced because there is no member named `folk`, only one named `home/myself/folk`.

If you are not sure of the exact file name, use globbing patterns, for example:

    $ tar --list --file=practice.tar --wildcards '*/folk'
    home/myself/practice/folk

See Wildcards Patterns and Matching, for a detailed discussion of globbing patterns and related `tar` command line options.