This is Info file tar.info, produced by Makeinfo version 1.67 from the
input file tar.texi.

START-INFO-DIR-ENTRY
* tar: (tar).			Making tape (or disk) archives.
END-INFO-DIR-ENTRY

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

   Copyright (C) 1992, 1994, 1995, 1996, 1997 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.

   This file documents GNU `tar', which is a utility used to store,
backup, and transport files.  `tar' is a tape (or disk) archiver.  This
manual documents the release 1.12a.


File: tar.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

* Menu:

* Introduction::
* Tutorial::                    A Tutorial to using tar, which presents
                                  the create, list, and extract
                                  subcommands in full.
* Subcommands::                 How to use the append, update, compare,
                                  delete, and concatenate subcommands.
* Backups::
* Choosing::
* Date input formats::
* Formats::
* Media::
* tar invocation::
* All Options::
* documentation and help::
* Index::

 -- The Detailed Node Listing --

Introduction

* Book Contents::               What this Book Contains
* Definitions::                 Some Definitions
* What tar Does::               What `tar' Does
* Naming tar Archives::         How `tar' Archives are Named
* posix compliance::
* Authors::                     GNU `tar' Authors
* Reports::                     Reporting bugs or suggestions

Tutorial Introduction to `tar'

* assumptions::
* stylistic conventions::
* basic tar options::           Basic `tar' Subcommands and Options
* frequent subcommands::
* Two Frequent Options::
* create::                      How to Create Archives
* list::                        How to List Archives
* extract::                     How to Extract Members from an Archive
* going further::

Two Frequently Used Options

* file tutorial::
* verbose tutorial::
* help tutorial::

How to Create Archives

* prepare for examples::
* Creating the archive::
* create verbose::
* short create::
* create dir::
* create prefix::

How to List Archives

* list dir::

How to Extract Members from an Archive

* extracting archives::
* extracting files::
* extract dir::
* failing commands::

GNU `tar' Subcommands

* Basic tar::
* current state::
* append::
* update::
* concatenate::
* delete::
* compare::
* extract options::
* backup::
* Applications::
* looking ahead::

How to Add Files to Existing Archives: `--append'

* appending files::             Appending Files to an Archive
* multiple::

Updating an Archive

* how to update::

Options Used by `--extract'

* Reading::                     Options to Help Read Archives
* Writing::                     Changing How `tar' Writes Files
* Scarce::                      Coping with Scarce Resources

Options to Help Read Archives

* read full records::
* Ignore Zeros::
* Ignore Failed Read::

Changing How `tar' Writes Files

* Prevention Overwriting::
* Keep Old Files::
* Unlink First::
* Recursive Unlink::
* Modification Times::
* Setting Access Permissions::
* Writing to Standard Output::
* remove files::

Options to Prevent Overwriting Files

* Keep Old Files::
* Unlink First::
* Recursive Unlink::

Coping with Scarce Resources

* Starting File::
* Same Order::

Performing Backups and Restoring Files

* Full Dumps::                  Using `tar' to Perform Full Dumps
* Inc Dumps::                   Using `tar' to Perform Incremental Dumps
* incremental and listed-incremental::  The Incremental Options
* Backup Levels::               Levels of Backups
* Backup Parameters::           Setting Parameters for Backups and Restoration
* Scripted Backups::            Using the Backup Scripts
* Scripted Restoration::        Using the Restore Script

Setting Parameters for Backups and Restoration

* backup-specs example::        An Example Text of `Backup-specs'
* Script Syntax::               Syntax for `Backup-specs'

Choosing Files and Names for `tar'

* file::                        Choosing the Archive's Name
* Selecting Archive Members::
* files::                       Reading Names from a File
* exclude::                     Excluding Some Files
* Wildcards::
* after::                       Operating Only on New Files
* recurse::                     Descending into Directories
* one::                         Crossing Filesystem Boundaries

Reading Names from a File

* nul::

Excluding Some Files

* problems with exclude::

Crossing Filesystem Boundaries

* directory::                   Changing Directory
* absolute::                    Absolute File Names

Date Input Formats

* General date syntax::         Common rules.
* Calendar date item::          19 Dec 1994.
* Time of day item::            9:20pm.
* Timezone item::               EST, DST, BST, UCT, AHST, ...
* Day of week item::            Monday and others.
* Relative item in date strings::  next tuesday, 2 years ago.
* Pure numbers in date strings::  19931219, 1440.
* Authors of getdate::          Bellovin, Salz, Berets, et al.

Controlling the Archive Format

* Portability::                 Making `tar' Archives More Portable
* Compression::                 Using Less Space through Compression
* Attributes::                  Handling File Attributes
* Standard::                    The Standard Format
* Extensions::                  GNU Extensions to the Archive Format
* cpio::                        Comparison of `tar' and `cpio'

