tar documentation
Being careful, the first thing is really checking that you are using GNU
tar, indeed. The `--version' option will generate a message
giving confirmation that you are using GNU tar, with the precise
version of GNU tar you are using. tar identifies itself
and prints the version number to the standard output, then immediately
exits successfully, without doing anything else, ignoring all other
options. For example, `tar --version' might return:
GNU tar version 1.11.9
Another thing you might want to do is checking the spelling or meaning
of some particular tar option, without resorting to this manual,
for once you have carefully read it. GNU tar has a short help
feature, triggerable through the `--help' option. By using this
option, tar will print a usage message listing all available
options on standard output, then exit successfully, without doing
anything else and ignoring all other options. Even if this is only a
brief summary, it may be several screens long. So, if you are not
using some kind of scrollable window, you might prefer to use something
like:
tar --help | less
presuming, here, that you like using less for a pager. Other
popular pagers are more and pg.
The perceptive reader would have noticed some contradiction in the previous paragraphs. It is written that both `--version' and `--help' print something, and have all other options ignored. In fact, they cannot ignore each other, and one of them has to win. We do not specify which is stronger, here; experiment if you really wonder!
The short help output is quite succint, and you might have to get back
to the full documentation for precise points. If you are reading this
paragraph, you already have the tar manual in some form. This
manual is available in printed form, as a kind of small book. It may
printed out of the GNU tar distribution, provided you have TeX
already installed somewhere, and a laser printer around. Just configure
the distribution, execute the command `make dvi', then print
`doc/tar.dvi' the usual way (contact your local guru to know how).
If GNU tar has been conveniently installed at your place, this
manual is also available in interactive, hypertextual form as an Info
file. Just call `info tar' or, if you do not have the
info program handy, use the Info reader provided within GNU
Emacs, calling `tar' from the main Info menu.
tar progress
Typically, tar performs most operations without reporting any
information to the user except error messages. When using tar
with many options, particularly ones with complicated or
difficult-to-predict behavior, it is possible to make serious mistakes.
tar provides several options that make observing tar
easier. These options cause tar to print information as it
progresses in its job, and you might want to use them just for being
more careful about what is going on, or merely for entertaining
yourself. If you have encountered a problem when operating on an
archive, however, you may need more information than just an error
message in order to solve the problem. The following options can be
helpful diagnostic tools.
Normally, the `--list' (`-t') command to list an archive prints just
the file names (one per line) and the other commands are silent.
When used with most operations, the `--verbose' (`-v') option causes
tar to print the name of each file or archive member as it
is processed. This and the other options which make tar print
status information can be useful in monitoring tar.
With `--create' (`-c') or `--extract' (`-x'), `--verbose' (`-v') used once
just prints the names of the files or members as they are processed.
Using it twice causes tar to print a longer listing (reminiscent
of `ls -l') for each member. Since `--list' (`-t') already prints
the names of the members, `--verbose' (`-v') used once with `--list' (`-t')
causes tar to print an `ls -l' type listing of the files
in the archive. The following examples both extract members with
long list output:
tar --extract --file=archive.tar --verbose --verbose tar xvv archive.tar
Verbose output appears on the standard output except when an archive is
being written to the standard output, as with `tar --create
--file=- --verbose' (`tar cfv -', or even `tar cv'---if the
installer let standard output be the default archive). In that case
tar writes verbose output to the standard error stream.
The `--totals' option--which is only meaningful when used with
`--create' (`-c')---causes tar to print the total
amount written to the archive, after it has been fully created.
The `--checkpoint' option prints an occasional message
as tar reads or writes the archive. In fact, it print
directory names while reading the archive. It is designed for
those who don't need the more detailed (and voluminous) output of
`--block-number' (`-R'), but do want visual confirmation that tar
is actually making forward progress.
@FIXME{There is some confusion here. It seems that -R once wrote a message at `every' record read or written.}
The `--show-omitted-dirs' option, when reading an archive--with `--list' (`-t') or `--extract' (`-x'), for example--causes a message to be printed for each directory in the archive which is skipped. This happens regardless of the reason for skipping: the directory might not have been named on the command line (implicitly or explicitly), it might be excluded by the use of the `--exclude=pattern' option, or some other reason.
If `--block-number' (`-R') is used, tar prints, along with every
message it would normally produce, the block number within the archive
where the message was triggered. Also, supplementary messages are
triggered when reading blocks full of NULs, or when hitting end of
file on the archive. As of now, if the archive if properly terminated
with a NUL block, the reading of the file may stop before end of file
is met, so the position of end of file will not usually show when
`--block-number' (`-R') is used. But this may change in the future:
there are cases where GNU tar should drain the archive before
exiting, while it currently does not.
This option is especially useful when reading damaged archives, since it helps pinpoint the damaged sections. It can also be used with `--list' (`-t') when listing a file-system backup tape, allowing you to 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}.
Typically, tar carries out a command without stopping for
further instructions. In some situations however, you may want to
exclude some files and archive members from the operation (for instance
if disk or storage space is tight). You can do this by excluding
certain files automatically (see section Choosing Files and Names for tar), or by performing
an operation interactively, using the `--interactive' (`-w') option.
tar also accepts `--confirmation' for this option.
When the `--interactive' (`-w') option is specified, before
reading, writing, or deleting files, tar first prints a message
for each such file, telling what operation it intends to take, then asks
for confirmation on the terminal. The actions which require
confirmation include adding a file to the archive, extracting a file
from the archive, deleting a file from the archive, and deleting a file
from disk. To confirm the action, you must type a line of input
beginning with `y'. If your input line begins with anything other
than `y', tar skips that file.
If tar is reading the archive from the standard input,
tar opens the file `/dev/tty' to support the interactive
communications.
Verbose output is normally sent to standard output, separate from
other error messages. However, if the archive is produced directly
on standard output, then verbose output is mixed with errors on
stderr. Producing the archive on standard output may be used
as a way to avoid using disk space, when the archive is soon to be
consumed by another process reading it, say. Some people felt the need
of producing an archive on stdout, still willing to segregate between
verbose output and error output. A possible approach would be using a
named pipe to receive the archive, and having the consumer process to
read from that named pipe. This has the advantage of letting standard
output free to receive verbose output, all separate from errors.
This option causes tar to verify the archive after writing it.
Each volume is checked after it is written, and any discrepancies
are recorded on the standard error output.
Verification requires that the archive be on a back-space-able medium. This means pipes, some cartridge tape drives, and some other devices cannot be verified.
You can insure the accuracy of an archive by comparing files in the
system with archive members. tar can compare an archive to the
file system as the archive is being written, to verify a write
operation, or can compare a previously written archive, to insure that
it is up to date.
To check for discrepancies in an archive immediately after it is
written, use the `--verify' (`-W') option in conjunction with
the `--create' (`-c') operation. When this option is
specified, tar checks archive members against their counterparts
in the file system, and reports discrepancies on the standard error. In
multi-volume archives, each volume is verified after it is written,
before the next volume is written.
To verify an archive, you must be able to read it from before the end of the last written entry. This option is useful for detecting data errors on some tapes. Archives written to pipes, some cartridge tape drives, and some other devices cannot be verified.
One can explicitely compare an already made archive with the file system by using the `--compare' (`-d') option, instead of using the more automatic `--verify' (`-W') option. See section Comparing Archives Members with the File System.
All tapes and disks can be write protected, to protect data on them from being changed. Once an archive is written, you should write protect the media to prevent the archive from being accidently overwritten or deleted. (This will protect the archive from being changed with a tape or floppy drive--it will not protect it from magnet fields or other physical hazards).
The write protection device itself is usually an integral part of the physical media, and can be a two position (write enabled/write disabled) switch, a notch which can be popped out or covered, a ring which can be removed from the center of a tape reel, or some other changeable feature.