   This file documents GNU `tar', a utility used to store, backup, and
transport files.

   Copyright (C) 1992, 1994, 1995 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

GNU tar
*******

   This file documents `tar', a utility used to store, backup, and
transport files.  It is a rudimentary documentation for the GNU tape
(or disk) archiver.  It covers the release 1.11.8.

   This document has been quickly assembled from random notes and
sources.  I will of course accept documentation bug reports, but please
do not torture yourself into systematically reporting all inadequacies
for unrevised nodes.

Introduction
************

   This chapter introduces of a few words which will recur all over
this manual, like "archive", "member", "name", "unpack", etc.  It then
explains who wrote GNU `tar' and its documentation, and says where to
send bug reports or comments.

What `tar' Does
===============

   The `tar' program is used to create and manipulate `tar' archives.
An "archive" is a single file which contains within it the contents of
many files.  In addition, the archive identifies the names of the
files, their owner, and so forth.  (Archives record access permissions,
user and group, size in bytes, and last modification time.  Some
archives also record the file names in each archived directory, as well
as other file and directory information.)

   The files inside an archive are called "members".  Within this
manual, we use the term "file" to refer only to files accessible in the
normal ways (by `ls', `cat', and so forth), and the term "members" to
refer only to the members of an archive.  Similarly, a "file name" is
the name of a file, as it resides in the filesystem, and a "member
name" is the name of an archive member within the archive.

   Initially, `tar' archives were used to store files conveniently on
magnetic tape.  The name `tar' comes from this use; it stands for:
`t'ape `ar'chiver.  Despite the utility's name, `tar' can direct its
output to any available device, as well as store it in a file or direct
it to another program via a pipe.  `tar' may even access, as archives,
remote devices or files.

   You can use `tar' archives in many ways.  We want to stress a few of
them: storage, backup or transportation.

Storage
     Often, `tar' archives are used to store related files for
     convenient file transfer over a network.  For example, the GNU
     Project distributes its software bundled into `tar' archives, so
     that all the files relating to a particular program (or set of
     related programs) can be transferred as a single unit.

     A magnetic tape can store several files in sequence, but has no
     names for them, just relative position on the tape.  A `tar'
     archive or something like it is one way to store several files on
     one tape and retain their names.  Even when the basic transfer
     mechanism can keep track of names, as FTP can, the nuisance of
     handling multiple files, directories, and multiple links, makes
     `tar' archives an attractive method.

     Archive files are also used for long-term storage, which you can
     think of as transportation from one time to another.

Backup
     Because the archive created by `tar' is capable of preserving file
     information and directory structure, `tar' is commonly used for
     performing full and incremental backups of disks, putting all
     together bunch of files possibly pertaining to many users and
     different projects, to secure against accidental destruction of
     those disks.

     The GNU version of `tar' has special features that allow it to be
     used to make incremental and full dumps of all the files in a
     filesystem.

Transportation
     Archive files can be used for transporting a group of files from
     one system to another: put all relevant files into an archive on
     one computer system, transfer the archive to another, and extract
     the contents there.  The basic transfer medium might be magnetic
     tape, Internet FTP, or even electronic mail (though you must
     encode the archive with `uuencode' or some functional equivalent
     in order to transport it properly by mail).  Both machines do not
     have to use the same operating system, as long as they both
     support the `tar' program.

     Piping one `tar' to another is an easy way to copy a directory's
     contents from one disk to another, while preserving the dates,
     modes, owners and link structure of all the files therein.  `tar'
     is also ideal for transferring directories over networks.  We
     sometimes see a copy of `tar' packing many files into one archive
     on one machine, and sending the produced archive over a pipe over
     the network to another copy of `tar' on another machine, reading
     its archive from the pipe and unpacking all files there.

   The `tar' program provides the ability to create `tar' archives, as
well as for various other kinds of manipulation.  For example, you can
use `tar' on previously created archives to extract files, to store
additional files, or to update or list files already stored.  The term
"extraction" is used to refer to the process of copying an archive
member into a file in the filesystem.  One might speak of extracting a
single member.  Extracting all the members of an archive is often
called extracting the archive.  Also, the term "unpack" is used to
refer to the extraction of many or all the members of an archive.

   Conventionally, `tar' archives are given names ending with `.tar'.
This is not necessary for `tar' to operate properly, but this manual
follows the convention in order to get the reader used to seeing it.

   Occasionally, `tar' archives are referred to as `tar' files, archive
members are referred to as files, or entries.  For people familiar with
the operation of `tar', this causes no difficulty.  However, this
manual consistently uses the terminology above in referring to archives
and archive members, to make it easier to learn how to use `tar'.

GNU `tar' Authors
=================

   GNU `tar' was originally written by John Gilmore, and modified by
many people.  The GNU enhancements were written by Jay Fenlason, and
the whole package has been further maintained by Michael Bushnell, then
Franc,ois Pinard, with the help of numerous and kind users.  I wish to
stress that `tar' is somewhat a collective work, and owe much to all
those people who reported problems, offerred solutions and other
insights, or shared their thoughts and suggestions.  Even if we lost
track of many of those contributors, a partial list can be found in the
`THANKS' file from the GNU `tar' distribution.

   Jay Fenlason put together a draft of a GNU `tar' manual, also
borrowing notes from the original man page from John Gilmore, this
draft has been distributed in `tar' versions 1.04 (or even before?)
through 1.10, then withdrawn in version 1.11.  Michael Bushnell and Amy
Gorin worked at a tutorial and manual for GNU `tar', and left a few
unpublished versions of each.  For version 1.11.8, Franc,ois Pinard put
together a new manual by grabbing from all these sources and merging
them in a single manual.

   I heard that there is another manual in the works, by another team,
which should say everything about archives and related utilities, and
which will surely be nicer than this one.  In the meantime, please
consider this manual is a placeholder for `tar' option list and a few
random notes the maintainer wants to save somewhere, so users can read
them.  I wish GNU `tar' users will be happier with this imperfect
manual than with no documentation at all.

Reporting bugs or suggestions
=============================

   Please report problems or suggestions about this program to
`bug-gnu-utils@prep.ai.mit.edu'.  You may also write directly, and less
officially, to `pinard@iro.umontreal.ca'.  There is a lot of mail
flowing about `tar', and some accumulated in the past years.  You might
expect a quick acknowledgement of your invoices, but the proper
handling of your reports may be delayed for a long while.

   Many nodes of this document have not been revised much, these all
start with a little comment telling so.  I accept documentation bug
reports, of course.  But please do not torture yourself into
systematically reporting all inadequacies for the unrevised nodes of
this document, unless you really feel like revising them.

Support considerations
======================

   This informal appendix is for the maintainer to share a few words
and thoughts, while considering GNU `tar' support.

Stability of GNU `tar'
----------------------

   User reports mainly fall in three categories: portability problems,
execution bugs, and requests for enhancements.  For 1.11.X, the
emphasis has been on solving portability problems, then trying to make
GNU `tar' more solid.  Enhancements have fairly low priority, yet I
sometime slip one in just for taking a kind of rest :-).

   Many bugs have been corrected since 1.11.2.  If you are curious,
glance through ChangeLog.  I had only very few reports for things that
*might* be new bugs not present in 1.11.2.  If you are really curious,
and have access to the FSF machines, see `/gd/gnu/tar/rmail/' hierarchy
for all reports.  Subdirectories `0', `1', `2' and `3' represent
decreasing levels in priority.  Most problems in there were reported
against 1.10, 1.11 or 1.11.2 and still exist.  The only thing I have
consciously broken between 1.11.2 and 1.11.5 is `--record-number'
(`-R'), because I wanted some modification to be done to
`gnulib/error.c', which is outside my control.  This modification is
now done, but I did not revisit this area yet.

   Here is my candid opinion.  GNU `tar' has many areas of
unreliability.  See `BACKLOG' for the horrorful picture of the
situation.  Yet, for most users and usages, GNU `tar' looks very
dependable.  For me as a mere user, GNU `tar' did not give problems in
years.  And I think it offers a lot of functionality.  Many problems
have been solved since 1.11.2, even if true that many more remain to be
solved.  I'm not discouraged myself and feel positive about maintaining
it, simply because when I bite, that usually lasts for quite long.  I
might not have all the time I would want, but I surely have good will
and am happily surrounded by many collaborating pretesters.  So, I
still think GNU `tar' is on the winning side in the long run.

Should we rewrite the thing?
----------------------------

   Working in `tar' sources is not always pleasurable.  The problem is
that `tar' sources are very fragile.  Just cleaning around breaks
things.  The current sequence of prereleases is for slowly trying to
solidify it, so `tar' becomes more maintainable.  I think that the
ugliness of sources could be corrected to a certain extent, too.

   A few efforts to replace GNU `tar' have been done already and it
seems that all failed so far.  A toy program, for me, is another kind
of failure.  I think people underestimate the number of portability
problems such a program can raise.  This is not only a matter of
programming style, there is really a wide variability in systems out
there.  GNU `tar' has a long history, met a rich variety of porting
problems, machine peculiarities, system idiosyncrasies, which are
unrelated to programming style.  My own opinion is that we cannot
dismiss all the experience gleaned along the years, and saved (if not
hidden) in GNU `tar' sources, pretending to start anew, from scratch.

   Even if a new program replacing GNU `tar' would be marvelous, GNU
`tar' stalled for a few years waiting for such a program, and we are
now faced to nothing, with hundreds of user reports to catch on.  We
need a working archiver *now*, and cannot live on promises.  Any new
program will take hundreds of user reports, and many years, to
stabilize enough to become a plausible `tar' replacement.  I rather
plan to clean up GNU `tar'.  This alone is a big task for me, because
GNU `tar' coding is not ideal, and I have to find ways to transform it
slowly, while having it fully working at all times.

Why maintaining it?
-------------------

   I confess that I am a little afraid of `tar' maintainance.  It is
difficult for many reasons, the first tree being more evident than the
others:

   * the algorithmic design was initially oriented for machines having
     very small memory, it was later much adapted for new features
     without doing everything necessary for the whole to stay clean;

   * the wide visibility of `tar' forces many stunts at portability;

   * GNU `tar' has to be sensitive to file systems and device variance.

   * GNU central has been seduced by some users promising to write
     wonderful `tar' replacements, which never came, so development has
     been put aside for years, while bug reports accumulated;

   * the `tar' manual has been withdrawn, promising users a fine
     replacement for it, so raising their expectations;

   * maintenance was once split between four maintainers (one for
     `tar', one for `mt', another for scripts, and a team for
     documentation), and also, `rtapelib.[ch]' from `tar' is used in
     `cpio', and synchronisation has not always been easy.

   However, even if difficult, I do feel like doing a careful cleanup,
so `tar' would become less painful to maintain after a while (and less
subject to criticism).  And besides, I'm surrounded by a marvelous team
of pretesters and by many other collaborating users, which I should
learn to serve better.  Getting more experience with maintainance in
GNU, I hope being careful enough modifying `tar' so not hurting users
too much, being aware that `tar' is a sensitive product in GNU.  Once
cleaned up, I might be happy to return `tar' maintainance to someone
else...

   `tar' requires more work alone that all my other things together,
and I have to resist being swallowed whole in it.  This resistance
makes `tar' development somewhat slower.  Sorry!

MSDOS and other systems?
------------------------

   GNU does not necessarily support non-UNIX systems, that is to say,
MSDOS is not supported.  It is very true that ports can sometimes be
very intrusive in the sources, cluttering them significantly with
conditionals and extra code, and distract GNU maintainers from the main
development line.

   However, a special argument might be made for `tar'.  Both `tar' and
`gzip' are the required tools for getting something out of the GNU
archives, `tar' should be more opened to ports than the GNU rule
states.  Jean-loup did a tremendous job at porting `gzip' on smaller
systems.  It would be comfortable that a few other GNU tools be
available on MSDOS and others, among which `tar'.  These ports for
`tar' have theoretically no priority at all.  Nevertheless, a port is
interesting, because `tar' is so central in GNU distributions, and
`gzip' is already ported.

   Some porting efforts have been done in the past.  There are traces of
a few exchanges on this subject in `BACKLOG'.  GNU `tar' sources have
been modified a lot recently at a cosmetic level, and I would certainly
have a hard time integrating diffs provided by someone else.  If people
want porting `tar' to MSDOS or other non-UNIX systems, they should be
committed in supporting their ports after the fact, as I cannot do it
myself.

Tutorial Introduction to `tar'
******************************

   This chapter guides you through some basic examples of `tar'
operations.  If you already know how to use some other version of
`tar', then you probably don't need to read this chapter.  This chapter
omits complicated details about many of the ways `tar' works.  See
later chapters for full information.

   Before proceeding further with this tutorial chapter, be sure you
understand already and clearly what is meant by "archive" and "archive
member".
FIXME: xref What tar Does
   .

   This chapter guides you through some basic examples of `tar'
operations.  In the examples, the lines you should type are preceded by
a `%', which is a typical shell prompt.  We use mnemonic forms of
operations and options in the examples, and in discussions in the text,
but short forms produce the same result.

   Most of the options to `tar' come in both long forms and short
forms.  The options described in this tutorial have the following
abbreviations (except `--delete', which has no shorthand form):

`--create'
     `-c'

`--list'
     `-t'

`--extract'
     `-x'

`--append'
     `-r'

`--verbose'
     `-v'

`--file=ARCHIVE-NAME'
     `-f ARCHIVE-NAME'

   These options make typing long `tar' commands easier.  For example,
instead of typing
     tar --create --file=/tmp/afiles.tar --verbose apple angst asparagus
   you can type
     tar -c -f /tmp/afiles.tar -v apple angst asparagus

   For more information on option syntax,
FIXME: ref Invoking tar
   .  In discussions in the text, when we present some mnemonic option,
we also give the corresponding short option within parentheses.

How to Create Archives
======================

     *(This message will disappear, once this node revised.)*

   To create a new archive, use the `--create' (`-c') option to `tar'.
You can use options to specify the name and format of the archive (as
well as other characteristics), and you can use file name arguments to
specify which files and directories are to be put in the archive.

FIXME: xref Creating
   , for more information about the `--create' (`-c') operation.

   To create a new archive, use the `--create' (`-c') option to `tar'.
You should generally use the `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME')
option to specify the name the `tar' archive will have.  Then specify
the names of the files you wish to place in the new archive.  For
example, to place the files `apple', `angst', and `asparagus' into an
archive named `afiles.tar', use the following command:

     tar --create --file=afiles.tar apple angst asparagus

   The order of the arguments is not important when using mnemonic
option style.  You could also say:

     tar apple --create angst --file=afiles.tar asparagus

   This order is harder to understand however.  In this manual, we will
list the arguments in a reasonable order to make the commands easier to
understand, but you can type them in any order you wish.

   If you don't specify the names of any files to put in the archive,
then `tar' will create an empty archive.  So, the following command
will create an archive with nothing in it:

     tar --create --file=empty-archive.tar

   Whenever you use `--create' (`-c'), `tar' will erase the current
contents of the file named by `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME')
if it exists.  To add files to an existing archive, you need to use a
different option.
FIXME: xref Adding to Archives, for information on how to do this.

   When an archive is created through `--create' (`-c'), the member
names of the members of the archive are exactly the same as the file
names as you typed them in the `tar' command.  So, the member names of
`afiles' (as created by the first example above) are `apple', `angst',
and `asparagus'.  However, suppose an archive were created with this
command:

     tar --create --file=bfiles.tar ./balloons baboon ./bodacious

   Then, the three files `balloons', `baboon', and `bodacious' would
get placed in the archive (because `./' is a synonym for the current
directory), but their member names would be `./balloons', `baboon', and
`./bodacious'.

   If you want to see the progress of `tar' as it writes files into the
archive, you can use the `--verbose' (`-v') option.

   If one of the files named with `--create' (`-c') is a directory, then
the operation of `tar' is more complicated.
FIXME: xref Tar and Directories,
FIXME: the last section of this tutorial, for more information.

   If you don't specify the `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME')
option, then `tar' will use a default.  Usually this default is some
physical tape drive attached to your machine.  If there is no tape
drive attached, or the default is not meaningful, then `tar' will print
an error message.  This error message might look roughly like one of
the following:

     tar: can't open /dev/rmt8 : No such device or address
     tar: can't open /dev/rsmt0 : I/O error

   If you get an error like this, mentioning a file you didn't specify
(`/dev/rmt8' or `/dev/rsmt0' in the examples above), then `tar' is
using a default value for `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME').
You should generally specify a `--file=ARCHIVE-NAME' (`-f
ARCHIVE-NAME') argument whenever you use `tar', rather than relying on
a default.

   To create a new archive, use the `--create' (`-c') option to `tar'.
You can use options to specify the name and format of the archive (as
well as other characteristics), and you can use file name arguments to
specify which files to put in the archive.  If you don't use any
options or file name arguments, `tar' will use default values.
FIXME: xref Creating Example
   , for more information about the `--create' (`-c') option.

Creating Archives of Files
--------------------------

     *(This message will disappear, once this node revised.)*

   This example shows you how to create an archive file in your working
directory containing other files in the same directory.  The three
files you archive in this example are called `blues', `folk', and
`jazz'.  The archive file is called `records'.  While the archive in
this example is written to the file system, it could also be written to
tape.  (If you want to follow along with this and future examples,
create a practice subdirectory containing files with these names.  To
create the directory, type `mkdir practice' at the system prompt.  You
can create the files using a text editor, such as `emacs').

   While in the directory containing the files you want to archive, list
the directory's contents.

   Type:

     % cd practice
     % ls

The system responds:

     blues	folk	jazz
     %

This is to check that the files to be archived do in fact exist in the
working directory, and to check that the archive name you have chosen
isn't already in use.  If it is, `tar' will overwrite the old archive
and its contents will be lost.

   Then,
   * Create a new archive by giving `--create' (`-c') to `tar'.

   * Explicitly name the archive file being
     created--`--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME').  If you don't
     use this option `tar' will write the archive to the default
     storage device, which varies from system to system.

   * Specify which files to put into the archive.  If you don't specify
     any FILE NAME arguments, `tar' will archive everything in the
     working directory.

Type:
     % tar --create --file=records blues folk jazz

If you now list the contents of the working directory (`ls'), you will
find the archive file listed as well as the files you saw previously.

     % ls
     blues folk jazz records
     %

   This example shows you how to create an archive file in the working
directory containing other files in the working directory.  The three
files you archive in this example are called `blues', `folk', and
`jazz'.  The archive file is called `records'.  While the archive in
this example is written to the file system, it could also be written to
any other device.

   (If you want to follow along with this and future examples, create a
directory called `practice' containing files called `blues', `folk' and
`jazz'.  To create the directory, type `mkdir practice' at the system
prompt.  It will probably be easiest to create the files using a text
editor, such as Emacs.)

   First, change into the directory containing the files you want to
archive:

     % cd practice

   `~/practice' is now your working directory.

   Then, check that the files to be archived do in fact exist in the
working directory, and make sure there isn't already a file in the
working directory with the archive name you intend to use.  If you
specify an archive file name that is already in use, `tar' will
overwrite the old file and its contents will be lost.

   To list the names of files in the working directory, type:

     % ls

   The system responds:

     blues   folk    jazz
     %

   Then,

   * Create a new archive by giving the `--create' (`-c') option to
     `tar'.

   * Explicitly name the archive file being
     created--`--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME').  If you don't
     use this option `tar' will write the archive to the default
     storage device, which varies from system to system.
     FIXME: this syntax may change.  OK now--check before printing

     `tar' interprets archive file names relative to the working
     directory.  Make sure you have write access to the working
     directory before using `tar'.

   * Specify which files to put into the archive (`tar' interprets file
     names relative to the working directory).  If you don't use any
     NAME arguments, `tar' will archive everything in the working
     directory.

   Type:
     % tar --create --file=records blues folk jazz

   If you now list the contents of the working directory (`ls'), you
will find the archive file listed as well as the files you saw
previously.

     % ls
     blues folk jazz records
     %

Using `tar' in Verbose Mode
---------------------------

     *(This message will disappear, once this node revised.)*

   If you include the `--verbose' (`-v') option on the command line,
`tar' will list the files it is acting on as it is working.  The
example above in verbose mode would be:

     % tar --create --file=records --verbose blues folk jazz
     blues
     folk
     jazz

The first line, which is preceeded by a `%', is the command line.  The
lines after the first line are generated by `tar' as it works.  In the
following examples we usually use verbose mode, though it is almost
never required.

   If you include the `--verbose' (`-v') option on the command line,