Making `tar' Archives More Portable

* Portable Names::              Portable Names
* dereference::                 Symbolic Links
* old::                         Old V7 Archives
* posix::                       POSIX archives
* Checksumming::                Checksumming Problems

Using Less Space through Compression

* gzip::                        Creating and Reading Compressed Archives
* sparse::                      Archiving Sparse Files

Tapes and Other Archive Media

* Device::                      Device selection and switching
* Remote Tape Server::
* Common Problems and Solutions::
* Blocking::                    Blocking
* Many::                        Many archives on one tape
* Using Multiple Tapes::        Using Multiple Tapes
* label::                       Including a Label in the Archive
* verify::
* Write Protection::

Blocking

* Format Variations::           Format Variations
* Blocking Factor::             The Blocking Factor of an Archive

Many Archives on One Tape

* Tape Positioning::            Tape Positions and Tape Marks
* mt::                          The `mt' Utility

Using Multiple Tapes

* Multi-Volume Archives::       Archives Longer than One Tape or Disk
* Tape Files::                  Tape Files

Invoking GNU `tar'

* Synopsis::
* using tar options::
* Styles::

The Three Option Styles

* Mnemonic Options::            Mnemonic Option Style
* Short Options::               Short Option Style
* Old Options::                 Old Option Style
* Mixing::                      Mixing Option Styles

All `tar' Options

* Subcommand Summary::
* Option Summary::
* Short Option Summary::

Documentation and Troubleshooting

* verbose::
* interactive::


File: tar.info,  Node: Introduction,  Next: Tutorial,  Prev: Top,  Up: Top

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

   Welcome to the GNU `tar' manual.  GNU `tar' is used to create and
manipulate files ("archives") which are actually collections of many
other files; the program provides users with an organized and
systematic method for controlling a large amount of data.

* Menu:

* Book Contents::               What this Book Contains
* Definitions::                 Some Definitions
* What tar Does::               What `tar' Does
* Naming tar Archives::         How `tar' Archives are Named
* posix compliance::
* Authors::                     GNU `tar' Authors
* Reports::                     Reporting bugs or suggestions


File: tar.info,  Node: Book Contents,  Next: Definitions,  Prev: Introduction,  Up: Introduction

What this Book Contains
=======================

   The first part of this chapter introduces you to various terms that
will recur throughout the book.  It also tells you who has worked on GNU
`tar' and its documentation, and where you should send bug reports or
comments.

   The second chapter is a tutorial (*note Tutorial::.) which provides a
gentle introduction for people who are new to using `tar'.  It is meant
to be self-contained, not requiring any reading from subsequent
chapters to make sense.  It moves from topic to topic in a logical,
progressive order, building on information already explained.

   Although the tutorial is paced and structured to allow beginners to
learn how to use `tar', it is not intended solely for beginners.  The
tutorial explains how to use the three most frequently used subcommands
(`create', `list', and `extract') as well as two frequently used
options (`file' and `verbose').  The other chapters do not refer to the
tutorial frequently; however, if a section discusses something which is
a complex variant of a basic concept, there may be a cross reference to
that basic concept.  (The entire book, including the tutorial, assumes
that the reader understands some basic concepts of using a Unix-type
operating system; *note Tutorial::..)

   The third chapter presents the remaining five subcommands, and
information about using `tar' options and option syntax.  The other
chapters are meant to be used as a reference.  Each chapter presents
everything that needs to be said about a specific topic.

   One of the chapters (*note Date input formats::.) exists in its
entirety in other GNU manuals, and is mostly self-contained.  In
addition, one section of this manual (*note Standard::.) contains a big
quote which is taken directly from `tar' sources.

   In general, we give both the long and short (abbreviated) option
names at least once in each section where the relevant option is
covered, so that novice readers will become familiar with both styles.
(A few options have no short versions, and the relevant sections will
indicate this.)


File: tar.info,  Node: Definitions,  Next: What tar Does,  Prev: Book Contents,  Up: Introduction

Some Definitions
================

   The `tar' program is used to create and manipulate `tar' archives.
An "archive" is a single file which contains the contents of many
files, while still identifying the names of the files, their owner(s),
and so forth(1).  You can use `tar' to "create" a new archive in a
specified directory.

   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 "member" 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.

   The term "extraction" refers to the process of copying an archive
member (or multiple members) into a file in the filesystem.  Extracting
all the members of an archive is often called "extracting the archive".
The term "unpack" can also be used to refer to the extraction of many
or all the members of an archive.  Extracting an archive does not
destroy the archive's structure, just as creating an archive does not
destroy the copies of the files that exist outside of the archive.  You
may also "list" the members in a given archive (this is often thought
of as "printing" them to the standard output, or the command line), or
"append" members to a pre-existing archive.  All of these subcommands
can be peformed using `tar'.

   ---------- Footnotes ----------

   (1)  In addition, 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.


File: tar.info,  Node: What tar Does,  Next: Naming tar Archives,  Prev: Definitions,  Up: Introduction

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

   The `tar' program provides the ability to create `tar' archives, as
well as 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 which were already stored.

   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 available devices, files, or other programs (using pipes).
`tar' may even access remote devices or files (as archives).

   You can use `tar' archives in many ways.  We want to stress a few of
them: storage, backup, and 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.  However, the
     tape has no names for these files; it only knows their relative
     position on the tape.  One way to store several files on one tape
     and retain their names is by creating a `tar' archive.  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 useful.

     Archive files are also used for long-term storage.  You can think
     of this as transportation from the present into the future.  (It
     is a science-fiction idiom that you can move through time as well
     as in space; the idea here is that `tar' can be used to move
     archives in all dimensions, even time!)

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.  A backup puts a
     collection of files (possibly pertaining to many users and
     projects) together on a disk or a tape.  This guards against
     accidental destruction of the information in those files.  GNU
     `tar' has special features that allow it to be used to make
     incremental and full dumps of all the files in a filesystem.

Transportation
     You can create an archive on one system, transfer it to another
     system, and extract the contents there.  This allows you to
     transport a group of files from one system to another.


File: tar.info,  Node: Naming tar Archives,  Next: posix compliance,  Prev: What tar Does,  Up: Introduction

How `tar' Archives are Named
============================

   Conventionally, `tar' archives are given names ending with `.tar'.
