GNU Tar GNU Tar: An Archiver Tool FTP Release,

8/14/2019 GNU Tar GNU Tar: An Archiver Tool FTP Release,

1/230

GNU tar


2/230


3/230

GNU tar: an archiver toolFTP release, version 1.21, 30 October 2008

John Gilmore, Jay Fenlason et al.


4/230

This manual is or GNU tar (version 1.21, 30 October 2008), which createsand extracts les rom archives.

Copyright c 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003, 2004,2005, 2006, 2007, 2008 Free Sotware Foundation, Inc.

Permission is granted to copy, distribute and/or modiy this doc-ument under the terms o the GNU Free Documentation License,Version 1.1 or any later version published by the Free SotwareFoundation; with no Invariant Sections, with the Front-Cover Textsbeing A GNU Manual, and with the Back-Cover Texts as in (a)below. A copy o the license is included in the section entitled"GNU Free Documentation License".

(a) The FSFs Back-Cover Text is: You have the reedom to copyand modiy this GNU manual. Buying copies rom the FSF sup-ports it in developing GNU and promoting sotware reedom.


5/230

Chapter 1: Introduction 1

1 Introduction

GNU tar creates and manipulates archives which are actually collectionso many other les; the program provides users with an organized and sys-

tematic method or controlling a large amount o data. The name taroriginally came rom the phrase Tape ARchive, but archives need not(and these days, typically do not) reside on tapes.

1.1 What this Book Contains

The rst part o this chapter introduces you to various terms that will recurthroughout the book. It also tells you who has worked on GNU tar and itsdocumentation, and where you should send bug reports or comments.

The second chapter is a tutorial (see Chapter 2 [Tutorial], page 5) whichprovides a gentle introduction or people who are new to using tar. It

is meant to be sel contained, not requiring any reading rom subsequentchapters to make sense. It moves rom topic to topic in a logical, progressiveorder, building on inormation already explained.

Although the tutorial is paced and structured to allow beginners to learnhow to use tar, it is not intended solely or beginners. The tutorial explainshow to use the three most requently used operations (create, list, andextract) as well as two requently used options (file and verbose).The other chapters do not reer to the tutorial requently; however, i a sec-tion discusses something which is a complex variant o a basic concept, theremay be a cross reerence to that basic concept. (The entire book, including

the tutorial, assumes that the reader understands some basic concepts ousing a Unix-type operating system; see Chapter 2 [Tutorial], page 5.)

The third chapter presents the remaining ve operations, and inormationabout using tar options and option syntax.

The other chapters are meant to be used as a reerence. Each chapterpresents everything that needs to be said about a specic topic.

One o the chapters (see Chapter 7 [Date input ormats], page 117) ex-ists in its entirety in other GNU manuals, and is mostly sel-contained. Inaddition, one section o this manual (see [Standard], page 177) contains abig quote which is taken directly rom tar sources.

In general, we give both long and short (abbreviated) option names atleast once in each section where the relevant option is covered, so that novicereaders will become amiliar with both styles. (A ew options have no shortversions, and the relevant sections will indicate this.)

1.2 Some Defnitions

The tar program is used to create and manipulate tar archives. An archiveis a single le which contains the contents o many les, while still iden-tiying the names o the les, their owner(s), and so orth. (In addition,


6/230

2 GNU tar 1.21

archives record access permissions, user and group, size in bytes, and datamodication time. Some archives also record the le names in each archiveddirectory, as well as other le and directory inormation.) You can use tarto create a new archive in a specied directory.

The les inside an archive are called members. Within this manual, weuse the term le to reer only to les accessible in the normal ways (by ls,cat, and so orth), and the term member to reer only to the members o anarchive. Similarly, a le name is the name o a le, as it resides in the lesystem, and a member name is the name o an archive member within thearchive.

The term extraction reers to the process o copying an archive member(or multiple members) into a le in the le system. Extracting all the mem-bers o an archive is oten called extracting the archive. The term unpackcan also be used to reer to the extraction o many or all the members oan archive. Extracting an archive does not destroy the archives structure,

just as creating an archive does not destroy the copies o the les that existoutside o the archive. You may also list the members in a given archive(this is oten thought o as printing them to the standard output, or thecommand line), or append members to a pre-existing archive. All o theseoperations can be perormed using tar.

1.3 What tar Does

The tar program provides the ability to create tar archives, as well as vari-ous other kinds o manipulation. For example, you can use tar on previously

created archives to extract les, to store additional les, or to update or listles which were already stored.

Initially, tar archives were used to store les conveniently on magnetictape. The name tar comes rom this use; it stands or tape archiver. Despitethe utilitys name, tar can direct its output to available devices, les, orother programs (using pipes). tar may even access remote devices or les(as archives).

You can use tar archives in many ways. We want to stress a ew o them:storage, backup, and transportation.

Storage Oten, tar archives are used to store related les or convenientle transer over a network. For example, the GNU Project dis-tributes its sotware bundled into tar archives, so that all theles relating to a particular program (or set o related programs)can be transerred as a single unit.

A magnetic tape can store several les in sequence. However,the tape has no names or these les; it only knows their relativeposition on the tape. One way to store several les on onetape and retain their names is by creating a tar archive. Evenwhen the basic transer mechanism can keep track o names, as


7/230

Chapter 1: Introduction 3

FTP can, the nuisance o handling multiple les, directories, andmultiple links makes tar archives useul.

Archive les are also used or long-term storage. You can thinko this as transportation rom the present into the uture. (It is a

science-ction idiom that you can move through time as well asin space; the idea here is that tar can be used to move archivesin all dimensions, even time!)

Backup Because the archive created by tar is capable o preserving leinormation and directory structure, tar is commonly used orperorming ull and incremental backups o disks. A backupputs a collection o les (possibly pertaining to many users andprojects) together on a disk or a tape. This guards againstaccidental destruction o the inormation in those les. GNU tarhas special eatures that allow it to be used to make incrementaland ull dumps o all the les in a le system.

TransportationYou can create an archive on one system, transer it to anothersystem, and extract the contents there. This allows you to trans-port a group o les rom one system to another.

1.4 How tar Archives are Named

Conventionally, tar archives are given names ending with .tar. This isnot necessary or tar to operate properly, but this manual ollows that con-vention in order to accustom readers to it and to make examples more clear.

Oten, people reer to tar archives as tar les, and archive members asles or entries. For people amiliar with the operation otar, this causesno diculty. However, in this manual, we consistently reer to archivesand archive members to make learning to use tar easier or novice users.

1.5 GNU tar Authors

GNU tar was originally written by John Gilmore, and modied by manypeople. The GNU enhancements were written by Jay Fenlason, thenJoy Kendall, and the whole package has been urther maintained by

Thomas Bushnell, n/BSG, Francois Pinard, Paul Eggert, and nally SergeyPoznyakof with the help o numerous and kind users.

We wish to stress that tar is a collective work, and owes much to allthose people who reported problems, ofered solutions and other insights,or shared their thoughts and suggestions. An impressive, yet partial listo those contributors can be ound in the THANKS le rom the GNU tardistribution.

Jay Fenlason put together a drat o a GNU tar manual, borrowing notesrom the original man page rom John Gilmore. This was withdrawn inversion 1.11. Thomas Bushnell, n/BSG and Amy Gorin worked on a tutorial


8/230


9/230

Chapter 2: Tutorial Introduction to tar 5

2 Tutorial Introduction to tar

This chapter guides you through some basic examples o three tar opera-

tions: --create, --list, and --extract. I you already know how touse some other version o tar, then you may not need to read this chapter.This chapter omits most complicated details about how tar works.

2.1 Assumptions this Tutorial Makes

This chapter is paced to allow beginners to learn about tar slowly. At thesame time, we will try to cover all the basic aspects o these three operations.In order to accomplish both o these tasks, we have made certain assumptionsabout your knowledge beore reading this manual, and the hardware you will

be using:

Beore you start to work through this tutorial, you should understandwhat the terms archive and archive member mean (see Section 1.2[Denitions], page 1). In addition, you should understand somethingabout how Unix-type operating systems work, and you should knowhow to use some basic utilities. For example, you should know howto create, list, copy, rename, edit, and delete les and directories; howto change between directories; and how to gure out where you are inthe le system. You should have some basic understanding o directorystructure and how les are named according to which directory they

are in. You should understand concepts such as standard output andstandard input, what various denitions o the term argument mean,and the diferences between relative and absolute le names.

