X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=0adcfc0643f5ad1cd7cd613cb32e1e0f2005ce8c;hb=ec94fbdf458adb2af803eefdd1a9c9bbb432bb21;hp=9fde5a0761f41b7b6aff3e76bb840a8926e8fdaa;hpb=2c06a80918019471876956eef4ef22f05c9e0571;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index 9fde5a0..0adcfc0 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -2608,6 +2608,19 @@ tag file, but still dump the directory node itself. Exclude from dump any directory containing a valid cache directory tag file. @xref{exclude}. +@opsummary{exclude-ignore} +@item --exclude-ignore=@var{file} +Before dumping a directory, @command{tar} checks if it contains +@var{file}. If so, exclusion patterns are read from this file. +The patterns affect only the directory itself. @xref{exclude}. + +@opsummary{exclude-ignore-recursive} +@item --exclude-ignore-recursive=@var{file} +Before dumping a directory, @command{tar} checks if it contains +@var{file}. If so, exclusion patterns are read from this file. +The patterns affect the directory and all itssubdirectories. +@xref{exclude}. + @opsummary{exclude-tag} @item --exclude-tag=@var{file} @@ -2633,7 +2646,16 @@ 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,,exclude-vcs}. +@xref{exclude-vcs}. + +@opsummary{exclude-vcs-ignores} +@item --exclude-vcs-ignores +Exclude files that match patterns read from VCS-specific ignore +files. Supported files are: @file{.cvsignore}, @file{.gitignore}, +@file{.bzrignore}, and @file{.hgignore}. The semantics of each file +is the same as for the corresponding VCS, e.g. patterns read from +@file{.gitignore} affect the directory and all its subdirectories. +@xref{exclude-vcs-ignores}. @opsummary{file} @item --file=@var{archive} @@ -3086,6 +3108,19 @@ Used when creating an archive. Prevents @command{tar} from recursing into directories that are on different file systems from the current directory. +@opsummary{one-top-level} +@item --one-top-level[=@var{dir}] +Tells @command{tar} to create a new directory beneath the extraction directory +(or the one passed to @option{-C}) and use it to guard against +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 +transformations from @option{--transform} and +@option{--strip-components}) will be prefixed with it. Recognized +file name suffixes are @samp{.tar}, and any compression suffixes +recognizable by @xref{--auto-compress}. + @opsummary{overwrite} @item --overwrite @@ -3306,6 +3341,27 @@ The @option{--warning=existing-file} option can be used together with this option to produce warning messages about existing old files (@pxref{warnings}). +@opsummary{sort} +@item --sort=@var{order} +Specify the directory sorting order when reading directories. +@var{Order} may be one of the following: + +@table @samp +@item none +No directory sorting is performed. This is the default. + +@item name +Sort the directory entries on name. The operating system may deliver +directory entries in a more or less random order, and sorting them +makes archive creation reproducible. + +@item inode +Sort the directory entries on inode number. Sorting directories on +inode number may reduce the amount of disk seek operations when +creating an archive for some file systems. + +@end table + @opsummary{sparse} @item --sparse @itemx -S @@ -3614,7 +3670,7 @@ successfully. For example, @w{@samp{tar --version}} might print: @smallexample tar (GNU tar) @value{VERSION} -Copyright (C) 2013 Free Software Foundation, Inc. +Copyright (C) 2013-2014 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later . This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. @@ -3961,10 +4017,10 @@ e.g.: @end smallexample The @samp{%s} and @samp{%u} in the above example are -@dfn{meta-characters}. The @samp{%s} meta-character is replaced with +@dfn{format specifiers}. The @samp{%s} specifier is replaced with the @dfn{type} of the checkpoint: @samp{write} or @samp{read} (or a corresponding translated version in locales other -than @acronym{POSIX}). The @samp{%u} meta-character is replaced with +than @acronym{POSIX}). The @samp{%u} specifier is replaced with the ordinal number of the checkpoint. Thus, the above example could produce the following output when used with the @option{--create} option: @@ -3975,7 +4031,54 @@ tar: Hit write checkpoint #20 tar: Hit write checkpoint #30 @end smallexample -Aside from meta-character expansion, the message string is subject to +The complete list of available format specifiers follows. Some of +them can take optional arguments. These arguments, if given, are +supplied in curly braces between the percent sign and the specifier +letter. + +@table @samp +@item %s +Print type of the checkpoint (@samp{write} or @samp{read}). + +@item %u +Print number of the checkpoint. + +@item %@{r,w,d@}T +Print number of bytes transferred so far and approximate transfer +speed. Optional arguments supply prefixes to be used before number +of bytes read, written and deleted, correspondingly. If absent, +they default to @samp{R}. @samp{W}, @samp{D}. Any or all of them can +be omitted, so, that e.g. @samp{%@{@}T} means to print corresponding +statistics without any prefixes. Any surplus arguments, if present, +are silently ignored. + +@example +$ @kbd{tar --delete -f f.tar --checkpoint-action=echo="#%u: %T" main.c} +tar: #1: R: 0 (0B, 0B/s),W: 0 (0B, 0B/s),D: 0 +tar: #2: R: 10240 (10KiB, 19MiB/s),W: 0 (0B, 0B/s),D: 10240 +@end example + +@noindent +See also the @samp{totals} action, described below. + +@item %@{@var{fmt}@}t +Output current local time using @var{fmt} as format for @command{strftime} +(@pxref{strftime, strftime,,strftime(3), strftime(3) man page}). The +@samp{@{@var{fmt}@}} part is optional. If not present, the default +format is @samp{%c}, i.e. the preferred date and time representation +for the current locale. + +@item %@{@var{n}@}* +Pad output with spaces to the @var{n}th column. If the +@samp{@{@var{n}@}} part is omitted, the current screen width +is assumed. + +@item %c +This is a shortcut for @samp{%@{%Y-%m-%d %H:%M:%S@}t: %ds, %@{read,wrote@}T%*\r}, +intended mainly for use with @samp{ttyout} action (see below). +@end table + +Aside from format expansion, the message string is subject to @dfn{unquoting}, during which the backslash @dfn{escape sequences} are replaced with their corresponding @acronym{ASCII} characters (@pxref{escape sequences}). E.g. the following action will produce an @@ -4002,9 +4105,23 @@ following action will print the checkpoint message at the same screen line, overwriting any previous message: @smallexample ---checkpoint-action="ttyout=\rHit %s checkpoint #%u" +--checkpoint-action="ttyout=Hit %s checkpoint #%u%*\r" +@end smallexample + +@noindent +Notice the use of @samp{%*} specifier to clear out any eventual +remains of the prior output line. As as more complex example, +consider this: + +@smallexample +--checkpoint-action=ttyout='%@{%Y-%m-%d %H:%M:%S@}t (%d sec): #%u, %T%*\r' @end smallexample +@noindent +This prints the current local time, number of seconds expired since +tar was started, the checkpoint ordinal number, transferred bytes and +average computed I/O speed. + @cindex @code{dot}, checkpoint action Another available checkpoint action is @samp{dot} (or @samp{.}). It instructs @command{tar} to print a single dot on the standard listing @@ -4019,6 +4136,12 @@ For compatibility with previous @GNUTAR{} versions, this action can be abbreviated by placing a dot in front of the checkpoint frequency, as shown in the previous section. +@cindex @code{totals}, checkpoint action +The @samp{totals} action prints the total number of bytes transferred +so far. The format of the data is the same as for the +@option{--totals} option (@pxref{totals}). See also @samp{%T} format +specifier of the @samp{echo} or @samp{ttyout} action. + @cindex @code{sleep}, checkpoint action Yet another action, @samp{sleep}, pauses @command{tar} for a specified amount of seconds. The following example will stop for 30 seconds at each @@ -4193,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 @@ -7280,6 +7407,77 @@ which is difficult to catch using text editors. However, empty lines are OK. +@cindex VCS, excluding patterns from ignore files +@cindex VCS, ignore files +@cindex CVS, ignore files +@cindex Git, ignore files +@cindex Bazaar, ignore files +@cindex Mercurial, ignore files +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: + +@table @option +@anchor{exclude-vcs-ignores} +@opindex exclude-vcs-ignores +@item --exclude-vcs-ignores +Before archiving a directory, see if it contains any of the following +files: @file{cvsignore}, @file{.gitignore}, @file{.bzrignore}, or +@file{.hgignore}. If so, read ignore patterns from these files. + +The patterns are treated much as the corresponding VCS would treat +them, i.e.: + +@table @file +@findex .cvsignore +@item .cvsignore +Contains shell-style globbing patterns that apply only to the +directory where this file resides. No comments are allowed in the +file. Empty lines are ignored. + +@findex .gitignore +@item .gitignore +Contains shell-style globbing patterns. Applies to the directory +where @file{.gitfile} is located and all its subdirectories. + +Any line beginning with a @samp{#} is a comment. Backslash escapes +the comment character. + +@findex .bzrignore +@item .bzrignore +Contains shell globbing-patterns and regular expressions (if prefixed +with @samp{RE:}@footnote{According to the Bazaar docs, +globbing-patterns are Korn-shell style and regular expressions are +perl-style. As of @GNUTAR{} version @value{VERSION}, these are +treated as shell-style globs and posix extended regexps. This will be +fixed in future releases.}. Patterns affect the directory and all its +subdirectories. + +Any line beginning with a @samp{#} is a comment. + +@findex .hgignore +@item .hgignore +Contains posix regular expressions@footnote{Support for perl-style +regexps will appear in future releases.}. The line @samp{syntax: +glob} switches to shell globbing patterns. The line @samp{syntax: +regexp} switches back. Comments begin with a @samp{#}. Patterns +affect the directory and all its subdirectories. +@end table + +@opindex exclude-ignore +@item --exclude-ignore=@var{file} +Before dumping a directory, @command{tar} checks if it contains +@var{file}. If so, exclusion patterns are read from this file. +The patterns affect only the directory itself. + +@opindex exclude-ignore-recursive +@item --exclude-ignore-recursive=@var{file} +Same as @option{--exclude-ignore}, except that the patterns read +affect both the directory where @var{file} resides and all its +subdirectories. +@end table + @table @option @cindex version control system, excluding files @cindex VCS, excluding files @@ -7292,6 +7490,7 @@ However, empty lines are OK. @cindex Arch, excluding files @cindex Mercurial, excluding files @cindex Darcs, excluding files +@anchor{exclude-vcs} @opindex exclude-vcs @item --exclude-vcs Exclude files and directories used by following version control @@ -9618,15 +9817,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 @@ -9829,18 +10028,18 @@ same contents: 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 @@ -9855,7 +10054,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.