3.4.4 Position-Sensitive Options

Some GNU tar options can be used multiple times in the same invocation and affect all arguments that appear after them. These are options that control how file names are selected and what kind of pattern matching is used.

The most obvious example is the ‘-C’ option. It instructs tar to change to the directory given as its argument prior to processing the rest of command line (see section Changing the Working Directory). Thus, in the following command:

tar -c -f a.tar -C /etc passwd -C /var log spool

the file ‘passwd’ will be searched in the directory ‘/etc’, and files ‘log’ and ‘spool’ – in ‘/var’.

These options can also be used in a file list supplied with the ‘--files-from’ (‘-T’) option (see section Reading Names from a File). In that case they affect all files (patterns) appearing in that file after them and remain in effect for any arguments processed after that file. For example, if the file ‘list.txt’ contained:

README
-C src
main.c

and tar were invoked as follows:

tar -c -f a.tar -T list.txt Makefile

then the file ‘README’ would be looked up in the current working directory, and files ‘main.c’ and ‘Makefile’ would be looked up in the directory ‘src’.

Many options can be prefixed with ‘--no-’ to cancel the effect of the original option.

For example, the ‘--recursion’ option controls whether to recurse in the subdirectories. It’s counterpart ‘--no-recursion’ disables this. Consider the command below. It will store in the archive the directory ‘/usr’ with all files and directories that are located in it as well as any files and directories in ‘/var’, without recursing into them(6):

tar -cf a.tar --recursion /usr --no-recursion /var/*

During archive creation, GNU tar keeps track of positional options used and arguments affected by them. If it finds out that any such options are used in an obviously erroneous way, the fact is reported and exit code is set to 2. E.g.:

$ tar -cf a.tar . --exclude '*.o'
tar: The following options were used after any non-optional
arguments in archive create or update mode.  These options are
positional and affect only arguments that follow them.  Please,
rearrange them properly.
tar: --exclude '*.o' has no effect
tar: Exiting with failure status due to previous errors

The following table summarizes all position-sensitive options.

‘--directory=dir’

‘-C dir’

See section Changing the Working Directory.

‘--null’

‘--no-null’

See section NUL-Terminated File Names.

‘--unquote’

‘--no-unquote’

See input name quoting.

‘--verbatim-files-from’

‘--no-verbatim-files-from’

See verbatim-files-from.

‘--recursion’

‘--no-recursion’

See section Descending into Directories.

‘--anchored’

‘--no-anchored’

See anchored patterns.

‘--ignore-case’

‘--no-ignore-case’

See case-insensitive matches.

‘--wildcards’

‘--no-wildcards’

See section Controlling Pattern-Matching.

‘--wildcards-match-slash’

‘--no-wildcards-match-slash’

See section Controlling Pattern-Matching.

‘--exclude’

See section Excluding Some Files.

‘--exclude-from’

‘-X’

‘--exclude-caches’

‘--exclude-caches-under’

‘--exclude-caches-all’

‘--exclude-tag’

‘--exclude-ignore’

‘--exclude-ignore-recursive’

‘--exclude-tag-under’

‘--exclude-tag-all’

‘--exclude-vcs’

‘--exclude-vcs-ignores’

‘--exclude-backups’

See section Excluding Some Files.

This document was generated on August 23, 2023 using texi2html 5.0.