GNU tar 1.35: 9.7 Including a Label in the Archive

To avoid problems caused by misplaced paper labels on the archive media, you can include a label entry — an archive member which contains the name of the archive — in the archive itself. Use the ‘--label=archive-label’ (‘-V archive-label’) option(29) in conjunction with the ‘--create’ operation to include a label entry in the archive as it is being created.

If you create an archive using both ‘--label=archive-label’ (‘-V archive-label’) and ‘--multi-volume’ (‘-M’), each volume of the archive will have an archive label of the form ‘archive-label Volume n’, where n is 1 for the first volume, 2 for the next, and so on. See section Using Multiple Tapes, for information on creating multiple volume archives.

The volume label will be displayed by ‘--list’ along with the file contents. If verbose display is requested, it will also be explicitly marked as in the example below:

$ tar --verbose --list --file=iamanarchive
V--------- 0/0               0 1992-03-07 12:01 iamalabel--Volume Header--
-rw-r--r-- ringo/user       40 1990-05-21 13:30 iamafilename

However, ‘--list’ option will cause listing entire contents of the archive, which may be undesirable (for example, if the archive is stored on a tape). You can request checking only the volume label by specifying ‘--test-label’ option. This option reads only the first block of an archive, so it can be used with slow storage devices. For example:

$ tar --test-label --file=iamanarchive
iamalabel

If ‘--test-label’ is used with one or more command line arguments, tar compares the volume label with each argument. It exits with code 0 if a match is found, and with code 1 otherwise(30). No output is displayed, unless you also used the ‘--verbose’ option. For example:

$ tar --test-label --file=iamanarchive 'iamalabel'
⇒ 0
$ tar --test-label --file=iamanarchive 'alabel'
⇒ 1

When used with the ‘--verbose’ option, tar prints the actual volume label (if any), and a verbose diagnostics in case of a mismatch:

$ tar --test-label --verbose --file=iamanarchive 'iamalabel'
iamalabel
⇒ 0
$ tar --test-label --verbose --file=iamanarchive 'alabel'
iamalabel
tar: Archive label mismatch
⇒ 1

If you request any operation, other than ‘--create’, along with using ‘--label’ option, tar will first check if the archive label matches the one specified and will refuse to proceed if it does not. Use this as a safety precaution to avoid accidentally overwriting existing archives. For example, if you wish to add files to ‘archive’, presumably labeled with string ‘My volume’, you will get:

$ tar -rf archive --label 'My volume' .
tar: Archive not labeled to match 'My volume'

in case its label does not match. This will work even if ‘archive’ is not labeled at all.

Similarly, tar will refuse to list or extract the archive if its label doesn’t match the archive-label specified. In those cases, archive-label argument is interpreted as a globbing-style pattern which must match the actual magnetic volume label. See section Excluding Some Files, for a precise description of how match is attempted(31). If the switch ‘--multi-volume’ (‘-M’) is being used, the volume label matcher will also suffix archive-label by ‘ Volume [1-9]*’ if the initial match fails, before giving up. Since the volume numbering is automatically added in labels at creation time, it sounded logical to equally help the user taking care of it when the archive is being read.

You can also use ‘--label’ to get a common information on all tapes of a series. For having this information different in each series created through a single script used on a regular basis, just manage to get some date string as part of the label. For example:

$ tar -cM -f /dev/tape -V "Daily backup for `date +%Y-%m-%d`"
$ tar --create --file=/dev/tape --multi-volume \
     --label="Daily backup for `date +%Y-%m-%d`"