from archives.
Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
-2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@smallexample
@group
-$ @kbd{tar cfv archive /etc/mail}
+$ @kbd{tar --create --verbose --file archive /etc/mail}
tar: Removing leading `/' from member names
/etc/mail/
/etc/mail/sendmail.cf
/etc/mail/aliases
-$ @kbd{tar tf archive}
+$ @kbd{tar --test --file archive}
etc/mail/
etc/mail/sendmail.cf
etc/mail/aliases
@cindex return status
Besides successful exits, @GNUTAR{} may fail for
many reasons. Some reasons correspond to bad usage, that is, when the
-@command{tar} command is improperly written. Errors may be
-encountered later, while encountering an error processing the archive
-or the files. Some errors are recoverable, in which case the failure
-is delayed until @command{tar} has completed all its work. Some
-errors are such that it would not meaningful, or at least risky, to
-continue processing: @command{tar} then aborts processing immediately.
-All abnormal exits, whether immediate or delayed, should always be
-clearly diagnosed on @code{stderr}, after a line stating the nature of
-the error.
+@command{tar} command line is improperly written. Errors may be
+encountered later, while processing the archive or the files. Some
+errors are recoverable, in which case the failure is delayed until
+@command{tar} has completed all its work. Some errors are such that
+it would be not meaningful, or at least risky, to continue processing:
+@command{tar} then aborts processing immediately. All abnormal exits,
+whether immediate or delayed, should always be clearly diagnosed on
+@code{stderr}, after a line stating the nature of the error.
Possible exit codes of @GNUTAR{} are summarized in the following
table:
allow you to perform a variety of tasks. You are required to choose
one operating mode each time you employ the @command{tar} program by
specifying one, and only one operation as an argument to the
-@command{tar} command (two lists of four operations each may be found
+@command{tar} command (the corresponding options may be found
at @ref{frequent operations} and @ref{Operations}). Depending on
circumstances, you may also wish to customize how the chosen operating
mode behaves. For example, you may wish to change the way the output
@itemx -a
During a @option{--create} operation, enables automatic compressed
-format recognition based on the archive suffix. @xref{gzip}.
+format recognition based on the archive suffix. The effect of this
+option is cancelled by @option{--no-auto-compress}. @xref{gzip}.
@opsummary{backup}
@item --backup=@var{backup-type}
This option tells @command{tar} to read or write archives through
@command{lzma}. @xref{gzip}.
+@item --lzop
+
+This option tells @command{tar} to read or write archives through
+@command{lzop}. @xref{gzip}.
+
@opsummary{mode}
@item --mode=@var{permissions}
An exclude pattern can match any subsequence of the name's components.
@xref{controlling pattern-matching}.
+@opsummary{no-auto-compress}
+@item --no-auto-compress
+
+Disables automatic compressed format recognition based on the archive
+suffix. @xref{--auto-compress}. @xref{gzip}.
+
@opsummary{no-check-device}
@item --no-check-device
Do not check device numbers when creating a list of modified files
Print warnings about subprocesses that terminated with a nonzero exit
code. @xref{Writing to an External Program}.
+@opsummary{no-null}
+@item --no-null
+
+If the @option{--null} option was given previously, this option
+cancels its effect, so that any following @option{--files-from}
+options will expect their file lists to be newline-terminated.
+
@opsummary{no-overwrite-dir}
@item --no-overwrite-dir
@xref{Data Modification Times}.
@opsummary{transform}
+@opsummary{xform}
@item --transform=@var{sed-expr}
-
+@itemx --xform=@var{sed-expr}
Transform file or member names using @command{sed} replacement expression
@var{sed-expr}. For example,
@opsummary{use-compress-program}
@item --use-compress-program=@var{prog}
+@itemx -I=@var{prog}
Instructs @command{tar} to access the archive through @var{prog}, which is
presumed to be a compression program of some sort. @xref{gzip}.
@item --wildcards-match-slash
Wildcards match @samp{/}.
@xref{controlling pattern-matching}.
+
+@opsummary{xz}
+@item --xz
+@itemx -J
+Use @command{xz} for compressing or decompressing the archives. @xref{gzip}.
+
@end table
@node Short Option Summary
@item -G @tab @ref{--incremental}.
+@item -J @tab @ref{--xz}.
+
@item -K @tab @ref{--starting-file}.
@item -L @tab @ref{--tape-length}.
@item -o @tab When creating, @ref{--no-same-owner}, when extracting ---
@ref{--portability}.
-The later usage is deprecated. It is retained for compatibility with
+The latter usage is deprecated. It is retained for compatibility with
the earlier versions of @GNUTAR{}. In future releases
@option{-o} will be equivalent to @option{--no-same-owner} only.
every message it would normally produce, the block number within the
archive where the message was triggered. Also, supplementary messages
are triggered when reading blocks full of NULs, or when hitting end of
-file on the archive. As of now, if the archive if properly terminated
+file on the archive. As of now, if the archive is properly terminated
with a NUL block, the reading of the file may stop before end of file
is met, so the position of end of file will not usually show when
@option{--block-number} (@option{-R}) is used. Note that @GNUTAR{}
@vrindex TAR_BLOCKING_FACTOR, checkpoint script environment
@item TAR_BLOCKING_FACTOR
-Current blocking factor (@pxref{Blocking}.
+Current blocking factor (@pxref{Blocking}).
@vrindex TAR_CHECKPOINT, checkpoint script environment
@item TAR_CHECKPOINT
-The checkpoint number.
+Number of the checkpoint.
@vrindex TAR_SUBCOMMAND, checkpoint script environment
@item TAR_SUBCOMMAND
-A short option describing the operation @command{tar} is executing
+A short option describing the operation @command{tar} is executing.
@xref{Operations}, for a complete list of subcommand options.
@vrindex TAR_FORMAT, checkpoint script environment
@itemx -r
Add new entries to an archive that already exists.
@item --update
-@itemx -r
+@itemx -u
Add more recent copies of archive members to the end of an archive, if
they exist.
@item --concatenate
Backup options may prove unexpectedly useful when extracting archives
containing many members having identical name, or when extracting archives
on systems having file name limitations, making different members appear
-has having similar names through the side-effect of name truncation.
-(This is true only if we have a good scheme for truncated backup names,
-which I'm not sure at all: I suspect work is needed in this area.)
+as having similar names through the side-effect of name truncation.
+@FIXME{This is true only if we have a good scheme for truncated backup names,
+which I'm not sure at all: I suspect work is needed in this area.}
When any existing file is backed up before being overwritten by extraction,
then clashing files are automatically be renamed to be unique, and the
true name is kept for only the last file of a series of clashing files.
@option{--files-from}.
@table @option
-@opindex null
+@xopindex{null, described}
@item --null
Only consider @code{NUL} terminated file names, instead of files that
terminate in a newline.
+
+@xopindex{no-null, described}
+@item --no-null
+Undo the effect of any previous @option{--null} option.
@end table
The @option{--null} option is just like the one in @acronym{GNU}
$ @kbd{tar -c -v --null --files-from=long-files --file=big.tar}
@end smallexample
-@FIXME{say anything else here to conclude the section?}
+The @option{--no-null} option can be used if you need to read both
+zero-terminated and newline-terminated files on the same command line.
+For example, if @file{flist} is a newline-terminated file, then the
+following command can be used to combine it with the above command:
+
+@smallexample
+@group
+$ @kbd{find . -size +800 -print0 |
+ tar -c -f big.tar --null -T - --no-null -T flist}
+@end group
+@end smallexample
+
+This example uses short options for typographic reasons, to avoid
+very long lines.
+
+@GNUTAR is able to automatically detect null-terminated file lists, so
+it is safe to use them even without the @option{--null} option. In
+this case @command{tar} will print a warning and continue reading such
+a file as if @option{--null} were actually given:
+
+@smallexample
+@group
+$ @kbd{find . -size +800 -print0 | tar -c -f big.tar -T -}
+tar: -: file name read contains nul character
+@end group
+@end smallexample
+
+The null terminator, however, remains in effect only for this
+particular file, any following @option{-T} options will assume
+newline termination. Of course, the null autodetection applies
+to these eventual surplus @option{-T} options as well.
@node exclude
@section Excluding Some Files
@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:
@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
@command{Tar} archives contain detailed information about files stored
in them and full file names are part of that information. When
-storing file to an archive, its file name is recorded in the archive
+storing file to an archive, its file name is recorded in it,
along with the actual file contents. When restoring from an archive,
a file is created on disk with exactly the same name as that stored
in the archive. In the majority of cases this is the desired behavior
cases it is desirable to store files under differing names in the
archive.
-@GNUTAR{} provides two options for these needs.
+@GNUTAR{} provides several options for these needs.
@table @option
@opindex strip-components
two leading components (@file{usr/} and @file{include/}) off the file
name.
-If you add to the above invocation @option{--verbose} (@option{-v})
-option, you will note that the verbose listing still contains the
+If you add the @option{--verbose} (@option{-v}) option to the invocation
+above, you will note that the verbose listing still contains the
full file name, with the two removed components still in place. This
can be inconvenient, so @command{tar} provides a special option for
altering this behavior:
@end group
@end smallexample
-Notice that in both cases the file is @file{stdlib.h} extracted to the
+Notice that in both cases the file @file{stdlib.h} is extracted to the
current working directory, @option{--show-transformed-names} affects
only the way its name is displayed.
@table @option
@opindex transform
+@opindex xform
@item --transform=@var{expression}
+@itemx --xform=@var{expression}
Modify file names using supplied @var{expression}.
@end table
@var{regexp} and @var{replace} are described in detail in
@ref{The "s" Command, The "s" Command, The `s' Command, sed, GNU sed}.
+Any delimiter can be used in lieue of @samp{/}, the only requirement being
+that it be used consistently throughout the expression. For example,
+the following two expressions are equivalent:
+
+@smallexample
+@group
+s/one/two/
+s,one,two,
+@end group
+@end smallexample
+
+Changing delimiters is often useful when the @var{regex} contains
+slashes. For example, it is more convenient to write @code{s,/,-,} than
+@code{s/\//-/}.
+
As in @command{sed}, you can give several replace expressions,
separated by a semicolon.
@item @var{number}
Only replace the @var{number}th match of the @var{regexp}.
-Note: the @var{posix} standard does not specify what should happen
+Note: the @acronym{POSIX} standard does not specify what should happen
when you mix the @samp{g} and @var{number} modifiers. @GNUTAR{}
follows the GNU @command{sed} implementation in this regard, so
the interaction is defined to be: ignore matches before the
@end table
-Any delimiter can be used in lieue of @samp{/}, the only requirement being
-that it be used consistently throughout the expression. For example,
-the following two expressions are equivalent:
+In addition, several @dfn{transformation scope} flags are supported,
+that control to what files transformations apply. These are:
+
+@table @samp
+@item r
+Apply transformation to regular archive members.
+
+@item R
+Do not apply transformation to regular archive members.
+
+@item s
+Apply transformation to symbolic link targets.
+
+@item S
+Do not apply transformation to symbolic link targets.
+
+@item h
+Apply transformation to hard link targets.
+
+@item H
+Do not apply transformation to hard link targets.
+@end table
+
+Default is @samp{rsh}, which means to apply tranformations to both archive
+members and targets of symbolic and hard links.
+
+Default scope flags can also be changed using @samp{flags=} statement
+in the transform expression. The flags set this way remain in force
+until next @samp{flags=} statement or end of expression, whichever
+occurs first. For example:
@smallexample
-@group
-s/one/two/
-s,one,two,
-@end group
+ --transform 'flags=S;s|^|/usr/local/|'
@end smallexample
-Changing delimiters is often useful when the @var{regex} contains
-slashes. For example, it is more convenient to write @code{s,/,-,} than
-@code{s/\//-/}.
-
Here are several examples of @option{--transform} usage:
@enumerate
$ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar}
@end smallexample
+@item Convert each file name to lower case:
+
+@smallexample
+$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar}
+@end smallexample
+
@item Prepend @file{/prefix/} to each file name:
@smallexample
$ @kbd{tar --transform 's,^,/prefix/,' -x -f arch.tar}
@end smallexample
-@item Convert each file name to lower case:
+@item Archive the @file{/lib} directory, prepending @samp{/usr/local}
+to each archive member:
@smallexample
-$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar}
+$ @kbd{tar --transform 's,^,/usr/local/,S' -c -f arch.tar /lib}
@end smallexample
-
@end enumerate
+Notice the use of flags in the last example. The @file{/lib}
+directory often contains many symbolic links to files within it.
+It may look, for example, like this:
+
+@smallexample
+$ @kbd{ls -l}
+drwxr-xr-x root/root 0 2008-07-08 16:20 /lib/
+-rwxr-xr-x root/root 1250840 2008-05-25 07:44 /lib/libc-2.3.2.so
+lrwxrwxrwx root/root 0 2008-06-24 17:12 /lib/libc.so.6 -> libc-2.3.2.so
+...
+@end smallexample
+
+Using the expression @samp{s,^,/usr/local/,} would mean adding
+@samp{/usr/local} to both regular archive members and to link
+targets. In this case, @file{/lib/libc.so.6} would become:
+
+@smallexample
+ /usr/local/lib/libc.so.6 -> /usr/local/libc-2.3.2.so
+@end smallexample
+
+This is definitely not desired. To avoid this, the @samp{S} flag
+are used, which excludes symbolic link targets from filename
+transformations. The result is:
+
+@smallexample
+$ @kbd{tar --transform 's,^,/usr/local/,S', -c -v -f arch.tar \
+ --show-transformed /lib}
+drwxr-xr-x root/root 0 2008-07-08 16:20 /usr/local/lib/
+-rwxr-xr-x root/root 1250840 2008-05-25 07:44 /usr/local/lib/libc-2.3.2.so
+lrwxrwxrwx root/root 0 2008-06-24 17:12 /usr/local/lib/libc.so.6 ->
+libc-2.3.2.so
+@end smallexample
+
Unlike @option{--strip-components}, @option{--transform} can be used
in any @GNUTAR{} operation mode. For example, the following command
adds files to the archive while replacing the leading @file{usr/}
For example:
@smallexample
-$ @kbd{(cd / && tar -c -f archive.tar home)}
-# @i{or}:
-$ @kbd{tar -c -f archive.tar -C / home}
+$ @kbd{tar -c -f archive.tar -C / home}
@end smallexample
@include getdate.texi
@cindex Compressed archives
@cindex Storing archives in compressed format
+@cindex gzip
+@cindex bzip2
+@cindex lzma
+@cindex lzop
+@cindex compress
@GNUTAR{} is able to create and read compressed archives. It supports
-@command{gzip}, @command{bzip2} and @command{lzma} compression
+@command{gzip}, @command{bzip2}, @command{lzma} and @command{lzop} 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
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,
-@option{--lzma} to create an @asis{LZMA} compressed archive and
+@option{-J} (@option{--xz}) to create an @asis{XZ} archive,
+@option{--lzma} to create an @asis{LZMA} compressed
+archive, @option{--lzop} to create an @asis{LSOP} archive, and
@option{-Z} (@option{--compress}) to use @command{compress} program.
For example:
$ @kbd{tar xf archive.tar.gz}
@end smallexample
+The format recognition algorithm is based on @dfn{signatures}, a
+special byte sequences in the beginning of file, that are specific for
+certain compression formats. If this approach fails, @command{tar}
+falls back to using archive name suffix to determine its format
+(@xref{auto-compress}, for a list of recognized suffixes).
+
The only case when you have to specify a decompression option while
reading the archive is when reading from a pipe or from a tape drive
that does not support random access. However, in this case @GNUTAR{}
@item --auto-compress
@itemx -a
Select a compression program to use by the archive file name
-suffix. The following suffixes are recognized:
+suffix. The following suffixes are recognized:
@multitable @columnfractions 0.3 0.6
@headitem Suffix @tab Compression program
@item @samp{.tbz} @tab @command{bzip2}
@item @samp{.lzma} @tab @command{lzma}
@item @samp{.tlz} @tab @command{lzma}
+@item @samp{.lzo} @tab @command{lzop}
+@item @samp{.xz} @tab @command{xz}
@end multitable
@opindex gzip
So, there are pros and cons. We'll see!
@opindex bzip2
+@item -J
+@itemx --xz
+Filter the archive through @code{xz}. Otherwise like
+@option{--gzip}.
+
@item -j
@itemx --bzip2
Filter the archive through @code{bzip2}. Otherwise like @option{--gzip}.
@item --lzma
Filter the archive through @command{lzma}. Otherwise like @option{--gzip}.
+@opindex lzop
+@item --lzop
+Filter the archive through @command{lzop}. Otherwise like
+@option{--gzip}.
+
@opindex compress
@opindex uncompress
@item -Z
@opindex use-compress-program
@item --use-compress-program=@var{prog}
+@itemx -I=@var{prog}
Use external compression program @var{prog}. Use this option if you
have a compression program that @GNUTAR{} does not support. There
are two requirements to which @var{prog} should comply:
archive signed with your private key:
@smallexample
-$ @kbd{tar -cf foo.tar.gpgz --use-compress=gpgz .}
+$ @kbd{tar -cf foo.tar.gpgz -Igpgz .}
@end smallexample
@noindent
-Likewise, the following command will list its contents:
+Likewise, the command below will list its contents:
@smallexample
-$ @kbd{tar -tf foo.tar.gpgz --use-compress=gpgz .}
+$ @kbd{tar -tf foo.tar.gpgz -Igpgz .}
@end smallexample
@ignore
@item --preserve
Same as both @option{--same-permissions} and @option{--same-order}.
-The @option{--preserve} option has no equivalent short option name.
-It is equivalent to @option{--same-permissions} plus @option{--same-order}.
-
-@FIXME{I do not see the purpose of such an option. (Neither I. FP.)
-Neither do I. --Sergey}
+This option is deprecated, and will be removed in @GNUTAR{} version 1.23.
@end table
use signed checksums, while @GNUTAR{} uses unsigned
checksums while creating archives, as per @acronym{POSIX} standards. On
reading, @GNUTAR{} computes both checksums and
-accept any. It is somewhat worrying that a lot of people may go
+accepts any. 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
projects / chaz / tar / blobdiff