(tar.info)exclude


Next: after Prev: files Up: Choosing

Excluding Some Files
====================

     *(This message will disappear, once this node revised.)*

   This option causes `tar' to read a list of regular expressions (in
shell wildcard syntax), one per line, from FILE; `tar' will ignore
files matching those regular expressions.  Thus if `tar' is called as
`tar -c -X foo .' and the file `foo' contains a single line `*.o', no
files whose names end in `.o' will be added to the archive.  Multiple
`--exclude=PATTERN' options may be given.

   The `--exclude=PATTERN' option will prevent any file or member which
matches the regular expression PATTERN from being operated on.  For
example, if you want to create an archive with all the contents of
`/tmp' except the file `/tmp/foo', you can use the command `tar
--create --file=arch.tar --exclude=foo'.

   If there are many files you want to exclude, you can use the
`--exclude-from=FILE-OF-PATTERNS' (`-X FILE-OF-PATTERNS') option.  This
works just like the `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES')
option: specify the name of a file as EXCLUDE-LIST which contains the
list of patterns you want to exclude.

   To avoid operating on files whose names match a particular pattern,
use the `--exclude=PATTERN' or `--exclude-from=FILE-OF-PATTERNS' (`-X
FILE-OF-PATTERNS') options.  When you specify the `--exclude=PATTERN'
option, `tar' ignores files which match the PATTERN, which can be a
single file name or a more complex expression.  Thus, if you invoke
`tar' with `tar --create --exclude=*.o', no files whose names end in
`.o' are included in the archive.

   A PATTERN should be written according to shell syntax, using
wildcard characters to effect globbing.  Most characters in the pattern
stand for themselves in a file name, and case is significant: `a' will
match only `a', and not `A'.  The character `?' in the pattern matches
any single character in the file name.  The character `*' in the
pattern matches zero, one or more single characters in the file name.
The character `[', up to the matching `]', introduces a character class,
and is described in the next paragraph.  The character `\' in a pattern
merely introduces the following character of the pattern as matching a
single character in the file name; it is useful when one needs to match
`?', `*', `[' or `\' themselves.

   A character class is a list of acceptable characters for the next
single character of the file name.  However, if the first character of
the class, just after the opening `[', is `!' or `^', then the meaning
of the class is reversed, and it rather lists those characters which
are *forbidden* as the next single character of the file name.  Other
characters of the class stand for themselves.  The special construction
`L-M', using an hyphen between two letters, is meant to represent all
characters between L and M included.

   Periods (`.') or slashes (`/') are not considered special for
wildcard matches.  However, if a pattern completely matches a directory
prefix of a file name, then it matches the full file name: that is to
say that that excluding a directory also excludes all the files beneath
it.

   `--exclude-from=FILE-OF-PATTERNS' (`-X FILE-OF-PATTERNS') acts like
`--exclude=PATTERN', but specifies a file FILE containing a list of
patterns.  `tar' ignores files with names that fit any of these
patterns.

   You can use either option more than once in a single command.

`--exclude=PATTERN'
     Causes `tar' to ignore files that match the PATTERN.

`--exclude-from=FILE'
`-X FILE'
     Causes `tar' to ignore files that match the patterns listed in
     FILE.

   Even if exclude options are somewhat straightforward, a few users
find them confusing.  Collected out of a few reports we received, here
is a list of more common pitfalls.

   * On the command line invoking `tar', after all options, there is an
     explicit list of files or directories to handle.  If any such file
     is directly subject to an exclusion due to `--exclude=PATTERN' or
     {No Value For "op-exclude-file"}, then the explicit file prevails
     over the exclusion.  You may consider that exclusion is effected
     while directories are recursively traversed, but not at the top
     level.

   * One can sometimes mix the meaning of `--exclude=PATTERN' and
     `--exclude-from=FILE-OF-PATTERNS' (`-X FILE-OF-PATTERNS').  Be
     careful to use `--exclude=PATTERN' when files to be excluded are
     given as a pattern on the command line, and to use
     `--exclude-from=FILE-OF-PATTERNS' (`-X FILE-OF-PATTERNS') for
     introducing the name of a file, itself containing a list of
     patterns, one per line, each of these patterns being able to
     exclude zero, one or many files.

   * When using `--exclude=PATTERN', be sure to quote the PATTERN
     parameter, so GNU `tar' see wildcard characters like `*'.  If you
     do not do this, the shell might expand the `*' itself using files
     at hand, so `tar' might receive a list of files instead of one
     pattern, or none at all, making the command somewhat illegal.
     This might not correspond to what one wants.  For example, write:

          tar --create --file=ARCHIVE.tar --exclude='*/tmp/*' DIRECTORY

     rather than:

          tar --create --file=ARCHIVE.tar --exclude=*/tmp/* DIRECTORY

   * Exclude options in `tar' use shell syntax, or globbing, rather
     than `regexp' syntax.  Using `regexp' syntax to describe files to
     be excluded will generally not yield the expected behavior.

   * In releases of GNU `tar' prior to 1.11.8, long options and old
     options could not be safely mixed on a single `tar' invocation, so
     the `--exclude=PATTERN' option was not recognized as such, for the
     common case old options were used.

   * We found out that what is currently the `--exclude-from' option
     used to be called `--exclude' instead, in some previous version of
     GNU `tar', at a time before the current `--exclude' option
     functionality existed.


automatically generated by info version 1.5

Dirfile and infopages generated Sat Dec 3 02:07:54 2005