Next: , Previous: , Up: Choosing Files and Names for tar   [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.

When archiving directories that are under some version control system (VCS), it is often convenient to read exclusion patterns from this VCS’ ignore files (e.g. .cvsignore, .gitignore, etc.) The following options provide such possibility:

--exclude-vcs-ignores

Before archiving a directory, see if it contains any of the following files: cvsignore, .gitignore, .bzrignore, or .hgignore. If so, read ignore patterns from these files.

The patterns are treated much as the corresponding VCS would treat them, i.e.:

.cvsignore

Contains shell-style globbing patterns that apply only to the directory where this file resides. No comments are allowed in the file. Empty lines are ignored.

.gitignore

Contains shell-style globbing patterns. Applies to the directory where .gitfile is located and all its subdirectories.

Any line beginning with a ‘#’ is a comment. Backslash escapes the comment character.

.bzrignore

Contains shell globbing-patterns and regular expressions (if prefixed with ‘RE:16. Patterns affect the directory and all its subdirectories.

Any line beginning with a ‘#’ is a comment.

.hgignore

Contains posix regular expressions17. The line ‘syntax: glob’ switches to shell globbing patterns. The line ‘syntax: regexp’ switches back. Comments begin with a ‘#’. Patterns affect the directory and all its subdirectories.

--exclude-ignore=file

Before dumping a directory, tar checks if it contains file. If so, exclusion patterns are read from this file. The patterns affect only the directory itself.

--exclude-ignore-recursive=file

Same as --exclude-ignore, except that the patterns read affect both the directory where file resides and all its subdirectories.

--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.34, 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
  • .gitmodules
  • .gitattributes
  • .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

Footnotes

(16)

According to the Bazaar docs, globbing-patterns are Korn-shell style and regular expressions are perl-style. As of GNU tar version 1.34, these are treated as shell-style globs and posix extended regexps. This will be fixed in future releases.

(17)

Support for perl-style regexps will appear in future releases.


Next: Wildcards Patterns and Matching, Previous: Reading Names from a File, Up: Choosing Files and Names for tar   [Contents][Index]