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


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

Some Definitions

The tar program is used to create and manipulate tar archives. An archive is a single file which contains the contents of many files, while still identifying the names of the files, their owner(s), and so forth. (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.

What tar Does

The tar program provides the ability to create tar archives, as well as various other kinds of manipulation. For example, you can use tar on previously created archives to extract files, to store additional files, or to update or list files which were already stored.

Initially, tar archives were used to store files conveniently on magnetic tape. The name `tar' comes from this use; it stands for 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.

Often, tar archives are used to store related files for convenient file transfer over a network. For example, the GNU Project distributes its software bundled into tar archives, so that all the files relating to a particular program (or set of related programs) can be transferred as a single unit. A magnetic tape can store several files in sequence. However, the tape has no names for these files; it only knows their relative position on the tape. One way to store several files on one tape and retain their names is by creating a tar archive. Even when the basic transfer mechanism can keep track of names, as FTP can, the nuisance of handling multiple files, directories, and multiple links makes tar archives useful. Archive files are also used for long-term storage. You can think of this as transportation from the present into the future. (It is a science-fiction idiom that you can move through time as well as in space; the idea here is that tar can be used to move archives in all dimensions, even time!)
Because the archive created by tar is capable of preserving file information and directory structure, tar is commonly used for performing full and incremental backups of disks. A backup puts a collection of files (possibly pertaining to many users and projects) together on a disk or a tape. This guards against accidental destruction of the information in those files. GNU tar has special features that allow it to be used to make incremental and full dumps of all the files in a filesystem.
You can create an archive on one system, transfer it to another system, and extract the contents there. This allows you to transport a group of files from one system to another.

How tar Archives are Named

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

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

POSIX Compliance

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

GNU tar Authors

GNU tar was originally written by John Gilmore, and modified by many people. The GNU enhancements were written by Jay Fenlason, then Joy Kendall, and the whole package has been further maintained by Thomas Bushnell, n/BSG, and finally 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.

Reporting bugs or suggestions

If you find problems or have suggestions about this program or manual, please report them to `bug-gnu-utils@prep.ai.mit.edu'.

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