GNU tar

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

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1. Introduction

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.1 What `tar` Does

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

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

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

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

Storage

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

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

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

Backup

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

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

Transportation

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

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

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

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

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.2 GNU `tar` Authors

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

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

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.3 Reporting bugs or suggestions

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

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.4 Support considerations

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.4.1 Stability of GNU `tar`

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

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

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.4.2 Should we rewrite the thing?

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

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

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.4.3 Why maintaining it?

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

the algorithmic design was initially oriented for machines having very small memory, it was later much adapted for new features without doing everything necessary for the whole to stay clean;
the wide visibility of tar forces many stunts at portability;
GNU tar has to be sensitive to file systems and device variance.
GNU central has been seduced by some users promising to write wonderful tar replacements, which never came, so development has been put aside for years, while bug reports accumulated;
the tar manual has been withdrawn, promising users a fine replacement for it, so raising their expectations;
maintenance was once split between four maintainers (one for tar, one for mt, another for scripts, and a team for documentation), and also, `rtapelib.[ch]' from tar is used in cpio, and synchronisation has not always been easy.

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

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.4.4 MSDOS and other systems?

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

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

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2. Tutorial Introduction to `tar`

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

Before proceeding further with this tutorial chapter, be sure you understand already and clearly what is meant by "archive" and "archive member".

FIXME: xref What tar Does
.

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

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

`--create': `-c'
`--list': `-t'
`--extract': `-x'
`--append': `-r'
`--verbose': `-v'
`--file=archive-name': `-f archive-name'

These options make typing long tar commands easier. For example, instead of typing

tar --create --file=/tmp/afiles.tar --verbose apple angst asparagus
you can type

tar -c -f /tmp/afiles.tar -v apple angst asparagus

For more information on option syntax,

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.1 How to Create Archives

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

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

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

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

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

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

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

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

Whenever you use `--create' (`-c'), tar will erase the current contents of the file named by `--file=archive-name' (`-f archive-name') if it exists. To add files to an existing archive, you need to use a different option.

FIXME: xref Adding to Archives, for information on how to do this.

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

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

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

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

If one of the files named with `--create' (`-c') is a directory, then the operation of tar is more complicated.

FIXME: xref Tar and Directories, FIXME: the last section of this tutorial, for more information.

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

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

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

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

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.1.1 Creating Archives of Files

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

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

Type:

% cd practice % ls

The system responds:

blues folk jazz %

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

Then,

Create a new archive by giving `--create' (`-c') to tar.
Explicitly name the archive file being created---`--file=archive-name' (`-f archive-name'). If you don't use this option tar will write the archive to the default storage device, which varies from system to system.
Specify which files to put into the archive. If you don't specify any file name arguments, tar will archive everything in the working directory.

Type:

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

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

% ls blues folk jazz records %

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

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

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

% cd practice

`~/practice' is now your working directory.

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

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

% ls

The system responds:

blues folk jazz %

Then,

Create a new archive by giving the `--create' (`-c') option to tar.
Explicitly name the archive file being created---`--file=archive-name' (`-f archive-name'). If you don't use this option tar will write the archive to the default storage device, which varies from system to system.
FIXME: this syntax may change. OK now--check before printing
tar interprets archive file names relative to the working directory. Make sure you have write access to the working directory before using tar.
Specify which files to put into the archive (tar interprets file names relative to the working directory). If you don't use any name arguments, tar will archive everything in the working directory.

Type:

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

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

% ls blues folk jazz records %

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.1.2 Using `tar` in Verbose Mode

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

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

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

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

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

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.1.3 How to Archive Directories

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

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

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

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.1.4 Creating an Archive from the Superior Directory

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

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

% cd .. %

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

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

tar should output:

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

Note that the archive thus created is not in the subdirectory `practice', but rather in the working directory--the directory from which tar was invoked. Before trying to archive a directory from its superior directory, you should make sure you have write access to the superior directory itself, not only the directory you are trying archive with tar. Trying to store your home directory in an archive by invoking tar from the root directory will probably not work.

FIXME: xref absolute-names
(Note also that `records', the original archive file, has itself been archived. tar will accept any file as a file to be archived, regardless of its content. When `music' is extracted, the archive file `records' will be re-written into the file system).

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

FIXME: add an xref to --absolute-names

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

% cd .. %

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

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

tar should respond:

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

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

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

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

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

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

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

Invoke tar and specify the operation to compare files in the archive with their counterparts in the file system---`--compare' (`-d') or `--diff'.
Specify the name of the archive where the files to be compared are stored---`--file=archive-name' (`-f archive-name').
Specify the names of the files or directories to be compared, as file name arguments (in this case, you are comparing all the files in the archive, so nothing need be specified).

