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¹⁵ 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 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¹⁶. Only a subset of GNU tar options is allowed for use in file lists: the options described in Position-Sensitive Options, and the --add-file option, discussed below.

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 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.

The option --add-file is provided to add file names that look like command-line options, e.g.: --add-file=--my-file.

Notice, 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.

• NUL-Terminated File Names

Footnotes

(15)

A file system block is usually 512 bytes, so this amounts to 200K. Use the ‘c’ suffix to specify size in bytes. Also, when using GNU find, you can specify other size units, such as ‘k’, ‘m’, etc. See Size in GNU Findutils, for details.

(16)

Versions of GNU tar up to 1.15.1 recognized only -C option in file lists, and only if the option and its argument occupied two consecutive lines.

Next: Excluding Some Files, Previous: Selecting Archive Members, Up: Choosing Files and Names for tar [Contents][Index]