Written to go into a hypertext info. file. Somewhat redundant in plain format.

The GNU tar Manual

Copyright (C) 1992 Free Software Foundation, Inc.

DRAFT!


Introduction:The GNU Tape Archiver

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 Functions of Arguments

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.

Creating Archives

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.

Creating Archives of Files

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,

  1. Create a new archive ("tar -c" or "tar +create")
  2. Explicitly name the archive file being created ("-f archive-name" or "+file=archive-name"). If you don't use this option, tar will write the archive to the default storage device, which varies from system to system.

    tar interprets archive file names relative to the working directory. Make sure you have write access to the working directory before using tar.

  3. Specify which files to put into the archive (tar interprets file names relative to the working directory). If you don't use any file-name arguments, tar will archive everything in the working directory.

Type:

% tar +create +file=records blues folk jazz 

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

% ls
blues folk jazz records
%

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.

Creating an Archive of a Subdirectory

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

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.

Extracting Specific Files

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

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

First, change into the "practice" directory. Then,

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

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

% ls 
folk
jazz
records
blues
%

Extracting Directories

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

In a previous example, you stored the directory ~/practice in the archive file ~/music. If you delete the contents of ~/practice, you can restore them using 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 practice
Now, list the contents of practice again:
% ls 
practice
What 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.)

Listing the Contents of an Archive

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


The rest of this document is in the original Techinfo, not HTML. Techinfo was an Emacs based publishing system that automatically produced printable LaTex files as well as on-line hypertext trees. The user interface sucked. Draw your own conclusions.


@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/records
When 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
% 
@node Comparing Directories, , , @subsubsection Using Compare on Directories In addition to using "+compare} to compare text files, you can use "+compare} to compare directories. To illustrate this, re-create the examples above using your home directory as the working directory, and using the archive file @file{~/music} instead of the archive file @file{~/practice/records}. First, change into your home directory ("cd ~}). Then, try the above example using @file{music} as the specified archive file, and @file{practice} as a file-name argument.
% 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. @node Append, Update, Adding to Archives, Adding to Archives @subsection Appending Files to an Archive The simplest method of adding a file to an existing archive is the "+add-file}, "-r} or "+append} operation, which writes files into the archive without regard to whether or not they are already archive members. When you use "+add-file} you must use file-name arguments; there is no default. If you specify a file that is already stored in the archive, tar adds another copy of the file to the archive. If you have been following the previous examples, you should have a text file called @file{~/practice/rock} which has not been stored in either the archive file @file{~/practice/records}, or the archive file @file{~/music}. To add @file{rock} to @file{records}, first make @file{practice} the working directory ("cd practice}). Then: @itemize @bullet @item Invoke tar and specify the "+add-file} operation ("+add-file}, "-r} or "+append}) @item Specify the archive to which the file will be added ("+file=@var{archive-name}} or "-f @var{archive-name}}) @item Specify the files to be added to the archive, using file-name arguments @end itemize @noindent For example:
% 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. <<>> @node Update, , Append, Adding to Archives @subsection Updating Files in an Archive To keep archive members up to date with their counterparts of the same name in the file system, use the "+update} or "-u} operation. "tar +update} adds a specified file to an archive if no file of that name is already stored in the archive. If there is already an archive member with the same name, tar checks the modification date of the archive member, and adds the file only if its modification date is later. If a file is stored in the archive but no longer exists under the same name in the active file system, tar reports an error. You could use the "+add-file} option to keep an archive current, but do so you would either have to use the "+compare} and "+list} options to determine what files needed to be re-archived (which could waste a lot of time), or you would have to be willing to add identical copies of already archived files to the archive (which could waste a lot of space). You must use file-name arguments with the "+update} operation---if you don't specify any files, tar won't act on any files. To see the "+update} option at work, create a new file, @file{~/practice/classical}, and modify the file @file{~/practice/blues} (you can use a text editor, such as Emacs, to do both these things). Then, with @file{practice} as your working directory, invoke "tar +update} using the names of all the files in the practice directory as file-name arguments, and specifying the "+verbose} option:
% 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. <<>> In earlier examples, you stored the @file{~/practice} directory in an archive file, @file{~/music}. If you have been following the examples, you have since changed the contents of the @file{~/practice} directory. There is a current version of the files in the @file{practice} directory, however, stored in the archive file @file{~/practice/records}. To store current versions of the files in @file{practice} in the archive file @file{music}, you can use "tar +concatenate} to add the archive file @file{~/practice/records} to @file{music}. First, make sure you are in your home directory ("cd ~}). Then: @itemize @bullet @item Invoke tar, and specify the "+concatenate} operation ("-A} or "+concatenate}) @item Specify the archive file to be added to ("+file=@var{archive-name}} or "-f @var{archive-name}}) @item Specify the archives to be added, using file-name arguments. In this case, the file-name arguments are, unusually, the names of archive files. (Remember to include the path in the archive name, if the archive file is not in your working directory.) @end itemize
% cd ~
% tar +concatenate +file=music practice/records
If 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
% 
@node Listing Files, Verbose, Creating Example, Creating Example @subsubsection Listing files in an archive You can list the contents of an archive with another operation of tar---"+list} or "-l}. To list the contents of the archive you just created, type:
% 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.