This is not necessary for `tar' to operate properly, but this manual
follows that convention in order to accustom readers to it and to make
examples more clear.

   Often, people refer to `tar' archives as "`tar' files," and archive
members as "files" or "entries".  For people familiar with the
operation of `tar', this causes no difficulty.  However, in this
manual, we consistently refer to "archives" and "archive members" to
make learning to use `tar' easier for novice users.


File: tar.info,  Node: posix compliance,  Next: Authors,  Prev: Naming tar Archives,  Up: Introduction

POSIX Compliance
================

   We make some of our recommendations throughout this book for one
reason in addition to what we think of as "good sense".  The main
additional reason for a recommendation is to be compliant with the
POSIX standards.  If you set the shell environment variable
`POSIXLY_CORRECT', GNU `tar' will force you to adhere to these
standards.  Therefore, if this variable is set and you violate one of
the POSIX standards in the way you phrase a command, for example, GNU
`tar' will not allow the command and will signal an error.  You would
then have to reorder the options or rephrase the command to comply with
the POSIX standards.

   There is a chance in the future that, if you set this environment
variable, your archives will be forced to comply with POSIX standards,
also.  No GNU `tar' extensions will be allowed.


File: tar.info,  Node: Authors,  Next: Reports,  Prev: posix compliance,  Up: Introduction

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

   GNU `tar' was originally written by John Gilmore, and modified by
many people.  The GNU enhancements were written by Jay Fenlason, then
Joy Kendall, and the whole package has been further maintained by
Thomas Bushnell, n/BSG, and finally Franc,ois Pinard, with the help of
numerous and kind users.

   We wish to stress that `tar' is a collective work, and owes much to
all those people who reported problems, offered solutions and other
insights, or shared their thoughts and suggestions.  An impressive, yet
partial list of those contributors can be found in the `THANKS' file
from the GNU `tar' distribution.

   Jay Fenlason put together a draft of a GNU `tar' manual, borrowing
notes from the original man page from John Gilmore.  This draft has been
distributed in `tar' versions 1.04 through 1.10, then withdrawn in
version 1.11.  Michael Innis Bushnell (later known as Thomas) and Amy
Gorin worked on a tutorial and manual for GNU `tar'.  Franc,ois Pinard
put version 1.11.8 of the manual together by taking information from
all these sources and merging them.  Melissa Weisshaus revised many
parts of the manual and reorganised its structure, around version 1.12,
in view of publication by the FSF.  Some people especially contributed
to specific aspects of the manual: Karl Berry (dates), Dan Hagerty
(backups), Eli Zaretskii (MS-DOS), and surely others.


File: tar.info,  Node: Reports,  Prev: Authors,  Up: Introduction

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

   If you find problems or have suggestions about this program or
manual, please report them to `tar-bugs@iro.umontreal.ca'.