`tar' will list the files it is acting on as it is working. In verbose
mode, the creation example above would appear as:

     % tar --create --file=records --verbose blues folk jazz
     blues
     folk
     jazz

   The first line is the command typed in by the user.  The remaining
lines are generated by `tar'.  In the following examples we usually use
verbose mode, though it is almost never required.

How to Archive Directories
--------------------------

     *(This message will disappear, once this node revised.)*

   When the names of files or members specify directories, the
operation of `tar' is more complex.  Generally, when a directory is
named, `tar' also operates on all the contents of the directory,
recursively.  Thus, to `tar', the file name `/' names the entire file
system.

   To archive the entire contents of a directory, use `--create' (`-c')
or `--append' (`-r') as usual, and specify the name of the directory.
For example, to archive all the contents of the current directory, use
`tar --create --file=ARCHIVE-NAME .'.  Doing this will give the archive
members names starting with `./'.  To archive the contents of a
directory named `foodir', use `tar --create --file=ARCHIVE-NAME
foodir'.  In this case, the member names will all start with `foodir/'.

   If you give `tar' a command such as `tar --create --file=foo.tar .',
it will report `tar: foo.tar is the archive; not dumped'.  This happens
because the archive `foo.tar' is created before putting any files into
it.  Then, when `tar' attempts to add all the files in the directory
`.' to the archive, it notices that the file `foo.tar' is the same as
the archive, and skips it.  (It makes no sense to put an archive into
itself.)  GNU `tar' will continue in this case, and create the archive
as normal, except for the exclusion of that one file.  Other versions
of `tar', however, are not so clever, and will enter an infinite loop
when this happens, so you should not depend on this behavior.  In
general, make sure that the archive is not inside a directory being
dumped.

   When extracting files, you can also name directory archive members on