This manual assumes that you are working rom your own home di-rectory (unless we state otherwise). In this tutorial, you will create adirectory to practice tar commands in. When we show le names, wewill assume that those names are relative to your home directory. Forexample, my home directory is /home/fsf/melissa. All o my exam-ples are in a subdirectory o the directory named by that le name; thesubdirectory is called practice.

In general, we show examples o archives which exist on (or can bewritten to, or worked with rom) a directory on a hard disk. In mostcases, you could write those archives to, or work with them on any otherdevice, such as a tape drive. However, some o the later examples in thetutorial and next chapter will not work on tape drives. Additionally,working with tapes is much more complicated than working with harddisks. For these reasons, the tutorial does not cover working with tapedrives. See Chapter 9 [Media], page 147, or complete inormation onusing tar archives with tape drives.


10/230


11/230


For more inormation on option syntax, see Section 4.2 [Advanced tar],page 56. In discussions in the text, when we name an option by its longorm, we also give the corresponding short option in parentheses.

The term, option, can be conusing at times, since operations are

oten lumped in with the actual, optional options in certain general classstatements. For example, we just talked about short and long orms ooptions and operations. However, experienced tar users oten reer to theseby shorthand terms such as, short and long options. This term assumesthat the operations are included, also. Context will help you determinewhich denition o options to use.

Similarly, the term command can be conusing, as it is oten used intwo diferent ways. People sometimes reer to tar commands. A tarcommand is the entire command line o user input which tells tar whatto do including the operation, options, and any arguments (le names,pipes, other commands, etc.). However, you will also sometimes hear theterm the tar command. When the word command is used specicallylike this, a person is usually reerring to the tar operation, not the wholeline. Again, use context to gure out which o the meanings the speakerintends.

2.4 The Three Most Frequently Used Operations

Here are the three most requently used operations (both short and longorms), as well as a brie description o their meanings. The rest o thischapter will cover how to use these operations in detail. We will present the

rest o the operations in the next chapter.--create-c Create a new tar archive.

--list-t List the contents o an archive.

--extract-x Extract one or more members rom an archive.

2.5 Two Frequently Used OptionsTo understand how to run tar in the three operating modes listed previously,you also need to understand how to use two o the options to tar: --file(which takes an archive le as an argument) and --verbose. (You areusually not required to speciy either o these options when you run tar, butthey can be very useul in making things more clear and helping you avoiderrors.)

The --file Option


12/230

8 GNU tar 1.21

--file=archive-name -f archive-name

Speciy the name o an archive le.

You can speciy an argument or the --file=archive-name (-f

archive-name ) option whenever you use tar; this option determines thename o the archive le that tar will work on.

I you dont speciy this argument, then tar will examine the environmentvariable TAPE. I it is set, its value will be used as the archive name. Other-wise, tar will use the deault archive, determined at the compile time. Usu-ally it is standard output or some physical tape drive attached to your ma-chine (you can veriy what the deault is by running tar --show-defaults,see Section 3.6 [deaults], page 48). I there is no tape drive attached, or thedeault is not meaningul, then tar will print an error message. The errormessage might look roughly like one o the ollowing:

tar: cant open /dev/rmt8 : No such device or address

tar: cant open /dev/rsmt0 : I/O error

To avoid conusion, we recommend that you always speciy an archive lename by using --file=archive-name (-f archive-name ) when writingyour tar commands. For more inormation on using the --file=archive-name (-f archive-name ) option, see Section 6.1 [le], page 91.

The --verbose Option

--verbose-v Show the les being worked on as tar is running.

--verbose (-v) shows details about the results o running tar. Thiscan be especially useul when the results might not be obvious. For example,i you want to see the progress o tar as it writes les into the archive, youcan use the --verbose option. In the beginning, you may nd it useulto use --verbose at all times; when you are more accustomed to tar, youwill 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 manyexamples both using and not using --verbose to show the diferences.

Each instance o --verbose on the command line increases the verbositylevel by one, so i you need more details on the output, speciy it twice.

When reading archives (--list, --extract, --diff), tar by deaultprints only the names o the members being extracted. Using --verbosewill show a ull, ls style member listing.

In contrast, when writing archives (--create, --append, --update),tar does not print le names by deault. So, a single --verbose optionshows the le names being added to the archive, while two --verboseoptions enable the ull listing.

For example, to create an archive in verbose mode:$ tar -cvf afiles.tar apple angst aspicapple


13/230


angst

aspic

Creating the same archive with the verbosity level 2 could give:$ tar -cvvf afiles.tar apple angst aspic-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple

-rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst

-rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic

This works equally well using short or long orms o options. Using longorms, you would simply write out the mnemonic orm o 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.

The ull output consists o six elds:

File type and permissions in symbolic orm. These are displayed in thesame ormat as the rst column o ls -l output (see Section Verboselisting in GNU le utilities).

Owner name and group separated by a slash character. I these data arenot available (or example, when listing a v7 ormat archive), numericID values are printed instead.

Size o the le, in bytes.

File modication date in ISO 8601 ormat.

File modication time.

File name. I the name contains any special characters (white space,newlines, etc.) these are displayed in an unambiguous orm using socalled quoting style. For the detailed discussion o available styles andon how to use them, see Section 6.6 [quoting styles], page 102.

Depending on the le type, the name can be ollowed by some additionalinormation, described in the ollowing table:

-> link-name The le or archive member is a symbolic link and link-nameis the name o le it links to.

link to link-name The le or archive member is a hard link and link-name isthe name o le it links to.

--Long Link--The archive member is an old GNU ormat long link. Youwill normally not encounter this.

--Long Name--The archive member is an old GNU ormat long name. Youwill normally not encounter this.
http://fileutils.pdf/http://fileutils.pdf/http://fileutils.pdf/http://fileutils.pdf/http://fileutils.pdf/


14/230


15/230


The three les 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 inverbose mode, and showing examples using both short and long orms.

In the rest o the tutorial, and in the examples in the next chapter, we willproceed at a slightly quicker pace. This section moves more slowly to allowbeginning users to understand how tar works.

2.6.1 Preparing a Practice Directory or Examples

To ollow along with this and uture examples, create a new directory calledpractice containing les called blues, folk and jazz. The les cancontain any inormation you like: ideally, they should contain inormationwhich relates to their names, and be o diferent lengths. Our examplesassume that practice is a subdirectory o your home directory.

