You can use tar to create an archive---a single file which contains other files' contents as well as a listing of those files' characteristics. You can also use tar to read, add to, or manipulate already existing archives. Because an archive created by tar is capable of preserving file information and directory structure, tar is ideal for performing full and incremental backups, as well as for transferring groups of files between disks and over networks.
Despite the utility's name, which comes from the words T(ape)
AR(chiver), tar's output can be directed to any available
device. For instance, tar archives can be stored in a file
or sent to another program via a pipe.
How To Use tar
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, which specify the files tar is to act on. The typical tar command line syntax is:
tar operation [options...] [file-names...]
Note: You can actually type in arguments in any order. In this manual the operation is always first, the options second and the file-name arguments last, to make examples easier to understand.
The primary argument to tar is the operation, which specifies what tar does. tar can be used to:
Option arguments to tar change details of the operation, such as archive format, archive name, or level of user interaction. You can specify more than one option. All options are optional.
File-name arguments specify which files (including directory files) to archive, extract, delete or otherwise operate on.
If you don't use any file-name arguments, +add-file, +update and +delete will do nothing. The other operations of tar will act on defaults. <<<which have not yet been decided on>>>
When you use a file-name argument to specify a directory file,
tar acts on all the files in that directory, including
sub-directories.
The Forms of Arguments
Most operations of tar have a single letter form (a single letter preceded by a "-"), and at least one mnemonic form (a word or abbreviation preceded by a "+"). The forms are identical in function. For example, you can use either "tar -t" or "tar +list" to list the contents of an archive
Options, like operations, have both single letter and mnemonic forms. Options, however, may also incorporate an argument of their own. Single letter options are separated from their arguments by a space. Mnemonic options are separated from their arguments by an "=" sign. For example, to create an an archive file named "george", use either "tar +create +file=george" or "tar +create -f george". Both "+file=archive-name" and "-f archive-name" denote the option to give the archive a non-default name, which in the example is "george".
You can mix single letter and mnemonic forms in the same command. You could type the above example as "tar -c +file=george" or "tar +create -f george". However, tar operations and options are case sensitive. You would not type the above example as "tar -C +file=george", because "-C" is an option that causes tar to change directories, not an operation that creates an archive.
File-name arguments are the names of files (including directories). These names can be specified on the command line or read from a text file in the file system (using the "+files-from" option). Files stored in an archive are called archive members. The operations +delete, +extract, +list, +compare and +update take the names of archive members as file-name arguments. The other operations take the names of files in the file system.
tar interprets relative file names as being relative to the
working directory. tar will make all file names relative (by
removing leading "/"s when archiving or restoring files), unless
you specify otherwise (using the +absolute-paths option).
An Old, but Still Supported, Syntax for tar Commands
For historical reasons, GNU tar also accepts a syntax for commands which splits options that include arguments into two parts. That syntax is of the form:
tar operation [option-letters...] [option-arguments...] [file-names...]
where arguments to the options appear in the same order as the letters to which they correspond, and the operation and all the option letters appear as a single argument, without separating spaces.
This command syntax is useful because it lets you type the single letter forms of the operation and options as a single argument to tar, without writing preceding "-"s or inserting spaces between letters. "tar cv" or "tar -cv" are equivalent to "tar -c -v".
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. The modern
syntax--- "tar -c -v -b 20 -f /dev/rmt0" ---is clearer.
Tutorial:Getting Started With tar
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.
To create a new archive, use "tar +create" (or "tar -c"). 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.
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,
tar interprets archive file names relative to the working directory. Make sure you have write access to the working directory before using tar.
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 %
Note: Including the +verbose option in a command to tar will cause tar to print out the names of the files it is acting on. We will include +verbose in subsequent examples to make the explanations clearer, though it is not necessary to the operations being performed.
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.
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" or "-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.
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,
% 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 %
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 tar. First, change into the practice subdirectory (cd ~/practice). Then, remove all the files in ~/practice (rm *). If you list the contents of the directory, you should now see that it is empty:
% ls %
Let's try to restore the contents of practice by extracting them from the archive file ~/music. Type:
% tar +extract +file=~/music practiceNow, list the contents of practice again:
% ls practiceWhat happened to the files? When you created ~/music, your working directory was your home directory. When you extracted ~/music, your working directory was ~/practice. tar stored the files in practice relative to your home directory, and then extracted them relative to ~/practice. The files are now in a new subdirectory, called ~/practice/practice. To restore your files to their old positions, delete the new directory and its contents, and then redo the example above with your home directory as the working directory:
% rm ~/practice/practice/* % rmdir practice % cd .. % tar +extract +file=music practice
(tar will report that it is unable to create the directory ~/practice because it already exists. This will not effect the extraction of the other archive members.)
Use "+list" or "-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 with the +verbose option to print archive members' attributes (owner, size, etc.).
@node Listing names, Additional File Info, Listing Archive Contents, Listing Archive Contents @subsection Listing the names of stored files To list the names of files stored in an archive, use the "+list} operation of tar. In a previous example, you created the archive @file{~/music}. To list the contents of @file{music}, while in your home directory: @itemize @bullet @item List the contents of an archive ("tar -t} or "tar +list}) @item Specify the archive to be listed ("-f @var{archive-name}} or "+file=@var{archive-name}}) @refill @end itemize Thus:
% tar +list +file=music practice/ practice/blues practice/folk practice/jazz practice/records@node Additional File Info, Specific File, Listing names, Listing Archive Contents @subsection Listing Additional File Information To get more information when you list the names of files stored in an archive, specify the "+verbose} option in conjunction with "tar +list}. tar will print archive member's file protection, owner and group ID, size, and date and time of creation. For example:
% 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 when you use "+verbose} with "+list}, tar doesn't print the names of files as they are being acted on, though the "+verbose} option will have this effect when used with all other operations. @node Specific File, Comparing Files, Additional File Info, Listing Archive Contents @subsection List A Specific File in an Archive 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} operation. For example, to see whether the file @file{folk} is in the archive file @file{music}, do the following: @itemize @bullet @item Invoke tar, and specify the "+list} operation ("+list} or "-t}). @item Specify the archive file to be acted on ("+file @var{archive-name}} or "-f @var{archive-name}}). @item 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). <<< xref absolute-paths -ringo @end itemize Type:
% tar +list +file=music practice/folk@noindent tar responds:
practice/folk@noindent If the file were not stored in the archive (for example, the file @file{practice/rock}), the example above would look like:
% tar +list +file=music practice/rock tar: practice/rock not found in archive@noindent If you had used "+verbose} 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@node Listing Directories, , , @subsection 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}. To find out file attributes, include the "+verbose} option. For example, to find out about files in the directory @file{practice}, in the archive file @file{music}, type:
% tar +list +file=music practice@noindent 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/recordsWhen you use a directory name as a file-name argument, tar acts on all the files (including sub-directories) in that directory. @node Comparing Files, , , @section Comparing Files in an Archive with Files in the File System To compare the attributes of archive members with the attributes of their counterparts in the file system, use the "+compare}, "+diff}, or "-d}) operation. While you could use "+list +verbose} to manually compare some file attributes, it is simpler to have tar itself compare file attributes and report back on file differences. <<<"manually"? suggestions? -ringo The "+compare} 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 "tar +compare} a file-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 @file{records} with files in the @file{~/practice} directory, first change into the @file{practice} directory. Then: @itemize @bullet @item Invoke tar and specify the "+compare} operation. ("+compare}, "+diff}, or "-d}). @item Specify the archive where the files to be compared are stored ("+file=@var{archive-name}} or "-f @var{archive-name}}) @item 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). @end itemize
% tar +compare +file=records %@noindent While it looks like nothing has happened, tar has, in fact, done the comparison---and found nothing to report. Use the "+verbose} 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 %@noindent If tar had had anything to report, it would have done so as it was comparing each file. If you remove the file @file{jazz} from the file system ("rm jazz}), and modify the file @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 "tar +compare} reports the names of archive members that do not have counterparts in the file system, "tar +compare} ignores files in the file system that do not have counterparts in the archive. To demonstrate this, create a file in the @file{practice} directory called @file{rock} (using any text editor). The new file appears when you list the directory's contents:
% ls blues folk records rock@noindent If you type the "+compare} example again, tar prints the following:
% tar +compare +verbose +file=records blues blues: mod time differs blues: size differs folk jazz jazz: does not exist %@noindent tar ignores the file @file{rock} because tar is comparing archive members to files in the file system, not vice versa. If you specify @file{rock} explicitly (using a file-name argument), tar prints an error message:
% tar +compare +verbose +file=records rock tar: rock not found in archive %
% tar +compare +verbose +file=music practice@noindent 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@node Adding to Archives, Concatenate, Listing Archive Contents, Tutorial @section Adding Files to Existing Archives While you can use tar to create a new archive every time you want to store a file, it is more sometimes efficient to add files to an existing archive. To add new files to an existing archive, use the "+add-file}, "+append} or "-r} operation. To add newer versions of archive members to an archive, use the "+update} or "-u} operation.
% tar +add-file +file=records rock@noindent If you list the archive members in @file{records}, you will see that @file{rock} has been added to the archive:
% tar +list +file=records blues folk jazz rock<<< this should be some kind of node. You can use "+add-file} to keep archive members current with active files. Because "+add-file} stores a file whether or not there is already an archive member with the same file name, you can use "+add-file} to add newer versions of archive members to an archive. When you extract the file, only the version stored last will wind up in the file system. Because "tar +extract} extracts files from an archive in sequence, and overwrites files with the same name in the file system, if a file name appears more than once in an archive the last version of the file will overwrite the previous versions which have just been extracted. If you recall from the examples using "+compare} above, @file{blues} was changed after the archive @file{records} was created. It is simple, however, to use "+add-file} to add the new version of @file{blues} to @file{records}:
% tar +add-file +verbose +file=records blues blues@noindent If you now list the contents of the archive, you will obtain the following:
% tar +list -f records blues folk jazz rock blues@noindent The newest version of @file{blues} is at the end of the archive. When the files in @file{records} are extracted, the newer version of @file{blues} (which has the same name as the older) will overwrite the version stored first. When "tar +extract} is finished, only the newer version of @file{blues} is in the file system. <<
% tar +update +verbose +file=records blues folk rock classical blues classical %@noindent Because you specified verbose mode, tar printed out the names of the files it acted on. If you now list the archive members of the archive, ("tar +list +file=records}), you will see that the file @file{classical} and another version of the file @file{blues} have been added to @file{records}. Note: When you update an archive, tar does not overwrite old archive members when it stores newer versions of a file. This is because archive members appear in an archive in the order in which they are stored, and some archive devices do not allow writing in the middle of an archive. @node Concatenate, Extracting Files Example, Adding to Archives, Tutorial @comment node-name, next, previous, up @section Concatenating Archives To concatenate archive files, use "tar +concatenate} or "tar -A}. This operation adds other archives to the end of an archive. While it may seem intuitive to concatenate archives using @pre{cat}, the utility for adding files together, archive files which have been "catted" together cannot be read properly by tar. Archive files incorporate an end of file marker---if archives are concatenated using @pre{cat}, this marker will appear before the end of the new archive. This will interfere with operations on that archive. <<
% cd ~ % tar +concatenate +file=music practice/recordsIf you now list the contents of the @file{music}, you see it now contains the archive members of @file{practice/records}:
%tar +list +file=music blues folk jazz rock blues practice/blues practice/folk practice/jazz practice/rock practice/blues practice/classical@node Deleting Files, , , Tutorial @comment node-name, next, previous, up @section Deleting Files From an Archive In some instances, you may want to remove some files from an archive stored on disk @quotation @emph{Caution:} you should never delete files from an archive stored on tape---because of the linear nature of tape storage, doing this is likely to scramble the archive. @end quotation To remove archive members from an archive, use the "+delete} operation. You must specify the names of files to be removed as file-name arguments. All versions of the named file are removed from the archive. Execution of the "+delete} operation can be very slow. To delete all versions of the file @file{blues} from the archive @file{records} in the @file{practice} directory, make sure you are in that directory, and then: @itemize @bullet @item List the contents of the archive file @file{records} (see above for the steps involved) to insure that the file(s) you wish to delete are stored in the archive. (This step is optional) @item Invoke tar and specify the "+delete} operation ("+delete}). @item Specify the name of the archive file that the file(s) will be deleted from ("+file=@var{archive-name}} or "-f @var{archive-name}}) @item Specify the files to be deleted, using file-name arguments. @item List the contents of the archive file again---note that the files have been removed. (this step is also optional) @end itemize
% tar +list +file=records blues folk jazz % tar +delete +file=records blues % tar +list +file=records folk jazz %
% tar +list +file=records@noindent tar will respond:
blues folk jazz@xref{Listing Archive Contents}, for a more detailed tutorial of the "+list} operation. @xref{Listing Contents}, for more information about the "+list} operation. @node Verbose, , Listing Files, Creating Example @subsubsection Using tar in Verbose Mode If you include the "+verbose} or "-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: @cindex Verbose mode example @findex -v (verbose mode example)
% tar +create +file=records +verbose blues folk jazz blues folk jazz@noindent 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.