Go to the first, previous, next, last section, table of contents.


Tutorial Introduction to 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:

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?}

Basic 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.

The Three Most Frequently Used Operations

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
-c
Create a new tar archive.
--list
-t
List the contents of an archive.
--extract
-x
Extract one or more members from an archive.

Two Frequently Used Options

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

The `--file' Option

--file=archive-name
-f archive-name
Specify the name of an archive file.

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

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

The `--verbose' Option

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

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

Sometimes, a single instance of `--verbose' on the command line will show a full, `ls' style listing of an archive or files, giving sizes, owners, and similar information. Other times, `--verbose' will only show files or members that the particular 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'.

Getting Help: Using the --help Option

--help
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.

How to Create Archives

@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.

Preparing a Practice Directory for Examples

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

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

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

It is very important to make sure there isn't already a file in the working directory with the archive name you intend to use (in this case, `collection.tar'), or that you don't care about its contents. Whenever you use `create', tar will erase the current contents of the file named by --file=archive-name (-f archive-name) if it exists. tar will not tell you if you are about to overwrite a file unless you specify an option which does this @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.

Creating the Archive

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

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

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

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

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

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

The order of the options becomes more important when you begin to use short forms. With short forms, if you type commands in the wrong order (even if you type them correctly in all other ways), you may end up with results you don't expect. For this reason, it is a good idea to get into the habit of typing options in the order that makes inherent sense. 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.

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

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

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

This example is just like the example we showed which did not use `--verbose', except that tar generated the remaining lines (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.

Short Forms with `create'

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.)

Archiving Directories

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

To archive a directory, first move to its superior directory. If you have followed the previous instructions in this tutorial, you should type:

$ cd ..
$

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

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

tar should output:

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

Note that the archive thus created is not in the subdirectory `practice', but rather in the current working directory--the directory from which tar was invoked. Before trying to archive a directory from its superior directory, you should make sure you have write access to the superior directory itself, not only the directory you are trying archive with tar. For example, you will probably not be able to store your home directory in an archive by invoking tar from the root directory; 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.})

How to List Archives

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.

Listing the Contents of a Stored Directory

@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.

How to Extract Members from an Archive

@UNREVISED

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.

Extracting an Entire Archive

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

Extracting Specific Files

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 Files that are Directories

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.}

Commands That Will Fail

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.}

Going Further Ahead in this Manual

@FIXME{need to write up a node here about the things that are going to be in the rest of the manual.}


Go to the first, previous, next, last section, table of contents.