the command line.  In this case, `tar' extracts all the archive members
whose names begin with the name of the directory.  As usual, `tar' is
not particularly clever about interpreting member names.  The command
`tar --extract --file=ARCHIVE-NAME .' will not extract all the contents
of the archive, but only those members whose member names begin with
`./'.

Creating an Archive from the Superior Directory
-----------------------------------------------

     *(This message will disappear, once this node revised.)*

   You can archive a directory by specifying its directory name as a
file name argument to `tar'.  The files in the directory will be
archived relative to the working directory, and the directory will be
re-created along with its contents when the archive is extracted.

   To archive a directory, first move to its superior directory.  If you
have been following the tutorial, you should type:

     % cd ..
     %

   Once in the superior directory, you can specify the subdirectory as a
file name argument.  To store the directory `practice' in the archive
file `music', type:

     % tar --create --verbose --file=music practice

`tar' should output:

     practice/
     practice/blues
     practice/folk
     practice/jazz
     practice/records

   Note that the archive thus created is not in the subdirectory
`practice', but rather in the working directory--the directory from
which `tar' was invoked.  Before trying to archive a directory from its
superior directory, you should make sure you have write access to the
superior directory itself, not only the directory you are trying
archive with `tar'.  Trying to store your home directory in an archive
by invoking `tar' from the root directory will probably not work.
FIXME: xref absolute-names
   (Note also that `records', the original archive file, has itself
been archived.  `tar' will accept any file as a file to be archived,
regardless of its content.  When `music' is extracted, the archive file
`records' will be re-written into the file system).

   You can store a directory in an archive by using the directory name
as a file name argument to `tar'.  When you specify a directory file,
`tar' archives the directory file and all the files it contains.  The
names of the directory and the files it contains are stored in the
archive relative to the current working directory-when the directory is
extracted they will be written into the file system relative to the
working directory at that time.
FIXME: add an xref to --absolute-names

   To archive a directory, first move to its superior directory.  If you
have been following the tutorial, you should type:

     % cd ..
     %

   Once in the superior directory, specify the subdirectory using a
file name argument.  To store the directory file `~/practice' in the
archive file `music', type:

     % tar --create --verbose --file=music practice

   `tar' should respond:

     practice/
     practice/blues
     practice/folk
     practice/jazz
     practice/records

   Note that `~/practice/records', another archive file, has itself
been archived.  `tar' will accept any file as a file to be archived,
even an archive file.

FIXME: symbolic links and changing directories are now in main body,
FIXME: not in tutorial.

Comparing Files in an Archive with Files in the File System
-----------------------------------------------------------

     *(This message will disappear, once this node revised.)*

   While the `--list' (`-t') operation with the `--verbose' (`-v')
