6.9 Descending into Directories

Usually, tar will recursively explore all directories (either those given on the command line or through the ‘--files-from’ option) for the various files they contain. However, you may not always want tar to act this way.

The ‘--no-recursion’ option inhibits tar’s recursive descent into specified directories. If you specify ‘--no-recursion’, you can use the find (see (find)Top section ‘find’ in GNU Find Manual) utility for hunting through levels of directories to construct a list of file names which you could then pass to tar. find allows you to be more selective when choosing which files to archive; see Reading Names from a File, for more information on using find with tar.

‘--no-recursion’

Prevents tar from recursively descending directories.

‘--recursion’

Requires tar to recursively descend directories. This is the default.

When you use ‘--no-recursion’, GNU tar grabs directory entries themselves, but does not descend on them recursively. Many people use find for locating files they want to back up, and since tar usually recursively descends on directories, they have to use the ‘-not -type d’ test in their find invocation (see Type: (find)Type section ‘Type test’ in Finding Files), as they usually do not want all the files in a directory. They then use the ‘--files-from’ option to archive the files located via find.

The problem when restoring files archived in this manner is that the directories themselves are not in the archive; so the ‘--same-permissions’ (‘--preserve-permissions’, ‘-p’) option does not affect them—while users might really like it to. Specifying ‘--no-recursion’ is a way to tell tar to grab only the directory entries given to it, adding no new files on its own. To summarize, if you use find to create a list of files to be stored in an archive, use it as follows:

$ find dir tests | \
  tar -cf archive -T - --no-recursion

The ‘--no-recursion’ option also applies when extracting: it causes tar to extract only the matched directory entries, not the files under those directories.

The ‘--no-recursion’ option also affects how globbing patterns are interpreted (see section Controlling Pattern-Matching).

The ‘--no-recursion’ and ‘--recursion’ options apply to later options and operands, and can be overridden by later occurrences of ‘--no-recursion’ and ‘--recursion’. For example:

$ tar -cf jams.tar --no-recursion grape --recursion grape/concord

creates an archive with one entry for ‘grape’, and the recursive contents of ‘grape/concord’, but no entries under ‘grape’ other than ‘grape/concord’.