File: tar.info,  Node: Tutorial,  Next: Subcommands,  Prev: Introduction,  Up: Top

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

   This chapter guides you through some basic examples of three `tar'
subcommands: `--create', `--list', and `--extract'.  If you already
know how to use some other version of `tar', then you may not need to
read this chapter.  This chapter omits most complicated details about
how `tar' works.

* Menu:

* assumptions::
* stylistic conventions::
* basic tar options::           Basic `tar' Subcommands and Options
* frequent subcommands::
* Two Frequent Options::
* create::                      How to Create Archives
* list::                        How to List Archives
* extract::                     How to Extract Members from an Archive
* going further::


File: tar.info,  Node: assumptions,  Next: stylistic conventions,  Prev: Tutorial,  Up: Tutorial

Assumptions this Tutorial Makes
===============================

   This chapter is paced to allow beginners to learn about `tar'
slowly.  At the same time, we will try to cover all the basic aspects of
these three subcommands.  In order to accomplish both of these tasks, we
have made certain assumptions about your knowledge before reading this
manual, and the hardware you will be using:

   * Before you start to work through this tutorial, you should
     understand what the terms "archive" and "archive member" mean
     (*note Definitions::.).  In addition, you should understand
     something about how Unix-type operating systems work, and you
     should know how to use some basic utilities.  For example, you
     should know how to create, list, copy, rename, edit, and delete
     files and directories; how to change between directories; and how
     to figure out where you are in the 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 the file
     permission system.

   * This manual assumes that you are working from your own home
     directory (unless we state otherwise).  In this tutorial, you will
     create a directory to practice `tar' commands in.  When we show
     path names, we will assume that those paths are relative to your
     home directory.  For example, my home directory path is
     `/home/fsf/melissa'.  All of my examples are in a subdirectory of
     the directory named by that path name; the subdirectory is called
     `practice'.

   * In general, we show examples of archives which exist on (or can be
     written to, or worked with from) a directory on a hard disk.  In
     most cases, you could write those archives to, or work with them
     on any other device, such as a tape drive.  However, some of the
     later examples in 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.  *Note Media::
     for complete information on using `tar' archives with tape drives.


File: tar.info,  Node: stylistic conventions,  Next: basic tar options,  Prev: assumptions,  Up: Tutorial

Stylistic Conventions
=====================

   In the examples, `$' represents a typical shell prompt.  It precedes
lines you should type; to make this more clear, those lines as well as
the lines which represent the computer's response are shown in `like
this'.


File: tar.info,  Node: basic tar options,  Next: frequent subcommands,  Prev: stylistic conventions,  Up: Tutorial

`tar' Subcommands and Options
=============================

   `tar' can take a wide variety of arguments which specify and define
the actions it will perform on the particular set of files or the
archive.  The main types of arguments to `tar' fall into one of two
classes: subcommands, and options.

   Some arguments fall into a class called "subcommands"; exactly one of
these is both allowed and required for any instance of using `tar'; you
may *not* specify more than one.  People sometimes speak of them as
"operating modes".  You are in a particular operating mode when you
have specified the subcommand which calls for that mode; there are eight
subcommands in total, and thus there are eight operating modes.

   The other arguments fall into the class known as "options".  You are
