diff options
Diffstat (limited to 'doc/tar.info-1')
| -rw-r--r-- | doc/tar.info-1 | 7890 |
1 files changed, 7890 insertions, 0 deletions
diff --git a/doc/tar.info-1 b/doc/tar.info-1 new file mode 100644 index 0000000..ac57a2f --- /dev/null +++ b/doc/tar.info-1 @@ -0,0 +1,7890 @@ +This is tar.info, produced by makeinfo version 5.9.93 from tar.texi. + +This manual is for GNU 'tar' (version 1.29, 14 April 2016), which +creates and extracts files from archives. + + Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2016 Free Software +Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with the Invariant Sections being "GNU General Public + License", with the Front-Cover Texts being "A GNU Manual", and with + the Back-Cover Texts as in (a) below. A copy of the license is + included in the section entitled "GNU Free Documentation License". + + (a) The FSF's Back-Cover Text is: "You have the freedom to copy and + modify this GNU manual." +INFO-DIR-SECTION Archiving +START-INFO-DIR-ENTRY +* Tar: (tar). Making tape (or disk) archives. +END-INFO-DIR-ENTRY + +INFO-DIR-SECTION Individual utilities +START-INFO-DIR-ENTRY +* tar: (tar)tar invocation. Invoking GNU 'tar'. +END-INFO-DIR-ENTRY + + +File: tar.info, Node: Top, Next: Introduction, Up: (dir) + +GNU tar: an archiver tool +************************* + +This manual is for GNU 'tar' (version 1.29, 14 April 2016), which +creates and extracts files from archives. + + Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2016 Free Software +Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with the Invariant Sections being "GNU General Public + License", with the Front-Cover Texts being "A GNU Manual", and with + the Back-Cover Texts as in (a) below. A copy of the license is + included in the section entitled "GNU Free Documentation License". + + (a) The FSF's Back-Cover Text is: "You have the freedom to copy and + modify this GNU manual." + + The first part of this master menu lists the major nodes in this Info +document. The rest of the menu lists all the lower level nodes. + +* Menu: + +* Introduction:: +* Tutorial:: +* tar invocation:: +* operations:: +* Backups:: +* Choosing:: +* Date input formats:: +* Formats:: +* Media:: +* Reliability and security:: + +Appendices + +* Changes:: +* Configuring Help Summary:: +* Fixing Snapshot Files:: +* Tar Internals:: +* Genfile:: +* Free Software Needs Free Documentation:: +* GNU Free Documentation License:: +* Index of Command Line Options:: +* Index:: + + -- The Detailed Node Listing -- + +Introduction + +* Book Contents:: What this Book Contains +* Definitions:: Some Definitions +* What tar Does:: What 'tar' Does +* Naming tar Archives:: How 'tar' Archives are Named +* Authors:: GNU 'tar' Authors +* Reports:: Reporting bugs or suggestions + +Tutorial Introduction to 'tar' + +* assumptions:: +* stylistic conventions:: +* basic tar options:: Basic 'tar' Operations and Options +* frequent operations:: +* Two Frequent Options:: +* create:: How to Create Archives +* list:: How to List Archives +* extract:: How to Extract Members from an Archive +* going further:: + +Two Frequently Used Options + +* file tutorial:: +* verbose tutorial:: +* help tutorial:: + +How to Create Archives + +* prepare for examples:: +* Creating the archive:: +* create verbose:: +* short create:: +* create dir:: + +How to List Archives + +* list dir:: + +How to Extract Members from an Archive + +* extracting archives:: +* extracting files:: +* extract dir:: +* extracting untrusted archives:: +* failing commands:: + +Invoking GNU 'tar' + +* Synopsis:: +* using tar options:: +* Styles:: +* All Options:: +* help:: +* defaults:: +* verbose:: +* checkpoints:: +* warnings:: +* interactive:: + +The Three Option Styles + +* Long Options:: Long Option Style +* Short Options:: Short Option Style +* Old Options:: Old Option Style +* Mixing:: Mixing Option Styles + +All 'tar' Options + +* Operation Summary:: +* Option Summary:: +* Short Option Summary:: +* Position-Sensitive Options:: + +GNU 'tar' Operations + +* Basic tar:: +* Advanced tar:: +* create options:: +* extract options:: +* backup:: +* Applications:: +* looking ahead:: + +Advanced GNU 'tar' Operations + +* Operations:: +* append:: +* update:: +* concatenate:: +* delete:: +* compare:: + +How to Add Files to Existing Archives: '--append' + +* appending files:: Appending Files to an Archive +* multiple:: + +Updating an Archive + +* how to update:: + +Options Used by '--create' + +* override:: Overriding File Metadata. +* Extended File Attributes:: +* Ignore Failed Read:: + +Options Used by '--extract' + +* Reading:: Options to Help Read Archives +* Writing:: Changing How 'tar' Writes Files +* Scarce:: Coping with Scarce Resources + +Options to Help Read Archives + +* read full records:: +* Ignore Zeros:: + +Changing How 'tar' Writes Files + +* Dealing with Old Files:: +* Overwrite Old Files:: +* Keep Old Files:: +* Keep Newer Files:: +* Unlink First:: +* Recursive Unlink:: +* Data Modification Times:: +* Setting Access Permissions:: +* Directory Modification Times and Permissions:: +* Writing to Standard Output:: +* Writing to an External Program:: +* remove files:: + +Coping with Scarce Resources + +* Starting File:: +* Same Order:: + +Performing Backups and Restoring Files + +* Full Dumps:: Using 'tar' to Perform Full Dumps +* Incremental Dumps:: Using 'tar' to Perform Incremental Dumps +* Backup Levels:: Levels of Backups +* Backup Parameters:: Setting Parameters for Backups and Restoration +* Scripted Backups:: Using the Backup Scripts +* Scripted Restoration:: Using the Restore Script + +Setting Parameters for Backups and Restoration + +* General-Purpose Variables:: +* Magnetic Tape Control:: +* User Hooks:: +* backup-specs example:: An Example Text of 'Backup-specs' + +Choosing Files and Names for 'tar' + +* file:: Choosing the Archive's Name +* Selecting Archive Members:: +* files:: Reading Names from a File +* exclude:: Excluding Some Files +* wildcards:: Wildcards Patterns and Matching +* quoting styles:: Ways of Quoting Special Characters in Names +* transform:: Modifying File and Member Names +* after:: Operating Only on New Files +* recurse:: Descending into Directories +* one:: Crossing File System Boundaries + +Reading Names from a File + +* nul:: + +Excluding Some Files + +* problems with exclude:: + +Wildcards Patterns and Matching + +* controlling pattern-matching:: + +Crossing File System Boundaries + +* directory:: Changing Directory +* absolute:: Absolute File Names + +Date input formats + +* General date syntax:: Common rules. +* Calendar date items:: 19 Dec 1994. +* Time of day items:: 9:20pm. +* Time zone items:: EST, PDT, GMT. +* Day of week items:: Monday and others. +* Relative items in date strings:: next tuesday, 2 years ago. +* Pure numbers in date strings:: 19931219, 1440. +* Seconds since the Epoch:: @1078100502. +* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0". +* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al. + +Controlling the Archive Format + +* Compression:: Using Less Space through Compression +* Attributes:: Handling File Attributes +* Portability:: Making 'tar' Archives More Portable +* cpio:: Comparison of 'tar' and 'cpio' + +Using Less Space through Compression + +* gzip:: Creating and Reading Compressed Archives +* sparse:: Archiving Sparse Files + +Creating and Reading Compressed Archives + +* lbzip2:: Using lbzip2 with GNU 'tar'. + +Making 'tar' Archives More Portable + +* Portable Names:: Portable Names +* dereference:: Symbolic Links +* hard links:: Hard Links +* old:: Old V7 Archives +* ustar:: Ustar Archives +* gnu:: GNU and old GNU format archives. +* posix:: POSIX archives +* Checksumming:: Checksumming Problems +* Large or Negative Values:: Large files, negative time stamps, etc. +* Other Tars:: How to Extract GNU-Specific Data Using + Other 'tar' Implementations + +GNU 'tar' and POSIX 'tar' + +* PAX keywords:: Controlling Extended Header Keywords. + +How to Extract GNU-Specific Data Using Other 'tar' Implementations + +* Split Recovery:: Members Split Between Volumes +* Sparse Recovery:: Sparse Members + +Tapes and Other Archive Media + +* Device:: Device selection and switching +* Remote Tape Server:: +* Common Problems and Solutions:: +* Blocking:: Blocking +* Many:: Many archives on one tape +* Using Multiple Tapes:: Using Multiple Tapes +* label:: Including a Label in the Archive +* verify:: +* Write Protection:: + +Blocking + +* Format Variations:: Format Variations +* Blocking Factor:: The Blocking Factor of an Archive + +Many Archives on One Tape + +* Tape Positioning:: Tape Positions and Tape Marks +* mt:: The 'mt' Utility + +Using Multiple Tapes + +* Multi-Volume Archives:: Archives Longer than One Tape or Disk +* Tape Files:: Tape Files +* Tarcat:: Concatenate Volumes into a Single Archive + + +Tar Internals + +* Standard:: Basic Tar Format +* Extensions:: GNU Extensions to the Archive Format +* Sparse Formats:: Storing Sparse Files +* Snapshot Files:: +* Dumpdir:: + +Storing Sparse Files + +* Old GNU Format:: +* PAX 0:: PAX Format, Versions 0.0 and 0.1 +* PAX 1:: PAX Format, Version 1.0 + +Genfile + +* Generate Mode:: File Generation Mode. +* Status Mode:: File Status Mode. +* Exec Mode:: Synchronous Execution mode. + +Copying This Manual + +* GNU Free Documentation License:: License for copying this manual + + + +File: tar.info, Node: Introduction, Next: Tutorial, Prev: Top, Up: Top + +1 Introduction +************** + +GNU 'tar' creates and manipulates "archives" which are actually +collections of many other files; the program provides users with an +organized and systematic method for controlling a large amount of data. +The name "tar" originally came from the phrase "Tape ARchive", but +archives need not (and these days, typically do not) reside on tapes. + +* Menu: + +* Book Contents:: What this Book Contains +* Definitions:: Some Definitions +* What tar Does:: What 'tar' Does +* Naming tar Archives:: How 'tar' Archives are Named +* Authors:: GNU 'tar' Authors +* Reports:: Reporting bugs or suggestions + + +File: tar.info, Node: Book Contents, Next: Definitions, Up: Introduction + +1.1 What this Book Contains +=========================== + +The first part of this chapter introduces you to various terms that will +recur throughout the book. It also tells you who has worked on GNU +'tar' and its documentation, and where you should send bug reports or +comments. + + The second chapter is a tutorial (*note Tutorial::) which provides a +gentle introduction for people who are new to using 'tar'. It is meant +to be self-contained, not requiring any reading from subsequent chapters +to make sense. It moves from topic to topic in a logical, progressive +order, building on information already explained. + + Although the tutorial is paced and structured to allow beginners to +learn how to use 'tar', it is not intended solely for beginners. The +tutorial explains how to use the three most frequently used operations +('create', 'list', and 'extract') as well as two frequently used options +('file' and 'verbose'). The other chapters do not refer to the tutorial +frequently; however, if a section discusses something which is a complex +variant of a basic concept, there may be a cross-reference to that basic +concept. (The entire book, including the tutorial, assumes that the +reader understands some basic concepts of using a Unix-type operating +system; *note Tutorial::.) + + The third chapter presents the remaining five operations, and +information about using 'tar' options and option syntax. + + The other chapters are meant to be used as a reference. Each chapter +presents everything that needs to be said about a specific topic. + + One of the chapters (*note Date input formats::) exists in its +entirety in other GNU manuals, and is mostly self-contained. In +addition, one section of this manual (*note Standard::) contains a big +quote which is taken directly from 'tar' sources. + + In general, we give both long and short (abbreviated) option names at +least once in each section where the relevant option is covered, so that +novice readers will become familiar with both styles. (A few options +have no short versions, and the relevant sections will indicate this.) + + +File: tar.info, Node: Definitions, Next: What tar Does, Prev: Book Contents, Up: Introduction + +1.2 Some Definitions +==================== + +The 'tar' program is used to create and manipulate 'tar' archives. An +"archive" is a single file which contains the contents of many files, +while still identifying the names of the files, their owner(s), and so +forth. (In addition, archives record access permissions, user and +group, size in bytes, and data modification time. Some archives also +record the file names in each archived directory, as well as other file +and directory information.) You can use 'tar' to "create" a new archive +in a specified directory. + + The files inside an archive are called "members". Within this +manual, we use the term "file" to refer only to files accessible in the +normal ways (by 'ls', 'cat', and so forth), and the term "member" to +refer only to the members of an archive. Similarly, a "file name" is +the name of a file, as it resides in the file system, and a "member +name" is the name of an archive member within the archive. + + The term "extraction" refers to the process of copying an archive +member (or multiple members) into a file in the file system. Extracting +all the members of an archive is often called "extracting the archive". +The term "unpack" can also be used to refer to the extraction of many or +all the members of an archive. Extracting an archive does not destroy +the archive's structure, just as creating an archive does not destroy +the copies of the files that exist outside of the archive. You may also +"list" the members in a given archive (this is often thought of as +"printing" them to the standard output, or the command line), or +"append" members to a pre-existing archive. All of these operations can +be performed using 'tar'. + + +File: tar.info, Node: What tar Does, Next: Naming tar Archives, Prev: Definitions, Up: Introduction + +1.3 What 'tar' Does +=================== + +The 'tar' program provides the ability to create 'tar' archives, as well +as various other kinds of manipulation. For example, you can use 'tar' +on previously created archives to extract files, to store additional +files, or to update or list files which were already stored. + + Initially, 'tar' archives were used to store files conveniently on +magnetic tape. The name 'tar' comes from this use; it stands for 't'ape +'ar'chiver. Despite the utility's name, 'tar' can direct its output to +available devices, files, or other programs (using pipes). 'tar' may +even access remote devices or files (as archives). + + You can use 'tar' archives in many ways. We want to stress a few of +them: storage, backup, and transportation. + +Storage + Often, 'tar' archives are used to store related files for + convenient file transfer over a network. For example, the GNU + Project distributes its software bundled into 'tar' archives, so + that all the files relating to a particular program (or set of + related programs) can be transferred as a single unit. + + A magnetic tape can store several files in sequence. However, the + tape has no names for these files; it only knows their relative + position on the tape. One way to store several files on one tape + and retain their names is by creating a 'tar' archive. Even when + the basic transfer mechanism can keep track of names, as FTP can, + the nuisance of handling multiple files, directories, and multiple + links makes 'tar' archives useful. + + Archive files are also used for long-term storage. You can think + of this as transportation from the present into the future. (It is + a science-fiction idiom that you can move through time as well as + in space; the idea here is that 'tar' can be used to move archives + in all dimensions, even time!) + +Backup + Because the archive created by 'tar' is capable of preserving file + information and directory structure, 'tar' is commonly used for + performing full and incremental backups of disks. A backup puts a + collection of files (possibly pertaining to many users and + projects) together on a disk or a tape. This guards against + accidental destruction of the information in those files. GNU + 'tar' has special features that allow it to be used to make + incremental and full dumps of all the files in a file system. + +Transportation + You can create an archive on one system, transfer it to another + system, and extract the contents there. This allows you to + transport a group of files from one system to another. + + +File: tar.info, Node: Naming tar Archives, Next: Authors, Prev: What tar Does, Up: Introduction + +1.4 How 'tar' Archives are Named +================================ + +Conventionally, 'tar' archives are given names ending with '.tar'. This +is not necessary for 'tar' to operate properly, but this manual follows +that convention in order to accustom readers to it and to make examples +more clear. + + Often, people refer to 'tar' archives as "'tar' files," and archive +members as "files" or "entries". For people familiar with the operation +of 'tar', this causes no difficulty. However, in this manual, we +consistently refer to "archives" and "archive members" to make learning +to use 'tar' easier for novice users. + + +File: tar.info, Node: Authors, Next: Reports, Prev: Naming tar Archives, Up: Introduction + +1.5 GNU 'tar' Authors +===================== + +GNU 'tar' was originally written by John Gilmore, and modified by many +people. The GNU enhancements were written by Jay Fenlason, then Joy +Kendall, and the whole package has been further maintained by Thomas +Bushnell, n/BSG, Franc,ois Pinard, Paul Eggert, and finally Sergey +Poznyakoff with the help of numerous and kind users. + + We wish to stress that 'tar' is a collective work, and owes much to +all those people who reported problems, offered solutions and other +insights, or shared their thoughts and suggestions. An impressive, yet +partial list of those contributors can be found in the 'THANKS' file +from the GNU 'tar' distribution. + + Jay Fenlason put together a draft of a GNU 'tar' manual, borrowing +notes from the original man page from John Gilmore. This was withdrawn +in version 1.11. Thomas Bushnell, n/BSG and Amy Gorin worked on a +tutorial and manual for GNU 'tar'. Franc,ois Pinard put version 1.11.8 +of the manual together by taking information from all these sources and +merging them. Melissa Weisshaus finally edited and redesigned the book +to create version 1.12. The book for versions from 1.14 up to 1.29 were +edited by the current maintainer, Sergey Poznyakoff. + + For version 1.12, Daniel Hagerty contributed a great deal of +technical consulting. In particular, he is the primary author of *note +Backups::. + + In July, 2003 GNU 'tar' was put on CVS at savannah.gnu.org (see +<http://savannah.gnu.org/projects/tar>), and active development and +maintenance work has started again. Currently GNU 'tar' is being +maintained by Paul Eggert, Sergey Poznyakoff and Jeff Bailey. + + Support for POSIX archives was added by Sergey Poznyakoff. + + +File: tar.info, Node: Reports, Prev: Authors, Up: Introduction + +1.6 Reporting bugs or suggestions +================================= + +If you find problems or have suggestions about this program or manual, +please report them to 'bug-tar@gnu.org'. + + When reporting a bug, please be sure to include as much detail as +possible, in order to reproduce it. + + +File: tar.info, Node: Tutorial, Next: tar invocation, Prev: Introduction, Up: Top + +2 Tutorial Introduction to 'tar' +******************************** + +This chapter guides you through some basic examples of three 'tar' +operations: '--create', '--list', and '--extract'. If you already know +how to use some other version of 'tar', then you may not need to read +this chapter. This chapter omits most complicated details about how +'tar' works. + +* Menu: + +* assumptions:: +* stylistic conventions:: +* basic tar options:: Basic 'tar' Operations and Options +* frequent operations:: +* Two Frequent Options:: +* create:: How to Create Archives +* list:: How to List Archives +* extract:: How to Extract Members from an Archive +* going further:: + + +File: tar.info, Node: assumptions, Next: stylistic conventions, Up: Tutorial + +2.1 Assumptions this Tutorial Makes +=================================== + +This chapter is paced to allow beginners to learn about 'tar' slowly. +At the same time, we will try to cover all the basic aspects of these +three operations. In order to accomplish both of these tasks, we have +made certain assumptions about your knowledge before reading this +manual, and the hardware you will be using: + + * Before you start to work through this tutorial, you should + understand what the terms "archive" and "archive member" mean + (*note Definitions::). In addition, you should understand + something about how Unix-type operating systems work, and you + should know how to use some basic utilities. For example, you + should know how to create, list, copy, rename, edit, and delete + files and directories; how to change between directories; and how + to figure out where you are in the file system. You should have + some basic understanding of directory structure and how files are + named according to which directory they are in. You should + understand concepts such as standard output and standard input, + what various definitions of the term 'argument' mean, and the + differences between relative and absolute file names. + + * This manual assumes that you are working from your own home + directory (unless we state otherwise). In this tutorial, you will + create a directory to practice 'tar' commands in. When we show + file names, we will assume that those names are relative to your + home directory. For example, my home directory is + '/home/fsf/melissa'. All of my examples are in a subdirectory of + the directory named by that file name; the subdirectory is called + 'practice'. + + * In general, we show examples of archives which exist on (or can be + written to, or worked with from) a directory on a hard disk. In + most cases, you could write those archives to, or work with them on + any other device, such as a tape drive. However, some of the later + examples in the tutorial and next chapter will not work on tape + drives. Additionally, working with tapes is much more complicated + than working with hard disks. For these reasons, the tutorial does + not cover working with tape drives. *Note Media::, for complete + information on using 'tar' archives with tape drives. + + +File: tar.info, Node: stylistic conventions, Next: basic tar options, Prev: assumptions, Up: Tutorial + +2.2 Stylistic Conventions +========================= + +In the examples, '$' represents a typical shell prompt. It precedes +lines you should type; to make this more clear, those lines are shown in +'this font', as opposed to lines which represent the computer's +response; those lines are shown in 'this font', or sometimes 'like +this'. + + +File: tar.info, Node: basic tar options, Next: frequent operations, Prev: stylistic conventions, Up: Tutorial + +2.3 Basic 'tar' Operations and Options +====================================== + +'tar' can take a wide variety of arguments which specify and define the +actions it will have on the particular set of files or the archive. The +main types of arguments to 'tar' fall into one of two classes: +operations, and options. + + Some arguments fall into a class called "operations"; exactly one of +these is both allowed and required for any instance of using 'tar'; you +may _not_ specify more than one. People sometimes speak of "operating +modes". You are in a particular operating mode when you have specified +the operation which specifies it; there are eight operations in total, +and thus there are eight operating modes. + + The other arguments fall into the class known as "options". You are +not required to specify any options, and you are allowed to specify more +than one at a time (depending on the way you are using 'tar' at that +time). Some options are used so frequently, and are so useful for +helping you type commands more carefully that they are effectively +"required". We will discuss them in this chapter. + + You can write most of the 'tar' operations and options in any of +three forms: long (mnemonic) form, short form, and old style. Some of +the operations and options have no short or "old" forms; however, the +operations and options which we will cover in this tutorial have +corresponding abbreviations. We will indicate those abbreviations +appropriately to get you used to seeing them. Note, that the "old +style" option forms exist in GNU 'tar' for compatibility with Unix +'tar'. In this book we present a full discussion of this way of writing +options and operations (*note Old Options::), and we discuss the other +two styles of writing options (*Note Long Options::, and *note Short +Options::). + + In the examples and in the text of this tutorial, we usually use the +long forms of operations and options; but the "short" forms produce the +same result and can make typing long 'tar' commands easier. For +example, instead of typing + + tar --create --verbose --file=afiles.tar apple angst aspic + +you can type + tar -c -v -f afiles.tar apple angst aspic + +or even + tar -cvf afiles.tar apple angst aspic + +For more information on option syntax, see *note Advanced tar::. In +discussions in the text, when we name an option by its long form, we +also give the corresponding short option in parentheses. + + The term, "option", can be confusing at times, since "operations" are +often lumped in with the actual, _optional_ "options" in certain general +class statements. For example, we just talked about "short and long +forms of options and operations". However, experienced 'tar' users +often refer to these by shorthand terms such as, "short and long +options". This term assumes that the "operations" are included, also. +Context will help you determine which definition of "options" to use. + + Similarly, the term "command" can be confusing, as it is often used +in two different ways. People sometimes refer to 'tar' "commands". A +'tar' "command" is the entire command line of user input which tells +'tar' what to do -- including the operation, options, and any arguments +(file names, pipes, other commands, etc.). However, you will also +sometimes hear the term "the 'tar' command". When the word "command" is +used specifically like this, a person is usually referring to the 'tar' +_operation_, not the whole line. Again, use context to figure out which +of the meanings the speaker intends. + + +File: tar.info, Node: frequent operations, Next: Two Frequent Options, Prev: basic tar options, Up: Tutorial + +2.4 The Three Most Frequently Used Operations +============================================= + +Here are the three most frequently used operations (both short and long +forms), as well as a brief description of their meanings. The rest of +this chapter will cover how to use these operations in detail. We will +present the rest of the operations in the next chapter. + +'--create' +'-c' + Create a new 'tar' archive. +'--list' +'-t' + List the contents of an archive. +'--extract' +'-x' + Extract one or more members from an archive. + + +File: tar.info, Node: Two Frequent Options, Next: create, Prev: frequent operations, Up: Tutorial + +2.5 Two Frequently Used Options +=============================== + +To understand how to run 'tar' in the three operating modes listed +previously, you also need to understand how to use two of the options to +'tar': '--file' (which takes an archive file as an argument) and +'--verbose'. (You are usually not _required_ to specify either of these +options when you run 'tar', but they can be very useful in making things +more clear and helping you avoid errors.) + +* Menu: + +* file tutorial:: +* verbose tutorial:: +* help tutorial:: + + +File: tar.info, Node: file tutorial, Next: verbose tutorial, Up: Two Frequent Options + +The '--file' Option +------------------- + +'--file=ARCHIVE-NAME' +'-f ARCHIVE-NAME' + Specify the name of an archive file. + + You can specify an argument for the '--file=ARCHIVE-NAME' ('-f +ARCHIVE-NAME') option whenever you use 'tar'; this option determines the +name of the archive file that 'tar' will work on. + + If you don't specify this argument, then 'tar' will examine the +environment variable 'TAPE'. If it is set, its value will be used as +the archive name. Otherwise, 'tar' will use the default archive, +determined at compile time. Usually it is standard output or some +physical tape drive attached to your machine (you can verify what the +default is by running 'tar --show-defaults', *note defaults::). If +there is no tape drive attached, or the default is not meaningful, then +'tar' will print an error message. The error message might look roughly +like one of the following: + + tar: can't open /dev/rmt8 : No such device or address + tar: can't open /dev/rsmt0 : I/O error + +To avoid confusion, we recommend that you always specify an archive file +name by using '--file=ARCHIVE-NAME' ('-f ARCHIVE-NAME') when writing +your 'tar' commands. For more information on using the +'--file=ARCHIVE-NAME' ('-f ARCHIVE-NAME') option, see *note file::. + + +File: tar.info, Node: verbose tutorial, Next: help tutorial, Prev: file tutorial, Up: Two Frequent Options + +The '--verbose' Option +---------------------- + +'--verbose' +'-v' + Show the files being worked on as 'tar' is running. + + '--verbose' ('-v') shows details about the results of running 'tar'. +This can be especially useful when the results might not be obvious. +For example, if you want to see the progress of 'tar' as it writes files +into the archive, you can use the '--verbose' option. In the beginning, +you may find it useful to use '--verbose' at all times; when you are +more accustomed to 'tar', you will likely want to use it at certain +times but not at others. We will use '--verbose' at times to help make +something clear, and we will give many examples both using and not using +'--verbose' to show the differences. + + Each instance of '--verbose' on the command line increases the +verbosity level by one, so if you need more details on the output, +specify it twice. + + When reading archives ('--list', '--extract', '--diff'), 'tar' by +default prints only the names of the members being extracted. Using +'--verbose' will show a full, 'ls' style member listing. + + In contrast, when writing archives ('--create', '--append', +'--update'), 'tar' does not print file names by default. So, a single +'--verbose' option shows the file names being added to the archive, +while two '--verbose' options enable the full listing. + + For example, to create an archive in verbose mode: + + $ tar -cvf afiles.tar apple angst aspic + apple + 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 forms of options. Using +long forms, you would simply write out the mnemonic form of the option +twice, like this: + + $ tar --create --verbose --verbose ... + +Note that you must double the hyphens properly each time. + + Later in the tutorial, we will give examples using +'--verbose --verbose'. + + The full output consists of six fields: + + * File type and permissions in symbolic form. These are displayed in + the same format as the first column of 'ls -l' output (*note + format=verbose: (fileutils)What information is listed.). + + * Owner name and group separated by a slash character. If these data + are not available (for example, when listing a 'v7' format + archive), numeric ID values are printed instead. + + * Size of the file, in bytes. + + * File modification date in ISO 8601 format. + + * File modification time. + + * File name. If the name contains any special characters (white + space, newlines, etc.) these are displayed in an unambiguous form + using so called "quoting style". For the detailed discussion of + available styles and on how to use them, see *note quoting + styles::. + + Depending on the file type, the name can be followed by some + additional information, described in the following table: + + '-> LINK-NAME' + The file or archive member is a "symbolic link" and LINK-NAME + is the name of file it links to. + + 'link to LINK-NAME' + The file or archive member is a "hard link" and LINK-NAME is + the name of file it links to. + + '--Long Link--' + The archive member is an old GNU format long link. You will + normally not encounter this. + + '--Long Name--' + The archive member is an old GNU format long name. You will + normally not encounter this. + + '--Volume Header--' + The archive member is a GNU "volume header" (*note Tape + Files::). + + '--Continued at byte N--' + Encountered only at the beginning of a multi-volume archive + (*note Using Multiple Tapes::). This archive member is a + continuation from the previous volume. The number N gives the + offset where the original file was split. + + 'unknown file type C' + An archive member of unknown type. C is the type character + from the archive header. If you encounter such a message, it + means that either your archive contains proprietary member + types GNU 'tar' is not able to handle, or the archive is + corrupted. + + For example, here is an archive listing containing most of the +special suffixes explained above: + + V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header-- + -rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at byte 32456-- + -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple + lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple + -rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues + hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues + + + +File: tar.info, Node: help tutorial, Prev: verbose tutorial, Up: Two Frequent Options + +Getting Help: Using the '--help' Option +--------------------------------------- + +'--help' + + The '--help' option to 'tar' prints out a very brief list of all + operations and option available for the current version of 'tar' + available on your system. + + +File: tar.info, Node: create, Next: list, Prev: Two Frequent Options, Up: Tutorial + +2.6 How to Create Archives +========================== + +One of the basic operations of 'tar' is '--create' ('-c'), which you use +to create a 'tar' archive. We will explain '--create' first because, in +order to learn about the other operations, you will find it useful to +have an archive available to practice on. + + To make this easier, in this section you will first create a +directory containing three files. Then, we will show you how to create +an _archive_ (inside the new directory). Both the directory, and the +archive are specifically for you to practice on. The rest of this +chapter and the next chapter will show many examples using this +directory and the files you will create: some of those files may be +other directories and other archives. + + The three files you will archive in this example are called 'blues', +'folk', and 'jazz'. The archive is called 'collection.tar'. + + This section will proceed slowly, detailing how to use '--create' in +'verbose' mode, and showing examples using both short and long forms. +In the rest of the tutorial, and in the examples in the next chapter, we +will proceed at a slightly quicker pace. This section moves more slowly +to allow beginning users to understand how 'tar' works. + +* Menu: + +* prepare for examples:: +* Creating the archive:: +* create verbose:: +* short create:: +* create dir:: + + +File: tar.info, Node: prepare for examples, Next: Creating the archive, Up: create + +2.6.1 Preparing a Practice Directory for Examples +------------------------------------------------- + +To follow along with this and future examples, create a new directory +called 'practice' containing files called 'blues', 'folk' and 'jazz'. +The files can contain any information you like: ideally, they should +contain information which relates to their names, and be of different +lengths. Our examples assume that 'practice' is a subdirectory of your +home directory. + + Now 'cd' to the directory named 'practice'; 'practice' is now your +"working directory". (_Please note_: Although the full file name of +this directory is '/HOMEDIR/practice', in our examples we will refer to +this directory as 'practice'; the HOMEDIR is presumed.) + + In general, you should check that the files to be archived exist +where you think they do (in the working directory) by running 'ls'. +Because you just created the directory and the files and have changed to +that directory, you probably don't need to do that this time. + + It is very important to make sure there isn't already a file in the +working directory with the archive name you intend to use (in this case, +'collection.tar'), or that you don't care about its contents. Whenever +you use 'create', 'tar' will erase the current contents of the file +named by '--file=ARCHIVE-NAME' ('-f ARCHIVE-NAME') if it exists. 'tar' +will not tell you if you are about to overwrite an archive unless you +specify an option which does this (*note backup::, for the information +on how to do so). To add files to an existing archive, you need to use +a different option, such as '--append' ('-r'); see *note append:: for +information on how to do this. + + +File: tar.info, Node: Creating the archive, Next: create verbose, Prev: prepare for examples, Up: create + +2.6.2 Creating the Archive +-------------------------- + +To place the files 'blues', 'folk', and 'jazz' into an archive named +'collection.tar', use the following command: + + $ tar --create --file=collection.tar blues folk jazz + + The order of the arguments is not very important, _when using long +option forms_, however you should always remember to use option as the +first argument to tar. For example, the following is wrong: + + $ tar blues -c folk -f collection.tar jazz + tar: -c: Invalid blocking factor + Try 'tar --help' or 'tar --usage' for more information. + + The error message is produced because 'tar' always treats its first +argument as an option (or cluster of options), even if it does not start +with dash. This is "traditional" or "old option" style, called so +because all implementations of 'tar' have used it since the very +inception of the tar archiver in 1970s. This option style will be +explained later (*note Old Options::), for now just remember to always +place option as the first argument. + + That being said, you could issue the following command: + + $ tar --create folk blues --file=collection.tar jazz + +However, you can see that this order is harder to understand; this is +why we will list the arguments in the order that makes the commands +easiest to understand (and we encourage you to do the same when you use +'tar', to avoid errors). + + Note that the sequence '--file=collection.tar' is considered to be +_one_ argument. If you substituted any other string of characters for +'collection.tar', then that string would become the name of the archive +file you create. + + The order of the options becomes more important when you begin to use +short forms. With short forms, if you type commands in the wrong order +(even if you type them correctly in all other ways), you may end up with +results you don't expect. For this reason, it is a good idea to get +into the habit of typing options in the order that makes inherent sense. +*Note short create::, for more information on this. + + In this example, you type the command as shown above: '--create' is +the operation which creates the new archive ('collection.tar'), and +'--file' is the option which lets you give it the name you chose. The +files, 'blues', 'folk', and 'jazz', are now members of the archive, +'collection.tar' (they are "file name arguments" to the '--create' +operation. *Note Choosing::, for the detailed discussion on these.) +Now that they are in the archive, they are called _archive members_, not +files. (*note members: Definitions.). + + When you create an archive, you _must_ specify which files you want +placed in the archive. If you do not specify any archive members, GNU +'tar' will complain. + + If you now list the contents of the working directory ('ls'), you +will find the archive file listed as well as the files you saw +previously: + + blues folk jazz collection.tar + +Creating the archive 'collection.tar' did not destroy the copies of the +files in the directory. + + Keep in mind that if you don't indicate an operation, 'tar' will not +run and will prompt you for one. If you don't name any files, 'tar' +will complain. You must have write access to the working directory, or +else you will not be able to create an archive in that directory. + + _Caution_: Do not attempt to use '--create' ('-c') to add files to an +existing archive; it will delete the archive and write a new one. Use +'--append' ('-r') instead. *Note append::. + + +File: tar.info, Node: create verbose, Next: short create, Prev: Creating the archive, Up: create + +2.6.3 Running '--create' with '--verbose' +----------------------------------------- + +If you include the '--verbose' ('-v') option on the command line, 'tar' +will list the files it is acting on as it is working. In verbose mode, +the 'create' example above would appear as: + + $ tar --create --verbose --file=collection.tar blues folk jazz + blues + folk + jazz + + This example is just like the example we showed which did not use +'--verbose', except that 'tar' generated the remaining lines. + + In the rest of the examples in this chapter, we will frequently use +'verbose' mode so we can show actions or 'tar' responses that you would +otherwise not see, and which are important for you to understand. + + +File: tar.info, Node: short create, Next: create dir, Prev: create verbose, Up: create + +2.6.4 Short Forms with 'create' +------------------------------- + +As we said before, the '--create' ('-c') operation is one of the most +basic uses of 'tar', and you will use it countless times. Eventually, +you will probably want to use abbreviated (or "short") forms of options. +A full discussion of the three different forms that options can take +appears in *note Styles::; for now, here is what the previous example +(including the '--verbose' ('-v') option) looks like using short option +forms: + + $ tar -cvf collection.tar blues folk jazz + blues + folk + jazz + +As you can see, the system responds the same no matter whether you use +long or short option forms. + + One difference between using short and long option forms is that, +although the exact placement of arguments following options is no more +specific when using short forms, it is easier to become confused and +make a mistake when using short forms. For example, suppose you +attempted the above example in the following way: + + $ tar -cfv collection.tar blues folk jazz + +In this case, 'tar' will make an archive file called 'v', containing the +files 'blues', 'folk', and 'jazz', because the 'v' is the closest "file +name" to the '-f' option, and is thus taken to be the chosen archive +file name. 'tar' will try to add a file called 'collection.tar' to the +'v' archive file; if the file 'collection.tar' did not already exist, +'tar' will report an error indicating that this file does not exist. If +the file 'collection.tar' does already exist (e.g., from a previous +command you may have run), then 'tar' will add this file to the archive. +Because the '-v' option did not get registered, 'tar' will not run under +'verbose' mode, and will not report its progress. + + The end result is that you may be quite confused about what happened, +and possibly overwrite a file. To illustrate this further, we will show +you how an example we showed previously would look using short forms. + + This example, + + $ tar --create folk blues --file=collection.tar jazz + +is confusing as it is. It becomes even more so when using short forms: + + $ tar -c folk blues -f collection.tar jazz + +It would be very easy to put the wrong string of characters immediately +following the '-f', but doing that could sacrifice valuable data. + + For this reason, we recommend that you pay very careful attention to +the order of options and placement of file and archive names, especially +when using short option forms. Not having the option name written out +mnemonically can affect how well you remember which option does what, +and therefore where different names have to be placed. + + +File: tar.info, Node: create dir, Prev: short create, Up: create + +2.6.5 Archiving Directories +--------------------------- + +You can archive a directory by specifying its directory name as a file +name argument to 'tar'. The files in the directory will be archived +relative to the working directory, and the directory will be re-created +along with its contents when the archive is extracted. + + To archive a directory, first move to its superior directory. If you +have followed the previous instructions in this tutorial, you should +type: + + $ cd .. + $ + +This will put you into the directory which contains 'practice', i.e., +your home directory. Once in the superior directory, you can specify +the subdirectory, 'practice', as a file name argument. To store +'practice' in the new archive file 'music.tar', type: + + $ tar --create --verbose --file=music.tar practice + +'tar' should output: + + practice/ + practice/blues + practice/folk + practice/jazz + practice/collection.tar + + Note that the archive thus created is not in the subdirectory +'practice', but rather in the current working directory--the directory +from which 'tar' was invoked. Before trying to archive a directory from +its superior directory, you should make sure you have write access to +the superior directory itself, not only the directory you are trying +archive with 'tar'. For example, you will probably not be able to store +your home directory in an archive by invoking 'tar' from the root +directory; *Note absolute::. (Note also that 'collection.tar', the +original archive file, has itself been archived. 'tar' will accept any +file as a file to be archived, regardless of its content. When +'music.tar' is extracted, the archive file 'collection.tar' will be +re-written into the file system). + + If you give 'tar' a command such as + + $ tar --create --file=foo.tar . + +'tar' will report 'tar: ./foo.tar is the archive; not dumped'. This +happens because 'tar' creates the archive 'foo.tar' in the current +directory before putting any files into it. Then, when 'tar' attempts +to add all the files in the directory '.' to the archive, it notices +that the file './foo.tar' is the same as the archive 'foo.tar', and +skips it. (It makes no sense to put an archive into itself.) GNU 'tar' +will continue in this case, and create the archive normally, except for +the exclusion of that one file. (_Please note:_ Other implementations +of 'tar' may not be so clever; they will enter an infinite loop when +this happens, so you should not depend on this behavior unless you are +certain you are running GNU 'tar'. In general, it is wise to always +place the archive outside of the directory being dumped.) + + +File: tar.info, Node: list, Next: extract, Prev: create, Up: Tutorial + +2.7 How to List Archives +======================== + +Frequently, you will find yourself wanting to determine exactly what a +particular archive contains. You can use the '--list' ('-t') operation +to get the member names as they currently appear in the archive, as well +as various attributes of the files at the time they were archived. For +example, assuming 'practice' is your working directory, you can examine +the archive 'collection.tar' that you created in the last section with +the command, + + $ tar --list --file=collection.tar + +The output of 'tar' would then be: + + blues + folk + jazz + +Be sure to use a '--file=ARCHIVE-NAME' ('-f ARCHIVE-NAME') option just +as with '--create' ('-c') to specify the name of the archive. + + You can specify one or more individual member names as arguments when +using 'list'. In this case, 'tar' will only list the names of members +you identify. For example, 'tar --list --file=collection.tar folk' +would only print 'folk': + + $ tar --list --file=collection.tar folk + folk + + If you use the '--verbose' ('-v') option with '--list', then 'tar' +will print out a listing reminiscent of 'ls -l', showing owner, file +size, and so forth. This output is described in detail in *note verbose +member listing::. + + If you had used '--verbose' ('-v') mode, the example above would look +like: + + $ tar --list --verbose --file=collection.tar folk + -rw-r--r-- myself/user 62 1990-05-23 10:55 folk + + It is important to notice that the output of 'tar --list --verbose' +does not necessarily match that produced by 'tar --create --verbose' +while creating the archive. It is because GNU 'tar', unless told +explicitly not to do so, removes some directory prefixes from file names +before storing them in the archive (*Note absolute::, for more +information). In other words, in verbose mode GNU 'tar' shows "file +names" when creating an archive and "member names" when listing it. +Consider this example, run from your home directory: + + $ tar --create --verbose --file practice.tar ~/practice + tar: Removing leading '/' from member names + /home/myself/practice/ + /home/myself/practice/blues + /home/myself/practice/folk + /home/myself/practice/jazz + /home/myself/practice/collection.tar + $ tar --test --file practice.tar + home/myself/practice/ + home/myself/practice/blues + home/myself/practice/folk + home/myself/practice/jazz + home/myself/practice/collection.tar + + This default behavior can sometimes be inconvenient. You can force +GNU 'tar' show member names when creating archive by supplying +'--show-stored-names' option. + +'--show-stored-names' + Print member (as opposed to _file_) names when creating the + archive. + + With this option, both commands produce the same output: + + $ tar --create --verbose --show-stored-names \ + --file practice.tar ~/practice + tar: Removing leading '/' from member names + home/myself/practice/ + home/myself/practice/blues + home/myself/practice/folk + home/myself/practice/jazz + home/myself/practice/collection.tar + $ tar --test --file practice.tar + home/myself/practice/ + home/myself/practice/blues + home/myself/practice/folk + home/myself/practice/jazz + home/myself/practice/collection.tar + + Since 'tar' preserves file names, those you wish to list must be +specified as they appear in the archive (i.e., relative to the directory +from which the archive was created). Continuing the example above: + + $ tar --list --file=practice.tar folk + tar: folk: Not found in archive + tar: Exiting with failure status due to previous errors + + the error message is produced because there is no member named +'folk', only one named 'home/myself/folk'. + + If you are not sure of the exact file name, use "globbing patterns", +for example: + + $ tar --list --file=practice.tar --wildcards '*/folk' + home/myself/practice/folk + +*Note wildcards::, for a detailed discussion of globbing patterns and +related 'tar' command line options. + +* Menu: + +* list dir:: + + +File: tar.info, Node: list dir, Up: list + +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' +('-t'). To find out file attributes, include the '--verbose' ('-v') +option. + + For example, to find out about files in the directory 'practice', in +the archive file 'music.tar', type: + + $ tar --list --verbose --file=music.tar practice + + 'tar' responds: + + drwxrwxrwx myself/user 0 1990-05-31 21:49 practice/ + -rw-r--r-- myself/user 42 1990-05-21 13:29 practice/blues + -rw-r--r-- myself/user 62 1990-05-23 10:55 practice/folk + -rw-r--r-- myself/user 40 1990-05-21 13:30 practice/jazz + -rw-r--r-- myself/user 10240 1990-05-31 21:49 practice/collection.tar + + When you use a directory name as a file name argument, 'tar' acts on +all the files (including sub-directories) in that directory. + + +File: tar.info, Node: extract, Next: going further, Prev: list, Up: Tutorial + +2.8 How to Extract Members from an Archive +========================================== + +Creating an archive is only half the job--there is no point in storing +files in an archive if you can't retrieve them. The act of retrieving +members from an archive so they can be used and manipulated as +unarchived files again is called "extraction". To extract files from an +archive, use the '--extract' ('--get' or '-x') operation. As with +'--create', specify the name of the archive with '--file' ('-f') option. +Extracting an archive does not modify the archive in any way; you can +extract it multiple times if you want or need to. + + Using '--extract', you can extract an entire archive, or specific +files. The files can be directories containing other files, or not. As +with '--create' ('-c') and '--list' ('-t'), you may use the short or the +long form of the operation without affecting the performance. + +* Menu: + +* extracting archives:: +* extracting files:: +* extract dir:: +* extracting untrusted archives:: +* failing commands:: + + +File: tar.info, Node: extracting archives, Next: extracting files, Up: extract + +2.8.1 Extracting an Entire Archive +---------------------------------- + +To extract an entire archive, specify the archive file name only, with +no individual file names as arguments. For example, + + $ tar -xvf collection.tar + +produces this: + + -rw-r--r-- myself/user 28 1996-10-18 16:31 jazz + -rw-r--r-- myself/user 21 1996-09-23 16:44 blues + -rw-r--r-- myself/user 20 1996-09-23 16:44 folk + + +File: tar.info, Node: extracting files, Next: extract dir, Prev: extracting archives, Up: extract + +2.8.2 Extracting Specific Files +------------------------------- + +To extract specific archive members, give their exact member names as +arguments, as printed by '--list' ('-t'). If you had mistakenly deleted +one of the files you had placed in the archive 'collection.tar' earlier +(say, 'blues'), you can extract it from the archive without changing the +archive's structure. Its contents will be identical to the original +file 'blues' that you deleted. + + First, make sure you are in the 'practice' directory, and list the +files in the directory. Now, delete the file, 'blues', and list the +files in the directory again. + + You can now extract the member 'blues' from the archive file +'collection.tar' like this: + + $ tar --extract --file=collection.tar blues + +If you list the files in the directory again, you will see that the file +'blues' has been restored, with its original permissions, data +modification times, and owner.(1) (These parameters will be identical +to those which the file had when you originally placed it in the +archive; any changes you may have made before deleting the file from the +file system, however, will _not_ have been made to the archive member.) +The archive file, 'collection.tar', is the same as it was before you +extracted 'blues'. You can confirm this by running 'tar' with '--list' +('-t'). + + Remember that as with other operations, specifying the exact member +name is important (*Note failing commands::, for more examples). + + You can extract a file to standard output by combining the above +options with the '--to-stdout' ('-O') option (*note Writing to Standard +Output::). + + If you give the '--verbose' option, then '--extract' will print the +names of the archive members as it extracts them. + + ---------- Footnotes ---------- + + (1) This is only accidentally true, but not in general. Whereas +modification times are always restored, in most cases, one has to be +root for restoring the owner, and use a special option for restoring +permissions. Here, it just happens that the restoring user is also the +owner of the archived members, and that the current 'umask' is +compatible with original permissions. + + +File: tar.info, Node: extract dir, Next: extracting untrusted archives, Prev: extracting files, Up: extract + +2.8.3 Extracting Files that are Directories +------------------------------------------- + +Extracting directories which are members of an archive is similar to +extracting other files. The main difference to be aware of is that if +the extracted directory has the same name as any directory already in +the working directory, then files in the extracted directory will be +placed into the directory of the same name. Likewise, if there are +files in the pre-existing directory with the same names as the members +which you extract, the files from the extracted archive will replace the +files already in the working directory (and possible subdirectories). +This will happen regardless of whether or not the files in the working +directory were more recent than those extracted (there exist, however, +special options that alter this behavior *note Writing::). + + However, if a file was stored with a directory name as part of its +file name, and that directory does not exist under the working directory +when the file is extracted, 'tar' will create the directory. + + We can demonstrate how to use '--extract' to extract a directory file +with an example. Change to the 'practice' directory if you weren't +there, and remove the files 'folk' and 'jazz'. Then, go back to the +parent directory and extract the archive 'music.tar'. You may either +extract the entire archive, or you may extract only the files you just +deleted. To extract the entire archive, don't give any file names as +arguments after the archive name 'music.tar'. To extract only the files +you deleted, use the following command: + + $ tar -xvf music.tar practice/folk practice/jazz + practice/folk + practice/jazz + +If you were to specify two '--verbose' ('-v') options, 'tar' would have +displayed more detail about the extracted files, as shown in the example +below: + + $ tar -xvvf music.tar practice/folk practice/jazz + -rw-r--r-- me/user 28 1996-10-18 16:31 practice/jazz + -rw-r--r-- me/user 20 1996-09-23 16:44 practice/folk + +Because you created the directory with 'practice' as part of the file +names of each of the files by archiving the 'practice' directory as +'practice', you must give 'practice' as part of the file names when you +extract those files from the archive. + + +File: tar.info, Node: extracting untrusted archives, Next: failing commands, Prev: extract dir, Up: extract + +2.8.4 Extracting Archives from Untrusted Sources +------------------------------------------------ + +Extracting files from archives can overwrite files that already exist. +If you receive an archive from an untrusted source, you should make a +new directory and extract into that directory, so that you don't have to +worry about the extraction overwriting one of your existing files. For +example, if 'untrusted.tar' came from somewhere else on the Internet, +and you don't necessarily trust its contents, you can extract it as +follows: + + $ mkdir newdir + $ cd newdir + $ tar -xvf ../untrusted.tar + + It is also a good practice to examine contents of the archive before +extracting it, using '--list' ('-t') option, possibly combined with +'--verbose' ('-v'). + + +File: tar.info, Node: failing commands, Prev: extracting untrusted archives, Up: extract + +2.8.5 Commands That Will Fail +----------------------------- + +Here are some sample commands you might try which will not work, and why +they won't work. + + If you try to use this command, + + $ tar -xvf music.tar folk jazz + +you will get the following response: + + tar: folk: Not found in archive + tar: jazz: Not found in archive + +This is because these files were not originally _in_ the parent +directory '..', where the archive is located; they were in the +'practice' directory, and their file names reflect this: + + $ tar -tvf music.tar + practice/blues + practice/folk + practice/jazz + +Likewise, if you try to use this command, + + $ tar -tvf music.tar folk jazz + +you would get a similar response. Members with those names are not in +the archive. You must use the correct member names, or wildcards, in +order to extract the files from the archive. + + If you have forgotten the correct names of the files in the archive, +use 'tar --list --verbose' to list them correctly. + + To extract the member named 'practice/folk', you must specify + + $ tar --extract --file=music.tar practice/folk + +Notice also, that as explained above, the 'practice' directory will be +created, if it didn't already exist. There are options that allow you +to strip away a certain number of leading directory components (*note +transform::). For example, + + $ tar --extract --file=music.tar --strip-components=1 folk + +will extract the file 'folk' into the current working directory. + + +File: tar.info, Node: going further, Prev: extract, Up: Tutorial + +2.9 Going Further Ahead in this Manual +====================================== + + _(This message will disappear, once this node revised.)_ + + +File: tar.info, Node: tar invocation, Next: operations, Prev: Tutorial, Up: Top + +3 Invoking GNU 'tar' +******************** + +This chapter is about how one invokes the GNU 'tar' command, from the +command synopsis (*note Synopsis::). There are numerous options, and +many styles for writing them. One mandatory option specifies the +operation 'tar' should perform (*note Operation Summary::), other +options are meant to detail how this operation should be performed +(*note Option Summary::). Non-option arguments are not always +interpreted the same way, depending on what the operation is. + + You will find in this chapter everything about option styles and +rules for writing them (*note Styles::). On the other hand, operations +and options are fully described elsewhere, in other chapters. Here, you +will find only synthetic descriptions for operations and options, +together with pointers to other parts of the 'tar' manual. + + Some options are so special they are fully described right in this +chapter. They have the effect of inhibiting the normal operation of +'tar' or else, they globally alter the amount of feedback the user +receives about what is going on. These are the '--help' and '--version' +(*note help::), '--verbose' (*note verbose::) and '--interactive' +options (*note interactive::). + +* Menu: + +* Synopsis:: +* using tar options:: +* Styles:: +* All Options:: All 'tar' Options. +* help:: Where to Get Help. +* defaults:: What are the Default Values. +* verbose:: Checking 'tar' progress. +* checkpoints:: Checkpoints. +* warnings:: Controlling Warning Messages. +* interactive:: Asking for Confirmation During Operations. +* external:: Running External Commands. + + +File: tar.info, Node: Synopsis, Next: using tar options, Up: tar invocation + +3.1 General Synopsis of 'tar' +============================= + +The GNU 'tar' program is invoked as either one of: + + tar OPTION... [NAME]... + tar LETTER... [ARGUMENT]... [OPTION]... [NAME]... + + The second form is for when old options are being used. + + You can use 'tar' to store files in an archive, to extract them from +an archive, and to do other types of archive manipulation. The primary +argument to 'tar', which is called the "operation", specifies which +action to take. The other arguments to 'tar' are either "options", +which change the way 'tar' performs an operation, or file names or +archive members, which specify the files or members 'tar' is to act on. + + You can actually type in arguments in any order, even if in this +manual the options always precede the other arguments, to make examples +easier to understand. Further, the option stating the main operation +mode (the 'tar' main command) is usually given first. + + Each NAME in the synopsis above is interpreted as an archive member +name when the main command is one of '--compare' ('--diff', '-d'), +'--delete', '--extract' ('--get', '-x'), '--list' ('-t') or '--update' +('-u'). When naming archive members, you must give the exact name of +the member in the archive, as it is printed by '--list'. For '--append' +('-r') and '--create' ('-c'), these NAME arguments specify the names of +either files or directory hierarchies to place in the archive. These +files or hierarchies should already exist in the file system, prior to +the execution of the 'tar' command. + + 'tar' interprets relative file names as being relative to the working +directory. 'tar' will make all file names relative (by removing leading +slashes when archiving or restoring files), unless you specify otherwise +(using the '--absolute-names' option). *Note absolute::, for more +information about '--absolute-names'. + + If you give the name of a directory as either a file name or a member +name, then 'tar' acts recursively on all the files and directories +beneath that directory. For example, the name '/' identifies all the +files in the file system to 'tar'. + + The distinction between file names and archive member names is +especially important when shell globbing is used, and sometimes a source +of confusion for newcomers. *Note wildcards::, for more information +about globbing. The problem is that shells may only glob using existing +files in the file system. Only 'tar' itself may glob on archive +members, so when needed, you must ensure that wildcard characters reach +'tar' without being interpreted by the shell first. Using a backslash +before '*' or '?', or putting the whole argument between quotes, is +usually sufficient for this. + + Even if NAMEs are often specified on the command line, they can also +be read from a text file in the file system, using the +'--files-from=FILE-OF-NAMES' ('-T FILE-OF-NAMES') option. + + If you don't use any file name arguments, '--append' ('-r'), +'--delete' and '--concatenate' ('--catenate', '-A') will do nothing, +while '--create' ('-c') will usually yield a diagnostic and inhibit +'tar' execution. The other operations of 'tar' ('--list', '--extract', +'--compare', and '--update') will act on the entire contents of the +archive. + + Besides successful exits, GNU 'tar' may fail for many reasons. Some +reasons correspond to bad usage, that is, when the 'tar' command line is +improperly written. Errors may be encountered later, while processing +the archive or the files. Some errors are recoverable, in which case +the failure is delayed until 'tar' has completed all its work. Some +errors are such that it would be not meaningful, or at least risky, to +continue processing: 'tar' then aborts processing immediately. All +abnormal exits, whether immediate or delayed, should always be clearly +diagnosed on 'stderr', after a line stating the nature of the error. + + Possible exit codes of GNU 'tar' are summarized in the following +table: + +0 + 'Successful termination'. + +1 + 'Some files differ'. If tar was invoked with '--compare' + ('--diff', '-d') command line option, this means that some files in + the archive differ from their disk counterparts (*note compare::). + If tar was given '--create', '--append' or '--update' option, this + exit code means that some files were changed while being archived + and so the resulting archive does not contain the exact copy of the + file set. + +2 + 'Fatal error'. This means that some fatal, unrecoverable error + occurred. + + If 'tar' has invoked a subprocess and that subprocess exited with a +nonzero exit code, 'tar' exits with that code as well. This can happen, +for example, if 'tar' was given some compression option (*note gzip::) +and the external compressor program failed. Another example is 'rmt' +failure during backup to the remote device (*note Remote Tape Server::). + + +File: tar.info, Node: using tar options, Next: Styles, Prev: Synopsis, Up: tar invocation + +3.2 Using 'tar' Options +======================= + +GNU 'tar' has a total of eight operating modes which allow you to +perform a variety of tasks. You are required to choose one operating +mode each time you employ the 'tar' program by specifying one, and only +one operation as an argument to the 'tar' command (the corresponding +options may be found at *note frequent operations:: and *note +Operations::). Depending on circumstances, you may also wish to +customize how the chosen operating mode behaves. For example, you may +wish to change the way the output looks, or the format of the files that +you wish to archive may require you to do something special in order to +make the archive look right. + + You can customize and control 'tar''s performance by running 'tar' +with one or more options (such as '--verbose' ('-v'), which we used in +the tutorial). As we said in the tutorial, "options" are arguments to +'tar' which are (as their name suggests) optional. Depending on the +operating mode, you may specify one or more options. Different options +will have different effects, but in general they all change details of +the operation, such as archive format, archive name, or level of user +interaction. Some options make sense with all operating modes, while +others are meaningful only with particular modes. You will likely use +some options frequently, while you will only use others infrequently, or +not at all. (A full list of options is available in *note All +Options::.) + + The 'TAR_OPTIONS' environment variable specifies default options to +be placed in front of any explicit options. For example, if +'TAR_OPTIONS' is '-v --unlink-first', 'tar' behaves as if the two +options '-v' and '--unlink-first' had been specified before any explicit +options. Option specifications are separated by whitespace. A +backslash escapes the next character, so it can be used to specify an +option containing whitespace or a backslash. + + Note that 'tar' options are case sensitive. For example, the options +'-T' and '-t' are different; the first requires an argument for stating +the name of a file providing a list of NAMEs, while the second does not +require an argument and is another way to write '--list' ('-t'). + + In addition to the eight operations, there are many options to 'tar', +and three different styles for writing both: long (mnemonic) form, short +form, and old style. These styles are discussed below. Both the +options and the operations can be written in any of these three styles. + + +File: tar.info, Node: Styles, Next: All Options, Prev: using tar options, Up: tar invocation + +3.3 The Three Option Styles +=========================== + +There are three styles for writing operations and options to the command +line invoking 'tar'. The different styles were developed at different +times during the history of 'tar'. These styles will be presented +below, from the most recent to the oldest. + + Some options must take an argument(1). Where you _place_ the +arguments generally depends on which style of options you choose. We +will detail specific information relevant to each option style in the +sections on the different option styles, below. The differences are +subtle, yet can often be very important; incorrect option placement can +cause you to overwrite a number of important files. We urge you to note +these differences, and only use the option style(s) which makes the most +sense to you until you feel comfortable with the others. + + Some options _may_ take an argument. Such options may have at most +long and short forms, they do not have old style equivalent. The rules +for specifying an argument for such options are stricter than those for +specifying mandatory arguments. Please, pay special attention to them. + +* Menu: + +* Long Options:: Long Option Style +* Short Options:: Short Option Style +* Old Options:: Old Option Style +* Mixing:: Mixing Option Styles + + ---------- Footnotes ---------- + + (1) For example, '--file' ('-f') takes the name of an archive file as +an argument. If you do not supply an archive file name, 'tar' will use +a default, but this can be confusing; thus, we recommend that you always +supply a specific archive file name. + + +File: tar.info, Node: Long Options, Next: Short Options, Up: Styles + +3.3.1 Long Option Style +----------------------- + +Each option has at least one "long" (or "mnemonic") name starting with +two dashes in a row, e.g., '--list'. The long names are more clear than +their corresponding short or old names. It sometimes happens that a +single long option has many different names which are synonymous, such +as '--compare' and '--diff'. In addition, long option names can be +given unique abbreviations. For example, '--cre' can be used in place +of '--create' because there is no other long option which begins with +'cre'. (One way to find this out is by trying it and seeing what +happens; if a particular abbreviation could represent more than one +option, 'tar' will tell you that that abbreviation is ambiguous and +you'll know that that abbreviation won't work. You may also choose to +run 'tar --help' to see a list of options. Be aware that if you run +'tar' with a unique abbreviation for the long name of an option you +didn't want to use, you are stuck; 'tar' will perform the command as +ordered.) + + Long options are meant to be obvious and easy to remember, and their +meanings are generally easier to discern than those of their +corresponding short options (see below). For example: + + $ tar --create --verbose --blocking-factor=20 --file=/dev/rmt0 + +gives a fairly good set of hints about what the command does, even for +those not fully acquainted with 'tar'. + + Long options which require arguments take those arguments immediately +following the option name. There are two ways of specifying a mandatory +argument. It can be separated from the option name either by an equal +sign, or by any amount of white space characters. For example, the +'--file' option (which tells the name of the 'tar' archive) is given a +file such as 'archive.tar' as argument by using any of the following +notations: '--file=archive.tar' or '--file archive.tar'. + + In contrast, optional arguments must always be introduced using an +equal sign. For example, the '--backup' option takes an optional +argument specifying backup type. It must be used as +'--backup=BACKUP-TYPE'. + + +File: tar.info, Node: Short Options, Next: Old Options, Prev: Long Options, Up: Styles + +3.3.2 Short Option Style +------------------------ + +Most options also have a "short option" name. Short options start with +a single dash, and are followed by a single character, e.g., '-t' (which +is equivalent to '--list'). The forms are absolutely identical in +function; they are interchangeable. + + The short option names are faster to type than long option names. + + Short options which require arguments take their arguments +immediately following the option, usually separated by white space. It +is also possible to stick the argument right after the short option +name, using no intervening space. For example, you might write +'-f archive.tar' or '-farchive.tar' instead of using +'--file=archive.tar'. Both '--file=ARCHIVE-NAME' and '-f ARCHIVE-NAME' +denote the option which indicates a specific archive, here named +'archive.tar'. + + Short options which take optional arguments take their arguments +immediately following the option letter, _without any intervening white +space characters_. + + Short options' letters may be clumped together, but you are not +required to do this (as compared to old options; see below). When short +options are clumped as a set, use one (single) dash for them all, e.g., +''tar' -cvf'. Only the last option in such a set is allowed to have an +argument(1). + + When the options are separated, the argument for each option which +requires an argument directly follows that option, as is usual for Unix +programs. For example: + + $ tar -c -v -b 20 -f /dev/rmt0 + + If you reorder short options' locations, be sure to move any +arguments that belong to them. If you do not move the arguments +properly, you may end up overwriting files. + + ---------- Footnotes ---------- + + (1) Clustering many options, the last of which has an argument, is a +rather opaque way to write options. Some wonder if GNU 'getopt' should +not even be made helpful enough for considering such usages as invalid. + + +File: tar.info, Node: Old Options, Next: Mixing, Prev: Short Options, Up: Styles + +3.3.3 Old Option Style +---------------------- + +As far as we know, all 'tar' programs, GNU and non-GNU, support "old +options": that is, if the first argument does not start with '-', it is +assumed to specify option letters. GNU 'tar' supports old options not +only for historical reasons, but also because many people are used to +them. If the first argument does not start with a dash, you are +announcing the old option style instead of the short option style; old +options are decoded differently. + + Like short options, old options are single letters. However, old +options must be written together as a single clumped set, without spaces +separating them or dashes preceding them. This set of letters must be +the first to appear on the command line, after the 'tar' program name +and some white space; old options cannot appear anywhere else. The +letter of an old option is exactly the same letter as the corresponding +short option. For example, the old option 't' is the same as the short +option '-t', and consequently, the same as the long option '--list'. So +for example, the command 'tar cv' specifies the option '-v' in addition +to the operation '-c'. + + When options that need arguments are given together with the command, +all the associated arguments follow, in the same order as the options. +Thus, the example given previously could also be written in the old +style as follows: + + $ tar cvbf 20 /dev/rmt0 + +Here, '20' is the argument of '-b' and '/dev/rmt0' is the argument of +'-f'. + + The old style syntax can make it difficult to match option letters +with their corresponding arguments, and is often confusing. In the +command 'tar cvbf 20 /dev/rmt0', for example, '20' is the argument for +'-b', '/dev/rmt0' is the argument for '-f', and '-v' does not have a +corresponding argument. Even using short options like in +'tar -c -v -b 20 -f /dev/rmt0' is clearer, putting all arguments next to +the option they pertain to. + + If you want to reorder the letters in the old option argument, be +sure to reorder any corresponding argument appropriately. + + This old way of writing 'tar' options can surprise even experienced +users. For example, the two commands: + + tar cfz archive.tar.gz file + tar -cfz archive.tar.gz file + +are quite different. The first example uses 'archive.tar.gz' as the +value for option 'f' and recognizes the option 'z'. The second example, +however, uses 'z' as the value for option 'f' -- probably not what was +intended. + + This second example could be corrected in many ways, among which the +following are equivalent: + + tar -czf archive.tar.gz file + tar -cf archive.tar.gz -z file + tar cf archive.tar.gz -z file + + +File: tar.info, Node: Mixing, Prev: Old Options, Up: Styles + +3.3.4 Mixing Option Styles +-------------------------- + +All three styles may be intermixed in a single 'tar' command, so long as +the rules for each style are fully respected(1). Old style options and +either of the modern styles of options may be mixed within a single +'tar' command. However, old style options must be introduced as the +first arguments only, following the rule for old options (old options +must appear directly after the 'tar' command and some white space). +Modern options may be given only after all arguments to the old options +have been collected. If this rule is not respected, a modern option +might be falsely interpreted as the value of the argument to one of the +old style options. + + For example, all the following commands are wholly equivalent, and +illustrate the many combinations and orderings of option styles. + + tar --create --file=archive.tar + tar --create -f archive.tar + tar --create -farchive.tar + tar --file=archive.tar --create + tar --file=archive.tar -c + tar -c --file=archive.tar + tar -c -f archive.tar + tar -c -farchive.tar + tar -cf archive.tar + tar -cfarchive.tar + tar -f archive.tar --create + tar -f archive.tar -c + tar -farchive.tar --create + tar -farchive.tar -c + tar c --file=archive.tar + tar c -f archive.tar + tar c -farchive.tar + tar cf archive.tar + tar f archive.tar --create + tar f archive.tar -c + tar fc archive.tar + + On the other hand, the following commands are _not_ equivalent to the +previous set: + + tar -f -c archive.tar + tar -fc archive.tar + tar -fcarchive.tar + tar -farchive.tarc + tar cfarchive.tar + +These last examples mean something completely different from what the +user intended (judging based on the example in the previous set which +uses long options, whose intent is therefore very clear). The first +four specify that the 'tar' archive would be a file named '-c', 'c', +'carchive.tar' or 'archive.tarc', respectively. The first two examples +also specify a single non-option, NAME argument having the value +'archive.tar'. The last example contains only old style option letters +(repeating option 'c' twice), not all of which are meaningful (eg., '.', +'h', or 'i'), with no argument value. + + ---------- Footnotes ---------- + + (1) Before GNU 'tar' version 1.11.6, a bug prevented intermixing old +style options with long options in some cases. + + +File: tar.info, Node: All Options, Next: help, Prev: Styles, Up: tar invocation + +3.4 All 'tar' Options +===================== + +The coming manual sections contain an alphabetical listing of all 'tar' +operations and options, with brief descriptions and cross-references to +more in-depth explanations in the body of the manual. They also contain +an alphabetically arranged table of the short option forms with their +corresponding long option. You can use this table as a reference for +deciphering 'tar' commands in scripts. + +* Menu: + +* Operation Summary:: +* Option Summary:: +* Short Option Summary:: +* Position-Sensitive Options:: + + +File: tar.info, Node: Operation Summary, Next: Option Summary, Up: All Options + +3.4.1 Operations +---------------- + +'--append' +'-r' + + Appends files to the end of the archive. *Note append::. + +'--catenate' +'-A' + + Same as '--concatenate'. *Note concatenate::. + +'--compare' +'-d' + + Compares archive members with their counterparts in the file + system, and reports differences in file size, mode, owner, + modification date and contents. *Note compare::. + +'--concatenate' +'-A' + + Appends other 'tar' archives to the end of the archive. *Note + concatenate::. + +'--create' +'-c' + + Creates a new 'tar' archive. *Note create::. + +'--delete' + + Deletes members from the archive. Don't try this on an archive on + a tape! *Note delete::. + +'--diff' +'-d' + + Same '--compare'. *Note compare::. + +'--extract' +'-x' + + Extracts members from the archive into the file system. *Note + extract::. + +'--get' +'-x' + + Same as '--extract'. *Note extract::. + +'--list' +'-t' + + Lists the members in an archive. *Note list::. + +'--update' +'-u' + + Adds files to the end of the archive, but only if they are newer + than their counterparts already in the archive, or if they do not + already exist in the archive. *Note update::. + + +File: tar.info, Node: Option Summary, Next: Short Option Summary, Prev: Operation Summary, Up: All Options + +3.4.2 'tar' Options +------------------- + +'--absolute-names' +'-P' + + Normally when creating an archive, 'tar' strips an initial '/' from + member names, and when extracting from an archive 'tar' treats + names specially if they have initial '/' or internal '..'. This + option disables that behavior. *Note absolute::. + +'--acls' + Enable POSIX ACLs support. *Note acls: Extended File Attributes. + +'--after-date' + + (See '--newer', *note after::) + +'--anchored' + A pattern must match an initial subsequence of the name's + components. *Note controlling pattern-matching::. + +'--atime-preserve' +'--atime-preserve=replace' +'--atime-preserve=system' + + Attempt to preserve the access time of files when reading them. + This option currently is effective only on files that you own, + unless you have superuser privileges. + + '--atime-preserve=replace' remembers the access time of a file + before reading it, and then restores the access time afterwards. + This may cause problems if other programs are reading the file at + the same time, as the times of their accesses will be lost. On + most platforms restoring the access time also requires 'tar' to + restore the data modification time too, so this option may also + cause problems if other programs are writing the file at the same + time ('tar' attempts to detect this situation, but cannot do so + reliably due to race conditions). Worse, on most platforms + restoring the access time also updates the status change time, + which means that this option is incompatible with incremental + backups. + + '--atime-preserve=system' avoids changing time stamps on files, + without interfering with time stamp updates caused by other + programs, so it works better with incremental backups. However, it + requires a special 'O_NOATIME' option from the underlying operating + and file system implementation, and it also requires that searching + directories does not update their access times. As of this writing + (November 2005) this works only with Linux, and only with Linux + kernels 2.6.8 and later. Worse, there is currently no reliable way + to know whether this feature actually works. Sometimes 'tar' knows + that it does not work, and if you use '--atime-preserve=system' + then 'tar' complains and exits right away. But other times 'tar' + might think that the option works when it actually does not. + + Currently '--atime-preserve' with no operand defaults to + '--atime-preserve=replace', but this may change in the future as + support for '--atime-preserve=system' improves. + + If your operating or file system does not support + '--atime-preserve=system', you might be able to preserve access + times reliably by using the 'mount' command. For example, you can + mount the file system read-only, or access the file system via a + read-only loopback mount, or use the 'noatime' mount option + available on some systems. However, mounting typically requires + superuser privileges and can be a pain to manage. + +'--auto-compress' +'-a' + + During a '--create' operation, enables automatic compressed format + recognition based on the archive suffix. The effect of this option + is cancelled by '--no-auto-compress'. *Note gzip::. + +'--backup=BACKUP-TYPE' + + Rather than deleting files from the file system, 'tar' will back + them up using simple or numbered backups, depending upon + BACKUP-TYPE. *Note backup::. + +'--block-number' +'-R' + + With this option present, 'tar' prints error messages for read + errors with the block number in the archive file. *Note + block-number::. + +'--blocking-factor=BLOCKING' +'-b BLOCKING' + + Sets the blocking factor 'tar' uses to BLOCKING x 512 bytes per + record. *Note Blocking Factor::. + +'--bzip2' +'-j' + + This option tells 'tar' to read or write archives through 'bzip2'. + *Note gzip::. + +'--check-device' + Check device numbers when creating a list of modified files for + incremental archiving. This is the default. *Note device + numbers::, for a detailed description. + +'--checkpoint[=NUMBER]' + + This option directs 'tar' to print periodic checkpoint messages as + it reads through the archive. It is intended for when you want a + visual indication that 'tar' is still running, but don't want to + see '--verbose' output. You can also instruct 'tar' to execute a + list of actions on each checkpoint, see '--checkpoint-action' + below. For a detailed description, see *note checkpoints::. + +'--checkpoint-action=ACTION' + Instruct 'tar' to execute an action upon hitting a breakpoint. + Here we give only a brief outline. *Note checkpoints::, for a + complete description. + + The ACTION argument can be one of the following: + + 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 of the checkpoint. This is the default. + + echo=STRING + Display STRING on the standard error. Before output, the + string is subject to meta-character expansion. + + exec=COMMAND + Execute the given COMMAND. + + sleep=TIME + Wait for TIME seconds. + + ttyout=STRING + Output STRING on the current console ('/dev/tty'). + + Several '--checkpoint-action' options can be specified. The + supplied actions will be executed in order of their appearance in + the command line. + + Using '--checkpoint-action' without '--checkpoint' assumes default + checkpoint frequency of one checkpoint per 10 records. + +'--check-links' +'-l' + If this option was given, 'tar' will check the number of links + dumped for each processed file. If this number does not match the + total number of hard links for the file, a warning message will be + output (1). + + *Note hard links::. + +'--compress' +'--uncompress' +'-Z' + + 'tar' will use the 'compress' program when reading or writing the + archive. This allows you to directly act on archives while saving + space. *Note gzip::. + +'--clamp-mtime' + + (See '--mtime'.) + +'--confirmation' + + (See '--interactive'.) *Note interactive::. + +'--delay-directory-restore' + + Delay setting modification times and permissions of extracted + directories until the end of extraction. *Note Directory + Modification Times and Permissions::. + +'--dereference' +'-h' + + When reading or writing a file to be archived, 'tar' accesses the + file that a symbolic link points to, rather than the symlink + itself. *Note dereference::. + +'--directory=DIR' +'-C DIR' + + When this option is specified, 'tar' will change its current + directory to DIR before performing any operations. When this + option is used during archive creation, it is order sensitive. + *Note directory::. + +'--exclude=PATTERN' + + When performing operations, 'tar' will skip files that match + PATTERN. *Note exclude::. + +'--exclude-backups' + Exclude backup and lock files. *Note exclude-backups: exclude. + +'--exclude-from=FILE' +'-X FILE' + + Similar to '--exclude', except 'tar' will use the list of patterns + in the file FILE. *Note exclude::. + +'--exclude-caches' + + Exclude from dump any directory containing a valid cache directory + tag file, but still dump the directory node and the tag file + itself. + + *Note exclude-caches: exclude. + +'--exclude-caches-under' + + Exclude from dump any directory containing a valid cache directory + tag file, but still dump the directory node itself. + + *Note exclude::. + +'--exclude-caches-all' + + Exclude from dump any directory containing a valid cache directory + tag file. *Note exclude::. + +'--exclude-ignore=FILE' + Before dumping a directory, 'tar' checks if it contains FILE. If + so, exclusion patterns are read from this file. The patterns + affect only the directory itself. *Note exclude::. + +'--exclude-ignore-recursive=FILE' + Before dumping a directory, 'tar' checks if it contains FILE. If + so, exclusion patterns are read from this file. The patterns + affect the directory and all itssubdirectories. *Note exclude::. + +'--exclude-tag=FILE' + + Exclude from dump any directory containing file named FILE, but + dump the directory node and FILE itself. *Note exclude-tag: + exclude. + +'--exclude-tag-under=FILE' + + Exclude from dump the contents of any directory containing file + named FILE, but dump the directory node itself. *Note + exclude-tag-under: exclude. + +'--exclude-tag-all=FILE' + + Exclude from dump any directory containing file named FILE. *Note + exclude-tag-all: exclude. + +'--exclude-vcs' + + Exclude from dump directories and files, that are internal for some + widely used version control systems. + + *Note exclude-vcs::. + +'--exclude-vcs-ignores' + Exclude files that match patterns read from VCS-specific ignore + files. Supported files are: '.cvsignore', '.gitignore', + '.bzrignore', and '.hgignore'. The semantics of each file is the + same as for the corresponding VCS, e.g. patterns read from + '.gitignore' affect the directory and all its subdirectories. + *Note exclude-vcs-ignores::. + +'--file=ARCHIVE' +'-f ARCHIVE' + + 'tar' will use the file ARCHIVE as the 'tar' archive it performs + operations on, rather than 'tar''s compilation dependent default. + *Note file tutorial::. + +'--files-from=FILE' +'-T FILE' + + 'tar' will use the contents of FILE as a list of archive members or + files to operate on, in addition to those specified on the + command-line. *Note files::. + +'--force-local' + + Forces 'tar' to interpret the file name given to '--file' as a + local file, even if it looks like a remote tape drive name. *Note + local and remote archives::. + +'--format=FORMAT' +'-H FORMAT' + + Selects output archive format. FORMAT may be one of the following: + + 'v7' + Creates an archive that is compatible with Unix V7 'tar'. + + 'oldgnu' + Creates an archive that is compatible with GNU 'tar' version + 1.12 or earlier. + + 'gnu' + Creates archive in GNU tar 1.13 format. Basically it is the + same as 'oldgnu' with the only difference in the way it + handles long numeric fields. + + 'ustar' + Creates a POSIX.1-1988 compatible archive. + + 'posix' + Creates a POSIX.1-2001 archive. + + *Note Formats::, for a detailed discussion of these formats. + +'--full-time' + This option instructs 'tar' to print file times to their full + resolution. Usually this means 1-second resolution, but that + depends on the underlying file system. The '--full-time' option + takes effect only when detailed output (verbosity level 2 or + higher) has been requested using the '--verbose' option, e.g., when + listing or extracting archives: + + $ tar -t -v --full-time -f archive.tar + + or, when creating an archive: + + $ tar -c -vv --full-time -f archive.tar . + + Notice, thar when creating the archive you need to specify + '--verbose' twice to get a detailed output (*note verbose + tutorial::). + +'--group=GROUP' + + Files added to the 'tar' archive will have a group ID of GROUP, + rather than the group from the source file. GROUP can specify a + symbolic name, or a numeric ID, or both as NAME:ID. *Note + override::. + + Also see the '--group-map' option and comments for the + '--owner=USER' option. + +'--group-map=FILE' + + Read owner group translation map from FILE. This option allows to + translate only certain group names and/or UIDs. *Note override::, + for a detailed description. When used together with '--group' + option, the latter affects only those files whose owner group is + not listed in the FILE. + + This option does not affect extraction from archives. + +'--gzip' +'--gunzip' +'--ungzip' +'-z' + + This option tells 'tar' to read or write archives through 'gzip', + allowing 'tar' to directly operate on several kinds of compressed + archives transparently. *Note gzip::. + +'--hard-dereference' + When creating an archive, dereference hard links and store the + files they refer to, instead of creating usual hard link members. + + *Note hard links::. + +'--help' +'-?' + + 'tar' will print out a short message summarizing the operations and + options to 'tar' and exit. *Note help::. + +'--hole-detection=METHOD' + Use METHOD to detect holes in sparse files. This option implies + '--sparse'. Valid methods are 'seek' and 'raw'. Default is 'seek' + with fallback to 'raw' when not applicable. *Note sparse::. + +'--ignore-case' + Ignore case when matching member or file names with patterns. + *Note controlling pattern-matching::. + +'--ignore-command-error' + Ignore exit codes of subprocesses. *Note Writing to an External + Program::. + +'--ignore-failed-read' + + Do not exit unsuccessfully merely because an unreadable file was + encountered. *Note Ignore Failed Read::. + +'--ignore-zeros' +'-i' + + With this option, 'tar' will ignore zeroed blocks in the archive, + which normally signals EOF. *Note Reading::. + +'--incremental' +'-G' + + Informs 'tar' that it is working with an old GNU-format incremental + backup archive. It is intended primarily for backwards + compatibility only. *Note Incremental Dumps::, for a detailed + discussion of incremental archives. + +'--index-file=FILE' + + Send verbose output to FILE instead of to standard output. + +'--info-script=COMMAND' +'--new-volume-script=COMMAND' +'-F COMMAND' + + When 'tar' is performing multi-tape backups, COMMAND is run at the + end of each tape. If it exits with nonzero status, 'tar' fails + immediately. *Note info-script::, for a detailed discussion of + this feature. + +'--interactive' +'--confirmation' +'-w' + + Specifies that 'tar' should ask the user for confirmation before + performing potentially destructive options, such as overwriting + files. *Note interactive::. + +'--keep-directory-symlink' + + This option changes the behavior of tar when it encounters a + symlink with the same name as the directory that it is about to + extract. By default, in this case tar would first remove the + symlink and then proceed extracting the directory. + + The '--keep-directory-symlink' option disables this behavior and + instructs tar to follow symlinks to directories when extracting + from the archive. + + It is mainly intended to provide compatibility with the Slackware + installation scripts. + +'--keep-newer-files' + + Do not replace existing files that are newer than their archive + copies when extracting files from an archive. + +'--keep-old-files' +'-k' + + Do not overwrite existing files when extracting files from an + archive. Return error if such files exist. See also *note + --skip-old-files::. + + *Note Keep Old Files::. + +'--label=NAME' +'-V NAME' + + When creating an archive, instructs 'tar' to write NAME as a name + record in the archive. When extracting or listing archives, 'tar' + will only operate on archives that have a label matching the + pattern specified in NAME. *Note Tape Files::. + +'--level=N' + Force incremental backup of level N. As of GNU 'tar' version 1.29, + the option '--level=0' truncates the snapshot file, thereby forcing + the level 0 dump. Other values of N are effectively ignored. + *Note --level=0::, for details and examples. + + The use of this option is valid only in conjunction with the + '--listed-incremental' option. *Note Incremental Dumps::, for a + detailed description. + +'--listed-incremental=SNAPSHOT-FILE' +'-g SNAPSHOT-FILE' + + During a '--create' operation, specifies that the archive that + 'tar' creates is a new GNU-format incremental backup, using + SNAPSHOT-FILE to determine which files to backup. With other + operations, informs 'tar' that the archive is in incremental + format. *Note Incremental Dumps::. + +'--lzip' + + This option tells 'tar' to read or write archives through 'lzip'. + *Note gzip::. + +'--lzma' + + This option tells 'tar' to read or write archives through 'lzma'. + *Note gzip::. + +'--lzop' + + This option tells 'tar' to read or write archives through 'lzop'. + *Note gzip::. + +'--mode=PERMISSIONS' + + When adding files to an archive, 'tar' will use PERMISSIONS for the + archive members, rather than the permissions from the files. + PERMISSIONS can be specified either as an octal number or as + symbolic permissions, like with 'chmod'. *Note override::. + +'--mtime=DATE' + + When adding files to an archive, 'tar' will use DATE as the + modification time of members when creating archives, instead of + their actual modification times. The value of DATE can be either a + textual date representation (*note Date input formats::) or a name + of the existing file, starting with '/' or '.'. In the latter + case, the modification time of that file is used. *Note + override::. + + When '--clamp-mtime' is also specified, files with modification + times earlier than DATE will retain their actual modification + times, and DATE will only be used for files whose modification + times are later than DATE. + +'--multi-volume' +'-M' + + Informs 'tar' that it should create or otherwise operate on a + multi-volume 'tar' archive. *Note Using Multiple Tapes::. + +'--new-volume-script' + + (see '--info-script') + +'--newer=DATE' +'--after-date=DATE' +'-N' + + When creating an archive, 'tar' will only add files that have + changed since DATE. If DATE begins with '/' or '.', it is taken to + be the name of a file whose data modification time specifies the + date. *Note after::. + +'--newer-mtime=DATE' + + Like '--newer', but add only files whose contents have changed (as + opposed to just '--newer', which will also back up files for which + any status information has changed). *Note after::. + +'--no-acls' + Disable the POSIX ACLs support. *Note acls: Extended File + Attributes. + +'--no-anchored' + An exclude pattern can match any subsequence of the name's + components. *Note controlling pattern-matching::. + +'--no-auto-compress' + + Disables automatic compressed format recognition based on the + archive suffix. *Note --auto-compress::. *Note gzip::. + +'--no-check-device' + Do not check device numbers when creating a list of modified files + for incremental archiving. *Note device numbers::, for a detailed + description. + +'--no-delay-directory-restore' + + Modification times and permissions of extracted directories are set + when all files from this directory have been extracted. This is + the default. *Note Directory Modification Times and Permissions::. + +'--no-ignore-case' + Use case-sensitive matching. *Note controlling pattern-matching::. + +'--no-ignore-command-error' + Print warnings about subprocesses that terminated with a nonzero + exit code. *Note Writing to an External Program::. + +'--no-null' + + If the '--null' option was given previously, this option cancels + its effect, so that any following '--files-from' options will + expect their file lists to be newline-terminated. + +'--no-overwrite-dir' + + Preserve metadata of existing directories when extracting files + from an archive. *Note Overwrite Old Files::. + +'--no-quote-chars=STRING' + Remove characters listed in STRING from the list of quoted + characters set by the previous '--quote-chars' option (*note + quoting styles::). + +'--no-recursion' + + With this option, 'tar' will not recurse into directories. *Note + recurse::. + +'--no-same-owner' +'-o' + + When extracting an archive, do not attempt to preserve the owner + specified in the 'tar' archive. This the default behavior for + ordinary users. + +'--no-same-permissions' + + When extracting an archive, subtract the user's umask from files + from the permissions specified in the archive. This is the default + behavior for ordinary users. + +'--no-seek' + + The archive media does not support seeks to arbitrary locations. + Usually 'tar' determines automatically whether the archive can be + seeked or not. Use this option to disable this mechanism. + +'--no-selinux' + Disable SELinux context support. *Note SELinux: Extended File + Attributes. + +'--no-unquote' + Treat all input file or member names literally, do not interpret + escape sequences. *Note input name quoting::. + +'--no-verbatim-files-from' + + Instructs GNU 'tar' to treat each line read from a file list as if + it were supplied in the command line. I.e., leading and trailing + whitespace is removed and, if the result begins with a dash, it is + treated as a GNU 'tar' command line option. + + This is default behavior. This option is provided as a way to + restore it after '--verbatim-files-from' option. + + It is implied by the '--no-null' option. + + *Note no-verbatim-files-from::. + +'--no-wildcards' + Do not use wildcards. *Note controlling pattern-matching::. + +'--no-wildcards-match-slash' + Wildcards do not match '/'. *Note controlling pattern-matching::. + +'--no-xattrs' + Disable extended attributes support. *Note xattrs: Extended File + Attributes. + +'--null' + + When 'tar' is using the '--files-from' option, this option + instructs 'tar' to expect file names terminated with NUL, and to + process file names verbatim. + + This means that 'tar' correctly works with file names that contain + newlines or begin with a dash. + + *Note nul::. + + See also *note verbatim-files-from::. + +'--numeric-owner' + + This option will notify 'tar' that it should use numeric user and + group IDs when creating a 'tar' file, rather than names. *Note + Attributes::. + +'-o' + The function of this option depends on the action 'tar' is + performing. When extracting files, '-o' is a synonym for + '--no-same-owner', i.e., it prevents 'tar' from restoring ownership + of files being extracted. + + When creating an archive, it is a synonym for '--old-archive'. + This behavior is for compatibility with previous versions of GNU + 'tar', and will be removed in future releases. + + *Note Changes::, for more information. + +'--occurrence[=NUMBER]' + + This option can be used in conjunction with one of the subcommands + '--delete', '--diff', '--extract' or '--list' when a list of files + is given either on the command line or via '-T' option. + + This option instructs 'tar' to process only the NUMBERth occurrence + of each named file. NUMBER defaults to 1, so + + tar -x -f archive.tar --occurrence filename + + will extract the first occurrence of the member 'filename' from + 'archive.tar' and will terminate without scanning to the end of the + archive. + +'--old-archive' + Synonym for '--format=v7'. + +'--one-file-system' + Used when creating an archive. Prevents 'tar' from recursing into + directories that are on different file systems from the current + directory. + +'--one-top-level[=DIR]' + Tells 'tar' to create a new directory beneath the extraction + directory (or the one passed to '-C') and use it to guard against + tarbombs. In the absence of DIR argument, the name of the new + directory will be equal to the base name of the archive (file name + minus the archive suffix, if recognized). Any member names that do + not begin with that directory name (after transformations from + '--transform' and '--strip-components') will be prefixed with it. + Recognized file name suffixes are '.tar', and any compression + suffixes recognizable by *Note --auto-compress::. + +'--overwrite' + + Overwrite existing files and directory metadata when extracting + files from an archive. *Note Overwrite Old Files::. + +'--overwrite-dir' + + Overwrite the metadata of existing directories when extracting + files from an archive. *Note Overwrite Old Files::. + +'--owner=USER' + + Specifies that 'tar' should use USER as the owner of members when + creating archives, instead of the user associated with the source + file. USER can specify a symbolic name, or a numeric ID, or both + as NAME:ID. *Note override::. + + This option does not affect extraction from archives. See also + '--owner-map', below. + +'--owner-map=FILE' + + Read owner translation map from FILE. This option allows to + translate only certain owner names or UIDs. *Note override::, for + a detailed description. When used together with '--owner' option, + the latter affects only those files whose owner is not listed in + the FILE. + + This option does not affect extraction from archives. + +'--pax-option=KEYWORD-LIST' + This option enables creation of the archive in POSIX.1-2001 format + (*note posix::) and modifies the way 'tar' handles the extended + header keywords. KEYWORD-LIST is a comma-separated list of keyword + options. *Note PAX keywords::, for a detailed discussion. + +'--portability' +'--old-archive' + Synonym for '--format=v7'. + +'--posix' + Same as '--format=posix'. + +'--preserve-order' + + (See '--same-order'; *note Reading::.) + +'--preserve-permissions' +'--same-permissions' +'-p' + + When 'tar' is extracting an archive, it normally subtracts the + users' umask from the permissions specified in the archive and uses + that number as the permissions to create the destination file. + Specifying this option instructs 'tar' that it should use the + permissions directly from the archive. *Note Setting Access + Permissions::. + +'--quote-chars=STRING' + Always quote characters from STRING, even if the selected quoting + style would not quote them (*note quoting styles::). + +'--quoting-style=STYLE' + Set quoting style to use when printing member and file names (*note + quoting styles::). Valid STYLE values are: 'literal', 'shell', + 'shell-always', 'c', 'escape', 'locale', and 'clocale'. Default + quoting style is 'escape', unless overridden while configuring the + package. + +'--read-full-records' +'-B' + + Specifies that 'tar' should reblock its input, for reading from + pipes on systems with buggy implementations. *Note Reading::. + +'--record-size=SIZE[SUF]' + + Instructs 'tar' to use SIZE bytes per record when accessing the + archive. The argument can be suffixed with a "size suffix", e.g. + '--record-size=10K' for 10 Kilobytes. *Note Table 9.1: + size-suffixes, for a list of valid suffixes. *Note Blocking + Factor::, for a detailed description of this option. + +'--recursion' + + With this option, 'tar' recurses into directories (default). *Note + recurse::. + +'--recursive-unlink' + + Remove existing directory hierarchies before extracting directories + of the same name from the archive. *Note Recursive Unlink::. + +'--remove-files' + + Directs 'tar' to remove the source file from the file system after + appending it to an archive. *Note remove files::. + +'--restrict' + + Disable use of some potentially harmful 'tar' options. Currently + this option disables shell invocation from multi-volume menu (*note + Using Multiple Tapes::). + +'--rmt-command=CMD' + + Notifies 'tar' that it should use CMD instead of the default + '/usr/libexec/rmt' (*note Remote Tape Server::). + +'--rsh-command=CMD' + + Notifies 'tar' that is should use CMD to communicate with remote + devices. *Note Device::. + +'--same-order' +'--preserve-order' +'-s' + + This option is an optimization for 'tar' when running on machines + with small amounts of memory. It informs 'tar' that the list of + file arguments has already been sorted to match the order of files + in the archive. *Note Reading::. + +'--same-owner' + + When extracting an archive, 'tar' will attempt to preserve the + owner specified in the 'tar' archive with this option present. + This is the default behavior for the superuser; this option has an + effect only for ordinary users. *Note Attributes::. + +'--same-permissions' + + (See '--preserve-permissions'; *note Setting Access Permissions::.) + +'--seek' +'-n' + + Assume that the archive media supports seeks to arbitrary + locations. Usually 'tar' determines automatically whether the + archive can be seeked or not. This option is intended for use in + cases when such recognition fails. It takes effect only if the + archive is open for reading (e.g. with '--list' or '--extract' + options). + +'--selinux' + Enable the SELinux context support. *Note selinux: Extended File + Attributes. + +'--show-defaults' + + Displays the default options used by 'tar' and exits successfully. + This option is intended for use in shell scripts. Here is an + example of 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 + + Notice, that this option outputs only one line. The example output + above has been split to fit page boundaries. *Note defaults::. + +'--show-omitted-dirs' + + Instructs 'tar' to mention the directories it is skipping when + operating on a 'tar' archive. *Note show-omitted-dirs::. + +'--show-snapshot-field-ranges' + + Displays the range of values allowed by this version of 'tar' for + each field in the snapshot file, then exits successfully. *Note + Snapshot Files::. + +'--show-transformed-names' +'--show-stored-names' + + Display file or member names after applying any transformations + (*note transform::). In particular, when used in conjunction with + one of the archive creation operations it instructs 'tar' to list + the member names stored in the archive, as opposed to the actual + file names. *Note listing member and file names::. + +'--skip-old-files' + + Do not overwrite existing files when extracting files from an + archive. *Note Keep Old Files::. + + This option differs from '--keep-old-files' in that it does not + treat such files as an error, instead it just silently avoids + overwriting them. + + The '--warning=existing-file' option can be used together with this + option to produce warning messages about existing old files (*note + warnings::). + +'--sort=ORDER' + Specify the directory sorting order when reading directories. + ORDER may be one of the following: + + 'none' + No directory sorting is performed. This is the default. + + 'name' + Sort the directory entries on name. The operating system may + deliver directory entries in a more or less random order, and + sorting them makes archive creation reproducible. + + 'inode' + Sort the directory entries on inode number. Sorting + directories on inode number may reduce the amount of disk seek + operations when creating an archive for some file systems. + +'--sparse' +'-S' + + Invokes a GNU extension when adding files to an archive that + handles sparse files efficiently. *Note sparse::. + +'--sparse-version=VERSION' + + Specifies the "format version" to use when archiving sparse files. + Implies '--sparse'. *Note sparse::. For the description of the + supported sparse formats, *Note Sparse Formats::. + +'--starting-file=NAME' +'-K NAME' + + This option affects extraction only; 'tar' will skip extracting + files in the archive until it finds one that matches NAME. *Note + Scarce::. + +'--strip-components=NUMBER' + Strip given NUMBER of leading components from file names before + extraction. For example, if archive 'archive.tar' contained + '/some/file/name', then running + + tar --extract --file archive.tar --strip-components=2 + + would extract this file to file 'name'. + + *Note transform::. + +'--suffix=SUFFIX' + + Alters the suffix 'tar' uses when backing up files from the default + '~'. *Note backup::. + +'--tape-length=NUM[SUF]' +'-L NUM[SUF]' + + Specifies the length of tapes that 'tar' is writing as being + NUM x 1024 bytes long. If optional SUF is given, it specifies a + multiplicative factor to be used instead of 1024. For example, + '-L2M' means 2 megabytes. *Note Table 9.1: size-suffixes, for a + list of allowed suffixes. *Note Using Multiple Tapes::, for a + detailed discussion of this option. + +'--test-label' + + Reads the volume label. If an argument is specified, test whether + it matches the volume label. *Note --test-label option::. + +'--to-command=COMMAND' + + During extraction 'tar' will pipe extracted files to the standard + input of COMMAND. *Note Writing to an External Program::. + +'--to-stdout' +'-O' + + During extraction, 'tar' will extract files to stdout rather than + to the file system. *Note Writing to Standard Output::. + +'--totals[=SIGNO]' + + Displays the total number of bytes transferred when processing an + archive. If an argument is given, these data are displayed on + request, when signal SIGNO is delivered to 'tar'. *Note totals::. + +'--touch' +'-m' + + Sets the data modification time of extracted files to the + extraction time, rather than the data modification time stored in + the archive. *Note Data Modification Times::. + +'--transform=SED-EXPR' +'--xform=SED-EXPR' + Transform file or member names using 'sed' replacement expression + SED-EXPR. For example, + + $ tar cf archive.tar --transform 's,^\./,usr/,' . + + will add to 'archive' files from the current working directory, + replacing initial './' prefix with 'usr/'. For the detailed + discussion, *Note transform::. + + To see transformed member names in verbose listings, use + '--show-transformed-names' option (*note show-transformed-names::). + +'--uncompress' + + (See '--compress', *note gzip::) + +'--ungzip' + + (See '--gzip', *note gzip::) + +'--unlink-first' +'-U' + + Directs 'tar' to remove the corresponding file from the file system + before extracting it from the archive. *Note Unlink First::. + +'--unquote' + Enable unquoting input file or member names (default). *Note input + name quoting::. + +'--use-compress-program=PROG' +'-I=PROG' + + Instructs 'tar' to access the archive through PROG, which is + presumed to be a compression program of some sort. *Note gzip::. + +'--utc' + + Display file modification dates in UTC. This option implies + '--verbose'. + +'--verbatim-files-from' + + Instructs GNU 'tar' to treat each line read from a file list as a + file name, even if it starts with a dash. + + File lists are supplied with the '--files-from' ('-T') option. By + default, each line read from a file list is first trimmed off the + leading and trailing whitespace and, if the result begins with a + dash, it is treated as a GNU 'tar' command line option. + + Use the '--verbatim-files-from' option to disable this special + handling. This facilitates the use of 'tar' with file lists + created by 'file' command. + + This option affects all '--files-from' options that occur after it + in the command line. Its effect is reverted by the + '--no-verbatim-files-from' option. + + This option is implied by the '--null' option. + + *Note verbatim-files-from::. + +'--verbose' +'-v' + + Specifies that 'tar' should be more verbose about the operations it + is performing. This option can be specified multiple times for + some operations to increase the amount of information displayed. + *Note verbose::. + +'--verify' +'-W' + + Verifies that the archive was correctly written when creating an + archive. *Note verify::. + +'--version' + + Print information about the program's name, version, origin and + legal status, all on standard output, and then exit successfully. + *Note help::. + +'--volno-file=FILE' + + Used in conjunction with '--multi-volume'. 'tar' will keep track + of which volume of a multi-volume archive it is working in FILE. + *Note volno-file::. + +'--warning=KEYWORD' + + Enable or disable warning messages identified by KEYWORD. The + messages are suppressed if KEYWORD is prefixed with 'no-'. *Note + warnings::. + +'--wildcards' + Use wildcards when matching member names with patterns. *Note + controlling pattern-matching::. + +'--wildcards-match-slash' + Wildcards match '/'. *Note controlling pattern-matching::. + +'--xattrs' + Enable extended attributes support. *Note xattrs: Extended File + Attributes. + +'--xattrs-exclude=PATTERN' + Specify exclude pattern for xattr keys. *Note xattrs-exclude: + Extended File Attributes. + +'--xattrs-include=PATTERN.' + Specify include pattern for xattr keys. PATTERN is a POSIX regular + expression, e.g. '--xattrs-exclude='^user\.'' to include only + attributes from the user namespace. *Note xattrs-include: Extended + File Attributes. + +'--xz' +'-J' + Use 'xz' for compressing or decompressing the archives. *Note + gzip::. + + ---------- Footnotes ---------- + + (1) Earlier versions of GNU 'tar' understood '-l' as a synonym for +'--one-file-system'. The current semantics, which complies to UNIX98, +was introduced with version 1.15.91. *Note Changes::, for more +information. + + +File: tar.info, Node: Short Option Summary, Next: Position-Sensitive Options, Prev: Option Summary, Up: All Options + +3.4.3 Short Options Cross Reference +----------------------------------- + +Here is an alphabetized list of all of the short option forms, matching +them with the equivalent long option. + +Short Option Reference + +-------------------------------------------------------------------------- +-A *note --concatenate::. + +-B *note --read-full-records::. + +-C *note --directory::. + +-F *note --info-script::. + +-G *note --incremental::. + +-J *note --xz::. + +-K *note --starting-file::. + +-L *note --tape-length::. + +-M *note --multi-volume::. + +-N *note --newer::. + +-O *note --to-stdout::. + +-P *note --absolute-names::. + +-R *note --block-number::. + +-S *note --sparse::. + +-T *note --files-from::. + +-U *note --unlink-first::. + +-V *note --label::. + +-W *note --verify::. + +-X *note --exclude-from::. + +-Z *note --compress::. + +-b *note --blocking-factor::. + +-c *note --create::. + +-d *note --compare::. + +-f *note --file::. + +-g *note --listed-incremental::. + +-h *note --dereference::. + +-i *note --ignore-zeros::. + +-j *note --bzip2::. + +-k *note --keep-old-files::. + +-l *note --check-links::. + +-m *note --touch::. + +-o When creating, *note --no-same-owner::, when extracting + -- *note --portability::. + + The latter usage is deprecated. It is retained for + compatibility with the earlier versions of GNU 'tar'. + In future releases '-o' will be equivalent to + '--no-same-owner' only. + +-p *note --preserve-permissions::. + +-r *note --append::. + +-s *note --same-order::. + +-t *note --list::. + +-u *note --update::. + +-v *note --verbose::. + +-w *note --interactive::. + +-x *note --extract::. + +-z *note --gzip::. + + + +File: tar.info, Node: Position-Sensitive Options, Prev: Short Option Summary, Up: All Options + +3.4.4 Position-Sensitive Options +-------------------------------- + +Some GNU 'tar' options can be used multiple times in the same invocation +and affect all arguments that appear after them. These are options that +control how file names are selected and what kind of pattern matching is +used. + + The most obvious example is the '-C' option. It instructs 'tar' to +change to the directory given as its argument prior to processing the +rest of command line (*note directory::). Thus, in the following +command: + + tar -c -f a.tar -C /etc passwd -C /var log spool + +the file 'passwd' will be searched in the directory '/etc', and files +'log' and 'spool' - in '/var'. + + These options can also be used in a file list supplied with the +'--files-from' ('-T') option (*note files::). In that case they affect +all files (patterns) appearing in that file after them and remain in +effect for any arguments processed after that file. For example, if the +file 'list.txt' contained: + + README + -C src + main.c + +and 'tar' were invoked as follows: + + tar -c -f a.tar -T list.txt Makefile + +then the file 'README' would be looked up in the current working +directory, and files 'main.c' and 'Makefile' would be looked up in the +directory 'src'. + + Many options can be prefixed with '--no-' to cancel the effect of the +original option. + + For example, the '--recursion' option controls whether to recurse in +the subdirectories. It's counterpart '--no-recursion' disables this. +Consider the command below. It will store in the archive the directory +'/usr' with all files and directories that are located in it as well as +any files and directories in '/var', without recursing into them(1): + + tar -cf a.tar --recursion /usr --no-recursion /var/* + + The following table summarizes all position-sensitive options. + +'--directory=DIR' +'-C DIR' + *Note directory::. + +'--null' +'--no-null' + *Note nul::. + +'--unquote' +'--no-unquote' + *Note input name quoting::. + +'--verbatim-files-from' +'--no-verbatim-files-from' + *Note verbatim-files-from::. + +'--recursion' +'--no-recursion' + *Note recurse::. + +'--anchored' +'--no-anchored' + *Note anchored patterns::. + +'--ignore-case' +'--no-ignore-case' + *Note case-insensitive matches::. + +'--wildcards' +'--no-wildcards' + *Note controlling pattern-matching::. + +'--wildcards-match-slash' +'--no-wildcards-match-slash' + *Note controlling pattern-matching::. + +'--exclude' + *Note exclude::. + +'--exclude-from' +'-X' +'--exclude-caches' +'--exclude-caches-under' +'--exclude-caches-all' +'--exclude-tag' +'--exclude-ignore' +'--exclude-ignore-recursive' +'--exclude-tag-under' +'--exclude-tag-all' +'--exclude-vcs' +'--exclude-vcs-ignores' +'--exclude-backups' + *Note exclude::. + + ---------- Footnotes ---------- + + (1) The '--recursion' option is the default and is used here for +clarity. The same example can be written as: + + tar -cf a.tar /usr --no-recursion /var/* + + +File: tar.info, Node: help, Next: defaults, Prev: All Options, Up: tar invocation + +3.5 GNU 'tar' documentation +=========================== + +Being careful, the first thing is really checking that you are using GNU +'tar', indeed. The '--version' option causes 'tar' to print information +about its name, version, origin and legal status, all on standard +output, and then exit successfully. For example, 'tar --version' might +print: + + tar (GNU tar) 1.29 + Copyright (C) 2013-2016 Free Software Foundation, Inc. + License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>. + This is free software: you are free to change and redistribute it. + There is NO WARRANTY, to the extent permitted by law. + + Written by John Gilmore and Jay Fenlason. + +The first occurrence of 'tar' in the result above is the program name in +the package (for example, 'rmt' is another program), while the second +occurrence of 'tar' is the name of the package itself, containing +possibly many programs. The package is currently named 'tar', after the +name of the main program it contains(1). + + Another thing you might want to do is checking the spelling or +meaning of some particular 'tar' option, without resorting to this +manual, for once you have carefully read it. GNU 'tar' has a short help +feature, triggerable through the '--help' option. By using this option, +'tar' will print a usage message listing all available options on +standard output, then exit successfully, without doing anything else and +ignoring all other options. Even if this is only a brief summary, it +may be several screens long. So, if you are not using some kind of +scrollable window, you might prefer to use something like: + + $ tar --help | less + +presuming, here, that you like using 'less' for a pager. Other popular +pagers are 'more' and 'pg'. If you know about some KEYWORD which +interests you and do not want to read all the '--help' output, another +common idiom is doing: + + tar --help | grep KEYWORD + +for getting only the pertinent lines. Notice, however, that some 'tar' +options have long description lines and the above command will list only +the first of them. + + The exact look of the option summary displayed by 'tar --help' is +configurable. *Note Configuring Help Summary::, for a detailed +description. + + If you only wish to check the spelling of an option, running 'tar +--usage' may be a better choice. This will display a terse list of +'tar' options without accompanying explanations. + + The short help output is quite succinct, and you might have to get +back to the full documentation for precise points. If you are reading +this paragraph, you already have the 'tar' manual in some form. This +manual is available in a variety of forms from +<http://www.gnu.org/software/tar/manual>. It may be printed out of the +GNU 'tar' distribution, provided you have TeX already installed +somewhere, and a laser printer around. Just configure the distribution, +execute the command 'make dvi', then print 'doc/tar.dvi' the usual way +(contact your local guru to know how). If GNU 'tar' has been +conveniently installed at your place, this manual is also available in +interactive, hypertextual form as an Info file. Just call 'info tar' +or, if you do not have the 'info' program handy, use the Info reader +provided within GNU Emacs, calling 'tar' from the main Info menu. + + There is currently no 'man' page for GNU 'tar'. If you observe such +a 'man' page on the system you are running, either it does not belong to +GNU 'tar', 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 bear in mind that the authoritative source of information +about GNU 'tar' is this Texinfo documentation. + + ---------- Footnotes ---------- + + (1) There are plans to merge the 'cpio' and 'tar' packages into a +single one which would be called 'paxutils'. So, who knows if, one of +this days, the '--version' would not output 'tar (GNU paxutils) 3.2'. + + +File: tar.info, Node: defaults, Next: verbose, Prev: help, Up: tar invocation + +3.6 Obtaining GNU 'tar' default values +====================================== + +GNU 'tar' has some predefined defaults that are used when you do not +explicitly specify another values. To obtain a list of such defaults, +use '--show-defaults' option. This will output the values in the form +of 'tar' command line options: + + $ tar --show-defaults + --format=gnu -f- -b20 --quoting-style=escape + --rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh + +Notice, that this option outputs only one line. The example output +above has been split to fit page boundaries. + +The above output shows that this version of GNU 'tar' defaults to using +'gnu' archive format (*note Formats::), it uses standard output as the +archive, if no '--file' option has been given (*note file tutorial::), +the default blocking factor is 20 (*note Blocking Factor::). It also +shows the default locations where 'tar' will look for 'rmt' and 'rsh' +binaries. + + +File: tar.info, Node: verbose, Next: checkpoints, Prev: defaults, Up: tar invocation + +3.7 Checking 'tar' progress +=========================== + +Typically, 'tar' performs most operations without reporting any +information to the user except error messages. When using 'tar' with +many options, particularly ones with complicated or difficult-to-predict +behavior, it is possible to make serious mistakes. 'tar' provides +several options that make observing 'tar' easier. These options cause +'tar' to print information as it progresses in its job, and you might +want to use them just for being more careful about what is going on, or +merely for entertaining yourself. If you have encountered a problem +when operating on an archive, however, you may need more information +than just an error message in order to solve the problem. The following +options can be helpful diagnostic tools. + + Normally, the '--list' ('-t') command to list an archive prints just +the file names (one per line) and the other commands are silent. When +used with most operations, the '--verbose' ('-v') option causes 'tar' to +print the name of each file or archive member as it is processed. This +and the other options which make 'tar' print status information can be +useful in monitoring 'tar'. + + With '--create' or '--extract', '--verbose' used once just prints the +names of the files or members as they are processed. Using it twice +causes 'tar' to print a longer listing (*Note verbose member listing::, +for the description) for each member. Since '--list' already prints the +names of the members, '--verbose' used once with '--list' causes 'tar' +to print an 'ls -l' type listing of the files in the archive. The +following examples both extract members with long list output: + + $ tar --extract --file=archive.tar --verbose --verbose + $ tar xvvf archive.tar + + Verbose output appears on the standard output except when an archive +is being written to the standard output, as with 'tar --create --file=- +--verbose' ('tar cvf -', or even 'tar cv'--if the installer let standard +output be the default archive). In that case 'tar' writes verbose +output to the standard error stream. + + If '--index-file=FILE' is specified, 'tar' sends verbose output to +FILE rather than to standard output or standard error. + + The '--totals' option causes 'tar' to print on the standard error the +total amount of bytes transferred when processing an archive. When +creating or appending to an archive, this option prints the number of +bytes written to the archive and the average speed at which they have +been written, e.g.: + + $ tar -c -f archive.tar --totals /home + Total bytes written: 7924664320 (7.4GiB, 85MiB/s) + + When reading an archive, this option displays the number of bytes +read: + + $ tar -x -f archive.tar --totals + Total bytes read: 7924664320 (7.4GiB, 95MiB/s) + + Finally, when deleting from an archive, the '--totals' option +displays both numbers plus number of bytes removed from the archive: + + $ tar --delete -f foo.tar --totals --wildcards '*~' + Total bytes read: 9543680 (9.2MiB, 201MiB/s) + Total bytes written: 3829760 (3.7MiB, 81MiB/s) + Total bytes deleted: 1474048 + + You can also obtain this information on request. When '--totals' is +used with an argument, this argument is interpreted as a symbolic name +of a signal, upon delivery of which the statistics is to be printed: + +'--totals=SIGNO' + Print statistics upon delivery of signal SIGNO. Valid arguments + are: 'SIGHUP', 'SIGQUIT', 'SIGINT', 'SIGUSR1' and 'SIGUSR2'. + Shortened names without 'SIG' prefix are also accepted. + + Both forms of '--totals' option can be used simultaneously. Thus, +'tar -x --totals --totals=USR1' instructs 'tar' to extract all members +from its default archive and print statistics after finishing the +extraction, as well as when receiving signal 'SIGUSR1'. + + The '--checkpoint' option prints an occasional message as 'tar' reads +or writes the archive. It is designed for those who don't need the more +detailed (and voluminous) output of '--block-number' ('-R'), but do want +visual confirmation that 'tar' is actually making forward progress. By +default it prints a message each 10 records read or written. This can +be changed by giving it a numeric argument after an equal sign: + + $ tar -c --checkpoint=1000 /var + tar: Write checkpoint 1000 + tar: Write checkpoint 2000 + tar: Write checkpoint 3000 + + This example shows the default checkpoint message used by 'tar'. If +you place a dot immediately after the equal sign, it will print a '.' at +each checkpoint(1). For example: + + $ tar -c --checkpoint=.1000 /var + ... + + The '--checkpoint' option provides a flexible mechanism for executing +arbitrary actions upon hitting checkpoints, see the next section (*note +checkpoints::), for more information on it. + + The '--show-omitted-dirs' option, when reading an archive--with +'--list' or '--extract', for example--causes a message to be printed for +each directory in the archive which is skipped. This happens regardless +of the reason for skipping: the directory might not have been named on +the command line (implicitly or explicitly), it might be excluded by the +use of the '--exclude=PATTERN' option, or some other reason. + + If '--block-number' ('-R') is used, 'tar' prints, along with every +message it would normally produce, the block number within the archive +where the message was triggered. Also, supplementary messages are +triggered when reading blocks full of NULs, or when hitting end of file +on the archive. As of now, if the archive is properly terminated with a +NUL block, the reading of the file may stop before end of file is met, +so the position of end of file will not usually show when +'--block-number' ('-R') is used. Note that GNU 'tar' drains the archive +before exiting when reading the archive from a pipe. + + This option is especially useful when reading damaged archives, since +it helps pinpoint the damaged sections. It can also be used with +'--list' ('-t') when listing a file-system backup tape, allowing you to +choose among several backup tapes when retrieving a file later, in favor +of the tape where the file appears earliest (closest to the front of the +tape). *Note backup::. + + ---------- Footnotes ---------- + + (1) This is actually a shortcut for '--checkpoint=N +--checkpoint-action=dot'. *Note dot: checkpoints. + + +File: tar.info, Node: checkpoints, Next: warnings, Prev: verbose, Up: tar invocation + +3.8 Checkpoints +=============== + +A "checkpoint" is a moment of time before writing Nth record to the +archive (a "write checkpoint"), or before reading Nth record from the +archive (a "read checkpoint"). Checkpoints allow to periodically +execute arbitrary actions. + + The checkpoint facility is enabled using the following option: + +'--checkpoint[=N]' + Schedule checkpoints before writing or reading each Nth record. + The default value for N is 10. + + A list of arbitrary "actions" can be executed at each checkpoint. +These actions include: pausing, displaying textual messages, and +executing arbitrary external programs. Actions are defined using the +'--checkpoint-action' option. + +'--checkpoint-action=ACTION' + Execute an ACTION at each checkpoint. + + The simplest value of ACTION is 'echo'. It instructs 'tar' to +display the default message on the standard error stream upon arriving +at each checkpoint. The default message is (in POSIX locale) 'Write +checkpoint N', for write checkpoints, and 'Read checkpoint N', for read +checkpoints. Here, N represents ordinal number of the checkpoint. + + In another locales, translated versions of this message are used. + + This is the default action, so running: + + $ tar -c --checkpoint=1000 --checkpoint-action=echo /var + +is equivalent to: + + $ tar -c --checkpoint=1000 /var + + The 'echo' action also allows to supply a customized message. You do +so by placing an equals sign and the message right after it, e.g.: + + --checkpoint-action="echo=Hit %s checkpoint #%u" + + The '%s' and '%u' in the above example are "format specifiers". The +'%s' specifier is replaced with the "type" of the checkpoint: 'write' or +'read' (or a corresponding translated version in locales other than +POSIX). The '%u' specifier is replaced with the ordinal number of the +checkpoint. Thus, the above example could produce the following output +when used with the '--create' option: + + tar: Hit write checkpoint #10 + tar: Hit write checkpoint #20 + tar: Hit write checkpoint #30 + + The complete list of available format specifiers follows. Some of +them can take optional arguments. These arguments, if given, are +supplied in curly braces between the percent sign and the specifier +letter. + +'%s' + Print type of the checkpoint ('write' or 'read'). + +'%u' + Print number of the checkpoint. + +'%{r,w,d}T' + Print number of bytes transferred so far and approximate transfer + speed. Optional arguments supply prefixes to be used before number + of bytes read, written and deleted, correspondingly. If absent, + they default to 'R'. 'W', 'D'. Any or all of them can be omitted, + so, that e.g. '%{}T' means to print corresponding statistics + without any prefixes. Any surplus arguments, if present, are + silently ignored. + + $ tar --delete -f f.tar --checkpoint-action=echo="#%u: %T" main.c + tar: #1: R: 0 (0B, 0B/s),W: 0 (0B, 0B/s),D: 0 + tar: #2: R: 10240 (10KiB, 19MiB/s),W: 0 (0B, 0B/s),D: 10240 + + See also the 'totals' action, described below. + +'%{FMT}t' + Output current local time using FMT as format for 'strftime' (*note + strftime: (strftime(3))strftime.). The '{FMT}' part is optional. + If not present, the default format is '%c', i.e. the preferred + date and time representation for the current locale. + +'%{N}*' + Pad output with spaces to the Nth column. If the '{N}' part is + omitted, the current screen width is assumed. + +'%c' + This is a shortcut for '%{%Y-%m-%d %H:%M:%S}t: %ds, + %{read,wrote}T%*\r', intended mainly for use with 'ttyout' action + (see below). + + Aside from format expansion, the message string is subject to +"unquoting", during which the backslash "escape sequences" are replaced +with their corresponding ASCII characters (*note escape sequences::). +E.g. the following action will produce an audible bell and the message +described above at each checkpoint: + + --checkpoint-action='echo=\aHit %s checkpoint #%u' + + There is also a special action which produces an audible signal: +'bell'. It is not equivalent to 'echo='\a'', because 'bell' sends the +bell directly to the console ('/dev/tty'), whereas 'echo='\a'' sends it +to the standard error. + + The 'ttyout=STRING' action outputs STRING to '/dev/tty', so it can be +used even if the standard output is redirected elsewhere. The STRING is +subject to the same modifications as with 'echo' action. In contrast to +the latter, 'ttyout' does not prepend 'tar' executable name to the +string, nor does it output a newline after it. For example, the +following action will print the checkpoint message at the same screen +line, overwriting any previous message: + + --checkpoint-action="ttyout=Hit %s checkpoint #%u%*\r" + +Notice the use of '%*' specifier to clear out any eventual remains of +the prior output line. As as more complex example, consider this: + + --checkpoint-action=ttyout='%{%Y-%m-%d %H:%M:%S}t (%d sec): #%u, %T%*\r' + +This prints the current local time, number of seconds expired since tar +was started, the checkpoint ordinal number, transferred bytes and +average computed I/O speed. + + Another available checkpoint action is 'dot' (or '.'). It instructs +'tar' to print a single dot on the standard listing stream, e.g.: + + $ tar -c --checkpoint=1000 --checkpoint-action=dot /var + ... + + For compatibility with previous GNU 'tar' versions, this action can +be abbreviated by placing a dot in front of the checkpoint frequency, as +shown in the previous section. + + The 'totals' action prints the total number of bytes transferred so +far. The format of the data is the same as for the '--totals' option +(*note totals::). See also '%T' format specifier of the 'echo' or +'ttyout' action. + + Yet another action, 'sleep', pauses 'tar' for a specified amount of +seconds. The following example will stop for 30 seconds at each +checkpoint: + + $ tar -c --checkpoint=1000 --checkpoint-action=sleep=30 + + Finally, the 'exec' action executes a given external command. For +example: + + $ tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint + + The supplied command can be any valid command invocation, with or +without additional command line arguments. If it does contain +arguments, don't forget to quote it to prevent it from being split by +the shell. *Note Running External Commands: external, for more detail. + + The command gets a copy of 'tar''s environment plus the following +variables: + +'TAR_VERSION' + GNU 'tar' version number. + +'TAR_ARCHIVE' + The name of the archive 'tar' is processing. + +'TAR_BLOCKING_FACTOR' + Current blocking factor (*note Blocking::). + +'TAR_CHECKPOINT' + Number of the checkpoint. + +'TAR_SUBCOMMAND' + A short option describing the operation 'tar' is executing. *Note + Operations::, for a complete list of subcommand options. + +'TAR_FORMAT' + Format of the archive being processed. *Note Formats::, for a + complete list of archive format names. + + These environment variables can also be passed as arguments to the +command, provided that they are properly escaped, for example: + + tar -c -f arc.tar \ + --checkpoint-action='exec=/sbin/cpoint $TAR_CHECKPOINT' + +Notice single quotes to prevent variable names from being expanded by +the shell when invoking 'tar'. + + Any number of actions can be defined, by supplying several +'--checkpoint-action' options in the command line. For example, the +command below displays two messages, pauses execution for 30 seconds and +executes the '/sbin/cpoint' script: + + $ tar -c -f arc.tar \ + --checkpoint-action='\aecho=Hit %s checkpoint #%u' \ + --checkpoint-action='echo=Sleeping for 30 seconds' \ + --checkpoint-action='sleep=30' \ + --checkpoint-action='exec=/sbin/cpoint' + + This example also illustrates the fact that '--checkpoint-action' can +be used without '--checkpoint'. In this case, the default checkpoint +frequency (at each 10th record) is assumed. + + +File: tar.info, Node: warnings, Next: interactive, Prev: checkpoints, Up: tar invocation + +3.9 Controlling Warning Messages +================================ + +Sometimes, while performing the requested task, GNU 'tar' notices some +conditions that are not exactly errors, but which the user should be +aware of. When this happens, 'tar' issues a "warning message" +describing the condition. Warning messages are output to the standard +error and they do not affect the exit code of 'tar' command. + + GNU 'tar' allows the user to suppress some or all of its warning +messages: + +'--warning=KEYWORD' + Control display of the warning messages identified by KEYWORD. If + KEYWORD starts with the prefix 'no-', such messages are suppressed. + Otherwise, they are enabled. + + Multiple '--warning' messages accumulate. + + The tables below list allowed values for KEYWORD along with the + warning messages they control. + +Keywords controlling 'tar' operation +------------------------------------ + +all + Enable all warning messages. This is the default. +none + Disable all warning messages. +filename-with-nuls + '%s: file name read contains nul character' +alone-zero-block + 'A lone zero block at %s' + +Keywords applicable for 'tar --create' +-------------------------------------- + +cachedir + '%s: contains a cache directory tag %s; %s' +file-shrank + '%s: File shrank by %s bytes; padding with zeros' +xdev + '%s: file is on a different filesystem; not dumped' +file-ignored + '%s: Unknown file type; file ignored' + '%s: socket ignored' + '%s: door ignored' +file-unchanged + '%s: file is unchanged; not dumped' +ignore-archive + '%s: file is the archive; not dumped' +file-removed + '%s: File removed before we read it' +file-changed + '%s: file changed as we read it' + +Keywords applicable for 'tar --extract' +--------------------------------------- + +existing-file + '%s: skipping existing file' +timestamp + '%s: implausibly old time stamp %s' + '%s: time stamp %s is %s s in the future' +contiguous-cast + 'Extracting contiguous files as regular files' +symlink-cast + 'Attempting extraction of symbolic links as hard links' +unknown-cast + '%s: Unknown file type '%c', extracted as normal file' +ignore-newer + 'Current %s is newer or same age' +unknown-keyword + 'Ignoring unknown extended header keyword '%s'' +decompress-program + Controls verbose description of failures occurring when trying to + run alternative decompressor programs (*note alternative + decompression programs::). This warning is disabled by default + (unless '--verbose' is used). A common example of what you can get + when using this warning is: + + $ tar --warning=decompress-program -x -f archive.Z + tar (child): cannot run compress: No such file or directory + tar (child): trying gzip + + This means that 'tar' first tried to decompress 'archive.Z' using + 'compress', and, when that failed, switched to 'gzip'. +record-size + 'Record size = %lu blocks' + +Keywords controlling incremental extraction: +-------------------------------------------- + +rename-directory + '%s: Directory has been renamed from %s' + '%s: Directory has been renamed' +new-directory + '%s: Directory is new' +xdev + '%s: directory is on a different device: not purging' +bad-dumpdir + 'Malformed dumpdir: 'X' never used' + + +File: tar.info, Node: interactive, Next: external, Prev: warnings, Up: tar invocation + +3.10 Asking for Confirmation During Operations +============================================== + +Typically, 'tar' carries out a command without stopping for further +instructions. In some situations however, you may want to exclude some +files and archive members from the operation (for instance if disk or +storage space is tight). You can do this by excluding certain files +automatically (*note Choosing::), or by performing an operation +interactively, using the '--interactive' ('-w') option. 'tar' also +accepts '--confirmation' for this option. + + When the '--interactive' ('-w') option is specified, before reading, +writing, or deleting files, 'tar' first prints a message for each such +file, telling what operation it intends to take, then asks for +confirmation on the terminal. The actions which require confirmation +include adding a file to the archive, extracting a file from the +archive, deleting a file from the archive, and deleting a file from +disk. To confirm the action, you must type a line of input beginning +with 'y'. If your input line begins with anything other than 'y', 'tar' +skips that file. + + If 'tar' is reading the archive from the standard input, 'tar' opens +the file '/dev/tty' to support the interactive communications. + + Verbose output is normally sent to standard output, separate from +other error messages. However, if the archive is produced directly on +standard output, then verbose output is mixed with errors on 'stderr'. +Producing the archive on standard output may be used as a way to avoid +using disk space, when the archive is soon to be consumed by another +process reading it, say. Some people felt the need of producing an +archive on stdout, still willing to segregate between verbose output and +error output. A possible approach would be using a named pipe to +receive the archive, and having the consumer process to read from that +named pipe. This has the advantage of letting standard output free to +receive verbose output, all separate from errors. + + +File: tar.info, Node: external, Prev: interactive, Up: tar invocation + +3.11 Running External Commands +============================== + +Certain GNU 'tar' operations imply running external commands that you +supply on the command line. One of such operations is checkpointing, +described above (*note checkpoint exec::). Another example of this +feature is the '-I' option, which allows you to supply the program to +use for compressing or decompressing the archive (*note +use-compress-program::). + + Whenever such operation is requested, 'tar' first splits the supplied +command into words much like the shell does. It then treats the first +word as the name of the program or the shell script to execute and the +rest of words as its command line arguments. The program, unless given +as an absolute file name, is searched in the shell's 'PATH'. + + Any additional information is normally supplied to external commands +in environment variables, specific to each particular operation. For +example, the '--checkpoint-action=exec' option, defines the +'TAR_ARCHIVE' variable to the name of the archive being worked upon. +You can, should the need be, use these variables in the command line of +the external command. For example: + + $ tar -x -f archive.tar \ + --checkpoint-action=exec='printf "%04d in %32s\r" $TAR_CHECKPOINT $TAR_ARCHIVE' + +This command prints for each checkpoint its number and the name of the +archive, using the same output line on the screen. + + Notice the use of single quotes to prevent variable names from being +expanded by the shell when invoking 'tar'. + + +File: tar.info, Node: operations, Next: Backups, Prev: tar invocation, Up: Top + +4 GNU 'tar' Operations +********************** + +* Menu: + +* Basic tar:: +* Advanced tar:: +* create options:: +* extract options:: +* backup:: +* Applications:: +* looking ahead:: + + +File: tar.info, Node: Basic tar, Next: Advanced tar, Up: operations + +4.1 Basic GNU 'tar' Operations +============================== + +The basic 'tar' operations, '--create' ('-c'), '--list' ('-t') and +'--extract' ('--get', '-x'), are currently presented and described in +the tutorial chapter of this manual. This section provides some +complementary notes for these operations. + +'--create' +'-c' + + Creating an empty archive would have some kind of elegance. One + can initialize an empty archive and later use '--append' ('-r') for + adding all members. Some applications would not welcome making an + exception in the way of adding the first archive member. On the + other hand, many people reported that it is dangerously too easy + for 'tar' to destroy a magnetic tape with an empty archive(1). The + two most common errors are: + + 1. Mistakingly using 'create' instead of 'extract', when the + intent was to extract the full contents of an archive. This + error is likely: keys 'c' and 'x' are right next to each other + on the QWERTY keyboard. Instead of being unpacked, the + archive then gets wholly destroyed. When users speak about + "exploding" an archive, they usually mean something else :-). + + 2. Forgetting the argument to 'file', when the intent was to + create an archive with a single file in it. This error is + likely because a tired user can easily add the 'f' key to the + cluster of option letters, by the mere force of habit, without + realizing the full consequence of doing so. The usual + consequence is that the single file, which was meant to be + saved, is rather destroyed. + + So, recognizing the likelihood and the catastrophic nature of these + errors, GNU 'tar' now takes some distance from elegance, and + cowardly refuses to create an archive when '--create' option is + given, there are no arguments besides options, and '--files-from' + ('-T') option is _not_ used. To get around the cautiousness of GNU + 'tar' and nevertheless create an archive with nothing in it, one + may still use, as the value for the '--files-from' option, a file + with no names in it, as shown in the following commands: + + tar --create --file=empty-archive.tar --files-from=/dev/null + tar -cf empty-archive.tar -T /dev/null + +'--extract' +'--get' +'-x' + + A socket is stored, within a GNU 'tar' archive, as a pipe. + +'--list (-t)' + + GNU 'tar' now shows dates as '1996-08-30', while it used to show + them as 'Aug 30 1996'. Preferably, people should get used to ISO + 8601 dates. Local American dates should be made available again + with full date localization support, once ready. In the meantime, + programs not being localizable for dates should prefer + international dates, that's really the way to go. + + Look up <http://www.cl.cam.ac.uk/~mgk25/iso-time.html> if you are + curious, it contains a detailed explanation of the ISO 8601 + standard. + + ---------- Footnotes ---------- + + (1) This is well described in 'Unix-haters Handbook', by Simson +Garfinkel, Daniel Weise & Steven Strassmann, IDG Books, ISBN +1-56884-203-1. + + +File: tar.info, Node: Advanced tar, Next: create options, Prev: Basic tar, Up: operations + +4.2 Advanced GNU 'tar' Operations +================================= + +Now that you have learned the basics of using GNU 'tar', you may want to +learn about further ways in which 'tar' can help you. + + This chapter presents five, more advanced operations which you +probably won't use on a daily basis, but which serve more specialized +functions. We also explain the different styles of options and why you +might want to use one or another, or a combination of them in your 'tar' +commands. Additionally, this chapter includes options which allow you +to define the output from 'tar' more carefully, and provide help and +error correction in special circumstances. + +* Menu: + +* Operations:: +* append:: +* update:: +* concatenate:: +* delete:: +* compare:: + + +File: tar.info, Node: Operations, Next: append, Up: Advanced tar + +4.2.1 The Five Advanced 'tar' Operations +---------------------------------------- + +In the last chapter, you learned about the first three operations to +'tar'. This chapter presents the remaining five operations to 'tar': +'--append', '--update', '--concatenate', '--delete', and '--compare'. + + You are not likely to use these operations as frequently as those +covered in the last chapter; however, since they perform specialized +functions, they are quite useful when you do need to use them. We will +give examples using the same directory and files that you created in the +last chapter. As you may recall, the directory is called 'practice', +the files are 'jazz', 'blues', 'folk', and the two archive files you +created are 'collection.tar' and 'music.tar'. + + We will also use the archive files 'afiles.tar' and 'bfiles.tar'. +The archive 'afiles.tar' contains the members 'apple', 'angst', and +'aspic'; 'bfiles.tar' contains the members './birds', 'baboon', and +'./box'. + + Unless we state otherwise, all practicing you do and examples you +follow in this chapter will take place in the 'practice' directory that +you created in the previous chapter; see *note prepare for examples::. +(Below in this section, we will remind you of the state of the examples +where the last chapter left them.) + + The five operations that we will cover in this chapter are: + +'--append' +'-r' + Add new entries to an archive that already exists. +'--update' +'-u' + Add more recent copies of archive members to the end of an archive, + if they exist. +'--concatenate' +'--catenate' +'-A' + Add one or more pre-existing archives to the end of another + archive. +'--delete' + Delete items from an archive (does not work on tapes). +'--compare' +'--diff' +'-d' + Compare archive members to their counterparts in the file system. + + +File: tar.info, Node: append, Next: update, Prev: Operations, Up: Advanced tar + +4.2.2 How to Add Files to Existing Archives: '--append' +------------------------------------------------------- + +If you want to add files to an existing archive, you don't need to +create a new archive; you can use '--append' ('-r'). The archive must +already exist in order to use '--append'. (A related operation is the +'--update' operation; you can use this to add newer versions of archive +members to an existing archive. To learn how to do this with +'--update', *note update::.) + + If you use '--append' to add a file that has the same name as an +archive member to an archive containing that archive member, then the +old member is not deleted. What does happen, however, is somewhat +complex. 'tar' _allows_ you to have infinite number of files with the +same name. Some operations treat these same-named members no +differently than any other set of archive members: for example, if you +view an archive with '--list' ('-t'), you will see all of those members +listed, with their data modification times, owners, etc. + + Other operations don't deal with these members as perfectly as you +might prefer; if you were to use '--extract' to extract the archive, +only the most recently added copy of a member with the same name as +other members would end up in the working directory. This is because +'--extract' extracts an archive in the order the members appeared in the +archive; the most recently archived members will be extracted last. +Additionally, an extracted member will _replace_ a file of the same name +which existed in the directory already, and 'tar' will not prompt you +about this(1). Thus, only the most recently archived member will end up +being extracted, as it will replace the one extracted before it, and so +on. + + There exists a special option that allows you to get around this +behavior and extract (or list) only a particular copy of the file. This +is '--occurrence' option. If you run 'tar' with this option, it will +extract only the first copy of the file. You may also give this option +an argument specifying the number of copy to be extracted. Thus, for +example if the archive 'archive.tar' contained three copies of file +'myfile', then the command + + tar --extract --file archive.tar --occurrence=2 myfile + +would extract only the second copy. *Note --occurrence: Option Summary, +for the description of '--occurrence' option. + + If you want to replace an archive member, use '--delete' to delete +the member you want to remove from the archive, and then use '--append' +to add the member you want to be in the archive. Note that you can not +change the order of the archive; the most recently added member will +still appear last. In this sense, you cannot truly "replace" one member +with another. (Replacing one member with another will not work on +certain types of media, such as tapes; see *note delete:: and *note +Media::, for more information.) + +* Menu: + +* appending files:: Appending Files to an Archive +* multiple:: + + ---------- Footnotes ---------- + + (1) Unless you give it '--keep-old-files' (or '--skip-old-files') +option, or the disk copy is newer than the one in the archive and you +invoke 'tar' with '--keep-newer-files' option. + + +File: tar.info, Node: appending files, Next: multiple, Up: append + +4.2.2.1 Appending Files to an Archive +..................................... + +The simplest way to add a file to an already existing archive is the +'--append' ('-r') operation, which writes specified files into the +archive whether or not they are already among the archived files. + + When you use '--append', you _must_ specify file name arguments, as +there is no default. If you specify a file that already exists in the +archive, another copy of the file will be added to the end of the +archive. As with other operations, the member names of the newly added +files will be exactly the same as their names given on the command line. +The '--verbose' ('-v') option will print out the names of the files as +they are written into the archive. + + '--append' cannot be performed on some tape drives, unfortunately, +due to deficiencies in the formats those tape drives use. The archive +must be a valid 'tar' archive, or else the results of using this +operation will be unpredictable. *Note Media::. + + To demonstrate using '--append' to add a file to an archive, create a +file called 'rock' in the 'practice' directory. Make sure you are in +the 'practice' directory. Then, run the following 'tar' command to add +'rock' to 'collection.tar': + + $ tar --append --file=collection.tar rock + +If you now use the '--list' ('-t') operation, you will see that 'rock' +has been added to the archive: + + $ tar --list --file=collection.tar + -rw-r--r-- me/user 28 1996-10-18 16:31 jazz + -rw-r--r-- me/user 21 1996-09-23 16:44 blues + -rw-r--r-- me/user 20 1996-09-23 16:44 folk + -rw-r--r-- me/user 20 1996-09-23 16:44 rock + + +File: tar.info, Node: multiple, Prev: appending files, Up: append + +4.2.2.2 Multiple Members with the Same Name +........................................... + +You can use '--append' ('-r') to add copies of files which have been +updated since the archive was created. (However, we do not recommend +doing this since there is another 'tar' option called '--update'; *Note +update::, for more information. We describe this use of '--append' here +for the sake of completeness.) When you extract the archive, the older +version will be effectively lost. This works because files are +extracted from an archive in the order in which they were archived. +Thus, when the archive is extracted, a file archived later in time will +replace a file of the same name which was archived earlier, even though +the older version of the file will remain in the archive unless you +delete all versions of the file. + + Supposing you change the file 'blues' and then append the changed +version to 'collection.tar'. As you saw above, the original 'blues' is +in the archive 'collection.tar'. If you change the file and append the +new version of the file to the archive, there will be two copies in the +archive. When you extract the archive, the older version of the file +will be extracted first, and then replaced by the newer version when it +is extracted. + + You can append the new, changed copy of the file 'blues' to the +archive in this way: + + $ tar --append --verbose --file=collection.tar blues + blues + +Because you specified the '--verbose' option, 'tar' has printed the name +of the file being appended as it was acted on. Now list the contents of +the archive: + + $ tar --list --verbose --file=collection.tar + -rw-r--r-- me/user 28 1996-10-18 16:31 jazz + -rw-r--r-- me/user 21 1996-09-23 16:44 blues + -rw-r--r-- me/user 20 1996-09-23 16:44 folk + -rw-r--r-- me/user 20 1996-09-23 16:44 rock + -rw-r--r-- me/user 58 1996-10-24 18:30 blues + +The newest version of 'blues' is now at the end of the archive (note the +different creation dates and file sizes). If you extract the archive, +the older version of the file 'blues' will be replaced by the newer +version. You can confirm this by extracting the archive and running +'ls' on the directory. + + If you wish to extract the first occurrence of the file 'blues' from +the archive, use '--occurrence' option, as shown in the following +example: + + $ tar --extract -vv --occurrence --file=collection.tar blues + -rw-r--r-- me/user 21 1996-09-23 16:44 blues + + *Note Writing::, for more information on '--extract' and see *note +-occurrence: Option Summary, for a description of '--occurrence' option. + + +File: tar.info, Node: update, Next: concatenate, Prev: append, Up: Advanced tar + +4.2.3 Updating an Archive +------------------------- + +In the previous section, you learned how to use '--append' to add a file +to an existing archive. A related operation is '--update' ('-u'). The +'--update' operation updates a 'tar' archive by comparing the date of +the specified archive members against the date of the file with the same +name. If the file has been modified more recently than the archive +member, then the newer version of the file is added to the archive (as +with '--append'). + + Unfortunately, you cannot use '--update' with magnetic tape drives. +The operation will fail. + + Both '--update' and '--append' work by adding to the end of the +archive. When you extract a file from the archive, only the version +stored last will wind up in the file system, unless you use the +'--backup' option. *Note multiple::, for a detailed discussion. + +* Menu: + +* how to update:: + + +File: tar.info, Node: how to update, Up: update + +4.2.3.1 How to Update an Archive Using '--update' +................................................. + +You must use file name arguments with the '--update' ('-u') operation. +If you don't specify any files, 'tar' won't act on any files and won't +tell you that it didn't do anything (which may end up confusing you). + + To see the '--update' option at work, create a new file, 'classical', +in your practice directory, and some extra text to the file 'blues', +using any text editor. Then invoke 'tar' with the 'update' operation +and the '--verbose' ('-v') option specified, using the names of all the +files in the 'practice' directory as file name arguments: + + $ tar --update -v -f collection.tar blues folk rock classical + blues + classical + $ + +Because we have specified verbose mode, 'tar' prints out the names of +the files it is working on, which in this case are the names of the +files that needed to be updated. If you run 'tar --list' and look at +the archive, you will see 'blues' and 'classical' at its end. There +will be a total of two versions of the member 'blues'; the one at the +end will be newer and larger, since you added text before updating it. + + The reason 'tar' does not overwrite the older file when updating it +is because writing to the middle of a section of tape is a difficult +process. Tapes are not designed to go backward. *Note Media::, for +more information about tapes. + + '--update' ('-u') is not suitable for performing backups for two +reasons: it does not change directory content entries, and it lengthens +the archive every time it is used. The GNU 'tar' options intended +specifically for backups are more efficient. If you need to run +backups, please consult *note Backups::. + + +File: tar.info, Node: concatenate, Next: delete, Prev: update, Up: Advanced tar + +4.2.4 Combining Archives with '--concatenate' +--------------------------------------------- + +Sometimes it may be convenient to add a second archive onto the end of +an archive rather than adding individual files to the archive. To add +one or more archives to the end of another archive, you should use the +'--concatenate' ('--catenate', '-A') operation. + + To use '--concatenate', give the first archive with '--file' option +and name the rest of archives to be concatenated on the command line. +The members, and their member names, will be copied verbatim from those +archives to the first one(1). The new, concatenated archive will be +called by the same name as the one given with the '--file' option. As +usual, if you omit '--file', 'tar' will use the value of the environment +variable 'TAPE', or, if this has not been set, the default archive name. + + To demonstrate how '--concatenate' works, create two small archives +called 'bluesrock.tar' and 'folkjazz.tar', using the relevant files from +'practice': + + $ tar -cvf bluesrock.tar blues rock + blues + rock + $ tar -cvf folkjazz.tar folk jazz + folk + jazz + +If you like, You can run 'tar --list' to make sure the archives contain +what they are supposed to: + + $ tar -tvf bluesrock.tar + -rw-r--r-- melissa/user 105 1997-01-21 19:42 blues + -rw-r--r-- melissa/user 33 1997-01-20 15:34 rock + $ tar -tvf jazzfolk.tar + -rw-r--r-- melissa/user 20 1996-09-23 16:44 folk + -rw-r--r-- melissa/user 65 1997-01-30 14:15 jazz + + We can concatenate these two archives with 'tar': + + $ cd .. + $ tar --concatenate --file=bluesrock.tar jazzfolk.tar + + If you now list the contents of the 'bluesrock.tar', you will see +that now it also contains the archive members of 'jazzfolk.tar': + + $ tar --list --file=bluesrock.tar + blues + rock + folk + jazz + + When you use '--concatenate', the source and target archives must +already exist and must have been created using compatible format +parameters. Notice, that 'tar' does not check whether the archives it +concatenates have compatible formats, it does not even check if the +files are really tar archives. + + Like '--append' ('-r'), this operation cannot be performed on some +tape drives, due to deficiencies in the formats those tape drives use. + + It may seem more intuitive to you to want or try to use 'cat' to +concatenate two archives instead of using the '--concatenate' operation; +after all, 'cat' is the utility for combining files. + + However, 'tar' archives incorporate an end-of-file marker which must +be removed if the concatenated archives are to be read properly as one +archive. '--concatenate' removes the end-of-archive marker from the +target archive before each new archive is appended. If you use 'cat' to +combine the archives, the result will not be a valid 'tar' format +archive. If you need to retrieve files from an archive that was added +to using the 'cat' utility, use the '--ignore-zeros' ('-i') option. +*Note Ignore Zeros::, for further information on dealing with archives +improperly combined using the 'cat' shell utility. + + ---------- Footnotes ---------- + + (1) This can cause multiple members to have the same name. For +information on how this affects reading the archive, see *note +multiple::. + + +File: tar.info, Node: delete, Next: compare, Prev: concatenate, Up: Advanced tar + +4.2.5 Removing Archive Members Using '--delete' +----------------------------------------------- + +You can remove members from an archive by using the '--delete' option. +Specify the name of the archive with '--file' ('-f') and then specify +the names of the members to be deleted; if you list no member names, +nothing will be deleted. The '--verbose' option will cause 'tar' to +print the names of the members as they are deleted. As with +'--extract', you must give the exact member names when using 'tar +--delete'. '--delete' will remove all versions of the named file from +the archive. The '--delete' operation can run very slowly. + + Unlike other operations, '--delete' has no short form. + + This operation will rewrite the archive. You can only use '--delete' +on an archive if the archive device allows you to write to any point on +the media, such as a disk; because of this, it does not work on magnetic +tapes. Do not try to delete an archive member from a magnetic tape; the +action will not succeed, and you will be likely to scramble the archive +and damage your tape. There is no safe way (except by completely +re-writing the archive) to delete files from most kinds of magnetic +tape. *Note Media::. + + To delete all versions of the file 'blues' from the archive +'collection.tar' in the 'practice' directory, make sure you are in that +directory, and then, + + $ tar --list --file=collection.tar + blues + folk + jazz + rock + $ tar --delete --file=collection.tar blues + $ tar --list --file=collection.tar + folk + jazz + rock + + The '--delete' option has been reported to work properly when 'tar' +acts as a filter from 'stdin' to 'stdout'. + + +File: tar.info, Node: compare, Prev: delete, Up: Advanced tar + +4.2.6 Comparing Archive Members with the File System +---------------------------------------------------- + +The '--compare' ('-d'), or '--diff' operation compares specified archive +members against files with the same names, and then reports differences +in file size, mode, owner, modification date and contents. You should +_only_ specify archive member names, not file names. If you do not name +any members, then 'tar' will compare the entire archive. If a file is +represented in the archive but does not exist in the file system, 'tar' +reports a difference. + + You have to specify the record size of the archive when modifying an +archive with a non-default record size. + + 'tar' ignores files in the file system that do not have corresponding +members in the archive. + + The following example compares the archive members 'rock', 'blues' +and 'funk' in the archive 'bluesrock.tar' with files of the same name in +the file system. (Note that there is no file, 'funk'; 'tar' will report +an error message.) + + $ tar --compare --file=bluesrock.tar rock blues funk + rock + blues + tar: funk not found in archive + + The spirit behind the '--compare' ('--diff', '-d') option is to check +whether the archive represents the current state of files on disk, more +than validating the integrity of the archive media. For this latter +goal, see *note verify::. + + +File: tar.info, Node: create options, Next: extract options, Prev: Advanced tar, Up: operations + +4.3 Options Used by '--create' +============================== + +The previous chapter described the basics of how to use '--create' +('-c') to create an archive from a set of files. *Note create::. This +section described advanced options to be used with '--create'. + +* Menu: + +* override:: Overriding File Metadata. +* Extended File Attributes:: +* Ignore Failed Read:: + + +File: tar.info, Node: override, Next: Extended File Attributes, Up: create options + +4.3.1 Overriding File Metadata +------------------------------ + +As described above, a 'tar' archive keeps, for each member it contains, +its "metadata", such as modification time, mode and ownership of the +file. GNU 'tar' allows to replace these data with other values when +adding files to the archive. The options described in this section +affect creation of archives of any type. For POSIX archives, see also +*note PAX keywords::, for additional ways of controlling metadata, +stored in the archive. + +'--mode=PERMISSIONS' + + When adding files to an archive, 'tar' will use PERMISSIONS for the + archive members, rather than the permissions from the files. + PERMISSIONS can be specified either as an octal number or as + symbolic permissions, like with 'chmod' (*Note Permissions: + (fileutils)File permissions. This reference also has useful + information for those not being overly familiar with the UNIX + permission system). Using latter syntax allows for more + flexibility. For example, the value 'a+rw' adds read and write + permissions for everybody, while retaining executable bits on + directories or on any other file already marked as executable: + + $ tar -c -f archive.tar --mode='a+rw' . + +'--mtime=DATE' + + When adding files to an archive, 'tar' will use DATE as the + modification time of members when creating archives, instead of + their actual modification times. The argument DATE can be either a + textual date representation in almost arbitrary format (*note Date + input formats::) or a name of an existing file, starting with '/' + or '.'. In the latter case, the modification time of that file + will be used. + + The following example will set the modification date to 00:00:00, + January 1, 1970: + + $ tar -c -f archive.tar --mtime='1970-01-01' . + + When used with '--verbose' (*note verbose tutorial::) GNU 'tar' + will try to convert the specified date back to its textual + representation and compare it with the one given with '--mtime' + options. If the two dates differ, 'tar' will print a warning + saying what date it will use. This is to help user ensure he is + using the right date. + + For example: + + $ tar -c -f archive.tar -v --mtime=yesterday . + tar: Option --mtime: Treating date 'yesterday' as 2006-06-20 + 13:06:29.152478 + ... + + When used with '--clamp-mtime' GNU 'tar' will only set the + modification date to DATE on files whose actual modification date + is later than DATE. This is to make it easy to build reproducible + archives given a common timestamp for generated files while still + retaining the original timestamps of untouched files. + + $ tar -c -f archive.tar --clamp-mtime --mtime=@$SOURCE_DATE_EPOCH . + +'--owner=USER' + + Specifies that 'tar' should use USER as the owner of members when + creating archives, instead of the user associated with the source + file. + + If USER contains a colon, it is taken to be of the form NAME:ID + where a nonempty NAME specifies the user name and a nonempty ID + specifies the decimal numeric user ID. If USER does not contain a + colon, it is taken to be a user number if it is one or more decimal + digits; otherwise it is taken to be a user name. + + If a name is given but no number, the number is inferred from the + current host's user database if possible, and the file's user + number is used otherwise. If a number is given but no name, the + name is inferred from the number if possible, and an empty name is + used otherwise. If both name and number are given, the user + database is not consulted, and the name and number need not be + valid on the current host. + + There is no value indicating a missing number, and '0' usually + means 'root'. Some people like to force '0' as the value to offer + in their distributions for the owner of files, because the 'root' + user is anonymous anyway, so that might as well be the owner of + anonymous archives. For example: + + $ tar -c -f archive.tar --owner=0 . + + or: + + $ tar -c -f archive.tar --owner=root . + +'--group=GROUP' + + Files added to the 'tar' archive will have a group ID of GROUP, + rather than the group from the source file. As with '--owner', the + argument GROUP can be an existing group symbolic name, or a decimal + numeric group ID, or NAME:ID. + + The '--owner' and '--group' options affect all files added to the +archive. GNU 'tar' provides also two options that allow for more +detailed control over owner translation: + +'--owner-map=FILE' + Read UID translation map from FILE. + + When reading, empty lines are ignored. The '#' sign, unless + quoted, introduces a comment, which extends to the end of the line. + Each nonempty line defines mapping for a single UID. It must + consist of two fields separated by any amount of whitespace. The + first field defines original username and UID. It can be a valid + user name or a valid UID prefixed with a plus sign. In both cases + the corresponding UID or user name is inferred from the current + host's user database. + + The second field defines the UID and username to map the original + one to. Its format can be the same as described above. Otherwise, + it can have the form NEWNAME:NEWUID, in which case neither NEWNAME + nor NEWUID are required to be valid as per the user database. + + For example, consider the following file: + + +10 bin + smith root:0 + + Given this file, each input file that is owner by UID 10 will be + stored in archive with owner name 'bin' and owner UID corresponding + to 'bin'. Each file owned by user 'smith' will be stored with + owner name 'root' and owner ID 0. Other files will remain + unchanged. + + When used together with '--owner-map', the '--owner' option affects + only files whose owner is not listed in the map file. + +'--group-map=FILE' + Read GID translation map from FILE. + + The format of FILE is the same as for '--owner-map' option: + + Each nonempty line defines mapping for a single GID. It must + consist of two fields separated by any amount of whitespace. The + first field defines original group name and GID. It can be a valid + group name or a valid GID prefixed with a plus sign. In both cases + the corresponding GID or user name is inferred from the current + host's group database. + + The second field defines the GID and group name to map the original + one to. Its format can be the same as described above. Otherwise, + it can have the form NEWNAME:NEWGID, in which case neither NEWNAME + nor NEWGID are required to be valid as per the group database. + + When used together with '--group-map', the '--group' option affects + only files whose owner group is not rewritten using the map file. + + +File: tar.info, Node: Extended File Attributes, Next: Ignore Failed Read, Prev: override, Up: create options + +4.3.2 Extended File Attributes +------------------------------ + +Extended file attributes are name-value pairs that can be associated +with each node in a file system. Despite the fact that POSIX.1e draft +which proposed them has been withdrawn, the extended file attributes are +supported by many file systems. GNU 'tar' can store extended file +attributes along with the files. This feature is controlled by the +following command line arguments: + +'--xattrs' + Enable extended attributes support. When used with '--create', + this option instructs GNU 'tar' to store extended file attribute in + the created archive. This implies POSIX.1-2001 archive format + ('--format=pax'). + + When used with '--extract', this option tells 'tar', for each file + extracted, to read stored attributes from the archive and to apply + them to the file. + +'--no-xattrs' + Disable extended attributes support. This is the default. + + Attribute names are strings prefixed by a "namespace" name and a dot. +Currently, four namespaces exist: 'user', 'trusted', 'security' and +'system'. By default, when '--xattr' is used, all names are stored in +the archive (or extracted, if using '--extract'). This can be +controlled using the following options: + +'--xattrs-exclude=PATTERN' + Specify exclude pattern for extended attributes. + +'--xattrs-include=PATTERN' + Specify include pattern for extended attributes. + + Here, the PATTERN is POSIX regular expression. For example, the +following command: + + $ tar --xattrs --xattrs-exclude='^user\.' -c a.tar . + + will include in the archive 'a.tar' all attributes, except those from +the 'user' namespace. + + Any number of these options can be given, thereby creating lists of +include and exclude patterns. + + When both options are used, first '--xattrs-inlcude' is applied to +select the set of attribute names to keep, and then '--xattrs-exclude' +is applied to the resulting set. In other words, only those attributes +will be stored, whose names match one of the regexps in +'--xattrs-inlcude' and don't match any of the regexps from +'--xattrs-exclude'. + + When listing the archive, if both '--xattrs' and '--verbose' options +are given, files that have extended attributes are marked with an +asterisk following their permission mask. For example: + + -rw-r--r--* smith/users 110 2016-03-16 16:07 file + + When two or more '--verbose' options are given, a detailed listing of +extended attributes is printed after each file entry. Each attribute is +listed on a separate line, which begins with two spaces and the letter +'x' indicating extended attribute. It is followed by a colon, length of +the attribute and its name, e.g.: + + -rw-r--r--* smith/users 110 2016-03-16 16:07 file + x: 7 user.mime_type + x: 32 trusted.md5sum + + File access control lists ("ACL") are another actively used feature +proposed by the POSIX.1e standard. Each ACL consists of a set of ACL +entries, each of which describes the access permissions on the file for +an individual user or a group of users as a combination of read, write +and search/execute permissions. + + Whether or not to use ACLs is controlled by the following two +options: + +'--acls' + Enable POSIX ACLs support. When used with '--create', this option + instructs GNU 'tar' to store ACLs in the created archive. This + implies POSIX.1-2001 archive format ('--format=pax'). + + When used with '--extract', this option tells 'tar', to restore + ACLs for each file extracted (provided they are present in the + archive). + +'--no-acls' + Disable POSIX ACLs support. This is the default. + + When listing the archive, if both '--acls' and '--verbose' options +are given, files that have ACLs are marked with a plus sing following +their permission mask. For example: + + -rw-r--r--+ smith/users 110 2016-03-16 16:07 file + + When two or more '--verbose' options are given, a detailed listing of +ACL is printed after each file entry: + + -rw-r--r--+ smith/users 110 2016-03-16 16:07 file + a: user::rw-,user:gray:-w-,group::r--,mask::rw-,other::r-- + + "Security-Enhanced Linux" ("SELinux" for short) is a Linux kernel +security module that provides a mechanism for supporting access control +security policies, including so-called mandatory access controls +("MAC"). Support for SELinux attributes is controlled by the following +command line options: + +'--selinux' + Enable the SELinux context support. + +'--no-selinux' + Disable SELinux context support. + + +File: tar.info, Node: Ignore Failed Read, Prev: Extended File Attributes, Up: create options + +4.3.3 Ignore Fail Read +---------------------- + +'--ignore-failed-read' + Do not exit with nonzero on unreadable files or directories. + + +File: tar.info, Node: extract options, Next: backup, Prev: create options, Up: operations + +4.4 Options Used by '--extract' +=============================== + +The previous chapter showed how to use '--extract' to extract an archive +into the file system. Various options cause 'tar' to extract more +information than just file contents, such as the owner, the permissions, +the modification date, and so forth. This section presents options to +be used with '--extract' when certain special considerations arise. You +may review the information presented in *note extract:: for more basic +information about the '--extract' operation. + +* Menu: + +* Reading:: Options to Help Read Archives +* Writing:: Changing How 'tar' Writes Files +* Scarce:: Coping with Scarce Resources + + +File: tar.info, Node: Reading, Next: Writing, Up: extract options + +4.4.1 Options to Help Read Archives +----------------------------------- + +Normally, 'tar' will request data in full record increments from an +archive storage device. If the device cannot return a full record, +'tar' will report an error. However, some devices do not always return +full records, or do not require the last record of an archive to be +padded out to the next record boundary. To keep reading until you +obtain a full record, or to accept an incomplete record if it contains +an end-of-archive marker, specify the '--read-full-records' ('-B') +option in conjunction with the '--extract' or '--list' operations. +*Note Blocking::. + + The '--read-full-records' ('-B') option is turned on by default when +'tar' reads an archive from standard input, or from a remote machine. +This is because on BSD Unix systems, attempting to read a pipe returns +however much happens to be in the pipe, even if it is less than was +requested. If this option were not enabled, 'tar' would fail as soon as +it read an incomplete record from the pipe. + + If you're not sure of the blocking factor of an archive, you can read +the archive by specifying '--read-full-records' ('-B') and +'--blocking-factor=512-SIZE' ('-b 512-SIZE'), using a blocking factor +larger than what the archive uses. This lets you avoid having to +determine the blocking factor of an archive. *Note Blocking Factor::. + +* Menu: + +* read full records:: +* Ignore Zeros:: + + +File: tar.info, Node: read full records, Next: Ignore Zeros, Up: Reading + +Reading Full Records +.................... + +'--read-full-records' +'-B' + Use in conjunction with '--extract' ('--get', '-x') to read an + archive which contains incomplete records, or one which has a + blocking factor less than the one specified. + + +File: tar.info, Node: Ignore Zeros, Prev: read full records, Up: Reading + +Ignoring Blocks of Zeros +........................ + +Normally, 'tar' stops reading when it encounters a block of zeros +between file entries (which usually indicates the end of the archive). +'--ignore-zeros' ('-i') allows 'tar' to completely read an archive which +contains a block of zeros before the end (i.e., a damaged archive, or +one that was created by concatenating several archives together). + + The '--ignore-zeros' ('-i') option is turned off by default because +many versions of 'tar' write garbage after the end-of-archive entry, +since that part of the media is never supposed to be read. GNU 'tar' +does not write after the end of an archive, but seeks to maintain +compatibility among archiving utilities. + +'--ignore-zeros' +'-i' + To ignore blocks of zeros (i.e., end-of-archive entries) which may + be encountered while reading an archive. Use in conjunction with + '--extract' or '--list'. + + +File: tar.info, Node: Writing, Next: Scarce, Prev: Reading, Up: extract options + +4.4.2 Changing How 'tar' Writes Files +------------------------------------- + + _(This message will disappear, once this node revised.)_ + +* Menu: + +* Dealing with Old Files:: +* Overwrite Old Files:: +* Keep Old Files:: +* Keep Newer Files:: +* Unlink First:: +* Recursive Unlink:: +* Data Modification Times:: +* Setting Access Permissions:: +* Directory Modification Times and Permissions:: +* Writing to Standard Output:: +* Writing to an External Program:: +* remove files:: + + +File: tar.info, Node: Dealing with Old Files, Next: Overwrite Old Files, Up: Writing + +Options Controlling the Overwriting of Existing Files +..................................................... + +When extracting files, if 'tar' discovers that the extracted file +already exists, it normally replaces the file by removing it before +extracting it, to prevent confusion in the presence of hard or symbolic +links. (If the existing file is a symbolic link, it is removed, not +followed.) However, if a directory cannot be removed because it is +nonempty, 'tar' normally overwrites its metadata (ownership, permission, +etc.). The '--overwrite-dir' option enables this default behavior. To +be more cautious and preserve the metadata of such a directory, use the +'--no-overwrite-dir' option. + + To be even more cautious and prevent existing files from being +replaced, use the '--keep-old-files' ('-k') option. It causes 'tar' to +refuse to replace or update a file that already exists, i.e., a file +with the same name as an archive member prevents extraction of that +archive member. Instead, it reports an error. For example: + + $ ls + blues + $ tar -x -k -f archive.tar + tar: blues: Cannot open: File exists + tar: Exiting with failure status due to previous errors + + If you wish to preserve old files untouched, but don't want 'tar' to +treat them as errors, use the '--skip-old-files' option. This option +causes 'tar' to silently skip extracting over existing files. + + To be more aggressive about altering existing files, use the +'--overwrite' option. It causes 'tar' to overwrite existing files and +to follow existing symbolic links when extracting. + + Some people argue that GNU 'tar' should not hesitate to overwrite +files with other files when extracting. When extracting a 'tar' +archive, they expect to see a faithful copy of the state of the file +system when the archive was created. It is debatable that this would +always be a proper behavior. For example, suppose one has an archive in +which 'usr/local' is a link to 'usr/local2'. Since then, maybe the site +removed the link and renamed the whole hierarchy from '/usr/local2' to +'/usr/local'. Such things happen all the time. I guess it would not be +welcome at all that GNU 'tar' removes the whole hierarchy just to make +room for the link to be reinstated (unless it _also_ simultaneously +restores the full '/usr/local2', of course!) GNU 'tar' is indeed able +to remove a whole hierarchy to reestablish a symbolic link, for example, +but _only if_ '--recursive-unlink' is specified to allow this behavior. +In any case, single files are silently removed. + + Finally, the '--unlink-first' ('-U') option can improve performance +in some cases by causing 'tar' to remove files unconditionally before +extracting them. + + +File: tar.info, Node: Overwrite Old Files, Next: Keep Old Files, Prev: Dealing with Old Files, Up: Writing + +Overwrite Old Files +................... + +'--overwrite' + Overwrite existing files and directory metadata when extracting + files from an archive. + + This causes 'tar' to write extracted files into the file system + without regard to the files already on the system; i.e., files with + the same names as archive members are overwritten when the archive + is extracted. It also causes 'tar' to extract the ownership, + permissions, and time stamps onto any preexisting files or + directories. If the name of a corresponding file name is a + symbolic link, the file pointed to by the symbolic link will be + overwritten instead of the symbolic link itself (if this is + possible). Moreover, special devices, empty directories and even + symbolic links are automatically removed if they are in the way of + extraction. + + Be careful when using the '--overwrite' option, particularly when + combined with the '--absolute-names' ('-P') option, as this + combination can change the contents, ownership or permissions of + any file on your system. Also, many systems do not take kindly to + overwriting files that are currently being executed. + +'--overwrite-dir' + Overwrite the metadata of directories when extracting files from an + archive, but remove other files before extracting. + + +File: tar.info, Node: Keep Old Files, Next: Keep Newer Files, Prev: Overwrite Old Files, Up: Writing + +Keep Old Files +.............. + +GNU 'tar' provides two options to control its actions in a situation +when it is about to extract a file which already exists on disk. + +'--keep-old-files' +'-k' + Do not replace existing files from archive. When such a file is + encountered, 'tar' issues an error message. Upon end of + extraction, 'tar' exits with code 2 (*note exit status::). + +'--skip-old-files' + Do not replace existing files from archive, but do not treat that + as error. Such files are silently skipped and do not affect 'tar' + exit status. + + Additional verbosity can be obtained using + '--warning=existing-file' together with that option (*note + warnings::). + + +File: tar.info, Node: Keep Newer Files, Next: Unlink First, Prev: Keep Old Files, Up: Writing + +Keep Newer Files +................ + +'--keep-newer-files' + Do not replace existing files that are newer than their archive + copies. This option is meaningless with '--list' ('-t'). + + +File: tar.info, Node: Unlink First, Next: Recursive Unlink, Prev: Keep Newer Files, Up: Writing + +Unlink First +............ + +'--unlink-first' +'-U' + Remove files before extracting over them. This can make 'tar' run + a bit faster if you know in advance that the extracted files all + need to be removed. Normally this option slows 'tar' down + slightly, so it is disabled by default. + + +File: tar.info, Node: Recursive Unlink, Next: Data Modification Times, Prev: Unlink First, Up: Writing + +Recursive Unlink +................ + +'--recursive-unlink' + When this option is specified, try removing files and directory + hierarchies before extracting over them. _This is a dangerous + option!_ + + If you specify the '--recursive-unlink' option, 'tar' removes +_anything_ that keeps you from extracting a file as far as current +permissions will allow it. This could include removal of the contents +of a full directory hierarchy. + + +File: tar.info, Node: Data Modification Times, Next: Setting Access Permissions, Prev: Recursive Unlink, Up: Writing + +Setting Data Modification Times +............................... + +Normally, 'tar' sets the data modification times of extracted files to +the corresponding times recorded for the files in the archive, but +limits the permissions of extracted files by the current 'umask' +setting. + + To set the data modification times of extracted files to the time +when the files were extracted, use the '--touch' ('-m') option in +conjunction with '--extract' ('--get', '-x'). + +'--touch' +'-m' + Sets the data modification time of extracted archive members to the + time they were extracted, not the time recorded for them in the + archive. Use in conjunction with '--extract' ('--get', '-x'). + + +File: tar.info, Node: Setting Access Permissions, Next: Directory Modification Times and Permissions, Prev: Data Modification Times, Up: Writing + +Setting Access Permissions +.......................... + +To set the modes (access permissions) of extracted files to those +recorded for those files in the archive, use '--same-permissions' in +conjunction with the '--extract' ('--get', '-x') operation. + +'--preserve-permissions' +'--same-permissions' +'-p' + Set modes of extracted archive members to those recorded in the + archive, instead of current umask settings. Use in conjunction + with '--extract' ('--get', '-x'). + + +File: tar.info, Node: Directory Modification Times and Permissions, Next: Writing to Standard Output, Prev: Setting Access Permissions, Up: Writing + +Directory Modification Times and Permissions +............................................ + +After successfully extracting a file member, GNU 'tar' normally restores +its permissions and modification times, as described in the previous +sections. This cannot be done for directories, because after extracting +a directory 'tar' will almost certainly extract files into that +directory and this will cause the directory modification time to be +updated. Moreover, restoring that directory permissions may not permit +file creation within it. Thus, restoring directory permissions and +modification times must be delayed at least until all files have been +extracted into that directory. GNU 'tar' restores directories using the +following approach. + + The extracted directories are created with the mode specified in the +archive, as modified by the umask of the user, which gives sufficient +permissions to allow file creation. The meta-information about the +directory is recorded in the temporary list of directories. When +preparing to extract next archive member, GNU 'tar' checks if the +directory prefix of this file contains the remembered directory. If it +does not, the program assumes that all files have been extracted into +that directory, restores its modification time and permissions and +removes its entry from the internal list. This approach allows to +correctly restore directory meta-information in the majority of cases, +while keeping memory requirements sufficiently small. It is based on +the fact, that most 'tar' archives use the predefined order of members: +first the directory, then all the files and subdirectories in that +directory. + + However, this is not always true. The most important exception are +incremental archives (*note Incremental Dumps::). The member order in +an incremental archive is reversed: first all directory members are +stored, followed by other (non-directory) members. So, when extracting +from incremental archives, GNU 'tar' alters the above procedure. It +remembers all restored directories, and restores their meta-data only +after the entire archive has been processed. Notice, that you do not +need to specify any special options for that, as GNU 'tar' automatically +detects archives in incremental format. + + There may be cases, when such processing is required for normal +archives too. Consider the following example: + + $ tar --no-recursion -cvf archive \ + foo foo/file1 bar bar/file foo/file2 + foo/ + foo/file1 + bar/ + bar/file + foo/file2 + + During the normal operation, after encountering 'bar' GNU 'tar' will +assume that all files from the directory 'foo' were already extracted +and will therefore restore its timestamp and permission bits. However, +after extracting 'foo/file2' the directory timestamp will be offset +again. + + To correctly restore directory meta-information in such cases, use +the '--delay-directory-restore' command line option: + +'--delay-directory-restore' + Delays restoring of the modification times and permissions of + extracted directories until the end of extraction. This way, + correct meta-information is restored even if the archive has + unusual member ordering. + +'--no-delay-directory-restore' + Cancel the effect of the previous '--delay-directory-restore'. Use + this option if you have used '--delay-directory-restore' in + 'TAR_OPTIONS' variable (*note TAR_OPTIONS::) and wish to + temporarily disable it. + + +File: tar.info, Node: Writing to Standard Output, Next: Writing to an External Program, Prev: Directory Modification Times and Permissions, Up: Writing + +Writing to Standard Output +.......................... + +To write the extracted files to the standard output, instead of creating +the files on the file system, use '--to-stdout' ('-O') in conjunction +with '--extract' ('--get', '-x'). This option is useful if you are +extracting files to send them through a pipe, and do not need to +preserve them in the file system. If you extract multiple members, they +appear on standard output concatenated, in the order they are found in +the archive. + +'--to-stdout' +'-O' + Writes files to the standard output. Use only in conjunction with + '--extract' ('--get', '-x'). When this option is used, instead of + creating the files specified, 'tar' writes the contents of the + files extracted to its standard output. This may be useful if you + are only extracting the files in order to send them through a pipe. + This option is meaningless with '--list' ('-t'). + + This can be useful, for example, if you have a tar archive containing +a big file and don't want to store the file on disk before processing +it. You can use a command like this: + + tar -xOzf foo.tgz bigfile | process + + or even like this if you want to process the concatenation of the +files: + + tar -xOzf foo.tgz bigfile1 bigfile2 | process + + However, '--to-command' may be more convenient for use with multiple +files. See the next section. + + +File: tar.info, Node: Writing to an External Program, Next: remove files, Prev: Writing to Standard Output, Up: Writing + +Writing to an External Program +.............................. + +You can instruct 'tar' to send the contents of each extracted file to +the standard input of an external program: + +'--to-command=COMMAND' + Extract files and pipe their contents to the standard input of + COMMAND. When this option is used, instead of creating the files + specified, 'tar' invokes COMMAND and pipes the contents of the + files to its standard output. The COMMAND may contain command line + arguments (see *note Running External Commands: external, for more + detail). + + Notice, that COMMAND is executed once for each regular file + extracted. Non-regular files (directories, etc.) are ignored when + this option is used. + + The command can obtain the information about the file it processes +from the following environment variables: + +'TAR_FILETYPE' + Type of the file. It is a single letter with the following + meaning: + + f Regular file + d Directory + l Symbolic link + h Hard link + b Block device + c Character device + + Currently only regular files are supported. + +'TAR_MODE' + File mode, an octal number. + +'TAR_FILENAME' + The name of the file. + +'TAR_REALNAME' + Name of the file as stored in the archive. + +'TAR_UNAME' + Name of the file owner. + +'TAR_GNAME' + Name of the file owner group. + +'TAR_ATIME' + Time of last access. It is a decimal number, representing seconds + since the Epoch. If the archive provides times with nanosecond + precision, the nanoseconds are appended to the timestamp after a + decimal point. + +'TAR_MTIME' + Time of last modification. + +'TAR_CTIME' + Time of last status change. + +'TAR_SIZE' + Size of the file. + +'TAR_UID' + UID of the file owner. + +'TAR_GID' + GID of the file owner. + + Additionally, the following variables contain information about tar +mode and the archive being processed: + +'TAR_VERSION' + GNU 'tar' version number. + +'TAR_ARCHIVE' + The name of the archive 'tar' is processing. + +'TAR_BLOCKING_FACTOR' + Current blocking factor (*note Blocking::). + +'TAR_VOLUME' + Ordinal number of the volume 'tar' is processing. + +'TAR_FORMAT' + Format of the archive being processed. *Note Formats::, for a + complete list of archive format names. + + These variables are defined prior to executing the command, so you +can pass them as arguments, if you prefer. For example, if the command +PROC takes the member name and size as its arguments, then you could do: + + $ tar -x -f archive.tar \ + --to-command='proc $TAR_FILENAME $TAR_SIZE' + +Notice single quotes to prevent variable names from being expanded by +the shell when invoking 'tar'. + + If COMMAND exits with a non-0 status, 'tar' will print an error +message similar to the following: + + tar: 2345: Child returned status 1 + + Here, '2345' is the PID of the finished process. + + If this behavior is not wanted, use '--ignore-command-error': + +'--ignore-command-error' + Ignore exit codes of subprocesses. Notice that if the program + exits on signal or otherwise terminates abnormally, the error + message will be printed even if this option is used. + +'--no-ignore-command-error' + Cancel the effect of any previous '--ignore-command-error' option. + This option is useful if you have set '--ignore-command-error' in + 'TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to temporarily cancel + it. + + +File: tar.info, Node: remove files, Prev: Writing to an External Program, Up: Writing + +Removing Files +.............. + +'--remove-files' + Remove files after adding them to the archive. + + +File: tar.info, Node: Scarce, Prev: Writing, Up: extract options + +4.4.3 Coping with Scarce Resources +---------------------------------- + + _(This message will disappear, once this node revised.)_ + +* Menu: + +* Starting File:: +* Same Order:: + + +File: tar.info, Node: Starting File, Next: Same Order, Up: Scarce + +Starting File +............. + +'--starting-file=NAME' +'-K NAME' + Starts an operation in the middle of an archive. Use in + conjunction with '--extract' ('--get', '-x') or '--list' ('-t'). + + If a previous attempt to extract files failed due to lack of disk +space, you can use '--starting-file=NAME' ('-K NAME') to start +extracting only after member NAME of the archive. This assumes, of +course, that there is now free space, or that you are now extracting +into a different file system. (You could also choose to suspend 'tar', +remove unnecessary files from the file system, and then resume the same +'tar' operation. In this case, '--starting-file' is not necessary.) +See also *note interactive::, and *note exclude::. + + +File: tar.info, Node: Same Order, Prev: Starting File, Up: Scarce + +Same Order +.......... + +'--same-order' +'--preserve-order' +'-s' + To process large lists of file names on machines with small amounts + of memory. Use in conjunction with '--compare' ('--diff', '-d'), + '--list' ('-t') or '--extract' ('--get', '-x'). + + The '--same-order' ('--preserve-order', '-s') option tells 'tar' that +the list of file names to be listed or extracted is sorted in the same +order as the files in the archive. This allows a large list of names to +be used, even on a small machine that would not otherwise be able to +hold all the names in memory at the same time. Such a sorted list can +easily be created by running 'tar -t' on the archive and editing its +output. + + This option is probably never needed on modern computer systems. + + +File: tar.info, Node: backup, Next: Applications, Prev: extract options, Up: operations + +4.5 Backup options +================== + +GNU 'tar' offers options for making backups of files before writing new +versions. These options control the details of these backups. They may +apply to the archive itself before it is created or rewritten, as well +as individual extracted members. Other GNU programs ('cp', 'install', +'ln', and 'mv', for example) offer similar options. + + Backup options may prove unexpectedly useful when extracting archives +containing many members having identical name, or when extracting +archives on systems having file name limitations, making different +members appear as having similar names through the side-effect of name +truncation. + + When any existing file is backed up before being overwritten by +extraction, then clashing files are automatically be renamed to be +unique, and the true name is kept for only the last file of a series of +clashing files. By using verbose mode, users may track exactly what +happens. + + At the detail level, some decisions are still experimental, and may +change in the future, we are waiting comments from our users. So, +please do not learn to depend blindly on the details of the backup +features. For example, currently, directories themselves are never +renamed through using these options, so, extracting a file over a +directory still has good chances to fail. Also, backup options apply to +created archives, not only to extracted members. For created archives, +backups will not be attempted when the archive is a block or character +device, or when it refers to a remote file. + + For the sake of simplicity and efficiency, backups are made by +renaming old files prior to creation or extraction, and not by copying. +The original name is restored if the file creation fails. If a failure +occurs after a partial extraction of a file, both the backup and the +partially extracted file are kept. + +'--backup[=METHOD]' + Back up files that are about to be overwritten or removed. Without + this option, the original versions are destroyed. + + Use METHOD to determine the type of backups made. If METHOD is not + specified, use the value of the 'VERSION_CONTROL' environment + variable. And if 'VERSION_CONTROL' is not set, use the 'existing' + method. + + This option corresponds to the Emacs variable 'version-control'; + the same values for METHOD are accepted as in Emacs. This option + also allows more descriptive names. The valid METHODs are: + + 't' + 'numbered' + Always make numbered backups. + + 'nil' + 'existing' + Make numbered backups of files that already have them, simple + backups of the others. + + 'never' + 'simple' + Always make simple backups. + +'--suffix=SUFFIX' + Append SUFFIX to each backup file made with '--backup'. If this + option is not specified, the value of the 'SIMPLE_BACKUP_SUFFIX' + environment variable is used. And if 'SIMPLE_BACKUP_SUFFIX' is not + set, the default is '~', just as in Emacs. + + +File: tar.info, Node: Applications, Next: looking ahead, Prev: backup, Up: operations + +4.6 Notable 'tar' Usages +======================== + + _(This message will disappear, once this node revised.)_ + + You can easily use archive files to transport a group of files from +one system to another: put all relevant files into an archive on one +computer system, transfer the archive to another system, and extract the +contents there. The basic transfer medium might be magnetic tape, +Internet FTP, or even electronic mail (though you must encode the +archive with 'uuencode' in order to transport it properly by mail). +Both machines do not have to use the same operating system, as long as +they both support the 'tar' program. + + For example, here is how you might copy a directory's contents from +one disk to another, while preserving the dates, modes, owners and +link-structure of all the files therein. In this case, the transfer +medium is a "pipe": + + $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -) + +You can avoid subshells by using '-C' option: + + $ tar -C sourcedir -cf - . | tar -C targetdir -xf - + +The command also works using long option forms: + + $ (cd sourcedir; tar --create --file=- . ) \ + | (cd targetdir; tar --extract --file=-) + +or + + $ tar --directory sourcedir --create --file=- . \ + | tar --directory targetdir --extract --file=- + +This is one of the easiest methods to transfer a 'tar' archive. + + +File: tar.info, Node: looking ahead, Prev: Applications, Up: operations + +4.7 Looking Ahead: The Rest of this Manual +========================================== + +You have now seen how to use all eight of the operations available to +'tar', and a number of the possible options. The next chapter explains +how to choose and change file and archive names, how to use files to +store names of other files which you can then call as arguments to 'tar' +(this can help you save time if you expect to archive the same list of +files a number of times), and so forth. + + If there are too many files to conveniently list on the command line, +you can list the names in a file, and 'tar' will read that file. *Note +files::. + + There are various ways of causing 'tar' to skip over some files, and +not archive them. *Note Choosing::. + + +File: tar.info, Node: Backups, Next: Choosing, Prev: operations, Up: Top + +5 Performing Backups and Restoring Files +**************************************** + +GNU 'tar' is distributed along with the scripts for performing backups +and restores. Even if there is a good chance those scripts may be +satisfying to you, they are not the only scripts or methods available +for doing backups and restore. You may well create your own, or use +more sophisticated packages dedicated to that purpose. + + Some users are enthusiastic about 'Amanda' (The Advanced Maryland +Automatic Network Disk Archiver), a backup system developed by James da +Silva 'jds@cs.umd.edu' and available on many Unix systems. This is free +software, and it is available from <http://www.amanda.org>. + + This chapter documents both the provided shell scripts and 'tar' +options which are more specific to usage as a backup tool. + + To "back up" a file system means to create archives that contain all +the files in that file system. Those archives can then be used to +restore any or all of those files (for instance if a disk crashes or a +file is accidentally deleted). File system "backups" are also called +"dumps". + +* Menu: + +* Full Dumps:: Using 'tar' to Perform Full Dumps +* Incremental Dumps:: Using 'tar' to Perform Incremental Dumps +* Backup Levels:: Levels of Backups +* Backup Parameters:: Setting Parameters for Backups and Restoration +* Scripted Backups:: Using the Backup Scripts +* Scripted Restoration:: Using the Restore Script + + +File: tar.info, Node: Full Dumps, Next: Incremental Dumps, Up: Backups + +5.1 Using 'tar' to Perform Full Dumps +===================================== + + _(This message will disappear, once this node revised.)_ + + Full dumps should only be made when no other people or programs are +modifying files in the file system. If files are modified while 'tar' +is making the backup, they may not be stored properly in the archive, in +which case you won't be able to restore them if you have to. (Files not +being modified are written with no trouble, and do not corrupt the +entire archive.) + + You will want to use the '--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL') +option to give the archive a volume label, so you can tell what this +archive is even if the label falls off the tape, or anything like that. + + Unless the file system you are dumping is guaranteed to fit on one +volume, you will need to use the '--multi-volume' ('-M') option. Make +sure you have enough tapes on hand to complete the backup. + + If you want to dump each file system separately you will need to use +the '--one-file-system' option to prevent 'tar' from crossing file +system boundaries when storing (sub)directories. + + The '--incremental' ('-G') (*note Incremental Dumps::) option is not +needed, since this is a complete copy of everything in the file system, +and a full restore from this backup would only be done onto a completely +empty disk. + + Unless you are in a hurry, and trust the 'tar' program (and your +tapes), it is a good idea to use the '--verify' ('-W') option, to make +sure your files really made it onto the dump properly. This will also +detect cases where the file was modified while (or just after) it was +being archived. Not all media (notably cartridge tapes) are capable of +being verified, unfortunately. + + +File: tar.info, Node: Incremental Dumps, Next: Backup Levels, Prev: Full Dumps, Up: Backups + +5.2 Using 'tar' to Perform Incremental Dumps +============================================ + +"Incremental backup" is a special form of GNU 'tar' archive that stores +additional metadata so that exact state of the file system can be +restored when extracting the archive. + + GNU 'tar' currently offers two options for handling incremental +backups: '--listed-incremental=SNAPSHOT-FILE' ('-g SNAPSHOT-FILE') and +'--incremental' ('-G'). + + The option '--listed-incremental' instructs tar to operate on an +incremental archive with additional metadata stored in a standalone +file, called a "snapshot file". The purpose of this file is to help +determine which files have been changed, added or deleted since the last +backup, so that the next incremental backup will contain only modified +files. The name of the snapshot file is given as an argument to the +option: + +'--listed-incremental=FILE' +'-g FILE' + Handle incremental backups with snapshot data in FILE. + + To create an incremental backup, you would use '--listed-incremental' +together with '--create' (*note create::). For example: + + $ tar --create \ + --file=archive.1.tar \ + --listed-incremental=/var/log/usr.snar \ + /usr + + This will create in 'archive.1.tar' an incremental backup of the +'/usr' file system, storing additional metadata in the file +'/var/log/usr.snar'. If this file does not exist, it will be created. +The created archive will then be a "level 0 backup"; please see the next +section for more on backup levels. + + Otherwise, if the file '/var/log/usr.snar' exists, it determines +which files are modified. In this case only these files will be stored +in the archive. Suppose, for example, that after running the above +command, you delete file '/usr/doc/old' and create directory +'/usr/local/db' with the following contents: + + $ ls /usr/local/db + /usr/local/db/data + /usr/local/db/index + + Some time later you create another incremental backup. You will then +see: + + $ tar --create \ + --file=archive.2.tar \ + --listed-incremental=/var/log/usr.snar \ + /usr + tar: usr/local/db: Directory is new + usr/local/db/ + usr/local/db/data + usr/local/db/index + +The created archive 'archive.2.tar' will contain only these three +members. This archive is called a "level 1 backup". Notice that +'/var/log/usr.snar' will be updated with the new data, so if you plan to +create more 'level 1' backups, it is necessary to create a working copy +of the snapshot file before running 'tar'. The above example will then +be modified as follows: + + $ cp /var/log/usr.snar /var/log/usr.snar-1 + $ tar --create \ + --file=archive.2.tar \ + --listed-incremental=/var/log/usr.snar-1 \ + /usr + + You can force 'level 0' backups either by removing the snapshot file +before running 'tar', or by supplying the '--level=0' option, e.g.: + + $ tar --create \ + --file=archive.2.tar \ + --listed-incremental=/var/log/usr.snar-0 \ + --level=0 \ + /usr + + Incremental dumps depend crucially on time stamps, so the results are +unreliable if you modify a file's time stamps during dumping (e.g., with +the '--atime-preserve=replace' option), or if you set the clock +backwards. + + Metadata stored in snapshot files include device numbers, which, +obviously are supposed to be non-volatile values. However, it turns out +that NFS devices have undependable values when an automounter gets in +the picture. This can lead to a great deal of spurious redumping in +incremental dumps, so it is somewhat useless to compare two NFS devices +numbers over time. The solution implemented currently is to consider +all NFS devices as being equal when it comes to comparing directories; +this is fairly gross, but there does not seem to be a better way to go. + + Apart from using NFS, there are a number of cases where relying on +device numbers can cause spurious redumping of unmodified files. For +example, this occurs when archiving LVM snapshot volumes. To avoid +this, use '--no-check-device' option: + +'--no-check-device' + Do not rely on device numbers when preparing a list of changed + files for an incremental dump. + +'--check-device' + Use device numbers when preparing a list of changed files for an + incremental dump. This is the default behavior. The purpose of + this option is to undo the effect of the '--no-check-device' if it + was given in 'TAR_OPTIONS' environment variable (*note + TAR_OPTIONS::). + + There is also another way to cope with changing device numbers. It +is described in detail in *note Fixing Snapshot Files::. + + Note that incremental archives use 'tar' extensions and may not be +readable by non-GNU versions of the 'tar' program. + + To extract from the incremental dumps, use '--listed-incremental' +together with '--extract' option (*note extracting files::). In this +case, 'tar' does not need to access snapshot file, since all the data +necessary for extraction are stored in the archive itself. So, when +extracting, you can give whatever argument to '--listed-incremental', +the usual practice is to use '--listed-incremental=/dev/null'. +Alternatively, you can use '--incremental', which needs no arguments. +In general, '--incremental' ('-G') can be used as a shortcut for +'--listed-incremental' when listing or extracting incremental backups +(for more information regarding this option, *note incremental-op::). + + When extracting from the incremental backup GNU 'tar' attempts to +restore the exact state the file system had when the archive was +created. In particular, it will _delete_ those files in the file system +that did not exist in their directories when the archive was created. +If you have created several levels of incremental files, then in order +to restore the exact contents the file system had when the last level +was created, you will need to restore from all backups in turn. +Continuing our example, to restore the state of '/usr' file system, one +would do(1): + + $ tar --extract \ + --listed-incremental=/dev/null \ + --file archive.1.tar + $ tar --extract \ + --listed-incremental=/dev/null \ + --file archive.2.tar + + To list the contents of an incremental archive, use '--list' (*note +list::), as usual. To obtain more information about the archive, use +'--listed-incremental' or '--incremental' combined with two '--verbose' +options(2): + + tar --list --incremental --verbose --verbose --file archive.tar + + This command will print, for each directory in the archive, the list +of files in that directory at the time the archive was created. This +information is put out in a format which is both human-readable and +unambiguous for a program: each file name is printed as + + X FILE + +where X is a letter describing the status of the file: 'Y' if the file +is present in the archive, 'N' if the file is not included in the +archive, or a 'D' if the file is a directory (and is included in the +archive). *Note Dumpdir::, for the detailed description of dumpdirs and +status codes. Each such line is terminated by a newline character. The +last line is followed by an additional newline to indicate the end of +the data. + + The option '--incremental' ('-G') gives the same behavior as +'--listed-incremental' when used with '--list' and '--extract' options. +When used with '--create' option, it creates an incremental archive +without creating snapshot file. Thus, it is impossible to create +several levels of incremental backups with '--incremental' option. + + ---------- Footnotes ---------- + + (1) Notice, that since both archives were created without '-P' option +(*note absolute::), these commands should be run from the root file +system. + + (2) Two '--verbose' options were selected to avoid breaking usual +verbose listing output ('--list --verbose') when using in scripts. + + Versions of GNU 'tar' up to 1.15.1 used to dump verbatim binary +contents of the DUMPDIR header (with terminating nulls) when +'--incremental' or '--listed-incremental' option was given, no matter +what the verbosity level. This behavior, and, especially, the binary +output it produced were considered inconvenient and were changed in +version 1.16. + + +File: tar.info, Node: Backup Levels, Next: Backup Parameters, Prev: Incremental Dumps, Up: Backups + +5.3 Levels of Backups +===================== + +An archive containing all the files in the file system is called a "full +backup" or "full dump". You could insure your data by creating a full +dump every day. This strategy, however, would waste a substantial +amount of archive media and user time, as unchanged files are daily +re-archived. + + It is more efficient to do a full dump only occasionally. To back up +files between full dumps, you can use "incremental dumps". A "level +one" dump archives all the files that have changed since the last full +dump. + + A typical dump strategy would be to perform a full dump once a week, +and a level one dump once a day. This means some versions of files will +in fact be archived more than once, but this dump strategy makes it +possible to restore a file system to within one day of accuracy by only +extracting two archives--the last weekly (full) dump and the last daily +(level one) dump. The only information lost would be in files changed +or created since the last daily backup. (Doing dumps more than once a +day is usually not worth the trouble.) + + GNU 'tar' comes with scripts you can use to do full and level-one +(actually, even level-two and so on) dumps. Using scripts (shell +programs) to perform backups and restoration is a convenient and +reliable alternative to typing out file name lists and 'tar' commands by +hand. + + Before you use these scripts, you need to edit the file +'backup-specs', which specifies parameters used by the backup scripts +and by the restore script. This file is usually located in +'/etc/backup' directory. *Note Backup Parameters::, for its detailed +description. Once the backup parameters are set, you can perform +backups or restoration by running the appropriate script. + + The name of the backup script is 'backup'. The name of the restore +script is 'restore'. The following sections describe their use in +detail. + + _Please Note:_ The backup and restoration scripts are designed to be +used together. While it is possible to restore files by hand from an +archive which was created using a backup script, and to create an +archive by hand which could then be extracted using the restore script, +it is easier to use the scripts. *Note Incremental Dumps::, before +making such an attempt. + + +File: tar.info, Node: Backup Parameters, Next: Scripted Backups, Prev: Backup Levels, Up: Backups + +5.4 Setting Parameters for Backups and Restoration +================================================== + +The file 'backup-specs' specifies backup parameters for the backup and +restoration scripts provided with 'tar'. You must edit 'backup-specs' +to fit your system configuration and schedule before using these +scripts. + + Syntactically, 'backup-specs' is a shell script, containing mainly +variable assignments. However, any valid shell construct is allowed in +this file. Particularly, you may wish to define functions within that +script (e.g., see 'RESTORE_BEGIN' below). For more information about +shell script syntax, please refer to the definition of the Shell Command +Language +(http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta +g_02). See also *note Bash Features: (bashref)Top. + + The shell variables controlling behavior of 'backup' and 'restore' +are described in the following subsections. + +* Menu: + +* General-Purpose Variables:: +* Magnetic Tape Control:: +* User Hooks:: +* backup-specs example:: An Example Text of 'Backup-specs' + + +File: tar.info, Node: General-Purpose Variables, Next: Magnetic Tape Control, Up: Backup Parameters + +5.4.1 General-Purpose Variables +------------------------------- + + -- Backup variable: ADMINISTRATOR + The user name of the backup administrator. 'Backup' scripts sends + a backup report to this address. + + -- Backup variable: BACKUP_HOUR + The hour at which the backups are done. This can be a number from + 0 to 23, or the time specification in form HOURS:MINUTES, or the + string 'now'. + + This variable is used by 'backup'. Its value may be overridden + using '--time' option (*note Scripted Backups::). + + -- Backup variable: TAPE_FILE + + The device 'tar' writes the archive to. If TAPE_FILE is a remote + archive (*note remote-dev::), backup script will suppose that your + 'mt' is able to access remote devices. If RSH (*note RSH::) is + set, '--rsh-command' option will be added to invocations of 'mt'. + + -- Backup variable: BLOCKING + + The blocking factor 'tar' will use when writing the dump archive. + *Note Blocking Factor::. + + -- Backup variable: BACKUP_DIRS + + A list of file systems to be dumped (for 'backup'), or restored + (for 'restore'). You can include any directory name in the list -- + subdirectories on that file system will be included, regardless of + how they may look to other networked machines. Subdirectories on + other file systems will be ignored. + + The host name specifies which host to run 'tar' on, and should + normally be the host that actually contains the file system. + However, the host machine must have GNU 'tar' installed, and must + be able to access the directory containing the backup scripts and + their support files using the same file name that is used on the + machine where the scripts are run (i.e., what 'pwd' will print when + in that directory on that machine). If the host that contains the + file system does not have this capability, you can specify another + host as long as it can access the file system through NFS. + + If the list of file systems is very long you may wish to put it in + a separate file. This file is usually named '/etc/backup/dirs', + but this name may be overridden in 'backup-specs' using 'DIRLIST' + variable. + + -- Backup variable: DIRLIST + + The name of the file that contains a list of file systems to backup + or restore. By default it is '/etc/backup/dirs'. + + -- Backup variable: BACKUP_FILES + + A list of individual files to be dumped (for 'backup'), or restored + (for 'restore'). These should be accessible from the machine on + which the backup script is run. + + If the list of individual files is very long you may wish to store + it in a separate file. This file is usually named + '/etc/backup/files', but this name may be overridden in + 'backup-specs' using 'FILELIST' variable. + + -- Backup variable: FILELIST + + The name of the file that contains a list of individual files to + backup or restore. By default it is '/etc/backup/files'. + + -- Backup variable: MT + + Full file name of 'mt' binary. + + -- Backup variable: RSH + Full file name of 'rsh' binary or its equivalent. You may wish to + set it to 'ssh', to improve security. In this case you will have + to use public key authentication. + + -- Backup variable: RSH_COMMAND + + Full file name of 'rsh' binary on remote machines. This will be + passed via '--rsh-command' option to the remote invocation of GNU + 'tar'. + + -- Backup variable: VOLNO_FILE + + Name of temporary file to hold volume numbers. This needs to be + accessible by all the machines which have file systems to be + dumped. + + -- Backup variable: XLIST + + Name of "exclude file list". An "exclude file list" is a file + located on the remote machine and containing the list of files to + be excluded from the backup. Exclude file lists are searched in + /etc/tar-backup directory. A common use for exclude file lists is + to exclude files containing security-sensitive information (e.g., + '/etc/shadow' from backups). + + This variable affects only 'backup'. + + -- Backup variable: SLEEP_TIME + + Time to sleep between dumps of any two successive file systems + + This variable affects only 'backup'. + + -- Backup variable: DUMP_REMIND_SCRIPT + + Script to be run when it's time to insert a new tape in for the + next volume. Administrators may want to tailor this script for + their site. If this variable isn't set, GNU 'tar' will display its + built-in prompt, and will expect confirmation from the console. + For the description of the default prompt, see *note change volume + prompt::. + + -- Backup variable: SLEEP_MESSAGE + + Message to display on the terminal while waiting for dump time. + Usually this will just be some literal text. + + -- Backup variable: TAR + + Full file name of the GNU 'tar' executable. If this is not set, + backup scripts will search 'tar' in the current shell path. + + +File: tar.info, Node: Magnetic Tape Control, Next: User Hooks, Prev: General-Purpose Variables, Up: Backup Parameters + +5.4.2 Magnetic Tape Control +--------------------------- + +Backup scripts access tape device using special "hook functions". These +functions take a single argument -- the name of the tape device. Their +names are kept in the following variables: + + -- Backup variable: MT_BEGIN + The name of "begin" function. This function is called before + accessing the drive. By default it retensions the tape: + + MT_BEGIN=mt_begin + + mt_begin() { + mt -f "$1" retension + } + + -- Backup variable: MT_REWIND + The name of "rewind" function. The default definition is as + follows: + + MT_REWIND=mt_rewind + + mt_rewind() { + mt -f "$1" rewind + } + + -- Backup variable: MT_OFFLINE + The name of the function switching the tape off line. By default + it is defined as follows: + + MT_OFFLINE=mt_offline + + mt_offline() { + mt -f "$1" offl + } + + -- Backup variable: MT_STATUS + The name of the function used to obtain the status of the archive + device, including error count. Default definition: + + MT_STATUS=mt_status + + mt_status() { + mt -f "$1" status + } + + +File: tar.info, Node: User Hooks, Next: backup-specs example, Prev: Magnetic Tape Control, Up: Backup Parameters + +5.4.3 User Hooks +---------------- + +"User hooks" are shell functions executed before and after each 'tar' +invocation. Thus, there are "backup hooks", which are executed before +and after dumping each file system, and "restore hooks", executed before +and after restoring a file system. Each user hook is a shell function +taking four arguments: + + -- User Hook Function: hook LEVEL HOST FS FSNAME + Its arguments are: + + LEVEL + Current backup or restore level. + + HOST + Name or IP address of the host machine being dumped or + restored. + + FS + Full file name of the file system being dumped or restored. + + FSNAME + File system name with directory separators replaced with + colons. This is useful, e.g., for creating unique files. + + Following variables keep the names of user hook functions: + + -- Backup variable: DUMP_BEGIN + Dump begin function. It is executed before dumping the file + system. + + -- Backup variable: DUMP_END + Executed after dumping the file system. + + -- Backup variable: RESTORE_BEGIN + Executed before restoring the file system. + + -- Backup variable: RESTORE_END + Executed after restoring the file system. + + +File: tar.info, Node: backup-specs example, Prev: User Hooks, Up: Backup Parameters + +5.4.4 An Example Text of 'Backup-specs' +--------------------------------------- + +The following is an example of 'backup-specs': + + # site-specific parameters for file system backup. + + ADMINISTRATOR=friedman + BACKUP_HOUR=1 + TAPE_FILE=/dev/nrsmt0 + + # Use ssh instead of the less secure rsh + RSH=/usr/bin/ssh + RSH_COMMAND=/usr/bin/ssh + + # Override MT_STATUS function: + my_status() { + mts -t $TAPE_FILE + } + MT_STATUS=my_status + + # Disable MT_OFFLINE function + MT_OFFLINE=: + + BLOCKING=124 + BACKUP_DIRS=" + albert:/fs/fsf + apple-gunkies:/gd + albert:/fs/gd2 + albert:/fs/gp + geech:/usr/jla + churchy:/usr/roland + albert:/ + albert:/usr + apple-gunkies:/ + apple-gunkies:/usr + gnu:/hack + gnu:/u + apple-gunkies:/com/mailer/gnu + apple-gunkies:/com/archive/gnu" + + BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]" + + + +File: tar.info, Node: Scripted Backups, Next: Scripted Restoration, Prev: Backup Parameters, Up: Backups + +5.5 Using the Backup Scripts +============================ + +The syntax for running a backup script is: + + backup --level=LEVEL --time=TIME + + The '--level' option requests the dump level. Thus, to produce a +full dump, specify '--level=0' (this is the default, so '--level' may be +omitted if its value is '0')(1). + + The '--time' option determines when should the backup be run. TIME +may take three forms: + +HH:MM + + The dump must be run at HH hours MM minutes. + +HH + + The dump must be run at HH hours. + +now + + The dump must be run immediately. + + You should start a script with a tape or disk mounted. Once you +start a script, it prompts you for new tapes or disks as it needs them. +Media volumes don't have to correspond to archive files -- a +multi-volume archive can be started in the middle of a tape that already +contains the end of another multi-volume archive. The 'restore' script +prompts for media by its archive volume, so to avoid an error message +you should keep track of which tape (or disk) contains which volume of +the archive (*note Scripted Restoration::). + + The backup scripts write two files on the file system. The first is +a record file in '/etc/tar-backup/', which is used by the scripts to +store and retrieve information about which files were dumped. This file +is not meant to be read by humans, and should not be deleted by them. +*Note Snapshot Files::, for a more detailed explanation of this file. + + The second file is a log file containing the names of the file +systems and files dumped, what time the backup was made, and any error +messages that were generated, as well as how much space was left in the +media volume after the last volume of the archive was written. You +should check this log file after every backup. The file name is +'log-MM-DD-YYYY-level-N', where MM-DD-YYYY represents current date, and +N represents current dump level number. + + The script also prints the name of each system being dumped to the +standard output. + + Following is the full list of options accepted by 'backup' script: + +'-l LEVEL' +'--level=LEVEL' + Do backup level LEVEL (default 0). + +'-f' +'--force' + Force backup even if today's log file already exists. + +'-v[LEVEL]' +'--verbose[=LEVEL]' + Set verbosity level. The higher the level is, the more debugging + information will be output during execution. Default LEVEL is 100, + which means the highest debugging level. + +'-t START-TIME' +'--time=START-TIME' + Wait till TIME, then do backup. + +'-h' +'--help' + Display short help message and exit. + +'-V' +'--version' + Display information about the program's name, version, origin and + legal status, all on standard output, and then exit successfully. + + ---------- Footnotes ---------- + + (1) For backward compatibility, the 'backup' will also try to deduce +the requested dump level from the name of the script itself. If the +name consists of a string 'level-' followed by a single decimal digit, +that digit is taken as the dump level number. Thus, you may create a +link from 'backup' to 'level-1' and then run 'level-1' whenever you need +to create a level one dump. + + +File: tar.info, Node: Scripted Restoration, Prev: Scripted Backups, Up: Backups + +5.6 Using the Restore Script +============================ + +To restore files that were archived using a scripted backup, use the +'restore' script. Its usage is quite straightforward. In the simplest +form, invoke 'restore --all', it will then restore all the file systems +and files specified in 'backup-specs' (*note BACKUP_DIRS: +General-Purpose Variables.). + + You may select the file systems (and/or files) to restore by giving +'restore' a list of "patterns" in its command line. For example, +running + + restore 'albert:*' + +will restore all file systems on the machine 'albert'. A more +complicated example: + + restore 'albert:*' '*:/var' + +This command will restore all file systems on the machine 'albert' as +well as '/var' file system on all machines. + + By default 'restore' will start restoring files from the lowest +available dump level (usually zero) and will continue through all +available dump levels. There may be situations where such a thorough +restore is not necessary. For example, you may wish to restore only +files from the recent level one backup. To do so, use '--level' option, +as shown in the example below: + + restore --level=1 + + The full list of options accepted by 'restore' follows: + +'-a' +'--all' + Restore all file systems and files specified in 'backup-specs'. + +'-l LEVEL' +'--level=LEVEL' + Start restoring from the given backup level, instead of the default + 0. + +'-v[LEVEL]' +'--verbose[=LEVEL]' + Set verbosity level. The higher the level is, the more debugging + information will be output during execution. Default LEVEL is 100, + which means the highest debugging level. + +'-h' +'--help' + Display short help message and exit. + +'-V' +'--version' + Display information about the program's name, version, origin and + legal status, all on standard output, and then exit successfully. + + You should start the restore script with the media containing the +first volume of the archive mounted. The script will prompt for other +volumes as they are needed. If the archive is on tape, you don't need +to rewind the tape to to its beginning--if the tape head is positioned +past the beginning of the archive, the script will rewind the tape as +needed. *Note Tape Positioning::, for a discussion of tape positioning. + + *Warning:* The script will delete files from the active file system + if they were not in the file system when the archive was made. + + *Note Incremental Dumps::, for an explanation of how the script makes +that determination. + + +File: tar.info, Node: Choosing, Next: Date input formats, Prev: Backups, Up: Top + +6 Choosing Files and Names for 'tar' +************************************ + +Certain options to 'tar' enable you to specify a name for your archive. +Other options let you decide which files to include or exclude from the +archive, based on when or whether files were modified, whether the file +names do or don't match specified patterns, or whether files are in +specified directories. + + This chapter discusses these options in detail. + +* Menu: + +* file:: Choosing the Archive's Name +* Selecting Archive Members:: +* files:: Reading Names from a File +* exclude:: Excluding Some Files +* wildcards:: Wildcards Patterns and Matching +* quoting styles:: Ways of Quoting Special Characters in Names +* transform:: Modifying File and Member Names +* after:: Operating Only on New Files +* recurse:: Descending into Directories +* one:: Crossing File System Boundaries + + +File: tar.info, Node: file, Next: Selecting Archive Members, Up: Choosing + +6.1 Choosing and Naming Archive Files +===================================== + +By default, 'tar' uses an archive file name that was compiled when it +was built on the system; usually this name refers to some physical tape +drive on the machine. However, the person who installed 'tar' on the +system may not have set the default to a meaningful value as far as most +users are concerned. As a result, you will usually want to tell 'tar' +where to find (or create) the archive. The '--file=ARCHIVE-NAME' ('-f +ARCHIVE-NAME') option allows you to either specify or name a file to use +as the archive instead of the default archive file location. + +'--file=ARCHIVE-NAME' +'-f ARCHIVE-NAME' + Name the archive to create or operate on. Use in conjunction with + any operation. + + For example, in this 'tar' command, + + $ tar -cvf collection.tar blues folk jazz + +'collection.tar' is the name of the archive. It must directly follow +the '-f' option, since whatever directly follows '-f' _will_ end up +naming the archive. If you neglect to specify an archive name, you may +end up overwriting a file in the working directory with the archive you +create since 'tar' will use this file's name for the archive name. + + An archive can be saved as a file in the file system, sent through a +pipe or over a network, or written to an I/O device such as a tape, +floppy disk, or CD write drive. + + If you do not name the archive, 'tar' uses the value of the +environment variable 'TAPE' as the file name for the archive. If that +is not available, 'tar' uses a default, compiled-in archive name, +usually that for tape unit zero (i.e., '/dev/tu00'). + + If you use '-' as an ARCHIVE-NAME, 'tar' reads the archive from +standard input (when listing or extracting files), or writes it to +standard output (when creating an archive). If you use '-' as an +ARCHIVE-NAME when modifying an archive, 'tar' reads the original archive +from its standard input and writes the entire new archive to its +standard output. + + The following example is a convenient way of copying directory +hierarchy from 'sourcedir' to 'targetdir'. + + $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -) + + The '-C' option allows to avoid using subshells: + + $ tar -C sourcedir -cf - . | tar -C targetdir -xpf - + + In both examples above, the leftmost 'tar' invocation archives the +contents of 'sourcedir' to the standard output, while the rightmost one +reads this archive from its standard input and extracts it. The '-p' +option tells it to restore permissions of the extracted files. + + To specify an archive file on a device attached to a remote machine, +use the following: + + --file=HOSTNAME:/DEV/FILE-NAME + +'tar' will set up the remote connection, if possible, and prompt you for +a username and password. If you use '--file=@HOSTNAME:/DEV/FILE-NAME', +'tar' will attempt to set up the remote connection using your username +as the username on the remote machine. + + If the archive file name includes a colon (':'), then it is assumed +to be a file on another machine. If the archive file is +'USER@HOST:FILE', then FILE is used on the host HOST. The remote host +is accessed using the 'rsh' program, with a username of USER. If the +username is omitted (along with the '@' sign), then your user name will +be used. (This is the normal 'rsh' behavior.) It is necessary for the +remote machine, in addition to permitting your 'rsh' access, to have the +'rmt' program installed (this command is included in the GNU 'tar' +distribution and by default is installed under 'PREFIX/libexec/rmt', +where PREFIX means your installation prefix). If you need to use a file +whose name includes a colon, then the remote tape drive behavior can be +inhibited by using the '--force-local' option. + + When the archive is being created to '/dev/null', GNU 'tar' tries to +minimize input and output operations. The Amanda backup system, when +used with GNU 'tar', has an initial sizing pass which uses this feature. + + +File: tar.info, Node: Selecting Archive Members, Next: files, Prev: file, Up: Choosing + +6.2 Selecting Archive Members +============================= + +"File Name arguments" specify which files in the file system 'tar' +operates on, when creating or adding to an archive, or which archive +members 'tar' operates on, when reading or deleting from an archive. +*Note Operations::. + + To specify file names, you can include them as the last arguments on +the command line, as follows: + tar OPERATION [OPTION1 OPTION2 ...] [FILE NAME-1 FILE NAME-2 ...] + + If a file name begins with dash ('-'), precede it with '--add-file' +option to prevent it from being treated as an option. + + By default GNU 'tar' attempts to "unquote" each file or member name, +replacing "escape sequences" according to the following table: + +Escape Replaced with +----------------------------------------------------------- +\a Audible bell (ASCII 7) +\b Backspace (ASCII 8) +\f Form feed (ASCII 12) +\n New line (ASCII 10) +\r Carriage return (ASCII 13) +\t Horizontal tabulation (ASCII 9) +\v Vertical tabulation (ASCII 11) +\? ASCII 127 +\N ASCII N (N should be an octal number of + up to 3 digits) + + A backslash followed by any other symbol is retained. + + This default behavior is controlled by the following command line +option: + +'--unquote' + Enable unquoting input file or member names (default). + +'--no-unquote' + Disable unquoting input file or member names. + + If you specify a directory name as a file name argument, all the +files in that directory are operated on by 'tar'. + + If you do not specify files, 'tar' behavior differs depending on the +operation mode as described below: + + When 'tar' is invoked with '--create' ('-c'), 'tar' will stop +immediately, reporting the following: + + $ tar cf a.tar + tar: Cowardly refusing to create an empty archive + Try 'tar --help' or 'tar --usage' for more information. + + If you specify either '--list' ('-t') or '--extract' ('--get', '-x'), +'tar' operates on all the archive members in the archive. + + If run with '--diff' option, tar will compare the archive with the +contents of the current working directory. + + If you specify any other operation, 'tar' does nothing. + + By default, 'tar' takes file names from the command line. However, +there are other ways to specify file or member names, or to modify the +manner in which 'tar' selects the files or members upon which to +operate. In general, these methods work both for specifying the names +of files and archive members. + + +File: tar.info, Node: files, Next: exclude, Prev: Selecting Archive Members, Up: Choosing + +6.3 Reading Names from a File +============================= + +Instead of giving the names of files or archive members on the command +line, you can put the names into a file, and then use the +'--files-from=FILE-OF-NAMES' ('-T FILE-OF-NAMES') option to 'tar'. Give +the name of the file which contains the list of files to include as the +argument to '--files-from'. In the list, the file names should be +separated by newlines. You will frequently use this option when you +have generated the list of files to archive with the 'find' utility. + +'--files-from=FILE-NAME' +'-T FILE-NAME' + Get names to extract or create from file FILE-NAME. + + If you give a single dash as a file name for '--files-from', (i.e., +you specify either '--files-from=-' or '-T -'), then the file names are +read from standard input. + + Unless you are running 'tar' with '--create', you cannot use both +'--files-from=-' and '--file=-' ('-f -') in the same command. + + Any number of '-T' options can be given in the command line. + + The following example shows how to use 'find' to generate a list of +files smaller than 400K in length and put that list into a file called +'small-files'. You can then use the '-T' option to 'tar' to specify the +files from that file, 'small-files', to create the archive 'little.tgz'. +(The '-z' option to 'tar' compresses the archive with 'gzip'; *note +gzip:: for more information.) + + $ find . -size -400 -print > small-files + $ tar -c -v -z -T small-files -f little.tgz + +By default, each line read from the file list is first stripped off any +leading and trailing whitespace. If the resulting string begins with +'-' character, it is considered a 'tar' option and is processed +accordingly(1). For example, the common use of this feature is to +change to another directory by specifying '-C' option: + + $ cat list + -C/etc + passwd + hosts + -C/lib + libc.a + $ tar -c -f foo.tar --files-from list + +In this example, 'tar' will first switch to '/etc' directory and add +files 'passwd' and 'hosts' to the archive. Then it will change to +'/lib' directory and will archive the file 'libc.a'. Thus, the +resulting archive 'foo.tar' will contain: + + $ tar tf foo.tar + passwd + hosts + libc.a + + Note, that any options used in the file list remain in effect for the +rest of the command line. For example, using the same 'list' file as +above, the following command + + $ tar -c -f foo.tar --files-from list libcurses.a + +will look for file 'libcurses.a' in the directory '/lib', because it was +used with the last '-C' option (*note Position-Sensitive Options::). + + If such option handling is undesirable, use the +'--verbatim-files-from' option. When this option is in effect, each +line read from the file list is treated as a file name. Notice, that +this means, in particular, that no whitespace trimming is performed. + + The '--verbatim-files-from' affects all '-T' options that follow it +in the command line. The default behavior can be restored using +'--no-verbatim-files-from' option. + + To disable option handling for a single file name, use the +'--add-file' option, e.g.: '--add-file=--my-file'. + + You can use any GNU 'tar' command line options in the file list file, +including '--files-from' option itself. This allows for including +contents of a file list into another file list file. Note however, that +options that control file list processing, such as +'--verbatim-files-from' or '--null' won't affect the file they appear +in. They will affect next '--files-from' option, if there is any. + +* Menu: + +* nul:: + + ---------- Footnotes ---------- + + (1) Versions of GNU 'tar' up to 1.15.1 recognized only '-C' option in +file lists, and only if the option and its argument occupied two +consecutive lines. + + +File: tar.info, Node: nul, Up: files + +6.3.1 'NUL'-Terminated File Names +--------------------------------- + +The '--null' option causes '--files-from=FILE-OF-NAMES' ('-T +FILE-OF-NAMES') to read file names terminated by a 'NUL' instead of a +newline, so files whose names contain newlines can be archived using +'--files-from'. + +'--null' + Only consider 'NUL'-terminated file names, instead of files that + terminate in a newline. + +'--no-null' + Undo the effect of any previous '--null' option. + + The '--null' option is just like the one in GNU 'xargs' and 'cpio', +and is useful with the '-print0' predicate of GNU 'find'. In 'tar', +'--null' also disables special handling for file names that begin with +dash (similar to '--verbatim-files-from' option). + + This example shows how to use 'find' to generate a list of files +larger than 800K in length and put that list into a file called +'long-files'. The '-print0' option to 'find' is just like '-print', +except that it separates files with a 'NUL' rather than with a newline. +You can then run 'tar' with both the '--null' and '-T' options to +specify that 'tar' gets the files from that file, 'long-files', to +create the archive 'big.tgz'. The '--null' option to 'tar' will cause +'tar' to recognize the 'NUL' separator between files. + + $ find . -size +800 -print0 > long-files + $ tar -c -v --null --files-from=long-files --file=big.tar + + The '--no-null' option can be used if you need to read both +'NUL'-terminated and newline-terminated files on the same command line. +For example, if 'flist' is a newline-terminated file, then the following +command can be used to combine it with the above command: + + $ find . -size +800 -print0 | + tar -c -f big.tar --null -T - --no-null -T flist + + This example uses short options for typographic reasons, to avoid +very long lines. + + GNU 'tar' is tries to automatically detect 'NUL'-terminated file +lists, so in many cases it is safe to use them even without the '--null' +option. In this case 'tar' will print a warning and continue reading +such a file as if '--null' were actually given: + + $ find . -size +800 -print0 | tar -c -f big.tar -T - + tar: -: file name read contains nul character + + The null terminator, however, remains in effect only for this +particular file, any following '-T' options will assume newline +termination. Of course, the null autodetection applies to these +eventual surplus '-T' options as well. + + +File: tar.info, Node: exclude, Next: wildcards, Prev: files, Up: Choosing + +6.4 Excluding Some Files +======================== + +To avoid operating on files whose names match a particular pattern, use +the '--exclude' or '--exclude-from' options. + +'--exclude=PATTERN' + Causes 'tar' to ignore files that match the PATTERN. + + The '--exclude=PATTERN' option prevents any file or member whose name +matches the shell wildcard (PATTERN) from being operated on. For +example, to create an archive with all the contents of the directory +'src' except for files whose names end in '.o', use the command 'tar -cf +src.tar --exclude='*.o' src'. + + You may give multiple '--exclude' options. + +'--exclude-from=FILE' +'-X FILE' + Causes 'tar' to ignore files that match the patterns listed in + FILE. + + Use the '--exclude-from' option to read a list of patterns, one per +line, from FILE; 'tar' will ignore files matching those patterns. Thus +if 'tar' is called as 'tar -c -X foo .' and the file 'foo' contains a +single line '*.o', no files whose names end in '.o' will be added to the +archive. + + Notice, that lines from FILE are read verbatim. One of the frequent +errors is leaving some extra whitespace after a file name, which is +difficult to catch using text editors. + + However, empty lines are OK. + + When archiving directories that are under some version control system +(VCS), it is often convenient to read exclusion patterns from this VCS' +ignore files (e.g. '.cvsignore', '.gitignore', etc.) The following +options provide such possibility: + +'--exclude-vcs-ignores' + Before archiving a directory, see if it contains any of the + following files: 'cvsignore', '.gitignore', '.bzrignore', or + '.hgignore'. If so, read ignore patterns from these files. + + The patterns are treated much as the corresponding VCS would treat + them, i.e.: + + '.cvsignore' + Contains shell-style globbing patterns that apply only to the + directory where this file resides. No comments are allowed in + the file. Empty lines are ignored. + + '.gitignore' + Contains shell-style globbing patterns. Applies to the + directory where '.gitfile' is located and all its + subdirectories. + + Any line beginning with a '#' is a comment. Backslash escapes + the comment character. + + '.bzrignore' + Contains shell globbing-patterns and regular expressions (if + prefixed with 'RE:'(1). Patterns affect the directory and all + its subdirectories. + + Any line beginning with a '#' is a comment. + + '.hgignore' + Contains posix regular expressions(2). The line 'syntax: + glob' switches to shell globbing patterns. The line 'syntax: + regexp' switches back. Comments begin with a '#'. Patterns + affect the directory and all its subdirectories. + +'--exclude-ignore=FILE' + Before dumping a directory, 'tar' checks if it contains FILE. If + so, exclusion patterns are read from this file. The patterns + affect only the directory itself. + +'--exclude-ignore-recursive=FILE' + Same as '--exclude-ignore', except that the patterns read affect + both the directory where FILE resides and all its subdirectories. + +'--exclude-vcs' + Exclude files and directories used by following version control + systems: 'CVS', 'RCS', 'SCCS', 'SVN', 'Arch', 'Bazaar', + 'Mercurial', and 'Darcs'. + + As of version 1.29, the following files are excluded: + + * 'CVS/', and everything under it + * 'RCS/', and everything under it + * 'SCCS/', and everything under it + * '.git/', and everything under it + * '.gitignore' + * '.gitmodules' + * '.gitattributes' + * '.cvsignore' + * '.svn/', and everything under it + * '.arch-ids/', and everything under it + * '{arch}/', and everything under it + * '=RELEASE-ID' + * '=meta-update' + * '=update' + * '.bzr' + * '.bzrignore' + * '.bzrtags' + * '.hg' + * '.hgignore' + * '.hgrags' + * '_darcs' + +'--exclude-backups' + Exclude backup and lock files. This option causes exclusion of + files that match the following shell globbing patterns: + + .#* + *~ + #*# + + When creating an archive, the '--exclude-caches' option family causes +'tar' to exclude all directories that contain a "cache directory tag". +A cache directory tag is a short file with the well-known name +'CACHEDIR.TAG' and having a standard header specified in +<http://www.brynosaurus.com/cachedir/spec.html>. Various applications +write cache directory tags into directories they use to hold +regenerable, non-precious data, so that such data can be more easily +excluded from backups. + + There are three 'exclude-caches' options, each providing a different +exclusion semantics: + +'--exclude-caches' + Do not archive the contents of the directory, but archive the + directory itself and the 'CACHEDIR.TAG' file. + +'--exclude-caches-under' + Do not archive the contents of the directory, nor the + 'CACHEDIR.TAG' file, archive only the directory itself. + +'--exclude-caches-all' + Omit directories containing 'CACHEDIR.TAG' file entirely. + + Another option family, '--exclude-tag', provides a generalization of +this concept. It takes a single argument, a file name to look for. Any +directory that contains this file will be excluded from the dump. +Similarly to 'exclude-caches', there are three options in this option +family: + +'--exclude-tag=FILE' + Do not dump the contents of the directory, but dump the directory + itself and the FILE. + +'--exclude-tag-under=FILE' + Do not dump the contents of the directory, nor the FILE, archive + only the directory itself. + +'--exclude-tag-all=FILE' + Omit directories containing FILE file entirely. + + Multiple '--exclude-tag*' options can be given. + + For example, given this directory: + + $ find dir + dir + dir/blues + dir/jazz + dir/folk + dir/folk/tagfile + dir/folk/sanjuan + dir/folk/trote + + The '--exclude-tag' will produce the following: + + $ tar -cf archive.tar --exclude-tag=tagfile -v dir + dir/ + dir/blues + dir/jazz + dir/folk/ + tar: dir/folk/: contains a cache directory tag tagfile; + contents not dumped + dir/folk/tagfile + + Both the 'dir/folk' directory and its tagfile are preserved in the +archive, however the rest of files in this directory are not. + + Now, using the '--exclude-tag-under' option will exclude 'tagfile' +from the dump, while still preserving the directory itself, as shown in +this example: + + $ tar -cf archive.tar --exclude-tag-under=tagfile -v dir + dir/ + dir/blues + dir/jazz + dir/folk/ + ./tar: dir/folk/: contains a cache directory tag tagfile; + contents not dumped + + Finally, using '--exclude-tag-all' omits the 'dir/folk' directory +entirely: + + $ tar -cf archive.tar --exclude-tag-all=tagfile -v dir + dir/ + dir/blues + dir/jazz + ./tar: dir/folk/: contains a cache directory tag tagfile; + directory not dumped + +* Menu: + +* problems with exclude:: + + ---------- Footnotes ---------- + + (1) According to the Bazaar docs, globbing-patterns are Korn-shell +style and regular expressions are perl-style. As of GNU 'tar' version +1.29, these are treated as shell-style globs and posix extended regexps. +This will be fixed in future releases. + + (2) Support for perl-style regexps will appear in future releases. + + +File: tar.info, Node: problems with exclude, Up: exclude + +Problems with Using the 'exclude' Options +----------------------------------------- + +Some users find 'exclude' options confusing. Here are some common +pitfalls: + + * The main operating mode of 'tar' does not act on a file name + explicitly listed on the command line, if one of its file name + components is excluded. In the example above, if you create an + archive and exclude files that end with '*.o', but explicitly name + the file 'dir.o/foo' after all the options have been listed, + 'dir.o/foo' will be excluded from the archive. + + * You can sometimes confuse the meanings of '--exclude' and + '--exclude-from'. Be careful: use '--exclude' when files to be + excluded are given as a pattern on the command line. Use + '--exclude-from' to introduce the name of a file which contains a + list of patterns, one per line; each of these patterns can exclude + zero, one, or many files. + + * When you use '--exclude=PATTERN', be sure to quote the PATTERN + parameter, so GNU 'tar' sees wildcard characters like '*'. If you + do not do this, the shell might expand the '*' itself using files + at hand, so 'tar' might receive a list of files instead of one + pattern, or none at all, making the command somewhat illegal. This + might not correspond to what you want. + + For example, write: + + $ tar -c -f ARCHIVE.TAR --exclude '*.o' DIRECTORY + + rather than: + + # _Wrong!_ + $ tar -c -f ARCHIVE.TAR --exclude *.o DIRECTORY + + * You must use use shell syntax, or globbing, rather than 'regexp' + syntax, when using exclude options in 'tar'. If you try to use + 'regexp' syntax to describe files to be excluded, your command + might fail. + + * + In earlier versions of 'tar', what is now the '--exclude-from' + option was called '--exclude' instead. Now, '--exclude' applies to + patterns listed on the command line and '--exclude-from' applies to + patterns listed in a file. + + +File: tar.info, Node: wildcards, Next: quoting styles, Prev: exclude, Up: Choosing + +6.5 Wildcards Patterns and Matching +=================================== + +"Globbing" is the operation by which "wildcard" characters, '*' or '?' +for example, are replaced and expanded into all existing files matching +the given pattern. GNU 'tar' can use wildcard patterns for matching (or +globbing) archive members when extracting from or listing an archive. +Wildcard patterns are also used for verifying volume labels of 'tar' +archives. This section has the purpose of explaining wildcard syntax +for 'tar'. + + A PATTERN should be written according to shell syntax, using wildcard +characters to effect globbing. Most characters in the pattern stand for +themselves in the matched string, and case is significant: 'a' will +match only 'a', and not 'A'. The character '?' in the pattern matches +any single character in the matched string. The character '*' in the +pattern matches zero, one, or more single characters in the matched +string. The character '\' says to take the following character of the +pattern _literally_; it is useful when one needs to match the '?', '*', +'[' or '\' characters, themselves. + + The character '[', up to the matching ']', introduces a character +class. A "character class" is a list of acceptable characters for the +next single character of the matched string. For example, '[abcde]' +would match any of the first five letters of the alphabet. Note that +within a character class, all of the "special characters" listed above +other than '\' lose their special meaning; for example, '[-\\[*?]]' +would match any of the characters, '-', '\', '[', '*', '?', or ']'. +(Due to parsing constraints, the characters '-' and ']' must either come +_first_ or _last_ in a character class.) + + If the first character of the class after the opening '[' is '!' or +'^', then the meaning of the class is reversed. Rather than listing +character to match, it lists those characters which are _forbidden_ as +the next single character of the matched string. + + Other characters of the class stand for themselves. The special +construction '[A-E]', using an hyphen between two letters, is meant to +represent all characters between A and E, inclusive. + + Periods ('.') or forward slashes ('/') are not considered special for +wildcard matches. However, if a pattern completely matches a directory +prefix of a matched string, then it matches the full matched string: +thus, excluding a directory also excludes all the files beneath it. + +* Menu: + +* controlling pattern-matching:: + + +File: tar.info, Node: controlling pattern-matching, Up: wildcards + +Controlling Pattern-Matching +---------------------------- + +For the purposes of this section, we call "exclusion members" all member +names obtained while processing '--exclude' and '--exclude-from' +options, and "inclusion members" those member names that were given in +the command line or read from the file specified with '--files-from' +option. + + These two pairs of member lists are used in the following operations: +'--diff', '--extract', '--list', '--update'. + + There are no inclusion members in create mode ('--create' and +'--append'), since in this mode the names obtained from the command line +refer to _files_, not archive members. + + By default, inclusion members are compared with archive members +literally (1) and exclusion members are treated as globbing patterns. +For example: + + $ tar tf foo.tar + a.c + b.c + a.txt + [remarks] + # Member names are used verbatim: + $ tar -xf foo.tar -v '[remarks]' + [remarks] + # Exclude member names are globbed: + $ tar -xf foo.tar -v --exclude '*.c' + a.txt + [remarks] + + This behavior can be altered by using the following options: + +'--wildcards' + Treat all member names as wildcards. + +'--no-wildcards' + Treat all member names as literal strings. + + Thus, to extract files whose names end in '.c', you can use: + + $ tar -xf foo.tar -v --wildcards '*.c' + a.c + b.c + +Notice quoting of the pattern to prevent the shell from interpreting it. + + The effect of '--wildcards' option is canceled by '--no-wildcards'. +This can be used to pass part of the command line arguments verbatim and +other part as globbing patterns. For example, the following invocation: + + $ tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]' + +instructs 'tar' to extract from 'foo.tar' all files whose names end in +'.txt' and the file named '[remarks]'. + + Normally, a pattern matches a name if an initial subsequence of the +name's components matches the pattern, where '*', '?', and '[...]' are +the usual shell wildcards, '\' escapes wildcards, and wildcards can +match '/'. + + Other than optionally stripping leading '/' from names (*note +absolute::), patterns and names are used as-is. For example, trailing +'/' is not trimmed from a user-specified name before deciding whether to +exclude it. + + However, this matching procedure can be altered by the options listed +below. These options accumulate. For example: + + --ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme' + +ignores case when excluding 'makefile', but not when excluding 'readme'. + +'--anchored' +'--no-anchored' + If anchored, a pattern must match an initial subsequence of the + name's components. Otherwise, the pattern can match any + subsequence. Default is '--no-anchored' for exclusion members and + '--anchored' inclusion members. + +'--ignore-case' +'--no-ignore-case' + When ignoring case, upper-case patterns match lower-case names and + vice versa. When not ignoring case (the default), matching is + case-sensitive. + +'--wildcards-match-slash' +'--no-wildcards-match-slash' + When wildcards match slash (the default for exclusion members), a + wildcard like '*' in the pattern can match a '/' in the name. + Otherwise, '/' is matched only by '/'. + + The '--recursion' and '--no-recursion' options (*note recurse::) also +affect how member patterns are interpreted. If recursion is in effect, +a pattern matches a name if it matches any of the name's parent +directories. + + The following table summarizes pattern-matching default values: + +Members Default settings +-------------------------------------------------------------------------- +Inclusion '--no-wildcards --anchored + --no-wildcards-match-slash' +Exclusion '--wildcards --no-anchored + --wildcards-match-slash' + + ---------- Footnotes ---------- + + (1) Notice that earlier GNU 'tar' versions used globbing for +inclusion members, which contradicted to UNIX98 specification and was +not documented. *Note Changes::, for more information on this and other +changes. + + +File: tar.info, Node: quoting styles, Next: transform, Prev: wildcards, Up: Choosing + +6.6 Quoting Member Names +======================== + +When displaying member names, 'tar' takes care to avoid ambiguities +caused by certain characters. This is called "name quoting". The +characters in question are: + + * Non-printable control characters: + Character ASCII Character name + ------------------------------------------------------------------- + \a 7 Audible bell + \b 8 Backspace + \f 12 Form feed + \n 10 New line + \r 13 Carriage return + \t 9 Horizontal tabulation + \v 11 Vertical tabulation + + * Space (ASCII 32) + + * Single and double quotes (''' and '"') + + * Backslash ('\') + + The exact way 'tar' uses to quote these characters depends on the +"quoting style". The default quoting style, called "escape" (see +below), uses backslash notation to represent control characters, space +and backslash. Using this quoting style, control characters are +represented as listed in column 'Character' in the above table, a space +is printed as '\ ' and a backslash as '\\'. + + GNU 'tar' offers seven distinct quoting styles, which can be selected +using '--quoting-style' option: + +'--quoting-style=STYLE' + + Sets quoting style. Valid values for STYLE argument are: literal, + shell, shell-always, c, escape, locale, clocale. + + These styles are described in detail below. To illustrate their +effect, we will use an imaginary tar archive 'arch.tar' containing the +following members: + + # 1. Contains horizontal tabulation character. + a tab + # 2. Contains newline character + a + newline + # 3. Contains a space + a space + # 4. Contains double quotes + a"double"quote + # 5. Contains single quotes + a'single'quote + # 6. Contains a backslash character: + a\backslash + + Here is how usual 'ls' command would have listed them, if they had +existed in the current working directory: + + $ ls + a\ttab + a\nnewline + a\ space + a"double"quote + a'single'quote + a\\backslash + + Quoting styles: + +'literal' + No quoting, display each character as is: + + $ tar tf arch.tar --quoting-style=literal + ./ + ./a space + ./a'single'quote + ./a"double"quote + ./a\backslash + ./a tab + ./a + newline + +'shell' + Display characters the same way Bourne shell does: control + characters, except '\t' and '\n', are printed using backslash + escapes, '\t' and '\n' are printed as is, and a single quote is + printed as '\''. If a name contains any quoted characters, it is + enclosed in single quotes. In particular, if a name contains + single quotes, it is printed as several single-quoted strings: + + $ tar tf arch.tar --quoting-style=shell + ./ + './a space' + './a'\''single'\''quote' + './a"double"quote' + './a\backslash' + './a tab' + './a + newline' + +'shell-always' + Same as 'shell', but the names are always enclosed in single + quotes: + + $ tar tf arch.tar --quoting-style=shell-always + './' + './a space' + './a'\''single'\''quote' + './a"double"quote' + './a\backslash' + './a tab' + './a + newline' + +'c' + Use the notation of the C programming language. All names are + enclosed in double quotes. Control characters are quoted using + backslash notations, double quotes are represented as '\"', + backslash characters are represented as '\\'. Single quotes and + spaces are not quoted: + + $ tar tf arch.tar --quoting-style=c + "./" + "./a space" + "./a'single'quote" + "./a\"double\"quote" + "./a\\backslash" + "./a\ttab" + "./a\nnewline" + +'escape' + Control characters are printed using backslash notation, a space is + printed as '\ ' and a backslash as '\\'. This is the default + quoting style, unless it was changed when configured the package. + + $ tar tf arch.tar --quoting-style=escape + ./ + ./a space + ./a'single'quote + ./a"double"quote + ./a\\backslash + ./a\ttab + ./a\nnewline + +'locale' + Control characters, single quote and backslash are printed using + backslash notation. All names are quoted using left and right + quotation marks, appropriate to the current locale. If it does not + define quotation marks, use ''' as left and as right quotation + marks. Any occurrences of the right quotation mark in a name are + escaped with '\', for example: + + For example: + + $ tar tf arch.tar --quoting-style=locale + './' + './a space' + './a\'single\'quote' + './a"double"quote' + './a\\backslash' + './a\ttab' + './a\nnewline' + +'clocale' + Same as 'locale', but '"' is used for both left and right quotation + marks, if not provided by the currently selected locale: + + $ tar tf arch.tar --quoting-style=clocale + "./" + "./a space" + "./a'single'quote" + "./a\"double\"quote" + "./a\\backslash" + "./a\ttab" + "./a\nnewline" + + You can specify which characters should be quoted in addition to +those implied by the current quoting style: + +'--quote-chars=STRING' + Always quote characters from STRING, even if the selected quoting + style would not quote them. + + For example, using 'escape' quoting (compare with the usual escape +listing above): + + $ tar tf arch.tar --quoting-style=escape --quote-chars=' "' + ./ + ./a\ space + ./a'single'quote + ./a\"double\"quote + ./a\\backslash + ./a\ttab + ./a\nnewline + + To disable quoting of such additional characters, use the following +option: + +'--no-quote-chars=STRING' + Remove characters listed in STRING from the list of quoted + characters set by the previous '--quote-chars' option. + + This option is particularly useful if you have added '--quote-chars' +to your 'TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to disable it for +the current invocation. + + Note, that '--no-quote-chars' does _not_ disable those characters +that are quoted by default in the selected quoting style. + + +File: tar.info, Node: transform, Next: after, Prev: quoting styles, Up: Choosing + +6.7 Modifying File and Member Names +=================================== + +'Tar' archives contain detailed information about files stored in them +and full file names are part of that information. When storing a file +to an archive, its file name is recorded in it, along with the actual +file contents. When restoring from an archive, a file is created on +disk with exactly the same name as that stored in the archive. In the +majority of cases this is the desired behavior of a file archiver. +However, there are some cases when it is not. + + First of all, it is often unsafe to extract archive members with +absolute file names or those that begin with a '../'. GNU 'tar' takes +special precautions when extracting such names and provides a special +option for handling them, which is described in *note absolute::. + + Secondly, you may wish to extract file names without some leading +directory components, or with otherwise modified names. In other cases +it is desirable to store files under differing names in the archive. + + GNU 'tar' provides several options for these needs. + +'--strip-components=NUMBER' + Strip given NUMBER of leading components from file names before + extraction. + + For example, suppose you have archived whole '/usr' hierarchy to a +tar archive named 'usr.tar'. Among other files, this archive contains +'usr/include/stdlib.h', which you wish to extract to the current working +directory. To do so, you type: + + $ tar -xf usr.tar --strip=2 usr/include/stdlib.h + + The option '--strip=2' instructs 'tar' to strip the two leading +components ('usr/' and 'include/') off the file name. + + If you add the '--verbose' ('-v') option to the invocation above, you +will note that the verbose listing still contains the full file name, +with the two removed components still in place. This can be +inconvenient, so 'tar' provides a special option for altering this +behavior: + +'--show-transformed-names' + Display file or member names with all requested transformations + applied. + +For example: + + $ tar -xf usr.tar -v --strip=2 usr/include/stdlib.h + usr/include/stdlib.h + $ tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h + stdlib.h + + Notice that in both cases the file 'stdlib.h' is extracted to the +current working directory, '--show-transformed-names' affects only the +way its name is displayed. + + This option is especially useful for verifying whether the invocation +will have the desired effect. Thus, before running + + $ tar -x --strip=N + +it is often advisable to run + + $ tar -t -v --show-transformed --strip=N + +to make sure the command will produce the intended results. + + In case you need to apply more complex modifications to the file +name, GNU 'tar' provides a general-purpose transformation option: + +'--transform=EXPRESSION' +'--xform=EXPRESSION' + Modify file names using supplied EXPRESSION. + +The EXPRESSION is a 'sed'-like replace expression of the form: + + s/REGEXP/REPLACE/[FLAGS] + +where REGEXP is a "regular expression", REPLACE is a replacement for +each file name part that matches REGEXP. Both REGEXP and REPLACE are +described in detail in *note The "s" Command: (sed)The "s" Command. + + Any delimiter can be used in lieu of '/', the only requirement being +that it be used consistently throughout the expression. For example, +the following two expressions are equivalent: + + s/one/two/ + s,one,two, + + Changing delimiters is often useful when the REGEX contains slashes. +For example, it is more convenient to write 's,/,-,' than 's/\//-/'. + + As in 'sed', you can give several replace expressions, separated by a +semicolon. + + Supported FLAGS are: + +'g' + Apply the replacement to _all_ matches to the REGEXP, not just the + first. + +'i' + Use case-insensitive matching. + +'x' + REGEXP is an "extended regular expression" (*note Extended regular + expressions: (sed)Extended regexps.). + +'NUMBER' + Only replace the NUMBERth match of the REGEXP. + + Note: the POSIX standard does not specify what should happen when + you mix the 'g' and NUMBER modifiers. GNU 'tar' follows the GNU + 'sed' implementation in this regard, so the interaction is defined + to be: ignore matches before the NUMBERth, and then match and + replace all matches from the NUMBERth on. + + In addition, several "transformation scope" flags are supported, that +control to what files transformations apply. These are: + +'r' + Apply transformation to regular archive members. + +'R' + Do not apply transformation to regular archive members. + +'s' + Apply transformation to symbolic link targets. + +'S' + Do not apply transformation to symbolic link targets. + +'h' + Apply transformation to hard link targets. + +'H' + Do not apply transformation to hard link targets. + + Default is 'rsh', which means to apply transformations to both +archive members and targets of symbolic and hard links. + + Default scope flags can also be changed using 'flags=' statement in +the transform expression. The flags set this way remain in force until +next 'flags=' statement or end of expression, whichever occurs first. +For example: + + --transform 'flags=S;s|^|/usr/local/|' + + Here are several examples of '--transform' usage: + + 1. Extract 'usr/' hierarchy into 'usr/local/': + + $ tar --transform='s,usr/,usr/local/,' -x -f arch.tar + + 2. Strip two leading directory components (equivalent to + '--strip-components=2'): + + $ tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar + + 3. Convert each file name to lower case: + + $ tar --transform 's/.*/\L&/' -x -f arch.tar + + 4. Prepend '/prefix/' to each file name: + + $ tar --transform 's,^,/prefix/,' -x -f arch.tar + + 5. Archive the '/lib' directory, prepending '/usr/local' to each + archive member: + + $ tar --transform 's,^,/usr/local/,S' -c -f arch.tar /lib + + Notice the use of flags in the last example. The '/lib' directory +often contains many symbolic links to files within it. It may look, for +example, like this: + + $ ls -l + drwxr-xr-x root/root 0 2008-07-08 16:20 /lib/ + -rwxr-xr-x root/root 1250840 2008-05-25 07:44 /lib/libc-2.3.2.so + lrwxrwxrwx root/root 0 2008-06-24 17:12 /lib/libc.so.6 -> libc-2.3.2.so + ... + + Using the expression 's,^,/usr/local/,' would mean adding +'/usr/local' to both regular archive members and to link targets. In +this case, '/lib/libc.so.6' would become: + + /usr/local/lib/libc.so.6 -> /usr/local/libc-2.3.2.so + + This is definitely not desired. To avoid this, the 'S' flag is used, +which excludes symbolic link targets from filename transformations. The +result is: + + $ tar --transform 's,^,/usr/local/,S', -c -v -f arch.tar \ + --show-transformed /lib + drwxr-xr-x root/root 0 2008-07-08 16:20 /usr/local/lib/ + -rwxr-xr-x root/root 1250840 2008-05-25 07:44 /usr/local/lib/libc-2.3.2.so + lrwxrwxrwx root/root 0 2008-06-24 17:12 /usr/local/lib/libc.so.6 \ + -> libc-2.3.2.so + + Unlike '--strip-components', '--transform' can be used in any GNU +'tar' operation mode. For example, the following command adds files to +the archive while replacing the leading 'usr/' component with 'var/': + + $ tar -cf arch.tar --transform='s,^usr/,var/,' / + + To test '--transform' effect we suggest using +'--show-transformed-names' option: + + $ tar -cf arch.tar --transform='s,^usr/,var/,' \ + --verbose --show-transformed-names / + + If both '--strip-components' and '--transform' are used together, +then '--transform' is applied first, and the required number of +components is then stripped from its result. + + You can use as many '--transform' options in a single command line as +you want. The specified expressions will then be applied in order of +their appearance. For example, the following two invocations are +equivalent: + + $ tar -cf arch.tar --transform='s,/usr/var,/var/' \ + --transform='s,/usr/local,/usr/,' + $ tar -cf arch.tar \ + --transform='s,/usr/var,/var/;s,/usr/local,/usr/,' + + +File: tar.info, Node: after, Next: recurse, Prev: transform, Up: Choosing + +6.8 Operating Only on New Files +=============================== + +The '--after-date=DATE' ('--newer=DATE', '-N DATE') option causes 'tar' +to only work on files whose data modification or status change times are +newer than the DATE given. If DATE starts with '/' or '.', it is taken +to be a file name; the data modification time of that file is used as +the date. If you use this option when creating or appending to an +archive, the archive will only include new files. If you use +'--after-date' when extracting an archive, 'tar' will only extract files +newer than the DATE you specify. + + If you only want 'tar' to make the date comparison based on +modification of the file's data (rather than status changes), then use +the '--newer-mtime=DATE' option. + + You may use these options with any operation. Note that these +options differ from the '--update' ('-u') operation in that they allow +you to specify a particular date against which 'tar' can compare when +deciding whether or not to archive the files. + +'--after-date=DATE' +'--newer=DATE' +'-N DATE' + Only store files newer than DATE. + + Acts on files only if their data modification or status change + times are later than DATE. Use in conjunction with any operation. + + If DATE starts with '/' or '.', it is taken to be a file name; the + data modification time of that file is used as the date. + +'--newer-mtime=DATE' + Acts like '--after-date', but only looks at data modification + times. + + These options limit 'tar' to operate only on files which have been +modified after the date specified. A file's status is considered to +have changed if its contents have been modified, or if its owner, +permissions, and so forth, have been changed. (For more information on +how to specify a date, see *note Date input formats::; remember that the +entire date argument must be quoted if it contains any spaces.) + + Gurus would say that '--after-date' tests both the data modification +time ('mtime', the time the contents of the file were last modified) and +the status change time ('ctime', the time the file's status was last +changed: owner, permissions, etc.) fields, while '--newer-mtime' tests +only the 'mtime' field. + + To be precise, '--after-date' checks _both_ 'mtime' and 'ctime' and +processes the file if either one is more recent than DATE, while +'--newer-mtime' only checks 'mtime' and disregards 'ctime'. Neither +does it use 'atime' (the last time the contents of the file were looked +at). + + Date specifiers can have embedded spaces. Because of this, you may +need to quote date arguments to keep the shell from parsing them as +separate arguments. For example, the following command will add to the +archive all the files modified less than two days ago: + + $ tar -cf foo.tar --newer-mtime '2 days ago' + + When any of these options is used with the option '--verbose' (*note +verbose tutorial::) GNU 'tar' will try to convert the specified date +back to its textual representation and compare that with the one given +with the option. If the two dates differ, 'tar' will print a warning +saying what date it will use. This is to help user ensure he is using +the right date. For example: + + $ tar -c -f archive.tar --after-date='10 days ago' . + tar: Option --after-date: Treating date '10 days ago' as 2006-06-11 + 13:19:37.232434 + + *Please Note:* '--after-date' and '--newer-mtime' should not be + used for incremental backups. *Note Incremental Dumps::, for + proper way of creating incremental backups. + + +File: tar.info, Node: recurse, Next: one, Prev: after, Up: Choosing + +6.9 Descending into Directories +=============================== + +Usually, 'tar' will recursively explore all directories (either those +given on the command line or through the '--files-from' option) for the +various files they contain. However, you may not always want 'tar' to +act this way. + + The '--no-recursion' option inhibits 'tar''s recursive descent into +specified directories. If you specify '--no-recursion', you can use the +'find' (*note find: (find)Top.) utility for hunting through levels of +directories to construct a list of file names which you could then pass +to 'tar'. 'find' allows you to be more selective when choosing which +files to archive; see *note files::, for more information on using +'find' with 'tar'. + +'--no-recursion' + Prevents 'tar' from recursively descending directories. + +'--recursion' + Requires 'tar' to recursively descend directories. This is the + default. + + When you use '--no-recursion', GNU 'tar' grabs directory entries +themselves, but does not descend on them recursively. Many people use +'find' for locating files they want to back up, and since 'tar' +_usually_ recursively descends on directories, they have to use the +'-not -type d' test in their 'find' invocation (*note Type: +(find)Type.), as they usually do not want all the files in a directory. +They then use the '--files-from' option to archive the files located via +'find'. + + The problem when restoring files archived in this manner is that the +directories themselves are not in the archive; so the +'--same-permissions' ('--preserve-permissions', '-p') option does not +affect them--while users might really like it to. Specifying +'--no-recursion' is a way to tell 'tar' to grab only the directory +entries given to it, adding no new files on its own. To summarize, if +you use 'find' to create a list of files to be stored in an archive, use +it as follows: + + $ find DIR TESTS | \ + tar -cf ARCHIVE -T - --no-recursion + + The '--no-recursion' option also applies when extracting: it causes +'tar' to extract only the matched directory entries, not the files under +those directories. + + The '--no-recursion' option also affects how globbing patterns are +interpreted (*note controlling pattern-matching::). + + The '--no-recursion' and '--recursion' options apply to later options +and operands, and can be overridden by later occurrences of +'--no-recursion' and '--recursion'. For example: + + $ tar -cf jams.tar --no-recursion grape --recursion grape/concord + +creates an archive with one entry for 'grape', and the recursive +contents of 'grape/concord', but no entries under 'grape' other than +'grape/concord'. + |