6.3 Reading Names from a File

Instead of giving the names of files or archive members on the command line, you can put the names into a file, and then use the ‘--files-from=file-of-names’ (‘-T file-of-names’) option to tar. Give the name of the file which contains the list of files to include as the argument to ‘--files-from’. In the list, the file names should be separated by newlines. You will frequently use this option when you have generated the list of files to archive with the find utility.

‘--files-from=file-name’

‘-T file-name’

Get names to extract or create from file file-name.

If you give a single dash as a file name for ‘--files-from’, (i.e., you specify either --files-from=- or -T -), then the file names are read from standard input.

Unless you are running tar with ‘--create’, you cannot use both --files-from=- and --file=- (-f -) in the same command.

Any number of ‘-T’ options can be given in the command line.

The following example shows how to use find to generate a list of files smaller than 400 blocks in length(15) and put that list into a file called ‘small-files’. You can then use the ‘-T’ option to tar to specify the files from that file, ‘small-files’, to create the archive ‘little.tgz’. (The ‘-z’ option to tar compresses the archive with gzip; see section Creating and Reading Compressed Archives for more information.)

$ find . -size -400 -print > small-files
$ tar -c -v -z -T small-files -f little.tgz

By default, each line read from the file list is first stripped off any leading and trailing whitespace. If the resulting string begins with ‘-’ character, it is considered a tar option and is processed accordingly(16). Only a subset of GNU tar options is allowed for use in file lists. For a list of such options, Position-Sensitive Options.

For example, the common use of this feature is to change to another directory by specifying ‘-C’ option:

$ cat list
-C/etc
passwd
hosts
-C/lib
libc.a
$ tar -c -f foo.tar --files-from list

In this example, tar will first switch to ‘/etc’ directory and add files ‘passwd’ and ‘hosts’ to the archive. Then it will change to ‘/lib’ directory and will archive the file ‘libc.a’. Thus, the resulting archive ‘foo.tar’ will contain:

$ tar tf foo.tar
passwd
hosts
libc.a

Note, that any options used in the file list remain in effect for the rest of the command line. For example, using the same ‘list’ file as above, the following command

$ tar -c -f foo.tar --files-from list libcurses.a

will look for file ‘libcurses.a’ in the directory ‘/lib’, because it was used with the last ‘-C’ option (see section Position-Sensitive Options).

If such option handling is undesirable, use the ‘--verbatim-files-from’ option. When this option is in effect, each line read from the file list is treated as a file name. Notice, that this means, in particular, that no whitespace trimming is performed.

The ‘--verbatim-files-from’ affects all ‘-T’ options that follow it in the command line. The default behavior can be restored using ‘--no-verbatim-files-from’ option.

To disable option handling for a single file name, use the ‘--add-file’ option, e.g.: --add-file=--my-file.

You can use any GNU tar command line options in the file list file, including ‘--files-from’ option itself. This allows for including contents of a file list into another file list file. Note however, that options that control file list processing, such as ‘--verbatim-files-from’ or ‘--null’ won’t affect the file they appear in. They will affect next ‘--files-from’ option, if there is any.

This document was generated on August 23, 2023 using texi2html 5.0.