Previous: , Up: All tar Options   [Contents][Index]


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 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 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 them6:

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 Changing the Working Directory.

--null
--no-null

See 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 Descending into Directories.

--anchored
--no-anchored

See anchored patterns.

--ignore-case
--no-ignore-case

See case-insensitive matches.

--wildcards
--no-wildcards

See Controlling Pattern-Matching.

--wildcards-match-slash
--no-wildcards-match-slash

See Controlling Pattern-Matching.

--exclude

See 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 Excluding Some Files.


Footnotes

(6)

The --recursion option is the default and is used here for clarity. The same example can be written as:

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

Previous: Short Options Cross Reference, Up: All tar Options   [Contents][Index]