This manual is for GNU tar (version 1.15.90, 19 February 2006), which creates and extracts files from archives.
Copyright © 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "GNU General Public License", with the Front-Cover Texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License".(a) The FSF's Back-Cover Text is: “You are free to copy and modify this GNU Manual. Buying copies from GNU Press supports the FSF in developing GNU and promoting software freedom.”
The first part of this master menu lists the major nodes in this Info document. The rest of the menu lists all the lower level nodes.
Appendices
--- The Detailed Node Listing ---
Introduction
Tutorial Introduction to tar
Two Frequently Used Options
How to Create Archives
How to List Archives
How to Extract Members from an Archive
Invoking GNU tar
The Three Option Styles
All tar Options
GNU tar Operations
Advanced GNU tar Operations
How to Add Files to Existing Archives: --append
Updating an Archive
Options Used by --create
Options Used by --extract
Options to Help Read Archives
Changing How tar Writes Files
Coping with Scarce Resources
Performing Backups and Restoring Files
Setting Parameters for Backups and Restoration
Choosing Files and Names for tar
Reading Names from a File
Excluding Some Files
Crossing File System Boundaries
Date input formats
Controlling the Archive Format
Making tar Archives More Portable
Using Less Space through Compression
Tapes and Other Archive Media
Blocking
Many Archives on One Tape
Using Multiple Tapes
GNU tar internals and development
Copying This Manual
GNU tar creates and manipulates archives which are actually collections of many other files; the program provides users with an organized and systematic method for controlling a large amount of data. The name “tar” originally came from the phrase “Tape ARchive”, but archives need not (and these days, typically do not) reside on tapes.
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 Tutorial) 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 Tutorial.)
The third chapter presents the remaining five operations, and information about using tar options and option syntax.
The other chapters are meant to be used as a reference. Each chapter presents everything that needs to be said about a specific topic.
One of the chapters (see Date input formats) exists in its entirety in other GNU manuals, and is mostly self-contained. In addition, one section of this manual (see Standard) contains a big quote which is taken directly from tar sources.
In general, we give both long and short (abbreviated) option names at least once in each section where the relevant option is covered, so that novice readers will become familiar with both styles. (A few options have no short versions, and the relevant sections will indicate this.)
The tar program is used to create and manipulate tar archives. An archive is a single file which contains the contents of many files, while still identifying the names of the files, their owner(s), and so forth. (In addition, archives record access permissions, user and group, size in bytes, and data modification time. Some archives also record the file names in each archived directory, as well as other file and directory information.) You can use tar to create a new archive in a specified directory.
The files inside an archive are called members. Within this manual, we use the term file to refer only to files accessible in the normal ways (by ls, cat, and so forth), and the term member to refer only to the members of an archive. Similarly, a file name is the name of a file, as it resides in the file system, and a member name is the name of an archive member within the archive.
The term extraction refers to the process of copying an archive member (or multiple members) into a file in the file system. Extracting all the members of an archive is often called extracting the archive. The term unpack can also be used to refer to the extraction of many or all the members of an archive. Extracting an archive does not destroy the archive's structure, just as creating an archive does not destroy the copies of the files that exist outside of the archive. You may also list the members in a given archive (this is often thought of as “printing” them to the standard output, or the command line), or append members to a pre-existing archive. All of these operations can be performed using tar.
The tar program provides the ability to create tar archives, as well as various other kinds of manipulation. For example, you can use tar on previously created archives to extract files, to store additional files, or to update or list files which were already stored.
Initially, tar archives were used to store files conveniently on
magnetic tape. The name tar comes from this use; it stands for
tape archiver. Despite the utility's name, tar can
direct its output to available devices, files, or other programs (using
pipes). tar may even access remote devices or files (as archives).
You can use tar archives in many ways. We want to stress a few of them: storage, backup, and transportation.
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!)
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.
GNU tar was originally written by John Gilmore, and modified by many people. The GNU enhancements were written by Jay Fenlason, then Joy Kendall, and the whole package has been further maintained by Thomas Bushnell, n/BSG, François Pinard, Paul Eggert, and finally Sergey Poznyakoff with the help of numerous and kind users.
We wish to stress that tar is a collective work, and owes much to all those people who reported problems, offered solutions and other insights, or shared their thoughts and suggestions. An impressive, yet partial list of those contributors can be found in the THANKS file from the GNU tar distribution.
Jay Fenlason put together a draft of a GNU tar manual, borrowing notes from the original man page from John Gilmore. This was withdrawn in version 1.11. Thomas Bushnell, n/BSG and Amy Gorin worked on a tutorial and manual for GNU tar. François Pinard put version 1.11.8 of the manual together by taking information from all these sources and merging them. Melissa Weisshaus finally edited and redesigned the book to create version 1.12.
For version 1.12, Daniel Hagerty contributed a great deal of technical consulting. In particular, he is the primary author of Backups.
In July, 2003 GNU tar was put on CVS at savannah.gnu.org (see http://savannah.gnu.org/projects/tar), and active development and maintenance work has started again. Currently GNU tar is being maintained by Paul Eggert, Sergey Poznyakoff and Jeff Bailey.
Support for POSIX archives was added by Sergey Poznyakoff.
If you find problems or have suggestions about this program or manual, please report them to bug-tar@gnu.org.
When reporting a bug, please be sure to include as much detail as possible, in order to reproduce it. .
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’.
tar can take a wide variety of arguments which specify and define the actions it will have on the particular set of files or the archive. The main types of arguments to tar fall into one of two classes: operations, and options.
Some arguments fall into a class called operations; exactly one of these is both allowed and required for any instance of using tar; you may not specify more than one. People sometimes speak of operating modes. You are in a particular operating mode when you have specified the operation which specifies it; there are eight operations in total, and thus there are eight operating modes.
The other arguments fall into the class known as options. You are not required to specify any options, and you are allowed to specify more than one at a time (depending on the way you are using tar at that time). Some options are used so frequently, and are so useful for helping you type commands more carefully that they are effectively “required”. We will discuss them in this chapter.
You can write most of the tar operations and options in any of three forms: long (mnemonic) form, short form, and old style. Some of the operations and options have no short or “old” forms; however, the operations and options which we will cover in this tutorial have corresponding abbreviations. We will indicate those abbreviations appropriately to get you used to seeing them. (Note that the “old style” option forms exist in GNU tar for compatibility with Unix tar. In this book we present a full discussion of this way of writing options and operations (see Old Options), and we discuss the other two styles of writing options (See Mnemonic Options, and see Short Options).
In the examples and in the text of this tutorial, we usually use the long forms of operations and options; but the “short” forms produce the same result and can make typing long tar commands easier. For example, instead of typing
tar --create --verbose --file=afiles.tar apple angst aspic
you can type
tar -c -v -f afiles.tar apple angst aspic
or even
tar -cvf afiles.tar apple angst aspic
For more information on option syntax, see Advanced tar. In discussions in the text, when we name an option by its long form, we also give the corresponding short option in parentheses.
The term, “option”, can be confusing at times, since “operations” are often lumped in with the actual, optional “options” in certain general class statements. For example, we just talked about “short and long forms of options and operations”. However, experienced tar users often refer to these by shorthand terms such as, “short and long options”. This term assumes that the “operations” are included, also. Context will help you determine which definition of “options” to use.
Similarly, the term “command” can be confusing, as it is often used in two different ways. People sometimes refer to tar “commands”. A tar command is the entire command line of user input which tells tar what to do — including the operation, options, and any arguments (file names, pipes, other commands, etc). However, you will also sometimes hear the term “the tar command”. When the word “command” is used specifically like this, a person is usually referring to the tar operation, not the whole line. Again, use context to figure out which of the meanings the speaker intends.
Here are the three most frequently used operations (both short and long forms), as well as a brief description of their meanings. The rest of this chapter will cover how to use these operations in detail. We will present the rest of the operations in the next chapter.
To understand how to run tar in the three operating modes listed previously, you also need to understand how to use two of the options to tar: --file (which takes an archive file as an argument) and --verbose. (You are usually not required to specify either of these options when you run tar, but they can be very useful in making things more clear and helping you avoid errors.)
You can specify an argument for the --file=archive-name (-f archive-name) option whenever you use tar; this option determines the name of the archive file that tar will work on.
If you don't specify this argument, then tar will examine the environment variable TAPE. If it is set, its value will be used as the archive name. Otherwise, tar will use the default archive, determined at the compile time. Usually it is standard output or some physical tape drive attached to your machine (you can verify what the default is by running tar --show-defaults, see defaults). If there is no tape drive attached, or the default is not meaningful, then tar will print an error message. The error message might look roughly like one of the following:
tar: can't open /dev/rmt8 : No such device or address
tar: can't open /dev/rsmt0 : I/O error
To avoid confusion, we recommend that you always specify an archive file name by using --file=archive-name (-f archive-name) when writing your tar commands. For more information on using the --file=archive-name (-f archive-name) option, see file.
--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.
One of the basic operations of tar is --create (-c), which you use to create a tar archive. We will explain --create first because, in order to learn about the other operations, you will find it useful to have an archive available to practice on.
To make this easier, in this section you will first create a directory containing three files. Then, we will show you how to create an archive (inside the new directory). Both the directory, and the archive are specifically for you to practice on. The rest of this chapter and the next chapter will show many examples using this directory and the files you will create: some of those files may be other directories and other archives.
The three files you will archive in this example are called blues, folk, and jazz. The archive is called collection.tar.
This section will proceed slowly, detailing how to use --create
in verbose mode, and showing examples using both short and long
forms. In the rest of the tutorial, and in the examples in the next
chapter, we will proceed at a slightly quicker pace. This section
moves more slowly to allow beginning users to understand how
tar works.
To follow along with this and future examples, create a new directory called practice containing files called blues, folk and jazz. The files can contain any information you like: ideally, they should contain information which relates to their names, and be of different lengths. Our examples assume that practice is a subdirectory of your home directory.
Now cd to the directory named practice; practice is now your working directory. (Please note: Although the full path name of this directory is /homedir/practice, in our examples we will refer to this directory as practice; the homedir is presumed.
In general, you should check that the files to be archived exist where you think they do (in the working directory) by running ls. Because you just created the directory and the files and have changed to that directory, you probably don't need to do that this time.
It is very important to make sure there isn't already a file in the working directory with the archive name you intend to use (in this case, ‘collection.tar’), or that you don't care about its contents. Whenever you use ‘create’, tar will erase the current contents of the file named by --file=archive-name (-f archive-name) if it exists. tar will not tell you if you are about to overwrite an archive unless you specify an option which does this (see backup, for the information on how to do so). To add files to an existing archive, you need to use a different option, such as --append (-r); see append for information on how to do this.
To place the files blues, folk, and jazz into an archive named collection.tar, use the following command:
$ tar --create --file=collection.tar blues folk jazz
The order of the arguments is not very important, when using long option forms. You could also say:
$ tar blues --create folk --file=collection.tar jazz
However, you can see that this order is harder to understand; this is why we will list the arguments in the order that makes the commands easiest to understand (and we encourage you to do the same when you use tar, to avoid errors).
Note that the part of the command which says, --file=collection.tar is considered to be one argument. If you substituted any other string of characters for collection.tar, then that string would become the name of the archive file you create.
The order of the options becomes more important when you begin to use short forms. With short forms, if you type commands in the wrong order (even if you type them correctly in all other ways), you may end up with results you don't expect. For this reason, it is a good idea to get into the habit of typing options in the order that makes inherent sense. See short 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). Now that they are in the archive, they are called archive members, not files. (see members).
When you create an archive, you must specify which files you want placed in the archive. If you do not specify any archive members, GNU tar will complain.
If you now list the contents of the working directory (ls), you will find the archive file listed as well as the files you saw previously:
blues folk jazz collection.tar
Creating the archive ‘collection.tar’ did not destroy the copies of the files in the directory.
Keep in mind that if you don't indicate an operation, tar will not run and will prompt you for one. If you don't name any files, tar will complain. You must have write access to the working directory, or else you will not be able to create an archive in that directory.
Caution: Do not attempt to use --create (-c) to add files to an existing archive; it will delete the archive and write a new one. Use --append (-r) instead. See append.
If you include the --verbose (-v) option on the command line,
tar will list the files it is acting on as it is working. In
verbose mode, the create example above would appear as:
$ tar --create --verbose --file=collection.tar blues folk jazz
blues
folk
jazz
This example is just like the example we showed which did not use --verbose, except that tar generated the remaining lines
In the rest of the examples in this chapter, we will frequently use
verbose mode so we can show actions or tar responses that
you would otherwise not see, and which are important for you to
understand.
As we said before, the --create (-c) operation is one of the most basic uses of tar, and you will use it countless times. Eventually, you will probably want to use abbreviated (or “short”) forms of options. A full discussion of the three different forms that options can take appears in Styles; for now, here is what the previous example (including the --verbose (-v) option) looks like using short option forms:
$ tar -cvf collection.tar blues folk jazz
blues
folk
jazz
As you can see, the system responds the same no matter whether you use long or short option forms.
One difference between using short and long option forms is that, although the exact placement of arguments following options is no more specific when using short forms, it is easier to become confused and make a mistake when using short forms. For example, suppose you attempted the above example in the following way:
$ tar -cfv collection.tar blues folk jazz
In this case, tar will make an archive file called v, containing the files blues, folk, and jazz, because the ‘v’ is the closest “file name” to the -f option, and is thus taken to be the chosen archive file name. tar will try to add a file called collection.tar to the v archive file; if the file collection.tar did not already exist, tar will report an error indicating that this file does not exist. If the file collection.tar does already exist (e.g., from a previous command you may have run), then tar will add this file to the archive. Because the -v option did not get registered, tar will not run under ‘verbose’ mode, and will not report its progress.
The end result is that you may be quite confused about what happened, and possibly overwrite a file. To illustrate this further, we will show you how an example we showed previously would look using short forms.
This example,
$ tar blues --create folk --file=collection.tar jazz
is confusing as it is. When shown using short forms, however, it becomes much more so:
$ tar blues -c folk -f collection.tar jazz
It would be very easy to put the wrong string of characters immediately following the -f, but doing that could sacrifice valuable data.
For this reason, we recommend that you pay very careful attention to the order of options and placement of file and archive names, especially when using short option forms. Not having the option name written out mnemonically can affect how well you remember which option does what, and therefore where different names have to be placed.
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 absolute. (Note also that collection.tar, the original archive file, has itself been archived. tar will accept any file as a file to be archived, regardless of its content. When music.tar is extracted, the archive file collection.tar will be re-written into the file system).
If you give tar a command such as
$ tar --create --file=foo.tar .
tar will report ‘tar: ./foo.tar is the archive; not dumped’. This happens because tar creates the archive foo.tar in the current directory before putting any files into it. Then, when tar attempts to add all the files in the directory . to the archive, it notices that the file ./foo.tar is the same as the archive foo.tar, and skips it. (It makes no sense to put an archive into itself.) GNU tar will continue in this case, and create the archive normally, except for the exclusion of that one file. (Please note: Other 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.)
Frequently, you will find yourself wanting to determine exactly what a particular archive contains. You can use the --list (-t) operation to get the member names as they currently appear in the archive, as well as various attributes of the files at the time they were archived. For example, you can examine the archive collection.tar that you created in the last section with the command,
$ tar --list --file=collection.tar
The output of tar would then be:
blues
folk
jazz
The archive bfiles.tar would list as follows:
./birds
baboon
./box
Be sure to use a --file=archive-name (-f archive-name) option just as with --create (-c) to specify the name of the archive.
If you use the --verbose (-v) option with --list, then tar will print out a listing reminiscent of ‘ls -l’, showing owner, file size, and so forth.
If you had used --verbose (-v) mode, the example above would look like:
$ tar --list --verbose --file=collection.tar folk
-rw-r--r-- myself user 62 1990-05-23 10:55 folk
It is important to notice that the output of tar --list --verbose does not necessarily match that produced by tar --create --verbose while creating the archive. It is because GNU tar, unless told explicitly not to do so, removes some directory prefixes from file names before storing them in the archive (See absolute, for more information). In other words, in verbose mode GNU tar shows file names when creating an archive and member names when listing it. Consider this example:
$ tar cfv archive /etc/mail
tar: Removing leading `/' from member names
/etc/mail/
/etc/mail/sendmail.cf
/etc/mail/aliases
$ tar tf archive
etc/mail/
etc/mail/sendmail.cf
etc/mail/aliases
This default behavior can sometimes be inconvenient. You can force GNU tar show member names when creating archive by supplying --show-stored-names option.
You can specify one or more individual member names as arguments when using ‘list’. In this case, tar will only list the names of members you identify. For example, tar --list --file=afiles.tar apple would only print apple.
Because tar preserves 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 absolute.
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.
To get information about the contents of an archived directory, use the directory name as a file name argument in conjunction with --list (-t). To find out file attributes, include the --verbose (-v) option.
For example, to find out about files in the directory practice, in the archive file music.tar, type:
$ tar --list --verbose --file=music.tar practice
tar responds:
drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
-rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues
-rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk
-rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz
-rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar
When you use a directory name as a file name argument, tar acts on all the files (including sub-directories) in that directory.
Creating an archive is only half the job—there is no point in storing files in an archive if you can't retrieve them. The act of retrieving members from an archive so they can be used and manipulated as unarchived files again is called extraction. To extract files from an archive, use the --extract (--get or -x) operation. As with --create, specify the name of the archive with --file (-f) option. Extracting an archive does not modify the archive in any way; you can extract it multiple times if you want or need to.
Using --extract, you can extract an entire archive, or specific files. The files can be directories containing other files, or not. As with --create (-c) and --list (-t), you may use the short or the long form of the operation without affecting the performance.
To extract an entire archive, specify the archive file name only, with no individual file names as arguments. For example,
$ tar -xvf collection.tar
produces this:
-rw-r--r-- me user 28 1996-10-18 16:31 jazz
-rw-r--r-- me user 21 1996-09-23 16:44 blues
-rw-r--r-- me user 20 1996-09-23 16:44 folk
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. Its contents will be identical to the original file blues that you deleted.
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, data modification times, and owner. (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).
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 list).
You can extract a file to standard output by combining the above options with the --to-stdout (-O) option (see Writing to Standard Output).
If you give the --verbose option, then --extract will print the names of the archive members as it extracts them.
Extracting directories which are members of an archive is similar to extracting other files. The main difference to be aware of is that if the extracted directory has the same name as any directory already in the working directory, then files in the extracted directory will be placed into the directory of the same name. Likewise, if there are files in the pre-existing directory with the same names as the members which you extract, the files from the extracted archive will replace 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 (there exist, however, special options that alter this behavior see Writing).
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
practice/folk
practice/jazz
If you were to specify two --verbose (-v) options, tar would have displayed more detail about the extracted files, as shown in the example below:
$ tar -xvvf music.tar practice/folk practice/jazz
-rw-r--r-- me user 28 1996-10-18 16:31 practice/jazz
-rw-r--r-- me user 20 1996-09-23 16:44 practice/folk
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.
Extracting files from archives can overwrite files that already exist. If you receive an archive from an untrusted source, you should make a new directory and extract into that directory, so that you don't have to worry about the extraction overwriting one of your existing files. For example, if untrusted.tar came from somewhere else on the Internet, and you don't necessarily trust its contents, you can extract it as follows:
$ mkdir newdir
$ cd newdir
$ tar -xvf ../untrusted.tar
It is also a good practice to examine contents of the archive before extracting it, using --list (-t) option, possibly combined with --verbose (-v).
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
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.
This chapter is about how one invokes the GNU tar command, from the command synopsis (see Synopsis). There are numerous options, and many styles for writing them. One mandatory option specifies the operation tar should perform (see Operation Summary), other options are meant to detail how this operation should be performed (see Option Summary). Non-option arguments are not always interpreted the same way, depending on what the operation is.
You will find in this chapter everything about option styles and rules for writing them (see Styles). On the other hand, operations and options are fully described elsewhere, in other chapters. Here, you will find only synthetic descriptions for operations and options, together with pointers to other parts of the tar manual.
Some options are so special they are fully described right in this chapter. They have the effect of inhibiting the normal operation of tar or else, they globally alter the amount of feedback the user receives about what is going on. These are the --help and --version (see help), --verbose (see verbose) and --interactive options (see interactive).
The GNU tar program is invoked as either one of:
tar option... [name]...
tar letter... [argument]... [option]... [name]...
The second form is for when old options are being used.
You can use tar to store files in an archive, to extract them from an archive, and to do other types of archive manipulation. The primary argument to tar, which is called the operation, specifies which action to take. The other arguments to tar are either options, which change the way tar performs an operation, or file names or archive members, which specify the files or members tar is to act on.
You can actually type in arguments in any order, even if in this manual the options always precede the other arguments, to make examples easier to understand. Further, the option stating the main operation mode (the tar main command) is usually given first.
Each name in the synopsis above is interpreted as an archive member name when the main command is one of --compare (--diff, -d), --delete, --extract (--get, -x), --list (-t) or --update (-u). When naming archive members, you must give the exact name of the member in the archive, as it is printed by --list. For --append (-r) and --create (-c), these name arguments specify the names of either files or directory hierarchies to place in the archive. These files or hierarchies should already exist in the file system, prior to the execution of the tar command.
tar interprets relative file names as being relative to the working directory. tar will make all file names relative (by removing leading slashes when archiving or restoring files), unless you specify otherwise (using the --absolute-names option). See absolute, for more information about --absolute-names.
If you give the name of a directory as either a file name or a member name, then tar acts recursively on all the files and directories beneath that directory. For example, the name / identifies all the files in the file system to tar.
The distinction between file names and archive member names is especially important when shell globbing is used, and sometimes a source of confusion for newcomers. See Wildcards, for more information about globbing. The problem is that shells may only glob using existing files in the file system. Only tar itself may glob on archive members, so when needed, you must ensure that wildcard characters reach tar without being interpreted by the shell first. Using a backslash before ‘*’ or ‘?’, or putting the whole argument between quotes, is usually sufficient for this.
Even if names are often specified on the command line, they can also be read from a text file in the file system, using the --files-from=file-of-names (-T file-of-names) option.
If you don't use any file name arguments, --append (-r), --delete and --concatenate (--catenate, -A) will do nothing, while --create (-c) will usually yield a diagnostic and inhibit tar execution. The other operations of tar (--list, --extract, --compare, and --update) will act on the entire contents of the archive.
Besides successful exits, GNU tar may fail for
many reasons. Some reasons correspond to bad usage, that is, when the
tar command is improperly written. Errors may be
encountered later, while encountering an error processing the archive
or the files. Some errors are recoverable, in which case the failure
is delayed until tar has completed all its work. Some
errors are such that it would not meaningful, or at least risky, to
continue processing: tar then aborts processing immediately.
All abnormal exits, whether immediate or delayed, should always be
clearly diagnosed on stderr, after a line stating the nature of
the error.
GNU tar returns only a few exit statuses. I'm really aiming simplicity in that area, for now. If you are not using the --compare --diff, -d) option, zero means that everything went well, besides maybe innocuous warnings. Nonzero means that something went wrong. Right now, as of today, “nonzero” is almost always 2, except for remote operations, where it may be 128.
GNU tar has a total of eight operating modes which allow you to perform a variety of tasks. You are required to choose one operating mode each time you employ the tar program by specifying one, and only one operation as an argument to the tar command (two lists of four operations each may be found at frequent operations and Operations). Depending on circumstances, you may also wish to customize how the chosen operating mode behaves. For example, you may wish to change the way the output looks, or the format of the files that you wish to archive may require you to do something special in order to make the archive look right.
You can customize and control tar's performance by running tar with one or more options (such as --verbose (-v), which we used in the tutorial). As we said in the tutorial, options are arguments to tar which are (as their name suggests) optional. Depending on the operating mode, you may specify one or more options. Different options will have different effects, but in general they all change details of the operation, such as archive format, archive name, or level of user interaction. Some options make sense with all operating modes, while others are meaningful only with particular modes. You will likely use some options frequently, while you will only use others infrequently, or not at all. (A full list of options is available in see All Options.)
The TAR_OPTIONS environment variable specifies default options to
be placed in front of any explicit options. For example, if
TAR_OPTIONS is ‘-v --unlink-first’, tar behaves as
if the two options -v and --unlink-first had been
specified before any explicit options. Option specifications are
separated by whitespace. A backslash escapes the next character, so it
can be used to specify an option containing whitespace or a backslash.
Note that tar options are case sensitive. For example, the options -T and -t are different; the first requires an argument for stating the name of a file providing a list of names, while the second does not require an argument and is another way to write --list (-t).
In addition to the eight operations, there are many options to tar, and three different styles for writing both: long (mnemonic) form, short form, and old style. These styles are discussed below. Both the options and the operations can be written in any of these three styles.
There are three styles for writing operations and options to the command line invoking tar. The different styles were developed at different times during the history of tar. These styles will be presented below, from the most recent to the oldest.
Some options must take an argument. (For example, --file (-f)) takes the name of an archive file as an argument. If you do not supply an archive file name, tar will use a default, but this can be confusing; thus, we recommend that you always supply a specific archive file name.) Where you place the arguments generally depends on which style of options you choose. We will detail specific information relevant to each option style in the sections on the different option styles, below. The differences are subtle, yet can often be very important; incorrect option placement can cause you to overwrite a number of important files. We urge you to note these differences, and only use the option style(s) which makes the most sense to you until you feel comfortable with the others.
Some options may take an argument (currently, there are two such options: --backup and --occurrence). Such options may have at most long and short forms, they do not have old style equivalent. The rules for specifying an argument for such options are stricter than those for specifying mandatory arguments. Please, pay special attention to them.
Each option has at least one long (or mnemonic) name starting with two dashes in a row, e.g., --list. The long names are more clear than their corresponding short or old names. It sometimes happens that a single mnemonic option has many different different names which are synonymous, such as --compare and --diff. In addition, long option names can be given unique abbreviations. For example, --cre can be used in place of --create because there is no other mnemonic option which begins with ‘cre’. (One way to find this out is by trying it and seeing what happens; if a particular abbreviation could represent more than one option, tar will tell you that that abbreviation is ambiguous and you'll know that that abbreviation won't work. You may also choose to run ‘tar --help’ to see a list of options. Be aware that if you run tar with a unique abbreviation for the long name of an option you didn't want to use, you are stuck; tar will perform the command as ordered.)
Mnemonic options are meant to be obvious and easy to remember, and their meanings are generally easier to discern than those of their corresponding short options (see below). For example:
$ tar --create --verbose --blocking-factor=20 --file=/dev/rmt0
gives a fairly good set of hints about what the command does, even for those not fully acquainted with tar.
Mnemonic options which require arguments take those arguments immediately following the option name. There are two ways of specifying a mandatory argument. It can be separated from the option name either by an equal sign, or by any amount of white space characters. For example, the --file option (which tells the name of the tar archive) is given a file such as archive.tar as argument by using any of the following notations: --file=archive.tar or --file archive.tar.
In contrast, optional arguments must always be introduced using an equal sign. For example, the --backup option takes an optional argument specifying backup type. It must be used as --backup=backup-type.
Most options also have a short option name. Short options start with a single dash, and are followed by a single character, e.g., -t (which is equivalent to --list). The forms are absolutely identical in function; they are interchangeable.
The short option names are faster to type than long option names.
Short options which require arguments take their arguments immediately following the option, usually separated by white space. It is also possible to stick the argument right after the short option name, using no intervening space. For example, you might write -f archive.tar or -farchive.tar instead of using --file=archive.tar. Both --file=archive-name and -f archive-name denote the option which indicates a specific archive, here named archive.tar.
Short options which take optional arguments take their arguments immediately following the option letter, without any intervening white space characters.
Short options' letters may be clumped together, but you are not required to do this (as compared to old options; see below). When short options are clumped as a set, use one (single) dash for them all, e.g., ‘tar -cvf’. Only the last option in such a set is allowed to have an argument1.
When the options are separated, the argument for each option which requires an argument directly follows that option, as is usual for Unix programs. For example:
$ tar -c -v -b 20 -f /dev/rmt0
If you reorder short options' locations, be sure to move any arguments that belong to them. If you do not move the arguments properly, you may end up overwriting files.
Like short options, old options are single letters. However, old options must be written together as a single clumped set, without spaces separating them or dashes preceding them2. This set of letters must be the first to appear on the command line, after the tar program name and some white space; old options cannot appear anywhere else. The letter of an old option is exactly the same letter as the corresponding short option. For example, the old option ‘t’ is the same as the short option -t, and consequently, the same as the mnemonic option --list. So for example, the command ‘tar cv’ specifies the option -v in addition to the operation -c.
When options that need arguments are given together with the command, all the associated arguments follow, in the same order as the options. Thus, the example given previously could also be written in the old style as follows:
$ tar cvbf 20 /dev/rmt0
Here, ‘20’ is the argument of -b and ‘/dev/rmt0’ is the argument of -f.
On the other hand, this old style syntax makes it difficult to match option letters with their corresponding arguments, and is often confusing. In the command ‘tar cvbf 20 /dev/rmt0’, for example, ‘20’ is the argument for -b, ‘/dev/rmt0’ is the argument for -f, and -v does not have a corresponding argument. Even using short options like in ‘tar -c -v -b 20 -f /dev/rmt0’ is clearer, putting all arguments next to the option they pertain to.
If you want to reorder the letters in the old option argument, be sure to reorder any corresponding argument appropriately.
This old way of writing tar options can surprise even experienced users. For example, the two commands:
tar cfz archive.tar.gz file
tar -cfz archive.tar.gz file
are quite different. The first example uses archive.tar.gz as the value for option ‘f’ and recognizes the option ‘z’. The second example, however, uses z as the value for option ‘f’ — probably not what was intended.
Old options are kept for compatibility with old versions of tar.
This second example could be corrected in many ways, among which the following are equivalent:
tar -czf archive.tar.gz file
tar -cf archive.tar.gz -z file
tar cf archive.tar.gz -z file
As far as we know, all tar programs, GNU and non-GNU, support old options. GNU tar supports them not only for historical reasons, but also because many people are used to them. For compatibility with Unix tar, the first argument is always treated as containing command and option letters even if it doesn't start with ‘-’. Thus, ‘tar c’ is equivalent to ‘tar -c’: both of them specify the --create (-c) command to create an archive.
All three styles may be intermixed in a single tar command, so long as the rules for each style are fully respected3. Old style options and either of the modern styles of options may be mixed within a single tar command. However, old style options must be introduced as the first arguments only, following the rule for old options (old options must appear directly after the tar command and some white space). Modern options may be given only after all arguments to the old options have been collected. If this rule is not respected, a modern option might be falsely interpreted as the value of the argument to one of the old style options.
For example, all the following commands are wholly equivalent, and illustrate the many combinations and orderings of option styles.
tar --create --file=archive.tar
tar --create -f archive.tar
tar --create -farchive.tar
tar --file=archive.tar --create
tar --file=archive.tar -c
tar -c --file=archive.tar
tar -c -f archive.tar
tar -c -farchive.tar
tar -cf archive.tar
tar -cfarchive.tar
tar -f archive.tar --create
tar -f archive.tar -c
tar -farchive.tar --create
tar -farchive.tar -c
tar c --file=archive.tar
tar c -f archive.tar
tar c -farchive.tar
tar cf archive.tar
tar f archive.tar --create
tar f archive.tar -c
tar fc archive.tar
On the other hand, the following commands are not equivalent to the previous set:
tar -f -c archive.tar
tar -fc archive.tar
tar -fcarchive.tar
tar -farchive.tarc
tar cfarchive.tar
These last examples mean something completely different from what the user intended (judging based on the example in the previous set which uses long options, whose intent is therefore very clear). The first four specify that the tar archive would be a file named -c, ‘c’, ‘carchive.tar’ or ‘archive.tarc’, respectively. The first two examples also specify a single non-option, name argument having the value ‘archive.tar’. The last example contains only old style option letters (repeating option ‘c’ twice), not all of which are meaningful (eg., ‘.’, ‘h’, or ‘i’), with no argument value.
The coming manual sections contain an alphabetical listing of all tar operations and options, with brief descriptions and cross references to more in-depth explanations in the body of the manual. They also contain an alphabetically arranged table of the short option forms with their corresponding long option. You can use this table as a reference for deciphering tar commands in scripts.
--atime-preserve=replace remembers the access time of a file before reading it, and then restores the access time afterwards. This may cause problems if other programs are reading the file at the same time, as the times of their accesses will be lost. On most platforms restoring the access time also requires tar to restore the data modification time too, so this option may also cause problems if other programs are writing the file at the same time. (Tar attempts to detect this situation, but cannot do so reliably due to race conditions.) Worse, on most platforms restoring the access time also updates the status change time, which means that this option is incompatible with incremental backups.
--atime-preserve=system avoids changing time stamps on files,
without interfering with time stamp updates
caused by other programs, so it works better with incremental backups.
However, it requires a special O_NOATIME option from the
underlying operating and file system implementation, and it also requires
that searching directories does not update their access times. As of
this writing (November 2005) this works only with Linux, and only with
Linux kernels 2.6.8 and later. Worse, there is currently no reliable
way to know whether this feature actually works. Sometimes
tar knows that it does not work, and if you use
--atime-preserve=system then tar complains and
exits right away. But other times tar might think that the
option works when it actually does not.
Currently --atime-preserve with no operand defaults to --atime-preserve=replace, but this may change in the future as support for --atime-preserve=system improves.
If your operating system does not support --atime-preserve=syst