option specified is useful in keeping files in the archive current with
files in the file system (by allowing the user to compare size and
modification dates), it is simpler to have `tar' itself compare file
attributes and report back on file differences.  To do so, use the
`--compare' (`-d') or `--diff' operation.

   The `--compare' (`-d') operation, as its name implies, causes `tar'
to compare files and directories in the archive with their counterparts
(files of the same name) in the file system, and report back
differences in file size, mode, owner and modification date.  When
performing the `--compare' (`-d') operation, `tar' acts only on files
actually in the archive--it will ignore files in the active file system
that do not exist in the archive.  If `tar' with `--compare' (`-d')
specified is given, as a file name argument, the name of a file that
does not exist in the archive, it will return an error message.

   To compare the files in the practice directory with their
counterparts in the archive file `records', in the same directory, you
would, while in the `practice' directory:

   * Invoke `tar' and specify the operation to compare files in the
     archive with their counterparts in the file system--`--compare'
     (`-d') or `--diff'.

   * Specify the name of the archive where the files to be compared are
     stored--`--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME').

   * Specify the names of the files or directories to be compared, as
     file name arguments (in this case, you are comparing all the files
     in the archive, so nothing need be specified).

     % tar --compare --file=records
     %

While it looks like nothing has happened, `tar' has, in fact, done the
comparison--and found nothing to report.  The same example with the
`--verbose' (`-v') option specified would list the files in the archive
as they are being compared with their counterparts of the same name:

     % tar --compare --verbose --file=records
     blues
     folk
     jazz
     %

   If `tar' had had anything to report, it would have done so as it was
comparing each file.  If you remove the file `jazz' from the file
system (`rm jazz'), and modify the file `blues' (for instance, by
adding text to it with a text editor), the above example would look
like:

     % tar --compare --verbose --file=records
     blues
     blues: mod time differs
     blues: size differs
     folk
     jazz
     jazz: does not exist
     %

   You should note again that while `--compare' (`-d') does cause `tar'
to report back on files in the archive that do not exist in the file
system, `tar' will ignore files in the active file system that do not
exist in the archive.  To demonstrate this, create a file in the
`practice' directory called `rock' (using any text editor).  If you
generate a directory listing the new file will appear.

     % ls
     blues	 folk	  records  rock

If you run the `--compare' (`-d') example again you will obtain the
following:

     % tar --compare --verbose --file=records
     blues
     blues: mod time differs
     blues: size differs
     folk
     jazz
     jazz: does not exist
     %

   `tar' ignores the file `rock' because `tar' is comparing files in
the archive to files in the file system, not vice versa.  If `rock' had
been passed to `tar' explicitly (as a file name argument), `tar' would
have returned an error message, as follows:

     % tar --compare --verbose --file=records rock
     tar: rock not found in archive
     %

   To compare the attributes of archive members with the attributes of
their counterparts in the file system, use the `--compare' (`-d') or
`--diff'operation.  While you could use `--list --verbose' (`-tv') to
manually compare some file attributes, it is simpler to have `tar'
itself compare file attributes and report back on file differences.
FIXME: "manually"?  suggestions?

   The `--compare' (`-d') operation, as its name implies, compares
