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 400K 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 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(15). 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'.

`--null'

Only consider NUL-terminated file names, instead of files that terminate in a newline.

`--no-null'

Undo the effect of any previous `--null' option.

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

This document was generated on February, 23 2019 using texi2html 1.76.