X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=9cff066134ed011bfcba1e5d158da8f32e57e42b;hb=4eb1484dced64b74cafda40918c0d96e5084846a;hp=e3df0c98b238cfd2326452888048598a91de80ad;hpb=93906c238d9309f95afeddfa9ac8d7ce92351e70;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index e3df0c9..9cff066 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -974,7 +974,7 @@ archive), numeric @acronym{ID} values are printed instead. @item File name. If the name contains any special characters (white space, newlines, -etc.) these are displayed in an unambiguous form using so called +etc.)@: these are displayed in an unambiguous form using so called @dfn{quoting style}. For the detailed discussion of available styles and on how to use them, see @ref{quoting styles}. @@ -3115,7 +3115,7 @@ Tells @command{tar} to create a new directory beneath the extraction directory tarbombs. In the absence of @var{dir} argument, the name of the new directory will be equal to the base name of the archive (file name minus the archive suffix, if recognized). Any member names that do not begin -with that directory name (after +with that directory name (after transformations from @option{--transform} and @option{--strip-components}) will be prefixed with it. Recognized file name suffixes are @samp{.tar}, and any compression suffixes @@ -4316,6 +4316,10 @@ Disable all warning messages. @subheading Keywords applicable for @command{tar --extract} @table @asis +@kwindex existing-file +@cindex @samp{%s: skipping existing file}, warning message +@item existing-file +@samp{%s: skipping existing file} @kwindex timestamp @cindex @samp{implausibly old time stamp %s}, warning message @cindex @samp{time stamp %s is %s s in the future}, warning message @@ -5681,7 +5685,7 @@ contain command line arguments (see @ref{external, Running External Commands}, for more detail). Notice, that @var{command} is executed once for each regular file -extracted. Non-regular files (directories, etc.) are ignored when this +extracted. Non-regular files (directories, etc.)@: are ignored when this option is used. @end table @@ -7409,7 +7413,7 @@ However, empty lines are OK. @cindex Git, ignore files @cindex Bazaar, ignore files @cindex Mercurial, ignore files -When archiving directories that are under some version control system (VCS), +When archiving directories that are under some version control system (VCS), it is often convenient to read exclusion patterns from this VCS' ignore files (e.g. @file{.cvsignore}, @file{.gitignore}, etc.) The following options provide such possibilty: @@ -8966,7 +8970,7 @@ recent, so not all tar implementations are able to handle it properly. However, this format is designed in such a way that any tar implementation able to read @samp{ustar} archives will be able to read most @samp{posix} archives as well, with the only exception that any -additional information (such as long file names etc.) will in such +additional information (such as long file names etc.)@: will in such case be extracted as plain text files along with the files it refers to. This archive format will be the default format for future versions @@ -9175,18 +9179,11 @@ The output produced by @command{tar --help} shows the actual compressor names along with each of these options. You can use any of these options on physical devices (tape drives, -etc.) and remote files as well as on normal files; data to or from +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. Most compression -programs let you override these by setting a program-specific -environment variable. For example, with @command{gzip} you can set -@env{GZIP}: - -@smallexample -$ @kbd{GZIP='-9 -n' tar czf archive.tar.gz subdir} -@end smallexample -Another way would be to use the @option{-I} option instead (see +size. The default compression parameters are used. +You can override them by using the @option{-I} option (see below), e.g.: @smallexample @@ -9194,7 +9191,7 @@ $ @kbd{tar -cf archive.tar.gz -I 'gzip -9 -n' subdir} @end smallexample @noindent -Finally, the third, traditional, way to do this is to use a pipe: +A more traditional way to do this is to use a pipe: @smallexample $ @kbd{tar cf - subdir | gzip -9 -n > archive.tar.gz} @@ -9242,12 +9239,13 @@ suffix. The following suffixes are recognized: @item --use-compress-program=@var{command} @itemx -I=@var{command} Use external compression program @var{command}. Use this option if you +want to specify options for the compression program, or if you are not happy with the compression program associated with the suffix -at compile time or if you have a compression program that @GNUTAR{} +at compile time, or if you have a compression program that @GNUTAR{} does not support. The @var{command} argument is a valid command invocation, as you would type it at the command line prompt, with any additional options as needed. Enclose it in quotes if it contains -white space (see @ref{external, Running External Commands}, for more detail). +white space (@pxref{external, Running External Commands}). The @var{command} should follow two conventions: @@ -9813,15 +9811,15 @@ free from many of @samp{v7}'s drawbacks. @subsection Ustar Archive Format @cindex ustar archive format -Archive format defined by @acronym{POSIX}.1-1988 specification is called -@code{ustar}. Although it is more flexible than the V7 format, it +The archive format defined by the @acronym{POSIX}.1-1988 specification is +called @code{ustar}. Although it is more flexible than the V7 format, it still has many restrictions (@pxref{Formats,ustar}, for the detailed description of @code{ustar} format). Along with V7 format, @code{ustar} format is a good choice for archives intended to be read with other implementations of @command{tar}. -To create archive in @code{ustar} format, use @option{--format=ustar} -option in conjunction with the @option{--create} (@option{-c}). +To create an archive in @code{ustar} format, use the @option{--format=ustar} +option in conjunction with @option{--create} (@option{-c}). @node gnu @subsection @acronym{GNU} and old @GNUTAR{} format @@ -9926,7 +9924,8 @@ will use the following default 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. +of the archive member described by that extended header (or to the +value of the @option{--mtime} option, if supplied). @item globexthdr.name=@var{string} This keyword allows user control over the name that is written into @@ -10019,23 +10018,39 @@ same contents: --pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0 @end smallexample +@noindent +If you extract files from such an archive and recreate the archive +from them, you will also need to eliminate changes due to ctime, as +shown in examples below: + +@smallexample +--pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0,ctime:=0 +@end smallexample + +@noindent +or + +@smallexample +--pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0,delete=ctime +@end smallexample + @node Checksumming @subsection Checksumming Problems SunOS and HP-UX @command{tar} fail to accept archives created using @GNUTAR{} and containing non-@acronym{ASCII} file names, that -is, file names having characters with the eight bit set, because they +is, file names having characters with the eighth bit set, because they use signed checksums, while @GNUTAR{} uses unsigned checksums while creating archives, as per @acronym{POSIX} standards. On -reading, @GNUTAR{} computes both checksums and -accepts any. It is somewhat worrying that a lot of people may go +reading, @GNUTAR{} computes both checksums and accepts either of them. +It is somewhat worrying that a lot of people may go around doing backup of their files using faulty (or at least non-standard) software, not learning about it until it's time to restore their missing files with an incompatible file extractor, or vice versa. -@GNUTAR{} computes checksums both ways, and accept -any on read, so @acronym{GNU} tar can read Sun tapes even with their +@GNUTAR{} computes checksums both ways, and accepts either of them +on read, so @acronym{GNU} tar can read Sun tapes even with their wrong checksums. @GNUTAR{} produces the standard checksum, however, raising incompatibilities with Sun. That is to say, @GNUTAR{} has not been modified to @@ -10050,7 +10065,7 @@ the default signing of @code{char}'s in their compiler. So they started computing checksums wrongly. When they later realized their mistake, they merely decided to stay compatible with it, and with themselves afterwards. Presumably, but I do not really know, HP-UX -has chosen that their @command{tar} archives to be compatible with Sun's. +has chosen their @command{tar} archives to be compatible with Sun's. The current standards do not favor Sun @command{tar} format. In any case, it now falls on the shoulders of SunOS and HP-UX users to get a @command{tar} able to read the good archives they receive. @@ -10759,7 +10774,7 @@ installed by default. @cindex absolute file names Unless you use the @option{--absolute-names} (@option{-P}) option, @GNUTAR{} will not allow you to create an archive that contains -absolute file names (a file name beginning with @samp{/}.) If you try, +absolute file names (a file name beginning with @samp{/}). If you try, @command{tar} will automatically remove the leading @samp{/} from the file names it stores in the archive. It will also type a warning message telling you what it is doing.