archive members with files of the same name in the file system, and
reports back differences in file size, mode, owner and modification
date. `tar +compare' acts only on archive members-it ignores files in
the file system that are not stored in the archive.  If you give with
`--compare' (`-d') a NAME argument that does not correspond to the name
of an archive member, `tar' responds with an error message.

   To compare archive members in the archive file `records' with files
in the `~/practice' directory, first change into the `practice'
directory.  Then:

   * Invoke `tar' and specify the `--compare' (`-d')
     operation--`--compare' (`-d') or `--diff'.

   * Specify the archive where the files to be compared are
     stored--`--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME').

   * Specify the archive members to be compared.  (In this example you
     are comparing all the archive members in the archive.  Since this
     is the default, you don't need to use any file name arguments).

     % tar --compare --file=records
     %

   While it looks like nothing has happened, `tar' has, in fact, done
the comparison--and found nothing to report.

   Use the `--verbose' (`-v') option to list the names of archive
members as they are being compared with their counterparts of the same
name in the file system:

     % tar --compare --verbose --file=records
     blues
     folk
     jazz
     %

   If `tar' had had anything to report, it would have done so as it was
comparing each file.

   If you remove the file `jazz' from the file system (`rm jazz'), and
modify the file `blues' (for instance, by adding text to it with an
editor such as Emacs), the above example would look like:

     % tar --compare --verbose --file=records
     blues
     blues: mod time differs
     blues: size differs
     folk
     jazz
     jazz: does not exist
     %

   Note again that while `--compare' (`-d') reports the names of archive