Now cd to the directory named practice; practice is now your work-ing directory. (Please note: Although the ull le name o this directory is/homedir/practice, in our examples we will reer to this directory aspractice; the homedir is presumed.

In general, you should check that the les to be archived exist where youthink they do (in the working directory) by running ls. Because you justcreated the directory and the les and have changed to that directory, youprobably dont need to do that this time.

It is very important to make sure there isnt already a le in theworking directory with the archive name you intend to use (in this case,

collection.tar

), or that you dont care about its contents. Wheneveryou use create, tar will erase the current contents o the le named by--file=archive-name (-f archive-name ) i it exists. tar will not tellyou i you are about to overwrite an archive unless you speciy an optionwhich does this (see Section 4.5 [backup], page 73, or the inormation onhow to do so). To add les to an existing archive, you need to use a diferentoption, such as --append (-r); see Section 4.2.2 [append], page 57 orinormation on how to do this.

2.6.2 Creating the Archive

To place the les blues, folk, and jazz into an archive namedcollection.tar, use the ollowing command:

$ tar --create --file=collection.tar blues folk jazz

The order o the arguments is not very important, when using long optionorms. 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 whywe will list the arguments in the order that makes the commands easiest tounderstand (and we encourage you to do the same when you use tar, toavoid errors).


16/230

12 GNU tar 1.21

Note that the sequence --file=collection.tar is considered to beone argument. I you substituted any other string o characters orcollection.tar, then that string would become the name o the archivele you create.

The order o the options becomes more important when you begin touse short orms. With short orms, i you type commands in the wrongorder (even i you type them correctly in all other ways), you may end upwith results you dont expect. For this reason, it is a good idea to get intothe habit o typing options in the order that makes inherent sense. SeeSection 2.6.4 [short create], page 13, or more inormation on this.

In this example, you type the command as shown above: --create is theoperation which creates the new archive (collection.tar), and --fileis the option which lets you give it the name you chose. The les, blues,folk, and jazz, are now members o the archive, collection.tar (they

are le name arguments to the --create operation. See Chapter 6 [Choos-ing], page 91, or the detailed discussion on these.) Now that they are inthe archive, they are called archive members, not les. (see Section 1.2[Denitions], page 1).

When you create an archive, you must speciy which les you want placedin the archive. I you do not speciy any archive members, GNU tar willcomplain.

I you now list the contents o the working directory (ls), you will ndthe archive le listed as well as the les you saw previously:

blues folk jazz collection.tar

Creating the archive collection.tar did not destroy the copies o the lesin the directory.

Keep in mind that i you dont indicate an operation, tar will not runand will prompt you or one. I you dont name any les, tar will complain.You must have write access to the working directory, or else you will not beable to create an archive in that directory.

Caution: Do not attempt to use --create (-c) to add les to an ex-isting archive; it will delete the archive and write a new one. Use --append(-r) instead. See Section 4.2.2 [append], page 57.

2.6.3 Running --create with --verbose

I you include the --verbose (-v) option on the command line, tar willlist the les it is acting on as it is working. In verbose mode, the createexample above would appear as:

$ tar --create --verbose --file=collection.tar blues folk jazzblues

folkjazz


17/230


This example is just like the example we showed which did not use--verbose, except that tar generated the remaining lines (note the difer-ent ont styles).

In the rest o the examples in this chapter, we will requently use verbose

mode so we can show actions or tar responses that you would otherwise notsee, and which are important or you to understand.

2.6.4 Short Forms with create

As we said beore, the --create (-c) operation is one o the most basicuses otar, and you will use it countless times. Eventually, you will probablywant to use abbreviated (or short) orms o options. A ull discussiono the three diferent orms that options can take appears in Section 3.3[Styles], page 24; or now, here is what the previous example (including the--verbose (-v) option) looks like using short option orms:

$ tar -cvf collection.tar blues folk jazzblues

folk

jazz

As you can see, the system responds the same no matter whether you uselong or short option orms.

One diference between using short and long option orms is that, al-though the exact placement o arguments ollowing options is no more spe-cic when using short orms, it is easier to become conused and make amistake when using short orms. For example, suppose you attempted the

above example in the ollowing way:$ tar -cfv collection.tar blues folk jazz

In this case, tar will make an archive le called v, containing the lesblues, folk, and jazz, because the v is the closest le name to the-f option, and is thus taken to be the chosen archive le name. tar willtry to add a le called collection.tar to the v archive le; i the lecollection.tar did not already exist, tar will report an error indicatingthat this le does not exist. I the le collection.tar does already exist(e.g., rom a previous command you may have run), then tar will add thisle 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 conused about what happened,

and possibly overwrite a le. To illustrate this urther, we will show youhow an example we showed previously would look using short orms.

This example,

$ tar blues --create folk --file=collection.tar jazz

is conusing as it is. When shown using short orms, however, it becomesmuch more so:

$ tar blues -c folk -f collection.tar jazz


18/230

14 GNU tar 1.21

It would be very easy to put the wrong string o characters immediatelyollowing the -f, but doing that could sacrice valuable data.

For this reason, we recommend that you pay very careul attention tothe order o options and placement o le and archive names, especially

when using short option orms. Not having the option name written outmnemonically can afect how well you remember which option does what,and thereore where diferent names have to be placed.

2.6.5 Archiving Directories

You can archive a directory by speciying its directory name as a le nameargument to tar. The les in the directory will be archived relative to theworking directory, and the directory will be re-created along with its contentswhen the archive is extracted.

To archive a directory, rst move to its superior directory. I you have

ollowed the previous instructions in this tutorial, you should type:$ cd ..$

This will put you into the directory which contains practice, i.e., yourhome directory. Once in the superior directory, you can speciy the subdi-rectory, practice, as a le name argument. To store practice in thenew archive le music.tar, type:

$ tar --create --verbose --file=music.tar practice

tar should output:practice/practice/blues

practice/folkpractice/jazz

practice/collection.tar

Note that the archive thus created is not in the subdirectory practice,but rather in the current working directorythe directory rom which tarwas invoked. Beore trying to archive a directory rom its superior directory,you should make sure you have write access to the superior directory itsel,not only the directory you are trying archive with tar. For example, youwill probably not be able to store your home directory in an archive byinvoking tar rom the root directory; See Section 6.10.2 [absolute], page 114.

(Note also that collection.tar, the original archive le, has itsel beenarchived. tar will accept any le as a le to be archived, regardless o itscontent. When music.tar is extracted, the archive le collection.tarwill be re-written into the le system).

I you give tar a command such as$ tar --create --file=foo.tar .

tar will report tar: ./foo.tar is the archive; not dumped. This hap-pens because tar creates the archive foo.tar in the current directory be-ore putting any les into it. Then, when tar attempts to add all the lesin the directory . to the archive, it notices that the le ./foo.tar is the


19/230


20/230

16 GNU tar 1.21

$ tar cfv archive /etc/mailtar: Removing leading / from member names

/etc/mail//etc/mail/sendmail.cf

/etc/mail/aliases

$ tar tf archiveetc/mail/

etc/mail/sendmail.cfetc/mail/aliases

This deault behavior can sometimes be inconvenient. You can orceGNU tar show member names when creating archive by supplying--show-stored-names option.

--show-stored-namesPrint member (as opposed to fle) names when creating thearchive.

You can speciy one or more individual member names as argumentswhen using list. In this case, tar will only list the names o members youidentiy. For example, tar --list --file=afiles.tar apple would onlyprint apple.

Because tar preserves le names, these must be specied as theyappear in the archive (i.e., relative to the directory rom which thearchive was created). Thereore, it is essential when speciying membernames to tar that you give the exact member names. For example,tar --list --file=bfiles.tar birds would produce an error messagesomething like tar: birds: Not found in archive, because there is no

member named birds, only one named ./birds. While the namesbirds and ./birds name the same le, member names by deault arecompared verbatim.

However, tar --list --file=bfiles.tar baboon would respond withbaboon, because this exact member name is in the archive le bfiles.tar.I you are not sure o the exact le name, use globbing patterns, or example:

$ tar --list --file=bfiles.tar --wildcards *b*

will list all members whose name contains b. See Section 6.5 [wildcards],page 99, or a detailed discussion o globbing patterns and related tar com-mand line options.

Listing the Contents o a Stored Directory

To get inormation about the contents o an archived directory, use thedirectory name as a le name argument in conjunction with --list (-t).To nd out le attributes, include the --verbose (-v) option.

For example, to nd out about les in the directory practice, in thearchive le music.tar, type:

$ tar --list --verbose --file=music.tar practice

tar responds:


21/230


22/230

18 GNU tar 1.21

I you list the les in the directory again, you will see that the le blueshas been restored, with its original permissions, data modication times,and owner.1 (These parameters will be identical to those which the le hadwhen you originally placed it in the archive; any changes you may havemade beore deleting the le rom the le system, however, will not havebeen made to the archive member.) The archive le, collection.tar, isthe same as it was beore you extracted blues. You can conrm this byrunning tar with --list (-t).

Remember that as with other operations, speciying the exact membername is important. tar --extract --file=bfiles.tar birds will ail, be-cause there is no member named birds. To extract the member named./birds, you must speciy tar --extract --file=bfiles.tar ./birds.I you dont remember the exact member names, use --list (-t) op-tion (see Section 2.7 [list], page 15). You can also extract those mem-bers that match a specic globbing pattern. For example, to extract rom

bfiles.tar all les that begin with b, no matter their directory prex,you could type:

$ tar -x -f bfiles.tar --wildcards --no-anchored b*

Here, --wildcards instructs tar to treat command line arguments as glob-bing patterns and --no-anchored inorms it that the patterns apply tomember names ater any / delimiter. The use o globbing patterns is dis-cussed in detail in See Section 6.5 [wildcards], page 99.

You can extract a le to standard output by combining the above optionswith the --to-stdout (-O) option (see [Writing to Standard Output],page 70).

I you give the --verbose option, then --extract will print the nameso the archive members as it extracts them.

2.8.3 Extracting Files that are Directories

Extracting directories which are members o an archive is similar to extract-ing other les. The main diference to be aware o is that i the extracted di-rectory has the same name as any directory already in the working directory,then les in the extracted directory will be placed into the directory o thesame name. Likewise, i there are les in the pre-existing directory with thesame names as the members which you extract, the les rom the extracted

archive will replace the les already in the working directory (and possiblesubdirectories). This will happen regardless o whether or not the les inthe working directory were more recent than those extracted (there exist,however, special options that alter this behavior see Section 4.4.2 [Writing],page 66).

1 This is only accidentally true, but not in general. Whereas modication times arealways restored, in most cases, one has to be root or restoring the owner, and use aspecial option or restoring permissions. Here, it just happens that the restoring useris also the owner o the archived members, and that the current umask is compatiblewith original permissions.


23/230


However, i a le was stored with a directory name as part o its le name,and that directory does not exist under the working directory when the leis extracted, tar will create the directory.

We can demonstrate how to use --extract to extract a directory le

with an example. Change to the practice

directory i you werent there,and remove the les folk and jazz. Then, go back to the parent di-rectory and extract the archive music.tar. You may either extract theentire archive, or you may extract only the les you just deleted. To extractthe entire archive, dont give any le names as arguments ater the archivename music.tar. To extract only the les you deleted, use the ollowingcommand:

$ tar -xvf music.tar practice/folk practice/jazzpractice/folk

practice/jazz

I you were to speciy two --verbose (-v) options, tar would have dis-

played more detail about the extracted les, 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 o the le nameso each o the les by archiving the practice directory as practice, youmust give practice as part o the le names when you extract those lesrom the archive.

2.8.4 Extracting Archives rom Untrusted Sources

Extracting les rom archives can overwrite les that already exist. I youreceive an archive rom an untrusted source, you should make a new di-rectory and extract into that directory, so that you dont have to worryabout the extraction overwriting one o your existing les. For example, iuntrusted.tar came rom somewhere else on the Internet, and you dontnecessarily trust its contents, you can extract it as ollows:

$ mkdir newdir$ cd newdir$ tar -xvf ../untrusted.tar

It is also a good practice to examine contents o the archive beore ex-tracting it, using --list (-t) option, possibly combined with --verbose

(-v).

2.8.5 Commands That Will Fail

Here are some sample commands you might try which will not work, andwhy they wont work.

I you try to use this command,$ tar -xvf music.tar folk jazz

you will get the ollowing response:tar: folk: Not found in archive


24/230

20 GNU tar 1.21

tar: jazz: Not found in archive

$

This is because these les were not originally in the parent directory ..,where the archive is located; they were in the practice directory, and theirle names reect this:

$ tar -tvf music.tarpractice/folkpractice/jazz

practice/rock

Likewise, i 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 thearchive. You must use the correct member names, or wildcards, in order toextract the les rom the archive.

I you have orgotten the correct names o the les in the archive, use

tar --list --verbose to list them correctly.

2.9 Going Further Ahead in this Manual

(This message will disappear, once this node revised.)


25/230

Chapter 3: Invoking GNU tar 21

3 Invoking GNU tar


This chapter is about how one invokes the GNU tar command, rom the

command synopsis (see Section 3.1 [Synopsis], page 21). There are numerousoptions, and many styles or writing them. One mandatory option speciesthe operation tar should perorm (see Section 3.4.1 [Operation Summary],page 28), other options are meant to detail how this operation should beperormed (see Section 3.4.2 [Option Summary], page 29). Non-option ar-guments are not always interpreted the same way, depending on what theoperation is.

You will nd in this chapter everything about option styles and rulesor writing them (see Section 3.3 [Styles], page 24). On the other hand,operations and options are ully described elsewhere, in other chapters. Here,you will nd only synthetic descriptions or operations and options, togetherwith pointers to other parts o the tar manual.

Some options are so special they are ully described right in this chapter.They have the efect o inhibiting the normal operation o tar or else, theyglobally alter the amount o eedback the user receives about what is goingon. These are the --help and --version (see Section 3.5 [help], page 46),--verbose (see Section 3.7 [verbose], page 48) and --interactive op-tions (see Section 3.9 [interactive], page 53).

3.1 General Synopsis o tar

The GNU tar program is invoked as either one o:tar option... [name]...

tar letter... [argument]... [option]... [name]...

The second orm is or when old options are being used.

You can use tar to store les in an archive, to extract them rom anarchive, and to do other types o archive manipulation. The primary argu-ment to tar, which is called the operation, species which action to take.The other arguments to tar are either options, which change the way tarperorms an operation, or le names or archive members, which speciy theles or members tar is to act on.

You can actually type in arguments in any order, even i in this manualthe options always precede the other arguments, to make examples easier tounderstand. Further, the option stating the main operation mode (the tarmain command) is usually given rst.

Each name in the synopsis above is interpreted as an archive mem-ber name when the main command is one o --compare (--diff, -d),--delete, --extract (--get, -x), --list (-t) or --update (-u).When naming archive members, you must give the exact name o the mem-ber in the archive, as it is printed by --list. For --append (-r) and--create (-c), these name arguments speciy the names o either les or


26/230

22 GNU tar 1.21

directory hierarchies to place in the archive. These les or hierarchies shouldalready exist in the le system, prior to the execution o the tar command.

tar interprets relative le names as being relative to the working di-rectory. tar will make all le names relative (by removing leading slashes

when archiving or restoring les), unless you speciy otherwise (using the--absolute-names option). See Section 6.10.2 [absolute], page 114, ormore inormation about --absolute-names.

I you give the name o a directory as either a le name or a membername, then tar acts recursively on all the les and directories beneath thatdirectory. For example, the name / identies all the les in the le systemto tar.

The distinction between le names and archive member names is espe-cially important when shell globbing is used, and sometimes a source oconusion or newcomers. See Section 6.5 [wildcards], page 99, or more in-ormation about globbing. The problem is that shells may only glob usingexisting les in the le system. Only tar itsel may glob on archive mem-bers, so when needed, you must ensure that wildcard characters reach tarwithout being interpreted by the shell rst. Using a backslash beore * or?, or putting the whole argument between quotes, is usually sucient orthis.

Even i names are oten specied on the command line, they can also beread rom a text le in the le system, using the --files-from=file-of-names (-T file-of-names ) option.

I you dont use any le name arguments, --append (-r), --deleteand --concatenate (--catenate, -A) will do nothing, while --create

(-c) will usually yield a diagnostic and inhibit tar execution. The otheroperations otar (--list, --extract, --compare, and --update) willact on the entire contents o the archive.

Besides successul exits, GNU tar may ail or many reasons. Some rea-sons correspond to bad usage, that is, when the tar command is improperlywritten. Errors may be encountered later, while encountering an error pro-cessing the archive or the les. Some errors are recoverable, in which casethe ailure is delayed until tar has completed all its work. Some errors aresuch that it would not meaningul, or at least risky, to continue processing:tar then aborts processing immediately. All abnormal exits, whether imme-

diate or delayed, should always be clearly diagnosed on stderr, ater a linestating the nature o the error.

Possible exit codes o GNU tar are summarized in the ollowing table:

0 Successful termination.

1 Some files differ. I tar was invoked with --compare(--diff, -d) command line option, this means that someles in the archive difer rom their disk counterparts (seeSection 4.2.6 [compare], page 63). I tar was given --create,--append or --update option, this exit code means that some


27/230


28/230

24 GNU tar 1.21

In addition to the eight operations, there are many options to tar, andthree diferent styles or writing both: long (mnemonic) orm, short orm,and old style. These styles are discussed below. Both the options and theoperations can be written in any o these three styles.

3.3 The Three Option Styles

There are three styles or writing operations and options to the commandline invoking tar. The diferent styles were developed at diferent timesduring the history o tar. These styles will be presented below, rom themost recent to the oldest.

Some options must take an argument. (For example, --file (-f))takes the name o an archive le as an argument. I you do not supply anarchive le name, tar will use a deault, but this can be conusing; thus,we recommend that you always supply a specic archive le name.) Where

