@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}
@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
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}
(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
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}.
@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::
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
@subsection Creating and Reading Compressed Archives
@cindex Compressed archives
@cindex Storing archives in compressed format
-@UNREVISED
+
+@GNUTAR{} is able to create and read compressed archives. It supports
+@command{gzip} and @command{bzip2} compression programms. For backward
+compatibilty, it also supports @command{compress} command, although
+we strongly recommend against using it, since there is a patent
+covering the algorithm it uses and you could be sued for patent
+infringement merely by running @command{compress}! Besides, it is less
+effective than @command{gzip} and @command{bzip2}.
+
+Creating a compressed archive is simple: you just specify a
+@dfn{compression option} along with the usual archive creation
+commands. The compression option is @option{-z} (@option{--gzip}) to
+create a @command{gzip} compressed archive, @option{-j}
+(@option{--bzip2}) to create a @command{bzip2} compressed archive, and
+@option{-Z} (@option{--compress}) to use @command{compress} program.
+For example:
+
+@smallexample
+$ @kbd{tar cfz archive.tar.gz .}
+@end smallexample
+
+Reading compressed archive is even simpler: you don't need to specify
+any additional options as @GNUTAR{} recognizes its format
+automatically. Thus, the following commands will list and extract the
+archive created in previous example:
+
+@smallexample
+# List the compressed archive
+$ @kbd{tar tf archive.tar.gz}
+# Extract the compressed archive
+$ @kbd{tar xf archive.tar.gz}
+@end smallexample
+
+The only case when you have to specify a decompression option while
+reading the archive is when reading from a pipe or from a tape drive
+that does not support random access. However, in this case @GNUTAR{}
+will indicate which option you should use. For example:
+
+@smallexample
+$ @kbd{cat archive.tar.gz | tar tf -}
+tar: Archive is compressed. Use -z option
+tar: Error is not recoverable: exiting now
+@end smallexample
+
+If you see such diagnostics, just add the suggested option to the
+invocation of @GNUTAR{}:
+
+@smallexample
+$ @kbd{cat archive.tar.gz | tar tfz -}
+@end smallexample
+
+Notice also, that there are several restrictions on operations on
+compressed archives. First of all, compressed archives cannot be
+modified, i.e. you cannot update (@value{op-update}) them or delete
+(@value{op-delete}) members from them. Likewise, you cannot append
+another @command{tar} archive to a compressed archive using
+@value{op-append}). Secondly, multi-volume archives cannot be
+compressed.
+
+The following table summarizes compression options used by @GNUTAR{}.
@table @kbd
@item -z
@itemx --gzip
@itemx --ungzip
Filter the archive through @command{gzip}.
-@end table
-
-@FIXME{ach; these two bits orig from "compare" (?). where to put?} Some
-format parameters must be taken into consideration when modifying an
-archive.@FIXME{???} Compressed archives cannot be modified.
You can use @samp{--gzip} and @samp{--gunzip} on physical devices
(tape drives, etc.) and remote files as well as on normal files; data
to or from such devices or remote files is reblocked by another copy
of the @command{tar} program to enforce the specified (or default) record
size. The default compression parameters are used; if you need to
-override them, avoid the @value{op-gzip} option and run @command{gzip}
-explicitly. (Or set the @env{GZIP} environment variable.)
-
-The @value{op-gzip} option does not work with the @value{op-multi-volume}
-option, or with the @value{op-update}, @value{op-append},
-@value{op-concatenate}, or @value{op-delete} operations.
-
-It is not exact to say that @GNUTAR{} is to work in concert
-with @command{gzip} in a way similar to @command{zip}, say. Surely, it is
-possible that @command{tar} and @command{gzip} be done with a single call,
-like in:
+override them, set @env{GZIP} environment variable, e.g.:
@smallexample
-$ @kbd{tar cfz archive.tar.gz subdir}
+$ @kbd{GZIP=--best tar cfz archive.tar.gz subdir}
@end smallexample
@noindent
-to save all of @samp{subdir} into a @code{gzip}'ed archive. Later you
-can do:
+Another way would be to avoid the @value{op-gzip} option and run
+@command{gzip} explicitly:
@smallexample
-$ @kbd{tar xfz archive.tar.gz}
-@end smallexample
-
-@noindent
-to explode and unpack.
-
-The difference is that the whole archive is compressed. With
-@command{zip}, archive members are archived individually. @command{tar}'s
-method yields better compression. On the other hand, one can view the
-contents of a @command{zip} archive without having to decompress it. As
-for the @command{tar} and @command{gzip} tandem, you need to decompress the
-archive to see its contents. However, this may be done without needing
-disk space, by using pipes internally:
-
-@smallexample
-$ @kbd{tar tfz archive.tar.gz}
+$ @kbd{tar cf - subdir | gzip --best -c - > archive.tar.gz}
@end smallexample
@cindex corrupted archives
lose some compressibility. But this would have make recovering easier.
So, there are pros and cons. We'll see!
-@table @kbd
@item -j
@itemx --bzip2
Filter the archive through @code{bzip2}. Otherwise like @value{op-gzip}.
Filter the archive through @command{compress}. Otherwise like
@value{op-gzip}.
-@item --use-compress-program=@var{prog}
-Filter through @var{prog} (must accept @samp{-d}).
-@end table
-
-@value{op-compress} stores an archive in compressed format. This
-option is useful in saving time over networks and space in pipes, and
-when storage space is at a premium. @value{op-compress} causes
-@command{tar} to compress when writing the archive, or to uncompress when
-reading the archive.
-
-To perform compression and uncompression on the archive, @command{tar}
-runs the @command{compress} utility. @command{tar} uses the default
-compression parameters; if you need to override them, avoid the
-@value{op-compress} option and run the @command{compress} utility
-explicitly. It is useful to be able to call the @command{compress}
-utility from within @command{tar} because the @command{compress} utility by
-itself cannot access remote tape drives.
-
-The @value{op-compress} option will not work in conjunction with the
-@value{op-multi-volume} option or the @value{op-append}, @value{op-update}
-and @value{op-delete} operations. @xref{Operations}, for
-more information on these operations.
+The @acronym{GNU} Project recommends you not use
+@command{compress}, because there is a patent covering the algorithm it
+uses. You could be sued for patent infringement merely by running
+@command{compress}.
-If there is no compress utility available, @command{tar} will report an error.
-@strong{Please note} that the @command{compress} program may be covered by
-a patent, and therefore we recommend you stop using it.
+@item --use-compress-program=@var{prog}
+Use external compression program @var{prog}. Use this option if you
+have a compression program that @GNUTAR{} does not support. There
+are two requirements to which @var{prog} should comply:
-@value{op-bzip2} acts like @value{op-compress}, except that it uses
-the @code{bzip2} utility.
+First, when called without options, it should read data from standard
+input, compress it and output it on standard output.
-@table @kbd
-@item --compress
-@itemx --uncompress
-@itemx -z
-@itemx -Z
-When this option is specified, @command{tar} will compress (when
-writing an archive), or uncompress (when reading an archive). Used in
-conjunction with the @value{op-create}, @value{op-extract},
-@value{op-list} and @value{op-compare} operations.
+Secondly, if called with @option{-d} argument, it should do exactly
+the opposite, i.e. read the compressed data from the standard input
+and produce uncompressed data on the standard output.
@end table
-You can have archives be compressed by using the @value{op-gzip} option.
-This will arrange for @command{tar} to use the @command{gzip} program to be
-used to compress or uncompress the archive wren writing or reading it.
-
-To use the older, obsolete, @command{compress} program, use the
-@value{op-compress} option. The @acronym{GNU} Project recommends you not use
-@command{compress}, because there is a patent covering the algorithm it
-uses. You could be sued for patent infringement merely by running
-@command{compress}.
-
@FIXME{I have one question, or maybe it's a suggestion if there isn't a way
to do it now. I would like to use @value{op-gzip}, but I'd also like
the output to be fed through a program like @acronym{GNU}