tar: Position-Sensitive Options

1 
1 3.4.4 Position-Sensitive Options
1 --------------------------------
1 
1 Some GNU 'tar' options can be used multiple times in the same invocation
1 and affect all arguments that appear after them.  These are options that
1 control how file names are selected and what kind of pattern matching is
1 used.
1 
1    The most obvious example is the '-C' option.  It instructs 'tar' to
1 change to the directory given as its argument prior to processing the
1 rest of command line (⇒directory).  Thus, in the following
1 command:
1 
1      tar -c -f a.tar -C /etc passwd -C /var log spool
1 
1 the file 'passwd' will be searched in the directory '/etc', and files
1 'log' and 'spool' - in '/var'.
1 
1    These options can also be used in a file list supplied with the
1 '--files-from' ('-T') option (⇒files).  In that case they affect
1 all files (patterns) appearing in that file after them and remain in
1 effect for any arguments processed after that file.  For example, if the
1 file 'list.txt' contained:
1 
1      README
1      -C src
1      main.c
1 
1 and 'tar' were invoked as follows:
1 
1      tar -c -f a.tar -T list.txt Makefile
1 
1 then the file 'README' would be looked up in the current working
1 directory, and files 'main.c' and 'Makefile' would be looked up in the
1 directory 'src'.
1 
1    Many options can be prefixed with '--no-' to cancel the effect of the
1 original option.
1 
1    For example, the '--recursion' option controls whether to recurse in
1 the subdirectories.  It's counterpart '--no-recursion' disables this.
1 Consider the command below.  It will store in the archive the directory
1 '/usr' with all files and directories that are located in it as well as
1 any files and directories in '/var', without recursing into them(1):
1 
1      tar -cf a.tar --recursion /usr --no-recursion /var/*
1 
1    During archive creation, GNU 'tar' keeps track of positional options
1 used and arguments affected by them.  If it finds out that any such
1 options are used in an obviously erroneous way, the fact is reported and
1 exit code is set to 2.  E.g.:
1 
1      $ tar -cf a.tar . --exclude '*.o'
1      tar: The following options were used after any non-optional
1      arguments in archive create or update mode.  These options are
1      positional and affect only arguments that follow them.  Please,
1      rearrange them properly.
1      tar: --exclude '*.o' has no effect
1      tar: Exiting with failure status due to previous errors
1 
1    The following table summarizes all position-sensitive options.
1 
1 '--directory=DIR'
1 '-C DIR'
1      ⇒directory.
1 
1 '--null'
1 '--no-null'
1      ⇒nul.
1 
1 '--unquote'
1 '--no-unquote'
1      ⇒input name quoting.
1 
1 '--verbatim-files-from'
1 '--no-verbatim-files-from'
1      ⇒verbatim-files-from.
1 
1 '--recursion'
1 '--no-recursion'
1      ⇒recurse.
1 
1 '--anchored'
1 '--no-anchored'
1      ⇒anchored patterns.
1 
1 '--ignore-case'
1 '--no-ignore-case'
1      ⇒case-insensitive matches.
1 
1 '--wildcards'
1 '--no-wildcards'
1      ⇒controlling pattern-matching.
1 
1 '--wildcards-match-slash'
1 '--no-wildcards-match-slash'
1      ⇒controlling pattern-matching.
1 
1 '--exclude'
1      ⇒exclude.
1 
1 '--exclude-from'
1 '-X'
1 '--exclude-caches'
1 '--exclude-caches-under'
1 '--exclude-caches-all'
1 '--exclude-tag'
1 '--exclude-ignore'
1 '--exclude-ignore-recursive'
1 '--exclude-tag-under'
1 '--exclude-tag-all'
1 '--exclude-vcs'
1 '--exclude-vcs-ignores'
1 '--exclude-backups'
1      ⇒exclude.
1 
1    ---------- Footnotes ----------
1 
1    (1) The '--recursion' option is the default and is used here for
1 clarity.  The same example can be written as:
1 
1      tar -cf a.tar /usr --no-recursion /var/*
1