you place the arguments generally depends on which style o options youchoose. We will detail specic inormation relevant to each option style inthe sections on the diferent option styles, below. The diferences are subtle,yet can oten be very important; incorrect option placement can cause you tooverwrite a number o important les. We urge you to note these diferences,and only use the option style(s) which makes the most sense to you untilyou eel comortable with the others.

Some options may take an argument. Such options may have at mostlong and short orms, they do not have old style equivalent. The rules orspeciying an argument or such options are stricter than those or speciying

mandatory arguments. Please, pay special attention to them.

3.3.1 Long Option Style

Each option has at least one long (or mnemonic) name starting with twodashes in a row, e.g., --list. The long names are more clear than theircorresponding short or old names. It sometimes happens that a single longoption has many diferent names which are synonymous, such as --compareand --diff. In addition, long option names can be given unique abbrevia-tions. For example, --cre can be used in place o --create because thereis no other long option which begins with cre. (One way to nd this out

is by trying it and seeing what happens; i a particular abbreviation couldrepresent more than one option, tar will tell you that that abbreviation isambiguous and youll know that that abbreviation wont work. You may alsochoose to run tar --help to see a list o options. Be aware that i you runtar with a unique abbreviation or the long name o an option you didntwant to use, you are stuck; tar will perorm the command as ordered.)

