GNU tar 1.35: 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.

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.

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.

6.3.1 NUL-Terminated File Names

The ‘--null’ option causes ‘--files-from=file-of-names’ (‘-T file-of-names’) to read file names terminated by a NUL instead of a newline, so files whose names contain newlines can be archived using ‘--files-from’.

The ‘--null’ option is just like the one in GNU xargs and cpio, and is useful with the ‘-print0’ predicate of GNU find. In tar, ‘--null’ also disables special handling for file names that begin with dash (similar to ‘--verbatim-files-from’ option).

This example shows how to use find to generate a list of files larger than 800 blocks in length and put that list into a file called ‘long-files’. The ‘-print0’ option to find is just like ‘-print’, except that it separates files with a NUL rather than with a newline. You can then run tar with both the ‘--null’ and ‘-T’ options to specify that tar gets the files from that file, ‘long-files’, to create the archive ‘big.tgz’. The ‘--null’ option to tar will cause tar to recognize the NUL separator between files.

$ find . -size +800 -print0 > long-files
$ tar -c -v --null --files-from=long-files --file=big.tar

The ‘--no-null’ option can be used if you need to read both NUL-terminated and newline-terminated files on the same command line. For example, if ‘flist’ is a newline-terminated file, then the following command can be used to combine it with the above command:

$ find . -size +800 -print0 |
  tar -c -f big.tar --null -T - --no-null -T flist

This example uses short options for typographic reasons, to avoid very long lines.

GNU tar is tries to automatically detect NUL-terminated file lists, so in many cases it is safe to use them even without the ‘--null’ option. In this case tar will print a warning and continue reading such a file as if ‘--null’ were actually given:

$ find . -size +800 -print0 | tar -c -f big.tar -T -
tar: -: file name read contains nul character

The null terminator, however, remains in effect only for this particular file, any following ‘-T’ options will assume newline termination. Of course, the null autodetection applies to these eventual surplus ‘-T’ options as well.

6.3 Reading Names from a File

6.3.1 NUL-Terminated File Names

6.3.1 `NUL`-Terminated File Names