% tar --compare --file=records %

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

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

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

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

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

% ls blues folk records rock

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

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

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

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

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

FIXME: "manually"? suggestions?

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

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

Invoke tar and specify the `--compare' (`-d') operation---`--compare' (`-d') or `--diff'.
Specify the archive where the files to be compared are stored---`--file=archive-name' (`-f archive-name').
Specify the archive members to be compared. (In this example you are comparing all the archive members in the archive. Since this is the default, you don't need to use any file name arguments).

% tar --compare --file=records %

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

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

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

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

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

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

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

FIXME: Given an example

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.1.6 Using Compare from the Superior Directory

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

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

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

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

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

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

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

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.2 How to List Archives

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

apple angst asparagus

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

./baloons baboon ./bodacious

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

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

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.2.1 Listing the Contents of an Archive

You can list the contents of the archive you just created with another option of tar: `--list' (`-t'). To list the contents of an archive, type:

% tar --list --file=records

tar will respond:

blues folk jazz

FIXME: xref Listing Archive Contents
, for a more detailed tutorial of the `--list' (`-t') operation.

FIXME: xref Listing Contents
for more information about the `--list' (`-t') operation.

FIXME:

You can use `--list' (`-t') to output a list of the files in an archive. If you use file name arguments with this operation, tar will look in the archive for the files specified and display their names only if they are, in fact, stored. You can use `--list' (`-t') with the `--verbose' (`-v') option to find out the attributes (owner, size, etc.) of stored files.

You can list the contents of an archive with another operation of tar: `--list' (`-t'). To list the contents of the archive you just created, type:

% tar --list --file=records

tar will respond:

blues folk jazz

FIXME: xref Listing Archive Contents
, for a more detailed tutorial of the `--list' (`-t') operation.

FIXME: xref Listing Contents
, for more information about the `--list' (`-t') operation.

In a previous example, you created the archive `music' in the home directory. To list the contents of `music':

List the contents of an archive by using `--list' (`-t') with tar.
Specify the name of the archive to be listed---`--file=archive-name' (`-f archive-name').

Thus:

% tar --list --file=music practice/ practice/blues practice/folk practice/jazz practice/records

Use `--list' (`-t') to print the names of files stored in an archive. If you use file name arguments with this operation, tar prints the names of the specified files if they are stored in the archive. If you use a directory name as a file name argument, tar also prints the names of all underlying files, including sub-directories. If you use no file name arguments, tar prints the names of all the archive members.

You can use `--list' (`-t') with the `--verbose' (`-v') option to print archive members' attributes (owner, size, etc.).

To list the names of files stored in an archive, use the `--list' (`-t') operation of tar.

In a previous example, you created the archive `~/music'. To list the contents of `music', while in your home directory:

List the contents of an archive by using with tar.
Specify the archive to be listed---`--file=archive-name' (`-f archive-name').

Thus:

% tar --list --file=music practice/ practice/blues practice/folk practice/jazz practice/records

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.2.2 Getting Additional File Information

When you specify the `--verbose' (`-v') option in conjunction with `--list' (`-t'), tar will print additional information about the files being listed (file protection, owner and group ID, size, and date and time of creation). The example above, in verbose mode, would be:

% tar --list --verbose --file=music drwxrwxrwx myself/user 0 May 31 21:49 1990 practice/ -rw-rw-rw- myself/user 42 May 21 13:29 1990 practice/blues -rw-rw-rw- myself/user 62 May 23 10:55 1990 practice/folk -rw-rw-rw- myself/user 40 May 21 13:30 1990 practice/jazz -rw-rw-rw- myself/user 10240 May 31 21:49 1990 practice/records %

Note that using `--verbose' (`-v') with `--list' (`-t') does not cause tar to print the names of files as they are being acted on, though the `--verbose' (`-v') option will have this effect with all other operations.

To get more information when you list the names of files stored in an archive, specify the `--verbose' (`-v') option in conjunction with `--list' (`-t').

tar will print archive member's file protection, owner and group ID, size, and date and time of creation.

For example:

Note that when you use `--verbose' (`-v') with `--list' (`-t'), tar doesn't print the names of files as they are being acted on, though the `--verbose' (`-v') option will have this effect when used with all other operations.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.2.3 List A Specific File in an Archive

FIXME:
To to see if a particular file is in an archive, specify the name of the file in question as a file name argument while specifying the `--list' (`-t') operation. For example, if you wanted to see if the file `folk' were in the archive file `music', you would:

Invoke tar, and specify the operation to list the contents of an archive---`--list' (`-t').
Specify the name of the archive file to be acted on---`--file=archive-name' (`-f archive-name').
Specify the name of the file tar is to look for, as a file name argument. Because tar preserves paths, file names must be specified as they appear in the archive (ie.. as they are relative to the directory from which the archive was created).
FIXME: xref -P

Type:

% tar --list --file=music practice/folk

tar responds:

practice/folk

If the file were not in the archive (for example, the file `practice/rock'), the example above would look like:

% tar --list --file=music practice/rock tar: practice/rock not found in archive

The `--verbose' (`-v') option does not have any effect on execution of the `--list' (`-t') operation when you have specified file name arguments.

FIXME: this is a bug (?)

To to see if a particular file is in an archive, use the name of the file in question as a file name argument while specifying the `--list' (`-t') operation. For example, to see whether the file `folk' is in the archive file `music', do the following:

Invoke tar, and specify the `--list' (`-t') operation.
Specify the archive file to be acted on---`--file=archive-name' (`-f archive-name').
Specify the files to look for, by typing their names as file name arguments. You have to type the file name as it appears in the archive (normally, as it is relative to the relative to the directory from which the archive was created).
FIXME: xref absolute-names

