tar.info: files

Choosing

exclude

Selecting Archive Members

Back to Software 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 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'; Note: 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(1).
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

   ---------- Footnotes ----------

   (1) 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.