| [Top] | [Contents] | [Index] | [ ? ] |
This manual is for GNU tar (version
1.20, 14 April 2008), which creates and extracts files
from archives.
Copyright © 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License".
(a) The FSF's Back-Cover Text is: “You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom.”
The first part of this master menu lists the major nodes in this Info document. The rest of the menu lists all the lower level nodes.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GNU tar creates
and manipulates 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.
The name “tar” originally came from the phrase “Tape ARchive”, but
archives need not (and these days, typically do not) reside on tapes.
| 1.1 What this Book Contains | ||
| 1.2 Some Definitions | ||
1.3 What tar Does | ||
1.4 How tar Archives are Named | ||
1.5 GNU tar Authors | ||
| 1.6 Reporting bugs or suggestions |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 (see section Tutorial Introduction to tar) 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
operations (‘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; see section Tutorial Introduction to tar.)
The third chapter presents the remaining five operations, 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 (see section Date input formats) exists in its
entirety in other GNU manuals, and is mostly self-contained.
In addition, one section of this manual (see section Basic Tar Format) contains a
big quote which is taken directly from tar sources.
In general, we give both 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.)
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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. (In addition, archives record access
permissions, user and group, size in bytes, and data modification time.
Some archives also record the file names in each archived directory, as
well as other file and directory information.) 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 file system,
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 file system. 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 operations can be performed using tar.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
tape archiver. 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.
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!)
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
file system.
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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, François
Pinard, Paul Eggert, and finally Sergey Poznyakoff 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 was withdrawn in version 1.11. Thomas Bushnell, n/BSG and Amy
Gorin worked on a tutorial and manual for GNU tar.
François Pinard put version 1.11.8 of the manual together by
taking information from all these sources and merging them. Melissa
Weisshaus finally edited and redesigned the book to create version
1.12. The book for versions from 1.14 up to 1.20 were edited
by the current maintainer, Sergey Poznyakoff.
For version 1.12, Daniel Hagerty contributed a great deal of technical consulting. In particular, he is the primary author of Performing Backups and Restoring Files.
In July, 2003 GNU tar was put on CVS at savannah.gnu.org
(see http://savannah.gnu.org/projects/tar), and
active development and maintenance work has started
again. Currently GNU tar is being maintained by Paul Eggert, Sergey
Poznyakoff and Jeff Bailey.
Support for POSIX archives was added by Sergey Poznyakoff.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
If you find problems or have suggestions about this program or manual, please report them to ‘bug-tar@gnu.org’.
When reporting a bug, please be sure to include as much detail as possible, in order to reproduce it. .
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
tar This chapter guides you through some basic examples of three tar
operations: ‘--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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 operations. 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:
tar commands in. When we show file names,
we will assume that those names are relative to your home directory.
For example, my home directory is ‘/home/fsf/melissa’. All of
my examples are in a subdirectory of the directory named by that file
name; the subdirectory is called ‘practice’.
tar archives with tape drives.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In the examples, ‘$’ represents a typical shell prompt. It
precedes lines you should type; to make this more clear, those lines are
shown in this font, as opposed to lines which represent the
computer's response; those lines are shown in this font, or
sometimes ‘like this’.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
tar Operations and Options tar can take a wide variety of arguments which specify and define
the actions it will have on the particular set of files or the archive.
The main types of arguments to tar fall into one of two classes:
operations, and options.
Some arguments fall into a class called operations; 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
operating modes. You are in a particular operating mode when you
have specified the operation which specifies it; there are eight
operations 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 operations and options in any
of three forms: long (mnemonic) form, short form, and old style. Some
of the operations and options have no short or “old” forms; however,
the operations and options which we will cover in this tutorial have
corresponding abbreviations. 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. In this book we present a full discussion of this way
of writing options and operations (see section Old Option Style), and we discuss
the other two styles of writing options (See section Long Option Style, and
see section Short Option Style).
In the examples and in the text of this tutorial, we usually use the
long forms of operations 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 Advanced GNU tar Operations. 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 “operations”
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 operations”. However, experienced tar
users often refer to these by shorthand terms such as, “short and long
options”. This term assumes that the “operations” 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”.
A tar command is the entire command line of user input
which tells tar what to do — including the operation, options,
and any arguments (file names, pipes, other commands, etc.). 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 tar operation, not the whole line.
Again, use context to figure out which of the meanings the speaker
intends.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here are the three most frequently used operations (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 operations in detail. We will present the rest of the operations in the next chapter.
Create a new tar archive.
List the contents of an archive.
Extract one or more members from an archive.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.)
| The ‘--file’ Option | ||
| The ‘--verbose’ Option | ||
| Getting Help: Using the ‘--help’ Option |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 examine
the environment variable TAPE. If it is set, its value will be
used as the archive name. Otherwise, tar will use the
default archive, determined at the compile time. Usually it is
standard output or some physical tape drive attached to your machine
(you can verify what the default is by running tar
--show-defaults, see section Obtaining GNU tar default values). 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 specify 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
Choosing and Naming Archive Files.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
Each instance of ‘--verbose’ on the command line increases the verbosity level by one, so if you need more details on the output, specify it twice.
When reading archives (‘--list’, ‘--extract’,
‘--diff’), tar by default prints only the names of
the members being extracted. Using ‘--verbose’ will show a full,
ls style member listing.
In contrast, when writing archives (‘--create’, ‘--append’,
‘--update’), tar does not print file names by
default. So, a single ‘--verbose’ option shows the file names
being added to the archive, while two ‘--verbose’ options
enable the full listing.
For example, to create an archive in verbose mode:
$ tar -cvf afiles.tar apple angst aspic apple angst aspic |
Creating the same archive with the verbosity level 2 could give:
$ tar -cvvf afiles.tar apple angst aspic -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple -rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst -rw-r--r-- gray/staff 23152 2006-06-09 12:06 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’.
The full output consists of six fields:
ls -l output (see format=verbose: (fileutils)What information is listed section `Verbose listing' in GNU file utilities).
Depending on the file type, the name can be followed by some additional information, described in the following table:
The file or archive member is a symbolic link and link-name is the name of file it links to.
The file or archive member is a hard link and link-name is the name of file it links to.
The archive member is an old GNU format long link. You will normally not encounter this.
The archive member is an old GNU format long name. You will normally not encounter this.
The archive member is a GNU volume header (see section Tape Files).
Encountered only at the beginning of a multi-volume archive (see section Using Multiple Tapes). This archive member is a continuation from the previous volume. The number n gives the offset where the original file was split.
An archive member of unknown type. c is the type character from
the archive header. If you encounter such a message, it means that
either your archive contains proprietary member types GNU tar is not
able to handle, or the archive is corrupted.
For example, here is an archive listing containing most of the special suffixes explained above:
V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header-- -rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at byte 32456-- -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple -rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The ‘--help’ option to tar prints out a very brief list of
all operations and option available for the current version of
tar available on your system.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
(This message will disappear, once this node revised.)
One of the basic operations 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
operations, 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.
| 2.6.1 Preparing a Practice Directory for Examples | ||
| 2.6.2 Creating the Archive | ||
| 2.6.3 Running ‘--create’ with ‘--verbose’ | ||
| 2.6.4 Short Forms with ‘create’ | ||
| 2.6.5 Archiving Directories |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 file 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 an archive unless you
specify an option which does this (see section Backup options, for the
information on how to do so). To add files to an existing archive,
you need to use a different option, such as ‘--append’ (‘-r’); see
How to Add Files to Existing Archives: ‘--append’ for information on how to do this.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 sequence ‘--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. See section Short Forms with ‘create’, for more information on this.
In this example, you type the command as shown above: ‘--create’
is the operation 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’ operation.
See section Choosing Files and Names for tar, for the detailed discussion on these.) Now that they are
in the archive, they are called archive members, not files.
(see section members).
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:
blues folk jazz collection.tar |
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 an operation, 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. See section How to Add Files to Existing Archives: ‘--append’.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
As we said before, the ‘--create’ (‘-c’) operation 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 The Three Option 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 |
In this case, tar will 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 will try
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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; See section Absolute File Names. (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 ‘foo.tar’, 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: Other implementations of tar may not be so clever;
they will enter an infinite loop when this happens, so you should not
depend on this behavior unless you are certain you are running
GNU tar. In general, it is wise to always place the archive outside
of the directory being dumped.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Frequently, you will find yourself wanting to determine exactly what a particular archive contains. You can use the ‘--list’ (‘-t’) operation 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. This output is described in detail in verbose member listing.
If you had used ‘--verbose’ (‘-v’) mode, the example above would look like:
$ tar --list --verbose --file=collection.tar folk -rw-r--r-- myself user 62 1990-05-23 10:55 folk |
It is important to notice that the output of tar --list
--verbose does not necessarily match that produced by tar
--create --verbose while creating the archive. It is because
GNU tar, unless told explicitly not to do so, removes some directory
prefixes from file names before storing them in the archive
(See section Absolute File Names, for more information). In other
words, in verbose mode GNU tar shows file names when creating
an archive and member names when listing it. Consider this
example:
$ tar cfv archive /etc/mail tar: Removing leading `/' from member names /etc/mail/ /etc/mail/sendmail.cf /etc/mail/aliases $ tar tf archive etc/mail/ etc/mail/sendmail.cf etc/mail/aliases |
This default behavior can sometimes be inconvenient. You can force
GNU tar show member names when creating archive by supplying
‘--show-stored-names’ option.
Print member (as opposed to file) names when creating the archive.
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 file names, these must be specified as
they appear in the archive (i.e., 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.tar 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 by default are compared verbatim.
However, tar --list --file=bfiles.tar baboon would respond with ‘baboon’, because this exact member name is in the archive file ‘bfiles.tar’. If you are not sure of the exact file name, use globbing patterns, for example:
$ tar --list --file=bfiles.tar --wildcards '*b*' |
will list all members whose name contains ‘b’. See section Wildcards Patterns and Matching,
for a detailed discussion of globbing patterns and related
tar command line options.
| Listing the Contents of a Stored Directory |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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-r--r-- myself user 42 1990-05-21 13:29 practice/blues -rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk -rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz -rw-r--r-- 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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
(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’ or ‘-x’) operation. As with ‘--create’, specify the name of the archive with ‘--file’ (‘-f’) option. 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 operation without affecting the performance.
| 2.8.1 Extracting an Entire Archive | ||
| 2.8.2 Extracting Specific Files | ||
| 2.8.3 Extracting Files that are Directories | ||
| 2.8.4 Extracting Archives from Untrusted Sources | ||
| 2.8.5 Commands That Will Fail |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To extract an entire archive, specify the archive file name only, with no individual file names as arguments. For example,
$ tar -xvf collection.tar |
produces this:
-rw-r--r-- me user 28 1996-10-18 16:31 jazz -rw-r--r-- me user 21 1996-09-23 16:44 blues -rw-r--r-- me user 20 1996-09-23 16:44 folk |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |