X-Git-Url: https://git.brokenzipper.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=abc81df393f46fe4920583a479492dc2536783e2;hb=762be4f2bd696b3fcc381da7d78fcdd4114215ec;hp=7154dfd06bc68b878e82d576582b5ce4c38e7be4;hpb=51aee274e892923a3f8fdb774e4f6b90bce47437;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index 7154dfd..abc81df 100644 --- 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}. +@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} @@ -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. -@xref{exclude}. +@xref{exclude,, exclude-caches}. @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 -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 -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}. -@xref{exclude}. +@xref{exclude,,exclude-tag-all}. @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. -@xref{exclude}. +@xref{exclude,,exclude-vcs}. @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. +@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 @@ -3047,8 +3060,8 @@ This option does not affect extraction from archives. @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. @@ -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 -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 @@ -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 -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. @@ -5415,9 +5430,32 @@ UID of the file owner. 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. +@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: @@ -7058,6 +7096,7 @@ which is difficult to catch using text editors. However, empty lines are OK. +@table @option @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 -@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}. -@end table 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 +@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 @@ -9399,6 +9449,13 @@ will use the following default value: %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 @@ -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}. +@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 @@ -9457,6 +9521,32 @@ the group name will be forced to a new value for all files 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