Supply more information to the --to-command script.

[chaz/tar] / doc / tar.texi

diff --git a/doc/tar.texi b/doc/tar.texi
index 7154dfd06bc68b878e82d576582b5ce4c38e7be4..abc81df393f46fe4920583a479492dc2536783e2 100644 (file)
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -2572,6 +2572,10 @@ during archive creation, it is order sensitive.  @xref{directory}.
 When performing operations, @command{tar} will skip files that match
 @var{pattern}.  @xref{exclude}.
 
 When performing operations, @command{tar} will skip files that match
 @var{pattern}.  @xref{exclude}.
 

+@opsummary{exclude-backups}
+@item --exclude-backups
+Exclude backup and lock files.  @xref{exclude,, exclude-backups}.
+

 @opsummary{exclude-from}
 @item --exclude-from=@var{file}
 @itemx -X @var{file}
 @opsummary{exclude-from}
 @item --exclude-from=@var{file}
 @itemx -X @var{file}


@@ -2585,7 +2589,7 @@ patterns in the file @var{file}.  @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.
 
 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}.
+@xref{exclude,, exclude-caches}.

 
 @opsummary{exclude-caches-under}
 @item --exclude-caches-under
 
 @opsummary{exclude-caches-under}
 @item --exclude-caches-under


@@ -2605,19 +2609,20 @@ tag file.  @xref{exclude}.
 @item --exclude-tag=@var{file}
 
 Exclude from dump any directory containing file named @var{file}, but
 @item --exclude-tag=@var{file}
 
 Exclude from dump any directory containing file named @var{file}, but

-dump the directory node and @var{file} itself.  @xref{exclude}.
+dump the directory node and @var{file} itself.  @xref{exclude,, exclude-tag}.

 
 @opsummary{exclude-tag-under}
 @item --exclude-tag-under=@var{file}
 
 Exclude from dump the contents of any directory containing file
 
 @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}.
+named @var{file}, but dump the directory node itself.  @xref{exclude,,
+exclude-tag-under}.

 
 @opsummary{exclude-tag-all}
 @item --exclude-tag-all=@var{file}
 
 Exclude from dump any directory containing file named @var{file}.
 
 @opsummary{exclude-tag-all}
 @item --exclude-tag-all=@var{file}
 
 Exclude from dump any directory containing file named @var{file}.

-@xref{exclude}.
+@xref{exclude,,exclude-tag-all}.

 
 @opsummary{exclude-vcs}
 @item --exclude-vcs
 
 @opsummary{exclude-vcs}
 @item --exclude-vcs


@@ -2625,7 +2630,7 @@ Exclude from dump any directory containing file named @var{file}.
 Exclude from dump directories and files, that are internal for some
 widely used version control systems.
 
 Exclude from dump directories and files, that are internal for some
 widely used version control systems.
 

-@xref{exclude}.
+@xref{exclude,,exclude-vcs}.

 
 @opsummary{file}
 @item --file=@var{archive}
 
 @opsummary{file}
 @item --file=@var{archive}


@@ -2950,6 +2955,14 @@ When extracting an archive, subtract the user's umask from files from
 the permissions specified in the archive.  This is the default behavior
 for ordinary users.
 
 the permissions specified in the archive.  This is the default behavior
 for ordinary users.
 

+@opsummary{no-seek}
+@item --no-seek
+
+The archive media does not support seeks to arbitrary
+locations.  Usually @command{tar} determines automatically whether
+the archive can be seeked or not.  Use this option to disable this
+mechanism.
+

 @opsummary{no-unquote}
 @item --no-unquote
 Treat all input file or member names literally, do not interpret
 @opsummary{no-unquote}
 @item --no-unquote
 Treat all input file or member names literally, do not interpret


@@ -3047,8 +3060,8 @@ This option does not affect extraction from archives.
 
 @opsummary{pax-option}
 @item --pax-option=@var{keyword-list}
 
 @opsummary{pax-option}
 @item --pax-option=@var{keyword-list}

