files (GNU tar 1.34)

Next: exclude, Previous: Selecting Archive Members, Up: Choosing [Contents][Index]

### 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 gzip 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 accordingly15. 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 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.

#### Footnotes

##### (15)

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: exclude, Previous: Selecting Archive Members, Up: Choosing [Contents][Index]