X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=993db4cfef7321b538c4e5c0a2625f78f4d228c0;hb=d5f2066cac82e84ba43e22c9718e381732f8454d;hp=1084e47696f2dbb93508a914eba38510073558a5;hpb=5099ddf6cc764dcb55c42a5d5a3415ce03ac191c;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index 1084e47..993db4c 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -35,7 +35,7 @@ This manual is for @acronym{GNU} @command{tar} (version from archives. Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, -2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -45,9 +45,9 @@ Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License". -(a) The FSF's Back-Cover Text is: ``You are free to copy and modify -this GNU Manual. Buying copies from GNU Press supports the FSF in -developing GNU and promoting software freedom.'' +(a) The FSF's Back-Cover Text is: ``You have the freedom to +copy and modify this GNU manual. Buying copies from the FSF +supports it in developing GNU and promoting software freedom.'' @end quotation @end copying @@ -453,11 +453,8 @@ concepts of using a Unix-type operating system; @pxref{Tutorial}.) The third chapter presents the remaining five operations, and information about using @command{tar} options and option syntax. -@FIXME{this sounds more like a @acronym{GNU} Project Manuals Concept [tm] more -than the reality. should think about whether this makes sense to say -here, or not.} The other chapters are meant to be used as a -reference. Each chapter presents everything that needs to be said -about a specific topic. +The other chapters are meant to be used as a reference. Each chapter +presents everything that needs to be said about a specific topic. One of the chapters (@pxref{Date input formats}) exists in its entirety in other @acronym{GNU} manuals, and is mostly self-contained. @@ -687,7 +684,7 @@ change between directories; and how to figure out where you are in the file system. You should have some basic understanding of directory structure and how files are named according to which directory they are in. You should understand concepts such as standard output and standard -input, what various definitions of the term ``argument'' mean, and the +input, what various definitions of the term @samp{argument} mean, and the differences between relative and absolute file names. @FIXME{and what else?} @@ -752,10 +749,9 @@ You can write most of the @command{tar} operations and options in any of three forms: long (mnemonic) form, short form, and old style. Some of the operations and options have no short or ``old'' forms; however, the operations and options which we will cover in this tutorial have -corresponding abbreviations. @FIXME{make sure this is still the case, -at the end}We will indicate those abbreviations appropriately to get -you used to seeing them. (Note that the ``old style'' option forms -exist in @GNUTAR{} for compatibility with Unix +corresponding abbreviations. We will indicate those abbreviations +appropriately to get you used to seeing them. (Note that the ``old +style'' option forms exist in @GNUTAR{} for compatibility with Unix @command{tar}. In this book we present a full discussion of this way of writing options and operations (@pxref{Old Options}), and we discuss the other two styles of writing options (@xref{Long Options}, and @@ -1765,6 +1761,7 @@ use @w{@kbd{tar --list --verbose}} to list them correctly. @node going further @section Going Further Ahead in this Manual +@UNREVISED @FIXME{need to write up a node here about the things that are going to be in the rest of the manual.} @@ -2440,6 +2437,12 @@ record. @xref{Blocking Factor}. This option tells @command{tar} to read or write archives through @code{bzip2}. @xref{gzip}. +@opsummary{check-device} +@item --check-device +Check device numbers when creating a list of modified files for +incremental archiving. This is the default. @xref{device numbers}, +for a detailed description. + @opsummary{checkpoint} @item --checkpoint[=@var{number}] @@ -2460,6 +2463,13 @@ for a complete description. The @var{action} argument can be one of the following: @table @asis +@item bell +Produce an audible bell on the console. + +@item dot +@itemx . +Print a single dot on the standard listing stream. + @item echo Display a textual message on the standard error, with the status and number of the checkpoint. This is the default. @@ -2468,20 +2478,19 @@ number of the checkpoint. This is the default. Display @var{string} on the standard error. Before output, the string is subject to meta-character expansion. -@item dot -@itemx . -Print a single dot on the standard listing stream. +@item exec=@var{command} +Execute the given @var{command}. @item sleep=@var{time} Wait for @var{time} seconds. -@item exec=@var{command} -Execute the given @var{command}. +@item ttyout=@var{string} +Output @var{string} on the current console (@file{/dev/tty}). @end table Several @option{--checkpoint-action} options can be specified. The supplied actions will be executed in order of their appearance in the -command line. +command line. Using @option{--checkpoint-action} without @option{--checkpoint} assumes default checkpoint frequency of one checkpoint per 10 records. @@ -2587,7 +2596,7 @@ named @var{file}, but dump the directory node itself. @xref{exclude}. @item --exclude-tag-all=@var{file} Exclude from dump any directory containing file named @var{file}. -@xref{exclude}. +@xref{exclude}. @opsummary{exclude-vcs} @item --exclude-vcs @@ -2834,6 +2843,12 @@ changed). @xref{after}. An exclude pattern can match any subsequence of the name's components. @xref{controlling pattern-matching}. +@opsummary{no-check-device} +@item --no-check-device +Do not check device numbers when creating a list of modified files +for incremental archiving. @xref{device numbers}, for +a detailed description. + @opsummary{no-delay-directory-restore} @item --no-delay-directory-restore @@ -3434,7 +3449,7 @@ successfully. For example, @w{@samp{tar --version}} might print: @smallexample tar (GNU tar) @value{VERSION} -Copyright (C) 2006 Free Software Foundation, Inc. +Copyright (C) 2008 Free Software Foundation, Inc. This is free software. You may redistribute copies of it under the terms of the GNU General Public License . There is NO WARRANTY, to the extent permitted by law. @@ -3805,6 +3820,26 @@ audible bell and the message described above at each checkpoint: --checkpoint-action='echo=\aHit %s checkpoint #%u' @end smallexample +@cindex @code{bell}, checkpoint action +There is also a special action which produces an audible signal: +@samp{bell}. It is not equivalent to @samp{echo='\a'}, because +@samp{bell} sends the bell directly to the console (@file{/dev/tty}), +whereas @samp{echo='\a'} sends it to the standard error. + +@cindex @code{ttyout}, checkpoint action +The @samp{ttyout=@var{string}} action outputs @var{string} to +@file{/dev/tty}, so it can be used even if the standard output is +redirected elsewhere. The @var{string} is subject to the same +modifications as with @samp{echo} action. In contrast to the latter, +@samp{ttyout} does not prepend @command{tar} executable name to the +string, nor does it output a newline after it. For example, the +following action will print the checkpoint message at the same screen +line, overwriting any previous message: + +@smallexample +--checkpoint-action="ttyout=\rHit %s checkpoint #%u" +@end smallexample + @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 @@ -3822,7 +3857,7 @@ as shown in the previous section. @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 -checkpoint: +checkpoint: @smallexample $ @kbd{tar -c --checkpoint=1000 --checkpoint-action=sleep=30} @@ -3849,6 +3884,10 @@ additional arguments. Its exit code is ignored. It gets a copy of @item TAR_ARCHIVE The name of the archive @command{tar} is processing. +@vrindex TAR_BLOCKING_FACTOR, checkpoint script environment +@item TAR_BLOCKING_FACTOR +Current blocking factor (@pxref{Blocking}. + @vrindex TAR_CHECKPOINT, checkpoint script environment @item TAR_CHECKPOINT The checkpoint number. @@ -3883,7 +3922,7 @@ This example also illustrates the fact that @option{--checkpoint-action} can be used without @option{--checkpoint}. In this case, the default checkpoint frequency (at each 10th record) is assumed. - + @node interactive @section Asking for Confirmation During Operations @cindex Interactive operation @@ -5646,21 +5685,40 @@ 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. +@anchor{device numbers} @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 +obviously are supposed to be a non-volatile values. However, it turns +out that @acronym{NFS} devices have undependable values when an automounter gets in the picture. This can lead to a great deal of spurious redumping in incremental dumps, so it is somewhat useless to compare -two NFS devices numbers over time. The solution implemented currently -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. +two @acronym{NFS} devices numbers over time. The solution implemented +currently is to considers all @acronym{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. + +Apart from using @acronym{NFS}, there are a number of cases where +relying on device numbers can cause spurious redumping of unmodified +files. For example, this occurs when archiving @acronym{LVM} snapshot +volumes. To avoid this, use @option{--no-check-device} option: + +@table @option +@xopindex{no-check-device, described} +@item --no-check-device +Do not rely on device numbers when preparing a list of changed files +for an incremental dump. + +@xopindex{check-device, described} +@item --check-device +Use device numbers when preparing a list of changed files +for an incremental dump. This is the default behavior. The purpose +of this option is to undo the effect of the @option{--no-check-device} +if it was given in @env{TAR_OPTIONS} environment variable +(@pxref{TAR_OPTIONS}). +@end table -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. +There is also another way to cope with changing device numbers. It is +described in detail in @ref{Fixing Snapshot Files}. Note that incremental archives use @command{tar} extensions and may not be readable by non-@acronym{GNU} versions of the @command{tar} program. @@ -5871,7 +5929,7 @@ their support files using the same file name that is used on the machine where the scripts are run (i.e., what @command{pwd} will print when in that directory on that machine). If the host that contains the file system does not have this capability, you can specify another -host as long as it can access the file system through NFS. +host as long as it can access the file system through @acronym{NFS}. If the list of file systems is very long you may wish to put it in a separate file. This file is usually named @@ -6758,10 +6816,16 @@ However, empty lines are OK. @cindex CVS, excluding files @cindex SVN, excluding files @cindex git, excluding files +@cindex Bazaar, excluding files +@cindex Arch, excluding files +@cindex Mercurial, excluding files +@cindex Darcs, excluding files @table @option @opindex exclude-vcs @item --exclude-vcs -Exclude files and directories used by some version control systems. +Exclude files and directories used by following version control +systems: @samp{CVS}, @samp{RCS}, @samp{SCCS}, @samp{SVN}, @samp{Arch}, +@samp{Bazaar}, @samp{Mercurial}, and @samp{Darcs}. @end table As of version @value{VERSION}, the following files are excluded: @@ -6779,6 +6843,13 @@ As of version @value{VERSION}, the following files are excluded: @item @file{=RELEASE-ID} @item @file{=meta-update} @item @file{=update} +@item @file{.bzr} +@item @file{.bzrignore} +@item @file{.bzrtags} +@item @file{.hg} +@item @file{.hgignore} +@item @file{.hgrags} +@item @file{_darcs} @end itemize @findex exclude-caches @@ -7254,7 +7325,7 @@ $ @kbd{tar tf arch.tar --quoting-style=literal} ./a'single'quote ./a"double"quote ./a\backslash -./a tab +./a tab ./a newline @end group @@ -7276,7 +7347,7 @@ $ @kbd{tar tf arch.tar --quoting-style=shell} './a'\''single'\''quote' './a"double"quote' './a\backslash' -'./a tab' +'./a tab' './a newline' @end group @@ -7294,7 +7365,7 @@ $ @kbd{tar tf arch.tar --quoting-style=shell-always} './a'\''single'\''quote' './a"double"quote' './a\backslash' -'./a tab' +'./a tab' './a newline' @end group @@ -7535,6 +7606,9 @@ replacement for each file name part that matches @var{regexp}. Both @var{regexp} and @var{replace} are described in detail in @ref{The "s" Command, The "s" Command, The `s' Command, sed, GNU sed}. +As in @command{sed}, you can give several replace expressions, +separated by a semicolon. + Supported @var{flags} are: @table @samp @@ -7628,6 +7702,18 @@ If both @option{--strip-components} and @option{--transform} are used together, then @option{--transform} is applied first, and the required number of components is then stripped from its result. +You can use as many @option{--transform} options in a single command +line as you want. The specified expressions will then be applied in +order of their appearance. For example, the following two invocations +are equivalent: + +@smallexample +$ @kbd{tar -cf arch.tar --transform='s,/usr/var,/var/' \ + --transform='s,/usr/local,/usr/,'} +$ @kbd{tar -cf arch.tar \ + --transform='s,/usr/var,/var/;s,/usr/local,/usr/,'} +@end smallexample + @node after @section Operating Only on New Files @UNREVISED @@ -8183,7 +8269,7 @@ Creating a compressed archive is simple: you just specify a 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, -@command{lzma} to create an @asis{LZMA} compressed archive and +@option{--lzma} to create an @asis{LZMA} compressed archive and @option{-Z} (@option{--compress}) to use @command{compress} program. For example: @@ -8209,7 +8295,7 @@ $ @kbd{tar cfa archive.tar.lzma .} @end smallexample For a complete list of file name suffixes recognized by @GNUTAR{}, -@ref{auto-compress}. +@ref{auto-compress}. Reading compressed archive is even simpler: you don't need to specify any additional options as @GNUTAR{} recognizes its format @@ -8243,11 +8329,12 @@ $ @kbd{cat archive.tar.gz | tar tfz -} Notice also, that there are several restrictions on operations on compressed archives. First of all, compressed archives cannot be -modified, i.e., you cannot update (@option{--update} (@option{-u})) them or delete -(@option{--delete}) members from them. Likewise, you cannot append -another @command{tar} archive to a compressed archive using -@option{--append} (@option{-r})). Secondly, multi-volume archives cannot be -compressed. +modified, i.e., you cannot update (@option{--update} (@option{-u})) +them or delete (@option{--delete}) members from them or +add (@option{--append} (@option{-r})) members to them. Likewise, you +cannot append another @command{tar} archive to a compressed archive using +@option{--concatenate} (@option{-A})). Secondly, multi-volume +archives cannot be compressed. The following table summarizes compression options used by @GNUTAR{}. @@ -8958,7 +9045,7 @@ from @var{string} after making the following substitutions: result of the @command{dirname} utility on the translated file name. @item %f @tab The name of the file with the directory information stripped, equivalent to the result of the @command{basename} utility -on the translated file name. +on the translated file name. @item %p @tab The process @acronym{ID} of the @command{tar} process. @item %% @tab A @samp{%} character. @end multitable @@ -10621,6 +10708,10 @@ environment variables: @item TAR_ARCHIVE The name of the archive @command{tar} is processing. +@vrindex TAR_BLOCKING_FACTOR, info script environment variable +@item TAR_BLOCKING_FACTOR +Current blocking factor (@pxref{Blocking}. + @vrindex TAR_VOLUME, info script environment variable @item TAR_VOLUME Ordinal number of the volume @command{tar} is about to start. @@ -10682,7 +10773,7 @@ name=`expr $TAR_ARCHIVE : '\(.*\)-.*'` case $TAR_SUBCOMMAND in -c) ;; -d|-x|-t) test -r $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME || exit 1 - ;; + ;; *) exit 1 esac