@set xref-blocking-factor @xref{Blocking Factor}
@set pxref-blocking-factor @pxref{Blocking Factor}
+@set op-bzip2 @kbd{--bzip2} (@kbd{-y})
+@set ref-bzip2 @ref{gzip}
+@set xref-bzip2 @xref{gzip}
+@set pxref-bzip2 @pxref{gzip}
+
@set op-checkpoint @kbd{--checkpoint}
@set ref-checkpoint @ref{verbose}
@set xref-checkpoint @xref{verbose}
This file documents GNU @code{tar}, a utility used to store, backup, and
transport files.
-Copyright (C) 1992, 1994, 1995, 1996, 1997 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
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1992, 1994, 1995, 1996, 1997 Free Software
+Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999 Free Software
Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
Jay Fenlason put together a draft of a GNU @code{tar} manual,
borrowing notes from the original man page from John Gilmore. This
-draft has been distributed in @code{tar} versions 1.04 (or even
-before?) @FIXME{huh? IMO, either we know or we don't; the
-parenthetical is confusing.} through 1.10, then withdrawn in version
+was withdrawn in version
1.11. Thomas Bushnell, n/BSG and Amy Gorin worked on a tutorial and
manual for GNU @code{tar}. Fran@,{c}ois Pinard put version 1.11.8
of the manual together by taking information from all these sources
@cindex bug reports
@cindex reporting bugs
If you find problems or have suggestions about this program or manual,
-please report them to @file{bug-gnu-utils@@prep.ai.mit.edu}.
+please report them to @file{bug-tar@@gnu.org}.
@node Tutorial, tar invocation, Introduction, Top
@chapter Tutorial Introduction to @code{tar}
filesystem. You should have some basic understanding of directory
structure and how files are named according to which directory they are
in. You should understand concepts such as standard output and standard
-input, what various definitions of the term ``argument'' mean, the
-differences between relative and absolute path names, and @FIXME{what
-else?}.
+input, what various definitions of the term ``argument'' mean, and the
+differences between relative and absolute path names. @FIXME{and what
+else?}
@item
This manual assumes that you are working from your own home directory
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.}
the operations and options have no short or ``old'' forms; however, the
operations and options which we will cover in this tutorial have
corresponding abbreviations. @FIXME{make sure this is still the case,
-at the end} We will indicate those abbreviations appropriately to get
+at the end}We will indicate those abbreviations appropriately to get
you used to seeing them. (Note that the ``old style'' option forms
exist in GNU @code{tar} for compatibility with Unix @code{tar}. We
present a full discussion of this way of writing options and operations
Whenever you use @samp{create}, @code{tar} will erase the current
contents of the file named by @value{op-file} if it exists. @code{tar}
will not tell you if you are about to overwrite a file unless you
-specify an option which does this @FIXME{xref to the node for
---backup!}. To add files to an existing archive, you need to use a
+specify an option which does this. @FIXME{xref to the node for
+--backup!}To add files to an existing archive, you need to use a
different option, such as @value{op-append}; see @ref{append} for
information on how to do this.
(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
(@file{collection.tar}), and @samp{--file} is the option which lets
you give it the name you chose. The files, @file{blues}, @file{folk},
and @file{jazz}, are now members of the archive, @file{collection.tar}
-(they are @dfn{file name arguments} to the @samp{--create} operation)
-@FIXME{xref here to the discussion of file name args?}. Now that they
-are are in the archive, they are called @emph{archive members}, not
-files @FIXME{xref to definitions?}.
+(they are @dfn{file name arguments} to the @samp{--create} operation).
+@FIXME{xref here to the discussion of file name args?}Now that they are
+in the archive, they are called @emph{archive members}, not files.
+@FIXME{xref to definitions?}
When you create an archive, you @emph{must} specify which files you want
placed in the archive. If you do not specify any archive members, GNU
@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
depend on this behavior unless you are certain you are running GNU
-@code{tar}. @FIXME{bob doesn't like this sentence, since he does it
+@code{tar}.) @FIXME{bob doesn't like this sentence, since he does it
all the time, and we've been doing it in the editing passes for this
manual: In general, make sure that the archive is not inside a
-directory being dumped.})
+directory being dumped.}
@node list, extract, create, Tutorial
@section How to List Archives
@noindent
If you list the files in the directory again, you will see that the file
@file{blues} has been restored, with its original permissions, creation
-times, and owner. @FIXME{This is only accidentally true, but not in
+times, and owner.@FIXME{This is only accidentally true, but not in
general. In most cases, one has to be root for restoring the owner, and
use a special option for restoring permissions. Here, it just happens
that the restoring user is also the owner of the archived members, and
@itemx -P
Normally when creating an archive, @code{tar} strips an initial @samp{/} from
-member names. This option disables that behavior. @FIXME-xref{}.
+member names. This option disables that behavior. @FIXME-xref{}
@item --after-date
-(See @samp{--newer}; @FIXME-pxref{}.)
+(See @samp{--newer}.) @FIXME-pxref{}
@item --atime-preserve
Tells @code{tar} to preserve the access time field in a file's inode when
-dumping it. @FIXME-xref{}.
+dumping it. @FIXME-xref{}
@item --backup=@var{backup-type}
Rather than deleting files from the file system, @code{tar} will back them up
using simple or numbered backups, depending upon @var{backup-type}.
-@FIXME-xref{}.
+@FIXME-xref{}
@item --block-number
@itemx -R
With this option present, @code{tar} prints error messages for read errors
-with the block number in the archive file. @FIXME-xref{}.
+with the block number in the archive file. @FIXME-xref{}
@item --blocking-factor=@var{blocking}
@itemx -b @var{blocking}
Sets the blocking factor @code{tar} uses to @var{blocking} x 512 bytes per
-record. @FIXME-xref{}.
+record. @FIXME-xref{}
+
+@item --bzip2
+@itemx -y
+
+This option tells @code{tar} to read or write archives through @code{bzip2}.
+@FIXME-xref{}
@item --checkpoint
This option directs @code{tar} to print periodic checkpoint messages as it
reads through the archive. Its intended for when you want a visual
indication that @code{tar} is still running, but don't want to see
-@samp{--verbose} output. @FIXME-xref{}.
+@samp{--verbose} output. @FIXME-xref{}
@item --compress
@itemx --uncompress
@code{tar} will use the @code{compress} program when reading or writing the
archive. This allows you to directly act on archives while saving
-space. @FIXME-xref{}.
+space. @FIXME-xref{}
@item --confirmation
-(See @samp{--interactive}; @FIXME-pxref{}.)
+(See @samp{--interactive}.) @FIXME-pxref{}
@item --dereference
@itemx -h
When creating a @code{tar} archive, @code{tar} will archive the file that a symbolic
-link points to, rather than archiving the symlink. @FIXME-xref{}.
+link points to, rather than archiving the symlink. @FIXME-xref{}
@item --directory=@var{dir}
@itemx -C @var{dir}
When this option is specified, @code{tar} will change its current directory
to @var{dir} before performing any operations. When this option is used
-during archive creation, it is order sensitive. @FIXME-xref{}.
+during archive creation, it is order sensitive. @FIXME-xref{}
@item --exclude=@var{pattern}
When performing operations, @code{tar} will skip files that match
-@var{pattern}. @FIXME-xref{}.
+@var{pattern}. @FIXME-xref{}
@item --exclude-from=@var{file}
@itemx -X @var{file}
Similar to @samp{--exclude}, except @code{tar} will use the list of patterns
-in the file @var{file}. @FIXME-xref{}.
+in the file @var{file}. @FIXME-xref{}
@item --file=@var{archive}
@itemx -f @var{archive}
@code{tar} will use the file @var{archive} as the @code{tar} archive it
performs operations on, rather than @code{tar}'s compilation dependent
-default. @FIXME-xref{}.
+default. @FIXME-xref{}
@item --files-from=@var{file}
@itemx -T @var{file}
@code{tar} will use the contents of @var{file} as a list of archive members
or files to operate on, in addition to those specified on the
-command-line. @FIXME-xref{}.
+command-line. @FIXME-xref{}
@item --force-local
Forces @code{tar} to interpret the filename given to @samp{--file} as a local
-file, even if it looks like a remote tape drive name. @FIXME-xref{}.
+file, even if it looks like a remote tape drive name. @FIXME-xref{}
@item --group=@var{group}
Files added to the @code{tar} archive will have a group 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 ID. @FIXME-xref{}.
+a decimal numeric group ID. @FIXME-xref{}
Also see the comments for the @value{op-owner} option.
@item --gunzip
-(See @samp{--gzip}; @FIXME-pxref{}.)
+(See @samp{--gzip}.) @FIXME-pxref{}
@item --gzip
@itemx --gunzip
This option tells @code{tar} to read or write archives through @code{gzip},
allowing @code{tar} to directly operate on several kinds of compressed
-archives transparently. @FIXME-xref{}.
+archives transparently. @FIXME-xref{}
@item --help
@code{tar} will print out a short message summarizing the operations and
-options to @code{tar} and exit. @FIXME-xref{}.
+options to @code{tar} and exit. @FIXME-xref{}
@item --ignore-failed-read
Used to inform @code{tar} that it is working with an old GNU-format
incremental backup archive. It is intended primarily for backwards
-compatibility only. @FIXME-xref{}.
+compatibility only. @FIXME-xref{}
@item --info-script=@var{script-file}
@itemx --new-volume-script=@var{script-file}
@itemx -F @var{script-file}
When @code{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. @FIXME-xref{}
@item --interactive
@itemx --confirmation
Specifies that @code{tar} should ask the user for confirmation before
performing potentially destructive options, such as overwriting files.
-@FIXME-xref{}.
+@FIXME-xref{}
@item --keep-old-files
@itemx -k
When creating an archive, instructs @code{tar} to write @var{name} as a name
record in the archive. When extracting or listing archives, @code{tar} will
only operate on archives that have a label matching the pattern
-specified in @var{name}. @FIXME-xref{}.
+specified in @var{name}. @FIXME-xref{}
@item --listed-incremental=@var{snapshot-file}
@itemx -g @var{snapshot-file}
@code{tar} creates is a new GNU-format incremental backup, using
@var{snapshot-file} to determine which files to backup.
With other operations, informs @code{tar} that the archive is in incremental
-format. @FIXME-xref{}.
+format. @FIXME-xref{}
@item --mode=@var{permissions}
@itemx -M
Informs @code{tar} that it should create or otherwise operate on a
-multi-volume @code{tar} archive. @FIXME-xref{}.
+multi-volume @code{tar} archive. @FIXME-xref{}
@item --new-volume-script
@itemx -N
When creating an archive, @code{tar} will only add files that have changed
-since @var{date}. @FIXME-xref{}.
+since @var{date}. @FIXME-xref{}
@item --newer-mtime
@item --no-recursion
With this option, @code{tar} will not recurse into directories unless a
-directory is explicitly named as an argument to @code{tar}. @FIXME-xref{}.
+directory is explicitly named as an argument to @code{tar}. @FIXME-xref{}
@item --null
When @code{tar} is using the @samp{--files-from} option, this option
instructs @code{tar} to expect filenames terminated with @kbd{NUL}, so
@code{tar} can correctly work with file names that contain newlines.
-@FIXME-xref{}.
+@FIXME-xref{}
@item --numeric-owner
This option will notify @code{tar} that it should use numeric user and group
-IDs when creating a @code{tar} file, rather than names. @FIXME-xref{}.
+IDs when creating a @code{tar} file, rather than names. @FIXME-xref{}
@item --old-archive
-(See @samp{--portability}; @FIXME-pxref{}.)
+(See @samp{--portability}.) @FIXME-pxref{}
@item --one-file-system
@itemx -l
Used when creating an archive. Prevents @code{tar} from recursing into
directories that are on different file systems from the current
-directory. @FIXME-xref{}.
+directory. @FIXME-xref{}
@item --owner=@var{user}
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 ID.
-@FIXME-xref{}.
+@FIXME-xref{}
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
@itemx -o
Tells @code{tar} to create an archive that is compatible with Unix V7
-@code{tar}. @FIXME-xref{}.
+@code{tar}. @FIXME-xref{}
@item --posix
-Instructs @code{tar} to create a POSIX compliant @code{tar} archive. @FIXME-xref{}.
+Instructs @code{tar} to create a POSIX compliant @code{tar} archive. @FIXME-xref{}
@item --preserve
Synonymous with specifying both @samp{--preserve-permissions} and
-@samp{--same-order}. @FIXME-xref{}.
+@samp{--same-order}. @FIXME-xref{}
@item --preserve-order
@item --record-size=@var{size}
Instructs @code{tar} to use @var{size} bytes per record when accessing the
-archive. @FIXME-xref{}.
+archive. @FIXME-xref{}
@item --recursive-unlink
@item --remove-files
Directs @code{tar} to remove the source file from the file system after
-appending it to an archive. @FIXME-xref{}.
+appending it to an archive. @FIXME-xref{}
@item --rsh-command=@var{cmd}
Notifies @code{tar} that is should use @var{cmd} to communicate with remote
-devices. @FIXME-xref{}.
+devices. @FIXME-xref{}
@item --same-order
@itemx --preserve-order
@item --same-owner
When extracting an archive, @code{tar} will attempt to preserve the owner
-specified in the @code{tar} archive with this option present. @FIXME-xref{}.
+specified in the @code{tar} archive with this option present. @FIXME-xref{}
@item --same-permissions
@item --show-omitted-dirs
Instructs @code{tar} to mention directories its skipping over when operating
-on a @code{tar} archive. @FIXME-xref{}.
+on a @code{tar} archive. @FIXME-xref{}
@item --sparse
@itemx -S
Invokes a GNU extension when adding files to an archive that handles
-sparse files efficiently. @FIXME-xref{}.
+sparse files efficiently. @FIXME-xref{}
@item --starting-file=@var{name}
@itemx -K @var{name}
@item --suffix=@var{suffix}
Alters the suffix @code{tar} uses when backing up files from the default
-@samp{~}. @FIXME-xref{}.
+@samp{~}. @FIXME-xref{}
@item --tape-length=@var{num}
@itemx -L @var{num}
Specifies the length of tapes that @code{tar} is writing as being
-@w{@var{num} x 1024} bytes long. @FIXME-xref{}.
+@w{@var{num} x 1024} bytes long. @FIXME-xref{}
@item --to-stdout
@itemx -O
@item --totals
Displays the total number of bytes written after creating an archive.
-@FIXME-xref{}.
+@FIXME-xref{}
@item --touch
@itemx -m
@item --uncompress
-(See @samp{--compress}; @FIXME-pxref{}.)
+(See @samp{--compress}.) @FIXME-pxref{}
@item --ungzip
-(See @samp{--gzip}; @FIXME-pxref{}.)
+(See @samp{--gzip}.) @FIXME-pxref{}
@item --unlink-first
@itemx -U
@item --use-compress-program=@var{prog}
Instructs @code{tar} to access the archive through @var{prog}, which is
-presumed to be a compression program of some sort. @FIXME-xref{}.
+presumed to be a compression program of some sort. @FIXME-xref{}
@item --verbose
@itemx -v
Specifies that @code{tar} should be more verbose about the operations its
performing. This option can be specified multiple times for some
-operations to increase the amount of information displayed. @FIXME-xref{}.
+operations to increase the amount of information displayed. @FIXME-xref{}
@item --verify
@itemx -W
Verifies that the archive was correctly written when creating an
-archive. @FIXME-xref{}.
+archive. @FIXME-xref{}
@item --version
@code{tar} will print an informational message about what version it is and a
-copyright message, some credits, and then exit. @FIXME-xref{}.
+copyright message, some credits, and then exit. @FIXME-xref{}
@item --volno-file=@var{file}
Used in conjunction with @samp{--multi-volume}. @code{tar} will keep track
of which volume of a multi-volume archive its working in @var{file}.
-@FIXME-xref{}.
+@FIXME-xref{}
@end table
@node Short Option Summary, , Option Summary, All Options
@samp{--extract}
+@item -y
+
+@samp{--bzip2}
+
@item -z
@samp{--gzip}
choose among several backup tapes when retrieving a file later, in
favor of the tape where the file appears earliest (closest to the
front of the tape). @FIXME-xref{when the node name is set and the
-backup section written}.
+backup section written.}
@node interactive, , verbose, tar invocation
@section Asking for Confirmation During Operations
MMwtSN node; not sure. i didn't know how to make it simpler...}
There are a few ways to get around this. @FIXME-xref{Multiple Members
-with the Same Name}.
+with the Same Name.}
@cindex Members, replacing with other members
@cindex Replacing members with other members
like to admit to, specifically the last sentence. On the other hand, i
don't think it's a good idea to be saying that re explicitly don't
recommend using something, but i can't see any better way to deal with
-the situation.} When you extract the archive, the older version will be
+the situation.}When you extract the archive, the older version will be
effectively lost. This works because files are extracted from an
archive in the order in which they were archived. Thus, when the
archive is extracted, a file archived later in time will overwrite a
(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
+you employ the @value{op-backup} option. @FIXME-ref{Multiple Members
with the Same Name}.)
@node update, concatenate, append, Advanced tar
Both @samp{--update} and @samp{--append} work by adding to the end
of the archive. When you extract a file from the archive, only the
version stored last will wind up in the file system, unless you use
-the @value{op-backup} option (@FIXME-ref{Multiple Members with the
-Same Name}).
+the @value{op-backup} option. @FIXME-ref{Multiple Members with the
+Same Name}
@menu
* how to update::
(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
command line. (Nothing happens if you don't list any.) The members,
and their member names, will be copied verbatim from those archives. If
this causes multiple members to have the same name, it does not delete
-any members; all the members with the same name coexist. For
-information on how this affects reading the archive, @FIXME-ref{Multiple
-Members with the Same Name}.
+any members; all the members with the same name coexist. @FIXME-ref{For
+information on how this affects reading the archive, Multiple
+Members with the Same Name.}
To demonstrate how @samp{--concatenate} works, create two small archives
called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant
When you use @samp{--concatenate}, the source and target archives must
already exist and must have been created using compatable format
-parameters (@FIXME-pxref{Matching Format Parameters}). The new,
+parameters. @FIXME-pxref{Matching Format Parameters}The new,
concatenated archive will be called by the same name as the first
archive listed on the command line. @FIXME{is there a way to specify a
new name?}
@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.
@value{op-extract}.
@end table
-@FIXME{Following paragraph needs to be rewritten: why doesnt' this cat
+@FIXME{Following paragraph needs to be rewritten: why doesn't this cat
files together, why is this useful. is it really useful with
more than one file?}
explains how to choose and change file and archive names, how to use
files to store names of other files which you can then call as
arguments to @code{tar} (this can help you save time if you expect to
-archive the same list of files a number of times), and how to
+archive the same list of files a number of times), and so forth.
@FIXME{in case it's not obvious, i'm making this up in some sense
based on my imited memory of what the next chapter *really* does. i
just wanted to flesh out this final section a little bit so i'd
Before you use these scripts, you need to edit the file
@file{backup-specs}, which specifies parameters used by the backup
scripts and by the restore script. @FIXME{There is no such restore
-script!}. @FIXME-xref{Script Syntax}. Once the backup parameters
+script!}@FIXME-xref{Script Syntax}Once the backup parameters
are set, you can perform backups or restoration by running the
appropriate script.
The name of the restore script is @code{restore}. @FIXME{There is
-no such restore script!}. The names of the level one and full backup
+no such restore script!}The names of the level one and full backup
scripts are, respectively, @code{level-1} and @code{level-0}.
The @code{level-0} script also exists under the name @code{weekly}, and
the @code{level-1} under the name @code{daily}---these additional names
can be changed according to your backup schedule. @FIXME-xref{Scripted
-Restoration}, for more information on running the restoration script.
-@FIXME-xref{Scripted Backups}, for more information on running the
-backup scripts.
+Restoration, for more information on running the restoration script.}
+@FIXME-xref{Scripted Backups, for more information on running the
+backup scripts.}
@emph{Please Note:} The backup scripts and the restoration scripts are
designed to be used together. While it is possible to restore files by
hand from an archive which was created using a backup script, and to create
an archive by hand which could then be extracted using the restore script,
-it is easier to use the scripts. @FIXME{There is no such restore script!}.
+it is easier to use the scripts.@FIXME{There is no such restore script!}
@value{xref-incremental}, and @value{xref-listed-incremental},
before making such an attempt.
@FIXME{This about backup scripts needs to be written: BS is a shell
script .... thus ... @file{backup-specs} is in shell script syntax.}
-@FIXME-xref{Script Syntax}, for an explanation of this syntax.
+@FIXME-xref{Script Syntax, for an explanation of this syntax.}
@FIXME{Whats a parameter .... looked at by the backup scripts
... which will be expecting to find ... now syntax ... value is linked
where @var{time-to-be-run} can be a specific system time, or can be
@kbd{now}. If you do not specify a time, the script runs at the time
-specified in @file{backup-specs} (@FIXME-pxref{Script Syntax}).
+specified in @file{backup-specs}. @FIXME-pxref{Script Syntax}
You should start a script with a tape or disk mounted. Once you
start a script, it prompts you for new tapes or disks as it
The @code{restore} script prompts for media by its archive volume,
so to avoid an error message you should keep track of which tape
(or disk) contains which volume of the archive. @FIXME{There is
-no such restore script!}. @FIXME-xref{Scripted Restoration}.
+no such restore script!} @FIXME-xref{Scripted Restoration}
@FIXME{Have file names changed?}
The backup scripts write two files on the file system. The first is a
record file in @file{/etc/tar-backup/}, which is used by the scripts
to store and retrieve information about which files were dumped. This
file is not meant to be read by humans, and should not be deleted by
-them. @FIXME-xref{incremental and listed-incremental}, for a more
-detailed explanation of this file.
+them. @FIXME-xref{incremental and listed-incremental, for a more
+detailed explanation of this file.}
The second file is a log file containing the names of the file systems
and files dumped, what time the backup was made, and any error
volumes as they are needed. If the archive is on tape, you don't need
to rewind the tape to to its beginning---if the tape head is
positioned past the beginning of the archive, the script will rewind
-the tape as needed. @FIXME-xref{Media}, for a discussion of tape
-positioning.
+the tape as needed. @FIXME-xref{Media, for a discussion of tape
+positioning.}
If you specify @samp{--all} as the @var{files} argument, the
@code{restore} script extracts all the files in the archived file
By default, @code{tar} takes file names from the command line. However,
there are other ways to specify file or member names, or to modify the
manner in which @code{tar} selects the files or members upon which to
-operate; @FIXME{add xref here}. In general, these methods work both for
+operate. @FIXME{add xref here}In general, these methods work both for
specifying the names of files and archive members.
@node files, exclude, Selecting Archive Members, Choosing
@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 example
@noindent
-which tells @FIXME{need to fill this in!}.
+@FIXME{which tells -- need to fill this in!}
@node recurse, one, after, Choosing
@section Descending into Directories
@code{find} for locating files they want to back up, and since
@code{tar} @emph{usually} recursively descends on directories, they have
to use the @samp{@w{! -d}} option to @code{find} @FIXME{needs more
-explanation or a cite to another info file} as they usually do not want
+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}
option to archive the files located via @code{find}.
@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).
@FIXME{ach; these two bits orig from "compare" (?). where to put?} Some
format parameters must be taken into consideration when modifying an
-archive: @FIXME{???}. Compressed archives cannot be modified.
+archive.@FIXME{???} Compressed archives cannot be modified.
You can use @samp{--gzip} and @samp{--gunzip} on physical devices
(tape drives, etc.) and remote files as well as on normal files; data
So, there are pros and cons. We'll see!
@table @kbd
+@item -y
+@itemx --bzip2
+Filter the archive through @code{bzip2}. Otherwise like @value{op-gzip}.
+
@item -Z
@itemx --compress
@itemx --uncompress
@strong{Please note} that the @code{compress} program may be covered by
a patent, and therefore we recommend you stop using it.
+@value{op-bzip2} acts like @value{op-compress}, except that it uses
+the @code{bzip2} utility.
+
@table @kbd
@item --compress
@itemx --uncompress
When writing an archive, @code{tar} writes the user id and user name
separately. If it can't find a user name (because the user id is not
in @file{/etc/passwd}), then it does not write one. When restoring,
-and doing a @code{chmod} like when you use @value{op-same-permissions}
-(@FIXME{same-owner?}), it tries to look the name (if one was written)
+and doing a @code{chmod} like when you use @value{op-same-permissions},
+@FIXME{same-owner?}it tries to look the name (if one was written)
up in @file{/etc/passwd}. If it fails, then it uses the user id
stored in the archive instead.
Archives are permitted to have more than one member with the same
member name. One way this situation can occur is if more than one
version of a file has been stored in the archive. For information
-about adding new versions of a file to an archive, see @ref{update},
-and to learn more about having more than one archive member with the
-same name, see @FIXME-xref{-backup node, when it's written}.
+about adding new versions of a file to an archive, see @ref{update}.
+@FIXME-xref{To learn more about having more than one archive member with the
+same name, see -backup node, when it's written.}
In addition to entries describing archive members, an archive may
contain entries which @code{tar} itself uses to store information.
not support numeric user or group IDs, these fields should be ignored.
The @code{size} field is the size of the file in bytes; linked files
-are archived with this field specified as zero. @FIXME-xref{Modifiers}, in
-particular the @value{op-incremental} option.
+are archived with this field specified as zero. @FIXME-xref{Modifiers, in
+particular the @value{op-incremental} option.}
The @code{mtime} field is the modification time of the file at the time
it was archived. It is the ASCII representation of the octal value of
Before reading an archive, you should make sure the tape head is at
the beginning of the archive you want to read. (The @code{restore}
script will find the archive automatically. @FIXME{There is no such
-restore script!}. @FIXME-xref{Scripted Restoration}). @xref{mt}, for
+restore script!}@FIXME-xref{Scripted Restoration}@xref{mt}, for
an explanation of the tape moving utility.
If you want to add new archive file entries to a tape, you should
on it) and print an error if the archive label doesn't match the
@var{archive-name} specified. @var{archive-name} can be any regular
expression. If the labels match, @code{tar} extracts the archive.
-@value{xref-label}. @FIXME-xref{Matching Format Parameters}.
-@FIXME{fix cross references} @samp{tar --list --label} will cause
-@code{tar} to print the label.
+@value{xref-label}.
+@FIXME-xref{Matching Format Parameters}@FIXME{fix cross
+references}@samp{tar --list --label} will cause @code{tar} to print the
+label.
@FIXME{Program to list all the labels on a tape?}
@value{op-label} option. This will write a special block identifying
@var{volume-label} as the name of the archive to the front of the archive
which will be displayed when the archive is listed with @value{op-list}.
-If you are creating a multi-volume archive with @value{op-multi-volume}
-(@FIXME-pxref{Using Multiple Tapes}), then the volume label will have
+If you are creating a multi-volume archive with
+@value{op-multi-volume}@FIXME-pxref{Using Multiple Tapes}, then the
+volume label will have
@samp{Volume @var{nnn}} appended to the name you give, where @var{nnn} is
the number of the volume of the archive. (If you use the @value{op-label}
option when reading an archive, it checks to make sure the label on the
@value{op-multi-volume}, each volume of the archive will have an
archive label of the form @samp{@var{archive-label} Volume @var{n}},
where @var{n} is 1 for the first volume, 2 for the next, and so on.
-@FIXME-xref{Multi-Volume Archives}, for information on creating multiple
-volume archives.
+@FIXME-xref{Multi-Volume Archives, for information on creating multiple
+volume archives.}
If you list or extract an archive using @value{op-label}, @code{tar} will
print an error if the archive label doesn't match the @var{archive-label}
projects / chaz / tar / blobdiff