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 can not 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 gzip for more information.)

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

In the file list given by -T option, any file name beginning with ‘-’ character is considered a tar option and is processed accordingly.¹ 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

Notice that the option parsing algorithm used with -T is stricter than the one used by shell. Namely, when specifying option arguments, you should observe the following rules:

• When using short (single-letter) option form, its argument must immediately follow the option letter, without any intervening whitespace. For example: -Cdir.
• When using long option form, the option argument must be separated from the option by a single equal sign. No whitespace is allowed on any side of the equal sign. For example: --directory=dir.
• For both short and long option forms, the option argument can be given on the next line after the option name, e.g.:

            --directory
            dir
       

  and

            -C
            dir
       

If you happen to have a file whose name starts with ‘-’, precede it with --add-file option to prevent it from being recognized as an option. For example: --add-file=--my-file.

• nul