@settitle GNU tar
@finalout
@smallbook
+@setchapternewpage odd
@c %**end of header
@c ======================================================================
@set xref-file @xref{file}
@set pxref-file @pxref{file}
-@set op-files-from @kbd{--files-from=@var{file-of-names}} (@kbd{-I @var{file-of-names}}, @kbd{-T @var{file-of-names}})
+@set op-files-from @kbd{--files-from=@var{file-of-names}} (@kbd{-T @var{file-of-names}})
@set ref-files-from @ref{files}
@set xref-files-from @xref{files}
@set pxref-files-from @pxref{files}
@defindex op
@syncodeindex op cp
-@ifinfo
+@dircategory GNU Packages
+@direntry
+* Tar: (tar). Making tape (or disk) archives.
+@end direntry
+
+@dircategory Individual utilities
@direntry
-* tar: (tar). Making tape (or disk) archives.
+* tar: (tar)tar invocation. Invoking @sc{gnu} @command{tar}
@end direntry
+@ifinfo
This file documents @sc{gnu} @command{tar}, which creates and extracts
files from archives.
-Published by the Free Software Foundation,
-59 Temple Place - Suite 330,
-Boston, MA 02111-1307, USA
-
-Copyright 1992, 1994, 1995, 1996, 1997, 1999, 2000 Free Software
+Copyright 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001 Free Software
Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
@end ifinfo
-@setchapternewpage odd
-
@shorttitlepage @sc{gnu} @command{tar}
@titlepage
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000 Free Software
-Foundation, Inc.
+Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001
+Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
document. The rest of the menu lists all the lower level nodes.
@end ifnottex
+@c The master menu, created with texinfo-master-menu, goes here.
+@c (However, getdate.texi's menu is interpolated by hand.)
+
@menu
* Introduction::
* Tutorial::
* Date input formats::
* Formats::
* Media::
-* GNU Free Documentation License::
+* Free Software Needs Free Documentation::
+* Copying This Manual::
* Index::
@detailmenu
-
--- The Detailed Node Listing ---
Introduction
* how to update::
-Options used by @code{--create}
+Options Used by @code{--create}
* Ignore Failed Read::
* read full records::
* Ignore Zeros::
-Changing How @command{tar} Extracts Files Over Preexisting Files
+Changing How @command{tar} Writes Files
* Dealing with Old Files::
* Overwrite Old Files::
* Keep Old Files::
* Unlink First::
* Recursive Unlink::
-
-Changing How @command{tar} Writes Files
-
* Modification Times::
* Setting Access Permissions::
* Writing to Standard Output::
Excluding Some Files
+* controlling pattern-patching with exclude::
* problems with exclude::
Crossing Filesystem Boundaries
* Day of week items:: Monday and others.
* Relative items in date strings:: next tuesday, 2 years ago.
* Pure numbers in date strings:: 19931219, 1440.
-* Authors of getdate:: Bellovin, Eggert, Berets, Salz, et al.
+* Authors of getdate:: Bellovin, Eggert, Salz, Berets, et al.
Controlling the Archive Format
* Multi-Volume Archives:: Archives Longer than One Tape or Disk
* Tape Files:: Tape Files
+
+Copying This Manual
+
+* GNU Free Documentation License:: License for copying this manual
+
@end detailmenu
@end menu
exact member names of the members of an archive, use @value{op-list}
(@pxref{list}).
+You can extract a file to standard output by combining the above options
+with the @option{--to-stdout} option (@pxref{Writing to Standard
+Output}).
+
If you give the @value{op-verbose} option, then @value{op-extract} will
print the names of the archive members as it extracts them.
(See @samp{--newer}.) @FIXME-pxref{}
+@item --anchored
+An exclude pattern must match an initial subsequence of the name's components.
+@FIXME-xref{}
+
@item --atime-preserve
Tells @command{tar} to preserve the access time field in a file's inode when
default. @FIXME-xref{}
@item --files-from=@var{file}
-@itemx -I @var{file}
@itemx -T @var{file}
@command{tar} will use the contents of @var{file} as a list of archive members
@command{tar} will print out a short message summarizing the operations and
options to @command{tar} and exit. @FIXME-xref{}
+@item --ignore-case
+Ignore case when excluding files.
+@FIXME-xref{}
+
@item --ignore-failed-read
Do not exit unsuccessfully merely because an unreadable file was encountered.
@itemx -F @var{script-file}
When @command{tar} is performing multi-tape backups, @var{script-file} is run
-at the end of each tape. @FIXME-xref{}
+at the end of each tape. If @var{script-file} exits with nonzero status,
+@command{tar} fails immediately. @FIXME-xref{}
@item --interactive
@itemx --confirmation
@itemx -N
When creating an archive, @command{tar} will only add files that have changed
-since @var{date}. @FIXME-xref{}
+since @var{date}. If @var{date} begins with @samp{/} or @samp{.}, it
+is taken to be the name of a file whose last-modified time specifies
+the date. @FIXME-xref{}
-@item --newer-mtime
+@item --newer-mtime=@var{date}
-In conjunction with @samp{--newer}, @command{tar} will only add files whose
+Like @samp{--newer}, but add only files whose
contents have changed (as opposed to just @samp{--newer}, which will
also back up files for which any status information has changed).
+@item --no-anchored
+An exclude pattern can match any subsequence of the name's components.
+@FIXME-xref{}
+
+@item --no-ignore-case
+Use case-sensitive matching when excluding files.
+@FIXME-xref{}
+
@item --no-recursion
-With this option, @command{tar} will not recurse into directories unless a
-directory is explicitly named as an argument to @command{tar}. @FIXME-xref{}
+With this option, @command{tar} will not recurse into directories.
+@FIXME-xref{}
@item --no-same-owner
the permissions specified in the archive. This is the default behavior
for ordinary users; this option has an effect only for the superuser.
+@item --no-wildcards
+Do not use wildcards when excluding files.
+@FIXME-xref{}
+
+@item --no-wildcards-match-slash
+Wildcards do not match @samp{/} when excluding files.
+@FIXME-xref{}
+
@item --null
When @command{tar} is using the @samp{--files-from} option, this option
Overwrite existing files and directory metadata when extracting files
from an archive. @xref{Overwrite Old Files}.
+@item --overwrite-dir
+
+Overwrite the metadata of existing directories when extracting files
+from an archive. @xref{Overwrite Old Files}.
+
@item --owner=@var{user}
Specifies that @command{tar} should use @var{user} as the owner of members
Instructs @command{tar} to use @var{size} bytes per record when accessing the
archive. @FIXME-xref{}
+@item --recursion
+
+With this option, @command{tar} recurses into directories.
+@FIXME-xref{}
+
@item --recursive-unlink
Remove existing
Used in conjunction with @samp{--multi-volume}. @command{tar} will keep track
of which volume of a multi-volume archive its working in @var{file}.
@FIXME-xref{}
+
+@item --wildcards
+Use wildcards when excluding files.
+@FIXME-xref{}
+
+@item --wildcards-match-slash
+Wildcards match @samp{/} when excluding files.
+@FIXME-xref{}
@end table
@node Short Option Summary
@samp{--incremental}
-@item -I
-
-@samp{--files-from}
-
@item -K
@samp{--starting-file}
the @value{op-keep-old-files} option. It causes @command{tar} to refuse
to replace or update a file that already exists, i.e., a file with the
same name as an archive member prevents extraction of that archive
-member.
+member. Instead, it reports an error.
To be more aggressive about altering existing files, use the
@value{op-overwrite} option. It causes @command{tar} to overwrite
existing files and to follow existing symbolic links when extracting.
+The @option{--overwrite-dir} option is somewhat more conservative than
+@value{op-overwrite}: it overwrites metadata (ownership, permission,
+etc.) for directories, but removes other files before extracting them.
Some people argue that @sc{gnu} @command{tar} should not hesitate to overwrite
files with other files when extracting. When extracting a @command{tar}
can change the contents, ownership or permissions of any file on your
system. Also, many systems do not take kindly to overwriting files that
are currently being executed.
+
+@item --overwrite-dir
+Overwrite the metadata of directories when extracting files from an
+archive, but remove other files before extracting.
@end table
@node Keep Old Files
@table @kbd
@item --files-from=@var{file name}
-@itemx -I @var{file name}
@itemx -T @var{file name}
Get names to extract or create from file @var{file name}.
@end table
If you give a single dash as a file name for @samp{--files-from}, (i.e.,
-you specify either @samp{--files-from=-} or @samp{-I -}) or @samp{-T
--}), then the file names are read from standard input.
+you specify either @samp{--files-from=-} or @samp{-T -}), then the file
+names are read from standard input.
Unless you are running @command{tar} with @samp{--create}, you can not use
both @samp{--files-from=-} and @samp{--file=-} (@samp{-f -}) in the same
@file{src} except for files whose names end in @file{.o}, use the
command @samp{tar -cf src.tar --exclude='*.o' src}.
-A @var{pattern} containing @samp{/} excludes a name if an initial
-subsequence of the name's components matches @var{pattern}; a
-@var{pattern} without @samp{/} excludes a name if it matches any of its
-name components. For example, the pattern @samp{*b/RCS} contains
-@samp{/}, so it excludes @file{blob/RCS} and @file{.blob/RCS/f} but not
-@file{blob/RCSit/RCS} or @file{/blob/RCS}, whereas the pattern
-@samp{RCS} excludes all these names. Conversely, the pattern @samp{*.o}
-lacks @samp{/}, so it excludes @file{.f.o}, @file{d/f.o}, and
-@file{d.o/f}.
-
-Other than optionally stripping leading @samp{/} from names
-(@pxref{absolute}), patterns and candidate names are used as-is. For
-example, trailing @samp{/} is not trimmed from a user-specified name
-before deciding whether to exclude it.
-
You may give multiple @samp{--exclude} options.
@table @kbd
@findex exclude-from
Use the @samp{--exclude-from=@var{file-of-patterns}} option to read a
-list of shell wildcards, one per line, from @var{file}; @command{tar} will
-ignore files matching those regular expressions. Thus if @command{tar} is
+list of patterns, one per line, from @var{file}; @command{tar} will
+ignore files matching those patterns. Thus if @command{tar} is
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.
newlines the same as the files-from option does?}
@menu
+* controlling pattern-patching with exclude::
* problems with exclude::
@end menu
+@node controlling pattern-patching with exclude
+@unnumberedsubsec Controlling Pattern-Matching with the @code{exclude} Options
+
+Normally, a pattern matches a name if an initial subsequence of the
+name's components matches the pattern, where @samp{*}, @samp{?}, and
+@samp{[...]} are the usual shell wildcards, @samp{\} escapes wildcards,
+and wildcards can match @samp{/}.
+
+Other than optionally stripping leading @samp{/} from names
+(@pxref{absolute}), patterns and names are used as-is. For
+example, trailing @samp{/} is not trimmed from a user-specified name
+before deciding whether to exclude it.
+
+However, this matching procedure can be altered by the options listed
+below. These options accumulate. For example:
+
+@example
+--ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
+@end example
+
+ignores case when excluding @samp{makefile}, but not when excluding
+@samp{readme}.
+
+@table @option
+@item --anchored
+@itemx --no-anchored
+If anchored (the default), a pattern must match an initial subsequence
+of the name's components. Otherwise, the pattern can match any subsequence.
+
+@item --ignore-case
+@itemx --no-ignore-case
+When ignoring case, upper-case patterns match lower-case names and vice versa.
+When not ignoring case (the default), matching is case-sensitive.
+
+@item --wildcards
+@itemx --no-wildcards
+When using wildcards (the default), @samp{*}, @samp{?}, and @samp{[...]}
+are the usual shell wildcards, and @samp{\} escapes wildcards.
+Otherwise, none of these characters are special, and patterns must match
+names literally.
+
+@item --wildcards-match-slash
+@itemx --no-wildcards-match-slash
+When wildcards match slash (the default), a wildcard like @samp{*} in
+the pattern can match a @samp{/} in the name. Otherwise, @samp{/} is
+matched only by @samp{/}.
+
+@end table
+
+The @option{--recursion} and @option{--no-recursion} options
+(@pxref{recurse}) also affect how exclude patterns are interpreted. If
+recursion is in effect, a pattern excludes a name if it matches any of
+the name's parent directories.
+
@node problems with exclude
@unnumberedsubsec Problems with Using the @code{exclude} Options
@item
In earlier versions of @command{tar}, what is now the
@samp{--exclude-from=@var{file-of-patterns}} option was called
-@samp{--exclude-@var{pattern}} instead. Now,
+@samp{--exclude=@var{pattern}} instead. Now,
@samp{--exclude=@var{pattern}} applies to patterns listed on the command
line and @samp{--exclude-from=@var{file-of-patterns}} applies to
patterns listed in a file.
The @value{op-after-date} option causes @command{tar} to only work on files
whose modification or inode-changed times are newer than the @var{date}
-given. If you use this option when creating or appending to an archive,
+given. If @var{date} starts with @samp{/} or @samp{.}, it is taken to
+be a file name; the last-modified time of that file is used as the date.
+If you use this option when creating or appending to an archive,
the archive will only include new files. If you use @samp{--after-date}
when extracting an archive, @command{tar} will only extract files newer
than the @var{date} you specify.
Acts on files only if their modification or inode-changed times are
later than @var{date}. Use in conjunction with any operation.
+If @var{date} starts with @samp{/} or @samp{.}, it is taken to be a file
+name; the last-modified time of that file is used as the date.
+
@item --newer-mtime=@var{date}
Acts like @value{op-after-date}, but only looks at modification times.
@end table
@xref{incremental and listed-incremental}.
@end quotation
-To select files newer than the modification time of a file that already
-exists, you can use the @samp{--reference} (@samp{-r}) option of @sc{gnu}
-@command{date}, available in @sc{gnu} shell utilities 1.13 or later. It returns
-the time stamp of the already-existing file; this time stamp expands to
-become the referent date which @samp{--newer} uses to determine which
-files to archive. For example, you could say,
-
-@example
-$ @kbd{tar -cf @var{archive.tar} --newer="`date -r @var{file}`" /home}
-@end example
-
@noindent
@FIXME{which tells -- need to fill this in!}
@table @kbd
@item --no-recursion
Prevents @command{tar} from recursively descending directories.
+
+@item --recursion
+Requires @command{tar} to recursively descend directories.
+This is the default.
@end table
When you use @samp{--no-recursion}, @sc{gnu} @command{tar} grabs directory entries
@command{tar} @emph{usually} recursively descends on directories, they have
to use the @samp{@w{! -d}} option to @command{find} @FIXME{needs more
explanation or a cite to another info file}as they usually do not want
-all the files in a directory. They then use the @value{op-file-from}
+all the files in a directory. They then use the @value{op-files-from}
option to archive the files located via @command{find}.
The problem when restoring files archived in this manner is that the
tell @command{tar} to grab only the directory entries given to it, adding
no new files on its own.
+The @value{op-no-recursion} option also applies when extracting: it
+causes @command{tar} to extract only the matched directory entries, not
+the files under those directories.
+
+The @value{op-no-recursion} option also affects how exclude patterns
+are interpreted (@pxref{controlling pattern-patching with exclude}).
+
@FIXME{example here}
@node one
of file contents is performed.
The @code{name}, @code{linkname}, @code{magic}, @code{uname}, and
-@code{gname} are null-terminated character strings. All other fileds
+@code{gname} are null-terminated character strings. All other fields
are zero-filled octal numbers in ASCII. Each numeric field of width
@var{w} contains @var{w} minus 2 digits, a space, and a null, except
@code{size}, and @code{mtime}, which do not contain the trailing null.
@item -F @var{file}
@itemx --info-script=@var{file}
@itemx --new-volume-script=@var{file}
-Execute @file{file} at end of each tape. This implies
-@value{op-multi-volume}.
+Execute @file{file} at end of each tape. If @file{file} exits with
+nonzero status, exit. This implies @value{op-multi-volume}.
@end table
@node Remote Tape Server
If you want more elaborate behavior than this, give @command{tar} the
@value{op-info-script} option. The file @var{script-name} is expected
to be a program (or shell script) to be run instead of the normal
-prompting procedure. When the program finishes, @command{tar} will
-immediately begin writing the next volume. The behavior of the
+prompting procedure. If the program fails, @command{tar} exits;
+otherwise, @command{tar} begins writing the next volume. The behavior
+of the
@samp{n} response to the normal tape-change prompt is not available
if you use @value{op-info-script}.
@value{op-update} and @value{op-delete} operations. @xref{Operations},
for more information on these operations.
+Also, since @command{tar} normally strips leading @samp{/} from file
+names (@pxref{absolute}), a command like @samp{tar --verify -cf
+/tmp/foo.tar /etc} will work as desired only if the working directory is
+@file{/}, as @command{tar} uses the archive's relative member names
+(e.g., @file{etc/motd}) when verifying the archive.
+
@node Write Protection
@section Write Protection
which can be removed from the center of a tape reel, or some other
changeable feature.
+@node Free Software Needs Free Documentation
+@appendix Free Software Needs Free Documentation
+@include freemanuals.texi
+
+@node Copying This Manual
+@appendix Copying This Manual
+
+@menu
+* GNU Free Documentation License:: License for copying this manual
+@end menu
+
@include fdl.texi
@node Index
-@unnumbered Index
+@appendix Index
@printindex cp