@item File name.
If the name contains any special characters (white space, newlines,
-etc.) these are displayed in an unambiguous form using so called
+etc.)@: these are displayed in an unambiguous form using so called
@dfn{quoting style}. For the detailed discussion of available styles
and on how to use them, see @ref{quoting styles}.
Treat all input file or member names literally, do not interpret
escape sequences. @xref{input name quoting}.
+@opsummary{no-verbatim-files-from}
+@item --no-verbatim-files-from
+
+Instructs @GNUTAR{} to treat each line read from a file list as if it
+were supplied in the command line. I.e., leading and trailing
+whitespace is removed and, if the result begins with a dash, it is
+treated as a @GNUTAR{} command line option.
+
+This is default behavior. This option is provided as a way to restore
+it after @option{--verbatim-files-from} option.
+
+It is implied by the @option{--no-null} option.
+
+@xref{no-verbatim-files-from}.
+
@opsummary{no-wildcards}
@item --no-wildcards
Do not use wildcards.
@item --null
When @command{tar} is using the @option{--files-from} option, this option
-instructs @command{tar} to expect file names terminated with @acronym{NUL}, so
-@command{tar} can correctly work with file names that contain newlines.
+instructs @command{tar} to expect file names terminated with
+@acronym{NUL}, and to process file names verbatim.
+
+This means that @command{tar} correctly works with file names that
+contain newlines or begin with a dash.
+
@xref{nul}.
+See also @ref{verbatim-files-from}.
+
@opsummary{numeric-owner}
@item --numeric-owner
tarbombs. In the absence of @var{dir} argument, the name of the new directory
will be equal to the base name of the archive (file name minus the
archive suffix, if recognized). Any member names that do not begin
-with that directory name (after
+with that directory name (after
transformations from @option{--transform} and
@option{--strip-components}) will be prefixed with it. Recognized
file name suffixes are @samp{.tar}, and any compression suffixes
Display file modification dates in @acronym{UTC}. This option implies
@option{--verbose}.
+@opsummary{verbatim-files-from}
+@item --verbatim-files-from
+
+Instructs @GNUTAR{} to treat each line read from a file list as a file
+name, even if it starts with a dash.
+
+File lists are supplied with the @option{--files-from} (@option{-T})
+option. By default, each line read from a file list is first trimmed
+off the leading and trailing whitespace and, if the result begins with
+a dash, it is treated as a @GNUTAR{} command line option.
+
+Use the @option{--verbatim-files-from} option to disable this special
+handling. This facilitates the use of @command{tar} with file lists
+created by @command{file} command.
+
+This option affects all @option{--files-from} options that occur after
+it in the command line. Its effect is reverted by the
+@option{--no-verbatim-files-from} option.
+
+This option is implied by the @option{--null} option.
+
+@xref{verbatim-files-from}.
+
@opsummary{verbose}
@item --verbose
@itemx -v
@smallexample
tar (GNU tar) @value{VERSION}
-Copyright (C) 2013-2014 Free Software Foundation, Inc.
+Copyright (C) 2013-2015 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.
@subheading Keywords applicable for @command{tar --extract}
@table @asis
+@kwindex existing-file
+@cindex @samp{%s: skipping existing file}, warning message
+@item existing-file
+@samp{%s: skipping existing file}
@kwindex timestamp
@cindex @samp{implausibly old time stamp %s}, warning message
@cindex @samp{time stamp %s is %s s in the future}, warning message
for more detail).
Notice, that @var{command} is executed once for each regular file
-extracted. Non-regular files (directories, etc.) are ignored when this
+extracted. Non-regular files (directories, etc.)@: are ignored when this
option is used.
@end table
you specify either @code{--files-from=-} or @code{-T -}), then the file
names are read from standard input.
-Unless you are running @command{tar} with @option{--create}, you can not use
+Unless you are running @command{tar} with @option{--create}, you cannot use
both @code{--files-from=-} and @code{--file=-} (@code{-f -}) in the same
command.
@end smallexample
@noindent
-In the file list given by @option{-T} option, any file name beginning
-with @samp{-} character is considered a @command{tar} option and is
+By default, each line read from the file list is first stripped off
+any leading and trailing whitespace. If the resulting string begins
+with @samp{-} character, it is considered a @command{tar} option and is
processed accordingly@footnote{Versions of @GNUTAR{} up to 1.15.1
recognized only @option{-C} option in file lists, and only if the
option and its argument occupied two consecutive lines.}. For example,
@end group
@end smallexample
+@anchor{verbatim-files-from}
+@opindex verbatim-files-from
+If such option handling is undesirable, use the
+@option{--verbatim-files-from} option. When this option is in effect,
+each line read from the file list is treated as a file name. Notice,
+that this means, in particular, that no whitespace trimming is
+performed.
+
+@anchor{no-verbatim-files-from}
+@opindex no-verbatim-files-from
+The @option{--verbatim-files-from} affects all @option{-T} options
+that follow it in the command line. The default behavior can be
+restored using @option{--no-verbatim-files-from} option.
+
@opindex add-file
-If you happen to have a file whose name starts with @samp{-},
-precede it with @option{--add-file} option to prevent it from
-being recognized as an option. For example: @code{--add-file=--my-file}.
+To disable option handling for a single file name, use the
+@option{--add-file} option, e.g.: @code{--add-file=--my-file}.
@menu
* nul::
@command{xargs} and @command{cpio}, and is useful with the
@option{-print0} predicate of @acronym{GNU} @command{find}. In
@command{tar}, @option{--null} also disables special handling for
-file names that begin with dash.
+file names that begin with dash (similar to
+@option{--verbatim-files-from} option).
This example shows how to use @command{find} to generate a list of files
larger than 800K in length and put that list into a file called
@cindex Git, ignore files
@cindex Bazaar, ignore files
@cindex Mercurial, ignore files
-When archiving directories that are under some version control system (VCS),
+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:
+following options provide such possibility:
@table @option
@anchor{exclude-vcs-ignores}
Do not apply transformation to hard link targets.
@end table
-Default is @samp{rsh}, which means to apply tranformations to both archive
+Default is @samp{rsh}, which means to apply transformations to both archive
members and targets of symbolic and hard links.
Default scope flags can also be changed using @samp{flags=} statement
$ @kbd{tar -c -f foo.tar --files-from list}
@end smallexample
-The interpretation of @option{--directory} is disabled by
-@option{--null} option.
+The interpretation of options in file lists is disabled by
+@option{--verbatim-files-from} and @option{--null} options.
@node absolute
@subsection Absolute File Names
However, this format is designed in such a way that any tar
implementation able to read @samp{ustar} archives will be able to read
most @samp{posix} archives as well, with the only exception that any
-additional information (such as long file names etc.) will in such
+additional information (such as long file names etc.)@: will in such
case be extracted as plain text files along with the files it refers to.
This archive format will be the default format for future versions
compressor names along with each of these options.
You can use any of these options on physical devices (tape drives,
-etc.) and remote files as well as on normal files; data to or from
+etc.)@: and remote files as well as on normal files; data to or from
such devices or remote files is reblocked by another copy of the
@command{tar} program to enforce the specified (or default) record
-size. The default compression parameters are used. Most compression
-programs let you override these by setting a program-specific
-environment variable. For example, with @command{gzip} you can set
-@env{GZIP}:
-
-@smallexample
-$ @kbd{GZIP='-9 -n' tar czf archive.tar.gz subdir}
-@end smallexample
-Another way would be to use the @option{-I} option instead (see
+size. The default compression parameters are used.
+You can override them by using the @option{-I} option (see
below), e.g.:
@smallexample
@end smallexample
@noindent
-Finally, the third, traditional, way to do this is to use a pipe:
+A more traditional way to do this is to use a pipe:
@smallexample
$ @kbd{tar cf - subdir | gzip -9 -n > archive.tar.gz}
@item --use-compress-program=@var{command}
@itemx -I=@var{command}
Use external compression program @var{command}. Use this option if you
+want to specify options for the compression program, or if you
are not happy with the compression program associated with the suffix
-at compile time or if you have a compression program that @GNUTAR{}
+at compile time, or if you have a compression program that @GNUTAR{}
does not support. The @var{command} argument is a valid command
invocation, as you would type it at the command line prompt, with any
additional options as needed. Enclose it in quotes if it contains
-white space (see @ref{external, Running External Commands}, for more detail).
+white space (@pxref{external, Running External Commands}).
The @var{command} should follow two conventions:
@node Attributes
@section Handling File Attributes
-@cindex atrributes, files
+@cindex attributes, files
@cindex file attributes
When @command{tar} reads files, it updates their access times. To
record of the file system contents and makes archives more compact, it
may present some difficulties when extracting individual members from
the archive. For example, trying to extract file @file{one} from the
-archive created in previous examples produces, in the absense of file
+archive created in previous examples produces, in the absence of file
@file{jeden}:
@smallexample
@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}.
-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
This keyword defines the value of the @samp{mtime} field that
is written into the ustar header blocks for the extended headers.
By default, the @samp{mtime} field is set to the modification time
-of the archive member described by that extended headers.
+of the archive member described by that extended header (or to the
+value of the @option{--mtime} option, if supplied).
@item globexthdr.name=@var{string}
This keyword allows user control over the name that is written into
--pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0
@end smallexample
+@noindent
+If you extract files from such an archive and recreate the archive
+from them, you will also need to eliminate changes due to ctime, as
+shown in examples below:
+
+@smallexample
+--pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0,ctime:=0
+@end smallexample
+
+@noindent
+or
+
+@smallexample
+--pax-option=exthdr.name=%d/PaxHeaders/%f,atime:=0,delete=ctime
+@end smallexample
+
@node Checksumming
@subsection Checksumming Problems
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
-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.
-@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
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.
@node Split Recovery
@subsubsection Extracting Members Split Between Volumes
-@cindex Mutli-volume archives, extracting using non-GNU tars
+@cindex Multi-volume archives, extracting using non-GNU tars
If a member is split between several volumes of an old GNU format archive
most third party @command{tar} implementation will fail to extract
it. To extract it, use @command{tarcat} program (@pxref{Tarcat}).
$ @kbd{tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf -}
@end smallexample
-@cindex Mutli-volume archives in PAX format, extracting using non-GNU tars
+@cindex Multi-volume archives in PAX format, extracting using non-GNU tars
You could use this approach for most (although not all) PAX
format archives as well. However, extracting split members from a PAX
archive is a much easier task, because PAX volumes are constructed in
@end smallexample
@noindent
-where symbols preceeded by @samp{%} are @dfn{macro characters} that
+where symbols preceded by @samp{%} are @dfn{macro characters} that
have the following meaning:
@multitable @columnfractions .25 .55
@noindent
The program behaves the same way all UNIX utilities do: it will keep
-quiet unless it has simething important to tell you (e.g. an error
+quiet unless it has something important to tell you (e.g. an error
condition or something). If you wish it to produce verbose output,
similar to that from the dry run mode, use @option{-v} option:
@cindex absolute file names
Unless you use the @option{--absolute-names} (@option{-P}) option,
@GNUTAR{} will not allow you to create an archive that contains
-absolute file names (a file name beginning with @samp{/}.) If you try,
+absolute file names (a file name beginning with @samp{/}). If you try,
@command{tar} will automatically remove the leading @samp{/} from the
file names it stores in the archive. It will also type a warning
message telling you what it is doing.
projects / chaz / tar / blobdiff