Improve documentation.

[chaz/tar] / doc / tar.texi

diff --git a/doc/tar.texi b/doc/tar.texi
index 979e2427954ef2d199774456a8325cf7608b9c4a..0adcfc0643f5ad1cd7cd613cb32e1e0f2005ce8c 100644 (file)
--- 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}.
 
 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}
 
 @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.
 
 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}
 
 @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.
 
 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
 
 @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}).
 
 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
 @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}
 
 @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 <http://gnu.org/licenses/gpl.html>.
 This is free software: you are free to change and redistribute it.
 There is NO WARRANTY, to the extent permitted by law.
 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
 This is free software: you are free to change and redistribute it.
 There is NO WARRANTY, to the extent permitted by law.


@@ -3975,7 +4031,10 @@ tar: Hit write checkpoint #20
 tar: Hit write checkpoint #30
 @end smallexample
 
 tar: Hit write checkpoint #30
 @end smallexample
 

-The complete list of available format specifiers follows:
+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
 
 @table @samp
 @item %s


@@ -3984,17 +4043,18 @@ Print type of the checkpoint (@samp{write} or @samp{read}).
 @item %u
 Print number of the checkpoint.
 
 @item %u
 Print number of the checkpoint.
 

-@item %T
+@item %@{r,w,d@}T

 Print number of bytes transferred so far and approximate transfer
 Print number of bytes transferred so far and approximate transfer

-speed.  The number is preceded by @samp{W:}, when writing and by
-@samp{R:} when reading.  If @command{tar} is performing delete
-operation (@pxref{delete}), three numbers are printed: number of bytes
-read, written and deleted, each of them prefixed by @samp{R:},
-@samp{W:} and @samp{D:} correspondingy.  For example:
+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}
 
 @example
 $ @kbd{tar --delete -f f.tar --checkpoint-action=echo="#%u: %T" main.c}

-tar: #1: R: 0 (0B, ?/s),W: 0 (0B, ?/s),D: 0
+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
 
 tar: #2: R: 10240 (10KiB, 19MiB/s),W: 0 (0B, 0B/s),D: 10240
 @end example
 


@@ -4012,6 +4072,10 @@ for the current locale.
 Pad output with spaces to the @var{n}th column.  If the
 @samp{@{@var{n}@}} part is omitted, the current screen width
 is assumed.
 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
 @end table
 
 Aside from format expansion, the message string is subject to


@@ -4252,6 +4316,10 @@ Disable all warning messages.
 
 @subheading Keywords applicable for @command{tar --extract}
 @table @asis
 
 @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
 @kwindex timestamp
 @cindex @samp{implausibly old time stamp %s}, warning message
 @cindex @samp{time stamp %s is %s s in the future}, warning message


@@ -7339,6 +7407,77 @@ which is difficult to catch using text editors.
 
 However, empty lines are OK.
 
 
 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
 @table @option
 @cindex version control system, excluding files
 @cindex VCS, excluding files


@@ -7351,6 +7490,7 @@ 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

+@anchor{exclude-vcs}

 @opindex exclude-vcs
 @item --exclude-vcs
 Exclude files and directories used by following version control
 @opindex exclude-vcs
 @item --exclude-vcs
 Exclude files and directories used by following version control


@@ -9677,15 +9817,15 @@ free from many of @samp{v7}'s drawbacks.
 @subsection Ustar Archive Format
 
 @cindex ustar archive format
 @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}.
 
 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
 
 @node gnu
 @subsection @acronym{GNU} and old @GNUTAR{} format


@@ -9888,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
 
 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
 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.
 
 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
 wrong checksums.  @GNUTAR{} produces the standard
 checksum, however, raising incompatibilities with Sun.  That is to
 say, @GNUTAR{} has not been modified to


@@ -9914,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
 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.
 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.