not required to specify any options, and you are allowed to specify more
than one at a time (depending on the way you are using `tar' at that
time).  Some options are used so frequently, and are so useful for
helping you type commands more carefully that they are effectively
"required".  We will discuss them in this chapter.

   You can write most of the `tar' subcommands and options in any of
three forms: long (mnemonic) form, short form, and old style.  Some of
the subcommands and options have no short or "old" forms; however, the
subcommands and options which we will cover in this tutorial have
corresponding abbreviations.    We will indicate those abbreviations
appropriately to get you used to seeing them.  (Note that the "old
style" option forms exist in GNU `tar' for compatibility with Unix
`tar'.  We present a full discussion of this way of writing options and
subcommands in *Note Old Options::, and we discuss the other two styles
of writing options in *Note Mnemonic Options:: and *Note Short
Options::.)

   In the examples and in the text of this tutorial, we usually use the
long forms of subcommands and options; but the "short" forms produce
the same result and can make typing long `tar' commands easier.  For
example, instead of typing

     tar --create --verbose --file=afiles.tar apple angst aspic

you can type
     tar -c -v -f afiles.tar apple angst aspic

or even
     tar -cvf afiles.tar apple angst aspic

For more information on option syntax, see *Note Styles::.  In
discussions in the text, when we name an option by its long form, we
also give the corresponding short option in parentheses.

   The term, "option", can be confusing at times, since "subcommands"
are often lumped in with the actual, *optional* "options" in certain
general class statements.  For example, we just talked about "short and
long forms of options and subcommands".  However, experienced `tar'
users often refer to these by shorthand terms such as, "short and long
forms of options".  This term assumes that the "subcommands" are
included, also.  Context will help you determine which definition of
"options" to use.

   Similarly, the term "command" can be confusing, as it is often used
in two different ways.  People sometimes refer to `tar' "commands".
The term, `tar' "commands", refers to the various *subcommands*.
However, you will also sometimes hear the term "the `tar' command".
When the word "command" is used specifically like this, a person is
usually referring to the whole line, not the `tar' *subcommand*.
Again, use context to figure out which of the meanings the speaker
intends.


File: tar.info,  Node: frequent subcommands,  Next: Two Frequent Options,  Prev: basic tar options,  Up: Tutorial

The Three Most Frequently Used Subcommands
==========================================

   Here are the three most frequently used subcommands (both short and
long forms), as well as a brief description of their meanings.  The
rest of this chapter will cover how to use these subcommands in detail.
We will present the rest of the subcommands in the next chapter.

`--create'
`-c'
     Create a new `tar' archive.

`--list'
`-t'
     List the contents of an archive.

`--extract'
`-x'
     Extract one or more members from an archive.


File: tar.info,  Node: Two Frequent Options,  Next: create,  Prev: frequent subcommands,  Up: Tutorial

Two Frequently Used Options
===========================

   To understand how to run `tar' in the three operating modes listed
previously, you also need to understand how to use two of the options to
`tar': `--file' (which takes an archive file as an argument) and
`--verbose'.  (You are usually not *required* to specify either of
these options when you run `tar', but they can be very useful in making
things more clear and helping you avoid errors.)

* Menu:

* file tutorial::
* verbose tutorial::
* help tutorial::


File: tar.info,  Node: file tutorial,  Next: verbose tutorial,  Prev: Two Frequent Options,  Up: Two Frequent Options

The `--file' Option
-------------------

`--file=ARCHIVE-NAME'
`-f ARCHIVE-NAME'
     Specify the name of an archive file.

   You can specify an argument for the `--file=ARCHIVE-NAME' (`-f
ARCHIVE-NAME') option whenever you use `tar'; this option determines
the name of the archive file that `tar' will work on.

   If you don't specify this argument, then `tar' will use a default,
usually standard output or standard input, or 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.  The
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

To avoid confusion, we recommend that you always specfiy an archive file
name by using `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') when writing
your `tar' commands.  For more information on using the
`--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option, see *Note file::.


File: tar.info,  Node: verbose tutorial,  Next: help tutorial,  Prev: file tutorial,  Up: Two Frequent Options

The `--verbose' Option
----------------------

`--verbose'
`-v'
     Show the files being worked on as `tar' is running.

   `--verbose' (`-v') shows details about the results of running `tar'.
This can be especially useful when the results might not be obvious.
For example, if you want to see the progress of `tar' as it writes
files into the archive, you can use the `--verbose' option.  In the
beginning, you may find it useful to use `--verbose' at all times; when
you are more accustomed to `tar', you will likely want to use it at
certain times but not at others.  We will use `--verbose' at times to
help make something clear, and we will give many examples both using
and not using `--verbose' to show the differences.

   Sometimes, a single instance of `--verbose' on the command line will
show a full, `ls' style listing of an archive or files, giving sizes,
owners, and similar information.  Other times, `--verbose' will only
show files or members that the particular subcommand is operating on at
the time.  In the latter case, you can use `--verbose' twice in a
command to get a listing such as that in the former case.  For example,
instead of saying

     tar -cvf afiles.tar apple angst aspic

above, you might say

     tar -cvvf afiles.tar apple angst aspic

This works equally well using short or long forms of options.  Using
long forms, you would simply write out the mnemonic form of the option
twice, like this:

     $ tar --create --verbose --verbose ...

Note that you must double the hyphens properly each time.

   Later in the tutorial, we will give examples using
`--verbose --verbose'.


File: tar.info,  Node: help tutorial,  Prev: verbose tutorial,  Up: Two Frequent Options

