X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=0adcfc0643f5ad1cd7cd613cb32e1e0f2005ce8c;hb=0e0a852e9115da076d482d0a7fb6abe8bd7e2b78;hp=48c22a36dc6eb0e2bb213528e239934c6316ef70;hpb=1689ed43885c8418c29d1365ae3a06450a460830;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index 48c22a3..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} @@ -3319,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 @@ -3627,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. @@ -4030,7 +4073,7 @@ 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 %@var{c} +@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 @@ -4273,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 @@ -7360,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 @@ -7372,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 @@ -9698,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 @@ -9909,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 @@ -9935,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.