Long options are meant to be obvious and easy to remember, and theirmeanings are generally easier to discern than those o their correspondingshort options (see below). For example:

$ tar --create --verbose --blocking-factor=20 --file=/dev/rmt0


29/230


gives a airly good set o hints about what the command does, even or thosenot ully acquainted with tar.

Long options which require arguments take those arguments immediatelyollowing the option name. There are two ways o speciying a mandatory ar-

gument. It can be separated rom the option name either by an equal sign, orby any amount o white space characters. For example, the --file option(which tells the name o the tar archive) is given a le such as archive.taras argument by using any o the ollowing notations: --file=archive.taror --file archive.tar.

In contrast, optional arguments must always be introduced using an equalsign. For example, the --backup option takes an optional argument speci-ying backup type. It must be used as --backup=backup-type .

3.3.2 Short Option Style

Most options also have a short option name. Short options start with asingle dash, and are ollowed by a single character, e.g., -t (which is equiv-alent to --list). The orms are absolutely identical in unction; they areinterchangeable.

The short option names are aster to type than long option names.

Short options which require arguments take their arguments immediatelyollowing the option, usually separated by white space. It is also possible tostick the argument right ater the short option name, using no interveningspace. For example, you might write -f archive.tar or -farchive.tarinstead o using --file=archive.tar. Both --file=archive-name and

-f archive-name denote the option which indicates a specic archive, herenamed archive.tar.

Short options which take optional arguments take their arguments im-mediately ollowing the option letter, without any intervening white spacecharacters.

Short options letters may be clumped together, but you are not requiredto do this (as compared to old options; see below). When short options areclumped as a set, use one (single) dash or them all, e.g., tar -cvf. Onlythe last option in such a set is allowed to have an argument1.

When the options are separated, the argument or each option which

requires an argument directly ollows that option, as is usual or Unix pro-grams. For example:$ tar -c -v -b 20 -f /dev/rmt0

I you reorder short options locations, be sure to move any argumentsthat belong to them. I you do not move the arguments properly, you mayend up overwriting les.

1 Clustering many options, the last o which has an argument, is a rather opaque way towrite options. Some wonder iGNU getopt should not even be made helpul enoughor considering such usages as invalid.


30/230

26 GNU tar 1.21

3.3.3 Old Option Style


Like short options, old options are single letters. However, old optionsmust be written together as a single clumped set, without spaces separating

them or dashes preceding them2

. This set o letters must be the rst toappear on the command line, ater the tar program name and some whitespace; old options cannot appear anywhere else. The letter o an old optionis 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, thesame as the long option --list. So or example, the command tar cvspecies the option -v in addition to the operation -c.

When options that need arguments are given together with the command,all the associated arguments ollow, in the same order as the options. Thus,the example given previously could also be written in the old style as ollows:

$ tar cvbf 20 /dev/rmt0Here, 20 is the argument o -b and /dev/rmt0 is the argument o -f.

On the other hand, this old style syntax makes it dicult to matchoption letters with their corresponding arguments, and is oten conus-ing. In the command tar cvbf 20 /dev/rmt0, or example, 20 is theargument or -b, /dev/rmt0 is the argument or -f, and -v doesnot have a corresponding argument. Even using short options like intar -c -v -b 20 -f /dev/rmt0 is clearer, putting all arguments next tothe option they pertain to.

I you want to reorder the letters in the old option argument, be sure to

reorder any corresponding argument appropriately.This old way o 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 diferent. The rst example uses archive.tar.gz as the valueor option f and recognizes the option z. The second example, however,uses z as the value or option f probably not what was intended.

Old options are kept or compatibility with old versions o tar.

This second example could be corrected in many ways, among which the

ollowing are equivalent:tar -czf archive.tar.gz file

tar -cf archive.tar.gz -z file

tar cf archive.tar.gz -z file

As ar as we know, all tar programs, GNU and non-GNU, support oldoptions. GNU tar supports them not only or historical reasons, but alsobecause many people are used to them. For compatibility with Unix tar, the

2 Beware that i you precede options with a dash, you are announcing the short optionstyle instead o the old option style; short options are decoded diferently.


31/230


rst argument is always treated as containing command and option letterseven i it doesnt start with -. Thus, tar c is equivalent to tar -c: botho them speciy the --create (-c) command to create an archive.

3.3.4 Mixing Option StylesAll three styles may be intermixed in a single tar command, so long asthe rules or each style are ully respected3. Old style options and either othe modern styles o options may be mixed within a single tar command.However, old style options must be introduced as the rst arguments only,ollowing the rule or old options (old options must appear directly ater thetar command and some white space). Modern options may be given onlyater all arguments to the old options have been collected. I this rule is notrespected, a modern option might be alsely interpreted as the value o theargument to one o the old style options.

For example, all the ollowing commands are wholly equivalent, and il-lustrate the many combinations and orderings o option styles.

tar --create --file=archive.tartar --create -f archive.tar

tar --create -farchive.tar

tar --file=archive.tar --createtar --file=archive.tar -c

tar -c --file=archive.tartar -c -f archive.tar

tar -c -farchive.tar

tar -cf archive.tartar -cfarchive.tar

tar -f archive.tar --createtar -f archive.tar -c

tar -farchive.tar --create

tar -farchive.tar -ctar c --file=archive.tar

tar c -f archive.tartar c -farchive.tar

tar cf archive.tar

tar f archive.tar --createtar f archive.tar -c

tar fc archive.tar

On the other hand, the ollowing commands are not equivalent to theprevious set:

tar -f -c archive.tar

tar -fc archive.tar

tar -fcarchive.tartar -farchive.tarc

tar cfarchive.tar

3 Beore GNU tar version 1.11.6, a bug prevented intermixing old style options with longoptions in some cases.


32/230

28 GNU tar 1.21

These last examples mean something completely diferent rom what theuser intended (judging based on the example in the previous set which useslong options, whose intent is thereore very clear). The rst our speciythat the tar archive would be a le named -c, c, carchive.tar orarchive.tarc, respectively. The rst two examples also speciy a singlenon-option, name argument having the value archive.tar. The last ex-ample contains only old style option letters (repeating option c twice), notall o which are meaningul (eg., ., h, or i), with no argument value.

3.4 All tar Options

The coming manual sections contain an alphabetical listing o all tar op-erations and options, with brie descriptions and cross reerences to morein-depth explanations in the body o the manual. They also contain analphabetically arranged table o the short option orms with their corre-

sponding long option. You can use this table as a reerence or decipheringtar commands in scripts.

3.4.1 Operations

--append-r

Appends les to the end o the archive. See Section 4.2.2 [ap-pend], page 57.

--catenate

-A Same as --concatenate. See Section 4.2.4 [concatenate],page 61.

--compare-d

Compares archive members with their counterparts in the lesystem, and reports diferences in le size, mode, owner, modi-cation date and contents. See Section 4.2.6 [compare], page 63.

--concatenate-A

Appends other tar archives to the end o the archive. SeeSection 4.2.4 [concatenate], page 61.

--create-c

Creates a new tar archive. See Section 2.6 [create], page 10.

--deleteDeletes members rom the archive. Dont try this on a archiveon a tape! See Section 4.2.5 [delete], page 62.


33/230


--diff-d

Same --compare. See Section 4.2.6 [compare], page 63.

--extract

-xExtracts members rom the archive into the le system. SeeSection 2.8 [extract], page 17.

--get-x

Same as --extract. See Section 2.8 [extract], page 17.

--list-t

Lists the members in an archive. See Section 2.7 [list], page 15.

--update-u

Adds les to the end o the archive, but only i they are newerthan their counterparts already in the archive, or i they do notalready exist in the archive. See Section 4.2.3 [update], page 60.

3.4.2 tar Options

--absolute-names-P

Normally when creating an archive, tar strips an initial /rom member names. This option disables that behavior. SeeSection 6.10.2 [absolute], page 114.

--after-date(See --newer, see Section 6.8 [ater], page 109)

--anchoredA pattern must match an initial subsequence o the names com-ponents. See [controlling pattern-matching], page 100.

--atime-preserve--atime-preserve=replace--atime-preserve=system

Attempt to preserve the access time o les when reading them.This option currently is efective only on les that you own,unless you have superuser privileges.

