Position-Sensitive Options (GNU tar 1.34)

Previous: Short Option Summary, Up: All 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 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 files). 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 directory.

`--null`
`--no-null`

  See nul.

`--unquote`
`--no-unquote`

  See input name quoting.

`--verbatim-files-from`
`--no-verbatim-files-from`

  See verbatim-files-from.

`--recursion`
`--no-recursion`

  See recurse.

`--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 exclude.

`--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 exclude.

#### 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 Option Summary, Up: All Options [Contents][Index]