from archives.
Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
-2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
+2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software
+Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
-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 have the freedom to
-copy and modify this GNU manual. Buying copies from the FSF
-supports it in developing GNU and promoting software freedom.''
+Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+A copy of the license is included in the section entitled ``GNU Free
+Documentation License''.
@end quotation
@end copying
@smallexample
@group
-V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header--
--rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at
-byte 32456--
--rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
-lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple
--rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
-hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues
+V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header--
+-rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at byte 32456--
+-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
+lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple
+-rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
+hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues
@end group
@end smallexample
@smallexample
$ @kbd{tar --list --verbose --file=collection.tar folk}
--rw-r--r-- myself user 62 1990-05-23 10:55 folk
+-rw-r--r-- myself/user 62 1990-05-23 10:55 folk
@end smallexample
@cindex listing member and file names
@command{tar} responds:
@smallexample
-drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
--rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues
--rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk
--rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz
--rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar
+drwxrwxrwx myself/user 0 1990-05-31 21:49 practice/
+-rw-r--r-- myself/user 42 1990-05-21 13:29 practice/blues
+-rw-r--r-- myself/user 62 1990-05-23 10:55 practice/folk
+-rw-r--r-- myself/user 40 1990-05-21 13:30 practice/jazz
+-rw-r--r-- myself/user 10240 1990-05-31 21:49 practice/collection.tar
@end smallexample
When you use a directory name as a file name argument, @command{tar} acts on
produces this:
@smallexample
--rw-r--r-- me user 28 1996-10-18 16:31 jazz
--rw-r--r-- me user 21 1996-09-23 16:44 blues
--rw-r--r-- me user 20 1996-09-23 16:44 folk
+-rw-r--r-- me/user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me/user 21 1996-09-23 16:44 blues
+-rw-r--r-- me/user 20 1996-09-23 16:44 folk
@end smallexample
@node extracting files
@smallexample
$ @kbd{tar -xvvf music.tar practice/folk practice/jazz}
--rw-r--r-- me user 28 1996-10-18 16:31 practice/jazz
--rw-r--r-- me user 20 1996-09-23 16:44 practice/folk
+-rw-r--r-- me/user 28 1996-10-18 16:31 practice/jazz
+-rw-r--r-- me/user 20 1996-09-23 16:44 practice/folk
@end smallexample
@noindent
@subsection Old Option Style
@cindex options, old style
@cindex old option style
+@cindex option syntax, traditional
-Like short options, @dfn{old options} are single letters. However, old options
+As far as we know, all @command{tar} programs, @acronym{GNU} and
+non-@acronym{GNU}, support @dfn{old options}: that is, if the first
+argument does not start with @samp{-}, it is assumed to specify option
+letters. @GNUTAR{} supports old options not only for historical
+reasons, but also because many people are used to them. If the first
+argument does not start with a dash, you are announcing the old option
+style instead of the short option style; old options are decoded
+differently.
+
+Like short options, old options are single letters. However, old options
must be written together as a single clumped set, without spaces separating
-them or dashes preceding them@footnote{Beware that if you precede options
-with a dash, you are announcing the short option style instead of the
-old option style; short options are decoded differently.}. This set
+them or dashes preceding them. This set
of letters must be the first to appear on the command line, after the
@command{tar} program name and some white space; old options cannot appear
anywhere else. The letter of an old option is exactly the same letter as
Here, @samp{20} is the argument of @option{-b} and @samp{/dev/rmt0} is
the argument of @option{-f}.
-On the other hand, this old style syntax makes it difficult to match
+The old style syntax can make it difficult to match
option letters with their corresponding arguments, and is often
confusing. In the command @w{@samp{tar cvbf 20 /dev/rmt0}}, for example,
@samp{20} is the argument for @option{-b}, @samp{/dev/rmt0} is the
second example, however, uses @file{z} as the value for option
@samp{f} --- probably not what was intended.
-Old options are kept for compatibility with old versions of @command{tar}.
-
This second example could be corrected in many ways, among which the
following are equivalent:
@kbd{tar cf archive.tar.gz -z file}
@end smallexample
-@cindex option syntax, traditional
-As far as we know, all @command{tar} programs, @acronym{GNU} and
-non-@acronym{GNU}, support old options. @GNUTAR{}
-supports them not only for historical reasons, but also because many
-people are used to them. For compatibility with Unix @command{tar},
-the first argument is always treated as containing command and option
-letters even if it doesn't start with @samp{-}. Thus, @samp{tar c} is
-equivalent to @w{@samp{tar -c}:} both of them specify the
-@option{--create} (@option{-c}) command to create an archive.
-
@node Mixing
@subsection Mixing Option Styles
@item --group=@var{group}
Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group},
-rather than the group from the source file. @var{group} is first decoded
-as a group symbolic name, but if this interpretation fails, it has to be
-a decimal numeric group @acronym{ID}. @xref{override}.
+rather than the group from the source file. @var{group} can specify a
+symbolic name, or a numeric @acronym{ID}, or both as
+@var{name}:@var{id}. @xref{override}.
Also see the comments for the @option{--owner=@var{user}} option.
Specifies that @command{tar} should use @var{user} as the owner of members
when creating archives, instead of the user associated with the source
-file. @var{user} is first decoded as a user symbolic name, but if
-this interpretation fails, it has to be a decimal numeric user @acronym{ID}.
+file. @var{user} can specify a symbolic name, or a numeric
+@acronym{ID}, or both as @var{name}:@var{id}.
@xref{override}.
This option does not affect extraction from archives.
@smallexample
tar (GNU tar) @value{VERSION}
-Copyright (C) 2010 Free Software Foundation, Inc.
-Copyright (C) 2010 Free Software Foundation, Inc.
+Copyright (C) 2011 Free Software Foundation, Inc.
+Copyright (C) 2011 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.
Verbose output appears on the standard output except when an archive is
being written to the standard output, as with @samp{tar --create
---file=- --verbose} (@samp{tar cfv -}, or even @samp{tar cv}---if the
+--file=- --verbose} (@samp{tar cvf -}, or even @samp{tar cv}---if the
installer let standard output be the default archive). In that case
@command{tar} writes verbose output to the standard error stream.
@cindex @samp{Ignoring unknown extended header keyword `%s'}, warning message
@item unknown-keyword
@samp{Ignoring unknown extended header keyword `%s'}
+@kwindex decompress-program
+@item decompress-program
+Controls verbose description of failures occurring when trying to run
+alternative decompressor programs (@pxref{alternative decompression
+programs}). This warning is disabled by default (unless
+@option{--verbose} is used). A common example of what you can get
+when using this warning is:
+
+@smallexample
+$ @kbd{tar --warning=decompress-program -x -f archive.Z}
+tar (child): cannot run compress: No such file or directory
+tar (child): trying gzip
+@end smallexample
+
+This means that @command{tar} first tried to decompress
+@file{archive.Z} using @command{compress}, and, when that
+failed, switched to @command{gzip}.
@end table
@subheading Keywords controlling incremental extraction:
@smallexample
@kbd{tar --create --file=empty-archive.tar --files-from=/dev/null}
-@kbd{tar cfT empty-archive.tar /dev/null}
+@kbd{tar -cf empty-archive.tar -T /dev/null}
@end smallexample
@xopindex{extract, complementary notes}
@smallexample
$ @kbd{tar --list --file=collection.tar}
--rw-r--r-- me user 28 1996-10-18 16:31 jazz
--rw-r--r-- me user 21 1996-09-23 16:44 blues
--rw-r--r-- me user 20 1996-09-23 16:44 folk
--rw-r--r-- me user 20 1996-09-23 16:44 rock
+-rw-r--r-- me/user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me/user 21 1996-09-23 16:44 blues
+-rw-r--r-- me/user 20 1996-09-23 16:44 folk
+-rw-r--r-- me/user 20 1996-09-23 16:44 rock
@end smallexample
@node multiple
@smallexample
$ @kbd{tar --list --verbose --file=collection.tar}
--rw-r--r-- me user 28 1996-10-18 16:31 jazz
--rw-r--r-- me user 21 1996-09-23 16:44 blues
--rw-r--r-- me user 20 1996-09-23 16:44 folk
--rw-r--r-- me user 20 1996-09-23 16:44 rock
--rw-r--r-- me user 58 1996-10-24 18:30 blues
+-rw-r--r-- me/user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me/user 21 1996-09-23 16:44 blues
+-rw-r--r-- me/user 20 1996-09-23 16:44 folk
+-rw-r--r-- me/user 20 1996-09-23 16:44 rock
+-rw-r--r-- me/user 58 1996-10-24 18:30 blues
@end smallexample
@noindent
@smallexample
$ @kbd{tar --extract -vv --occurrence --file=collection.tar blues}
--rw-r--r-- me user 21 1996-09-23 16:44 blues
+-rw-r--r-- me/user 21 1996-09-23 16:44 blues
@end smallexample
@xref{Writing}, for more information on @option{--extract} and
@smallexample
$ @kbd{tar -tvf bluesrock.tar}
--rw-r--r-- melissa user 105 1997-01-21 19:42 blues
--rw-r--r-- melissa user 33 1997-01-20 15:34 rock
+-rw-r--r-- melissa/user 105 1997-01-21 19:42 blues
+-rw-r--r-- melissa/user 33 1997-01-20 15:34 rock
$ @kbd{tar -tvf jazzfolk.tar}
--rw-r--r-- melissa user 20 1996-09-23 16:44 folk
--rw-r--r-- melissa user 65 1997-01-30 14:15 jazz
+-rw-r--r-- melissa/user 20 1996-09-23 16:44 folk
+-rw-r--r-- melissa/user 65 1997-01-30 14:15 jazz
@end smallexample
We can concatenate these two archives with @command{tar}:
Specifies that @command{tar} should use @var{user} as the owner of members
when creating archives, instead of the user associated with the source
-file. The argument @var{user} can be either an existing user symbolic
-name, or a decimal numeric user @acronym{ID}.
+file.
+
+If @var{user} contains a colon, it is taken to be of the form
+@var{name}:@var{id} where a nonempty @var{name} specifies the user
+name and a nonempty @var{id} specifies the decimal numeric user
+@acronym{ID}. If @var{user} does not contain a colon, it is taken to
+be a user number if it is one or more decimal digits; otherwise it is
+taken to be a user name.
+
+If a name is given but no number, the number is inferred from the
+current host's user database if possible, and the file's user number
+is used otherwise. If a number is given but no name, the name is
+inferred from the number if possible, and an empty name is used
+otherwise. If both name and number are given, the user database is
+not consulted, and the name and number need not be valid on the
+current host.
There is no value indicating a missing number, and @samp{0} usually means
@code{root}. Some people like to force @samp{0} as the value to offer in
@opindex group
Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group},
-rather than the group from the source file. The argument @var{group}
-can be either an existing group symbolic name, or a decimal numeric group @acronym{ID}.
+rather than the group from the source file. As with @option{--owner},
+the argument @var{group} can be an existing group symbolic name, or a
+decimal numeric group @acronym{ID}, or @var{name}:@var{id}.
@end table
@node Ignore Failed Read
For example:
@smallexample
-$ @kbd{tar cfz archive.tar.gz .}
+$ @kbd{tar czf archive.tar.gz .}
@end smallexample
You can also let @GNUTAR{} select the compression program based on
compression:
@smallexample
-$ @kbd{tar cfa archive.tar.bz2 .}
+$ @kbd{tar caf archive.tar.bz2 .}
@end smallexample
@noindent
whereas the following one will use @command{lzma}:
@smallexample
-$ @kbd{tar cfa archive.tar.lzma .}
+$ @kbd{tar caf archive.tar.lzma .}
@end smallexample
For a complete list of file name suffixes recognized by @GNUTAR{},
falls back to using archive name suffix to determine its format
(@pxref{auto-compress}, for a list of recognized suffixes).
+@anchor{alternative decompression programs}
+@cindex alternative decompression programs
+Some compression programs are able to handle different compression
+formats. @GNUTAR{} uses this, if the principal decompressor for the
+given format is not available. For example, if @command{compress} is
+not installed, @command{tar} will try to use @command{gzip}. As of
+version @value{VERSION} the following alternatives are
+tried@footnote{To verbosely trace the decompressor selection, use the
+@option{--warning=decompress-program} option
+(@pxref{warnings,decompress-program}).}:
+
+@multitable @columnfractions 0.3 0.3 0.3
+@headitem Format @tab Main decompressor @tab Alternatives
+@item compress @tab compress @tab gzip
+@item lzma @tab lzma @tab xz
+@item bzip2 @tab bzip2 @tab lbzip2
+@end multitable
+
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{}
invocation of @GNUTAR{}:
@smallexample
-$ @kbd{cat archive.tar.gz | tar tfz -}
+$ @kbd{cat archive.tar.gz | tar tzf -}
@end smallexample
Notice also, that there are several restrictions on operations on
use @env{GZIP} as in the example below:
@smallexample
-$ @kbd{GZIP=--best tar cfz archive.tar.gz subdir}
+$ @kbd{GZIP=--best tar czf archive.tar.gz subdir}
@end smallexample
@noindent
@smallexample
@group
-$ ls
--rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one
--rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden
+$ ls -l
+-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one
+-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden
@end group
@end smallexample
the following:
@smallexample
-$ tar cfvv ../archive.tar .
+$ tar cvvf ../archive.tar .
drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./
-rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden
hrw-r--r-- gray/staff 0 2007-10-30 15:11 ./one link to ./jeden
@smallexample
$ @kbd{tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 @var{files}}
-$ @kbd{tar cMff /dev/tape0 /dev/tape1 @var{files}}
+$ @kbd{tar -cM -f /dev/tape0 -f /dev/tape1 @var{files}}
@end smallexample
The second method is to use the @samp{n} response to the tape-change
@smallexample
@group
$ @kbd{tar --verbose --list --file=iamanarchive}
-V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header--
--rw-r--r-- ringo user 40 1990-05-21 13:30 iamafilename
+V--------- 0/0 0 1992-03-07 12:01 iamalabel--Volume Header--
+-rw-r--r-- ringo/user 40 1990-05-21 13:30 iamafilename
@end group
@end smallexample
@smallexample
@group
-$ @kbd{tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`"}
+$ @kbd{tar -cM -f /dev/tape -V "Daily backup for `date +%Y-%m-%d`"}
$ @kbd{tar --create --file=/dev/tape --multi-volume \
--label="Daily backup for `date +%Y-%m-%d`"}
@end group
projects / chaz / tar / blobdiff