Type:

% tar --list --file=music practice/folk

tar responds:

practice/folk

If the file were not stored in the archive (for example, the file `practice/rock'), the example above would look like:

% tar --list --file=music practice/rock tar: practice/rock not found in archive

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

% tar --list --file=music practice/folk -rw-rw-rw- myself/user 62 May 23 10:55 1990 practice/folk

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.2.4 Listing the Contents of a Stored Directory

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', type:

% tar --list --file=music practice

tar responds:

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

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3 How to Extract Members from an Archive

In order to extract members from an archive, use the `--extract' (`-x') option. Specify the name of the archive with `--file=archive-name' (`-f archive-name'). To extract specific archive members, give their member names as arguments. It essential to give their exact member name, as printed by `--list' (`-t'). This will create a copy of the archive member, with a file name the same as its name in the archive.

Keeping the example of the two archives created at the beginning of this tutorial, `tar --extract --file=afiles.tar apple' would create a file `apple' in the current directory with the contents of the archive member `apple'. It would remove any file named `apple' already present in the directory, but it would not change the archive in any way.

Remember that specifying the exact member name is important. `tar --extract --file=bfiles.tar baloons' will fail, because there is no member named `baloons'. To extract the member named `./baloons' you would need to specify `tar --extract --file=bfiles.tar ./baloons'. To find the exact member names of the members of an archive, use `--list' (`-t').

FIXME: xref Listing Archives.

If you do not list any archive member names, then `--extract' (`-x') will extract all the members of the archive.

If you give the `--verbose' (`-v') option, then `--extract' (`-x') will print the names of the archive members as it extracts them.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.1 Extract Files from an Archive into Your Current Directory

Obviously, the ultimate goal of tar users is to eventually get their files back. To do this, use the `--extract' (`-x') or `--get' operation. `--extract' (`-x') can be used to retrieve individual files from an archive, or can be used to write all the files in the archive back into the file system.

In the previous example you concatenated two archives, `music', and `practice/records'. To now retrieve the complete contents of `music' (the target file in the concatenation process), you would, from the home directory:

