@set xref-blocking-factor @xref{Blocking Factor}
@set pxref-blocking-factor @pxref{Blocking Factor}
-@set op-bzip2 @kbd{--bzip2} (@kbd{--bunzip2})
+@set op-bzip2 @kbd{--bzip2} (@kbd{-y})
@set ref-bzip2 @ref{gzip}
@set xref-bzip2 @xref{gzip}
@set pxref-bzip2 @pxref{gzip}
This file documents GNU @code{tar}, a utility used to store, backup, and
transport files.
-Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999 Free Software Foundation, Inc.
+Copyright 1992, 1994, 1995, 1996, 1997, 1999 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@cindex bug reports
@cindex reporting bugs
If you find problems or have suggestions about this program or manual,
-please report them to @file{tar-bugs@@gnu.org}.
+please report them to @file{bug-tar@@gnu.org}.
@node Tutorial, tar invocation, Introduction, Top
@chapter Tutorial Introduction to @code{tar}
the tutorial and next chapter will not work on tape drives.
Additionally, working with tapes is much more complicated than working
with hard disks. For these reasons, the tutorial does not cover working
-with tape drives. @xref{Media} for complete information on using
+with tape drives. @xref{Media}, for complete information on using
@code{tar} archives with tape drives.
@FIXME{this is a cop out. need to add some simple tape drive info.}
(even if you type them correctly in all other ways), you may end up with
results you don't expect. For this reason, it is a good idea to get
into the habit of typing options in the order that makes inherent sense.
-@xref{short create} for more information on this.
+@xref{short create}, for more information on this.
In this example, you type the command as shown above: @samp{--create}
is the operation which creates the new archive
@end example
@noindent
-@code{tar} will report @samp{tar: foo.tar is the archive; not dumped}.
+@code{tar} will report @samp{tar: ./foo.tar is the archive; not dumped}.
This happens because @code{tar} creates the archive @file{foo.tar} in
the current directory before putting any files into it. Then, when
@code{tar} attempts to add all the files in the directory @file{.} to
-the archive, it notices that the file @file{foo.tar} is the same as the
-archive, and skips it. (It makes no sense to put an archive into
-itself.) GNU @code{tar} will continue in this case, and create the
+the archive, it notices that the file @file{./foo.tar} is the same as the
+archive @file{foo.tar}, and skips it. (It makes no sense to put an archive
+into itself.) GNU @code{tar} will continue in this case, and create the
archive normally, except for the exclusion of that one file.
(@emph{Please note:} Other versions of @code{tar} are not so clever;
they will enter an infinite loop when this happens, so you should not
Sets the blocking factor @code{tar} uses to @var{blocking} x 512 bytes per
record. @FIXME-xref{}.
-@item --bunzip2
-
-(See @samp{--bzip2}; @FIXME-pxref{}.)
-
@item --bzip2
-@itemx --bunzip2
-@itemx --unbzip2
+@itemx -y
This option tells @code{tar} to read or write archives through @code{bzip2}.
@FIXME-xref{}.
rather than the modification time stored in the archive.
@xref{Writing}.
-@item --unbzip2
-
-(See @samp{--bzip2}; @FIXME-pxref{}.)
-
@item --uncompress
(See @samp{--compress}; @FIXME-pxref{}.)
@samp{--extract}
+@item -y
+
+@samp{--bzip2}
+
@item -z
@samp{--gzip}
(note the different creation dates and file sizes). If you extract
the archive, the older version of the file @file{blues} will be
overwritten by the newer version. You can confirm this by extracting
-the archive and running @samp{ls} on the directory. @xref{Writing}
+the archive and running @samp{ls} on the directory. @xref{Writing},
for more information. (@emph{Please note:} This is the case unless
you employ the @value{op-backup} option; @FIXME-ref{Multiple Members
with the Same Name}.)
(The reason @code{tar} does not overwrite the older file when updating
it is because writing to the middle of a section of tape is a difficult
-process. Tapes are not designed to go backward. @xref{Media} for more
+process. Tapes are not designed to go backward. @xref{Media}, for more
information about tapes.
@value{op-update} is not suitable for performing backups for two
@code{cat} to combine the archives, the result will not be a valid
@code{tar} format archive. If you need to retrieve files from an
archive that was added to using the @code{cat} utility, use the
-@value{op-ignore-zeros} option. @xref{Ignore Zeros} for further
+@value{op-ignore-zeros} option. @xref{Ignore Zeros}, for further
information on dealing with archives improperly combined using the
@code{cat} shell utility.
@end table
@findex exclude
-The @value{op-exclude} option will prevent any file or member which
-matches the shell wildcards (@var{pattern}) from being operated on
-(@var{pattern} can be a single file name or a more complex expression).
-For example, if you want to create an archive with all the contents of
-@file{/tmp} except the file @file{/tmp/foo}, you can use the command
-@samp{tar --create --file=arch.tar --exclude=foo}. You may give
-multiple @samp{--exclude} options.
+The @value{op-exclude} option prevents any file or member whose name
+matches the shell wildcard (@var{pattern}) from being operated on.
+For example, to create an archive with all the contents of the directory
+@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
@item --exclude-from=@var{file}
@itemize @bullet
@item
-The main operating mode of @code{tar} will always act on file names
-listed on the command line, no matter whether or not there is an
-exclusion which would otherwise affect them. In the example above, if
+The main operating mode of @code{tar} does not act on a path name
+explicitly listed on the command line if one of its file name
+components is excluded. In the example above, if
you create an archive and exclude files that end with @samp{*.o}, but
-explicitly name the file @samp{catc.o} after all the options have been
-listed, @samp{catc.o} @emph{will} be included in the archive.
+explicitly name the file @samp{dir.o/foo} after all the options have been
+listed, @samp{dir.o/foo} will be excluded from the archive.
@item
You can sometimes confuse the meanings of @value{op-exclude} and
For example, write:
@example
-$ @kbd{tar -c -f @var{archive.tar} -X '*/tmp/*' @var{directory}}
+$ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}}
@end example
@noindent
rather than:
@example
-$ @kbd{tar -c -f @var{archive.tar} -X */tmp/* @var{directory}}
+$ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}}
@end example
@item
@end table
By default, GNU @code{tar} drops a leading @samp{/} on input or output.
-This option turns off this behavior; it is equivalent to changing to the
+This option turns off this behavior.
+Tt is roughly equivalent to changing to the
root directory before running @code{tar} (except it also turns off the
usual warning message).
So, there are pros and cons. We'll see!
@table @kbd
+@item -y
@itemx --bzip2
-@itemx --unbzip2
Filter the archive through @code{bzip2}. Otherwise like @value{op-gzip}.
@item -Z
projects / chaz / tar / blobdiff