Updated

[chaz/tar] / doc / tar.texi

diff --git a/doc/tar.texi b/doc/tar.texi
index cc6dda0727509bb4778f3bf5a716930b58328d38..c9c7d81b690972cf461098f074f381bdf5738516 100644 (file)
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -201,6 +201,11 @@
 @set xref-exclude-from @xref{exclude}
 @set pxref-exclude-from @pxref{exclude}
 
+@set op-exclude-caches @kbd{--exclude-caches}
+@set ref-exclude-from @ref{exclude-caches}
+@set xref-exclude-from @xref{exclude-caches}
+@set pxref-exclude-from @pxref{exclude-caches}
+
 @set op-extract @kbd{--extract} (@kbd{--get}, @kbd{-x})
 @set ref-extract @ref{extract}
 @set xref-extract @xref{extract}
@@ -493,6 +498,11 @@
 @set xref-volno-file @xref{Using Multiple Tapes}
 @set pxref-volno-file @pxref{Using Multiple Tapes}
 
+@set op-seek @kbd{--seek}
+@set ref-seek @ref{seek}
+@set xref-seek @xref{seek}
+@set pxref-seek @pxref{seek}
+
 @c Put everything in one index (arbitrarily chosen to be the concept index).
 @syncodeindex fn cp
 @syncodeindex ky cp
@@ -2743,6 +2753,11 @@ When performing operations, @command{tar} will skip files that match
 Similar to @samp{--exclude}, except @command{tar} will use the list of
 patterns in the file @var{file}.  @FIXME-xref{}
 
+@item --exclude-caches
+
+Automatically excludes all directories
+containing a cache directory tag.  @FIXME-xref{}
+
 @item --file=@var{archive}
 @itemx -f @var{archive}
 
@@ -2911,6 +2926,14 @@ multi-volume @command{tar} archive.  @FIXME-xref{}
 
 (see --info-script)
 
+@item -n
+@itemx --seek
+
+Assume that the archive media supports seeks to arbitrary
+locations. Usually @command{tar} determines automatically whether
+the archive can be seeked or not. This option is intended for use
+in cases when such recognition fails.
+
 @item --newer=@var{date}
 @itemx --after-date=@var{date}
 @itemx -N
@@ -5289,7 +5312,7 @@ to comparing directories; this is fairly gross, but there does not seem
 to be a better way to go.
 
 @command{tar} doesn't access @var{snapshot-file} when
-@value{op-create} or @value{op-list} are specified, but the
+@value{op-extract} or @value{op-list} are specified, but the
 @value{op-listed-incremental} option must still be given.  A
 placeholder @var{snapshot-file} can be specified, e.g.,
 @file{/dev/null}.
@@ -6144,6 +6167,24 @@ added to the archive.
 @FIXME{do the exclude options files need to have stuff separated by
 newlines the same as the files-from option does?}
 
+@table @kbd
+@item --exclude-caches
+Causes @command{tar} to ignore directories containing a cache directory tag.
+@end table
+
+@findex exclude-caches
+When creating an archive,
+the @samp{--exclude-caches} option
+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}.
+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.
+
 @menu
 * controlling pattern-patching with exclude::
 * problems with exclude::
@@ -6580,14 +6621,35 @@ relative to the then current directory, which might not be the same as
 the original current working directory of @command{tar}, due to a previous
 @samp{--directory} option.
 
-@FIXME{dan: does this mean that you *can* use the short option form, but
-you can *not* use the long option form with --files-from?  or is this
-totally screwed?}
-
 When using @samp{--files-from} (@pxref{files}), you can put @samp{-C}
-options in the file list.  Unfortunately, you cannot put
-@samp{--directory} options in the file list.  (This interpretation can
-be disabled by using the @value{op-null} option.)
+options in the file list. Notice, however, that in this case the
+option and its argument must occupy two consecutive lines. For 
+instance, the file list for the above example will be:
+
+@smallexample
+@group
+-C
+/etc
+passwd
+hosts
+-C
+/lib
+libc.a
+@end group
+@end smallexample
+
+@noindent
+To use it, you would invoke @command{tar} as follows:
+
+@smallexample
+$ @kbd{tar -c -f foo.tar --files-from list}
+@end smallexample
+
+Notice also that you can only use the short option variant in the file
+list, i.e. always use @option{-C}, not @option{--directory}.
+
+The interpretation of @value{op-directory} is disabled by
+@value{op-null} option.
 
 @node absolute
 @subsection Absolute File Names