X-Git-Url: https://git.brokenzipper.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=328ed9f79b701fb889110a565808947793d4db89;hb=7111008659ee7d595cd2fa9f42944b4d59102f02;hp=25dc0249b7a99b179cc07143a173a6e1ae0c31f2;hpb=9d3142805b66dabe89a13502a1b34f5dd1e83058;p=chaz%2Ftar

diff --git a/doc/tar.texi b/doc/tar.texi
index 25dc024..328ed9f 100644
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -109,6 +109,7 @@ Appendices
 
 * Changes::
 * Configuring Help Summary::
+* Fixing Snapshot Files::
 * Tar Internals::
 * Genfile::
 * Free Software Needs Free Documentation::
@@ -315,11 +316,16 @@ Date input formats
 
 Controlling the Archive Format
 
-* Portability::                 Making @command{tar} Archives More Portable
 * Compression::                 Using Less Space through Compression
 * Attributes::                  Handling File Attributes
+* Portability::                 Making @command{tar} Archives More Portable
 * cpio::                        Comparison of @command{tar} and @command{cpio}
 
+Using Less Space through Compression
+
+* gzip::                        Creating and Reading Compressed Archives
+* sparse::                      Archiving Sparse Files
+
 Making @command{tar} Archives More Portable
 
 * Portable Names::              Portable Names
@@ -342,11 +348,6 @@ How to Extract GNU-Specific Data Using Other @command{tar} Implementations
 * Split Recovery::       Members Split Between Volumes
 * Sparse Recovery::      Sparse Members
 
-Using Less Space through Compression
-
-* gzip::                        Creating and Reading Compressed Archives
-* sparse::                      Archiving Sparse Files
-
 Tapes and Other Archive Media
 
 * Device::                      Device selection and switching
@@ -2401,6 +2402,13 @@ a read-only loopback mount, or use the @samp{noatime} mount option
 available on some systems.  However, mounting typically requires
 superuser privileges and can be a pain to manage.
 
+@opsummary{auto-compress}
+@item --auto-compress
+@itemx -a
+
+During a @option{--create} operation, enables automatic compressed
+format recognition based on the archive suffix. @xref{gzip}.
+
 @opsummary{backup}
 @item --backup=@var{backup-type}
 
@@ -2539,6 +2547,14 @@ named @var{file}, but dump the directory node itself.  @xref{exclude}.
 Exclude from dump any directory containing file named @var{file}.
 @xref{exclude}. 
 
+@opsummary{exclude-vcs}
+@item --exclude-vcs
+
+Exclude from dump directories and files, that are internal for some
+widely used version control systems.
+
+@xref{exclude}.
+
 @opsummary{file}
 @item --file=@var{archive}
 @itemx -f @var{archive}
@@ -2709,6 +2725,12 @@ backup, using @var{snapshot-file} to determine which files to backup.
 With other operations, informs @command{tar} that the archive is in
 incremental format.  @xref{Incremental Dumps}.
 
+@opsummary{lzma}
+@item --lzma
+
+This option tells @command{tar} to read or write archives through
+@command{lzma}.  @xref{gzip}.
+
 @opsummary{mode}
 @item --mode=@var{permissions}
 
@@ -2740,15 +2762,6 @@ multi-volume @command{tar} archive.  @xref{Using Multiple Tapes}.
 
 (see --info-script)
 
-@opsummary{seek}
-@item --seek
-@itemx -n
-
-Assume that the archive media supports seeks to arbitrary
-locations.  Usually @command{tar} determines automatically whether
-the archive can be seeked or not.  This option is intended for use
-in cases when such recognition fails.
-
 @opsummary{newer}
 @item --newer=@var{date}
 @itemx --after-date=@var{date}
@@ -2920,39 +2933,6 @@ this interpretation fails, it has to be a decimal numeric user @acronym{ID}.
 
 This option does not affect extraction from archives.
 
-@opsummary{transform}
-@item --transform=@var{sed-expr}
-
-Transform file or member names using @command{sed} replacement expression
-@var{sed-expr}.  For example,
-
-@smallexample
-$ @kbd{tar cf archive.tar --transform 's,^\./,usr/,' .}
-@end smallexample
-
-@noindent
-will add to @file{archive} files from the current working directory,
-replacing initial @samp{./} prefix with @samp{usr/}. For the detailed
-discussion, @xref{transform}.
-
-To see transformed member names in verbose listings, use
-@option{--show-transformed-names} option
-(@pxref{show-transformed-names}).
-
-@opsummary{quote-chars}
-@item --quote-chars=@var{string}
-Always quote characters from @var{string}, even if the selected
-quoting style would not quote them (@pxref{quoting styles}).
-
-@opsummary{quoting-style}
-@item --quoting-style=@var{style}
-Set quoting style to use when printing member and file names
-(@pxref{quoting styles}). Valid @var{style} values are:
-@code{literal}, @code{shell}, @code{shell-always}, @code{c},
-@code{escape}, @code{locale}, and @code{clocale}. Default quoting
-style is @code{escape}, unless overridden while configuring the
-package.
-
 @opsummary{pax-option}
 @item --pax-option=@var{keyword-list}
 This option is meaningful only with @acronym{POSIX.1-2001} archives