Invoke tar and specify the operation to extract files from an archive (`--extract' (`-x') or `--get'.
Specify the name of the archive the files will be extracted from---`--file=archive-name' (`-f archive-name').
Specify the names of the files you wish to extract, as file name arguments (in this case you want to extract the entire archive, so you don't need to specify anything).

% tar --extract --file=music tar: Could not make directory practice : File exists

Because the files stored originally in `music' were stored as files in a subdirectory (not as files in the working directory), they are stored in the archive with a leading directory name---tar, in restoring them, has tried to recreate that directory and failed: the directory already exists. The extraction has not been aborted, however. If you now change into the `practice' directory and generate a directory listing, you will find that `jazz', which we removed in an earlier example, has been resurrected.

% cd practice % ls blues classical folk jazz records rock

If you look more closely at the files in the directory, however, you will find that `blues' and `folk' are, in fact, the original versions of the file, which were stored in `music' at the beginning of the tutorial. tar, in extracting the original files from `music', has overwritten the existing files in the file system.

While the newer versions of the files were stored in `records' above, they can no longer be extracted from it. `records' too was archived by tar when the `practice' directory was stored in the archive file `music', and was restored to its older incarnation when the files in `practice' were overwritten. However, the newer version of `records' was concatenated with `music'. The contents of the newer version of `records', therefore, should have been extracted when all the contents of `music' were extracted. They were. tar has restored them into the working directory using the names with which they were originally stored. Because they were originally stored as part of `records', in the `practice' directory, they had no preceeding directory stored as part of their file names. To find the latest versions of `blues', `folk', `jazz', `rock' and `classical', look in your home directory.

You may wish to restore the files in your `practice' directory to their last state before we extracted the files from `music'. Rather than moving the files from your home directory to the `practice' subdirectory, you can run the same extraction procedure as above using the `practice' subdirectory as your working directory:

% cd practice % tar --extract --verbose --file=~/music practice/ practice/blues practice/folk practice/jazz practice/records blues folk jazz blues rock blues classical %

If you now examine the files in the practice directory, you will find that the files have been restored to their previous, newer, states. The old versions of the files, which were stored in `music' with a preceeding directory name, have been written into a newly created subdirectory under the working directory (which is your `practice' subdirectory). The new subdirectory is also called `practice'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.2 Extracting Files from an Archive

Creating an archive is only half the job--there would be no point in storing files in an archive if you couldn't retrieve them. To extract files from an archive, use the `--extract' (`-x') operation.

To extract specific files, use their names as file name arguments. If you use a directory name as a file name argument, tar extracts all the files (including subdirectories) in that directory. If you don't use any file name arguments, tar extracts all the files in the archive.

Note: tar will extract an archive member into the file system without checking to see if there is already a file with the archive member's file name. If there is a file with that name, tar will overwrite that file and its contents will be lost.

FIXME: xref keep-old

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.3 Extracting Specific Files

To extract specific files, specify them using file name arguments.

In an example above, you created the archive file `~/practice/records', which contained the files `blues', `folk' and `jazz' in the `practice' directory. If, for some reason, you were to lose one of those text files (`rm ~/practice/blues'), you could extract it from the archive file.