Getting Help: Using the `--help' Option
---------------------------------------

`--help'
     The `--help' option to `tar' prints out a very brief list of all
     subcommands and options available for the current version of `tar'
     available on your system.


File: tar.info,  Node: create,  Next: list,  Prev: Two Frequent Options,  Up: Tutorial

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

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

   One of the basic subcommands of `tar' is `--create' (`-c'), which
you use to create a `tar' archive.  We will explain `--create' first
because, in order to learn about the other subcommands, you will find
it useful to have an archive available to practice on.

   To make this easier, in this section you will first create a
directory containing three files.  Then, we will show you how to create
an *archive* (inside the new directory).  Both the directory, and the
archive are specifically for you to practice on.  The rest of this
chapter and the next chapter will show many examples using this
directory and the files you will create: some of those files may be
other directories and other archives.

   The three files you will archive in this example are called `blues',
`folk', and `jazz'.  The archive is called `collection.tar'.

   This section will proceed slowly, detailing how to use `--create' in
`verbose' mode, and showing examples using both short and long forms.
In the rest of the tutorial, and in the examples in the next chapter,
we will proceed at a slightly quicker pace.  This section moves more
slowly to allow beginning users to understand how `tar' works.

* Menu:

* prepare for examples::
* Creating the archive::
* create verbose::
* short create::
* create dir::
* create prefix::


File: tar.info,  Node: prepare for examples,  Next: Creating the archive,  Prev: create,  Up: create

Preparing a Practice Directory for Examples
-------------------------------------------

   To follow along with this and future examples, create a new directory
called `practice' containing files called `blues', `folk' and `jazz'.
The files can contain any information you like: ideally, they should
contain information which relates to their names, and be of different
lengths.  Our examples assume that `practice' is a subdirectory of your
home directory.

   Now `cd' to the directory named `practice'; `practice' is now your
"working directory".  (*Please note*: Although the full path name of
this directory is `/HOMEDIR/practice', in our examples we will refer to
this directory as `practice'; the HOMEDIR is presumed.

   In general, you should check that the files to be archived exist
where you think they do (in the working directory) by running `ls'.
Because you just created the directory and the files and have changed to
that directory, you probably don't need to do that this time.

   It is very important to make sure there isn't already a file in the
working directory with the archive name you intend to use (in this case,
`collection.tar'), or that you don't care about its contents.  Whenever
you use `create', `tar' will erase the current contents of the file
named by `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') if it exists.  `tar'
will not tell you if you are about to overwrite a file unless you
specify an option which does this .  To add files to an existing
archive, you need to use a different option, such as `--append' (`-r');
see *Note append:: for information on how to do this.


File: tar.info,  Node: Creating the archive,  Next: create verbose,  Prev: prepare for examples,  Up: create

Creating the Archive
--------------------

   To place the files `blues', `folk', and `jazz' into an archive named
`collection.tar', use the following command:

     $ tar --create --file=collection.tar blues folk jazz

   The order of the arguments is not very important, *when using long
option forms*.  You could also say:

     $ tar blues --create folk --file=collection.tar jazz

However, you can see that this order is harder to understand; this is
why we will list the arguments in the order that makes the commands
easiest to understand (and we encourage you to do the same when you use
`tar', to avoid errors).

   Note that the part of the command which says,
`--file=collection.tar' is considered to be *one* argument.  If you
substituted any other string of characters for ``collection.tar'',
then that string would become the name of the archive file you create.

   The order of the options becomes more important when you begin to use
short forms.  With short forms, if you type commands in the wrong order
(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.
*Note short create:: for more information on this.

   In this example, you type the command as shown above: `--create' is
the subcommand which creates the new archive (`collection.tar'), and
`--file' is the option which lets you give it the name you chose.  The
files, `blues', `folk', and `jazz', are now members of the archive,
`collection.tar' (they are "file name arguments" to the `--create'
subcommand) .  Now that they are are in the archive, they are called
*archive members*, not files .

   When you create an archive, you *must* specify which files you want
placed in the archive.  If you do not specify any archive members, GNU
`tar' will complain.

   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	collection.tar	folk	jazz

Creating the archive `collection.tar' did not destroy the copies of the
files in the directory.

   Keep in mind that if you don't indicate any subcommand, `tar' will
not run and will prompt you for one.  If you don't name any files, `tar'
will complain.  You must have write access to the working directory, or
else you will not be able to create an archive in that directory.

   *Caution*: Do not attempt to use `--create' (`-c') to add files to
an existing archive; it will delete the archive and write a new one.
Use `--append' (`-r') instead.  *Note append::.


File: tar.info,  Node: create verbose,  Next: short create,  Prev: Creating the archive,  Up: create

Running `--create' with `--verbose'
-----------------------------------

   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 `create' example above would appear as:

     $ tar --create --verbose --file=collection.tar blues folk jazz
     blues
     folk
     jazz

   This example is just like the example we showed which did not use
`--verbose', except that `tar' generated the remaining lines.

   In the rest of the examples in this chapter, we will frequently use
`verbose' mode so we can show actions or `tar' responses that you would
otherwise not see, and which are important for you to understand what
`tar' does.


File: tar.info,  Node: short create,  Next: create dir,  Prev: create verbose,  Up: create

Short Forms with `create'
-------------------------

   As we said before, the `--create' (`-c') subcommand is one of the
most basic uses of `tar', and you will use it countless times.
Eventually, you will probably want to use abbreviated (or "short")
forms of options.  A full discussion of the three different forms that
options can take appears in *Note Styles::; for now, here is what the
previous example (including the `--verbose' (`-v') option) looks like
using short option forms:

     $ tar -cvf collection.tar blues folk jazz
     blues
     folk
     jazz

