tar
tar
tar Operations
tar Operations
tar Operations
--extract
tar Usages
tar
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.
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.
@FIXME{this sounds more like a GNU Project Manuals Concept [tm] more than the reality. should think about whether this makes sense to say here, or not.} 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 The Standard Format) 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.)
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 last 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 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 operations can be peformed using tar.
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).
@FIXME{the following table entries need a bit of work..}
You can use tar archives in many ways. We want to stress a few
of them: storage, backup, and transportation.
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!)
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.
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.
@FIXME{must ask franc,ois about this. dan hagerty thinks this might be an issue, but we're not really sure at this time. dan just tried a test case of mixing up options' orders while the variable was set, and there was no problem...}
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 message. 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.
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 Fran@,{c}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.
@FIXME{i want all of these names mentioned, Absolutely. BUT, i'm not sure i want to spell out the history in this detail, at least not for the printed book. i'm just not sure it needs to be said this way. i'll think about it.}
@FIXME{History is more important, and surely more interesting, than actual names. Quoting names without history would be meaningless. FP}
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 (or even
before?) @FIXME{huh? IMO, either we know or we don't; the
parenthetical is confusing.} through 1.10, then withdrawn in version
1.11. Thomas Bushnell, n/BSG and Amy Gorin worked on a tutorial and
manual for GNU tar. Fran@,{c}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. @FIXME{update version number as
necessary; i'm being optimistic!} @FIXME{Someone [maybe karl berry?
maybe bob chassell? maybe melissa? maybe julie sussman?] needs to
properly index the thing.}
For version 1.12, Daniel Hagerty contributed a great deal of technical consulting. In particular, he is the primary author of section Performing Backups and Restoring Files.
If you find problems or have suggestions about this program or manual, please report them to `bug-gnu-utils@prep.ai.mit.edu'.
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.
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 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'.
tar archives with tape drives.
@FIXME{this is a cop out. need to add some simple tape drive info.}
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'. When we have lines which are too long to be
displayed in any other way, we will show them like this:
This is an example of a line which would otherwise not fit in this space.
@FIXME{how often do we use smallexample?}
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. @FIXME{make sure this is still the case,
at the end} We will indicate those abbreviations appropriately to get
you used to seeing them. (Note that the "old style" option forms
exist in GNU tar for compatibility with Unix tar. We
present a full discussion of this way of writing options and operations
appears in section Old Option Style, and we discuss the other two styles of
writing options in section Mnemonic Option Style and 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 section 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.
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.
tar archive.
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.)
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 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
section Choosing and Naming Archive Files.
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 operation 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'.
--help Optiontar prints out a very brief list of
all operations and option available for the current version of
tar available on your system.
@UNREVISED
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.
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 @FIXME{xref to the node for
--backup!}. To add files to an existing archive, you need to use a
different option, such as --append (-r); see section How to Add Files to Existing Archives: --append for
information on how to do this.
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. 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) @FIXME{xref here to the discussion of file name args?}. Now that they are are in the archive, they are called archive members, not files @FIXME{xref to definitions?}.
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.
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
(note the different font styles).
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.
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 section 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.
@FIXME{i don't like how this is worded:} 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.
(Placing options in an unusual order can also cause tar to
report an error if you have set the shell environment variable,
POSIXLY_CORRECT; see section POSIX Compliance for more information
on this.)
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, 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 versions of tar are not so clever;
they will enter an infinite loop when this happens, so you should not
depend on this behavior unless you are certain you are running GNU
tar. @FIXME{bob doesn't like this sentence, since he does it
all the time, and we've been doing it in the editing passes for this
manual: In general, make sure that the archive is not inside a
directory being dumped.})
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
@FIXME{we hope this will change. if it doesn't, need to show the creation of bfiles somewhere above!!! : }
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 folk -rw-rw-rw- myself user 62 1990-05-23 10:55 folk
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'.
@FIXME{we hope the relevant aspects of this will change:}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. See section Absolute File Names.
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.
@UNREVISED
@FIXME{i changed the order of these nodes around and haven't had a chance to play around with this node's example, yet. i have to play with it and see what it actually does for my own satisfaction, even if what it says *is* correct..}
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.
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) operation. 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 operation without affecting the performance.
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-rw-rw- me user 28 1996-10-18 16:31 jazz -rw-rw-rw- me user 21 1996-09-23 16:44 blues -rw-rw-rw- me user 20 1996-09-23 16:44 folk
To extract specific archive members, give their exact member names as arguments, as printed by --list (-t). If you had mistakenly deleted one of the files you had placed in the archive `collection.tar' earlier (say, `blues'), you can extract it from the archive without changing the archive's structure. It will be identical to the original file `blues' that you deleted. @FIXME{check this; will the times, permissions, owner, etc be the same, also?}
First, make sure you are in the `practice' directory, and list the files in the directory. Now, delete the file, `blues', and list the files in the directory again.
You can now extract the member `blues' from the archive file `collection.tar' like this:
$ tar --extract --file=collection.tar blues
If you list the files in the directory again, you will see that the file
`blues' has been restored, with its original permissions, creation
times, and owner. @FIXME{This is only accidentally true, but not in
general. In most cases, one has to be root for restoring the owner, and
use a special option for restoring permissions. Here, it just happens
that the restoring user is also the owner of the archived members, and
that the current umask is compatible with original permissions.}
(These parameters will be identical to those which
the file had when you originally placed it in the archive; any changes
you may have made before deleting the file from the file system,
however, will not have been made to the archive member.) The
archive file, `collection.tar', is the same as it was before you
extracted `blues'. You can confirm this by running tar with
--list (-t).
@FIXME{we hope this will change:}Remember that as with other operations, specifying the exact member name is important. tar --extract --file=bfiles.tar birds will fail, because there is no member named `birds'. To extract the member named `./birds', you must specify tar --extract --file=bfiles.tar ./birds. To find the exact member names of the members of an archive, use --list (-t) (see section How to List Archives).
If you give the --verbose (-v) option, then --extract (--get, -x) will print the names of the archive members as it extracts them.
Extracting directories which are members of an archive is similar to extracting other files. The main difference to be aware of is that if the extracted directory has the same name as any directory already in the working directory, then files in the extracted directory will be placed into the directory of the same name. Likewise, if there are files in the pre-existing directory with the same names as the members which you extract, the files from the extracted archive will overwrite the files already in the working directory (and possible subdirectories). This will happen regardless of whether or not the files in the working directory were more recent than those extracted.
However, if a file was stored with a directory name as part of its file
name, and that directory does not exist under the working directory when
the file is extracted, tar will create the directory.
We can demonstrate how to use `--extract' to extract a directory file with an example. Change to the `practice' directory if you weren't there, and remove the files `folk' and `jazz'. Then, go back to the parent directory and extract the archive `music.tar'. You may either extract the entire archive, or you may extract only the files you just deleted. To extract the entire archive, don't give any file names as arguments after the archive name `music.tar'. To extract only the files you deleted, use the following command:
$ tar -xvf music.tar practice/folk practice/jazz
@FIXME{need to show tar's response; used verbose above. also, here's a good place to demonstrate the -v -v thing. have to write that up (should be trivial, but i'm too tired!).}
Because you created the directory with `practice' as part of the file names of each of the files by archiving the `practice' directory as `practice', you must give `practice' as part of the file names when you extract those files from the archive.
@FIXME{IMPORTANT! show the final structure, here. figure out what it will be.}
Here are some sample commands you might try which will not work, and why they won't work.
If you try to use this command,
$ tar -xvf music.tar folk jazz
you will get the following response:
tar: folk: Not found in archive tar: jazz: Not found in archive $
This is because these files were not originally in the parent directory `..', where the archive is located; they were in the `practice' directory, and their file names reflect this:
$ tar -tvf music.tar practice/folk practice/jazz practice/rock
@FIXME{make sure the above works when going through the examples in order...}
Likewise, if you try to use this command,
$ tar -tvf music.tar folk jazz
you would get a similar response. Members with those names are not in the archive. You must use the correct member names in order to extract the files from the archive.
If you have forgotten the correct names of the files in the archive, use tar --list --verbose to list them correctly.
@FIXME{more examples, here? hag thinks it's a good idea.}
@FIXME{need to write up a node here about the things that are going to be in the rest of the manual.}
tar@UNREVISED
This chapter is about how one invokes the GNU tar command, from
the command synopsis (see section General Synopsis of tar). There are numerous options,
and many styles for writing them. One mandatory option specifies
the operation tar should perform (see section Operations),
other options are meant to detail how this operation should be performed
(see section tar Options). Non-option arguments are not always interpreted
the same way, depending on what the operation is.
You will find in this chapter everything about option styles and rules for
writing them (see section The Three Option Styles). On the other hand, operations and options
are fully described elsewhere, in other chapters. Here, you will find
only synthetic descriptions for operations and options, together with
pointers to other parts of the tar manual.
Some options are so special they are fully described right in this
chapter. They have the effect of inhibiting the normal operation of
tar or else, they globally alter the amount of feedback the user
receives about what is going on. These are the --help and
--version (see section GNU tar documentation), --verbose (-v) (see section Checking tar progress)
and --interactive (-w) options (see section Asking for Confirmation During Operations).
tar
The GNU tar program is invoked as either one of:
tar option... [name]... tar letter... [argument]... [option]... [name]...
The second form is for when old options are being used.
You can use tar to store files in an archive, to extract them from
an archive, and to do other types of archive manipulation. The primary
argument to tar, which is called the operation, specifies
which action to take. The other arguments to tar are either
options, which change the way tar performs an operation,
or file names or archive members, which specify the files or members
tar is to act on.
You can actually type in arguments in any order, even if in this manual
the options always precede the other arguments, to make examples easier
to understand. Further, the option stating the main operation mode
(the tar main command) is usually given first.
Each name in the synopsis above is interpreted as an archive member
name when the main command is one of --compare (--diff, -d), --delete,
--extract (--get, -x), --list (-t) or --update (-u). When naming
archive members, you must give the exact name of the member in the
archive, as it is printed by --list (-t). For --append (-r)
and --create (-c), these name arguments specify the names
of either files or directory hierarchies to place in the archive.
These files or hierarchies should already exist in the file system,
prior to the execution of the tar command.
tar interprets relative file names as being relative to the
working directory. tar will make all file names relative
(by removing leading slashes when archiving or restoring files),
unless you specify otherwise (using the --absolute-names (-P)
option). See section Absolute File Names, for more information about
--absolute-names (-P).
If you give the name of a directory as either a file name or a member
name, then tar acts recursively on all the files and directories
beneath that directory. For example, the name `/' identifies all
the files in the filesystem to tar.
The distinction between file names and archive member names is especially
important when shell globbing is used, and sometimes a source of confusion
for newcomers. See section Wildcards Patterns and Matching, for more information about globbing.
The problem is that shells may only glob using existing files in the
file system. Only tar itself may glob on archive members, so when
needed, you must ensure that wildcard characters reach tar without
being interpreted by the shell first. Using a backslash before `*'
or `?', or putting the whole argument between quotes, is usually
sufficient for this.
Even if names are often specified on the command line, they can also be read from a text file in the file system, using the --files-from=file-of-names (-T file-of-names) option.
If you don't use any file name arguments, --append (-r),
--delete and --concatenate (--catenate, -A) will do nothing, while
--create (-c) will usually yield a diagnostic and inhibit tar
execution. The other operations of tar (--list (-t),
--extract (--get, -x), --compare (--diff, -d), and --update (-u)) will act
on the entire contents of the archive.
Besides successful exits, GNU tar may fail for many reasons.
Some reasons correspond to bad usage, that is, when the tar
command is improperly written.
Errors may be encountered later, while encountering an error
processing the archive or the files. Some errors are recoverable,
in which case the failure is delayed until tar has completed
all its work. Some errors are such that it would not meaningful,
or at least risky, to continue processing: tar then aborts
processing immediately. All abnormal exits, whether immediate or
delayed, should always be clearly diagnosed on stderr, after
a line stating the nature of the error.
GNU tar returns only a few exit statuses. I'm really
aiming simplicity in that area, for now. If you are not using the
--compare (--diff, -d) option, zero means that everything went well, besides
maybe innocuous warnings. Nonzero means that something went wrong.
Right now, as of today, "nonzero" is almost always 2, except for
remote operations, where it may be 128.
tar Options
GNU tar has a total of eight operating modes which allow you to
perform a variety of tasks. You are required to choose one operating
mode each time you employ the tar program by specifying one, and
only one operation as an argument to the tar command (two lists
of four operations each may be found at section The Three Most Frequently Used Operations and
section The Five Advanced tar Operations). Depending on circumstances, you may also wish to
customize how the chosen operating mode behaves. For example, you may
wish to change the way the output looks, or the format of the files that
you wish to archive may require you to do something special in order to
make the archive look right.
You can customize and control tar's performance by running
tar with one or more options (such as --verbose (-v), which
we used in the tutorial). As we said in the tutorial, options are
arguments to tar which are (as their name suggests) optional.
Depending on the operating mode, you may specify one or more options.
Different options will have different effects, but in general they all
change details of the operation, such as archive format, archive name,
or level of user interaction. Some options make sense with all
operating modes, while others are meaningful only with particular modes.
You will likely use some options frequently, while you will only use
others infrequently, or not at all. (A full list of options is
available in see section All tar Options.)
Note that tar options are case sensitive. For example, the
options `-T' and `-t' are different; the first requires an
argument for stating the name of a file providing a list of names,
while the second does not require an argument and is another way to
write --list (-t).
In addition to the eight operations, there are many options to
tar, and three different styles for writing both: long (mnemonic)
form, short form, and old style. These styles are discussed below.
Both the options and the operations can be written in any of these three
styles.
@FIXME{menu at end of this node. need to think of an actual outline for this chapter; probably do that after stuff from chap. 4 is incorporated.}
There are three styles for writing operations and options to the command
line invoking tar. The different styles were developed at
different times during the history of tar. These styles will be
presented below, from the most recent to the oldest.
Some options must take an argument. (For example, --file=archive-name (-f archive-name) takes
the name of an archive file as an argument. If you do not supply an
archive file name, tar will use a default, but this can be
confusing; thus, we recommend that you always supply a specific archive
file name.) Where you place the arguments generally depends on
which style of options you choose. We will detail specific information
relevant to each option style in the sections on the different option
styles, below. The differences are subtle, yet can often be very
important; incorrect option placement can cause you to overwrite a
number of important files. We urge you to note these differences, and
only use the option style(s) which makes the most sense to you until you
feel comfortable with the others.
@FIXME{hag to write a brief paragraph on the option(s) which can optionally take an argument}
@FIXME{have to decide whether or ot to replace other occurrences of "mnemonic" with "long", or *ugh* vice versa.}
Each option has at least one long (or mnemonic) name starting with two
dashes in a row, e.g. `list'. The long names are more clear than
their corresponding short or old names. It sometimes happens that a
single mnemonic option has many different different names which are
synonymous, such as `--compare' and `--diff'. In addition,
long option names can be given unique abbreviations. For example,
`--cre' can be used in place of `--create' because there is no
other mnemonic option which begins with `cre'. (One way to find
this out is by trying it and seeing what happens; if a particular
abbreviation could represent more than one option, tar will tell
you that that abbreviation is ambiguous and you'll know that that
abbreviation won't work. You may also choose to run `tar --help'
to see a list of options. Be aware that if you run tar with a
unique abbreviation for the long name of an option you didn't want to
use, you are stuck; tar will perform the command as ordered.)
Mnemonic options are meant to be obvious and easy to remember, and their meanings are generally easier to discern than those of their corresponding short options (see below). For example:
$ tar --create --verbose --blocking-factor=20 --file=/dev/rmt0
gives a fairly good set of hints about what the command does, even
for those not fully acquainted with tar.
Mnemonic options which require arguments take those arguments
immediately following the option name; they are introduced by an equal
sign. For example, the `--file' option (which tells the name
of the tar archive) is given a file such as `archive.tar'
as argument by using the notation `--file=archive.tar' for the
mnemonic option.
Most options also have a short option name. Short options start with a single dash, and are followed by a single character, e.g. `-t' (which is equivalent to `--list'). The forms are absolutely identical in function; they are interchangeable.
The short option names are faster to type than long option names.
Short options which require arguments take their arguments immediately following the option, usually separated by white space. It is also possible to stick the argument right after the short option name, using no intervening space. For example, you might write `-f archive.tar' or `-farchive.tar' instead of using `--file=archive.tar'. Both `--file=archive-name' and `-f archive-name' denote the option which indicates a specific archive, here named `archive.tar'.
Short options' letters may be clumped together, but you are not
required to do this (as compared to old options; see below). When short
options are clumped as a set, use one (single) dash for them all, e.g.
`tar -cvf'. Only the last option in such a set is allowed
to have an argument(1).
When the options are separated, the argument for each option which requires an argument directly follows that option, as is usual for Unix programs. For example:
$ tar -c -v -b 20 -f /dev/rmt0
If you reorder short options' locations, be sure to move any arguments that belong to them. If you do not move the arguments properly, you may end up overwriting files.
@UNREVISED
Like short options, old options are single letters. However, old options
must be written together as a single clumped set, without spaces separating
them or dashes preceding them(2). This set
of letters must be the first to appear on the command line, after the
tar program name and some whitespace; old options cannot appear
anywhere else. The letter of an old option is exactly the same letter as
the corresponding short option. For example, the old option `t' is
the same as the short option `-t', and consequently, the same as the
mnemonic option `--list'. So for example, the command `tar
cv' specifies the option `-v' in addition to the operation `-c'.
@FIXME{bob suggests having an uglier example. :-) }
When options that need arguments are given together with the command, all the associated arguments follow, in the same order as the options. Thus, the example given previously could also be written in the old style as follows:
$ tar cvbf 20 /dev/rmt0
Here, `20' is the argument of `-b' and `/dev/rmt0' is the argument of `-f'.
On the other hand, this old style syntax makes it difficult to match option letters with their corresponding arguments, and is often confusing. In the command `tar cvbf 20 /dev/rmt0', for example, `20' is the argument for `-b', `/dev/rmt0' is the argument for `-f', and `-v' does not have a corresponding argument. Even using short options like in `tar -c -v -b 20 -f /dev/rmt0' is clearer, putting all arguments next to the option they pertain to.
If you want to reorder the letters in the old option argument, be sure to reorder any corresponding argument appropriately.
This old way of writing tar options can surprise even experienced
users. For example, the two commands:
tar cfz archive.tar.gz file tar -cfz archive.tar.gz file
are quite different. The first example uses `archive.tar.gz' as the value for option `f' and recognizes the option `z'. The second example, however, uses `z' as the value for option `f'---probably not what was intended.
Old options are kept for compatibility with old versions of tar.
This second example could be corrected in many ways, among which the following are equivalent:
tar -czf archive.tar.gz file tar -cf archive.tar.gz -z file tar cf archive.tar.gz -z file
@FIXME{still could explain this better; it's redundant:}
As far as we know, all tar programs, GNU and non-GNU, support
old options. GNU tar supports them not only for historical
reasons, but also because many people are used to them. For
compatibility with Unix tar, the first argument is always
treated as containing command and option letters even if it doesn't
start with `-'. Thus, `tar c' is equivalent to `tar
-c:' both of them specify the --create (-c) command to create an
archive.
All three styles may be intermixed in a single tar command, so
long as the rules for each style are fully respected(3). Old style options and either of the
modern styles of options may be mixed within a single tar command.
However, old style options must be introduced as the first arguments only,
following the rule for old options (old options must appear directly
after the tar command and some whitespace). Modern options may
be given only after all arguments to the old options have been collected.
If this rule is not respected, a modern option might be falsely interpreted
as the value of the argument to one of the old style options.
For example, all the following commands are wholly equivalent, and illustrate the many combinations and orderings of option styles.
tar --create --file=archive.tar tar --create -f archive.tar tar --create -farchive.tar tar --file=archive.tar --create tar --file=archive.tar -c tar -c --file=archive.tar tar -c -f archive.tar tar -c -farchive.tar tar -cf archive.tar tar -cfarchive.tar tar -f archive.tar --create tar -f archive.tar -c tar -farchive.tar --create tar -farchive.tar -c tar c --file=archive.tar tar c -f archive.tar tar c -farchive.tar tar cf archive.tar tar f archive.tar --create tar f archive.tar -c tar fc archive.tar
On the other hand, the following commands are not equivalent to the previous set:
tar -f -c archive.tar tar -fc archive.tar tar -fcarchive.tar tar -farchive.tarc tar cfarchive.tar
These last examples mean something completely different from what the
user intended (judging based on the example in the previous set which
uses long options, whose intent is therefore very clear). The first
four specify that the tar archive would be a file named
`-c', `c', `carchive.tar' or `archive.tarc',
respectively. The first two examples also specify a single non-option,
name argument having the value `archive.tar'. The last
example contains only old style option letters (repeating option
`c' twice), not all of which are meaningful (eg., `.',
`h', or `i'), with no argument value. @FIXME{not sure i liked
the first sentence of this paragraph..}
tar Options
The coming manual sections contain an alphabetical listing of all
tar operations and options, with brief descriptions and cross
references to more in-depth explanations in the body of the manual.
They also contain an alphabetically arranged table of the short option
forms with their corresponding long option. You can use this table as
a reference for deciphering tar commands in scripts.
--append.
--concatenate.
tar archives to the end of the archive.
See section Combining Archives with --concatenate.
tar archive. See section How to Create Archives.
tar Optionstar strips an initial `/' from
member names. This option disables that behavior. @FIXME-xref{}.
tar to preserve the access time field in a file's inode when
dumping it. @FIXME-xref{}.
tar will back them up
using simple or numbered backups, depending upon backup-type.
@FIXME-xref{}.
tar prints error messages for read errors
with the block number in the archive file. @FIXME-xref{}.
tar uses to blocking x 512 bytes per
record. @FIXME-xref{}.
tar to print periodic checkpoint messages as it
reads through the archive. Its intended for when you want a visual
indication that tar is still running, but don't want to see
`--verbose' output. @FIXME-xref{}.
tar will use the compress program when reading or writing the
archive. This allows you to directly act on archives while saving
space. @FIXME-xref{}.
tar archive, tar will archive the file that a symbolic
link points to, rather than archiving the symlink. @FIXME-xref{}.
tar will change its current directory
to dir before performing any operations. When this option is used
during archive creation, it is order sensitive. @FIXME-xref{}.
tar will skip files that match
pattern. @FIXME-xref{}.
tar will use the list of patterns
in the file file. @FIXME-xref{}.
tar will use the file archive as the tar archive it
performs operations on, rather than tar's compilation dependent
default. @FIXME-xref{}.
tar will use the contents of file as a list of archive members
or files to operate on, in addition to those specified on the
command-line. @FIXME-xref{}.
tar to interpret the filename given to `--file' as a local
file, even if it looks like a remote tape drive name. @FIXME-xref{}.
tar archive will have a group id of group,
rather than the group from the source file. group is first decoded
as a group symbolic name, but if this interpretation fails, it has to be
a decimal numeric group ID. @FIXME-xref{}.
Also see the comments for the --owner=user option.
tar to read or write archives through gzip,
allowing tar to directly operate on several kinds of compressed
archives transparently. @FIXME-xref{}.
tar will print out a short message summarizing the operations and
options to tar and exit. @FIXME-xref{}.
tar to exit successfully if it encounters an
unreadable file. See section Options to Help Read Archives.
tar Writes Files.)
tar will ignore zeroed blocks in the archive, which
normally signals EOF. See section Options to Help Read Archives.
tar that it is working with an old GNU-format
incremental backup archive. It is intended primarily for backwards
compatibility only. @FIXME-xref{}.
tar is performing multi-tape backups, script-file is run
at the end of each tape. @FIXME-xref{}.
tar should ask the user for confirmation before
performing potentially destructive options, such as overwriting files.
@FIXME-xref{}.
tar will not overwrite existing
files if this option is present. See section Changing How tar Writes Files.
tar to write name as a name
record in the archive. When extracting or listing archives, tar will
only operate on archives that have a label matching the pattern
specified in name. @FIXME-xref{}.
tar creates is a new GNU-format incremental backup, using
snapshot-file to determine which files to backup.
With other operations, informs tar that the archive is in incremental
format. @FIXME-xref{}.
tar will use permissions
for the archive members, rather than the permissions from the files.
The program chmod and this tar option share the same syntax
for what permissions might be. See section `File permissions' in GNU file utilities. This reference also
has useful information for those not being overly familiar with the Unix
permission system.
Of course, permissions might be plainly specified as an octal number.
However, by using generic symbolic modifications to mode bits, this allows
more flexibility. For example, the value `a+rw' adds read and write
permissions for everybody, while retaining executable bits on directories
or on any other file already marked as executable.
tar that it should create or otherwise operate on a
multi-volume tar archive. @FIXME-xref{}.
tar will only add files that have changed
since date. @FIXME-xref{}.
tar will only add files whose
contents have changed (as opposed to just `--newer', which will
also back up files for which any status information has changed).
tar will not recurse into directories unless a
directory is explicitly named as an argument to tar. @FIXME-xref{}.
tar is using the `--files-from' option, this option
instructs tar to expect filenames terminated with NUL, so
tar can correctly work with file names that contain newlines.
@FIXME-xref{}.
tar that it should use numeric user and group
IDs when creating a tar file, rather than names. @FIXME-xref{}.
tar from recursing into
directories that are on different file systems from the current
directory. @FIXME-xref{}.
tar should use user as the owner of members
when creating archives, instead of the user associated with the source
file. user is first decoded as a user symbolic name, but if
this interpretation fails, it has to be a decimal numeric user ID.
@FIXME-xref{}.
There is no value indicating a missing number, and `0' usually means
root. Some people like to force `0' as the value to offer in
their distributions for the owner of files, because the root user is
anonymous anyway, so that might as well be the owner of anonymous archives.
tar to create an archive that is compatible with Unix V7
tar. @FIXME-xref{}.
tar to create a POSIX compliant tar archive. @FIXME-xref{}.
tar is extracting an archive, it normally subtracts the users'
umask from the permissions specified in the archive and uses that
number as the permissions to create the destination file. Specifying
this option instructs tar that it should use the permissions directly
from the archive. See section Changing How tar Writes Files.
tar should reblock its input, for reading from pipes on
systems with buggy implementations. See section Options to Help Read Archives.
tar to use size bytes per record when accessing the
archive. @FIXME-xref{}.
tar Writes Files.
tar to remove the source file from the file system after
appending it to an archive. @FIXME-xref{}.
tar that is should use cmd to communicate with remote
devices. @FIXME-xref{}.
tar when running on machines with
small amounts of memory. It informs tar that the list of file
arguments has already been sorted to match the order of files in the
archive. See section Options to Help Read Archives.
tar will attempt to preserve the owner
specified in the tar archive with this option present. @FIXME-xref{}.
tar Writes Files.)
tar to mention directories its skipping over when operating
on a tar archive. @FIXME-xref{}.
tar will skip extracting
files in the archive until it finds one that matches name.
See section Coping with Scarce Resources.
tar uses when backing up files from the default
`~'. @FIXME-xref{}.
tar is writing as being
num x 1024 bytes long. @FIXME-xref{}.
tar will extract files to stdout rather than to the
file system. See section Changing How tar Writes Files.
tar Writes Files.
tar to remove the corresponding file from the file system
before extracting it from the archive. See section Changing How tar Writes Files.
tar to access the archive through prog, which is
presumed to be a compression program of some sort. @FIXME-xref{}.
tar should be more verbose about the operations its
performing. This option can be specified multiple times for some
operations to increase the amount of information displayed. @FIXME-xref{}.
tar will print an informational message about what version it is and a
copyright message, some credits, and then exit. @FIXME-xref{}.
tar will keep track
of which volume of a multi-volume archive its working in file.
@FIXME-xref{}.
Here is an alphabetized list of all of the short option forms, matching them with the equivalent long option.
tar documentation
Being careful, the first thing is really checking that you are using GNU
tar, indeed. The --version option will generate a message
giving confirmation that you are using GNU tar, with the precise
version of GNU tar you are using. tar identifies itself
and prints the version number to the standard output, then immediately
exits successfully, without doing anything else, ignoring all other
options. For example, `tar --version' might return:
tar (GNU tar) 1.12
The first occurrence of `tar' in the result above is the program
name in the package (for example, rmt is another program), while
the second occurrence of `tar' is the name of the package itself,
containing possibly many programs. The package is currently named
`tar', after the name of the main program it contains(4).
Another thing you might want to do is checking the spelling or meaning
of some particular tar option, without resorting to this manual,
for once you have carefully read it. GNU tar has a short help
feature, triggerable through the --help option. By using this
option, tar will print a usage message listing all available
options on standard output, then exit successfully, without doing
anything else and ignoring all other options. Even if this is only a
brief summary, it may be several screens long. So, if you are not
using some kind of scrollable window, you might prefer to use something
like:
$ tar --help | less
presuming, here, that you like using less for a pager. Other
popular pagers are more and pg. If you know about some
keyword which interests you and do not want to read all the
--help output, another common idiom is doing:
tar --help | grep keyword
for getting only the pertinent lines.
The perceptive reader would have noticed some contradiction in the previous paragraphs. It is written that both --version and --help print something, and have all other options ignored. In fact, they cannot ignore each other, and one of them has to win. We do not specify which is stronger, here; experiment if you really wonder!
The short help output is quite succint, and you might have to get back
to the full documentation for precise points. If you are reading this
paragraph, you already have the tar manual in some form. This
manual is available in printed form, as a kind of small book. It may
printed out of the GNU tar distribution, provided you have TeX
already installed somewhere, and a laser printer around. Just configure
the distribution, execute the command `make dvi', then print
`doc/tar.dvi' the usual way (contact your local guru to know how).
If GNU tar has been conveniently installed at your place, this
manual is also available in interactive, hypertextual form as an Info
file. Just call `info tar' or, if you do not have the
info program handy, use the Info reader provided within GNU
Emacs, calling `tar' from the main Info menu.
There is currently no man page for GNU tar. If you observe
such a man page on the system you are running, either it does not
long to GNU tar, or it has not been produced by GNU. Currently,
GNU tar documentation is provided in Texinfo format only, if we
except, of course, the short result of tar --help.
tar progress
Typically, tar performs most operations without reporting any
information to the user except error messages. When using tar
with many options, particularly ones with complicated or
difficult-to-predict behavior, it is possible to make serious mistakes.
tar provides several options that make observing tar
easier. These options cause tar to print information as it
progresses in its job, and you might want to use them just for being
more careful about what is going on, or merely for entertaining
yourself. If you have encountered a problem when operating on an
archive, however, you may need more information than just an error
message in order to solve the problem. The following options can be
helpful diagnostic tools.
Normally, the --list (-t) command to list an archive prints just
the file names (one per line) and the other commands are silent.
When used with most operations, the --verbose (-v) option causes
tar to print the name of each file or archive member as it
is processed. This and the other options which make tar print
status information can be useful in monitoring tar.
With --create (-c) or --extract (--get, -x), --verbose (-v) used once
just prints the names of the files or members as they are processed.
Using it twice causes tar to print a longer listing (reminiscent
of `ls -l') for each member. Since --list (-t) already prints
the names of the members, --verbose (-v) used once with --list (-t)
causes tar to print an `ls -l' type listing of the files
in the archive. The following examples both extract members with
long list output:
$ tar --extract --file=archive.tar --verbose --verbose $ tar xvv archive.tar
Verbose output appears on the standard output except when an archive is
being written to the standard output, as with `tar --create
--file=- --verbose' (`tar cfv -', or even `tar cv'---if the
installer let standard output be the default archive). In that case
tar writes verbose output to the standard error stream.
The --totals option--which is only meaningful when used with
--create (-c)---causes tar to print the total
amount written to the archive, after it has been fully created.
The --checkpoint option prints an occasional message
as tar reads or writes the archive. In fact, it print
directory names while reading the archive. It is designed for
those who don't need the more detailed (and voluminous) output of
--block-number (-R), but do want visual confirmation that tar
is actually making forward progress.
@FIXME{There is some confusion here. It seems that -R once wrote a message at `every' record read or written.}
The --show-omitted-dirs option, when reading an archive--with --list (-t) or --extract (--get, -x), for example--causes a message to be printed for each directory in the archive which is skipped. This happens regardless of the reason for skipping: the directory might not have been named on the command line (implicitly or explicitly), it might be excluded by the use of the --exclude=pattern option, or some other reason.
If --block-number (-R) is used, tar prints, along with every
message it would normally produce, the block number within the archive
where the message was triggered. Also, supplementary messages are
triggered when reading blocks full of NULs, or when hitting end of file on
the archive. As of now, if the archive if properly terminated with a NUL
block, the reading of the file may stop before end of file is met, so the
position of end of file will not usually show when --block-number (-R)
is used. Note that GNU tar drains the archive before exiting when
reading the archive from a pipe.
This option is especially useful when reading damaged archives, since it helps pinpoint the damaged sections. It can also be used with --list (-t) when listing a file-system backup tape, allowing you to choose among several backup tapes when retrieving a file later, in favor of the tape where the file appears earliest (closest to the front of the tape). @FIXME-xref{when the node name is set and the backup section written}.
Typically, tar carries out a command without stopping for
further instructions. In some situations however, you may want to
exclude some files and archive members from the operation (for instance
if disk or storage space is tight). You can do this by excluding
certain files automatically (see section Choosing Files and Names for tar), or by performing
an operation interactively, using the --interactive (-w) option.
tar also accepts `--confirmation' for this option.
When the --interactive (-w) option is specified, before
reading, writing, or deleting files, tar first prints a message
for each such file, telling what operation it intends to take, then asks
for confirmation on the terminal. The actions which require
confirmation include adding a file to the archive, extracting a file
from the archive, deleting a file from the archive, and deleting a file
from disk. To confirm the action, you must type a line of input
beginning with `y'. If your input line begins with anything other
than `y', tar skips that file.
If tar is reading the archive from the standard input,
tar opens the file `/dev/tty' to support the interactive
communications.
Verbose output is normally sent to standard output, separate from
other error messages. However, if the archive is produced directly
on standard output, then verbose output is mixed with errors on
stderr. Producing the archive on standard output may be used
as a way to avoid using disk space, when the archive is soon to be
consumed by another process reading it, say. Some people felt the need
of producing an archive on stdout, still willing to segregate between
verbose output and error output. A possible approach would be using a
named pipe to receive the archive, and having the consumer process to
read from that named pipe. This has the advantage of letting standard
output free to receive verbose output, all separate from errors.
tar Operationstar Operations
The basic tar operations, --create (-c), --list (-t) and
--extract (--get, -x), are currently presented and described in the tutorial
chapter of this manual. This section provides some complementary notes
for these operations.
tar
to destroy a magnetic tape with an empty archive(5). The two most
common errors are:
create instead of extract, when the
intent was to extract the full contents of an archive. This error
is likely: keys c and x are right next ot each other on
the QWERTY keyboard. Instead of being unpacked, the archive then
gets wholly destroyed. When users speak about exploding an
archive, they usually mean something else :-).
file, when the intent was to create
an archive with a single file in it. This error is likely because a
tired user can easily add the f key to the cluster of option
letters, by the mere force of habit, without realizing the full
consequence of doing so. The usual consequence is that the single
file, which was meant to be saved, is rather destroyed.
tar now takes some distance from elegance, and
cowardly refuses to create an archive when --create (-c) option is
given, there are no arguments besides options, and --files-from=file-of-names (-T file-of-names)
option is not used. To get around the cautiousness of GNU
tar and nevertheless create an archive with nothing in it,
one may still use, as the value for the --files-from=file-of-names (-T file-of-names) option,
a file with no names in it, as shown in the following commands:
tar --create --file=empty-archive.tar --files-from=/dev/null tar cfT empty-archive.tar /dev/null
tar archive, as a pipe.
tar now shows dates as `1996-11-09', while it used to
show them as `Nov 11 1996'. (One can revert to the old behavior by
defining USE_OLD_CTIME in `src/list.c' before reinstalling.)
But preferrably, people you should get used to ISO 8601 dates. Local
American dates should be made available again with full date localisation
support, once ready. In the meantime, programs not being localisable
for dates should prefer international dates, that's really the way to go.
Look up http://www.ft.uni-erlangen.de/~mskuhn/iso-time.html if you
are curious, it contains a detailed explanation of the ISO 8601 standard.
tar Operations
Now that you have learned the basics of using GNU tar, you may
want to learn about further ways in which tar can help you.
This chapter presents five, more advanced operations which you probably
won't use on a daily basis, but which serve more specialized functions.
We also explain the different styles of options and why you might want
to use one or another, or a combination of them in your tar
commands. Additionally, this chapter includes options which allow you to
define the output from tar more carefully, and provide help and
error correction in special circumstances.
@FIXME{check this after the chapter is actually revised to make sure it still introduces the info in the chapter correctly : ).}
tar Operations@UNREVISED
In the last chapter, you learned about the first three operations to
tar. This chapter presents the remaining five operations to
tar: `--append', `--update', `--concatenate',
`--delete', and `--compare'.
You are not likely to use these operations as frequently as those covered in the last chapter; however, since they perform specialized functions, they are quite useful when you do need to use them. We will give examples using the same directory and files that you created in the last chapter. As you may recall, the directory is called `practice', the files are `jazz', `blues', `folk', `rock', and the two archive files you created are `collection.tar' and `music.tar'.
We will also use the archive files `afiles.tar' and `bfiles.tar'. `afiles.tar' contains the members `apple', `angst', and `aspic'. `bfiles.tar' contains the members `./birds', `baboon', and `./box'.
Unless we state otherwise, all practicing you do and examples you follow in this chapter will take place in the `practice' directory that you created in the previous chapter; see section Preparing a Practice Directory for Examples. (Below in this section, we will remind you of the state of the examples where the last chapter left them.)
The five operations that we will cover in this chapter are:
Currently, the listing of the directory using ls is as follows:
The archive file `collection.tar' looks like this:
$ tar -tvf collection.tar
The archive file `music.tar' looks like this:
$ tar -tvf music.tar
@FIXME{need to fill in the above!!!}
--append@UNREVISED
If you want to add files to an existing archive, you don't need to create a new archive; you can use --append (-r). The archive must already exist in order to use `--append'. (A related operation is the `--update' operation; you can use this to add newer versions of archive members to an existing archive. To learn how to do this with `--update', see section Updating an Archive.)
@FIXME{Explain in second paragraph whether you can get to the previous version -- explain whole situation somewhat more clearly.}
If you use --append (-r) to add a file that has the same name as an
archive member to an archive containing that archive member, then the
old member is not deleted. What does happen, however, is somewhat
complex. tar allows you to have infinite numbers of files
with the same name. Some operations treat these same-named members no
differently than any other set of archive members: for example, if you
view an archive with --list (-t), you will see all of those members
listed, with their modification times, owners, etc.
Other operations don't deal with these members as perfectly as you might
prefer; if you were to use --extract (--get, -x) to extract the archive,
only the most recently added copy of a member with the same name as four
other members would end up in the working directory. This is because
`--extract' extracts an archive in the order the members appeared
in the archive; the most recently archived members will be extracted
last. Additionally, an extracted member will overwrite a file of
the same name which existed in the directory already, and tar
will not prompt you about this. Thus, only the most recently archived
member will end up being extracted, as it will overwrite the one
extracted before it, and so on.
@FIXME{ hag -- you might want to incorporate some of the above into the MMwtSN node; not sure. i didn't know how to make it simpler...}
There are a few ways to get around this. @FIXME-xref{Multiple Members with the Same Name}.
If you want to replace an archive member, use --delete to delete the member you want to remove from the archive, , and then use `--append' to add the member you want to be in the archive. Note that you can not change the order of the archive; the most recently added member will still appear last. In this sense, you cannot truely "replace" one member with another. (Replacing one member with another will not work on certain types of media, such as tapes; see section Removing Archive Members Using `--delete' and section Tapes and Other Archive Media, for more information.)
The simplest way to add a file to an already existing archive is the --append (-r) operation, which writes specified files into the archive whether or not they are already among the archived files. When you use `--append', you must specify file name arguments, as there is no default. If you specify a file that already exists in the archive, another copy of the file will be added to the end of the archive. As with other operations, the member names of the newly added files will be exactly the same as their names given on the command line. The --verbose (-v) option will print out the names of the files as they are written into the archive.
`--append' cannot be performed on some tape drives, unfortunately,
due to deficiencies in the formats those tape drives use. The archive
must be a valid tar archive, or else the results of using this
operation will be unpredictable. See section Tapes and Other Archive Media.
To demonstrate using `--append' to add a file to an archive,
create a file called `rock' in the `practice' directory.
Make sure you are in the `practice' directory. Then, run the
following tar command to add `rock' to
`collection.tar':
$ tar --append --file=collection.tar rock
If you now use the --list (-t) operation, you will see that `rock' has been added to the archive:
$ tar --list --file=collection.tar -rw-rw-rw- me user 28 1996-10-18 16:31 jazz -rw-rw-rw- me user 21 1996-09-23 16:44 blues -rw-rw-rw- me user 20 1996-09-23 16:44 folk -rw-rw-rw- me user 20 1996-09-23 16:44 rock
@FIXME{in theory, dan will (soon) try to turn this node into what it's title claims it will become...}
You can use --append (-r) to add copies of files which have been
updated since the archive was created. (However, we do not recommend
doing this since there is another tar option called
`--update'; see section Updating an Archive for more information. We describe this
use of `--append' here for the sake of completeness.) @FIXME{is
this really a good idea, to give this whole description for something
which i believe is basically a Stupid way of doing something? certain
aspects of it show ways in which tar is more broken than i'd personally
like to admit to, specifically the last sentence. On the other hand, i
don't think it's a good idea to be saying that re explicitly don't
recommend using som