--atime-preserve=replace remembers the access time o ale beore reading it, and then restores the access time ater-wards. This may cause problems i other programs are readingthe le at the same time, as the times o their accesses will be


34/230


35/230


With this option present, tar prints error messages or readerrors with the block number in the archive le. See [block-number], page 50.

--blocking-factor=blocking

-b blockingSets the blocking actor tar uses to blocking x 512 bytes perrecord. See Section 9.4.2 [Blocking Factor], page 153.

--bzip2-j

This option tells tar to read or write archives through bzip2.See Section 8.1.1 [gzip], page 126.

--check-deviceCheck device numbers when creating a list o modied les orincremental archiving. This is the deault. See [device numbers],page 79, or a detailed description.

--checkpoint[=number]This option directs tar to print periodic checkpoint messages asit reads through the archive. It is intended or when you wanta visual indication that tar is still running, but dont want tosee --verbose output. You can also instruct tar to executea list o actions on each checkpoint, see --checklist-actionbelow. For a detailed description, see Section 3.8 [checkpoints],page 50.

--checkpoint-action=action Instruct tar to execute an action upon hitting a breakpoint.Here we give only a brie outline. See Section 3.8 [checkpoints],page 50, or a complete description.

The action argument can be one o the ollowing:

bell Produce an audible bell on the console.

dot. Print a single dot on the standard listing stream.

echo Display a textual message on the standard error,

with the status and number o the checkpoint. Thisis the deault.

echo=stringDisplay string on the standard error. Beore output,the string is subject to meta-character expansion.

exec=commandExecute the given command.

sleep=timeWait or time seconds.


36/230

32 GNU tar 1.21

ttyout=stringOutput string on the current console (/dev/tty).

Several --checkpoint-action options can be specied. Thesupplied actions will be executed in order o their appearance in

the command line.Using --checkpoint-action without --checkpoint assumesdeault checkpoint requency o one checkpoint per 10 records.

--check-links-l I this option was given, tar will check the number o links

dumped or each processed le. I this number does not matchthe total number o hard links or the le, a warning messagewill be output4.

See Section 8.3.3 [hard links], page 134.

--compress

--uncompress-Z

tar will use the compress program when reading or writing thearchive. This allows you to directly act on archives while savingspace. See Section 8.1.1 [gzip], page 126.

--confirmation(See --interactive.) See Section 3.9 [interactive], page 53.

--delay-directory-restoreDelay setting modication times and permissions o extracted

directories until the end o extraction. See [Directory Modica-tion Times and Permissions], page 69.

--dereference-h

When creating a tar archive, tar will archive the le that asymbolic link points to, rather than archiving the symlink. SeeSection 8.3.2 [dereerence], page 134.

--directory=dir-C dir

When this option is specied, tar will change its current di-

rectory to dir beore perorming any operations. When thisoption is used during archive creation, it is order sensitive. SeeSection 6.10.1 [directory], page 112.

--exclude=pattern When perorming operations, tar will skip les that match pat-tern. See Section 6.4 [exclude], page 96.

4 Earlier versions oGNU tar understood -l as a synonym or --one-file-system.The current semantics, which complies to UNIX98, was introduced with version1.15.91. See Appendix A [Changes], page 169, or more inormation.


37/230


--exclude-from=file -X file

Similar to --exclude, except tar will use the list o patternsin the le le. See Section 6.4 [exclude], page 96.

--exclude-cachesExclude rom dump any directory containing a valid cache di-rectory tag le, but still dump the directory node and the tagle itsel.

See Section 6.4 [exclude], page 96.

--exclude-caches-underExclude rom dump any directory containing a valid cache di-rectory tag le, but still dump the directory node itsel.


--exclude-caches-allExclude rom dump any directory containing a valid cache di-rectory tag le. See Section 6.4 [exclude], page 96.

--exclude-tag=file Exclude rom dump any directory containing le named le, butdump the directory node and le itsel. See Section 6.4 [exclude],page 96.

--exclude-tag-under=file Exclude rom dump the contents o any directory containing lenamed le, but dump the directory node itsel. See Section 6.4

[exclude], page 96.

--exclude-tag-all=file Exclude rom dump any directory containing le named le. SeeSection 6.4 [exclude], page 96.

--exclude-vcsExclude rom dump directories and les, that are internal orsome widely used version control systems.


--file=archive -f archive

tar will use the le archive as the tar archive it perorms oper-ations on, rather than tars compilation dependent deault. See[le tutorial], page 7.

--files-from=file -T file

tar will use the contents o le as a list o archive membersor les to operate on, in addition to those specied on thecommand-line. See Section 6.3 [les], page 93.


38/230

34 GNU tar 1.21

--force-localForces tar to interpret the le name given to --file as a localle, even i it looks like a remote tape drive name. See [localand remote archives], page 92.

--format=format -H format Selects output archive ormat. Format may be one o the ol-lowing:

v7 Creates an archive that is compatible with Unix V7tar.

oldgnu Creates an archive that is compatible with GNU tarversion 1.12 or earlier.

gnu Creates archive in GNU tar 1.13 ormat. Basicallyit is the same as oldgnu with the only diferencein the way it handles long numeric elds.

ustar Creates a POSIX.1-1988 compatible archive.

posix Creates a POSIX.1-2001 archive.

See Chapter 8 [Formats], page 125, or a detailed discussion othese ormats.

--group=group Files added to the tar archive will have a group ID o group,rather than the group rom the source le. group is rst decodedas a group symbolic name, but i this interpretation ails, it hasto be a decimal numeric group ID. See Section 4.3.1 [override],page 64.

Also see the comments or the --owner=user option.

--gzip--gunzip--ungzip-z

This option tells tar to read or write archives through gzip,allowing tar to directly operate on several kinds o compressed

archives transparently. See Section 8.1.1 [gzip], page 126.--hard-dereference

When creating an archive, dereerence hard links and store theles they reer to, instead o creating usual hard link members.

See Section 8.3.3 [hard links], page 134.

--help-?

tar will print out a short message summarizing the operationsand options to tar and exit. See Section 3.5 [help], page 46.


39/230


--ignore-caseIgnore case when matching member or le names with patterns.See [controlling pattern-matching], page 100.

--ignore-command-error

Ignore exit codes o subprocesses. See [Writing to an ExternalProgram], page 71.

--ignore-failed-readDo not exit unsuccessully merely because an unreadable le wasencountered. See Section 4.4.1 [Reading], page 65.

--ignore-zeros-i

With this option, tar will ignore zeroed blocks in the archive,which normally signals EOF. See Section 4.4.1 [Reading],page 65.

--incremental-G

Inorms tar that it is working with an old GNU-ormat incremen-tal backup archive. It is intended primarily or backwards com-patibility only. See Section 5.2 [Incremental Dumps], page 78,or a detailed discussion o incremental archives.

--index-file=file Send verbose output to le instead o to standard output.

--info-script=script-file

--new-volume-script=script-file -F script-file

When tar is perorming multi-tape backups, script-le is runat the end o each tape. I script-le exits with nonzero status,tar ails immediately. See [ino-script], page 162, or a detaileddiscussion o script-le.

--interactive--confirmation-w

Species that tar should ask the user or conrmation beore

perorming potentially destructive options, such as overwritingles. See Section 3.9 [interactive], page 53.

--keep-newer-filesDo not replace existing les that are newer than their archivecopies when extracting les rom an archive.

--keep-old-files-k

Do not overwrite existing les when extracting les rom anarchive. See [Keep Old Files], page 68.


40/230

36 GNU tar 1.21

--label=name -V name

When creating an archive, instructs tar to write name as aname record in the archive. When extracting or listing archives,

tar will only operate on archives that have a label matchingthe pattern specied in name. See Section 9.6.2 [Tape Files],page 164.

--listed-incremental=snapshot-file -g snapshot-file

During a --create operation, species that the archive thattar creates is a new GNU-ormat incremental backup, usingsnapshot-le to determine which les to backup. With otheroperations, inorms tar that the archive is in incremental or-mat. See Section 5.2 [Incremental Dumps], page 78.

--lzma-J

This option tells tar to read or write archives through lzma.See Section 8.1.1 [gzip], page 126.

--lzop

This option tells tar to read or write archives through lzop.See Section 8.1.1 [gzip], page 126.

--mode=permissions When adding les to an archive, tar will use permissions or

the archive members, rather than the permissions rom the les.permissionscan be specied either as an octal number or as sym-bolic permissions, like with chmod. See Section 4.3.1 [override],page 64.