-This option is meaningful only with @acronym{POSIX.1-2001} archives
-(@pxref{posix}).  It modifies the way @command{tar} handles the
+This option enables creation of the archive in @acronym{POSIX.1-2001}
+format (@pxref{posix}) and modifies the way @command{tar} handles the

 extended header keywords.  @var{Keyword-list} is a comma-separated
 list of keyword options.  @xref{PAX keywords}, for a detailed
 discussion.
 extended header keywords.  @var{Keyword-list} is a comma-separated
 list of keyword options.  @xref{PAX keywords}, for a detailed
 discussion.


@@ -3180,7 +3193,9 @@ effect only for ordinary users.  @xref{Attributes}.
 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
 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.
+in cases when such recognition fails.  It takes effect only if the
+archive is open for reading (e.g. with @option{--list} or
+@option{--extract} options).

 
 @opsummary{show-defaults}
 @item --show-defaults
 
 @opsummary{show-defaults}
 @item --show-defaults


@@ -5390,7 +5405,7 @@ Name of the file owner group.
 @vrindex TAR_ATIME, to-command environment
 @item TAR_ATIME
 Time of last access. It is a decimal number, representing seconds
 @vrindex TAR_ATIME, to-command environment
 @item TAR_ATIME
 Time of last access. It is a decimal number, representing seconds

-since the epoch.  If the archive provides times with nanosecond
+since the Epoch.  If the archive provides times with nanosecond

 precision, the nanoseconds are appended to the timestamp after a
 decimal point.
 
 precision, the nanoseconds are appended to the timestamp after a
 decimal point.
 


@@ -5415,9 +5430,32 @@ UID of the file owner.
 GID of the file owner.
 @end table
 
 GID of the file owner.
 @end table
 

-In addition to these variables, @env{TAR_VERSION} contains the
+Additionally, the following variables contain information about
+tar mode and the archive being processed:
+
+@table @env
+@vrindex TAR_VERSION, to-command environment
+@item TAR_VERSION

 @GNUTAR{} version number.
 
 @GNUTAR{} version number.
 

