X-Git-Url: https://git.brokenzipper.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=45ae59fb092867973b5d4a8db0931555472c9350;hb=78bfbb5661c534c1790f1e4c82ef1581baa2311c;hp=cb7502f3f79a44af2b4aa8857d2ad43400817b35;hpb=cc82db7f2d7768afab6d789c0e78ce1f07722d0d;p=chaz%2Ftar

diff --git a/doc/tar.texi b/doc/tar.texi
index cb7502f..45ae59f 100644
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -35,7 +35,7 @@ This manual is for @acronym{GNU} @command{tar} (version
 from archives.
 
 Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
-2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -2009,7 +2009,7 @@ attention to them.
 Each option has at least one @dfn{long} (or @dfn{mnemonic}) name starting with two
 dashes in a row, e.g., @option{--list}.  The long names are more clear than
 their corresponding short or old names.  It sometimes happens that a
-single long option has many different different names which are
+single long option has many different names which are
 synonymous, such as @option{--compare} and @option{--diff}.  In addition,
 long option names can be given unique abbreviations.  For example,
 @option{--cre} can be used in place of @option{--create} because there is no
@@ -2502,13 +2502,42 @@ patterns in the file @var{file}.  @xref{exclude}.
 @opsummary{exclude-caches}
 @item --exclude-caches
 
-Automatically excludes all directories
-containing a cache directory tag.  @xref{exclude}.
+Exclude from dump any directory containing a valid cache directory
+tag file, but still dump the directory node and the tag file itself.
+
+@xref{exclude}.
+
+@opsummary{exclude-caches-under}
+@item --exclude-caches-under
+
+Exclude from dump any directory containing a valid cache directory
+tag file, but still dump the directory node itself.
+
+@xref{exclude}.
+
+@opsummary{exclude-caches-all}
+@item --exclude-caches-all
+
+Exclude from dump any directory containing a valid cache directory
+tag file.  @xref{exclude}.
 
 @opsummary{exclude-tag}
 @item --exclude-tag=@var{file}
 
-Exclude all directories, containing file named @var{file}.  @xref{exclude}.
+Exclude from dump any directory containing file named @var{file}, but
+dump the directory node and @var{file} itself.  @xref{exclude}.
+
+@opsummary{exclude-tag-under}
+@item --exclude-tag-under=@var{file}
+
+Exclude from dump the contents of any directory containing file
+named @var{file}, but dump the directory node itself.  @xref{exclude}.
+
+@opsummary{exclude-tag-all}
+@item --exclude-tag-all=@var{file}
+
+Exclude from dump any directory containing file named @var{file}.
+@xref{exclude}. 
 
 @opsummary{file}
 @item --file=@var{archive}
@@ -6470,15 +6499,9 @@ called as @w{@samp{tar -c -X foo .}} and the file @file{foo} contains a
 single line @file{*.o}, no files whose names end in @file{.o} will be
 added to the archive.
 
-@table @option
-@opindex exclude-caches
-@item --exclude-caches
-Causes @command{tar} to ignore directories containing a cache directory tag.
-@end table
-
 @findex exclude-caches
-When creating an archive, the @option{--exclude-caches} option causes
-@command{tar} to exclude all directories that contain a @dfn{cache
+When creating an archive, the @option{--exclude-caches} option family
+causes @command{tar} to exclude all directories that contain a @dfn{cache
 directory tag}. A cache directory tag is a short file with the
 well-known name @file{CACHEDIR.TAG} and having a standard header
 specified in @url{http://www.brynosaurus.com/cachedir/spec.html}.
@@ -6486,41 +6509,105 @@ 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 @samp{exclude-caches} option, providing a different
+exclusion semantics:
+
+@table @option
+@opindex exclude-caches
+@item --exclude-caches
+Do not archive the contents of the directory, but archive the
+directory itself and the @file{CACHEDIR.TAG} file.
+
+@opindex exclude-caches-under
+@item --exclude-caches-under
+Do not archive the contents of the directory, nor the
+@file{CACHEDIR.TAG} file, archive only the directory itself.
+
+@opindex exclude-caches-all
+@item --exclude-caches-all
+Omit directories containing @file{CACHEDIR.TAG} file entirely.
+@end table
+
 @findex exclude-tag
-Another option, @option{--exclude-tag}, provides a generalization of
+Another option family, @option{--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 @samp{exclude-caches}, there are three options in this
+option family:
 
 @table @option
 @opindex exclude-tag
 @item --exclude-tag=@var{file}
-Causes @command{tar} to ignore directories containing @var{file}.
+Do not dump the contents of the directory, but dump the
+directory itself and the @var{file}.
+
+@opindex exclude-tag-under
+@item --exclude-tag-under=@var{file}
+Do not dump the contents of the directory, nor the
+@var{file}, archive only the directory itself.
+
+@opindex exclude-tag-all
+@item --exclude-tag-all=@var{file}
+Omit directories containing @var{file} file entirely.
 @end table
 
-You can specify as many exclusion tags as you like.
+Multiple @option{--exclude-tag*} options can be given.
 
-Notice, that when speaking about ``excluding the directory'' we mean
-that the files and subdirectories it contains will not get into the
-archive, while the entry for the directory itself will, e.g.:
+For example, given this directory:
 
 @smallexample
+@group
 $ @kbd{find dir}
 dir
 dir/blues
 dir/jazz
 dir/folk
 dir/folk/tagfile
-$ @kbd{tar -cf archive.tar --extract-tag=tagfile -v}
+dir/folk/sanjuan
+dir/folk/trote
+@end group
+@end smallexample
+
+The @option{--exclude-tag} will produce the following:
+
+@smallexample
+$ @kbd{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; not dumped
-$ @kbd{tar -tf archive.tar}
+tar: dir/folk/: contains a cache directory tag tagfile;
+  contents not dumped
+dir/folk/tagfile
+@end smallexample
+
+Both the @file{dir/folk} directory and its tagfile are preserved in
+the archive, however the rest of files in this directory are not.
+
+Now, using the @option{--exclude-tag-under} option will exclude
+@file{tagfile} from the dump, while still preserving the directory
+itself, as shown in this example:
+
+@smallexample
+$ @kbd{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
+@end smallexample
+
+Finally, using @option{--exclude-tag-all} omits the @file{dir/folk}
+directory entirely:
+
+@smallexample
+$ @kbd{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
 @end smallexample
 
 @menu
@@ -8734,7 +8821,7 @@ members.  Read further to learn more about them.
 Any @command{tar} implementation will be able to extract sparse members from a
 PAX archive.  However, the extracted files will be @dfn{condensed},
 i.e., any zero blocks will be removed from them.  When we restore such
-a condensed file to its original form, by adding zero bloks (or
+a condensed file to its original form, by adding zero blocks (or
 @dfn{holes}) back to their original locations, we call this process
 @dfn{expanding} a compressed sparse file.
 
@@ -8780,7 +8867,7 @@ name will be @file{@var{dir}/@var{name}}.
 @file{@var{name}}.
 @end enumerate
 
-In the unlikely case when this algorithm does not suite your needs,
+In the unlikely case when this algorithm does not suit your needs,
 you can explicitly specify output file name as a second argument to
 the command:
 
@@ -8854,10 +8941,10 @@ An @dfn{extended header} is a special @command{tar} archive header
 that precedes an archive member and contains a set of
 @dfn{variables}, describing the member properties that cannot be
 stored in the standard @code{ustar} header.  While optional for
-expanding sparse version 1.0 members, use of extended headers is
+expanding sparse version 1.0 members, the use of extended headers is
 mandatory when expanding sparse members in older sparse formats: v.0.0
 and v.0.1 (The sparse formats are described in detail in @ref{Sparse
-Formats}.)  So, for this format, the question is: how to obtain
+Formats}.)  So, for these formats, the question is: how to obtain
 extended headers from the archive?
 
 If you use a @command{tar} implementation that does not support PAX
@@ -10128,10 +10215,15 @@ Short option describing the operation @command{tar} is executing
 @item TAR_FORMAT
 Format of the archive being processed. @xref{Formats}, for a complete
 list of archive format names.
+
+@vrindex TAR_FD, info script environment variable
+@item TAR_FD
+File descriptor which can be used to communicate the new volume
+name to @command{tar}.
 @end table
 
 The volume script can instruct @command{tar} to use new archive name,
-by writing in to file descriptor 3 (see below for an example).
+by writing in to file descriptor @env{$TAR_FD} (see below for an example).
 
 If the info script fails, @command{tar} exits; otherwise, it begins
 writing the next volume.
@@ -10156,7 +10248,7 @@ The second method is to use the @samp{n} response to the tape-change
 prompt.
 
 Finally, the most flexible approach is to use a volume script, that
-writes new archive name to the file descriptor #3.  For example, the
+writes new archive name to the file descriptor @env{$TAR_FD}.  For example, the
 following volume script will create a series of archive files, named
 @file{@var{archive}-@var{vol}}, where @var{archive} is the name of the
 archive being created (as given by @option{--file} option) and
@@ -10175,7 +10267,7 @@ case $TAR_SUBCOMMAND in
 *)        exit 1
 esac
 
-echo $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME >&3
+echo $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME >&$TAR_FD
 @end group
 @end smallexample