@@ -2993,6 +2973,20 @@ that number as the permissions to create the destination file.
 Specifying this option instructs @command{tar} that it should use the
 permissions directly from the archive.  @xref{Setting Access Permissions}.
 
+@opsummary{quote-chars}
+@item --quote-chars=@var{string}
+Always quote characters from @var{string}, even if the selected
+quoting style would not quote them (@pxref{quoting styles}).
+
+@opsummary{quoting-style}
+@item --quoting-style=@var{style}
+Set quoting style to use when printing member and file names
+(@pxref{quoting styles}). Valid @var{style} values are:
+@code{literal}, @code{shell}, @code{shell-always}, @code{c},
+@code{escape}, @code{locale}, and @code{clocale}. Default quoting
+style is @code{escape}, unless overridden while configuring the
+package.
+
 @opsummary{read-full-records}
 @item --read-full-records
 @itemx -B
@@ -3067,6 +3061,15 @@ effect only for ordinary users.  @xref{Attributes}.
 
 (See @option{--preserve-permissions}; @pxref{Setting Access Permissions}.)
 
+@opsummary{seek}
+@item --seek
+@itemx -n
+
+Assume that the archive media supports seeks to arbitrary
+locations.  Usually @command{tar} determines automatically whether
+the archive can be seeked or not.  This option is intended for use
+in cases when such recognition fails.
+
 @opsummary{show-defaults}
 @item --show-defaults
 
@@ -3180,6 +3183,25 @@ Sets the data modification time of extracted files to the extraction time,
 rather than the data modification time stored in the archive.
 @xref{Data Modification Times}.
 
+@opsummary{transform}
+@item --transform=@var{sed-expr}
+
+Transform file or member names using @command{sed} replacement expression
+@var{sed-expr}.  For example,
+
+@smallexample
+$ @kbd{tar cf archive.tar --transform 's,^\./,usr/,' .}
+@end smallexample
+
+@noindent
+will add to @file{archive} files from the current working directory,
+replacing initial @samp{./} prefix with @samp{usr/}. For the detailed
+discussion, @xref{transform}.
+
+To see transformed member names in verbose listings, use
+@option{--show-transformed-names} option
+(@pxref{show-transformed-names}).
+
 @opsummary{uncompress}
 @item --uncompress
 
@@ -5406,6 +5428,7 @@ unreliable if you modify a file's time stamps during dumping (e.g.,
 with the @option{--atime-preserve=replace} option), or if you set the clock
 backwards.
 
+@cindex Device numbers, using in incremental backups
 Metadata stored in snapshot files include device numbers, which,
 obviously is supposed to be a non-volatile value.  However, it turns
 out that NFS devices have undependable values when an automounter
@@ -5416,6 +5439,11 @@ is to considers all NFS devices as being equal when it comes to
 comparing directories; this is fairly gross, but there does not seem
 to be a better way to go.
 
+If you are using the @i{Linux} kernel, the device numbers can also
+change when upgrading to some newer versions of the kernel.  This can
+cause the next backup to be full backup on the affected filesystems.
+@xref{Fixing Snapshot Files}, for the information on how to handle this case.
+
 Note that incremental archives use @command{tar} extensions and may
 not be readable by non-@acronym{GNU} versions of the @command{tar} program.
 
@@ -6499,6 +6527,42 @@ called as @w{@samp{tar -c -X foo .}} and the file @file{foo} contains a
 single line @file{*.o}, no files whose names end in @file{.o} will be
 added to the archive.
 