+@vrindex TAR_ARCHIVE, to-command environment
+@item TAR_ARCHIVE
+The name of the archive @command{tar} is processing.
+
+@vrindex TAR_BLOCKING_FACTOR, to-command environment
+@item TAR_BLOCKING_FACTOR
+Current blocking factor (@pxref{Blocking}.
+
+@vrindex TAR_VOLUME, to-command environment
+@item TAR_VOLUME
+Ordinal number of the volume @command{tar} is processing.
+
+@vrindex TAR_FORMAT, to-command environment
+@item TAR_FORMAT
+Format of the archive being processed. @xref{Formats}, for a complete
+list of archive format names.
+@end table
+

 If @var{command} exits with a non-0 status, @command{tar} will print
 an error message similar to the following:
 
 If @var{command} exits with a non-0 status, @command{tar} will print
 an error message similar to the following:
 


@@ -7058,6 +7096,7 @@ which is difficult to catch using text editors.
 
 However, empty lines are OK.
 
 
 However, empty lines are OK.
 

+@table @option

 @cindex version control system, excluding files
 @cindex VCS, excluding files
 @cindex SCCS, excluding files
 @cindex version control system, excluding files
 @cindex VCS, excluding files
 @cindex SCCS, excluding files


@@ -7069,13 +7108,11 @@ However, empty lines are OK.
 @cindex Arch, excluding files
 @cindex Mercurial, excluding files
 @cindex Darcs, excluding files
 @cindex Arch, excluding files
 @cindex Mercurial, excluding files
 @cindex Darcs, excluding files

-@table @option

 @opindex exclude-vcs
 @item --exclude-vcs
 Exclude files and directories used by following version control
 systems: @samp{CVS}, @samp{RCS}, @samp{SCCS}, @samp{SVN}, @samp{Arch},
 @samp{Bazaar}, @samp{Mercurial}, and @samp{Darcs}.
 @opindex exclude-vcs
 @item --exclude-vcs
 Exclude files and directories used by following version control
 systems: @samp{CVS}, @samp{RCS}, @samp{SCCS}, @samp{SVN}, @samp{Arch},
 @samp{Bazaar}, @samp{Mercurial}, and @samp{Darcs}.

-@end table

 
 As of version @value{VERSION}, the following files are excluded:
 
 
 As of version @value{VERSION}, the following files are excluded:
 


@@ -7101,6 +7138,19 @@ As of version @value{VERSION}, the following files are excluded:
 @item @file{_darcs}
 @end itemize
 
 @item @file{_darcs}
 @end itemize
 

+@opindex exclude-backups
+@item --exclude-backups
+Exclude backup and lock files.  This option causes exclusion of files
+that match the following shell globbing patterns:
+
+@table @asis
+@item .#*
+@item *~
+@item #*#
+@end table
+
+@end table
+

 @findex exclude-caches
 When creating an archive, the @option{--exclude-caches} option family
 causes @command{tar} to exclude all directories that contain a @dfn{cache
 @findex exclude-caches
 When creating an archive, the @option{--exclude-caches} option family
 causes @command{tar} to exclude all directories that contain a @dfn{cache


@@ -9399,6 +9449,13 @@ will use the following default value:
 %d/PaxHeaders.%p/%f
 @end smallexample
 
 %d/PaxHeaders.%p/%f
 @end smallexample
 

+@item exthdr.mtime=@var{value}
+
+This keyword defines the value of the @samp{mtime} field that
+is written into the ustar header blocks for the extended headers.
+By default, the @samp{mtime} field is set to the modification time
+of the archive member described by that extended headers.
+

 @item globexthdr.name=@var{string}
 This keyword allows user control over the name that is written into
 the ustar header blocks for global extended header records.  The name
 @item globexthdr.name=@var{string}
 This keyword allows user control over the name that is written into
 the ustar header blocks for global extended header records.  The name


@@ -9428,6 +9485,13 @@ where @samp{$TMPDIR} represents the value of the @var{TMPDIR}
 environment variable.  If @var{TMPDIR} is not set, @command{tar}
 uses @samp{/tmp}.
 
 environment variable.  If @var{TMPDIR} is not set, @command{tar}
 uses @samp{/tmp}.
 

+@item exthdr.mtime=@var{value}
+
+This keyword defines the value of the @samp{mtime} field that
+is written into the ustar header blocks for the global extended headers.
+By default, the @samp{mtime} field is set to the time when
+@command{tar} was invoked.
+

 @item @var{keyword}=@var{value}
 When used with one of archive-creation commands, these keyword/value pairs
 will be included at the beginning of the archive in a global extended
 @item @var{keyword}=@var{value}
 When used with one of archive-creation commands, these keyword/value pairs
 will be included at the beginning of the archive in a global extended


@@ -9457,6 +9521,32 @@ the group name will be forced to a new value for all files
 stored in the archive.
 @end table
 
 stored in the archive.
 @end table
 

+In any of the forms described above, the @var{value} may be
+a string enclosed in curly braces.  In that case, the string
+between the braces is understood either as a textual time
+representation, as described in @ref{Date input formats}, or a name of
+the existing file, starting with @samp{/} or @samp{.}.  In the latter
+case, the modification time of that file is used.
+
+For example, to set all modification times to the current date, you
+use the following option:
+
+@smallexample
+--pax-option='mtime:=@{now@}'
+@end smallexample
+
+Note quoting of the option's argument.
+
+@cindex archives, binary equivalent
+@cindex binary equivalent archives, creating
+As another example, here is the option that ensures that any two
+archives created using it, will be binary equivalent if they have the
+same contents:
+
+@smallexample
+--pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0
+@end smallexample
+

 @node Checksumming
 @subsection Checksumming Problems
 
 @node Checksumming
 @subsection Checksumming Problems