As you can see, the system responds the same no matter whether you use
long or short option forms.

   One difference between using short and long option forms is that,
although the exact placement of arguments following options is no more
specific when using short forms, it is easier to become confused and
make a mistake when using short forms.  For example, suppose you
attempted the above example in the following way:

     $ tar -cfv collection.tar blues folk jazz
     tar: Cannot add file collection.tar: No such file or directory
     tar: Error exit delayed from previous errors
     $ ls
     blues   folk   jazz   v
     $

You got error messages and a file called `v'.  What happened is that
`tar' tried to make an archive file called `v', containing the files
`blues', `folk', and `jazz', because the `v' is the closest "file name"
to the `-f' option, and is thus taken to be the chosen archive file
name.  `tar' tried to add a file called `collection.tar' to the `v'
archive file; if the file `collection.tar' did not already exist, `tar'
will report an error indicating that this file does not exist.  If the
file `collection.tar' does already exist (e.g., from a previous command
you may have run), then `tar' will add this file to the archive.
Because the `-v' option did not get registered, `tar' will not run
under `verbose' mode, and will not report its progress.

   The end result is that you may be quite confused about what happened,
and possibly overwrite a file.  To illustrate this further, we will show
you how an example we showed previously would look using short forms.

   This example,

     $ tar blues --create folk --file=collection.tar jazz

is confusing as it is.  When shown using short forms, however, it
becomes much more so:

     $ tar blues -c folk -f collection.tar jazz

It would be very easy to put the wrong string of characters immediately
following the `-f', but doing that could sacrifice valuable data.

   For this reason, we recommend that you pay very careful attention to
the order of options and placement of file and archive names,
especially when using short option forms.  Not having the option name
written out mnemonically can affect how well you remember which option
does what, and therefore where different names have to be placed.
(Placing options in an unusual order can also cause `tar' to report an
error if you have set the shell environment variable,
`POSIXLY_CORRECT'; *note posix compliance::. for more information on
this.)


File: tar.info,  Node: create dir,  Next: create prefix,  Prev: short create,  Up: create

Archiving Directories
---------------------

   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 followed the previous instructions in this tutorial, you should
type:

     $ cd ..
     $

This will put you into the directory which contains `practice', i.e.
your home directory.  Once in the superior directory, you can specify
the subdirectory, `practice', as a file name argument.  To store
`practice' in the new archive file `music.tar', type:

     $ tar --create --verbose --file=music.tar practice

`tar' should output:

     practice/
     practice/blues
     practice/folk
     practice/jazz
     practice/collection.tar

   Note that the archive thus created is not in the subdirectory
`practice', but rather in the current 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'.  For example, you will probably not be able to
store your home directory in an archive by invoking `tar' from the root
directory; *Note absolute::.  (Note also that `collection.tar', 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.tar' is extracted, the archive file `collection.tar' will be
re-written into the file system).

   If you give `tar' a command such as

     $ tar --create --file=foo.tar .

`tar' will report `tar: foo.tar is the archive; not dumped'.  This
happens because `tar' creates the archive `foo.tar' in the current
directory 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 normally, except for the exclusion
of that one file.  (*Please note:* Some other versions of `tar' are not
so clever; they might enter an infinite loop when this happens.  It is
safer, in general, to not depend on GNU `tar' behaviour, by making sure
that the archive is not created inside a directory being itself
dumped.)  Some MS-Windows file systems (notably, Windows 95 VFAT disks)
don't support the feature which is used by GNU `tar' to detect that the
archive is included in itself, so the archive *will* be included on
those file systems.


File: tar.info,  Node: create prefix,  Prev: create dir,  Up: create

Using Name Prefixes
-------------------

   Sometimes the directory structure you want an archive to create when
you unpack it is different from the directory structure you built it in.

   This is often true when you are using a `tar' production in a
Makefile, to build distribution archives in a source-code directory.
The most convenient way to do this would be with a command like the
following:

     $ tar --create --file=distribution.tar *

But this makes an archive that will unpack as a lot of individual files,
which is usually not what you want.  Assuming your build directory is
named `project', you might do something like

     $ tar --directory=.. --create --file=distribution.tar project

   But this means you will be stuck with the name of your build
directory as the top-level name of the distribution archive.  Often you
would like your distribution archive to unpack into a single directory,
but with a synthetic top-level directory name (perhaps including a
version number).

   You can get this effect with the `--name-prefix=PREFIX' option.  Its
argument is a name prefix which gets prepended to each file name entry
in an archive as it is added to the archive.

   For example, if you say

     $ tar --name-prefix='project-5.23/' --create --file=collection.tar *

   you will make an archive of all the files and directories in the
current directory, but it will extract into the single subdirectory
`project-5.23'.

   Note that you will almost always want the argument of
