Next: wildcards, Previous: files, Up: Choosing [Contents][Index]

### 6.4 Excluding Some Files

To avoid operating on files whose names match a particular pattern, use the `--exclude` or `--exclude-from` options.

`--exclude=pattern`

  Causes `tar` to ignore files that match the pattern.

The `--exclude=pattern` option prevents any file or member whose name matches the shell wildcard (pattern) from being operated on. For example, to create an archive with all the contents of the directory `src` except for files whose names end in `.o`, use the command ‘`tar -cf src.tar --exclude='*.o' src`’.

You may give multiple `--exclude` options.

`--exclude-from=file`
`-X file`

  Causes `tar` to ignore files that match the patterns listed in file.

Use the `--exclude-from` option to read a list of patterns, one per line, from file; `tar` will ignore files matching those patterns. 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.

Notice, that lines from file are read verbatim. One of the frequent errors is leaving some extra whitespace after a file name, which is difficult to catch using text editors.

However, empty lines are OK.

`--exclude-vcs`

  Exclude files and directories used by following version control systems: ‘`CVS`’, ‘`RCS`’, ‘`SCCS`’, ‘`SVN`’, ‘`Arch`’, ‘`Bazaar`’, ‘`Mercurial`’, and ‘`Darcs`’.

  As of version 1.27.1, the following files are excluded:

  - `CVS/`, and everything under it
  - `RCS/`, and everything under it
  - `SCCS/`, and everything under it
  - `.git/`, and everything under it
  - `.gitignore`
  - `.cvsignore`
  - `.svn/`, and everything under it
  - `.arch-ids/`, and everything under it
  - `{arch}/`, and everything under it
  - `=RELEASE-ID`
  - `=meta-update`
  - `=update`
  - `.bzr`
  - `.bzrignore`
  - `.bzrtags`
  - `.hg`
  - `.hgignore`
  - `.hgrags`
  - `_darcs`
`--exclude-backups`

  Exclude backup and lock files. This option causes exclusion of files that match the following shell globbing patterns:

  .#*
  *~
  #*#

When creating an archive, the `--exclude-caches` option family causes `tar` to exclude all directories that contain a cache directory tag. A cache directory tag is a short file with the well-known name `CACHEDIR.TAG` and having a standard header specified in http://www.brynosaurus.com/cachedir/spec.html. Various applications write cache directory tags into directories they use to hold regenerable, non-precious data, so that such data can be more easily excluded from backups.

There are three ‘`exclude-caches`’ options, each providing a different exclusion semantics:

`--exclude-caches`

  Do not archive the contents of the directory, but archive the directory itself and the `CACHEDIR.TAG` file.

`--exclude-caches-under`

  Do not archive the contents of the directory, nor the `CACHEDIR.TAG` file, archive only the directory itself.

`--exclude-caches-all`

  Omit directories containing `CACHEDIR.TAG` file entirely.

Another option family, `--exclude-tag`, provides a generalization of this concept. It takes a single argument, a file name to look for. Any directory that contains this file will be excluded from the dump. Similarly to ‘`exclude-caches`’, there are three options in this option family:

`--exclude-tag=file`

  Do not dump the contents of the directory, but dump the directory itself and the file.

`--exclude-tag-under=file`

  Do not dump the contents of the directory, nor the file, archive only the directory itself.

`--exclude-tag-all=file`

  Omit directories containing file file entirely.

Multiple `--exclude-tag*` options can be given.

For example, given this directory:

    $ find dir
    dir
    dir/blues
    dir/jazz
    dir/folk
    dir/folk/tagfile
    dir/folk/sanjuan
    dir/folk/trote

The `--exclude-tag` will produce the following:

    $ tar -cf archive.tar --exclude-tag=tagfile -v dir
    dir/
    dir/blues
    dir/jazz
    dir/folk/
    tar: dir/folk/: contains a cache directory tag tagfile;
      contents not dumped
    dir/folk/tagfile

Both the `dir/folk` directory and its tagfile are preserved in the archive, however the rest of files in this directory are not.

Now, using the `--exclude-tag-under` option will exclude `tagfile` from the dump, while still preserving the directory itself, as shown in this example:

    $ tar -cf archive.tar --exclude-tag-under=tagfile -v dir
    dir/
    dir/blues
    dir/jazz
    dir/folk/
    ./tar: dir/folk/: contains a cache directory tag tagfile;
      contents not dumped

Finally, using `--exclude-tag-all` omits the `dir/folk` directory entirely:

    $ tar -cf archive.tar --exclude-tag-all=tagfile -v dir
    dir/
    dir/blues
    dir/jazz
    ./tar: dir/folk/: contains a cache directory tag tagfile;
      directory not dumped

Next: wildcards, Previous: files, Up: Choosing [Contents][Index]