--mtime=date When adding les to an archive, tar will use date as the modi-cation time o members when creating archives, instead o theiractual modication times. The value o date can be either atextual date representation (see Chapter 7 [Date input ormats],page 117) or a name o the existing le, starting with / or ..

In the latter case, the modication time o that le is used. SeeSection 4.3.1 [override], page 64.

--multi-volume-M

Inorms tar that it should create or otherwise operate on amulti-volume tar archive. See Section 9.6 [Using MultipleTapes], page 160.

--new-volume-script(see ino-script)


41/230


--newer=date --after-date=date -N

When creating an archive, tar will only add les that have

changed since date. I date begins with / or ., it is takento be the name o a le whose data modication time speciesthe date. See Section 6.8 [ater], page 109.

--newer-mtime=date Like --newer, but add only les whose contents have changed(as opposed to just --newer, which will also back up les orwhich any status inormation has changed). See Section 6.8[ater], page 109.

--no-anchoredAn exclude pattern can match any subsequence o the names

components. See [controlling pattern-matching], page 100.--no-auto-compress

Disables automatic compressed ormat recognition based on thearchive sux. See [auto-compress], page 30. See Section 8.1.1[gzip], page 126.

--no-check-deviceDo not check device numbers when creating a list o modiedles or incremental archiving. See [device numbers], page 79,or a detailed description.

--no-delay-directory-restoreModication times and permissions o extracted directories areset when all les rom this directory have been extracted. Thisis the deault. See [Directory Modication Times and Permis-sions], page 69.

--no-ignore-caseUse case-sensitive matching. See [controlling pattern-matching],page 100.

--no-ignore-command-errorPrint warnings about subprocesses that terminated with a

nonzero exit code. See [Writing to an External Program],page 71.

--no-nullI the --null option was given previously, this option cancelsits efect, so that any ollowing --files-from options will ex-pect their le lists to be newline-terminated.

--no-overwrite-dirPreserve metadata o existing directories when extracting lesrom an archive. See [Overwrite Old Files], page 67.


42/230

38 GNU tar 1.21

--no-quote-chars=stringRemove characters listed in string rom the list o quoted charac-ters set by the previous --quote-chars option (see Section 6.6[quoting styles], page 102).

--no-recursionWith this option, tar will not recurse into directories. SeeSection 6.9 [recurse], page 111.

--no-same-owner-o

When extracting an archive, do not attempt to preserve theowner specied in the tar archive. This the deault behavior orordinary users.

--no-same-permissionsWhen extracting an archive, subtract the users umask rom les

rom the permissions specied in the archive. This is the deaultbehavior or ordinary users.

--no-unquoteTreat all input le or member names literally, do not interpretescape sequences. See [input name quoting], page 92.

--no-wildcardsDo not use wildcards. See [controlling pattern-matching],page 100.

--no-wildcards-match-slash

Wildcards do not match /. See [controlling pattern-matching],page 100.

--null

When tar is using the --files-from option, this option in-structs tar to expect le names terminated with NUL, so tarcan correctly work with le names that contain newlines. SeeSection 6.3.1 [nul], page 95.

--numeric-ownerThis option will notiy tar that it should use numeric user andgroup IDs when creating a tar le, rather than names. See

Section 8.2 [Attributes], page 131.

-o The unction o this option depends on the action tar isperorming. When extracting les, -o is a synonym or--no-same-owner, i.e., it prevents tar rom restoring owner-ship o les being extracted.

When creating an archive, it is a synonym or --old-archive.This behavior is or compatibility with previous versions oGNUtar, and will be removed in uture releases.

See Appendix A [Changes], page 169, or more inormation.


43/230


--occurrence[=number]This option can be used in conjunction with one o the sub-commands --delete, --diff, --extract or --list whena list o les is given either on the command line or via -Toption.

This option instructs tar to process only the numberth occur-rence o each named le. Number deaults to 1, so

tar -x -f archive.tar --occurrence filename

will extract the rst occurrence o the member filename romarchive.tar and will terminate without scanning to the endo the archive.

--old-archiveSynonym or --format=v7.

--one-file-systemUsed when creating an archive. Prevents tar rom recursinginto directories that are on diferent le systems rom the currentdirectory.

--overwriteOverwrite existing les and directory metadata when extractingles rom an archive. See [Overwrite Old Files], page 67.

--overwrite-dirOverwrite the metadata o existing directories when extracting

les rom an archive. See [Overwrite Old Files], page 67.--owner=user

Species that tar should use user as the owner o members whencreating archives, instead o the user associated with the sourcele. user is rst decoded as a user symbolic name, but i thisinterpretation ails, it has to be a decimal numeric user ID. SeeSection 4.3.1 [override], page 64.

This option does not afect extraction rom archives.

--pax-option=keyword-list

This option is meaningul only with POSIX.1-2001 archives (seeSection 8.3.7 [posix], page 136). It modies the way tar han-dles the extended header keywords. Keyword-list is a comma-separated list o keyword options. See Section 8.3.7.1 [PAX key-words], page 136, or a detailed discussion.

--portability--old-archive

Synonym or --format=v7.

--posix Same as --format=posix.


44/230

40 GNU tar 1.21

--preserveSynonymous with speciying both --preserve-permissionsand --same-order. See [Setting Access Permissions], page 69.

--preserve-order

(See --same-order; see Section 4.4.1 [Reading], page 65.)--preserve-permissions--same-permissions-p

When tar is extracting an archive, it normally subtracts theusers umask rom the permissions specied in the archive anduses that number as the permissions to create the destinationle. Speciying this option instructs tar that it should use thepermissions directly rom the archive. See [Setting Access Per-missions], page 69.

--quote-chars=stringAlways quote characters rom string, even i the selected quotingstyle would not quote them (see Section 6.6 [quoting styles],page 102).

--quoting-style=style Set quoting style to use when printing member and le names(see Section 6.6 [quoting styles], page 102). Valid style valuesare: literal, shell, shell-always, c, escape, locale, andclocale. Deault quoting style is escape, unless overriddenwhile conguring the package.

--read-full-records-B

Species that tar should reblock its input, or reading rompipes on systems with buggy implementations. See Section 4.4.1[Reading], page 65.

--record-size=size Instructs tar to use size bytes per record when accessing thearchive. See Section 9.4.2 [Blocking Factor], page 153.

--recursion

With this option, tar recurses into directories (deault). SeeSection 6.9 [recurse], page 111.

--recursive-unlinkRemove existing directory hierarchies beore extracting directo-ries o the same name rom the archive. See [Recursive Unlink],page 68.

--remove-filesDirects tar to remove the source le rom the le system aterappending it to an archive. See [remove les], page 72.


45/230


--restrictDisable use o some potentially harmul tar options. Currentlythis option disables shell invocation rom multi-volume menu(see Section 9.6 [Using Multiple Tapes], page 160).

--rmt-command=cmd Noties tar that it should use cmd instead o the deault/usr/libexec/rmt (see Section 9.2 [Remote Tape Server],page 149).

--rsh-command=cmd Noties tar that is should use cmd to communicate with remotedevices. See Section 9.1 [Device], page 147.

--same-order--preserve-order-s

This option is an optimization or tar when running on machineswith small amounts o memory. It inorms tar that the list ole arguments has already been sorted to match the order o lesin the archive. See Section 4.4.1 [Reading], page 65.

--same-ownerWhen extracting an archive, tar will attempt to preserve theowner specied in the tar archive with this option present. Thisis the deault behavior or the superuser; this option has an efectonly or ordinary users. See Section 8.2 [Attributes], page 131.

--same-permissions(See --preserve-permissions; see [Setting Access Permis-sions], page 69.)

--seek-n

Assume that the archive media supports seeks to arbitrary loca-tions. Usually tar determines automatically whether the archivecan be seeked or not. This option is intended or use in caseswhen such recognition ails.

--show-defaultsDisplays the deault options used by tar and exits successully.This option is intended or use in shell scripts. Here is an exam-ple o what you can see using this option:

$ tar --show-defaults

--format=gnu -f- -b20 --quoting-style=escape \--rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh

--show-omitted-dirsInstructs tar to mention the directories it is skipping when op-erating on a tar archive. See [show-omitted-dirs], page 50.


46/230

42 GNU tar 1.21

--show-transformed-names--show-stored-names

Display le or member names ater applying any transormations(see Section 6.7 [transorm], page 106). In particular, when usedin conjunction with one o the archive creation operations itinstructs tar to list the member names stored in the archive, asopposed to the actual le names. See [listing member and lenames], page 15.

--sparse-S