members that do not have counterparts in the file system, `--compare'
(`-d') ignores files in the file system that do not have counterparts
in the archive.  To demonstrate this, create a file in the `practice'
directory called `rock' (using any text editor).  The new file appears
when you list the directory's contents:

FIXME: Given an example

Using Compare from the Superior Directory
-----------------------------------------

     *(This message will disappear, once this node revised.)*

   In addition to using `--compare' (`-d') to compare individual files
in an archive with their counterparts in the file system, you can use
`--compare' (`-d') to compare archived directories with their
counterparts in the active file system.  You could re-create the
examples above using your home directory as the working directory, and
using the archive file `music' (in which is stored the `practice'
directory) instead of the archive file `records'.

   First, change into the home directory (`cd ..').  Then, try the
above example using `music' as the specified archive file, and the
`practice' subdirectory as a file name argument.

     % tar --compare --verbose --file=music practice
     practice
     practice/blues
     practice/blues: mod time differs
     practice/blues: size differs
     practice/folk
     practice/jazz
     practice/jazz: does not exist
     practice/records

   In addition to using `--compare' (`-d') to compare text files, you
can use `--compare' (`-d') to compare directories.  To illustrate this,
re-create the examples above using your home directory as the working
directory, and using the archive file `~/music' instead of the archive
file `~/practice/records'.

   First, change into your home directory (`cd ~').  Then, try the
above example using `music' as the specified archive file, and
`practice' as a file name argument.

     % tar --compare --verbose --file=music practice

   If you have been following along with the tutorial, `tar' will
respond:

     practice
     practice/blues
     practice/blues: mod time differs
     practice/blues: size differs
     practice/folk
     practice/jazz
     practice/jazz: does not exist
     practice/records

How to List Archives
====================

     *(This message will disappear, once this node revised.)*

   Use `--list' (`-t') to print the names of members stored in an
archive.  Use a `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option just
as with `--create' (`-c') to specify the name of the archive.  For
example, the archive `afiles.tar' created in the last section could be
examined with the command `tar --list --file=afiles.tar'.  The output
of `tar' would then be:

     apple
     angst
     asparagus

   The archive `bfiles.tar' would list as follows:

     ./baloons
     baboon
     ./bodacious

   (Of course, `tar --list --file=empty-archive.tar' would produce no
output.)

   If you use the `--verbose' (`-v') option with `--list' (`-t'), then
`tar' will print out a listing reminiscent of `ls -l', showing owner,
file size, and so forth.

   You can also specify member names when using `--list' (`-t').  In
this case, `tar' will only list the names of members you identify.  For
example, `tar --list --file=afiles.tar apple' would only print `apple'.
It is essential when specifying member names to `tar' that you give
the exact member names.  For example, `tar --list --file=bfiles
baloons' would produce no output, because there is no member named
`baloons', only one named `./baloons'.  While the file names `baloons'
and `./baloons' name the same file, member names are compared using a
simplistic name comparison, in which an exact match is necessary.