`--name-prefix=PREFIX' to end with a directory delimiter (forward slash
under Unix-like operating systems, forward or back-slash under DOS).
Otherwise you will make an archive in which each file has a prefix
welded directly to the first segment of its name.  While this capability
is there for full generality, it is probably not what you want.


File: tar.info,  Node: list,  Next: extract,  Prev: create,  Up: Tutorial

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

   Frequently, you will find yourself wanting to determine exactly what
a particular archive contains.  You can use the `--list' (`-t')
subcommand to get the member names as they currently appear in the
archive, as well as various attributes of the files at the time they
were archived.  For example, you can examine the archive
`collection.tar' that you created in the last section with the command,

     $ tar --list --file=collection.tar

The output of `tar' would then be:

     blues
     folk
     jazz

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

     ./birds
     baboon
     ./box

Be sure to use a `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option just
as with `--create' (`-c') to specify the name of the archive.

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

   If you had used `--verbose' (`-v') mode, the example above would look
like:

     $ tar --list --verbose --file=collection.tar
     -rw-rw-rw- myself user 42 1990-05-21 13:29 blues
     -rw-rw-rw- myself user 62 1990-05-23 10:55 folk
     -rw-rw-rw- myself user 40 1990-05-21 13:30 jazz

   You can specify one or more individual member names as arguments when
using `list'.  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'.

   Because `tar' preserves paths, file names must be specified as they
appear in the archive (ie., relative to the directory from which the
archive was created).  Therefore, it is essential when specifying member
names to `tar' that you give the exact member names.  For example,
`tar --list --file=bfiles birds' would produce an error message
something like `tar: birds: Not found in archive', because there is no
member named `birds', only one named `./birds'.  While the names
`birds' and `./birds' name the same file, *member* names are compared
using a simplistic name comparison, in which an exact match is
necessary.  *Note absolute::.

   However, `tar --list --file=collection.tar folk' would respond with
`folk', because `folk' is in the archive file `collection.tar'.  If you
are not sure of the exact file name, try listing all the files in the
archive and searching for the one you expect to find; remember that if
you use `--list' with no file names as arguments, `tar' will print the
names of all the members stored in the specified archive.

   As an exception to member name preservation when creating the
archive, `tar' on MS-DOS/MS-Windows mirrors the DOS-style backslashes
into Unix-style forward slashes.  This is because the bulk of `tar' code
is deeply entrenched in the Unix world and assumes that forward slashes
are used in too many places.  Converting slashes automatically lets the
users specify files as they are used to on those systems.  But it also
means that you need to remember about this conversion, so you won't be
surprised when `tar' lists the files differently than what you typed on
the command line.  For example:

     $ tar -cvf c:\files\backup\today.tar d:\data\may97 d:\data\june97
     data/may97
     data/june97
     $ tar -xvf c:\files\backup\today.tar data\may97
     data/may97

* Menu:

* list dir::


File: tar.info,  Node: list dir,  Prev: list,  Up: list

Listing the Contents of a Stored Directory
------------------------------------------

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

   To get information about the contents of an archived directory, use
the directory name as a file name argument in conjunction with `--list'
(`-t').  To find out file attributes, include the `--verbose' (`-v')
option.

   For example, to find out about files in the directory `practice', in
the archive file `music.tar', type:

     $ tar --list --verbose --file=music.tar practice

   `tar' responds:

     drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
     -rw-rw-rw- myself user 42 1990-05-21 13:29 practice/blues
     -rw-rw-rw- myself user 62 1990-05-23 10:55 practice/folk
     -rw-rw-rw- myself user 40 1990-05-21 13:30 practice/jazz
     -rw-rw-rw- myself user 10240 1990-05-31 21:49 practice/collection.tar

   When you use a directory name as a file name argument, `tar' acts on
all the files (including sub-directories) in that directory.


File: tar.info,  Node: extract,  Next: going further,  Prev: list,  Up: Tutorial

How to Extract Members from an Archive
======================================

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

   Creating an archive is only half the job--there is no point in
storing files in an archive if you can't retrieve them.  The act of
retrieving members from an archive so they can be used and manipulated
as unarchived files again is called "extraction".  To extract files
from an archive, use the `--extract' (`--get', `-x') subcommand.  As
with `--create' (`-c'), specify the name of the archive with
`--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME').  Extracting an archive does
not modify the archive in any way; you can extract it multiple times if
you want or need to.

   Using `--extract', you can extract an entire archive, or specific
files.  The files can be directories containing other files, or not.  As
with `--create' (`-c') and `--list' (`-t'), you may use the short or the
long form of the subcommand without affecting the performance.

* Menu:

* extracting archives::
* extracting files::
* extract dir::
* failing commands::