+Notice, that lines from @var{file} are read verbatim. One of the
+frequent errors is leaving some extra whitespace after a file name,
+which is difficult to catch using text editors.
+
+However, empty lines are OK.
+
+@cindex version control system, excluding files
+@cindex VCS, excluding files
+@cindex SCCS, excluding files
+@cindex RCS, excluding files
+@cindex CVS, excluding files
+@cindex SVN, excluding files
+@cindex git, excluding files
+@table @option
+@opindex exclude-vcs
+@item --exclude-vcs
+Exclude files and directories used by some version control systems.
+@end table
+
+As of version @value{VERSION}, the following files are excluded:
+
+@itemize @bullet
+@item @file{CVS/}, and everything under it
+@item @file{RCS/}, and everything under it
+@item @file{SCCS/}, and everything under it
+@item @file{.git/}, and everything under it
+@item @file{.gitignore}
+@item @file{.cvsignore}
+@item @file{.svn/}, and everything under it
+@item @file{.arch-ids/}, and everything under it
+@item @file{@{arch@}/}, and everything under it
+@item @file{=RELEASE-ID}
+@item @file{=meta-update}
+@item @file{=update}
+@end itemize
+
 @findex exclude-caches
 When creating an archive, the @option{--exclude-caches} option family
 causes @command{tar} to exclude all directories that contain a @dfn{cache
@@ -6509,7 +6573,7 @@ Various applications write cache directory tags into directories they
 use to hold regenerable, non-precious data, so that such data can be
 more easily excluded from backups.
 
-There are three @samp{exclude-caches} option, providing a different
+There are three @samp{exclude-caches} options, each providing a different
 exclusion semantics:
 
 @table @option
@@ -7890,18 +7954,18 @@ switch to @samp{posix}.
 @cindex Storing archives in compressed format
 
 @GNUTAR{} is able to create and read compressed archives.  It supports
-@command{gzip} and @command{bzip2} compression programs.  For backward
-compatibility, it also supports @command{compress} command, although
-we strongly recommend against using it, since there is a patent
-covering the algorithm it uses and you could be sued for patent
-infringement merely by running @command{compress}!  Besides, it is less
-effective than @command{gzip} and @command{bzip2}.
+@command{gzip}, @command{bzip2} and @command{lzma} compression
+programs.  For backward compatibility, it also supports
+@command{compress} command, although we strongly recommend against
+using it, because it is by far less effective than other compression
+programs@footnote{It also had patent problems in the past.}.
 
 Creating a compressed archive is simple: you just specify a
 @dfn{compression option} along with the usual archive creation
 commands.  The compression option is @option{-z} (@option{--gzip}) to
 create a @command{gzip} compressed archive, @option{-j}
-(@option{--bzip2}) to create a @command{bzip2} compressed archive, and
+(@option{--bzip2}) to create a @command{bzip2} compressed archive,
+@command{lzma} to create an @asis{LZMA} compressed archive and
 @option{-Z} (@option{--compress}) to use @command{compress} program.
 For example:
 
@@ -7909,6 +7973,26 @@ For example:
 $ @kbd{tar cfz archive.tar.gz .}
 @end smallexample
 
+You can also let @GNUTAR{} select the compression program basing on
+the suffix of the archive file name. This is done using
+@option{--auto-compress} (@option{-a}) command line option. For
+example, the following invocation will use @command{bzip2} for
+compression:
+
+@smallexample
+$ @kbd{tar cfa archive.tar.bz2 .}
+@end smallexample
+
+@noindent
+whereas the following one will use @command{lzma}:
+
+@smallexample
+$ @kbd{tar cfa archive.tar.lzma .}
+@end smallexample
+
+For a complete list of file name suffixes recognized by @GNUTAR{},
+@ref{auto-compress}. 
+
 Reading compressed archive is even simpler: you don't need to specify
 any additional options as @GNUTAR{} recognizes its format
 automatically.  Thus, the following commands will list and extract the
@@ -7950,6 +8034,28 @@ compressed.
 The following table summarizes compression options used by @GNUTAR{}.
 
 @table @option
+@anchor{auto-compress}
+@opindex auto-compress
+@item --auto-compress
+@itemx -a
+Select a compression program to use by the archive file name
+suffix. The following suffixes are recognized:
+
+@multitable @columnfractions 0.3 0.6
+@headitem Suffix @tab Compression program
+@item @samp{.gz} @tab @command{gzip}
+@item @samp{.tgz} @tab @command{gzip}
+@item @samp{.taz} @tab @command{gzip}
+@item @samp{.Z} @tab @command{compress}
+@item @samp{.taZ} @tab @command{compress}
+@item @samp{.bz2} @tab @command{bzip2}
+@item @samp{.tz2} @tab @command{bzip2}
+@item @samp{.tbz2} @tab @command{bzip2}
+@item @samp{.tbz} @tab @command{bzip2}
+@item @samp{.lzma} @tab @command{lzma}
+@item @samp{.tlz} @tab @command{lzma}
+@end multitable
+
 @opindex gzip
 @opindex ungzip
 @item -z
@@ -7996,6 +8102,10 @@ So, there are pros and cons.  We'll see!
 @itemx --bzip2
 Filter the archive through @code{bzip2}.  Otherwise like @option{--gzip}.
 
+@opindex lzma
+@item --lzma
+Filter the archive through @command{lzma}.  Otherwise like @option{--gzip}.
+
 @opindex compress
 @opindex uncompress
 @item -Z
@@ -8003,11 +8113,6 @@ Filter the archive through @code{bzip2}.  Otherwise like @option{--gzip}.
 @itemx --uncompress
 Filter the archive through @command{compress}.  Otherwise like @option{--gzip}.
 
-The @acronym{GNU} Project recommends you not use
-@command{compress}, because there is a patent covering the algorithm it
-uses.  You could be sued for patent infringement merely by running
-@command{compress}.
-
 @opindex use-compress-program
 @item --use-compress-program=@var{prog}
 Use external compression program @var{prog}.  Use this option if you
@@ -10272,7 +10377,7 @@ echo $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME >&$TAR_FD
 @end group
 @end smallexample
 
-The same script cant be used while listing, comparing or extracting
+The same script can be used while listing, comparing or extracting
 from the created archive.  For example:
 
 @smallexample
@@ -10914,6 +11019,10 @@ output. Default is 12.
 Right margin of the text output. Used for wrapping.
 @end deftypevr
 
+@node Fixing Snapshot Files
+@appendix Fixing Snapshot Files
+@include tar-snapshot-edit.texi
+
 @node Tar Internals
 @appendix Tar Internals
 @include intern.texi