Fix a typo and some wordings in the documentation.

[chaz/tar] / doc / tar.texi

diff --git a/doc/tar.texi b/doc/tar.texi
index 6323d2181f3c981fe9d44b611c193e9f98ca3fd0..82c303d7024cea36a4f861cae48f0491ef499eb7 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}


@@ -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}).
 
 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


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


@@ -7360,6 +7403,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


@@ -7372,6 +7486,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


@@ -9698,15 +9813,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


@@ -9909,18 +10024,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


@@ -9935,7 +10050,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.