Invokes a GNU extension when adding les to an archivethat handles sparse les eciently. See Section 8.1.2 [sparse],page 130.

--sparse-version=version

Species the ormat version to use when archiving sparse les.Implies --sparse. See Section 8.1.2 [sparse], page 130. Forthe description o the supported sparse ormats, See [Sparse For-mats], page 186.

--starting-file=name -K name

This option afects extraction only; tar will skip extractingles in the archive until it nds one that matches name. SeeSection 4.4.3 [Scarce], page 72.

--strip-components=numberStrip given number o leading components rom le names be-ore extraction. For example, i archive archive.tar contained/some/file/name, then running

tar --extract --file archive.tar --strip-components=2

would extract this le to le name.

, summary

--suffix=suffixAlters the sux tar uses when backing up les rom the deault

~. See Section 4.5 [backup], page 73.--tape-length=num -L num

Species the length o tapes that tar is writing as beingnum x 1024 bytes long. See Section 9.6 [Using Multiple Tapes],page 160.

--test-labelReads the volume label. I an argument is specied, test whetherit matches the volume label. See [test-label option], page 165.


47/230


--to-command=command During extraction tar will pipe extracted les to the standardinput o command. See [Writing to an External Program],page 71.

--to-stdout-O

During extraction, tar will extract les to stdout rather than tothe le system. See [Writing to Standard Output], page 70.

--totals[=signo ]Displays the total number o bytes transerred when processingan archive. I an argument is given, these data are displayedon request, when signal signo is delivered to tar. See [totals],page 49.

--touch-m

Sets the data modication time o extracted les to the extrac-tion time, rather than the data modication time stored in thearchive. See [Data Modication Times], page 68.

--transform=sed-expr--xform=sed-expr

Transorm le or member names using sed replacement expres-sion sed-expr. For example,

$ tar cf archive.tar --transform s,^\./,usr/, .

will add to archive les rom the current working directory,replacing initial ./ prex with usr/. For the detailed discus-sion, See Section 6.7 [transorm], page 106.

To see transormed member names in verbose listings, use--show-transformed-names option (see [show-transormed-names], page 107).

--uncompress(See --compress. see Section 8.1.1 [gzip], page 126)

--ungzip

(See --gzip. see Section 8.1.1 [gzip], page 126)

--unlink-first-U

Directs tar to remove the corresponding le rom the le systembeore extracting it rom the archive. See [Unlink First], page 68.

--unquoteEnable unquoting input le or member names (deault). See[input name quoting], page 92.


48/230

44 GNU tar 1.21

--use-compress-program=progInstructs tar to access the archive through prog, which ispresumed to be a compression program o some sort. SeeSection 8.1.1 [gzip], page 126.

--utcDisplay le modication dates in UTC. This option implies--verbose.

--verbose-v

Species that tar should be more verbose about the operationsit is perorming. This option can be specied multiple timesor some operations to increase the amount o inormation dis-played. See Section 3.7 [verbose], page 48.

--verify-W

Veries that the archive was correctly written when creating anarchive. See Section 9.8 [veriy], page 167.

--versionPrint inormation about the programs name, version, origin andlegal status, all on standard output, and then exit successully.See Section 3.5 [help], page 46.

--volno-file=file Used in conjunction with --multi-volume. tar will keep tracko which volume o a multi-volume archive it is working in le.See [volno-le], page 162.

--wildcardsUse wildcards when matching member names with patterns. See[controlling pattern-matching], page 100.

--wildcards-match-slashWildcards match /. See [controlling pattern-matching],page 100.

3.4.3 Short Options Cross ReerenceHere is an alphabetized list o all o the short option orms, matching themwith the equivalent long option.

Short Option Reerence

-A [concatenate], page 28.

-B [read-ull-records], page 40.


49/230


-C [directory], page 32.

-F [ino-script], page 35.

-G [incremental], page 35.

-J [lzma], page 36.

-K [starting-le], page 42.

-L [tape-length], page 42.

-M [multi-volume], page 36.

-N [newer], page 36.

-O [to-stdout], page 43.

-P [absolute-names], page 29.

-R [block-number], page 30.

-S [sparse], page 42.

-T [les-rom], page 33.

-U [unlink-rst], page 43.

-V [label], page 35.

-W [veriy], page 44.

-X [exclude-rom], page 32.

-Z [compress], page 32.

-b [blocking-actor], page 31.

-c [create], page 28.

-d [compare], page 28.

- [le], page 33.

-g [listed-incremental], page 36.

-h [dereerence], page 32.


50/230

46 GNU tar 1.21

-i [ignore-zeros], page 35.

-j [bzip2], page 31.

-k [keep-old-les], page 35.

-l [check-links], page 32.

-m [touch], page 43.

-o When creating, [no-same-owner], page 38, when extract-ing [portability], page 39.

The latter usage is deprecated. It is retained or com-patibility with the earlier versions o GNU tar. In uturereleases -o will be equivalent to --no-same-owner only.

-p [preserve-permissions], page 40.

-r [append], page 28.

-s [same-order], page 41.

-t [list], page 29.

-u [update], page 29.

-v [verbose], page 44.

-w [interactive], page 35.

-x [extract], page 29.

-z [gzip], page 34.

3.5 GNU tar documentation

Being careul, the rst thing is really checking that you are using GNU tar,indeed. The --version option causes tar to print inormation about itsname, version, origin and legal status, all on standard output, and then exitsuccessully. For example, tar --version might print:

tar (GNU tar) 1.21Copyright (C) 2008 Free Software Foundation, Inc.

This is free software. You may redistribute copies of it under the terms

of the GNU General Public License .There is NO WARRANTY, to the extent permitted by law.

Written by John Gilmore and Jay Fenlason.


51/230


The rst occurrence o tar in the result above is the program name in thepackage (or example, rmt is another program), while the second occurrenceo tar is the name o the package itsel, containing possibly many programs.The package is currently named tar, ater the name o the main programit contains5.

Another thing you might want to do is checking the spelling or meaningo some particular tar option, without resorting to this manual, or once youhave careully read it. GNU tar has a short help eature, triggerable throughthe --help option. By using this option, tar will print a usage messagelisting all available options on standard output, then exit successully, with-out doing anything else and ignoring all other options. Even i this is only abrie summary, it may be several screens long. So, i you are not using somekind o scrollable window, you might preer to use something like:

$ tar --help | less

presuming, here, that you like using less or a pager. Other popular pagers

are more and pg. I you know about some keyword which interests you anddo not want to read all the --help output, another common idiom is doing:

tar --help | grep keyword

or getting only the pertinent lines. Notice, however, that some tar optionshave long description lines and the above command will list only the rst othem.

The exact look o the option summary displayed by tar --help is con-gurable. See Appendix B [Conguring Help Summary], page 171, or adetailed description.

I you only wish to check the spelling o an option, running tar --usagemay be a better choice. This will display a terse list o tar option withoutaccompanying explanations.

The short help output is quite succinct, and you might have to get back tothe ull documentation or precise points. I you are reading this paragraph,you already have the tar manual in some orm. This manual is availablein a variety o orms rom http://www.gnu.org/software/tar/manual . Itmay be printed out o the GNU tar distribution, provided you have TEXalready installed somewhere, and a laser printer around. Just congure thedistribution, execute the command make dvi, then print doc/tar.dvithe usual way (contact your local guru to know how). I GNU tar has

been conveniently installed at your place, this manual is also available ininteractive, hypertextual orm as an Ino le. Just call info tar or, i youdo not have the info program handy, use the Ino reader provided withinGNU Emacs, calling tar rom the main Ino menu.

There is currently no man page or GNU tar. I you observe such a manpage on the system you are running, either it does not belong to GNU tar,

5 There are plans to merge the cpio and tar packages into a single one which would becalled paxutils. So, who knows i, one o this days, the --version would not outputtar (GNU paxutils) 3.2
http://www.gnu.org/software/tar/manualhttp://www.gnu.org/software/tar/manual


52/230

48 GNU tar 1.21

or it has not been produced by GNU. Some package maintainers convert tar--help output to a man page, using help2man. In any case, please bearin mind that the authoritative source o inormation about GNU tar is thisTexino documentation.

3.6 Obtaining GNU tar deault values

GNU tar has some predened deaults that are used when you do notexplicitly speciy another values. To obtain a list o such deaults, use--show-defaults option. This will output the values in the orm o tarcommand line options:

tar --show-defaults--format=g

Documents

GNU Tar GNU Tar: An Archiver Tool FTP Release,