First, change into the `practice' directory. Then,

Invoke tar and specify the `--extract' (`-x') or `--get' operation.
Specify the archive that the files will be extracted from---`--file=archive-name' (`-f archive-name').
Specify the files to extract, using file name arguments (if you don't specify any files, tar extracts all the archive members)

% tar --extract --file=records blues

If you list the contents of the directory, you will see that `blues' is back:

% ls folk jazz records blues

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.4 Extracting Directories

To extract a directory and all the files it contains, use the directory's name as a file name argument in conjunction with `tar +extract'. Remember--tar stores and extracts file names relative to the working directory.

In a previous example you stored the directory `~/practice' in the archive file `~/music'. If you delete the contents of `practice', you can restore them using

1. Introduction
2. Tutorial Introduction to `tar`
3. Invoking GNU `tar`
4. Basic `tar` Operations
5. Specifying Names to `tar`
6. Being Even More Careful
7. Controlling the Archive Format
8. Tapes and Other Archive Media
9. Performing Backups and Restoring Files
10. Date input formats
11. Format of `tar` archives
Index

1.1 What `tar` Does
1.2 GNU `tar` Authors
1.3 Reporting bugs or suggestions
1.4 Support considerations

1.4.1 Stability of GNU `tar`
1.4.2 Should we rewrite the thing?
1.4.3 Why maintaining it?
1.4.4 MSDOS and other systems?

2.1.1 Creating Archives of Files
2.1.2 Using `tar` in Verbose Mode
2.1.3 How to Archive Directories
2.1.4 Creating an Archive from the Superior Directory
2.1.5 Comparing Files in an Archive with Files in the File System
2.1.6 Using Compare from the Superior Directory

2.4.1 Appending Files to an Archive
2.4.2 Updating Files in an Archive
2.4.3 Concatenating Archives

3.1 General Synopsis of `tar`
3.2 Many Styles for Options
3.3 All Available Options

3.2.1 Mnemonic Option Style
3.2.2 Short Option Style
3.2.3 Old Option Style
3.2.4 Mixing Option Styles

3.3.1 Device selection and switching
3.3.2 Device blocking
3.3.3 Old classification of options

4.1 Creating a New Archive
4.2 Adding to an Existing Archive
4.3 Updating an Archive
4.4 Combining Archives
4.5 Removing Archive Members
4.6 Listing Archive Members
4.7 Extracting Archive Members
4.8 Comparing Archives Members with Files
4.9 Matching the Format Parameters

4.7.1 Options to Help Read Archives
4.7.2 Changing How `tar` Writes Files
4.7.3 Recovering From Scarce Disk Space

5.1 Changing the Archive Name
5.2 Selecting Files by Characteristic
5.3 Local file selection

5.2.1 Reading Names from a File
5.2.2 Excluding Some Files
5.2.3 Operating Only on New Files
5.2.4 Crossing Filesystem Boundaries

6.1 GNU `tar` documentation
6.2 Checking `tar` progress
6.3 Asking for Confirmation During Operations
6.4 Verifying Data as It is Stored
6.5 Comparing an Archive with the File System
6.6 Making `tar` Archives More Portable
6.7 Write Protection

6.6.1 Portable Names
6.6.2 Symbolic Links
6.6.3 Old V7 and POSIX Archives
6.6.4 Checksumming Problems

7.1 Handling of file attributes
7.2 Archive format selection
7.3 Using Less Space through Compression
7.4 Special Options for Archiving
7.5 The Structure of an Archive
7.6 Operation mode modifiers

7.3.1 Creating and Reading Compressed Archives
7.3.2 Dealing with Compressed Archives
7.3.3 Archiving Sparse Files

8.1 Device selection and switching
8.2 Blocking
8.3 Many archives on one tape
8.4 Using Multiple Tapes
8.5 Including a Label in the Archive

8.2.1 Format Variations
8.2.2 The Blocking Factor of an Archive

9.1 Using `tar` to Perform Full Dumps
9.2 Using `tar` to Perform Incremental Dumps
9.3 The Incremental Options
9.4 Levels of Backups
9.5 Setting Parameters for Backups and Restoration
9.6 Using the Backup Scripts
9.7 Using the Restore Script

9.5.1 An Example Text of `Backup-specs'
9.5.2 Syntax for `Backup-specs'

GNU tar

1. Introduction

1.1 What tar Does

1.2 GNU tar Authors

1.3 Reporting bugs or suggestions

1.4 Support considerations

1.4.1 Stability of GNU tar

1.4.2 Should we rewrite the thing?

1.4.3 Why maintaining it?

1.4.4 MSDOS and other systems?

2. Tutorial Introduction to tar

2.1 How to Create Archives

2.1.1 Creating Archives of Files

2.1.2 Using tar in Verbose Mode

2.1.3 How to Archive Directories

2.1.4 Creating an Archive from the Superior Directory

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

2.1.6 Using Compare from the Superior Directory

2.2 How to List Archives

2.2.1 Listing the Contents of an Archive

2.2.2 Getting Additional File Information

2.2.3 List A Specific File in an Archive

2.2.4 Listing the Contents of a Stored Directory

2.3 How to Extract Members from an Archive

2.3.1 Extract Files from an Archive into Your Current Directory

2.3.2 Extracting Files from an Archive

2.3.3 Extracting Specific Files

2.3.4 Extracting Directories

1.1 What `tar` Does

1.2 GNU `tar` Authors

1.4.1 Stability of GNU `tar`

2. Tutorial Introduction to `tar`

2.1.2 Using `tar` in Verbose Mode

10.1 General date syntax
10.2 Calendar date item
10.3 Time of day item
10.4 Timezone item
10.5 Day of week item
10.6 Relative item in date strings
10.7 Pure numbers in date strings
10.8 Authors of `getdate`

11.1 The Standard Format
11.2 GNU Extensions to the Archive Format
11.3 Comparison of `tar` and `cpio`