1This is tar.info, produced by makeinfo version 6.7 from tar.texi. 2 3This manual is for GNU 'tar' (version 1.34, 4 February 2021), which 4creates and extracts files from archives. 5 6 Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2017, 2021 Free 7Software Foundation, Inc. 8 9 Permission is granted to copy, distribute and/or modify this 10 document under the terms of the GNU Free Documentation License, 11 Version 1.3 or any later version published by the Free Software 12 Foundation; with the Invariant Sections being "GNU General Public 13 License", with the Front-Cover Texts being "A GNU Manual", and with 14 the Back-Cover Texts as in (a) below. A copy of the license is 15 included in the section entitled "GNU Free Documentation License". 16 17 (a) The FSF's Back-Cover Text is: "You have the freedom to copy and 18 modify this GNU manual." 19INFO-DIR-SECTION Archiving 20START-INFO-DIR-ENTRY 21* Tar: (tar). Making tape (or disk) archives. 22END-INFO-DIR-ENTRY 23 24INFO-DIR-SECTION Individual utilities 25START-INFO-DIR-ENTRY 26* tar: (tar)tar invocation. Invoking GNU 'tar'. 27END-INFO-DIR-ENTRY 28 29 30File: tar.info, Node: Top, Next: Introduction, Up: (dir) 31 32GNU tar: an archiver tool 33************************* 34 35This manual is for GNU 'tar' (version 1.34, 4 February 2021), which 36creates and extracts files from archives. 37 38 Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2017, 2021 Free 39Software Foundation, Inc. 40 41 Permission is granted to copy, distribute and/or modify this 42 document under the terms of the GNU Free Documentation License, 43 Version 1.3 or any later version published by the Free Software 44 Foundation; with the Invariant Sections being "GNU General Public 45 License", with the Front-Cover Texts being "A GNU Manual", and with 46 the Back-Cover Texts as in (a) below. A copy of the license is 47 included in the section entitled "GNU Free Documentation License". 48 49 (a) The FSF's Back-Cover Text is: "You have the freedom to copy and 50 modify this GNU manual." 51 52 The first part of this master menu lists the major nodes in this Info 53document. The rest of the menu lists all the lower level nodes. 54 55* Menu: 56 57* Introduction:: 58* Tutorial:: 59* tar invocation:: 60* operations:: 61* Backups:: 62* Choosing:: 63* Date input formats:: 64* Formats:: 65* Media:: 66* Reliability and security:: 67 68Appendices 69 70* Changes:: 71* Recipes:: Frequently used tar recipes 72* Configuring Help Summary:: 73* Fixing Snapshot Files:: 74* Tar Internals:: 75* Genfile:: 76* GNU Free Documentation License:: 77* Index of Command Line Options:: 78* Index:: 79 80 -- The Detailed Node Listing -- 81 82Introduction 83 84* Book Contents:: What this Book Contains 85* Definitions:: Some Definitions 86* What tar Does:: What 'tar' Does 87* Naming tar Archives:: How 'tar' Archives are Named 88* Authors:: GNU 'tar' Authors 89* Reports:: Reporting bugs or suggestions 90 91Tutorial Introduction to 'tar' 92 93* assumptions:: 94* stylistic conventions:: 95* basic tar options:: Basic 'tar' Operations and Options 96* frequent operations:: 97* Two Frequent Options:: 98* create:: How to Create Archives 99* list:: How to List Archives 100* extract:: How to Extract Members from an Archive 101* going further:: 102 103Two Frequently Used Options 104 105* file tutorial:: 106* verbose tutorial:: 107* help tutorial:: 108 109How to Create Archives 110 111* prepare for examples:: 112* Creating the archive:: 113* create verbose:: 114* short create:: 115* create dir:: 116 117How to List Archives 118 119* list dir:: 120 121How to Extract Members from an Archive 122 123* extracting archives:: 124* extracting files:: 125* extract dir:: 126* extracting untrusted archives:: 127* failing commands:: 128 129Invoking GNU 'tar' 130 131* Synopsis:: 132* using tar options:: 133* Styles:: 134* All Options:: 135* help:: 136* defaults:: 137* verbose:: 138* checkpoints:: 139* warnings:: 140* interactive:: 141 142The Three Option Styles 143 144* Long Options:: Long Option Style 145* Short Options:: Short Option Style 146* Old Options:: Old Option Style 147* Mixing:: Mixing Option Styles 148 149All 'tar' Options 150 151* Operation Summary:: 152* Option Summary:: 153* Short Option Summary:: 154* Position-Sensitive Options:: 155 156GNU 'tar' Operations 157 158* Basic tar:: 159* Advanced tar:: 160* create options:: 161* extract options:: 162* backup:: 163* looking ahead:: 164 165Advanced GNU 'tar' Operations 166 167* Operations:: 168* append:: 169* update:: 170* concatenate:: 171* delete:: 172* compare:: 173 174How to Add Files to Existing Archives: '--append' 175 176* appending files:: Appending Files to an Archive 177* multiple:: 178 179Updating an Archive 180 181* how to update:: 182 183Options Used by '--create' 184 185* override:: Overriding File Metadata. 186* Extended File Attributes:: 187* Ignore Failed Read:: 188 189Options Used by '--extract' 190 191* Reading:: Options to Help Read Archives 192* Writing:: Changing How 'tar' Writes Files 193* Scarce:: Coping with Scarce Resources 194 195Options to Help Read Archives 196 197* read full records:: 198* Ignore Zeros:: 199 200Changing How 'tar' Writes Files 201 202* Dealing with Old Files:: 203* Overwrite Old Files:: 204* Keep Old Files:: 205* Keep Newer Files:: 206* Unlink First:: 207* Recursive Unlink:: 208* Data Modification Times:: 209* Setting Access Permissions:: 210* Directory Modification Times and Permissions:: 211* Writing to Standard Output:: 212* Writing to an External Program:: 213* remove files:: 214 215Coping with Scarce Resources 216 217* Starting File:: 218* Same Order:: 219 220Performing Backups and Restoring Files 221 222* Full Dumps:: Using 'tar' to Perform Full Dumps 223* Incremental Dumps:: Using 'tar' to Perform Incremental Dumps 224* Backup Levels:: Levels of Backups 225* Backup Parameters:: Setting Parameters for Backups and Restoration 226* Scripted Backups:: Using the Backup Scripts 227* Scripted Restoration:: Using the Restore Script 228 229Setting Parameters for Backups and Restoration 230 231* General-Purpose Variables:: 232* Magnetic Tape Control:: 233* User Hooks:: 234* backup-specs example:: An Example Text of 'Backup-specs' 235 236Choosing Files and Names for 'tar' 237 238* file:: Choosing the Archive's Name 239* Selecting Archive Members:: 240* files:: Reading Names from a File 241* exclude:: Excluding Some Files 242* wildcards:: Wildcards Patterns and Matching 243* quoting styles:: Ways of Quoting Special Characters in Names 244* transform:: Modifying File and Member Names 245* after:: Operating Only on New Files 246* recurse:: Descending into Directories 247* one:: Crossing File System Boundaries 248 249Reading Names from a File 250 251* nul:: 252 253Excluding Some Files 254 255* problems with exclude:: 256 257Wildcards Patterns and Matching 258 259* controlling pattern-matching:: 260 261Crossing File System Boundaries 262 263* directory:: Changing Directory 264* absolute:: Absolute File Names 265 266Date input formats 267 268* General date syntax:: Common rules. 269* Calendar date items:: 19 Dec 1994. 270* Time of day items:: 9:20pm. 271* Time zone items:: EST, PDT, GMT. 272* Day of week items:: Monday and others. 273* Relative items in date strings:: next tuesday, 2 years ago. 274* Pure numbers in date strings:: 19931219, 1440. 275* Seconds since the Epoch:: @1078100502. 276* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0". 277* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al. 278 279Controlling the Archive Format 280 281* Compression:: Using Less Space through Compression 282* Attributes:: Handling File Attributes 283* Portability:: Making 'tar' Archives More Portable 284* cpio:: Comparison of 'tar' and 'cpio' 285 286Using Less Space through Compression 287 288* gzip:: Creating and Reading Compressed Archives 289* sparse:: Archiving Sparse Files 290 291Creating and Reading Compressed Archives 292 293* lbzip2:: Using lbzip2 with GNU 'tar'. 294 295Making 'tar' Archives More Portable 296 297* Portable Names:: Portable Names 298* dereference:: Symbolic Links 299* hard links:: Hard Links 300* old:: Old V7 Archives 301* ustar:: Ustar Archives 302* gnu:: GNU and old GNU format archives. 303* posix:: POSIX archives 304* Checksumming:: Checksumming Problems 305* Large or Negative Values:: Large files, negative time stamps, etc. 306* Other Tars:: How to Extract GNU-Specific Data Using 307 Other 'tar' Implementations 308 309GNU 'tar' and POSIX 'tar' 310 311* PAX keywords:: Controlling Extended Header Keywords. 312 313How to Extract GNU-Specific Data Using Other 'tar' Implementations 314 315* Split Recovery:: Members Split Between Volumes 316* Sparse Recovery:: Sparse Members 317 318Tapes and Other Archive Media 319 320* Device:: Device selection and switching 321* Remote Tape Server:: 322* Common Problems and Solutions:: 323* Blocking:: Blocking 324* Many:: Many archives on one tape 325* Using Multiple Tapes:: Using Multiple Tapes 326* label:: Including a Label in the Archive 327* verify:: 328* Write Protection:: 329 330Blocking 331 332* Format Variations:: Format Variations 333* Blocking Factor:: The Blocking Factor of an Archive 334 335Many Archives on One Tape 336 337* Tape Positioning:: Tape Positions and Tape Marks 338* mt:: The 'mt' Utility 339 340Using Multiple Tapes 341 342* Multi-Volume Archives:: Archives Longer than One Tape or Disk 343* Tape Files:: Tape Files 344* Tarcat:: Concatenate Volumes into a Single Archive 345 346 347Tar Internals 348 349* Standard:: Basic Tar Format 350* Extensions:: GNU Extensions to the Archive Format 351* Sparse Formats:: Storing Sparse Files 352* Snapshot Files:: 353* Dumpdir:: 354 355Storing Sparse Files 356 357* Old GNU Format:: 358* PAX 0:: PAX Format, Versions 0.0 and 0.1 359* PAX 1:: PAX Format, Version 1.0 360 361Genfile 362 363* Generate Mode:: File Generation Mode. 364* Status Mode:: File Status Mode. 365* Exec Mode:: Synchronous Execution mode. 366 367Copying This Manual 368 369* GNU Free Documentation License:: License for copying this manual 370 371 372 373File: tar.info, Node: Introduction, Next: Tutorial, Prev: Top, Up: Top 374 3751 Introduction 376************** 377 378GNU 'tar' creates and manipulates "archives" which are actually 379collections of many other files; the program provides users with an 380organized and systematic method for controlling a large amount of data. 381The name "tar" originally came from the phrase "Tape ARchive", but 382archives need not (and these days, typically do not) reside on tapes. 383 384* Menu: 385 386* Book Contents:: What this Book Contains 387* Definitions:: Some Definitions 388* What tar Does:: What 'tar' Does 389* Naming tar Archives:: How 'tar' Archives are Named 390* Authors:: GNU 'tar' Authors 391* Reports:: Reporting bugs or suggestions 392 393 394File: tar.info, Node: Book Contents, Next: Definitions, Up: Introduction 395 3961.1 What this Book Contains 397=========================== 398 399The first part of this chapter introduces you to various terms that will 400recur throughout the book. It also tells you who has worked on GNU 401'tar' and its documentation, and where you should send bug reports or 402comments. 403 404 The second chapter is a tutorial (*note Tutorial::) which provides a 405gentle introduction for people who are new to using 'tar'. It is meant 406to be self-contained, not requiring any reading from subsequent chapters 407to make sense. It moves from topic to topic in a logical, progressive 408order, building on information already explained. 409 410 Although the tutorial is paced and structured to allow beginners to 411learn how to use 'tar', it is not intended solely for beginners. The 412tutorial explains how to use the three most frequently used operations 413('create', 'list', and 'extract') as well as two frequently used options 414('file' and 'verbose'). The other chapters do not refer to the tutorial 415frequently; however, if a section discusses something which is a complex 416variant of a basic concept, there may be a cross-reference to that basic 417concept. (The entire book, including the tutorial, assumes that the 418reader understands some basic concepts of using a Unix-type operating 419system; *note Tutorial::.) 420 421 The third chapter presents the remaining five operations, and 422information about using 'tar' options and option syntax. 423 424 The other chapters are meant to be used as a reference. Each chapter 425presents everything that needs to be said about a specific topic. 426 427 One of the chapters (*note Date input formats::) exists in its 428entirety in other GNU manuals, and is mostly self-contained. In 429addition, one section of this manual (*note Standard::) contains a big 430quote which is taken directly from 'tar' sources. 431 432 In general, we give both long and short (abbreviated) option names at 433least once in each section where the relevant option is covered, so that 434novice readers will become familiar with both styles. (A few options 435have no short versions, and the relevant sections will indicate this.) 436 437 438File: tar.info, Node: Definitions, Next: What tar Does, Prev: Book Contents, Up: Introduction 439 4401.2 Some Definitions 441==================== 442 443The 'tar' program is used to create and manipulate 'tar' archives. An 444"archive" is a single file which contains the contents of many files, 445while still identifying the names of the files, their owner(s), and so 446forth. (In addition, archives record access permissions, user and 447group, size in bytes, and data modification time. Some archives also 448record the file names in each archived directory, as well as other file 449and directory information.) You can use 'tar' to "create" a new archive 450in a specified directory. 451 452 The files inside an archive are called "members". Within this 453manual, we use the term "file" to refer only to files accessible in the 454normal ways (by 'ls', 'cat', and so forth), and the term "member" to 455refer only to the members of an archive. Similarly, a "file name" is 456the name of a file, as it resides in the file system, and a "member 457name" is the name of an archive member within the archive. 458 459 The term "extraction" refers to the process of copying an archive 460member (or multiple members) into a file in the file system. Extracting 461all the members of an archive is often called "extracting the archive". 462The term "unpack" can also be used to refer to the extraction of many or 463all the members of an archive. Extracting an archive does not destroy 464the archive's structure, just as creating an archive does not destroy 465the copies of the files that exist outside of the archive. You may also 466"list" the members in a given archive (this is often thought of as 467"printing" them to the standard output, or the command line), or 468"append" members to a pre-existing archive. All of these operations can 469be performed using 'tar'. 470 471 472File: tar.info, Node: What tar Does, Next: Naming tar Archives, Prev: Definitions, Up: Introduction 473 4741.3 What 'tar' Does 475=================== 476 477The 'tar' program provides the ability to create 'tar' archives, as well 478as various other kinds of manipulation. For example, you can use 'tar' 479on previously created archives to extract files, to store additional 480files, or to update or list files which were already stored. 481 482 Initially, 'tar' archives were used to store files conveniently on 483magnetic tape. The name 'tar' comes from this use; it stands for 't'ape 484'ar'chiver. Despite the utility's name, 'tar' can direct its output to 485available devices, files, or other programs (using pipes). 'tar' may 486even access remote devices or files (as archives). 487 488 You can use 'tar' archives in many ways. We want to stress a few of 489them: storage, backup, and transportation. 490 491Storage 492 Often, 'tar' archives are used to store related files for 493 convenient file transfer over a network. For example, the GNU 494 Project distributes its software bundled into 'tar' archives, so 495 that all the files relating to a particular program (or set of 496 related programs) can be transferred as a single unit. 497 498 A magnetic tape can store several files in sequence. However, the 499 tape has no names for these files; it only knows their relative 500 position on the tape. One way to store several files on one tape 501 and retain their names is by creating a 'tar' archive. Even when 502 the basic transfer mechanism can keep track of names, as FTP can, 503 the nuisance of handling multiple files, directories, and multiple 504 links makes 'tar' archives useful. 505 506 Archive files are also used for long-term storage. You can think 507 of this as transportation from the present into the future. (It is 508 a science-fiction idiom that you can move through time as well as 509 in space; the idea here is that 'tar' can be used to move archives 510 in all dimensions, even time!) 511 512Backup 513 Because the archive created by 'tar' is capable of preserving file 514 information and directory structure, 'tar' is commonly used for 515 performing full and incremental backups of disks. A backup puts a 516 collection of files (possibly pertaining to many users and 517 projects) together on a disk or a tape. This guards against 518 accidental destruction of the information in those files. GNU 519 'tar' has special features that allow it to be used to make 520 incremental and full dumps of all the files in a file system. 521 522Transportation 523 You can create an archive on one system, transfer it to another 524 system, and extract the contents there. This allows you to 525 transport a group of files from one system to another. 526 527 528File: tar.info, Node: Naming tar Archives, Next: Authors, Prev: What tar Does, Up: Introduction 529 5301.4 How 'tar' Archives are Named 531================================ 532 533Conventionally, 'tar' archives are given names ending with '.tar'. This 534is not necessary for 'tar' to operate properly, but this manual follows 535that convention in order to accustom readers to it and to make examples 536more clear. 537 538 Often, people refer to 'tar' archives as "'tar' files," and archive 539members as "files" or "entries". For people familiar with the operation 540of 'tar', this causes no difficulty. However, in this manual, we 541consistently refer to "archives" and "archive members" to make learning 542to use 'tar' easier for novice users. 543 544 545File: tar.info, Node: Authors, Next: Reports, Prev: Naming tar Archives, Up: Introduction 546 5471.5 GNU 'tar' Authors 548===================== 549 550GNU 'tar' was originally written by John Gilmore, and modified by many 551people. The GNU enhancements were written by Jay Fenlason, then Joy 552Kendall, and the whole package has been further maintained by Thomas 553Bushnell, n/BSG, François Pinard, Paul Eggert, and finally Sergey 554Poznyakoff with the help of numerous and kind users. 555 556 We wish to stress that 'tar' is a collective work, and owes much to 557all those people who reported problems, offered solutions and other 558insights, or shared their thoughts and suggestions. An impressive, yet 559partial list of those contributors can be found in the 'THANKS' file 560from the GNU 'tar' distribution. 561 562 Jay Fenlason put together a draft of a GNU 'tar' manual, borrowing 563notes from the original man page from John Gilmore. This was withdrawn 564in version 1.11. Thomas Bushnell, n/BSG and Amy Gorin worked on a 565tutorial and manual for GNU 'tar'. François Pinard put version 1.11.8 566of the manual together by taking information from all these sources and 567merging them. Melissa Weisshaus finally edited and redesigned the book 568to create version 1.12. The book for versions from 1.14 up to 1.34 were 569edited by the current maintainer, Sergey Poznyakoff. 570 571 For version 1.12, Daniel Hagerty contributed a great deal of 572technical consulting. In particular, he is the primary author of *note 573Backups::. 574 575 In July, 2003 GNU 'tar' was put on CVS at savannah.gnu.org (see 576<http://savannah.gnu.org/projects/tar>), and active development and 577maintenance work has started again. Currently GNU 'tar' is being 578maintained by Paul Eggert, Sergey Poznyakoff and Jeff Bailey. 579 580 Support for POSIX archives was added by Sergey Poznyakoff. 581 582 583File: tar.info, Node: Reports, Prev: Authors, Up: Introduction 584 5851.6 Reporting bugs or suggestions 586================================= 587 588If you find problems or have suggestions about this program or manual, 589please report them to 'bug-tar@gnu.org'. 590 591 When reporting a bug, please be sure to include as much detail as 592possible, in order to reproduce it. 593 594 595File: tar.info, Node: Tutorial, Next: tar invocation, Prev: Introduction, Up: Top 596 5972 Tutorial Introduction to 'tar' 598******************************** 599 600This chapter guides you through some basic examples of three 'tar' 601operations: '--create', '--list', and '--extract'. If you already know 602how to use some other version of 'tar', then you may not need to read 603this chapter. This chapter omits most complicated details about how 604'tar' works. 605 606* Menu: 607 608* assumptions:: 609* stylistic conventions:: 610* basic tar options:: Basic 'tar' Operations and Options 611* frequent operations:: 612* Two Frequent Options:: 613* create:: How to Create Archives 614* list:: How to List Archives 615* extract:: How to Extract Members from an Archive 616* going further:: 617 618 619File: tar.info, Node: assumptions, Next: stylistic conventions, Up: Tutorial 620 6212.1 Assumptions this Tutorial Makes 622=================================== 623 624This chapter is paced to allow beginners to learn about 'tar' slowly. 625At the same time, we will try to cover all the basic aspects of these 626three operations. In order to accomplish both of these tasks, we have 627made certain assumptions about your knowledge before reading this 628manual, and the hardware you will be using: 629 630 * Before you start to work through this tutorial, you should 631 understand what the terms "archive" and "archive member" mean 632 (*note Definitions::). In addition, you should understand 633 something about how Unix-type operating systems work, and you 634 should know how to use some basic utilities. For example, you 635 should know how to create, list, copy, rename, edit, and delete 636 files and directories; how to change between directories; and how 637 to figure out where you are in the file system. You should have 638 some basic understanding of directory structure and how files are 639 named according to which directory they are in. You should 640 understand concepts such as standard output and standard input, 641 what various definitions of the term 'argument' mean, and the 642 differences between relative and absolute file names. 643 644 * This manual assumes that you are working from your own home 645 directory (unless we state otherwise). In this tutorial, you will 646 create a directory to practice 'tar' commands in. When we show 647 file names, we will assume that those names are relative to your 648 home directory. For example, my home directory is 649 '/home/fsf/melissa'. All of my examples are in a subdirectory of 650 the directory named by that file name; the subdirectory is called 651 'practice'. 652 653 * In general, we show examples of archives which exist on (or can be 654 written to, or worked with from) a directory on a hard disk. In 655 most cases, you could write those archives to, or work with them on 656 any other device, such as a tape drive. However, some of the later 657 examples in the tutorial and next chapter will not work on tape 658 drives. Additionally, working with tapes is much more complicated 659 than working with hard disks. For these reasons, the tutorial does 660 not cover working with tape drives. *Note Media::, for complete 661 information on using 'tar' archives with tape drives. 662 663 664File: tar.info, Node: stylistic conventions, Next: basic tar options, Prev: assumptions, Up: Tutorial 665 6662.2 Stylistic Conventions 667========================= 668 669In the examples, '$' represents a typical shell prompt. It precedes 670lines you should type; to make this more clear, those lines are shown in 671'this font', as opposed to lines which represent the computer's 672response; those lines are shown in 'this font', or sometimes 'like 673this'. 674 675 676File: tar.info, Node: basic tar options, Next: frequent operations, Prev: stylistic conventions, Up: Tutorial 677 6782.3 Basic 'tar' Operations and Options 679====================================== 680 681'tar' can take a wide variety of arguments which specify and define the 682actions it will have on the particular set of files or the archive. The 683main types of arguments to 'tar' fall into one of two classes: 684operations, and options. 685 686 Some arguments fall into a class called "operations"; exactly one of 687these is both allowed and required for any instance of using 'tar'; you 688may _not_ specify more than one. People sometimes speak of "operating 689modes". You are in a particular operating mode when you have specified 690the operation which specifies it; there are eight operations in total, 691and thus there are eight operating modes. 692 693 The other arguments fall into the class known as "options". You are 694not required to specify any options, and you are allowed to specify more 695than one at a time (depending on the way you are using 'tar' at that 696time). Some options are used so frequently, and are so useful for 697helping you type commands more carefully that they are effectively 698"required". We will discuss them in this chapter. 699 700 You can write most of the 'tar' operations and options in any of 701three forms: long (mnemonic) form, short form, and old style. Some of 702the operations and options have no short or "old" forms; however, the 703operations and options which we will cover in this tutorial have 704corresponding abbreviations. We will indicate those abbreviations 705appropriately to get you used to seeing them. Note, that the "old 706style" option forms exist in GNU 'tar' for compatibility with Unix 707'tar'. In this book we present a full discussion of this way of writing 708options and operations (*note Old Options::), and we discuss the other 709two styles of writing options (*Note Long Options::, and *note Short 710Options::). 711 712 In the examples and in the text of this tutorial, we usually use the 713long forms of operations and options; but the "short" forms produce the 714same result and can make typing long 'tar' commands easier. For 715example, instead of typing 716 717 tar --create --verbose --file=afiles.tar apple angst aspic 718 719you can type 720 tar -c -v -f afiles.tar apple angst aspic 721 722or even 723 tar -cvf afiles.tar apple angst aspic 724 725For more information on option syntax, see *note Advanced tar::. In 726discussions in the text, when we name an option by its long form, we 727also give the corresponding short option in parentheses. 728 729 The term, "option", can be confusing at times, since "operations" are 730often lumped in with the actual, _optional_ "options" in certain general 731class statements. For example, we just talked about "short and long 732forms of options and operations". However, experienced 'tar' users 733often refer to these by shorthand terms such as, "short and long 734options". This term assumes that the "operations" are included, also. 735Context will help you determine which definition of "options" to use. 736 737 Similarly, the term "command" can be confusing, as it is often used 738in two different ways. People sometimes refer to 'tar' "commands". A 739'tar' "command" is the entire command line of user input which tells 740'tar' what to do -- including the operation, options, and any arguments 741(file names, pipes, other commands, etc.). However, you will also 742sometimes hear the term "the 'tar' command". When the word "command" is 743used specifically like this, a person is usually referring to the 'tar' 744_operation_, not the whole line. Again, use context to figure out which 745of the meanings the speaker intends. 746 747 748File: tar.info, Node: frequent operations, Next: Two Frequent Options, Prev: basic tar options, Up: Tutorial 749 7502.4 The Three Most Frequently Used Operations 751============================================= 752 753Here are the three most frequently used operations (both short and long 754forms), as well as a brief description of their meanings. The rest of 755this chapter will cover how to use these operations in detail. We will 756present the rest of the operations in the next chapter. 757 758'--create' 759'-c' 760 Create a new 'tar' archive. 761'--list' 762'-t' 763 List the contents of an archive. 764'--extract' 765'-x' 766 Extract one or more members from an archive. 767 768 769File: tar.info, Node: Two Frequent Options, Next: create, Prev: frequent operations, Up: Tutorial 770 7712.5 Two Frequently Used Options 772=============================== 773 774To understand how to run 'tar' in the three operating modes listed 775previously, you also need to understand how to use two of the options to 776'tar': '--file' (which takes an archive file as an argument) and 777'--verbose'. (You are usually not _required_ to specify either of these 778options when you run 'tar', but they can be very useful in making things 779more clear and helping you avoid errors.) 780 781* Menu: 782 783* file tutorial:: 784* verbose tutorial:: 785* help tutorial:: 786 787 788File: tar.info, Node: file tutorial, Next: verbose tutorial, Up: Two Frequent Options 789 790The '--file' Option 791------------------- 792 793'--file=ARCHIVE-NAME' 794'-f ARCHIVE-NAME' 795 Specify the name of an archive file. 796 797 You can specify an argument for the '--file=ARCHIVE-NAME' ('-f 798ARCHIVE-NAME') option whenever you use 'tar'; this option determines the 799name of the archive file that 'tar' will work on. 800 801 If you don't specify this argument, then 'tar' will examine the 802environment variable 'TAPE'. If it is set, its value will be used as 803the archive name. Otherwise, 'tar' will use the default archive, 804determined at compile time. Usually it is standard output or some 805physical tape drive attached to your machine (you can verify what the 806default is by running 'tar --show-defaults', *note defaults::). If 807there is no tape drive attached, or the default is not meaningful, then 808'tar' will print an error message. The error message might look roughly 809like one of the following: 810 811 tar: can't open /dev/rmt8 : No such device or address 812 tar: can't open /dev/rsmt0 : I/O error 813 814To avoid confusion, we recommend that you always specify an archive file 815name by using '--file=ARCHIVE-NAME' ('-f ARCHIVE-NAME') when writing 816your 'tar' commands. For more information on using the 817'--file=ARCHIVE-NAME' ('-f ARCHIVE-NAME') option, see *note file::. 818 819 820File: tar.info, Node: verbose tutorial, Next: help tutorial, Prev: file tutorial, Up: Two Frequent Options 821 822The '--verbose' Option 823---------------------- 824 825'--verbose' 826'-v' 827 Show the files being worked on as 'tar' is running. 828 829 '--verbose' ('-v') shows details about the results of running 'tar'. 830This can be especially useful when the results might not be obvious. 831For example, if you want to see the progress of 'tar' as it writes files 832into the archive, you can use the '--verbose' option. In the beginning, 833you may find it useful to use '--verbose' at all times; when you are 834more accustomed to 'tar', you will likely want to use it at certain 835times but not at others. We will use '--verbose' at times to help make 836something clear, and we will give many examples both using and not using 837'--verbose' to show the differences. 838 839 Each instance of '--verbose' on the command line increases the 840verbosity level by one, so if you need more details on the output, 841specify it twice. 842 843 When reading archives ('--list', '--extract', '--diff'), 'tar' by 844default prints only the names of the members being extracted. Using 845'--verbose' will show a full, 'ls' style member listing. 846 847 In contrast, when writing archives ('--create', '--append', 848'--update'), 'tar' does not print file names by default. So, a single 849'--verbose' option shows the file names being added to the archive, 850while two '--verbose' options enable the full listing. 851 852 For example, to create an archive in verbose mode: 853 854 $ tar -cvf afiles.tar apple angst aspic 855 apple 856 angst 857 aspic 858 859Creating the same archive with the verbosity level 2 could give: 860 861 $ tar -cvvf afiles.tar apple angst aspic 862 -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple 863 -rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst 864 -rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic 865 866This works equally well using short or long forms of options. Using 867long forms, you would simply write out the mnemonic form of the option 868twice, like this: 869 870 $ tar --create --verbose --verbose ... 871 872Note that you must double the hyphens properly each time. 873 874 Later in the tutorial, we will give examples using 875'--verbose --verbose'. 876 877 The full output consists of six fields: 878 879 * File type and permissions in symbolic form. These are displayed in 880 the same format as the first column of 'ls -l' output (*note 881 format=verbose: (fileutils)What information is listed.). 882 883 * Owner name and group separated by a slash character. If these data 884 are not available (for example, when listing a 'v7' format 885 archive), numeric ID values are printed instead. 886 887 * Size of the file, in bytes. 888 889 * File modification date in ISO 8601 format. 890 891 * File modification time. 892 893 * File name. If the name contains any special characters (white 894 space, newlines, etc.) these are displayed in an unambiguous form 895 using so called "quoting style". For the detailed discussion of 896 available styles and on how to use them, see *note quoting 897 styles::. 898 899 Depending on the file type, the name can be followed by some 900 additional information, described in the following table: 901 902 '-> LINK-NAME' 903 The file or archive member is a "symbolic link" and LINK-NAME 904 is the name of file it links to. 905 906 'link to LINK-NAME' 907 The file or archive member is a "hard link" and LINK-NAME is 908 the name of file it links to. 909 910 '--Long Link--' 911 The archive member is an old GNU format long link. You will 912 normally not encounter this. 913 914 '--Long Name--' 915 The archive member is an old GNU format long name. You will 916 normally not encounter this. 917 918 '--Volume Header--' 919 The archive member is a GNU "volume header" (*note Tape 920 Files::). 921 922 '--Continued at byte N--' 923 Encountered only at the beginning of a multi-volume archive 924 (*note Using Multiple Tapes::). This archive member is a 925 continuation from the previous volume. The number N gives the 926 offset where the original file was split. 927 928 'unknown file type C' 929 An archive member of unknown type. C is the type character 930 from the archive header. If you encounter such a message, it 931 means that either your archive contains proprietary member 932 types GNU 'tar' is not able to handle, or the archive is 933 corrupted. 934 935 For example, here is an archive listing containing most of the 936special suffixes explained above: 937 938 V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header-- 939 -rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at byte 32456-- 940 -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple 941 lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple 942 -rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues 943 hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues 944 945 946 947File: tar.info, Node: help tutorial, Prev: verbose tutorial, Up: Two Frequent Options 948 949Getting Help: Using the '--help' Option 950--------------------------------------- 951 952'--help' 953 954 The '--help' option to 'tar' prints out a very brief list of all 955 operations and option available for the current version of 'tar' 956 available on your system. 957 958 959File: tar.info, Node: create, Next: list, Prev: Two Frequent Options, Up: Tutorial 960 9612.6 How to Create Archives 962========================== 963 964One of the basic operations of 'tar' is '--create' ('-c'), which you use 965to create a 'tar' archive. We will explain '--create' first because, in 966order to learn about the other operations, you will find it useful to 967have an archive available to practice on. 968 969 To make this easier, in this section you will first create a 970directory containing three files. Then, we will show you how to create 971an _archive_ (inside the new directory). Both the directory, and the 972archive are specifically for you to practice on. The rest of this 973chapter and the next chapter will show many examples using this 974directory and the files you will create: some of those files may be 975other directories and other archives. 976 977 The three files you will archive in this example are called 'blues', 978'folk', and 'jazz'. The archive is called 'collection.tar'. 979 980 This section will proceed slowly, detailing how to use '--create' in 981'verbose' mode, and showing examples using both short and long forms. 982In the rest of the tutorial, and in the examples in the next chapter, we 983will proceed at a slightly quicker pace. This section moves more slowly 984to allow beginning users to understand how 'tar' works. 985 986* Menu: 987 988* prepare for examples:: 989* Creating the archive:: 990* create verbose:: 991* short create:: 992* create dir:: 993 994 995File: tar.info, Node: prepare for examples, Next: Creating the archive, Up: create 996 9972.6.1 Preparing a Practice Directory for Examples 998------------------------------------------------- 999 1000To follow along with this and future examples, create a new directory 1001called 'practice' containing files called 'blues', 'folk' and 'jazz'. 1002The files can contain any information you like: ideally, they should 1003contain information which relates to their names, and be of different 1004lengths. Our examples assume that 'practice' is a subdirectory of your 1005home directory. 1006 1007 Now 'cd' to the directory named 'practice'; 'practice' is now your 1008"working directory". (_Please note_: Although the full file name of 1009this directory is '/HOMEDIR/practice', in our examples we will refer to 1010this directory as 'practice'; the HOMEDIR is presumed.) 1011 1012 In general, you should check that the files to be archived exist 1013where you think they do (in the working directory) by running 'ls'. 1014Because you just created the directory and the files and have changed to 1015that directory, you probably don't need to do that this time. 1016 1017 It is very important to make sure there isn't already a file in the 1018working directory with the archive name you intend to use (in this case, 1019'collection.tar'), or that you don't care about its contents. Whenever 1020you use 'create', 'tar' will erase the current contents of the file 1021named by '--file=ARCHIVE-NAME' ('-f ARCHIVE-NAME') if it exists. 'tar' 1022will not tell you if you are about to overwrite an archive unless you 1023specify an option which does this (*note backup::, for the information 1024on how to do so). To add files to an existing archive, you need to use 1025a different option, such as '--append' ('-r'); see *note append:: for 1026information on how to do this. 1027 1028 1029File: tar.info, Node: Creating the archive, Next: create verbose, Prev: prepare for examples, Up: create 1030 10312.6.2 Creating the Archive 1032-------------------------- 1033 1034To place the files 'blues', 'folk', and 'jazz' into an archive named 1035'collection.tar', use the following command: 1036 1037 $ tar --create --file=collection.tar blues folk jazz 1038 1039 The order of the arguments is not very important, _when using long 1040option forms_, however you should always remember to use option as the 1041first argument to tar. For example, the following is wrong: 1042 1043 $ tar blues -c folk -f collection.tar jazz 1044 tar: -c: Invalid blocking factor 1045 Try 'tar --help' or 'tar --usage' for more information. 1046 1047 The error message is produced because 'tar' always treats its first 1048argument as an option (or cluster of options), even if it does not start 1049with dash. This is "traditional" or "old option" style, called so 1050because all implementations of 'tar' have used it since the very 1051inception of the tar archiver in 1970s. This option style will be 1052explained later (*note Old Options::), for now just remember to always 1053place option as the first argument. 1054 1055 That being said, you could issue the following command: 1056 1057 $ tar --create folk blues --file=collection.tar jazz 1058 1059However, you can see that this order is harder to understand; this is 1060why we will list the arguments in the order that makes the commands 1061easiest to understand (and we encourage you to do the same when you use 1062'tar', to avoid errors). 1063 1064 Note that the sequence '--file=collection.tar' is considered to be 1065_one_ argument. If you substituted any other string of characters for 1066'collection.tar', then that string would become the name of the archive 1067file you create. 1068 1069 The order of the options becomes more important when you begin to use 1070short forms. With short forms, if you type commands in the wrong order 1071(even if you type them correctly in all other ways), you may end up with 1072results you don't expect. For this reason, it is a good idea to get 1073into the habit of typing options in the order that makes inherent sense. 1074*Note short create::, for more information on this. 1075 1076 In this example, you type the command as shown above: '--create' is 1077the operation which creates the new archive ('collection.tar'), and 1078'--file' is the option which lets you give it the name you chose. The 1079files, 'blues', 'folk', and 'jazz', are now members of the archive, 1080'collection.tar' (they are "file name arguments" to the '--create' 1081operation. *Note Choosing::, for the detailed discussion on these.) 1082Now that they are in the archive, they are called _archive members_, not 1083files. (*note members: Definitions.). 1084 1085 When you create an archive, you _must_ specify which files you want 1086placed in the archive. If you do not specify any archive members, GNU 1087'tar' will complain. 1088 1089 If you now list the contents of the working directory ('ls'), you 1090will find the archive file listed as well as the files you saw 1091previously: 1092 1093 blues folk jazz collection.tar 1094 1095Creating the archive 'collection.tar' did not destroy the copies of the 1096files in the directory. 1097 1098 Keep in mind that if you don't indicate an operation, 'tar' will not 1099run and will prompt you for one. If you don't name any files, 'tar' 1100will complain. You must have write access to the working directory, or 1101else you will not be able to create an archive in that directory. 1102 1103 _Caution_: Do not attempt to use '--create' ('-c') to add files to an 1104existing archive; it will delete the archive and write a new one. Use 1105'--append' ('-r') instead. *Note append::. 1106 1107 1108File: tar.info, Node: create verbose, Next: short create, Prev: Creating the archive, Up: create 1109 11102.6.3 Running '--create' with '--verbose' 1111----------------------------------------- 1112 1113If you include the '--verbose' ('-v') option on the command line, 'tar' 1114will list the files it is acting on as it is working. In verbose mode, 1115the 'create' example above would appear as: 1116 1117 $ tar --create --verbose --file=collection.tar blues folk jazz 1118 blues 1119 folk 1120 jazz 1121 1122 This example is just like the example we showed which did not use 1123'--verbose', except that 'tar' generated the remaining lines. 1124 1125 In the rest of the examples in this chapter, we will frequently use 1126'verbose' mode so we can show actions or 'tar' responses that you would 1127otherwise not see, and which are important for you to understand. 1128 1129 1130File: tar.info, Node: short create, Next: create dir, Prev: create verbose, Up: create 1131 11322.6.4 Short Forms with 'create' 1133------------------------------- 1134 1135As we said before, the '--create' ('-c') operation is one of the most 1136basic uses of 'tar', and you will use it countless times. Eventually, 1137you will probably want to use abbreviated (or "short") forms of options. 1138A full discussion of the three different forms that options can take 1139appears in *note Styles::; for now, here is what the previous example 1140(including the '--verbose' ('-v') option) looks like using short option 1141forms: 1142 1143 $ tar -cvf collection.tar blues folk jazz 1144 blues 1145 folk 1146 jazz 1147 1148As you can see, the system responds the same no matter whether you use 1149long or short option forms. 1150 1151 One difference between using short and long option forms is that, 1152although the exact placement of arguments following options is no more 1153specific when using short forms, it is easier to become confused and 1154make a mistake when using short forms. For example, suppose you 1155attempted the above example in the following way: 1156 1157 $ tar -cfv collection.tar blues folk jazz 1158 1159In this case, 'tar' will make an archive file called 'v', containing the 1160files 'blues', 'folk', and 'jazz', because the 'v' is the closest "file 1161name" to the '-f' option, and is thus taken to be the chosen archive 1162file name. 'tar' will try to add a file called 'collection.tar' to the 1163'v' archive file; if the file 'collection.tar' did not already exist, 1164'tar' will report an error indicating that this file does not exist. If 1165the file 'collection.tar' does already exist (e.g., from a previous 1166command you may have run), then 'tar' will add this file to the archive. 1167Because the '-v' option did not get registered, 'tar' will not run under 1168'verbose' mode, and will not report its progress. 1169 1170 The end result is that you may be quite confused about what happened, 1171and possibly overwrite a file. To illustrate this further, we will show 1172you how an example we showed previously would look using short forms. 1173 1174 This example, 1175 1176 $ tar --create folk blues --file=collection.tar jazz 1177 1178is confusing as it is. It becomes even more so when using short forms: 1179 1180 $ tar -c folk blues -f collection.tar jazz 1181 1182It would be very easy to put the wrong string of characters immediately 1183following the '-f', but doing that could sacrifice valuable data. 1184 1185 For this reason, we recommend that you pay very careful attention to 1186the order of options and placement of file and archive names, especially 1187when using short option forms. Not having the option name written out 1188mnemonically can affect how well you remember which option does what, 1189and therefore where different names have to be placed. 1190 1191 1192File: tar.info, Node: create dir, Prev: short create, Up: create 1193 11942.6.5 Archiving Directories 1195--------------------------- 1196 1197You can archive a directory by specifying its directory name as a file 1198name argument to 'tar'. The files in the directory will be archived 1199relative to the working directory, and the directory will be re-created 1200along with its contents when the archive is extracted. 1201 1202 To archive a directory, first move to its superior directory. If you 1203have followed the previous instructions in this tutorial, you should 1204type: 1205 1206 $ cd .. 1207 $ 1208 1209This will put you into the directory which contains 'practice', i.e., 1210your home directory. Once in the superior directory, you can specify 1211the subdirectory, 'practice', as a file name argument. To store 1212'practice' in the new archive file 'music.tar', type: 1213 1214 $ tar --create --verbose --file=music.tar practice 1215 1216'tar' should output: 1217 1218 practice/ 1219 practice/blues 1220 practice/folk 1221 practice/jazz 1222 practice/collection.tar 1223 1224 Note that the archive thus created is not in the subdirectory 1225'practice', but rather in the current working directory--the directory 1226from which 'tar' was invoked. Before trying to archive a directory from 1227its superior directory, you should make sure you have write access to 1228the superior directory itself, not only the directory you are trying 1229archive with 'tar'. For example, you will probably not be able to store 1230your home directory in an archive by invoking 'tar' from the root 1231directory; *Note absolute::. (Note also that 'collection.tar', the 1232original archive file, has itself been archived. 'tar' will accept any 1233file as a file to be archived, regardless of its content. When 1234'music.tar' is extracted, the archive file 'collection.tar' will be 1235re-written into the file system). 1236 1237 If you give 'tar' a command such as 1238 1239 $ tar --create --file=foo.tar . 1240 1241'tar' will report 'tar: ./foo.tar is the archive; not dumped'. This 1242happens because 'tar' creates the archive 'foo.tar' in the current 1243directory before putting any files into it. Then, when 'tar' attempts 1244to add all the files in the directory '.' to the archive, it notices 1245that the file './foo.tar' is the same as the archive 'foo.tar', and 1246skips it. (It makes no sense to put an archive into itself.) GNU 'tar' 1247will continue in this case, and create the archive normally, except for 1248the exclusion of that one file. (_Please note:_ Other implementations 1249of 'tar' may not be so clever; they will enter an infinite loop when 1250this happens, so you should not depend on this behavior unless you are 1251certain you are running GNU 'tar'. In general, it is wise to always 1252place the archive outside of the directory being dumped.) 1253 1254 1255File: tar.info, Node: list, Next: extract, Prev: create, Up: Tutorial 1256 12572.7 How to List Archives 1258======================== 1259 1260Frequently, you will find yourself wanting to determine exactly what a 1261particular archive contains. You can use the '--list' ('-t') operation 1262to get the member names as they currently appear in the archive, as well 1263as various attributes of the files at the time they were archived. For 1264example, assuming 'practice' is your working directory, you can examine 1265the archive 'collection.tar' that you created in the last section with 1266the command, 1267 1268 $ tar --list --file=collection.tar 1269 1270The output of 'tar' would then be: 1271 1272 blues 1273 folk 1274 jazz 1275 1276Be sure to use a '--file=ARCHIVE-NAME' ('-f ARCHIVE-NAME') option just 1277as with '--create' ('-c') to specify the name of the archive. 1278 1279 You can specify one or more individual member names as arguments when 1280using 'list'. In this case, 'tar' will only list the names of members 1281you identify. For example, 'tar --list --file=collection.tar folk' 1282would only print 'folk': 1283 1284 $ tar --list --file=collection.tar folk 1285 folk 1286 1287 If you use the '--verbose' ('-v') option with '--list', then 'tar' 1288will print out a listing reminiscent of 'ls -l', showing owner, file 1289size, and so forth. This output is described in detail in *note verbose 1290member listing::. 1291 1292 If you had used '--verbose' ('-v') mode, the example above would look 1293like: 1294 1295 $ tar --list --verbose --file=collection.tar folk 1296 -rw-r--r-- myself/user 62 1990-05-23 10:55 folk 1297 1298 It is important to notice that the output of 'tar --list --verbose' 1299does not necessarily match that produced by 'tar --create --verbose' 1300while creating the archive. It is because GNU 'tar', unless told 1301explicitly not to do so, removes some directory prefixes from file names 1302before storing them in the archive (*Note absolute::, for more 1303information). In other words, in verbose mode GNU 'tar' shows "file 1304names" when creating an archive and "member names" when listing it. 1305Consider this example, run from your home directory: 1306 1307 $ tar --create --verbose --file practice.tar ~/practice 1308 tar: Removing leading '/' from member names 1309 /home/myself/practice/ 1310 /home/myself/practice/blues 1311 /home/myself/practice/folk 1312 /home/myself/practice/jazz 1313 /home/myself/practice/collection.tar 1314 $ tar --list --file practice.tar 1315 home/myself/practice/ 1316 home/myself/practice/blues 1317 home/myself/practice/folk 1318 home/myself/practice/jazz 1319 home/myself/practice/collection.tar 1320 1321 This default behavior can sometimes be inconvenient. You can force 1322GNU 'tar' show member names when creating archive by supplying 1323'--show-stored-names' option. 1324 1325'--show-stored-names' 1326 Print member (as opposed to _file_) names when creating the 1327 archive. 1328 1329 With this option, both commands produce the same output: 1330 1331 $ tar --create --verbose --show-stored-names \ 1332 --file practice.tar ~/practice 1333 tar: Removing leading '/' from member names 1334 home/myself/practice/ 1335 home/myself/practice/blues 1336 home/myself/practice/folk 1337 home/myself/practice/jazz 1338 home/myself/practice/collection.tar 1339 $ tar --list --file practice.tar 1340 home/myself/practice/ 1341 home/myself/practice/blues 1342 home/myself/practice/folk 1343 home/myself/practice/jazz 1344 home/myself/practice/collection.tar 1345 1346 Since 'tar' preserves file names, those you wish to list must be 1347specified as they appear in the archive (i.e., relative to the directory 1348from which the archive was created). Continuing the example above: 1349 1350 $ tar --list --file=practice.tar folk 1351 tar: folk: Not found in archive 1352 tar: Exiting with failure status due to previous errors 1353 1354 the error message is produced because there is no member named 1355'folk', only one named 'home/myself/folk'. 1356 1357 If you are not sure of the exact file name, use "globbing patterns", 1358for example: 1359 1360 $ tar --list --file=practice.tar --wildcards '*/folk' 1361 home/myself/practice/folk 1362 1363*Note wildcards::, for a detailed discussion of globbing patterns and 1364related 'tar' command line options. 1365 1366* Menu: 1367 1368* list dir:: 1369 1370 1371File: tar.info, Node: list dir, Up: list 1372 1373Listing the Contents of a Stored Directory 1374------------------------------------------ 1375 1376To get information about the contents of an archived directory, use the 1377directory name as a file name argument in conjunction with '--list' 1378('-t'). To find out file attributes, include the '--verbose' ('-v') 1379option. 1380 1381 For example, to find out about files in the directory 'practice', in 1382the archive file 'music.tar', type: 1383 1384 $ tar --list --verbose --file=music.tar practice 1385 1386 'tar' responds: 1387 1388 drwxrwxrwx myself/user 0 1990-05-31 21:49 practice/ 1389 -rw-r--r-- myself/user 42 1990-05-21 13:29 practice/blues 1390 -rw-r--r-- myself/user 62 1990-05-23 10:55 practice/folk 1391 -rw-r--r-- myself/user 40 1990-05-21 13:30 practice/jazz 1392 -rw-r--r-- myself/user 10240 1990-05-31 21:49 practice/collection.tar 1393 1394 When you use a directory name as a file name argument, 'tar' acts on 1395all the files (including sub-directories) in that directory. 1396 1397 1398File: tar.info, Node: extract, Next: going further, Prev: list, Up: Tutorial 1399 14002.8 How to Extract Members from an Archive 1401========================================== 1402 1403Creating an archive is only half the job--there is no point in storing 1404files in an archive if you can't retrieve them. The act of retrieving 1405members from an archive so they can be used and manipulated as 1406unarchived files again is called "extraction". To extract files from an 1407archive, use the '--extract' ('--get' or '-x') operation. As with 1408'--create', specify the name of the archive with '--file' ('-f') option. 1409Extracting an archive does not modify the archive in any way; you can 1410extract it multiple times if you want or need to. 1411 1412 Using '--extract', you can extract an entire archive, or specific 1413files. The files can be directories containing other files, or not. As 1414with '--create' ('-c') and '--list' ('-t'), you may use the short or the 1415long form of the operation without affecting the performance. 1416 1417* Menu: 1418 1419* extracting archives:: 1420* extracting files:: 1421* extract dir:: 1422* extracting untrusted archives:: 1423* failing commands:: 1424 1425 1426File: tar.info, Node: extracting archives, Next: extracting files, Up: extract 1427 14282.8.1 Extracting an Entire Archive 1429---------------------------------- 1430 1431To extract an entire archive, specify the archive file name only, with 1432no individual file names as arguments. For example, 1433 1434 $ tar -xvf collection.tar 1435 1436produces this: 1437 1438 -rw-r--r-- myself/user 28 1996-10-18 16:31 jazz 1439 -rw-r--r-- myself/user 21 1996-09-23 16:44 blues 1440 -rw-r--r-- myself/user 20 1996-09-23 16:44 folk 1441 1442 1443File: tar.info, Node: extracting files, Next: extract dir, Prev: extracting archives, Up: extract 1444 14452.8.2 Extracting Specific Files 1446------------------------------- 1447 1448To extract specific archive members, give their exact member names as 1449arguments, as printed by '--list' ('-t'). If you had mistakenly deleted 1450one of the files you had placed in the archive 'collection.tar' earlier 1451(say, 'blues'), you can extract it from the archive without changing the 1452archive's structure. Its contents will be identical to the original 1453file 'blues' that you deleted. 1454 1455 First, make sure you are in the 'practice' directory, and list the 1456files in the directory. Now, delete the file, 'blues', and list the 1457files in the directory again. 1458 1459 You can now extract the member 'blues' from the archive file 1460'collection.tar' like this: 1461 1462 $ tar --extract --file=collection.tar blues 1463 1464If you list the files in the directory again, you will see that the file 1465'blues' has been restored, with its original permissions, data 1466modification times, and owner.(1) (These parameters will be identical 1467to those which the file had when you originally placed it in the 1468archive; any changes you may have made before deleting the file from the 1469file system, however, will _not_ have been made to the archive member.) 1470The archive file, 'collection.tar', is the same as it was before you 1471extracted 'blues'. You can confirm this by running 'tar' with '--list' 1472('-t'). 1473 1474 Remember that as with other operations, specifying the exact member 1475name is important (*Note failing commands::, for more examples). 1476 1477 You can extract a file to standard output by combining the above 1478options with the '--to-stdout' ('-O') option (*note Writing to Standard 1479Output::). 1480 1481 If you give the '--verbose' option, then '--extract' will print the 1482names of the archive members as it extracts them. 1483 1484 ---------- Footnotes ---------- 1485 1486 (1) This is only accidentally true, but not in general. Whereas 1487modification times are always restored, in most cases, one has to be 1488root for restoring the owner, and use a special option for restoring 1489permissions. Here, it just happens that the restoring user is also the 1490owner of the archived members, and that the current 'umask' is 1491compatible with original permissions. 1492 1493 1494File: tar.info, Node: extract dir, Next: extracting untrusted archives, Prev: extracting files, Up: extract 1495 14962.8.3 Extracting Files that are Directories 1497------------------------------------------- 1498 1499Extracting directories which are members of an archive is similar to 1500extracting other files. The main difference to be aware of is that if 1501the extracted directory has the same name as any directory already in 1502the working directory, then files in the extracted directory will be 1503placed into the directory of the same name. Likewise, if there are 1504files in the pre-existing directory with the same names as the members 1505which you extract, the files from the extracted archive will replace the 1506files already in the working directory (and possible subdirectories). 1507This will happen regardless of whether or not the files in the working 1508directory were more recent than those extracted (there exist, however, 1509special options that alter this behavior *note Writing::). 1510 1511 However, if a file was stored with a directory name as part of its 1512file name, and that directory does not exist under the working directory 1513when the file is extracted, 'tar' will create the directory. 1514 1515 We can demonstrate how to use '--extract' to extract a directory file 1516with an example. Change to the 'practice' directory if you weren't 1517there, and remove the files 'folk' and 'jazz'. Then, go back to the 1518parent directory and extract the archive 'music.tar'. You may either 1519extract the entire archive, or you may extract only the files you just 1520deleted. To extract the entire archive, don't give any file names as 1521arguments after the archive name 'music.tar'. To extract only the files 1522you deleted, use the following command: 1523 1524 $ tar -xvf music.tar practice/folk practice/jazz 1525 practice/folk 1526 practice/jazz 1527 1528If you were to specify two '--verbose' ('-v') options, 'tar' would have 1529displayed more detail about the extracted files, as shown in the example 1530below: 1531 1532 $ tar -xvvf music.tar practice/folk practice/jazz 1533 -rw-r--r-- me/user 28 1996-10-18 16:31 practice/jazz 1534 -rw-r--r-- me/user 20 1996-09-23 16:44 practice/folk 1535 1536Because you created the directory with 'practice' as part of the file 1537names of each of the files by archiving the 'practice' directory as 1538'practice', you must give 'practice' as part of the file names when you 1539extract those files from the archive. 1540 1541 1542File: tar.info, Node: extracting untrusted archives, Next: failing commands, Prev: extract dir, Up: extract 1543 15442.8.4 Extracting Archives from Untrusted Sources 1545------------------------------------------------ 1546 1547Extracting files from archives can overwrite files that already exist. 1548If you receive an archive from an untrusted source, you should make a 1549new directory and extract into that directory, so that you don't have to 1550worry about the extraction overwriting one of your existing files. For 1551example, if 'untrusted.tar' came from somewhere else on the Internet, 1552and you don't necessarily trust its contents, you can extract it as 1553follows: 1554 1555 $ mkdir newdir 1556 $ cd newdir 1557 $ tar -xvf ../untrusted.tar 1558 1559 It is also a good practice to examine contents of the archive before 1560extracting it, using '--list' ('-t') option, possibly combined with 1561'--verbose' ('-v'). 1562 1563 1564File: tar.info, Node: failing commands, Prev: extracting untrusted archives, Up: extract 1565 15662.8.5 Commands That Will Fail 1567----------------------------- 1568 1569Here are some sample commands you might try which will not work, and why 1570they won't work. 1571 1572 If you try to use this command, 1573 1574 $ tar -xvf music.tar folk jazz 1575 1576you will get the following response: 1577 1578 tar: folk: Not found in archive 1579 tar: jazz: Not found in archive 1580 1581This is because these files were not originally _in_ the parent 1582directory '..', where the archive is located; they were in the 1583'practice' directory, and their file names reflect this: 1584 1585 $ tar -tvf music.tar 1586 practice/blues 1587 practice/folk 1588 practice/jazz 1589 1590Likewise, if you try to use this command, 1591 1592 $ tar -tvf music.tar folk jazz 1593 1594you would get a similar response. Members with those names are not in 1595the archive. You must use the correct member names, or wildcards, in 1596order to extract the files from the archive. 1597 1598 If you have forgotten the correct names of the files in the archive, 1599use 'tar --list --verbose' to list them correctly. 1600 1601 To extract the member named 'practice/folk', you must specify 1602 1603 $ tar --extract --file=music.tar practice/folk 1604 1605Notice also, that as explained above, the 'practice' directory will be 1606created, if it didn't already exist. There are options that allow you 1607to strip away a certain number of leading directory components (*note 1608transform::). For example, 1609 1610 $ tar --extract --file=music.tar --strip-components=1 folk 1611 1612will extract the file 'folk' into the current working directory. 1613 1614 1615File: tar.info, Node: going further, Prev: extract, Up: Tutorial 1616 16172.9 Going Further Ahead in this Manual 1618====================================== 1619 1620 _(This message will disappear, once this node revised.)_ 1621 1622 1623File: tar.info, Node: tar invocation, Next: operations, Prev: Tutorial, Up: Top 1624 16253 Invoking GNU 'tar' 1626******************** 1627 1628This chapter is about how one invokes the GNU 'tar' command, from the 1629command synopsis (*note Synopsis::). There are numerous options, and 1630many styles for writing them. One mandatory option specifies the 1631operation 'tar' should perform (*note Operation Summary::), other 1632options are meant to detail how this operation should be performed 1633(*note Option Summary::). Non-option arguments are not always 1634interpreted the same way, depending on what the operation is. 1635 1636 You will find in this chapter everything about option styles and 1637rules for writing them (*note Styles::). On the other hand, operations 1638and options are fully described elsewhere, in other chapters. Here, you 1639will find only synthetic descriptions for operations and options, 1640together with pointers to other parts of the 'tar' manual. 1641 1642 Some options are so special they are fully described right in this 1643chapter. They have the effect of inhibiting the normal operation of 1644'tar' or else, they globally alter the amount of feedback the user 1645receives about what is going on. These are the '--help' and '--version' 1646(*note help::), '--verbose' (*note verbose::) and '--interactive' 1647options (*note interactive::). 1648 1649* Menu: 1650 1651* Synopsis:: 1652* using tar options:: 1653* Styles:: 1654* All Options:: All 'tar' Options. 1655* help:: Where to Get Help. 1656* defaults:: What are the Default Values. 1657* verbose:: Checking 'tar' progress. 1658* checkpoints:: Checkpoints. 1659* warnings:: Controlling Warning Messages. 1660* interactive:: Asking for Confirmation During Operations. 1661* external:: Running External Commands. 1662 1663 1664File: tar.info, Node: Synopsis, Next: using tar options, Up: tar invocation 1665 16663.1 General Synopsis of 'tar' 1667============================= 1668 1669The GNU 'tar' program is invoked as either one of: 1670 1671 tar OPTION... [NAME]... 1672 tar LETTER... [ARGUMENT]... [OPTION]... [NAME]... 1673 1674 The second form is for when old options are being used. 1675 1676 You can use 'tar' to store files in an archive, to extract them from 1677an archive, and to do other types of archive manipulation. The primary 1678argument to 'tar', which is called the "operation", specifies which 1679action to take. The other arguments to 'tar' are either "options", 1680which change the way 'tar' performs an operation, or file names or 1681archive members, which specify the files or members 'tar' is to act on. 1682 1683 You can actually type in arguments in any order, even if in this 1684manual the options always precede the other arguments, to make examples 1685easier to understand. Further, the option stating the main operation 1686mode (the 'tar' main command) is usually given first. 1687 1688 Each NAME in the synopsis above is interpreted as an archive member 1689name when the main command is one of '--compare' ('--diff', '-d'), 1690'--delete', '--extract' ('--get', '-x'), '--list' ('-t') or '--update' 1691('-u'). When naming archive members, you must give the exact name of 1692the member in the archive, as it is printed by '--list'. For '--append' 1693('-r') and '--create' ('-c'), these NAME arguments specify the names of 1694either files or directory hierarchies to place in the archive. These 1695files or hierarchies should already exist in the file system, prior to 1696the execution of the 'tar' command. 1697 1698 'tar' interprets relative file names as being relative to the working 1699directory. 'tar' will make all file names relative (by removing leading 1700slashes when archiving or restoring files), unless you specify otherwise 1701(using the '--absolute-names' option). *Note absolute::, for more 1702information about '--absolute-names'. 1703 1704 If you give the name of a directory as either a file name or a member 1705name, then 'tar' acts recursively on all the files and directories 1706beneath that directory. For example, the name '/' identifies all the 1707files in the file system to 'tar'. 1708 1709 The distinction between file names and archive member names is 1710especially important when shell globbing is used, and sometimes a source 1711of confusion for newcomers. *Note wildcards::, for more information 1712about globbing. The problem is that shells may only glob using existing 1713files in the file system. Only 'tar' itself may glob on archive 1714members, so when needed, you must ensure that wildcard characters reach 1715'tar' without being interpreted by the shell first. Using a backslash 1716before '*' or '?', or putting the whole argument between quotes, is 1717usually sufficient for this. 1718 1719 Even if NAMEs are often specified on the command line, they can also 1720be read from a text file in the file system, using the 1721'--files-from=FILE-OF-NAMES' ('-T FILE-OF-NAMES') option. 1722 1723 If you don't use any file name arguments, '--append' ('-r'), 1724'--delete' and '--concatenate' ('--catenate', '-A') will do nothing, 1725while '--create' ('-c') will usually yield a diagnostic and inhibit 1726'tar' execution. The other operations of 'tar' ('--list', '--extract', 1727'--compare', and '--update') will act on the entire contents of the 1728archive. 1729 1730 Besides successful exits, GNU 'tar' may fail for many reasons. Some 1731reasons correspond to bad usage, that is, when the 'tar' command line is 1732improperly written. Errors may be encountered later, while processing 1733the archive or the files. Some errors are recoverable, in which case 1734the failure is delayed until 'tar' has completed all its work. Some 1735errors are such that it would be not meaningful, or at least risky, to 1736continue processing: 'tar' then aborts processing immediately. All 1737abnormal exits, whether immediate or delayed, should always be clearly 1738diagnosed on 'stderr', after a line stating the nature of the error. 1739 1740 Possible exit codes of GNU 'tar' are summarized in the following 1741table: 1742 17430 1744 'Successful termination'. 1745 17461 1747 'Some files differ'. If tar was invoked with '--compare' 1748 ('--diff', '-d') command line option, this means that some files in 1749 the archive differ from their disk counterparts (*note compare::). 1750 If tar was given '--create', '--append' or '--update' option, this 1751 exit code means that some files were changed while being archived 1752 and so the resulting archive does not contain the exact copy of the 1753 file set. 1754 17552 1756 'Fatal error'. This means that some fatal, unrecoverable error 1757 occurred. 1758 1759 If 'tar' has invoked a subprocess and that subprocess exited with a 1760nonzero exit code, 'tar' exits with that code as well. This can happen, 1761for example, if 'tar' was given some compression option (*note gzip::) 1762and the external compressor program failed. Another example is 'rmt' 1763failure during backup to the remote device (*note Remote Tape Server::). 1764 1765 1766File: tar.info, Node: using tar options, Next: Styles, Prev: Synopsis, Up: tar invocation 1767 17683.2 Using 'tar' Options 1769======================= 1770 1771GNU 'tar' has a total of eight operating modes which allow you to 1772perform a variety of tasks. You are required to choose one operating 1773mode each time you employ the 'tar' program by specifying one, and only 1774one operation as an argument to the 'tar' command (the corresponding 1775options may be found at *note frequent operations:: and *note 1776Operations::). Depending on circumstances, you may also wish to 1777customize how the chosen operating mode behaves. For example, you may 1778wish to change the way the output looks, or the format of the files that 1779you wish to archive may require you to do something special in order to 1780make the archive look right. 1781 1782 You can customize and control 'tar''s performance by running 'tar' 1783with one or more options (such as '--verbose' ('-v'), which we used in 1784the tutorial). As we said in the tutorial, "options" are arguments to 1785'tar' which are (as their name suggests) optional. Depending on the 1786operating mode, you may specify one or more options. Different options 1787will have different effects, but in general they all change details of 1788the operation, such as archive format, archive name, or level of user 1789interaction. Some options make sense with all operating modes, while 1790others are meaningful only with particular modes. You will likely use 1791some options frequently, while you will only use others infrequently, or 1792not at all. (A full list of options is available in *note All 1793Options::.) 1794 1795 The 'TAR_OPTIONS' environment variable specifies default options to 1796be placed in front of any explicit options. For example, if 1797'TAR_OPTIONS' is '-v --unlink-first', 'tar' behaves as if the two 1798options '-v' and '--unlink-first' had been specified before any explicit 1799options. Option specifications are separated by whitespace. A 1800backslash escapes the next character, so it can be used to specify an 1801option containing whitespace or a backslash. 1802 1803 Note that 'tar' options are case sensitive. For example, the options 1804'-T' and '-t' are different; the first requires an argument for stating 1805the name of a file providing a list of NAMEs, while the second does not 1806require an argument and is another way to write '--list' ('-t'). 1807 1808 In addition to the eight operations, there are many options to 'tar', 1809and three different styles for writing both: long (mnemonic) form, short 1810form, and old style. These styles are discussed below. Both the 1811options and the operations can be written in any of these three styles. 1812 1813 1814File: tar.info, Node: Styles, Next: All Options, Prev: using tar options, Up: tar invocation 1815 18163.3 The Three Option Styles 1817=========================== 1818 1819There are three styles for writing operations and options to the command 1820line invoking 'tar'. The different styles were developed at different 1821times during the history of 'tar'. These styles will be presented 1822below, from the most recent to the oldest. 1823 1824 Some options must take an argument(1). Where you _place_ the 1825arguments generally depends on which style of options you choose. We 1826will detail specific information relevant to each option style in the 1827sections on the different option styles, below. The differences are 1828subtle, yet can often be very important; incorrect option placement can 1829cause you to overwrite a number of important files. We urge you to note 1830these differences, and only use the option style(s) which makes the most 1831sense to you until you feel comfortable with the others. 1832 1833 Some options _may_ take an argument. Such options may have at most 1834long and short forms, they do not have old style equivalent. The rules 1835for specifying an argument for such options are stricter than those for 1836specifying mandatory arguments. Please, pay special attention to them. 1837 1838* Menu: 1839 1840* Long Options:: Long Option Style 1841* Short Options:: Short Option Style 1842* Old Options:: Old Option Style 1843* Mixing:: Mixing Option Styles 1844 1845 ---------- Footnotes ---------- 1846 1847 (1) For example, '--file' ('-f') takes the name of an archive file as 1848an argument. If you do not supply an archive file name, 'tar' will use 1849a default, but this can be confusing; thus, we recommend that you always 1850supply a specific archive file name. 1851 1852 1853File: tar.info, Node: Long Options, Next: Short Options, Up: Styles 1854 18553.3.1 Long Option Style 1856----------------------- 1857 1858Each option has at least one "long" (or "mnemonic") name starting with 1859two dashes in a row, e.g., '--list'. The long names are more clear than 1860their corresponding short or old names. It sometimes happens that a 1861single long option has many different names which are synonymous, such 1862as '--compare' and '--diff'. In addition, long option names can be 1863given unique abbreviations. For example, '--cre' can be used in place 1864of '--create' because there is no other long option which begins with 1865'cre'. (One way to find this out is by trying it and seeing what 1866happens; if a particular abbreviation could represent more than one 1867option, 'tar' will tell you that that abbreviation is ambiguous and 1868you'll know that that abbreviation won't work. You may also choose to 1869run 'tar --help' to see a list of options. Be aware that if you run 1870'tar' with a unique abbreviation for the long name of an option you 1871didn't want to use, you are stuck; 'tar' will perform the command as 1872ordered.) 1873 1874 Long options are meant to be obvious and easy to remember, and their 1875meanings are generally easier to discern than those of their 1876corresponding short options (see below). For example: 1877 1878 $ tar --create --verbose --blocking-factor=20 --file=/dev/rmt0 1879 1880gives a fairly good set of hints about what the command does, even for 1881those not fully acquainted with 'tar'. 1882 1883 Long options which require arguments take those arguments immediately 1884following the option name. There are two ways of specifying a mandatory 1885argument. It can be separated from the option name either by an equal 1886sign, or by any amount of white space characters. For example, the 1887'--file' option (which tells the name of the 'tar' archive) is given a 1888file such as 'archive.tar' as argument by using any of the following 1889notations: '--file=archive.tar' or '--file archive.tar'. 1890 1891 In contrast, optional arguments must always be introduced using an 1892equal sign. For example, the '--backup' option takes an optional 1893argument specifying backup type. It must be used as 1894'--backup=BACKUP-TYPE'. 1895 1896 1897File: tar.info, Node: Short Options, Next: Old Options, Prev: Long Options, Up: Styles 1898 18993.3.2 Short Option Style 1900------------------------ 1901 1902Most options also have a "short option" name. Short options start with 1903a single dash, and are followed by a single character, e.g., '-t' (which 1904is equivalent to '--list'). The forms are absolutely identical in 1905function; they are interchangeable. 1906 1907 The short option names are faster to type than long option names. 1908 1909 Short options which require arguments take their arguments 1910immediately following the option, usually separated by white space. It 1911is also possible to stick the argument right after the short option 1912name, using no intervening space. For example, you might write 1913'-f archive.tar' or '-farchive.tar' instead of using 1914'--file=archive.tar'. Both '--file=ARCHIVE-NAME' and '-f ARCHIVE-NAME' 1915denote the option which indicates a specific archive, here named 1916'archive.tar'. 1917 1918 Short options which take optional arguments take their arguments 1919immediately following the option letter, _without any intervening white 1920space characters_. 1921 1922 Short options' letters may be clumped together, but you are not 1923required to do this (as compared to old options; see below). When short 1924options are clumped as a set, use one (single) dash for them all, e.g., 1925''tar' -cvf'. Only the last option in such a set is allowed to have an 1926argument(1). 1927 1928 When the options are separated, the argument for each option which 1929requires an argument directly follows that option, as is usual for Unix 1930programs. For example: 1931 1932 $ tar -c -v -b 20 -f /dev/rmt0 1933 1934 If you reorder short options' locations, be sure to move any 1935arguments that belong to them. If you do not move the arguments 1936properly, you may end up overwriting files. 1937 1938 ---------- Footnotes ---------- 1939 1940 (1) Clustering many options, the last of which has an argument, is a 1941rather opaque way to write options. Some wonder if GNU 'getopt' should 1942not even be made helpful enough for considering such usages as invalid. 1943 1944 1945File: tar.info, Node: Old Options, Next: Mixing, Prev: Short Options, Up: Styles 1946 19473.3.3 Old Option Style 1948---------------------- 1949 1950As far as we know, all 'tar' programs, GNU and non-GNU, support "old 1951options": that is, if the first argument does not start with '-', it is 1952assumed to specify option letters. GNU 'tar' supports old options not 1953only for historical reasons, but also because many people are used to 1954them. If the first argument does not start with a dash, you are 1955announcing the old option style instead of the short option style; old 1956options are decoded differently. 1957 1958 Like short options, old options are single letters. However, old 1959options must be written together as a single clumped set, without spaces 1960separating them or dashes preceding them. This set of letters must be 1961the first to appear on the command line, after the 'tar' program name 1962and some white space; old options cannot appear anywhere else. The 1963letter of an old option is exactly the same letter as the corresponding 1964short option. For example, the old option 't' is the same as the short 1965option '-t', and consequently, the same as the long option '--list'. So 1966for example, the command 'tar cv' specifies the option '-v' in addition 1967to the operation '-c'. 1968 1969 When options that need arguments are given together with the command, 1970all the associated arguments follow, in the same order as the options. 1971Thus, the example given previously could also be written in the old 1972style as follows: 1973 1974 $ tar cvbf 20 /dev/rmt0 1975 1976Here, '20' is the argument of '-b' and '/dev/rmt0' is the argument of 1977'-f'. 1978 1979 The old style syntax can make it difficult to match option letters 1980with their corresponding arguments, and is often confusing. In the 1981command 'tar cvbf 20 /dev/rmt0', for example, '20' is the argument for 1982'-b', '/dev/rmt0' is the argument for '-f', and '-v' does not have a 1983corresponding argument. Even using short options like in 1984'tar -c -v -b 20 -f /dev/rmt0' is clearer, putting all arguments next to 1985the option they pertain to. 1986 1987 If you want to reorder the letters in the old option argument, be 1988sure to reorder any corresponding argument appropriately. 1989 1990 This old way of writing 'tar' options can surprise even experienced 1991users. For example, the two commands: 1992 1993 tar cfz archive.tar.gz file 1994 tar -cfz archive.tar.gz file 1995 1996are quite different. The first example uses 'archive.tar.gz' as the 1997value for option 'f' and recognizes the option 'z'. The second example, 1998however, uses 'z' as the value for option 'f' -- probably not what was 1999intended. 2000 2001 This second example could be corrected in many ways, among which the 2002following are equivalent: 2003 2004 tar -czf archive.tar.gz file 2005 tar -cf archive.tar.gz -z file 2006 tar cf archive.tar.gz -z file 2007 2008 2009File: tar.info, Node: Mixing, Prev: Old Options, Up: Styles 2010 20113.3.4 Mixing Option Styles 2012-------------------------- 2013 2014All three styles may be intermixed in a single 'tar' command, so long as 2015the rules for each style are fully respected(1). Old style options and 2016either of the modern styles of options may be mixed within a single 2017'tar' command. However, old style options must be introduced as the 2018first arguments only, following the rule for old options (old options 2019must appear directly after the 'tar' command and some white space). 2020Modern options may be given only after all arguments to the old options 2021have been collected. If this rule is not respected, a modern option 2022might be falsely interpreted as the value of the argument to one of the 2023old style options. 2024 2025 For example, all the following commands are wholly equivalent, and 2026illustrate the many combinations and orderings of option styles. 2027 2028 tar --create --file=archive.tar 2029 tar --create -f archive.tar 2030 tar --create -farchive.tar 2031 tar --file=archive.tar --create 2032 tar --file=archive.tar -c 2033 tar -c --file=archive.tar 2034 tar -c -f archive.tar 2035 tar -c -farchive.tar 2036 tar -cf archive.tar 2037 tar -cfarchive.tar 2038 tar -f archive.tar --create 2039 tar -f archive.tar -c 2040 tar -farchive.tar --create 2041 tar -farchive.tar -c 2042 tar c --file=archive.tar 2043 tar c -f archive.tar 2044 tar c -farchive.tar 2045 tar cf archive.tar 2046 tar f archive.tar --create 2047 tar f archive.tar -c 2048 tar fc archive.tar 2049 2050 On the other hand, the following commands are _not_ equivalent to the 2051previous set: 2052 2053 tar -f -c archive.tar 2054 tar -fc archive.tar 2055 tar -fcarchive.tar 2056 tar -farchive.tarc 2057 tar cfarchive.tar 2058 2059These last examples mean something completely different from what the 2060user intended (judging based on the example in the previous set which 2061uses long options, whose intent is therefore very clear). The first 2062four specify that the 'tar' archive would be a file named '-c', 'c', 2063'carchive.tar' or 'archive.tarc', respectively. The first two examples 2064also specify a single non-option, NAME argument having the value 2065'archive.tar'. The last example contains only old style option letters 2066(repeating option 'c' twice), not all of which are meaningful (eg., '.', 2067'h', or 'i'), with no argument value. 2068 2069 ---------- Footnotes ---------- 2070 2071 (1) Before GNU 'tar' version 1.11.6, a bug prevented intermixing old 2072style options with long options in some cases. 2073 2074 2075File: tar.info, Node: All Options, Next: help, Prev: Styles, Up: tar invocation 2076 20773.4 All 'tar' Options 2078===================== 2079 2080The coming manual sections contain an alphabetical listing of all 'tar' 2081operations and options, with brief descriptions and cross-references to 2082more in-depth explanations in the body of the manual. They also contain 2083an alphabetically arranged table of the short option forms with their 2084corresponding long option. You can use this table as a reference for 2085deciphering 'tar' commands in scripts. 2086 2087* Menu: 2088 2089* Operation Summary:: 2090* Option Summary:: 2091* Short Option Summary:: 2092* Position-Sensitive Options:: 2093 2094 2095File: tar.info, Node: Operation Summary, Next: Option Summary, Up: All Options 2096 20973.4.1 Operations 2098---------------- 2099 2100'--append' 2101'-r' 2102 2103 Appends files to the end of the archive. *Note append::. 2104 2105'--catenate' 2106'-A' 2107 2108 Same as '--concatenate'. *Note concatenate::. 2109 2110'--compare' 2111'-d' 2112 2113 Compares archive members with their counterparts in the file 2114 system, and reports differences in file size, mode, owner, 2115 modification date and contents. *Note compare::. 2116 2117'--concatenate' 2118'-A' 2119 2120 Appends other 'tar' archives to the end of the archive. *Note 2121 concatenate::. 2122 2123'--create' 2124'-c' 2125 2126 Creates a new 'tar' archive. *Note create::. 2127 2128'--delete' 2129 2130 Deletes members from the archive. Don't try this on an archive on 2131 a tape! *Note delete::. 2132 2133'--diff' 2134'-d' 2135 2136 Same '--compare'. *Note compare::. 2137 2138'--extract' 2139'-x' 2140 2141 Extracts members from the archive into the file system. *Note 2142 extract::. 2143 2144'--get' 2145'-x' 2146 2147 Same as '--extract'. *Note extract::. 2148 2149'--list' 2150'-t' 2151 2152 Lists the members in an archive. *Note list::. 2153 2154'--update' 2155'-u' 2156 2157 Adds files to the end of the archive, but only if they are newer 2158 than their counterparts already in the archive, or if they do not 2159 already exist in the archive. *Note update::. 2160 2161 2162File: tar.info, Node: Option Summary, Next: Short Option Summary, Prev: Operation Summary, Up: All Options 2163 21643.4.2 'tar' Options 2165------------------- 2166 2167'--absolute-names' 2168'-P' 2169 2170 Normally when creating an archive, 'tar' strips an initial '/' from 2171 member names, and when extracting from an archive 'tar' treats 2172 names specially if they have initial '/' or internal '..'. This 2173 option disables that behavior. *Note absolute::. 2174 2175'--acls' 2176 Enable POSIX ACLs support. *Note acls: Extended File Attributes. 2177 2178'--after-date' 2179 2180 (See '--newer', *note after::) 2181 2182'--anchored' 2183 A pattern must match an initial subsequence of the name's 2184 components. *Note controlling pattern-matching::. 2185 2186'--atime-preserve' 2187'--atime-preserve=replace' 2188'--atime-preserve=system' 2189 2190 Attempt to preserve the access time of files when reading them. 2191 This option currently is effective only on files that you own, 2192 unless you have superuser privileges. 2193 2194 '--atime-preserve=replace' remembers the access time of a file 2195 before reading it, and then restores the access time afterwards. 2196 This may cause problems if other programs are reading the file at 2197 the same time, as the times of their accesses will be lost. On 2198 most platforms restoring the access time also requires 'tar' to 2199 restore the data modification time too, so this option may also 2200 cause problems if other programs are writing the file at the same 2201 time ('tar' attempts to detect this situation, but cannot do so 2202 reliably due to race conditions). Worse, on most platforms 2203 restoring the access time also updates the status change time, 2204 which means that this option is incompatible with incremental 2205 backups. 2206 2207 '--atime-preserve=system' avoids changing time stamps on files, 2208 without interfering with time stamp updates caused by other 2209 programs, so it works better with incremental backups. However, it 2210 requires a special 'O_NOATIME' option from the underlying operating 2211 and file system implementation, and it also requires that searching 2212 directories does not update their access times. As of this writing 2213 (November 2005) this works only with Linux, and only with Linux 2214 kernels 2.6.8 and later. Worse, there is currently no reliable way 2215 to know whether this feature actually works. Sometimes 'tar' knows 2216 that it does not work, and if you use '--atime-preserve=system' 2217 then 'tar' complains and exits right away. But other times 'tar' 2218 might think that the option works when it actually does not. 2219 2220 Currently '--atime-preserve' with no operand defaults to 2221 '--atime-preserve=replace', but this may change in the future as 2222 support for '--atime-preserve=system' improves. 2223 2224 If your operating or file system does not support 2225 '--atime-preserve=system', you might be able to preserve access 2226 times reliably by using the 'mount' command. For example, you can 2227 mount the file system read-only, or access the file system via a 2228 read-only loopback mount, or use the 'noatime' mount option 2229 available on some systems. However, mounting typically requires 2230 superuser privileges and can be a pain to manage. 2231 2232'--auto-compress' 2233'-a' 2234 2235 During a '--create' operation, enables automatic compressed format 2236 recognition based on the archive suffix. The effect of this option 2237 is cancelled by '--no-auto-compress'. *Note gzip::. 2238 2239'--backup=BACKUP-TYPE' 2240 2241 Rather than deleting files from the file system, 'tar' will back 2242 them up using simple or numbered backups, depending upon 2243 BACKUP-TYPE. *Note backup::. 2244 2245'--block-number' 2246'-R' 2247 2248 With this option present, 'tar' prints error messages for read 2249 errors with the block number in the archive file. *Note 2250 block-number::. 2251 2252'--blocking-factor=BLOCKING' 2253'-b BLOCKING' 2254 2255 Sets the blocking factor 'tar' uses to BLOCKING x 512 bytes per 2256 record. *Note Blocking Factor::. 2257 2258'--bzip2' 2259'-j' 2260 2261 This option tells 'tar' to read or write archives through 'bzip2'. 2262 *Note gzip::. 2263 2264'--check-device' 2265 Check device numbers when creating a list of modified files for 2266 incremental archiving. This is the default. *Note device 2267 numbers::, for a detailed description. 2268 2269'--checkpoint[=NUMBER]' 2270 2271 This option directs 'tar' to print periodic checkpoint messages as 2272 it reads through the archive. It is intended for when you want a 2273 visual indication that 'tar' is still running, but don't want to 2274 see '--verbose' output. You can also instruct 'tar' to execute a 2275 list of actions on each checkpoint, see '--checkpoint-action' 2276 below. For a detailed description, see *note checkpoints::. 2277 2278'--checkpoint-action=ACTION' 2279 Instruct 'tar' to execute an action upon hitting a breakpoint. 2280 Here we give only a brief outline. *Note checkpoints::, for a 2281 complete description. 2282 2283 The ACTION argument can be one of the following: 2284 2285 bell 2286 Produce an audible bell on the console. 2287 2288 dot 2289 . 2290 Print a single dot on the standard listing stream. 2291 2292 echo 2293 Display a textual message on the standard error, with the 2294 status and number of the checkpoint. This is the default. 2295 2296 echo=STRING 2297 Display STRING on the standard error. Before output, the 2298 string is subject to meta-character expansion. 2299 2300 exec=COMMAND 2301 Execute the given COMMAND. 2302 2303 sleep=TIME 2304 Wait for TIME seconds. 2305 2306 ttyout=STRING 2307 Output STRING on the current console ('/dev/tty'). 2308 2309 totals 2310 Print statistics (see *note totals::). 2311 2312 wait=SIGNO 2313 Wait for signal SIGNO. 2314 2315 Several '--checkpoint-action' options can be specified. The 2316 supplied actions will be executed in order of their appearance in 2317 the command line. 2318 2319 Using '--checkpoint-action' without '--checkpoint' assumes default 2320 checkpoint frequency of one checkpoint per 10 records. 2321 2322'--check-links' 2323'-l' 2324 If this option was given, 'tar' will check the number of links 2325 dumped for each processed file. If this number does not match the 2326 total number of hard links for the file, a warning message will be 2327 output (1). 2328 2329 *Note hard links::. 2330 2331'--compress' 2332'--uncompress' 2333'-Z' 2334 2335 'tar' will use the 'compress' program when reading or writing the 2336 archive. This allows you to directly act on archives while saving 2337 space. *Note gzip::. 2338 2339'--clamp-mtime' 2340 2341 (See '--mtime'.) 2342 2343'--confirmation' 2344 2345 (See '--interactive'.) *Note interactive::. 2346 2347'--delay-directory-restore' 2348 2349 Delay setting modification times and permissions of extracted 2350 directories until the end of extraction. *Note Directory 2351 Modification Times and Permissions::. 2352 2353'--dereference' 2354'-h' 2355 2356 When reading or writing a file to be archived, 'tar' accesses the 2357 file that a symbolic link points to, rather than the symlink 2358 itself. *Note dereference::. 2359 2360'--directory=DIR' 2361'-C DIR' 2362 2363 When this option is specified, 'tar' will change its current 2364 directory to DIR before performing any operations. When this 2365 option is used during archive creation, it is order sensitive. 2366 *Note directory::. 2367 2368'--exclude=PATTERN' 2369 2370 When performing operations, 'tar' will skip files that match 2371 PATTERN. *Note exclude::. 2372 2373'--exclude-backups' 2374 Exclude backup and lock files. *Note exclude-backups: exclude. 2375 2376'--exclude-from=FILE' 2377'-X FILE' 2378 2379 Similar to '--exclude', except 'tar' will use the list of patterns 2380 in the file FILE. *Note exclude::. 2381 2382'--exclude-caches' 2383 2384 Exclude from dump any directory containing a valid cache directory 2385 tag file, but still dump the directory node and the tag file 2386 itself. 2387 2388 *Note exclude-caches: exclude. 2389 2390'--exclude-caches-under' 2391 2392 Exclude from dump any directory containing a valid cache directory 2393 tag file, but still dump the directory node itself. 2394 2395 *Note exclude::. 2396 2397'--exclude-caches-all' 2398 2399 Exclude from dump any directory containing a valid cache directory 2400 tag file. *Note exclude::. 2401 2402'--exclude-ignore=FILE' 2403 Before dumping a directory, 'tar' checks if it contains FILE. If 2404 so, exclusion patterns are read from this file. The patterns 2405 affect only the directory itself. *Note exclude::. 2406 2407'--exclude-ignore-recursive=FILE' 2408 Before dumping a directory, 'tar' checks if it contains FILE. If 2409 so, exclusion patterns are read from this file. The patterns 2410 affect the directory and all itssubdirectories. *Note exclude::. 2411 2412'--exclude-tag=FILE' 2413 2414 Exclude from dump any directory containing file named FILE, but 2415 dump the directory node and FILE itself. *Note exclude-tag: 2416 exclude. 2417 2418'--exclude-tag-under=FILE' 2419 2420 Exclude from dump the contents of any directory containing file 2421 named FILE, but dump the directory node itself. *Note 2422 exclude-tag-under: exclude. 2423 2424'--exclude-tag-all=FILE' 2425 2426 Exclude from dump any directory containing file named FILE. *Note 2427 exclude-tag-all: exclude. 2428 2429'--exclude-vcs' 2430 2431 Exclude from dump directories and files, that are internal for some 2432 widely used version control systems. 2433 2434 *Note exclude-vcs::. 2435 2436'--exclude-vcs-ignores' 2437 Exclude files that match patterns read from VCS-specific ignore 2438 files. Supported files are: '.cvsignore', '.gitignore', 2439 '.bzrignore', and '.hgignore'. The semantics of each file is the 2440 same as for the corresponding VCS, e.g. patterns read from 2441 '.gitignore' affect the directory and all its subdirectories. 2442 *Note exclude-vcs-ignores::. 2443 2444'--file=ARCHIVE' 2445'-f ARCHIVE' 2446 2447 'tar' will use the file ARCHIVE as the 'tar' archive it performs 2448 operations on, rather than 'tar''s compilation dependent default. 2449 *Note file tutorial::. 2450 2451'--files-from=FILE' 2452'-T FILE' 2453 2454 'tar' will use the contents of FILE as a list of archive members or 2455 files to operate on, in addition to those specified on the 2456 command-line. *Note files::. 2457 2458'--force-local' 2459 2460 Forces 'tar' to interpret the file name given to '--file' as a 2461 local file, even if it looks like a remote tape drive name. *Note 2462 local and remote archives::. 2463 2464'--format=FORMAT' 2465'-H FORMAT' 2466 2467 Selects output archive format. FORMAT may be one of the following: 2468 2469 'v7' 2470 Creates an archive that is compatible with Unix V7 'tar'. 2471 2472 'oldgnu' 2473 Creates an archive that is compatible with GNU 'tar' version 2474 1.12 or earlier. 2475 2476 'gnu' 2477 Creates archive in GNU tar 1.13 format. Basically it is the 2478 same as 'oldgnu' with the only difference in the way it 2479 handles long numeric fields. 2480 2481 'ustar' 2482 Creates a POSIX.1-1988 compatible archive. 2483 2484 'posix' 2485 Creates a POSIX.1-2001 archive. 2486 2487 *Note Formats::, for a detailed discussion of these formats. 2488 2489'--full-time' 2490 This option instructs 'tar' to print file times to their full 2491 resolution. Usually this means 1-second resolution, but that 2492 depends on the underlying file system. The '--full-time' option 2493 takes effect only when detailed output (verbosity level 2 or 2494 higher) has been requested using the '--verbose' option, e.g., when 2495 listing or extracting archives: 2496 2497 $ tar -t -v --full-time -f archive.tar 2498 2499 or, when creating an archive: 2500 2501 $ tar -c -vv --full-time -f archive.tar . 2502 2503 Notice, thar when creating the archive you need to specify 2504 '--verbose' twice to get a detailed output (*note verbose 2505 tutorial::). 2506 2507'--group=GROUP' 2508 2509 Files added to the 'tar' archive will have a group ID of GROUP, 2510 rather than the group from the source file. GROUP can specify a 2511 symbolic name, or a numeric ID, or both as NAME:ID. *Note 2512 override::. 2513 2514 Also see the '--group-map' option and comments for the 2515 '--owner=USER' option. 2516 2517'--group-map=FILE' 2518 2519 Read owner group translation map from FILE. This option allows to 2520 translate only certain group names and/or UIDs. *Note override::, 2521 for a detailed description. When used together with '--group' 2522 option, the latter affects only those files whose owner group is 2523 not listed in the FILE. 2524 2525 This option does not affect extraction from archives. 2526 2527'--gzip' 2528'--gunzip' 2529'--ungzip' 2530'-z' 2531 2532 This option tells 'tar' to read or write archives through 'gzip', 2533 allowing 'tar' to directly operate on several kinds of compressed 2534 archives transparently. *Note gzip::. 2535 2536'--hard-dereference' 2537 When creating an archive, dereference hard links and store the 2538 files they refer to, instead of creating usual hard link members. 2539 2540 *Note hard links::. 2541 2542'--help' 2543'-?' 2544 2545 'tar' will print out a short message summarizing the operations and 2546 options to 'tar' and exit. *Note help::. 2547 2548'--hole-detection=METHOD' 2549 Use METHOD to detect holes in sparse files. This option implies 2550 '--sparse'. Valid methods are 'seek' and 'raw'. Default is 'seek' 2551 with fallback to 'raw' when not applicable. *Note sparse::. 2552 2553'--ignore-case' 2554 Ignore case when matching member or file names with patterns. 2555 *Note controlling pattern-matching::. 2556 2557'--ignore-command-error' 2558 Ignore exit codes of subprocesses. *Note Writing to an External 2559 Program::. 2560 2561'--ignore-failed-read' 2562 2563 Do not exit unsuccessfully merely because an unreadable file was 2564 encountered. *Note Ignore Failed Read::. 2565 2566'--ignore-zeros' 2567'-i' 2568 2569 With this option, 'tar' will ignore zeroed blocks in the archive, 2570 which normally signals EOF. *Note Reading::. 2571 2572'--incremental' 2573'-G' 2574 2575 Informs 'tar' that it is working with an old GNU-format incremental 2576 backup archive. It is intended primarily for backwards 2577 compatibility only. *Note Incremental Dumps::, for a detailed 2578 discussion of incremental archives. 2579 2580'--index-file=FILE' 2581 2582 Send verbose output to FILE instead of to standard output. 2583 2584'--info-script=COMMAND' 2585'--new-volume-script=COMMAND' 2586'-F COMMAND' 2587 2588 When 'tar' is performing multi-tape backups, COMMAND is run at the 2589 end of each tape. If it exits with nonzero status, 'tar' fails 2590 immediately. *Note info-script::, for a detailed discussion of 2591 this feature. 2592 2593'--interactive' 2594'--confirmation' 2595'-w' 2596 2597 Specifies that 'tar' should ask the user for confirmation before 2598 performing potentially destructive options, such as overwriting 2599 files. *Note interactive::. 2600 2601'--keep-directory-symlink' 2602 2603 This option changes the behavior of tar when it encounters a 2604 symlink with the same name as the directory that it is about to 2605 extract. By default, in this case tar would first remove the 2606 symlink and then proceed extracting the directory. 2607 2608 The '--keep-directory-symlink' option disables this behavior and 2609 instructs tar to follow symlinks to directories when extracting 2610 from the archive. 2611 2612 It is mainly intended to provide compatibility with the Slackware 2613 installation scripts. 2614 2615'--keep-newer-files' 2616 2617 Do not replace existing files that are newer than their archive 2618 copies when extracting files from an archive. 2619 2620'--keep-old-files' 2621'-k' 2622 2623 Do not overwrite existing files when extracting files from an 2624 archive. Return error if such files exist. See also *note 2625 --skip-old-files::. 2626 2627 *Note Keep Old Files::. 2628 2629'--label=NAME' 2630'-V NAME' 2631 2632 When creating an archive, instructs 'tar' to write NAME as a name 2633 record in the archive. When extracting or listing archives, 'tar' 2634 will only operate on archives that have a label matching the 2635 pattern specified in NAME. *Note Tape Files::. 2636 2637'--level=N' 2638 Force incremental backup of level N. As of GNU 'tar' version 1.34, 2639 the option '--level=0' truncates the snapshot file, thereby forcing 2640 the level 0 dump. Other values of N are effectively ignored. 2641 *Note --level=0::, for details and examples. 2642 2643 The use of this option is valid only in conjunction with the 2644 '--listed-incremental' option. *Note Incremental Dumps::, for a 2645 detailed description. 2646 2647'--listed-incremental=SNAPSHOT-FILE' 2648'-g SNAPSHOT-FILE' 2649 2650 During a '--create' operation, specifies that the archive that 2651 'tar' creates is a new GNU-format incremental backup, using 2652 SNAPSHOT-FILE to determine which files to backup. With other 2653 operations, informs 'tar' that the archive is in incremental 2654 format. *Note Incremental Dumps::. 2655 2656'--lzip' 2657 2658 This option tells 'tar' to read or write archives through 'lzip'. 2659 *Note gzip::. 2660 2661'--lzma' 2662 2663 This option tells 'tar' to read or write archives through 'lzma'. 2664 *Note gzip::. 2665 2666'--lzop' 2667 2668 This option tells 'tar' to read or write archives through 'lzop'. 2669 *Note gzip::. 2670 2671'--mode=PERMISSIONS' 2672 2673 When adding files to an archive, 'tar' will use PERMISSIONS for the 2674 archive members, rather than the permissions from the files. 2675 PERMISSIONS can be specified either as an octal number or as 2676 symbolic permissions, like with 'chmod'. *Note override::. 2677 2678'--mtime=DATE' 2679 2680 When adding files to an archive, 'tar' will use DATE as the 2681 modification time of members when creating archives, instead of 2682 their actual modification times. The value of DATE can be either a 2683 textual date representation (*note Date input formats::) or a name 2684 of the existing file, starting with '/' or '.'. In the latter 2685 case, the modification time of that file is used. *Note 2686 override::. 2687 2688 When '--clamp-mtime' is also specified, files with modification 2689 times earlier than DATE will retain their actual modification 2690 times, and DATE will only be used for files whose modification 2691 times are later than DATE. 2692 2693'--multi-volume' 2694'-M' 2695 2696 Informs 'tar' that it should create or otherwise operate on a 2697 multi-volume 'tar' archive. *Note Using Multiple Tapes::. 2698 2699'--new-volume-script' 2700 2701 (see '--info-script') 2702 2703'--newer=DATE' 2704'--after-date=DATE' 2705'-N' 2706 2707 When creating an archive, 'tar' will only add files that have 2708 changed since DATE. If DATE begins with '/' or '.', it is taken to 2709 be the name of a file whose data modification time specifies the 2710 date. *Note after::. 2711 2712'--newer-mtime=DATE' 2713 2714 Like '--newer', but add only files whose contents have changed (as 2715 opposed to just '--newer', which will also back up files for which 2716 any status information has changed). *Note after::. 2717 2718'--no-acls' 2719 Disable the POSIX ACLs support. *Note acls: Extended File 2720 Attributes. 2721 2722'--no-anchored' 2723 An exclude pattern can match any subsequence of the name's 2724 components. *Note controlling pattern-matching::. 2725 2726'--no-auto-compress' 2727 2728 Disables automatic compressed format recognition based on the 2729 archive suffix. *Note --auto-compress::. *Note gzip::. 2730 2731'--no-check-device' 2732 Do not check device numbers when creating a list of modified files 2733 for incremental archiving. *Note device numbers::, for a detailed 2734 description. 2735 2736'--no-delay-directory-restore' 2737 2738 Modification times and permissions of extracted directories are set 2739 when all files from this directory have been extracted. This is 2740 the default. *Note Directory Modification Times and Permissions::. 2741 2742'--no-ignore-case' 2743 Use case-sensitive matching. *Note controlling pattern-matching::. 2744 2745'--no-ignore-command-error' 2746 Print warnings about subprocesses that terminated with a nonzero 2747 exit code. *Note Writing to an External Program::. 2748 2749'--no-null' 2750 2751 If the '--null' option was given previously, this option cancels 2752 its effect, so that any following '--files-from' options will 2753 expect their file lists to be newline-terminated. 2754 2755'--no-overwrite-dir' 2756 2757 Preserve metadata of existing directories when extracting files 2758 from an archive. *Note Overwrite Old Files::. 2759 2760'--no-quote-chars=STRING' 2761 Remove characters listed in STRING from the list of quoted 2762 characters set by the previous '--quote-chars' option (*note 2763 quoting styles::). 2764 2765'--no-recursion' 2766 2767 With this option, 'tar' will not recurse into directories. *Note 2768 recurse::. 2769 2770'--no-same-owner' 2771'-o' 2772 2773 When extracting an archive, do not attempt to preserve the owner 2774 specified in the 'tar' archive. This the default behavior for 2775 ordinary users. 2776 2777'--no-same-permissions' 2778 2779 When extracting an archive, subtract the user's umask from files 2780 from the permissions specified in the archive. This is the default 2781 behavior for ordinary users. 2782 2783'--no-seek' 2784 2785 The archive media does not support seeks to arbitrary locations. 2786 Usually 'tar' determines automatically whether the archive can be 2787 seeked or not. Use this option to disable this mechanism. 2788 2789'--no-selinux' 2790 Disable SELinux context support. *Note SELinux: Extended File 2791 Attributes. 2792 2793'--no-unquote' 2794 Treat all input file or member names literally, do not interpret 2795 escape sequences. *Note input name quoting::. 2796 2797'--no-verbatim-files-from' 2798 2799 Instructs GNU 'tar' to treat each line read from a file list as if 2800 it were supplied in the command line. I.e., leading and trailing 2801 whitespace is removed and, if the result begins with a dash, it is 2802 treated as a GNU 'tar' command line option. 2803 2804 This is default behavior. This option is provided as a way to 2805 restore it after '--verbatim-files-from' option. 2806 2807 It is implied by the '--no-null' option. 2808 2809 *Note no-verbatim-files-from::. 2810 2811'--no-wildcards' 2812 Do not use wildcards. *Note controlling pattern-matching::. 2813 2814'--no-wildcards-match-slash' 2815 Wildcards do not match '/'. *Note controlling pattern-matching::. 2816 2817'--no-xattrs' 2818 Disable extended attributes support. *Note xattrs: Extended File 2819 Attributes. 2820 2821'--null' 2822 2823 When 'tar' is using the '--files-from' option, this option 2824 instructs 'tar' to expect file names terminated with NUL, and to 2825 process file names verbatim. 2826 2827 This means that 'tar' correctly works with file names that contain 2828 newlines or begin with a dash. 2829 2830 *Note nul::. 2831 2832 See also *note verbatim-files-from::. 2833 2834'--numeric-owner' 2835 2836 This option will notify 'tar' that it should use numeric user and 2837 group IDs when creating a 'tar' file, rather than names. *Note 2838 Attributes::. 2839 2840'-o' 2841 The function of this option depends on the action 'tar' is 2842 performing. When extracting files, '-o' is a synonym for 2843 '--no-same-owner', i.e., it prevents 'tar' from restoring ownership 2844 of files being extracted. 2845 2846 When creating an archive, it is a synonym for '--old-archive'. 2847 This behavior is for compatibility with previous versions of GNU 2848 'tar', and will be removed in future releases. 2849 2850 *Note Changes::, for more information. 2851 2852'--occurrence[=NUMBER]' 2853 2854 This option can be used in conjunction with one of the subcommands 2855 '--delete', '--diff', '--extract' or '--list' when a list of files 2856 is given either on the command line or via '-T' option. 2857 2858 This option instructs 'tar' to process only the NUMBERth occurrence 2859 of each named file. NUMBER defaults to 1, so 2860 2861 tar -x -f archive.tar --occurrence filename 2862 2863 will extract the first occurrence of the member 'filename' from 2864 'archive.tar' and will terminate without scanning to the end of the 2865 archive. 2866 2867'--old-archive' 2868 Synonym for '--format=v7'. 2869 2870'--one-file-system' 2871 Used when creating an archive. Prevents 'tar' from recursing into 2872 directories that are on different file systems from the current 2873 directory. 2874 2875'--one-top-level[=DIR]' 2876 Tells 'tar' to create a new directory beneath the extraction 2877 directory (or the one passed to '-C') and use it to guard against 2878 tarbombs. In the absence of DIR argument, the name of the new 2879 directory will be equal to the base name of the archive (file name 2880 minus the archive suffix, if recognized). Any member names that do 2881 not begin with that directory name (after transformations from 2882 '--transform' and '--strip-components') will be prefixed with it. 2883 Recognized file name suffixes are '.tar', and any compression 2884 suffixes recognizable by *Note --auto-compress::. 2885 2886'--overwrite' 2887 2888 Overwrite existing files and directory metadata when extracting 2889 files from an archive. *Note Overwrite Old Files::. 2890 2891'--overwrite-dir' 2892 2893 Overwrite the metadata of existing directories when extracting 2894 files from an archive. *Note Overwrite Old Files::. 2895 2896'--owner=USER' 2897 2898 Specifies that 'tar' should use USER as the owner of members when 2899 creating archives, instead of the user associated with the source 2900 file. USER can specify a symbolic name, or a numeric ID, or both 2901 as NAME:ID. *Note override::. 2902 2903 This option does not affect extraction from archives. See also 2904 '--owner-map', below. 2905 2906'--owner-map=FILE' 2907 2908 Read owner translation map from FILE. This option allows to 2909 translate only certain owner names or UIDs. *Note override::, for 2910 a detailed description. When used together with '--owner' option, 2911 the latter affects only those files whose owner is not listed in 2912 the FILE. 2913 2914 This option does not affect extraction from archives. 2915 2916'--pax-option=KEYWORD-LIST' 2917 This option enables creation of the archive in POSIX.1-2001 format 2918 (*note posix::) and modifies the way 'tar' handles the extended 2919 header keywords. KEYWORD-LIST is a comma-separated list of keyword 2920 options. *Note PAX keywords::, for a detailed discussion. 2921 2922'--portability' 2923'--old-archive' 2924 Synonym for '--format=v7'. 2925 2926'--posix' 2927 Same as '--format=posix'. 2928 2929'--preserve-order' 2930 2931 (See '--same-order'; *note Reading::.) 2932 2933'--preserve-permissions' 2934'--same-permissions' 2935'-p' 2936 2937 When 'tar' is extracting an archive, it normally subtracts the 2938 users' umask from the permissions specified in the archive and uses 2939 that number as the permissions to create the destination file. 2940 Specifying this option instructs 'tar' that it should use the 2941 permissions directly from the archive. *Note Setting Access 2942 Permissions::. 2943 2944'--quote-chars=STRING' 2945 Always quote characters from STRING, even if the selected quoting 2946 style would not quote them (*note quoting styles::). 2947 2948'--quoting-style=STYLE' 2949 Set quoting style to use when printing member and file names (*note 2950 quoting styles::). Valid STYLE values are: 'literal', 'shell', 2951 'shell-always', 'c', 'escape', 'locale', and 'clocale'. Default 2952 quoting style is 'escape', unless overridden while configuring the 2953 package. 2954 2955'--read-full-records' 2956'-B' 2957 2958 Specifies that 'tar' should reblock its input, for reading from 2959 pipes on systems with buggy implementations. *Note Reading::. 2960 2961'--record-size=SIZE[SUF]' 2962 2963 Instructs 'tar' to use SIZE bytes per record when accessing the 2964 archive. The argument can be suffixed with a "size suffix", e.g. 2965 '--record-size=10K' for 10 Kilobytes. *Note Table 9.1: 2966 size-suffixes, for a list of valid suffixes. *Note Blocking 2967 Factor::, for a detailed description of this option. 2968 2969'--recursion' 2970 2971 With this option, 'tar' recurses into directories (default). *Note 2972 recurse::. 2973 2974'--recursive-unlink' 2975 2976 Remove existing directory hierarchies before extracting directories 2977 of the same name from the archive. *Note Recursive Unlink::. 2978 2979'--remove-files' 2980 2981 Directs 'tar' to remove the source file from the file system after 2982 appending it to an archive. *Note remove files::. 2983 2984'--restrict' 2985 2986 Disable use of some potentially harmful 'tar' options. Currently 2987 this option disables shell invocation from multi-volume menu (*note 2988 Using Multiple Tapes::). 2989 2990'--rmt-command=CMD' 2991 2992 Notifies 'tar' that it should use CMD instead of the default 2993 '/usr/libexec/rmt' (*note Remote Tape Server::). 2994 2995'--rsh-command=CMD' 2996 2997 Notifies 'tar' that is should use CMD to communicate with remote 2998 devices. *Note Device::. 2999 3000'--same-order' 3001'--preserve-order' 3002'-s' 3003 3004 This option is an optimization for 'tar' when running on machines 3005 with small amounts of memory. It informs 'tar' that the list of 3006 file arguments has already been sorted to match the order of files 3007 in the archive. *Note Reading::. 3008 3009'--same-owner' 3010 3011 When extracting an archive, 'tar' will attempt to preserve the 3012 owner specified in the 'tar' archive with this option present. 3013 This is the default behavior for the superuser; this option has an 3014 effect only for ordinary users. *Note Attributes::. 3015 3016'--same-permissions' 3017 3018 (See '--preserve-permissions'; *note Setting Access Permissions::.) 3019 3020'--seek' 3021'-n' 3022 3023 Assume that the archive media supports seeks to arbitrary 3024 locations. Usually 'tar' determines automatically whether the 3025 archive can be seeked or not. This option is intended for use in 3026 cases when such recognition fails. It takes effect only if the 3027 archive is open for reading (e.g. with '--list' or '--extract' 3028 options). 3029 3030'--selinux' 3031 Enable the SELinux context support. *Note selinux: Extended File 3032 Attributes. 3033 3034'--show-defaults' 3035 3036 Displays the default options used by 'tar' and exits successfully. 3037 This option is intended for use in shell scripts. Here is an 3038 example of what you can see using this option: 3039 3040 $ tar --show-defaults 3041 --format=gnu -f- -b20 --quoting-style=escape 3042 --rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh 3043 3044 Notice, that this option outputs only one line. The example output 3045 above has been split to fit page boundaries. *Note defaults::. 3046 3047'--show-omitted-dirs' 3048 3049 Instructs 'tar' to mention the directories it is skipping when 3050 operating on a 'tar' archive. *Note show-omitted-dirs::. 3051 3052'--show-snapshot-field-ranges' 3053 3054 Displays the range of values allowed by this version of 'tar' for 3055 each field in the snapshot file, then exits successfully. *Note 3056 Snapshot Files::. 3057 3058'--show-transformed-names' 3059'--show-stored-names' 3060 3061 Display file or member names after applying any transformations 3062 (*note transform::). In particular, when used in conjunction with 3063 one of the archive creation operations it instructs 'tar' to list 3064 the member names stored in the archive, as opposed to the actual 3065 file names. *Note listing member and file names::. 3066 3067'--skip-old-files' 3068 3069 Do not overwrite existing files when extracting files from an 3070 archive. *Note Keep Old Files::. 3071 3072 This option differs from '--keep-old-files' in that it does not 3073 treat such files as an error, instead it just silently avoids 3074 overwriting them. 3075 3076 The '--warning=existing-file' option can be used together with this 3077 option to produce warning messages about existing old files (*note 3078 warnings::). 3079 3080'--sort=ORDER' 3081 Specify the directory sorting order when reading directories. 3082 ORDER may be one of the following: 3083 3084 'none' 3085 No directory sorting is performed. This is the default. 3086 3087 'name' 3088 Sort the directory entries on name. The operating system may 3089 deliver directory entries in a more or less random order, and 3090 sorting them makes archive creation reproducible. 3091 3092 'inode' 3093 Sort the directory entries on inode number. Sorting 3094 directories on inode number may reduce the amount of disk seek 3095 operations when creating an archive for some file systems. 3096 3097'--sparse' 3098'-S' 3099 3100 Invokes a GNU extension when adding files to an archive that 3101 handles sparse files efficiently. *Note sparse::. 3102 3103'--sparse-version=VERSION' 3104 3105 Specifies the "format version" to use when archiving sparse files. 3106 Implies '--sparse'. *Note sparse::. For the description of the 3107 supported sparse formats, *Note Sparse Formats::. 3108 3109'--starting-file=NAME' 3110'-K NAME' 3111 3112 This option affects extraction only; 'tar' will skip extracting 3113 files in the archive until it finds one that matches NAME. *Note 3114 Scarce::. 3115 3116'--strip-components=NUMBER' 3117 Strip given NUMBER of leading components from file names before 3118 extraction. For example, if archive 'archive.tar' contained 3119 '/some/file/name', then running 3120 3121 tar --extract --file archive.tar --strip-components=2 3122 3123 would extract this file to file 'name'. 3124 3125 *Note transform::. 3126 3127'--suffix=SUFFIX' 3128 3129 Alters the suffix 'tar' uses when backing up files from the default 3130 '~'. *Note backup::. 3131 3132'--tape-length=NUM[SUF]' 3133'-L NUM[SUF]' 3134 3135 Specifies the length of tapes that 'tar' is writing as being 3136 NUM x 1024 bytes long. If optional SUF is given, it specifies a 3137 multiplicative factor to be used instead of 1024. For example, 3138 '-L2M' means 2 megabytes. *Note Table 9.1: size-suffixes, for a 3139 list of allowed suffixes. *Note Using Multiple Tapes::, for a 3140 detailed discussion of this option. 3141 3142'--test-label' 3143 3144 Reads the volume label. If an argument is specified, test whether 3145 it matches the volume label. *Note --test-label option::. 3146 3147'--to-command=COMMAND' 3148 3149 During extraction 'tar' will pipe extracted files to the standard 3150 input of COMMAND. *Note Writing to an External Program::. 3151 3152'--to-stdout' 3153'-O' 3154 3155 During extraction, 'tar' will extract files to stdout rather than 3156 to the file system. *Note Writing to Standard Output::. 3157 3158'--totals[=SIGNO]' 3159 3160 Displays the total number of bytes transferred when processing an 3161 archive. If an argument is given, these data are displayed on 3162 request, when signal SIGNO is delivered to 'tar'. *Note totals::. 3163 3164'--touch' 3165'-m' 3166 3167 Sets the data modification time of extracted files to the 3168 extraction time, rather than the data modification time stored in 3169 the archive. *Note Data Modification Times::. 3170 3171'--transform=SED-EXPR' 3172'--xform=SED-EXPR' 3173 Transform file or member names using 'sed' replacement expression 3174 SED-EXPR. For example, 3175 3176 $ tar cf archive.tar --transform 's,^\./,usr/,' . 3177 3178 will add to 'archive' files from the current working directory, 3179 replacing initial './' prefix with 'usr/'. For the detailed 3180 discussion, *Note transform::. 3181 3182 To see transformed member names in verbose listings, use 3183 '--show-transformed-names' option (*note show-transformed-names::). 3184 3185'--uncompress' 3186 3187 (See '--compress', *note gzip::) 3188 3189'--ungzip' 3190 3191 (See '--gzip', *note gzip::) 3192 3193'--unlink-first' 3194'-U' 3195 3196 Directs 'tar' to remove the corresponding file from the file system 3197 before extracting it from the archive. *Note Unlink First::. 3198 3199'--unquote' 3200 Enable unquoting input file or member names (default). *Note input 3201 name quoting::. 3202 3203'--use-compress-program=PROG' 3204'-I=PROG' 3205 3206 Instructs 'tar' to access the archive through PROG, which is 3207 presumed to be a compression program of some sort. *Note gzip::. 3208 3209'--utc' 3210 3211 Display file modification dates in UTC. This option implies 3212 '--verbose'. 3213 3214'--verbatim-files-from' 3215 3216 Instructs GNU 'tar' to treat each line read from a file list as a 3217 file name, even if it starts with a dash. 3218 3219 File lists are supplied with the '--files-from' ('-T') option. By 3220 default, each line read from a file list is first trimmed off the 3221 leading and trailing whitespace and, if the result begins with a 3222 dash, it is treated as a GNU 'tar' command line option. 3223 3224 Use the '--verbatim-files-from' option to disable this special 3225 handling. This facilitates the use of 'tar' with file lists 3226 created by 'file' command. 3227 3228 This option affects all '--files-from' options that occur after it 3229 in the command line. Its effect is reverted by the 3230 '--no-verbatim-files-from' option. 3231 3232 This option is implied by the '--null' option. 3233 3234 *Note verbatim-files-from::. 3235 3236'--verbose' 3237'-v' 3238 3239 Specifies that 'tar' should be more verbose about the operations it 3240 is performing. This option can be specified multiple times for 3241 some operations to increase the amount of information displayed. 3242 *Note verbose::. 3243 3244'--verify' 3245'-W' 3246 3247 Verifies that the archive was correctly written when creating an 3248 archive. *Note verify::. 3249 3250'--version' 3251 3252 Print information about the program's name, version, origin and 3253 legal status, all on standard output, and then exit successfully. 3254 *Note help::. 3255 3256'--volno-file=FILE' 3257 3258 Used in conjunction with '--multi-volume'. 'tar' will keep track 3259 of which volume of a multi-volume archive it is working in FILE. 3260 *Note volno-file::. 3261 3262'--warning=KEYWORD' 3263 3264 Enable or disable warning messages identified by KEYWORD. The 3265 messages are suppressed if KEYWORD is prefixed with 'no-'. *Note 3266 warnings::. 3267 3268'--wildcards' 3269 Use wildcards when matching member names with patterns. *Note 3270 controlling pattern-matching::. 3271 3272'--wildcards-match-slash' 3273 Wildcards match '/'. *Note controlling pattern-matching::. 3274 3275'--xattrs' 3276 Enable extended attributes support. *Note xattrs: Extended File 3277 Attributes. 3278 3279'--xattrs-exclude=PATTERN' 3280 Specify exclude pattern for xattr keys. *Note xattrs-exclude: 3281 Extended File Attributes. 3282 3283'--xattrs-include=PATTERN.' 3284 Specify include pattern for xattr keys. PATTERN is a globbing 3285 pattern, e.g. '--xattrs-include='user.*'' to include only 3286 attributes from the user namespace. *Note xattrs-include: Extended 3287 File Attributes. 3288 3289'--xz' 3290'-J' 3291 Use 'xz' for compressing or decompressing the archives. *Note 3292 gzip::. 3293 3294'--zstd' 3295 Use 'zstd' for compressing or decompressing the archives. *Note 3296 gzip::. 3297 3298 ---------- Footnotes ---------- 3299 3300 (1) Earlier versions of GNU 'tar' understood '-l' as a synonym for 3301'--one-file-system'. The current semantics, which complies to UNIX98, 3302was introduced with version 1.15.91. *Note Changes::, for more 3303information. 3304 3305 3306File: tar.info, Node: Short Option Summary, Next: Position-Sensitive Options, Prev: Option Summary, Up: All Options 3307 33083.4.3 Short Options Cross Reference 3309----------------------------------- 3310 3311Here is an alphabetized list of all of the short option forms, matching 3312them with the equivalent long option. 3313 3314Short Option Reference 3315 3316-------------------------------------------------------------------------- 3317-A *note --concatenate::. 3318 3319-B *note --read-full-records::. 3320 3321-C *note --directory::. 3322 3323-F *note --info-script::. 3324 3325-G *note --incremental::. 3326 3327-J *note --xz::. 3328 3329-K *note --starting-file::. 3330 3331-L *note --tape-length::. 3332 3333-M *note --multi-volume::. 3334 3335-N *note --newer::. 3336 3337-O *note --to-stdout::. 3338 3339-P *note --absolute-names::. 3340 3341-R *note --block-number::. 3342 3343-S *note --sparse::. 3344 3345-T *note --files-from::. 3346 3347-U *note --unlink-first::. 3348 3349-V *note --label::. 3350 3351-W *note --verify::. 3352 3353-X *note --exclude-from::. 3354 3355-Z *note --compress::. 3356 3357-b *note --blocking-factor::. 3358 3359-c *note --create::. 3360 3361-d *note --compare::. 3362 3363-f *note --file::. 3364 3365-g *note --listed-incremental::. 3366 3367-h *note --dereference::. 3368 3369-i *note --ignore-zeros::. 3370 3371-j *note --bzip2::. 3372 3373-k *note --keep-old-files::. 3374 3375-l *note --check-links::. 3376 3377-m *note --touch::. 3378 3379-o When extracting, same as *note --no-same-owner::. When 3380 creating, - *note --old-archive::. 3381 3382 The latter usage is deprecated. It is retained for 3383 compatibility with the earlier versions of GNU 'tar'. 3384 In future releases '-o' will be equivalent to 3385 '--no-same-owner' only. 3386 3387-p *note --preserve-permissions::. 3388 3389-r *note --append::. 3390 3391-s *note --same-order::. 3392 3393-t *note --list::. 3394 3395-u *note --update::. 3396 3397-v *note --verbose::. 3398 3399-w *note --interactive::. 3400 3401-x *note --extract::. 3402 3403-z *note --gzip::. 3404 3405 3406 3407File: tar.info, Node: Position-Sensitive Options, Prev: Short Option Summary, Up: All Options 3408 34093.4.4 Position-Sensitive Options 3410-------------------------------- 3411 3412Some GNU 'tar' options can be used multiple times in the same invocation 3413and affect all arguments that appear after them. These are options that 3414control how file names are selected and what kind of pattern matching is 3415used. 3416 3417 The most obvious example is the '-C' option. It instructs 'tar' to 3418change to the directory given as its argument prior to processing the 3419rest of command line (*note directory::). Thus, in the following 3420command: 3421 3422 tar -c -f a.tar -C /etc passwd -C /var log spool 3423 3424the file 'passwd' will be searched in the directory '/etc', and files 3425'log' and 'spool' - in '/var'. 3426 3427 These options can also be used in a file list supplied with the 3428'--files-from' ('-T') option (*note files::). In that case they affect 3429all files (patterns) appearing in that file after them and remain in 3430effect for any arguments processed after that file. For example, if the 3431file 'list.txt' contained: 3432 3433 README 3434 -C src 3435 main.c 3436 3437and 'tar' were invoked as follows: 3438 3439 tar -c -f a.tar -T list.txt Makefile 3440 3441then the file 'README' would be looked up in the current working 3442directory, and files 'main.c' and 'Makefile' would be looked up in the 3443directory 'src'. 3444 3445 Many options can be prefixed with '--no-' to cancel the effect of the 3446original option. 3447 3448 For example, the '--recursion' option controls whether to recurse in 3449the subdirectories. It's counterpart '--no-recursion' disables this. 3450Consider the command below. It will store in the archive the directory 3451'/usr' with all files and directories that are located in it as well as 3452any files and directories in '/var', without recursing into them(1): 3453 3454 tar -cf a.tar --recursion /usr --no-recursion /var/* 3455 3456 During archive creation, GNU 'tar' keeps track of positional options 3457used and arguments affected by them. If it finds out that any such 3458options are used in an obviously erroneous way, the fact is reported and 3459exit code is set to 2. E.g.: 3460 3461 $ tar -cf a.tar . --exclude '*.o' 3462 tar: The following options were used after any non-optional 3463 arguments in archive create or update mode. These options are 3464 positional and affect only arguments that follow them. Please, 3465 rearrange them properly. 3466 tar: --exclude '*.o' has no effect 3467 tar: Exiting with failure status due to previous errors 3468 3469 The following table summarizes all position-sensitive options. 3470 3471'--directory=DIR' 3472'-C DIR' 3473 *Note directory::. 3474 3475'--null' 3476'--no-null' 3477 *Note nul::. 3478 3479'--unquote' 3480'--no-unquote' 3481 *Note input name quoting::. 3482 3483'--verbatim-files-from' 3484'--no-verbatim-files-from' 3485 *Note verbatim-files-from::. 3486 3487'--recursion' 3488'--no-recursion' 3489 *Note recurse::. 3490 3491'--anchored' 3492'--no-anchored' 3493 *Note anchored patterns::. 3494 3495'--ignore-case' 3496'--no-ignore-case' 3497 *Note case-insensitive matches::. 3498 3499'--wildcards' 3500'--no-wildcards' 3501 *Note controlling pattern-matching::. 3502 3503'--wildcards-match-slash' 3504'--no-wildcards-match-slash' 3505 *Note controlling pattern-matching::. 3506 3507'--exclude' 3508 *Note exclude::. 3509 3510'--exclude-from' 3511'-X' 3512'--exclude-caches' 3513'--exclude-caches-under' 3514'--exclude-caches-all' 3515'--exclude-tag' 3516'--exclude-ignore' 3517'--exclude-ignore-recursive' 3518'--exclude-tag-under' 3519'--exclude-tag-all' 3520'--exclude-vcs' 3521'--exclude-vcs-ignores' 3522'--exclude-backups' 3523 *Note exclude::. 3524 3525 ---------- Footnotes ---------- 3526 3527 (1) The '--recursion' option is the default and is used here for 3528clarity. The same example can be written as: 3529 3530 tar -cf a.tar /usr --no-recursion /var/* 3531 3532 3533File: tar.info, Node: help, Next: defaults, Prev: All Options, Up: tar invocation 3534 35353.5 GNU 'tar' documentation 3536=========================== 3537 3538Being careful, the first thing is really checking that you are using GNU 3539'tar', indeed. The '--version' option causes 'tar' to print information 3540about its name, version, origin and legal status, all on standard 3541output, and then exit successfully. For example, 'tar --version' might 3542print: 3543 3544 tar (GNU tar) 1.34 3545 Copyright (C) 2013-2020 Free Software Foundation, Inc. 3546 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>. 3547 This is free software: you are free to change and redistribute it. 3548 There is NO WARRANTY, to the extent permitted by law. 3549 3550 Written by John Gilmore and Jay Fenlason. 3551 3552The first occurrence of 'tar' in the result above is the program name in 3553the package (for example, 'rmt' is another program), while the second 3554occurrence of 'tar' is the name of the package itself, containing 3555possibly many programs. The package is currently named 'tar', after the 3556name of the main program it contains(1). 3557 3558 Another thing you might want to do is checking the spelling or 3559meaning of some particular 'tar' option, without resorting to this 3560manual, for once you have carefully read it. GNU 'tar' has a short help 3561feature, triggerable through the '--help' option. By using this option, 3562'tar' will print a usage message listing all available options on 3563standard output, then exit successfully, without doing anything else and 3564ignoring all other options. Even if this is only a brief summary, it 3565may be several screens long. So, if you are not using some kind of 3566scrollable window, you might prefer to use something like: 3567 3568 $ tar --help | less 3569 3570presuming, here, that you like using 'less' for a pager. Other popular 3571pagers are 'more' and 'pg'. If you know about some KEYWORD which 3572interests you and do not want to read all the '--help' output, another 3573common idiom is doing: 3574 3575 tar --help | grep KEYWORD 3576 3577for getting only the pertinent lines. Notice, however, that some 'tar' 3578options have long description lines and the above command will list only 3579the first of them. 3580 3581 The exact look of the option summary displayed by 'tar --help' is 3582configurable. *Note Configuring Help Summary::, for a detailed 3583description. 3584 3585 If you only wish to check the spelling of an option, running 'tar 3586--usage' may be a better choice. This will display a terse list of 3587'tar' options without accompanying explanations. 3588 3589 The short help output is quite succinct, and you might have to get 3590back to the full documentation for precise points. If you are reading 3591this paragraph, you already have the 'tar' manual in some form. This 3592manual is available in a variety of forms from 3593<http://www.gnu.org/software/tar/manual>. It may be printed out of the 3594GNU 'tar' distribution, provided you have TeX already installed 3595somewhere, and a laser printer around. Just configure the distribution, 3596execute the command 'make dvi', then print 'doc/tar.dvi' the usual way 3597(contact your local guru to know how). If GNU 'tar' has been 3598conveniently installed at your place, this manual is also available in 3599interactive, hypertextual form as an Info file. Just call 'info tar' 3600or, if you do not have the 'info' program handy, use the Info reader 3601provided within GNU Emacs, calling 'tar' from the main Info menu. 3602 3603 There is currently no 'man' page for GNU 'tar'. If you observe such 3604a 'man' page on the system you are running, either it does not belong to 3605GNU 'tar', or it has not been produced by GNU. Some package maintainers 3606convert 'tar --help' output to a man page, using 'help2man'. In any 3607case, please bear in mind that the authoritative source of information 3608about GNU 'tar' is this Texinfo documentation. 3609 3610 ---------- Footnotes ---------- 3611 3612 (1) There are plans to merge the 'cpio' and 'tar' packages into a 3613single one which would be called 'paxutils'. So, who knows if, one of 3614this days, the '--version' would not output 'tar (GNU paxutils) 3.2'. 3615 3616 3617File: tar.info, Node: defaults, Next: verbose, Prev: help, Up: tar invocation 3618 36193.6 Obtaining GNU 'tar' default values 3620====================================== 3621 3622GNU 'tar' has some predefined defaults that are used when you do not 3623explicitly specify another values. To obtain a list of such defaults, 3624use '--show-defaults' option. This will output the values in the form 3625of 'tar' command line options: 3626 3627 $ tar --show-defaults 3628 --format=gnu -f- -b20 --quoting-style=escape 3629 --rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh 3630 3631Notice, that this option outputs only one line. The example output 3632above has been split to fit page boundaries. 3633 3634The above output shows that this version of GNU 'tar' defaults to using 3635'gnu' archive format (*note Formats::), it uses standard output as the 3636archive, if no '--file' option has been given (*note file tutorial::), 3637the default blocking factor is 20 (*note Blocking Factor::). It also 3638shows the default locations where 'tar' will look for 'rmt' and 'rsh' 3639binaries. 3640 3641 3642File: tar.info, Node: verbose, Next: checkpoints, Prev: defaults, Up: tar invocation 3643 36443.7 Checking 'tar' progress 3645=========================== 3646 3647Typically, 'tar' performs most operations without reporting any 3648information to the user except error messages. When using 'tar' with 3649many options, particularly ones with complicated or difficult-to-predict 3650behavior, it is possible to make serious mistakes. 'tar' provides 3651several options that make observing 'tar' easier. These options cause 3652'tar' to print information as it progresses in its job, and you might 3653want to use them just for being more careful about what is going on, or 3654merely for entertaining yourself. If you have encountered a problem 3655when operating on an archive, however, you may need more information 3656than just an error message in order to solve the problem. The following 3657options can be helpful diagnostic tools. 3658 3659 Normally, the '--list' ('-t') command to list an archive prints just 3660the file names (one per line) and the other commands are silent. When 3661used with most operations, the '--verbose' ('-v') option causes 'tar' to 3662print the name of each file or archive member as it is processed. This 3663and the other options which make 'tar' print status information can be 3664useful in monitoring 'tar'. 3665 3666 With '--create' or '--extract', '--verbose' used once just prints the 3667names of the files or members as they are processed. Using it twice 3668causes 'tar' to print a longer listing (*Note verbose member listing::, 3669for the description) for each member. Since '--list' already prints the 3670names of the members, '--verbose' used once with '--list' causes 'tar' 3671to print an 'ls -l' type listing of the files in the archive. The 3672following examples both extract members with long list output: 3673 3674 $ tar --extract --file=archive.tar --verbose --verbose 3675 $ tar xvvf archive.tar 3676 3677 Verbose output appears on the standard output except when an archive 3678is being written to the standard output, as with 'tar --create --file=- 3679--verbose' ('tar cvf -', or even 'tar cv'--if the installer let standard 3680output be the default archive). In that case 'tar' writes verbose 3681output to the standard error stream. 3682 3683 If '--index-file=FILE' is specified, 'tar' sends verbose output to 3684FILE rather than to standard output or standard error. 3685 3686 The '--totals' option causes 'tar' to print on the standard error the 3687total amount of bytes transferred when processing an archive. When 3688creating or appending to an archive, this option prints the number of 3689bytes written to the archive and the average speed at which they have 3690been written, e.g.: 3691 3692 $ tar -c -f archive.tar --totals /home 3693 Total bytes written: 7924664320 (7.4GiB, 85MiB/s) 3694 3695 When reading an archive, this option displays the number of bytes 3696read: 3697 3698 $ tar -x -f archive.tar --totals 3699 Total bytes read: 7924664320 (7.4GiB, 95MiB/s) 3700 3701 Finally, when deleting from an archive, the '--totals' option 3702displays both numbers plus number of bytes removed from the archive: 3703 3704 $ tar --delete -f foo.tar --totals --wildcards '*~' 3705 Total bytes read: 9543680 (9.2MiB, 201MiB/s) 3706 Total bytes written: 3829760 (3.7MiB, 81MiB/s) 3707 Total bytes deleted: 1474048 3708 3709 You can also obtain this information on request. When '--totals' is 3710used with an argument, this argument is interpreted as a symbolic name 3711of a signal, upon delivery of which the statistics is to be printed: 3712 3713'--totals=SIGNO' 3714 Print statistics upon delivery of signal SIGNO. Valid arguments 3715 are: 'SIGHUP', 'SIGQUIT', 'SIGINT', 'SIGUSR1' and 'SIGUSR2'. 3716 Shortened names without 'SIG' prefix are also accepted. 3717 3718 Both forms of '--totals' option can be used simultaneously. Thus, 3719'tar -x --totals --totals=USR1' instructs 'tar' to extract all members 3720from its default archive and print statistics after finishing the 3721extraction, as well as when receiving signal 'SIGUSR1'. 3722 3723 The '--checkpoint' option prints an occasional message as 'tar' reads 3724or writes the archive. It is designed for those who don't need the more 3725detailed (and voluminous) output of '--block-number' ('-R'), but do want 3726visual confirmation that 'tar' is actually making forward progress. By 3727default it prints a message each 10 records read or written. This can 3728be changed by giving it a numeric argument after an equal sign: 3729 3730 $ tar -c --checkpoint=1000 /var 3731 tar: Write checkpoint 1000 3732 tar: Write checkpoint 2000 3733 tar: Write checkpoint 3000 3734 3735 This example shows the default checkpoint message used by 'tar'. If 3736you place a dot immediately after the equal sign, it will print a '.' at 3737each checkpoint(1). For example: 3738 3739 $ tar -c --checkpoint=.1000 /var 3740 ... 3741 3742 The '--checkpoint' option provides a flexible mechanism for executing 3743arbitrary actions upon hitting checkpoints, see the next section (*note 3744checkpoints::), for more information on it. 3745 3746 The '--show-omitted-dirs' option, when reading an archive--with 3747'--list' or '--extract', for example--causes a message to be printed for 3748each directory in the archive which is skipped. This happens regardless 3749of the reason for skipping: the directory might not have been named on 3750the command line (implicitly or explicitly), it might be excluded by the 3751use of the '--exclude=PATTERN' option, or some other reason. 3752 3753 If '--block-number' ('-R') is used, 'tar' prints, along with every 3754message it would normally produce, the block number within the archive 3755where the message was triggered. Also, supplementary messages are 3756triggered when reading blocks full of NULs, or when hitting end of file 3757on the archive. As of now, if the archive is properly terminated with a 3758NUL block, the reading of the file may stop before end of file is met, 3759so the position of end of file will not usually show when 3760'--block-number' ('-R') is used. Note that GNU 'tar' drains the archive 3761before exiting when reading the archive from a pipe. 3762 3763 This option is especially useful when reading damaged archives, since 3764it helps pinpoint the damaged sections. It can also be used with 3765'--list' ('-t') when listing a file-system backup tape, allowing you to 3766choose among several backup tapes when retrieving a file later, in favor 3767of the tape where the file appears earliest (closest to the front of the 3768tape). *Note backup::. 3769 3770 ---------- Footnotes ---------- 3771 3772 (1) This is actually a shortcut for '--checkpoint=N 3773--checkpoint-action=dot'. *Note dot: checkpoints. 3774 3775 3776File: tar.info, Node: checkpoints, Next: warnings, Prev: verbose, Up: tar invocation 3777 37783.8 Checkpoints 3779=============== 3780 3781A "checkpoint" is a moment of time before writing Nth record to the 3782archive (a "write checkpoint"), or before reading Nth record from the 3783archive (a "read checkpoint"). Checkpoints allow to periodically 3784execute arbitrary actions. 3785 3786 The checkpoint facility is enabled using the following option: 3787 3788'--checkpoint[=N]' 3789 Schedule checkpoints before writing or reading each Nth record. 3790 The default value for N is 10. 3791 3792 A list of arbitrary "actions" can be executed at each checkpoint. 3793These actions include: pausing, displaying textual messages, and 3794executing arbitrary external programs. Actions are defined using the 3795'--checkpoint-action' option. 3796 3797'--checkpoint-action=ACTION' 3798 Execute an ACTION at each checkpoint. 3799 3800 The simplest value of ACTION is 'echo'. It instructs 'tar' to 3801display the default message on the standard error stream upon arriving 3802at each checkpoint. The default message is (in POSIX locale) 'Write 3803checkpoint N', for write checkpoints, and 'Read checkpoint N', for read 3804checkpoints. Here, N represents ordinal number of the checkpoint. 3805 3806 In another locales, translated versions of this message are used. 3807 3808 This is the default action, so running: 3809 3810 $ tar -c --checkpoint=1000 --checkpoint-action=echo /var 3811 3812is equivalent to: 3813 3814 $ tar -c --checkpoint=1000 /var 3815 3816 The 'echo' action also allows to supply a customized message. You do 3817so by placing an equals sign and the message right after it, e.g.: 3818 3819 --checkpoint-action="echo=Hit %s checkpoint #%u" 3820 3821 The '%s' and '%u' in the above example are "format specifiers". The 3822'%s' specifier is replaced with the "type" of the checkpoint: 'write' or 3823'read' (or a corresponding translated version in locales other than 3824POSIX). The '%u' specifier is replaced with the ordinal number of the 3825checkpoint. Thus, the above example could produce the following output 3826when used with the '--create' option: 3827 3828 tar: Hit write checkpoint #10 3829 tar: Hit write checkpoint #20 3830 tar: Hit write checkpoint #30 3831 3832 The complete list of available format specifiers follows. Some of 3833them can take optional arguments. These arguments, if given, are 3834supplied in curly braces between the percent sign and the specifier 3835letter. 3836 3837'%s' 3838 Print type of the checkpoint ('write' or 'read'). 3839 3840'%u' 3841 Print number of the checkpoint. 3842 3843'%{r,w,d}T' 3844 Print number of bytes transferred so far and approximate transfer 3845 speed. Optional arguments supply prefixes to be used before number 3846 of bytes read, written and deleted, correspondingly. If absent, 3847 they default to 'R'. 'W', 'D'. Any or all of them can be omitted, 3848 so, that e.g. '%{}T' means to print corresponding statistics 3849 without any prefixes. Any surplus arguments, if present, are 3850 silently ignored. 3851 3852 $ tar --delete -f f.tar --checkpoint-action=echo="#%u: %T" main.c 3853 tar: #1: R: 0 (0B, 0B/s),W: 0 (0B, 0B/s),D: 0 3854 tar: #2: R: 10240 (10KiB, 19MiB/s),W: 0 (0B, 0B/s),D: 10240 3855 3856 See also the 'totals' action, described below. 3857 3858'%{FMT}t' 3859 Output current local time using FMT as format for 'strftime' (*note 3860 strftime: (strftime(3))strftime.). The '{FMT}' part is optional. 3861 If not present, the default format is '%c', i.e. the preferred 3862 date and time representation for the current locale. 3863 3864'%{N}*' 3865 Pad output with spaces to the Nth column. If the '{N}' part is 3866 omitted, the current screen width is assumed. 3867 3868'%c' 3869 This is a shortcut for '%{%Y-%m-%d %H:%M:%S}t: %ds, 3870 %{read,wrote}T%*\r', intended mainly for use with 'ttyout' action 3871 (see below). 3872 3873 Aside from format expansion, the message string is subject to 3874"unquoting", during which the backslash "escape sequences" are replaced 3875with their corresponding ASCII characters (*note escape sequences::). 3876E.g. the following action will produce an audible bell and the message 3877described above at each checkpoint: 3878 3879 --checkpoint-action='echo=\aHit %s checkpoint #%u' 3880 3881 There is also a special action which produces an audible signal: 3882'bell'. It is not equivalent to 'echo='\a'', because 'bell' sends the 3883bell directly to the console ('/dev/tty'), whereas 'echo='\a'' sends it 3884to the standard error. 3885 3886 The 'ttyout=STRING' action outputs STRING to '/dev/tty', so it can be 3887used even if the standard output is redirected elsewhere. The STRING is 3888subject to the same modifications as with 'echo' action. In contrast to 3889the latter, 'ttyout' does not prepend 'tar' executable name to the 3890string, nor does it output a newline after it. For example, the 3891following action will print the checkpoint message at the same screen 3892line, overwriting any previous message: 3893 3894 --checkpoint-action="ttyout=Hit %s checkpoint #%u%*\r" 3895 3896Notice the use of '%*' specifier to clear out any eventual remains of 3897the prior output line. As as more complex example, consider this: 3898 3899 --checkpoint-action=ttyout='%{%Y-%m-%d %H:%M:%S}t (%d sec): #%u, %T%*\r' 3900 3901This prints the current local time, number of seconds expired since tar 3902was started, the checkpoint ordinal number, transferred bytes and 3903average computed I/O speed. 3904 3905 Another available checkpoint action is 'dot' (or '.'). It instructs 3906'tar' to print a single dot on the standard listing stream, e.g.: 3907 3908 $ tar -c --checkpoint=1000 --checkpoint-action=dot /var 3909 ... 3910 3911 For compatibility with previous GNU 'tar' versions, this action can 3912be abbreviated by placing a dot in front of the checkpoint frequency, as 3913shown in the previous section. 3914 3915 The 'totals' action prints the total number of bytes transferred so 3916far. The format of the data is the same as for the '--totals' option 3917(*note totals::). See also '%T' format specifier of the 'echo' or 3918'ttyout' action. 3919 3920 Yet another action, 'sleep', pauses 'tar' for a specified amount of 3921seconds. The following example will stop for 30 seconds at each 3922checkpoint: 3923 3924 $ tar -c --checkpoint=1000 --checkpoint-action=sleep=30 3925 3926 The 'wait=SIGNO' action stops further execution until the signal 3927SIGNO is delivered. Valid values for SIGNO are: 'SIGHUP', 'SIGQUIT', 3928'SIGINT', 'SIGUSR1' and 'SIGUSR2'. The 'SIG' prefix is optional. For 3929example: 3930 3931 $ tar -c -f arc --checkpoint=1000 --checkpoint-action wait=USR1 . 3932 3933 In this example, GNU 'tar' will stop archivation at each 1000th 3934checkpoint. wait until the 'SIGUSR1' signal is delivered, and resume 3935processing. 3936 3937 This action is used by the 'genfile' utility to perform modifications 3938on the input files upon hitting certain checkpoints (*note genfile: Exec 3939Mode.). 3940 3941 Finally, the 'exec' action executes a given external command. For 3942example: 3943 3944 $ tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint 3945 3946 The supplied command can be any valid command invocation, with or 3947without additional command line arguments. If it does contain 3948arguments, don't forget to quote it to prevent it from being split by 3949the shell. *Note Running External Commands: external, for more detail. 3950 3951 The command gets a copy of 'tar''s environment plus the following 3952variables: 3953 3954'TAR_VERSION' 3955 GNU 'tar' version number. 3956 3957'TAR_ARCHIVE' 3958 The name of the archive 'tar' is processing. 3959 3960'TAR_BLOCKING_FACTOR' 3961 Current blocking factor (*note Blocking::). 3962 3963'TAR_CHECKPOINT' 3964 Number of the checkpoint. 3965 3966'TAR_SUBCOMMAND' 3967 A short option describing the operation 'tar' is executing. *Note 3968 Operations::, for a complete list of subcommand options. 3969 3970'TAR_FORMAT' 3971 Format of the archive being processed. *Note Formats::, for a 3972 complete list of archive format names. 3973 3974 These environment variables can also be passed as arguments to the 3975command, provided that they are properly escaped, for example: 3976 3977 tar -c -f arc.tar \ 3978 --checkpoint-action='exec=/sbin/cpoint $TAR_CHECKPOINT' 3979 3980Notice single quotes to prevent variable names from being expanded by 3981the shell when invoking 'tar'. 3982 3983 Any number of actions can be defined, by supplying several 3984'--checkpoint-action' options in the command line. For example, the 3985command below displays two messages, pauses execution for 30 seconds and 3986executes the '/sbin/cpoint' script: 3987 3988 $ tar -c -f arc.tar \ 3989 --checkpoint-action='\aecho=Hit %s checkpoint #%u' \ 3990 --checkpoint-action='echo=Sleeping for 30 seconds' \ 3991 --checkpoint-action='sleep=30' \ 3992 --checkpoint-action='exec=/sbin/cpoint' 3993 3994 This example also illustrates the fact that '--checkpoint-action' can 3995be used without '--checkpoint'. In this case, the default checkpoint 3996frequency (at each 10th record) is assumed. 3997 3998 3999File: tar.info, Node: warnings, Next: interactive, Prev: checkpoints, Up: tar invocation 4000 40013.9 Controlling Warning Messages 4002================================ 4003 4004Sometimes, while performing the requested task, GNU 'tar' notices some 4005conditions that are not exactly errors, but which the user should be 4006aware of. When this happens, 'tar' issues a "warning message" 4007describing the condition. Warning messages are output to the standard 4008error and they do not affect the exit code of 'tar' command. 4009 4010 GNU 'tar' allows the user to suppress some or all of its warning 4011messages: 4012 4013'--warning=KEYWORD' 4014 Control display of the warning messages identified by KEYWORD. If 4015 KEYWORD starts with the prefix 'no-', such messages are suppressed. 4016 Otherwise, they are enabled. 4017 4018 Multiple '--warning' messages accumulate. 4019 4020 The tables below list allowed values for KEYWORD along with the 4021 warning messages they control. 4022 4023Keywords controlling 'tar' operation 4024------------------------------------ 4025 4026all 4027 Enable all warning messages. This is the default. 4028none 4029 Disable all warning messages. 4030filename-with-nuls 4031 '%s: file name read contains nul character' 4032alone-zero-block 4033 'A lone zero block at %s' 4034 4035Keywords applicable for 'tar --create' 4036-------------------------------------- 4037 4038cachedir 4039 '%s: contains a cache directory tag %s; %s' 4040file-shrank 4041 '%s: File shrank by %s bytes; padding with zeros' 4042xdev 4043 '%s: file is on a different filesystem; not dumped' 4044file-ignored 4045 '%s: Unknown file type; file ignored' 4046 '%s: socket ignored' 4047 '%s: door ignored' 4048file-unchanged 4049 '%s: file is unchanged; not dumped' 4050ignore-archive 4051 '%s: file is the archive; not dumped' 4052file-removed 4053 '%s: File removed before we read it' 4054file-changed 4055 '%s: file changed as we read it' 4056failed-read 4057 Suppresses warnings about unreadable files or directories. This 4058 keyword applies only if used together with the 4059 '--ignore-failed-read' option. *Note Ignore Failed Read::. 4060 4061Keywords applicable for 'tar --extract' 4062--------------------------------------- 4063 4064existing-file 4065 '%s: skipping existing file' 4066timestamp 4067 '%s: implausibly old time stamp %s' 4068 '%s: time stamp %s is %s s in the future' 4069contiguous-cast 4070 'Extracting contiguous files as regular files' 4071symlink-cast 4072 'Attempting extraction of symbolic links as hard links' 4073unknown-cast 4074 '%s: Unknown file type '%c', extracted as normal file' 4075ignore-newer 4076 'Current %s is newer or same age' 4077unknown-keyword 4078 'Ignoring unknown extended header keyword '%s'' 4079decompress-program 4080 Controls verbose description of failures occurring when trying to 4081 run alternative decompressor programs (*note alternative 4082 decompression programs::). This warning is disabled by default 4083 (unless '--verbose' is used). A common example of what you can get 4084 when using this warning is: 4085 4086 $ tar --warning=decompress-program -x -f archive.Z 4087 tar (child): cannot run compress: No such file or directory 4088 tar (child): trying gzip 4089 4090 This means that 'tar' first tried to decompress 'archive.Z' using 4091 'compress', and, when that failed, switched to 'gzip'. 4092record-size 4093 'Record size = %lu blocks' 4094 4095Keywords controlling incremental extraction: 4096-------------------------------------------- 4097 4098rename-directory 4099 '%s: Directory has been renamed from %s' 4100 '%s: Directory has been renamed' 4101new-directory 4102 '%s: Directory is new' 4103xdev 4104 '%s: directory is on a different device: not purging' 4105bad-dumpdir 4106 'Malformed dumpdir: 'X' never used' 4107 4108 4109File: tar.info, Node: interactive, Next: external, Prev: warnings, Up: tar invocation 4110 41113.10 Asking for Confirmation During Operations 4112============================================== 4113 4114Typically, 'tar' carries out a command without stopping for further 4115instructions. In some situations however, you may want to exclude some 4116files and archive members from the operation (for instance if disk or 4117storage space is tight). You can do this by excluding certain files 4118automatically (*note Choosing::), or by performing an operation 4119interactively, using the '--interactive' ('-w') option. 'tar' also 4120accepts '--confirmation' for this option. 4121 4122 When the '--interactive' ('-w') option is specified, before reading, 4123writing, or deleting files, 'tar' first prints a message for each such 4124file, telling what operation it intends to take, then asks for 4125confirmation on the terminal. The actions which require confirmation 4126include adding a file to the archive, extracting a file from the 4127archive, deleting a file from the archive, and deleting a file from 4128disk. To confirm the action, you must type a line of input beginning 4129with 'y'. If your input line begins with anything other than 'y', 'tar' 4130skips that file. 4131 4132 If 'tar' is reading the archive from the standard input, 'tar' opens 4133the file '/dev/tty' to support the interactive communications. 4134 4135 Verbose output is normally sent to standard output, separate from 4136other error messages. However, if the archive is produced directly on 4137standard output, then verbose output is mixed with errors on 'stderr'. 4138Producing the archive on standard output may be used as a way to avoid 4139using disk space, when the archive is soon to be consumed by another 4140process reading it, say. Some people felt the need of producing an 4141archive on stdout, still willing to segregate between verbose output and 4142error output. A possible approach would be using a named pipe to 4143receive the archive, and having the consumer process to read from that 4144named pipe. This has the advantage of letting standard output free to 4145receive verbose output, all separate from errors. 4146 4147 4148File: tar.info, Node: external, Prev: interactive, Up: tar invocation 4149 41503.11 Running External Commands 4151============================== 4152 4153Certain GNU 'tar' operations imply running external commands that you 4154supply on the command line. One of such operations is checkpointing, 4155described above (*note checkpoint exec::). Another example of this 4156feature is the '-I' option, which allows you to supply the program to 4157use for compressing or decompressing the archive (*note 4158use-compress-program::). 4159 4160 Whenever such operation is requested, 'tar' first splits the supplied 4161command into words much like the shell does. It then treats the first 4162word as the name of the program or the shell script to execute and the 4163rest of words as its command line arguments. The program, unless given 4164as an absolute file name, is searched in the shell's 'PATH'. 4165 4166 Any additional information is normally supplied to external commands 4167in environment variables, specific to each particular operation. For 4168example, the '--checkpoint-action=exec' option, defines the 4169'TAR_ARCHIVE' variable to the name of the archive being worked upon. 4170You can, should the need be, use these variables in the command line of 4171the external command. For example: 4172 4173 $ tar -x -f archive.tar \ 4174 --checkpoint-action=exec='printf "%04d in %32s\r" $TAR_CHECKPOINT $TAR_ARCHIVE' 4175 4176This command prints for each checkpoint its number and the name of the 4177archive, using the same output line on the screen. 4178 4179 Notice the use of single quotes to prevent variable names from being 4180expanded by the shell when invoking 'tar'. 4181 4182 4183File: tar.info, Node: operations, Next: Backups, Prev: tar invocation, Up: Top 4184 41854 GNU 'tar' Operations 4186********************** 4187 4188* Menu: 4189 4190* Basic tar:: 4191* Advanced tar:: 4192* create options:: 4193* extract options:: 4194* backup:: 4195* looking ahead:: 4196 4197 4198File: tar.info, Node: Basic tar, Next: Advanced tar, Up: operations 4199 42004.1 Basic GNU 'tar' Operations 4201============================== 4202 4203The basic 'tar' operations, '--create' ('-c'), '--list' ('-t') and 4204'--extract' ('--get', '-x'), are currently presented and described in 4205the tutorial chapter of this manual. This section provides some 4206complementary notes for these operations. 4207 4208'--create' 4209'-c' 4210 4211 Creating an empty archive would have some kind of elegance. One 4212 can initialize an empty archive and later use '--append' ('-r') for 4213 adding all members. Some applications would not welcome making an 4214 exception in the way of adding the first archive member. On the 4215 other hand, many people reported that it is dangerously too easy 4216 for 'tar' to destroy a magnetic tape with an empty archive(1). The 4217 two most common errors are: 4218 4219 1. Mistakingly using 'create' instead of 'extract', when the 4220 intent was to extract the full contents of an archive. This 4221 error is likely: keys 'c' and 'x' are right next to each other 4222 on the QWERTY keyboard. Instead of being unpacked, the 4223 archive then gets wholly destroyed. When users speak about 4224 "exploding" an archive, they usually mean something else :-). 4225 4226 2. Forgetting the argument to 'file', when the intent was to 4227 create an archive with a single file in it. This error is 4228 likely because a tired user can easily add the 'f' key to the 4229 cluster of option letters, by the mere force of habit, without 4230 realizing the full consequence of doing so. The usual 4231 consequence is that the single file, which was meant to be 4232 saved, is rather destroyed. 4233 4234 So, recognizing the likelihood and the catastrophic nature of these 4235 errors, GNU 'tar' now takes some distance from elegance, and 4236 cowardly refuses to create an archive when '--create' option is 4237 given, there are no arguments besides options, and '--files-from' 4238 ('-T') option is _not_ used. To get around the cautiousness of GNU 4239 'tar' and nevertheless create an archive with nothing in it, one 4240 may still use, as the value for the '--files-from' option, a file 4241 with no names in it, as shown in the following commands: 4242 4243 tar --create --file=empty-archive.tar --files-from=/dev/null 4244 tar -cf empty-archive.tar -T /dev/null 4245 4246'--extract' 4247'--get' 4248'-x' 4249 4250 A socket is stored, within a GNU 'tar' archive, as a pipe. 4251 4252'--list (-t)' 4253 4254 GNU 'tar' now shows dates as '1996-08-30', while it used to show 4255 them as 'Aug 30 1996'. Preferably, people should get used to ISO 4256 8601 dates. Local American dates should be made available again 4257 with full date localization support, once ready. In the meantime, 4258 programs not being localizable for dates should prefer 4259 international dates, that's really the way to go. 4260 4261 Look up <http://www.cl.cam.ac.uk/~mgk25/iso-time.html> if you are 4262 curious, it contains a detailed explanation of the ISO 8601 4263 standard. 4264 4265 ---------- Footnotes ---------- 4266 4267 (1) This is well described in 'Unix-haters Handbook', by Simson 4268Garfinkel, Daniel Weise & Steven Strassmann, IDG Books, ISBN 42691-56884-203-1. 4270 4271 4272File: tar.info, Node: Advanced tar, Next: create options, Prev: Basic tar, Up: operations 4273 42744.2 Advanced GNU 'tar' Operations 4275================================= 4276 4277Now that you have learned the basics of using GNU 'tar', you may want to 4278learn about further ways in which 'tar' can help you. 4279 4280 This chapter presents five, more advanced operations which you 4281probably won't use on a daily basis, but which serve more specialized 4282functions. We also explain the different styles of options and why you 4283might want to use one or another, or a combination of them in your 'tar' 4284commands. Additionally, this chapter includes options which allow you 4285to define the output from 'tar' more carefully, and provide help and 4286error correction in special circumstances. 4287 4288* Menu: 4289 4290* Operations:: 4291* append:: 4292* update:: 4293* concatenate:: 4294* delete:: 4295* compare:: 4296 4297 4298File: tar.info, Node: Operations, Next: append, Up: Advanced tar 4299 43004.2.1 The Five Advanced 'tar' Operations 4301---------------------------------------- 4302 4303In the last chapter, you learned about the first three operations to 4304'tar'. This chapter presents the remaining five operations to 'tar': 4305'--append', '--update', '--concatenate', '--delete', and '--compare'. 4306 4307 You are not likely to use these operations as frequently as those 4308covered in the last chapter; however, since they perform specialized 4309functions, they are quite useful when you do need to use them. We will 4310give examples using the same directory and files that you created in the 4311last chapter. As you may recall, the directory is called 'practice', 4312the files are 'jazz', 'blues', 'folk', and the two archive files you 4313created are 'collection.tar' and 'music.tar'. 4314 4315 We will also use the archive files 'afiles.tar' and 'bfiles.tar'. 4316The archive 'afiles.tar' contains the members 'apple', 'angst', and 4317'aspic'; 'bfiles.tar' contains the members './birds', 'baboon', and 4318'./box'. 4319 4320 Unless we state otherwise, all practicing you do and examples you 4321follow in this chapter will take place in the 'practice' directory that 4322you created in the previous chapter; see *note prepare for examples::. 4323(Below in this section, we will remind you of the state of the examples 4324where the last chapter left them.) 4325 4326 The five operations that we will cover in this chapter are: 4327 4328'--append' 4329'-r' 4330 Add new entries to an archive that already exists. 4331'--update' 4332'-u' 4333 Add more recent copies of archive members to the end of an archive, 4334 if they exist. 4335'--concatenate' 4336'--catenate' 4337'-A' 4338 Add one or more pre-existing archives to the end of another 4339 archive. 4340'--delete' 4341 Delete items from an archive (does not work on tapes). 4342'--compare' 4343'--diff' 4344'-d' 4345 Compare archive members to their counterparts in the file system. 4346 4347 4348File: tar.info, Node: append, Next: update, Prev: Operations, Up: Advanced tar 4349 43504.2.2 How to Add Files to Existing Archives: '--append' 4351------------------------------------------------------- 4352 4353If you want to add files to an existing archive, you don't need to 4354create a new archive; you can use '--append' ('-r'). The archive must 4355already exist in order to use '--append'. (A related operation is the 4356'--update' operation; you can use this to add newer versions of archive 4357members to an existing archive. To learn how to do this with 4358'--update', *note update::.) 4359 4360 If you use '--append' to add a file that has the same name as an 4361archive member to an archive containing that archive member, then the 4362old member is not deleted. What does happen, however, is somewhat 4363complex. 'tar' _allows_ you to have infinite number of files with the 4364same name. Some operations treat these same-named members no 4365differently than any other set of archive members: for example, if you 4366view an archive with '--list' ('-t'), you will see all of those members 4367listed, with their data modification times, owners, etc. 4368 4369 Other operations don't deal with these members as perfectly as you 4370might prefer; if you were to use '--extract' to extract the archive, 4371only the most recently added copy of a member with the same name as 4372other members would end up in the working directory. This is because 4373'--extract' extracts an archive in the order the members appeared in the 4374archive; the most recently archived members will be extracted last. 4375Additionally, an extracted member will _replace_ a file of the same name 4376which existed in the directory already, and 'tar' will not prompt you 4377about this(1). Thus, only the most recently archived member will end up 4378being extracted, as it will replace the one extracted before it, and so 4379on. 4380 4381 There exists a special option that allows you to get around this 4382behavior and extract (or list) only a particular copy of the file. This 4383is '--occurrence' option. If you run 'tar' with this option, it will 4384extract only the first copy of the file. You may also give this option 4385an argument specifying the number of copy to be extracted. Thus, for 4386example if the archive 'archive.tar' contained three copies of file 4387'myfile', then the command 4388 4389 tar --extract --file archive.tar --occurrence=2 myfile 4390 4391would extract only the second copy. *Note --occurrence: Option Summary, 4392for the description of '--occurrence' option. 4393 4394 If you want to replace an archive member, use '--delete' to delete 4395the member you want to remove from the archive, and then use '--append' 4396to add the member you want to be in the archive. Note that you can not 4397change the order of the archive; the most recently added member will 4398still appear last. In this sense, you cannot truly "replace" one member 4399with another. (Replacing one member with another will not work on 4400certain types of media, such as tapes; see *note delete:: and *note 4401Media::, for more information.) 4402 4403* Menu: 4404 4405* appending files:: Appending Files to an Archive 4406* multiple:: 4407 4408 ---------- Footnotes ---------- 4409 4410 (1) Unless you give it '--keep-old-files' (or '--skip-old-files') 4411option, or the disk copy is newer than the one in the archive and you 4412invoke 'tar' with '--keep-newer-files' option. 4413 4414 4415File: tar.info, Node: appending files, Next: multiple, Up: append 4416 44174.2.2.1 Appending Files to an Archive 4418..................................... 4419 4420The simplest way to add a file to an already existing archive is the 4421'--append' ('-r') operation, which writes specified files into the 4422archive whether or not they are already among the archived files. 4423 4424 When you use '--append', you _must_ specify file name arguments, as 4425there is no default. If you specify a file that already exists in the 4426archive, another copy of the file will be added to the end of the 4427archive. As with other operations, the member names of the newly added 4428files will be exactly the same as their names given on the command line. 4429The '--verbose' ('-v') option will print out the names of the files as 4430they are written into the archive. 4431 4432 '--append' cannot be performed on some tape drives, unfortunately, 4433due to deficiencies in the formats those tape drives use. The archive 4434must be a valid 'tar' archive, or else the results of using this 4435operation will be unpredictable. *Note Media::. 4436 4437 To demonstrate using '--append' to add a file to an archive, create a 4438file called 'rock' in the 'practice' directory. Make sure you are in 4439the 'practice' directory. Then, run the following 'tar' command to add 4440'rock' to 'collection.tar': 4441 4442 $ tar --append --file=collection.tar rock 4443 4444If you now use the '--list' ('-t') operation, you will see that 'rock' 4445has been added to the archive: 4446 4447 $ tar --list --file=collection.tar 4448 -rw-r--r-- me/user 28 1996-10-18 16:31 jazz 4449 -rw-r--r-- me/user 21 1996-09-23 16:44 blues 4450 -rw-r--r-- me/user 20 1996-09-23 16:44 folk 4451 -rw-r--r-- me/user 20 1996-09-23 16:44 rock 4452 4453 4454File: tar.info, Node: multiple, Prev: appending files, Up: append 4455 44564.2.2.2 Multiple Members with the Same Name 4457........................................... 4458 4459You can use '--append' ('-r') to add copies of files which have been 4460updated since the archive was created. (However, we do not recommend 4461doing this since there is another 'tar' option called '--update'; *Note 4462update::, for more information. We describe this use of '--append' here 4463for the sake of completeness.) When you extract the archive, the older 4464version will be effectively lost. This works because files are 4465extracted from an archive in the order in which they were archived. 4466Thus, when the archive is extracted, a file archived later in time will 4467replace a file of the same name which was archived earlier, even though 4468the older version of the file will remain in the archive unless you 4469delete all versions of the file. 4470 4471 Supposing you change the file 'blues' and then append the changed 4472version to 'collection.tar'. As you saw above, the original 'blues' is 4473in the archive 'collection.tar'. If you change the file and append the 4474new version of the file to the archive, there will be two copies in the 4475archive. When you extract the archive, the older version of the file 4476will be extracted first, and then replaced by the newer version when it 4477is extracted. 4478 4479 You can append the new, changed copy of the file 'blues' to the 4480archive in this way: 4481 4482 $ tar --append --verbose --file=collection.tar blues 4483 blues 4484 4485Because you specified the '--verbose' option, 'tar' has printed the name 4486of the file being appended as it was acted on. Now list the contents of 4487the archive: 4488 4489 $ tar --list --verbose --file=collection.tar 4490 -rw-r--r-- me/user 28 1996-10-18 16:31 jazz 4491 -rw-r--r-- me/user 21 1996-09-23 16:44 blues 4492 -rw-r--r-- me/user 20 1996-09-23 16:44 folk 4493 -rw-r--r-- me/user 20 1996-09-23 16:44 rock 4494 -rw-r--r-- me/user 58 1996-10-24 18:30 blues 4495 4496The newest version of 'blues' is now at the end of the archive (note the 4497different creation dates and file sizes). If you extract the archive, 4498the older version of the file 'blues' will be replaced by the newer 4499version. You can confirm this by extracting the archive and running 4500'ls' on the directory. 4501 4502 If you wish to extract the first occurrence of the file 'blues' from 4503the archive, use '--occurrence' option, as shown in the following 4504example: 4505 4506 $ tar --extract -vv --occurrence --file=collection.tar blues 4507 -rw-r--r-- me/user 21 1996-09-23 16:44 blues 4508 4509 *Note Writing::, for more information on '--extract' and see *note 4510-occurrence: Option Summary, for a description of '--occurrence' option. 4511 4512 4513File: tar.info, Node: update, Next: concatenate, Prev: append, Up: Advanced tar 4514 45154.2.3 Updating an Archive 4516------------------------- 4517 4518In the previous section, you learned how to use '--append' to add a file 4519to an existing archive. A related operation is '--update' ('-u'). The 4520'--update' operation updates a 'tar' archive by comparing the date of 4521the specified archive members against the date of the file with the same 4522name. If the file has been modified more recently than the archive 4523member, then the newer version of the file is added to the archive (as 4524with '--append'). 4525 4526 Unfortunately, you cannot use '--update' with magnetic tape drives. 4527The operation will fail. 4528 4529 Both '--update' and '--append' work by adding to the end of the 4530archive. When you extract a file from the archive, only the version 4531stored last will wind up in the file system, unless you use the 4532'--backup' option. *Note multiple::, for a detailed discussion. 4533 4534* Menu: 4535 4536* how to update:: 4537 4538 4539File: tar.info, Node: how to update, Up: update 4540 45414.2.3.1 How to Update an Archive Using '--update' 4542................................................. 4543 4544You must use file name arguments with the '--update' ('-u') operation. 4545If you don't specify any files, 'tar' won't act on any files and won't 4546tell you that it didn't do anything (which may end up confusing you). 4547 4548 To see the '--update' option at work, create a new file, 'classical', 4549in your practice directory, and some extra text to the file 'blues', 4550using any text editor. Then invoke 'tar' with the 'update' operation 4551and the '--verbose' ('-v') option specified, using the names of all the 4552files in the 'practice' directory as file name arguments: 4553 4554 $ tar --update -v -f collection.tar blues folk rock classical 4555 blues 4556 classical 4557 $ 4558 4559Because we have specified verbose mode, 'tar' prints out the names of 4560the files it is working on, which in this case are the names of the 4561files that needed to be updated. If you run 'tar --list' and look at 4562the archive, you will see 'blues' and 'classical' at its end. There 4563will be a total of two versions of the member 'blues'; the one at the 4564end will be newer and larger, since you added text before updating it. 4565 4566 The reason 'tar' does not overwrite the older file when updating it 4567is that writing to the middle of a section of tape is a difficult 4568process. Tapes are not designed to go backward. *Note Media::, for 4569more information about tapes. 4570 4571 '--update' ('-u') is not suitable for performing backups for two 4572reasons: it does not change directory content entries, and it lengthens 4573the archive every time it is used. The GNU 'tar' options intended 4574specifically for backups are more efficient. If you need to run 4575backups, please consult *note Backups::. 4576 4577 4578File: tar.info, Node: concatenate, Next: delete, Prev: update, Up: Advanced tar 4579 45804.2.4 Combining Archives with '--concatenate' 4581--------------------------------------------- 4582 4583Sometimes it may be convenient to add a second archive onto the end of 4584an archive rather than adding individual files to the archive. To add 4585one or more archives to the end of another archive, you should use the 4586'--concatenate' ('--catenate', '-A') operation. 4587 4588 To use '--concatenate', give the first archive with '--file' option 4589and name the rest of archives to be concatenated on the command line. 4590The members, and their member names, will be copied verbatim from those 4591archives to the first one(1). The new, concatenated archive will be 4592called by the same name as the one given with the '--file' option. As 4593usual, if you omit '--file', 'tar' will use the value of the environment 4594variable 'TAPE', or, if this has not been set, the default archive name. 4595 4596 To demonstrate how '--concatenate' works, create two small archives 4597called 'bluesrock.tar' and 'folkjazz.tar', using the relevant files from 4598'practice': 4599 4600 $ tar -cvf bluesrock.tar blues rock 4601 blues 4602 rock 4603 $ tar -cvf folkjazz.tar folk jazz 4604 folk 4605 jazz 4606 4607If you like, You can run 'tar --list' to make sure the archives contain 4608what they are supposed to: 4609 4610 $ tar -tvf bluesrock.tar 4611 -rw-r--r-- melissa/user 105 1997-01-21 19:42 blues 4612 -rw-r--r-- melissa/user 33 1997-01-20 15:34 rock 4613 $ tar -tvf jazzfolk.tar 4614 -rw-r--r-- melissa/user 20 1996-09-23 16:44 folk 4615 -rw-r--r-- melissa/user 65 1997-01-30 14:15 jazz 4616 4617 We can concatenate these two archives with 'tar': 4618 4619 $ cd .. 4620 $ tar --concatenate --file=bluesrock.tar jazzfolk.tar 4621 4622 If you now list the contents of the 'bluesrock.tar', you will see 4623that now it also contains the archive members of 'jazzfolk.tar': 4624 4625 $ tar --list --file=bluesrock.tar 4626 blues 4627 rock 4628 folk 4629 jazz 4630 4631 When you use '--concatenate', the source and target archives must 4632already exist and must have been created using compatible format 4633parameters. Notice, that 'tar' does not check whether the archives it 4634concatenates have compatible formats, it does not even check if the 4635files are really tar archives. 4636 4637 Like '--append' ('-r'), this operation cannot be performed on some 4638tape drives, due to deficiencies in the formats those tape drives use. 4639 4640 It may seem more intuitive to you to want or try to use 'cat' to 4641concatenate two archives instead of using the '--concatenate' operation; 4642after all, 'cat' is the utility for combining files. 4643 4644 However, 'tar' archives incorporate an end-of-file marker which must 4645be removed if the concatenated archives are to be read properly as one 4646archive. '--concatenate' removes the end-of-archive marker from the 4647target archive before each new archive is appended. If you use 'cat' to 4648combine the archives, the result will not be a valid 'tar' format 4649archive. If you need to retrieve files from an archive that was added 4650to using the 'cat' utility, use the '--ignore-zeros' ('-i') option. 4651*Note Ignore Zeros::, for further information on dealing with archives 4652improperly combined using the 'cat' shell utility. 4653 4654 ---------- Footnotes ---------- 4655 4656 (1) This can cause multiple members to have the same name. For 4657information on how this affects reading the archive, see *note 4658multiple::. 4659 4660 4661File: tar.info, Node: delete, Next: compare, Prev: concatenate, Up: Advanced tar 4662 46634.2.5 Removing Archive Members Using '--delete' 4664----------------------------------------------- 4665 4666You can remove members from an archive by using the '--delete' option. 4667Specify the name of the archive with '--file' ('-f') and then specify 4668the names of the members to be deleted; if you list no member names, 4669nothing will be deleted. The '--verbose' option will cause 'tar' to 4670print the names of the members as they are deleted. As with 4671'--extract', you must give the exact member names when using 'tar 4672--delete'. '--delete' will remove all versions of the named file from 4673the archive. The '--delete' operation can run very slowly. 4674 4675 Unlike other operations, '--delete' has no short form. 4676 4677 This operation will rewrite the archive. You can only use '--delete' 4678on an archive if the archive device allows you to write to any point on 4679the media, such as a disk; because of this, it does not work on magnetic 4680tapes. Do not try to delete an archive member from a magnetic tape; the 4681action will not succeed, and you will be likely to scramble the archive 4682and damage your tape. There is no safe way (except by completely 4683re-writing the archive) to delete files from most kinds of magnetic 4684tape. *Note Media::. 4685 4686 To delete all versions of the file 'blues' from the archive 4687'collection.tar' in the 'practice' directory, make sure you are in that 4688directory, and then, 4689 4690 $ tar --list --file=collection.tar 4691 blues 4692 folk 4693 jazz 4694 rock 4695 $ tar --delete --file=collection.tar blues 4696 $ tar --list --file=collection.tar 4697 folk 4698 jazz 4699 rock 4700 4701 The '--delete' option has been reported to work properly when 'tar' 4702acts as a filter from 'stdin' to 'stdout'. 4703 4704 4705File: tar.info, Node: compare, Prev: delete, Up: Advanced tar 4706 47074.2.6 Comparing Archive Members with the File System 4708---------------------------------------------------- 4709 4710The '--compare' ('-d'), or '--diff' operation compares specified archive 4711members against files with the same names, and then reports differences 4712in file size, mode, owner, modification date and contents. You should 4713_only_ specify archive member names, not file names. If you do not name 4714any members, then 'tar' will compare the entire archive. If a file is 4715represented in the archive but does not exist in the file system, 'tar' 4716reports a difference. 4717 4718 You have to specify the record size of the archive when modifying an 4719archive with a non-default record size. 4720 4721 'tar' ignores files in the file system that do not have corresponding 4722members in the archive. 4723 4724 The following example compares the archive members 'rock', 'blues' 4725and 'funk' in the archive 'bluesrock.tar' with files of the same name in 4726the file system. (Note that there is no file, 'funk'; 'tar' will report 4727an error message.) 4728 4729 $ tar --compare --file=bluesrock.tar rock blues funk 4730 rock 4731 blues 4732 tar: funk not found in archive 4733 4734 The spirit behind the '--compare' ('--diff', '-d') option is to check 4735whether the archive represents the current state of files on disk, more 4736than validating the integrity of the archive media. For this latter 4737goal, see *note verify::. 4738 4739 4740File: tar.info, Node: create options, Next: extract options, Prev: Advanced tar, Up: operations 4741 47424.3 Options Used by '--create' 4743============================== 4744 4745The previous chapter described the basics of how to use '--create' 4746('-c') to create an archive from a set of files. *Note create::. This 4747section described advanced options to be used with '--create'. 4748 4749* Menu: 4750 4751* override:: Overriding File Metadata. 4752* Extended File Attributes:: 4753* Ignore Failed Read:: 4754 4755 4756File: tar.info, Node: override, Next: Extended File Attributes, Up: create options 4757 47584.3.1 Overriding File Metadata 4759------------------------------ 4760 4761As described above, a 'tar' archive keeps, for each member it contains, 4762its "metadata", such as modification time, mode and ownership of the 4763file. GNU 'tar' allows to replace these data with other values when 4764adding files to the archive. The options described in this section 4765affect creation of archives of any type. For POSIX archives, see also 4766*note PAX keywords::, for additional ways of controlling metadata, 4767stored in the archive. 4768 4769'--mode=PERMISSIONS' 4770 4771 When adding files to an archive, 'tar' will use PERMISSIONS for the 4772 archive members, rather than the permissions from the files. 4773 PERMISSIONS can be specified either as an octal number or as 4774 symbolic permissions, like with 'chmod' (*Note Permissions: 4775 (fileutils)File permissions. This reference also has useful 4776 information for those not being overly familiar with the UNIX 4777 permission system). Using latter syntax allows for more 4778 flexibility. For example, the value 'a+rw' adds read and write 4779 permissions for everybody, while retaining executable bits on 4780 directories or on any other file already marked as executable: 4781 4782 $ tar -c -f archive.tar --mode='a+rw' . 4783 4784'--mtime=DATE' 4785 4786 When adding files to an archive, 'tar' will use DATE as the 4787 modification time of members when creating archives, instead of 4788 their actual modification times. The argument DATE can be either a 4789 textual date representation in almost arbitrary format (*note Date 4790 input formats::) or a name of an existing file, starting with '/' 4791 or '.'. In the latter case, the modification time of that file 4792 will be used. 4793 4794 The following example will set the modification date to 00:00:00, 4795 January 1, 1970: 4796 4797 $ tar -c -f archive.tar --mtime='1970-01-01' . 4798 4799 When used with '--verbose' (*note verbose tutorial::) GNU 'tar' 4800 will try to convert the specified date back to its textual 4801 representation and compare it with the one given with '--mtime' 4802 options. If the two dates differ, 'tar' will print a warning 4803 saying what date it will use. This is to help user ensure he is 4804 using the right date. 4805 4806 For example: 4807 4808 $ tar -c -f archive.tar -v --mtime=yesterday . 4809 tar: Option --mtime: Treating date 'yesterday' as 2006-06-20 4810 13:06:29.152478 4811 ... 4812 4813 When used with '--clamp-mtime' GNU 'tar' will only set the 4814 modification date to DATE on files whose actual modification date 4815 is later than DATE. This is to make it easy to build reproducible 4816 archives given a common timestamp for generated files while still 4817 retaining the original timestamps of untouched files. 4818 4819 $ tar -c -f archive.tar --clamp-mtime --mtime=@$SOURCE_DATE_EPOCH . 4820 4821'--owner=USER' 4822 4823 Specifies that 'tar' should use USER as the owner of members when 4824 creating archives, instead of the user associated with the source 4825 file. 4826 4827 If USER contains a colon, it is taken to be of the form NAME:ID 4828 where a nonempty NAME specifies the user name and a nonempty ID 4829 specifies the decimal numeric user ID. If USER does not contain a 4830 colon, it is taken to be a user number if it is one or more decimal 4831 digits; otherwise it is taken to be a user name. 4832 4833 If a name is given but no number, the number is inferred from the 4834 current host's user database if possible, and the file's user 4835 number is used otherwise. If a number is given but no name, the 4836 name is inferred from the number if possible, and an empty name is 4837 used otherwise. If both name and number are given, the user 4838 database is not consulted, and the name and number need not be 4839 valid on the current host. 4840 4841 There is no value indicating a missing number, and '0' usually 4842 means 'root'. Some people like to force '0' as the value to offer 4843 in their distributions for the owner of files, because the 'root' 4844 user is anonymous anyway, so that might as well be the owner of 4845 anonymous archives. For example: 4846 4847 $ tar -c -f archive.tar --owner=0 . 4848 4849 or: 4850 4851 $ tar -c -f archive.tar --owner=root . 4852 4853'--group=GROUP' 4854 4855 Files added to the 'tar' archive will have a group ID of GROUP, 4856 rather than the group from the source file. As with '--owner', the 4857 argument GROUP can be an existing group symbolic name, or a decimal 4858 numeric group ID, or NAME:ID. 4859 4860 The '--owner' and '--group' options affect all files added to the 4861archive. GNU 'tar' provides also two options that allow for more 4862detailed control over owner translation: 4863 4864'--owner-map=FILE' 4865 Read UID translation map from FILE. 4866 4867 When reading, empty lines are ignored. The '#' sign, unless 4868 quoted, introduces a comment, which extends to the end of the line. 4869 Each nonempty line defines mapping for a single UID. It must 4870 consist of two fields separated by any amount of whitespace. The 4871 first field defines original username and UID. It can be a valid 4872 user name or a valid UID prefixed with a plus sign. In both cases 4873 the corresponding UID or user name is inferred from the current 4874 host's user database. 4875 4876 The second field defines the UID and username to map the original 4877 one to. Its format can be the same as described above. Otherwise, 4878 it can have the form NEWNAME:NEWUID, in which case neither NEWNAME 4879 nor NEWUID are required to be valid as per the user database. 4880 4881 For example, consider the following file: 4882 4883 +10 bin 4884 smith root:0 4885 4886 Given this file, each input file that is owner by UID 10 will be 4887 stored in archive with owner name 'bin' and owner UID corresponding 4888 to 'bin'. Each file owned by user 'smith' will be stored with 4889 owner name 'root' and owner ID 0. Other files will remain 4890 unchanged. 4891 4892 When used together with '--owner-map', the '--owner' option affects 4893 only files whose owner is not listed in the map file. 4894 4895'--group-map=FILE' 4896 Read GID translation map from FILE. 4897 4898 The format of FILE is the same as for '--owner-map' option: 4899 4900 Each nonempty line defines mapping for a single GID. It must 4901 consist of two fields separated by any amount of whitespace. The 4902 first field defines original group name and GID. It can be a valid 4903 group name or a valid GID prefixed with a plus sign. In both cases 4904 the corresponding GID or user name is inferred from the current 4905 host's group database. 4906 4907 The second field defines the GID and group name to map the original 4908 one to. Its format can be the same as described above. Otherwise, 4909 it can have the form NEWNAME:NEWGID, in which case neither NEWNAME 4910 nor NEWGID are required to be valid as per the group database. 4911 4912 When used together with '--group-map', the '--group' option affects 4913 only files whose owner group is not rewritten using the map file. 4914 4915 4916File: tar.info, Node: Extended File Attributes, Next: Ignore Failed Read, Prev: override, Up: create options 4917 49184.3.2 Extended File Attributes 4919------------------------------ 4920 4921Extended file attributes are name-value pairs that can be associated 4922with each node in a file system. Despite the fact that POSIX.1e draft 4923which proposed them has been withdrawn, the extended file attributes are 4924supported by many file systems. GNU 'tar' can store extended file 4925attributes along with the files. This feature is controlled by the 4926following command line arguments: 4927 4928'--xattrs' 4929 Enable extended attributes support. When used with '--create', 4930 this option instructs GNU 'tar' to store extended file attribute in 4931 the created archive. This implies POSIX.1-2001 archive format 4932 ('--format=pax'). 4933 4934 When used with '--extract', this option tells 'tar', for each file 4935 extracted, to read stored attributes from the archive and to apply 4936 them to the file. 4937 4938'--no-xattrs' 4939 Disable extended attributes support. This is the default. 4940 4941 Attribute names are strings prefixed by a "namespace" name and a dot. 4942Currently, four namespaces exist: 'user', 'trusted', 'security' and 4943'system'. By default, when '--xattr' is used, all names are stored in 4944the archive (or extracted, if using '--extract'). This can be 4945controlled using the following options: 4946 4947'--xattrs-exclude=PATTERN' 4948 Specify exclude pattern for extended attributes. 4949 4950'--xattrs-include=PATTERN' 4951 Specify include pattern for extended attributes. 4952 4953 Here, the PATTERN is a globbing pattern. For example, the following 4954command: 4955 4956 $ tar --xattrs --xattrs-exclude='user.*' -c a.tar . 4957 4958 will include in the archive 'a.tar' all attributes, except those from 4959the 'user' namespace. 4960 4961 Any number of these options can be given, thereby creating lists of 4962include and exclude patterns. 4963 4964 When both options are used, first '--xattrs-include' is applied to 4965select the set of attribute names to keep, and then '--xattrs-exclude' 4966is applied to the resulting set. In other words, only those attributes 4967will be stored, whose names match one of the regexps in 4968'--xattrs-include' and don't match any of the regexps from 4969'--xattrs-exclude'. 4970 4971 When listing the archive, if both '--xattrs' and '--verbose' options 4972are given, files that have extended attributes are marked with an 4973asterisk following their permission mask. For example: 4974 4975 -rw-r--r--* smith/users 110 2016-03-16 16:07 file 4976 4977 When two or more '--verbose' options are given, a detailed listing of 4978extended attributes is printed after each file entry. Each attribute is 4979listed on a separate line, which begins with two spaces and the letter 4980'x' indicating extended attribute. It is followed by a colon, length of 4981the attribute and its name, e.g.: 4982 4983 -rw-r--r--* smith/users 110 2016-03-16 16:07 file 4984 x: 7 user.mime_type 4985 x: 32 trusted.md5sum 4986 4987 File access control lists ("ACL") are another actively used feature 4988proposed by the POSIX.1e standard. Each ACL consists of a set of ACL 4989entries, each of which describes the access permissions on the file for 4990an individual user or a group of users as a combination of read, write 4991and search/execute permissions. 4992 4993 Whether or not to use ACLs is controlled by the following two 4994options: 4995 4996'--acls' 4997 Enable POSIX ACLs support. When used with '--create', this option 4998 instructs GNU 'tar' to store ACLs in the created archive. This 4999 implies POSIX.1-2001 archive format ('--format=pax'). 5000 5001 When used with '--extract', this option tells 'tar', to restore 5002 ACLs for each file extracted (provided they are present in the 5003 archive). 5004 5005'--no-acls' 5006 Disable POSIX ACLs support. This is the default. 5007 5008 When listing the archive, if both '--acls' and '--verbose' options 5009are given, files that have ACLs are marked with a plus sign following 5010their permission mask. For example: 5011 5012 -rw-r--r--+ smith/users 110 2016-03-16 16:07 file 5013 5014 When two or more '--verbose' options are given, a detailed listing of 5015ACL is printed after each file entry: 5016 5017 -rw-r--r--+ smith/users 110 2016-03-16 16:07 file 5018 a: user::rw-,user:gray:-w-,group::r--,mask::rw-,other::r-- 5019 5020 "Security-Enhanced Linux" ("SELinux" for short) is a Linux kernel 5021security module that provides a mechanism for supporting access control 5022security policies, including so-called mandatory access controls 5023("MAC"). Support for SELinux attributes is controlled by the following 5024command line options: 5025 5026'--selinux' 5027 Enable the SELinux context support. 5028 5029'--no-selinux' 5030 Disable SELinux context support. 5031 5032 5033File: tar.info, Node: Ignore Failed Read, Prev: Extended File Attributes, Up: create options 5034 50354.3.3 Ignore Failed Read 5036------------------------ 5037 5038'--ignore-failed-read' 5039 Do not exit with nonzero on unreadable files or directories. 5040 5041 This option has effect only during creation. It instructs tar to 5042treat as mild conditions any missing or unreadable files (directories). 5043Such failures don't affect the program exit code, and the corresponding 5044diagnostic messages are marked as warnings, not errors. These warnings 5045can be suppressed using the '--warning=failed-read' option (*note 5046warnings::). 5047 5048 5049File: tar.info, Node: extract options, Next: backup, Prev: create options, Up: operations 5050 50514.4 Options Used by '--extract' 5052=============================== 5053 5054The previous chapter showed how to use '--extract' to extract an archive 5055into the file system. Various options cause 'tar' to extract more 5056information than just file contents, such as the owner, the permissions, 5057the modification date, and so forth. This section presents options to 5058be used with '--extract' when certain special considerations arise. You 5059may review the information presented in *note extract:: for more basic 5060information about the '--extract' operation. 5061 5062* Menu: 5063 5064* Reading:: Options to Help Read Archives 5065* Writing:: Changing How 'tar' Writes Files 5066* Scarce:: Coping with Scarce Resources 5067 5068 5069File: tar.info, Node: Reading, Next: Writing, Up: extract options 5070 50714.4.1 Options to Help Read Archives 5072----------------------------------- 5073 5074Normally, 'tar' will request data in full record increments from an 5075archive storage device. If the device cannot return a full record, 5076'tar' will report an error. However, some devices do not always return 5077full records, or do not require the last record of an archive to be 5078padded out to the next record boundary. To keep reading until you 5079obtain a full record, or to accept an incomplete record if it contains 5080an end-of-archive marker, specify the '--read-full-records' ('-B') 5081option in conjunction with the '--extract' or '--list' operations. 5082*Note Blocking::. 5083 5084 The '--read-full-records' ('-B') option is turned on by default when 5085'tar' reads an archive from standard input, or from a remote machine. 5086This is because on BSD Unix systems, attempting to read a pipe returns 5087however much happens to be in the pipe, even if it is less than was 5088requested. If this option were not enabled, 'tar' would fail as soon as 5089it read an incomplete record from the pipe. 5090 5091 If you're not sure of the blocking factor of an archive, you can read 5092the archive by specifying '--read-full-records' ('-B') and 5093'--blocking-factor=512-SIZE' ('-b 512-SIZE'), using a blocking factor 5094larger than what the archive uses. This lets you avoid having to 5095determine the blocking factor of an archive. *Note Blocking Factor::. 5096 5097* Menu: 5098 5099* read full records:: 5100* Ignore Zeros:: 5101 5102 5103File: tar.info, Node: read full records, Next: Ignore Zeros, Up: Reading 5104 5105Reading Full Records 5106.................... 5107 5108'--read-full-records' 5109'-B' 5110 Use in conjunction with '--extract' ('--get', '-x') to read an 5111 archive which contains incomplete records, or one which has a 5112 blocking factor less than the one specified. 5113 5114 5115File: tar.info, Node: Ignore Zeros, Prev: read full records, Up: Reading 5116 5117Ignoring Blocks of Zeros 5118........................ 5119 5120Normally, 'tar' stops reading when it encounters a block of zeros 5121between file entries (which usually indicates the end of the archive). 5122'--ignore-zeros' ('-i') allows 'tar' to completely read an archive which 5123contains a block of zeros before the end (i.e., a damaged archive, or 5124one that was created by concatenating several archives together). 5125 5126 The '--ignore-zeros' ('-i') option is turned off by default because 5127many versions of 'tar' write garbage after the end-of-archive entry, 5128since that part of the media is never supposed to be read. GNU 'tar' 5129does not write after the end of an archive, but seeks to maintain 5130compatibility among archiving utilities. 5131 5132'--ignore-zeros' 5133'-i' 5134 To ignore blocks of zeros (i.e., end-of-archive entries) which may 5135 be encountered while reading an archive. Use in conjunction with 5136 '--extract' or '--list'. 5137 5138 5139File: tar.info, Node: Writing, Next: Scarce, Prev: Reading, Up: extract options 5140 51414.4.2 Changing How 'tar' Writes Files 5142------------------------------------- 5143 5144 _(This message will disappear, once this node revised.)_ 5145 5146* Menu: 5147 5148* Dealing with Old Files:: 5149* Overwrite Old Files:: 5150* Keep Old Files:: 5151* Keep Newer Files:: 5152* Unlink First:: 5153* Recursive Unlink:: 5154* Data Modification Times:: 5155* Setting Access Permissions:: 5156* Directory Modification Times and Permissions:: 5157* Writing to Standard Output:: 5158* Writing to an External Program:: 5159* remove files:: 5160 5161 5162File: tar.info, Node: Dealing with Old Files, Next: Overwrite Old Files, Up: Writing 5163 5164Options Controlling the Overwriting of Existing Files 5165..................................................... 5166 5167When extracting files, if 'tar' discovers that the extracted file 5168already exists, it normally replaces the file by removing it before 5169extracting it, to prevent confusion in the presence of hard or symbolic 5170links. (If the existing file is a symbolic link, it is removed, not 5171followed.) However, if a directory cannot be removed because it is 5172nonempty, 'tar' normally overwrites its metadata (ownership, permission, 5173etc.). The '--overwrite-dir' option enables this default behavior. To 5174be more cautious and preserve the metadata of such a directory, use the 5175'--no-overwrite-dir' option. 5176 5177 To be even more cautious and prevent existing files from being 5178replaced, use the '--keep-old-files' ('-k') option. It causes 'tar' to 5179refuse to replace or update a file that already exists, i.e., a file 5180with the same name as an archive member prevents extraction of that 5181archive member. Instead, it reports an error. For example: 5182 5183 $ ls 5184 blues 5185 $ tar -x -k -f archive.tar 5186 tar: blues: Cannot open: File exists 5187 tar: Exiting with failure status due to previous errors 5188 5189 If you wish to preserve old files untouched, but don't want 'tar' to 5190treat them as errors, use the '--skip-old-files' option. This option 5191causes 'tar' to silently skip extracting over existing files. 5192 5193 To be more aggressive about altering existing files, use the 5194'--overwrite' option. It causes 'tar' to overwrite existing files and 5195to follow existing symbolic links when extracting. 5196 5197 Some people argue that GNU 'tar' should not hesitate to overwrite 5198files with other files when extracting. When extracting a 'tar' 5199archive, they expect to see a faithful copy of the state of the file 5200system when the archive was created. It is debatable that this would 5201always be a proper behavior. For example, suppose one has an archive in 5202which 'usr/local' is a link to 'usr/local2'. Since then, maybe the site 5203removed the link and renamed the whole hierarchy from '/usr/local2' to 5204'/usr/local'. Such things happen all the time. I guess it would not be 5205welcome at all that GNU 'tar' removes the whole hierarchy just to make 5206room for the link to be reinstated (unless it _also_ simultaneously 5207restores the full '/usr/local2', of course!) GNU 'tar' is indeed able 5208to remove a whole hierarchy to reestablish a symbolic link, for example, 5209but _only if_ '--recursive-unlink' is specified to allow this behavior. 5210In any case, single files are silently removed. 5211 5212 Finally, the '--unlink-first' ('-U') option can improve performance 5213in some cases by causing 'tar' to remove files unconditionally before 5214extracting them. 5215 5216 5217File: tar.info, Node: Overwrite Old Files, Next: Keep Old Files, Prev: Dealing with Old Files, Up: Writing 5218 5219Overwrite Old Files 5220................... 5221 5222'--overwrite' 5223 Overwrite existing files and directory metadata when extracting 5224 files from an archive. 5225 5226 This causes 'tar' to write extracted files into the file system 5227 without regard to the files already on the system; i.e., files with 5228 the same names as archive members are overwritten when the archive 5229 is extracted. It also causes 'tar' to extract the ownership, 5230 permissions, and time stamps onto any preexisting files or 5231 directories. If the name of a corresponding file name is a 5232 symbolic link, the file pointed to by the symbolic link will be 5233 overwritten instead of the symbolic link itself (if this is 5234 possible). Moreover, special devices, empty directories and even 5235 symbolic links are automatically removed if they are in the way of 5236 extraction. 5237 5238 Be careful when using the '--overwrite' option, particularly when 5239 combined with the '--absolute-names' ('-P') option, as this 5240 combination can change the contents, ownership or permissions of 5241 any file on your system. Also, many systems do not take kindly to 5242 overwriting files that are currently being executed. 5243 5244'--overwrite-dir' 5245 Overwrite the metadata of directories when extracting files from an 5246 archive, but remove other files before extracting. 5247 5248 5249File: tar.info, Node: Keep Old Files, Next: Keep Newer Files, Prev: Overwrite Old Files, Up: Writing 5250 5251Keep Old Files 5252.............. 5253 5254GNU 'tar' provides two options to control its actions in a situation 5255when it is about to extract a file which already exists on disk. 5256 5257'--keep-old-files' 5258'-k' 5259 Do not replace existing files from archive. When such a file is 5260 encountered, 'tar' issues an error message. Upon end of 5261 extraction, 'tar' exits with code 2 (*note exit status::). 5262 5263'--skip-old-files' 5264 Do not replace existing files from archive, but do not treat that 5265 as error. Such files are silently skipped and do not affect 'tar' 5266 exit status. 5267 5268 Additional verbosity can be obtained using 5269 '--warning=existing-file' together with that option (*note 5270 warnings::). 5271 5272 5273File: tar.info, Node: Keep Newer Files, Next: Unlink First, Prev: Keep Old Files, Up: Writing 5274 5275Keep Newer Files 5276................ 5277 5278'--keep-newer-files' 5279 Do not replace existing files that are newer than their archive 5280 copies. This option is meaningless with '--list' ('-t'). 5281 5282 5283File: tar.info, Node: Unlink First, Next: Recursive Unlink, Prev: Keep Newer Files, Up: Writing 5284 5285Unlink First 5286............ 5287 5288'--unlink-first' 5289'-U' 5290 Remove files before extracting over them. This can make 'tar' run 5291 a bit faster if you know in advance that the extracted files all 5292 need to be removed. Normally this option slows 'tar' down 5293 slightly, so it is disabled by default. 5294 5295 5296File: tar.info, Node: Recursive Unlink, Next: Data Modification Times, Prev: Unlink First, Up: Writing 5297 5298Recursive Unlink 5299................ 5300 5301'--recursive-unlink' 5302 When this option is specified, try removing files and directory 5303 hierarchies before extracting over them. _This is a dangerous 5304 option!_ 5305 5306 If you specify the '--recursive-unlink' option, 'tar' removes 5307_anything_ that keeps you from extracting a file as far as current 5308permissions will allow it. This could include removal of the contents 5309of a full directory hierarchy. 5310 5311 5312File: tar.info, Node: Data Modification Times, Next: Setting Access Permissions, Prev: Recursive Unlink, Up: Writing 5313 5314Setting Data Modification Times 5315............................... 5316 5317Normally, 'tar' sets the data modification times of extracted files to 5318the corresponding times recorded for the files in the archive, but 5319limits the permissions of extracted files by the current 'umask' 5320setting. 5321 5322 To set the data modification times of extracted files to the time 5323when the files were extracted, use the '--touch' ('-m') option in 5324conjunction with '--extract' ('--get', '-x'). 5325 5326'--touch' 5327'-m' 5328 Sets the data modification time of extracted archive members to the 5329 time they were extracted, not the time recorded for them in the 5330 archive. Use in conjunction with '--extract' ('--get', '-x'). 5331 5332 5333File: tar.info, Node: Setting Access Permissions, Next: Directory Modification Times and Permissions, Prev: Data Modification Times, Up: Writing 5334 5335Setting Access Permissions 5336.......................... 5337 5338To set the modes (access permissions) of extracted files to those 5339recorded for those files in the archive, use '--same-permissions' in 5340conjunction with the '--extract' ('--get', '-x') operation. 5341 5342'--preserve-permissions' 5343'--same-permissions' 5344'-p' 5345 Set modes of extracted archive members to those recorded in the 5346 archive, instead of current umask settings. Use in conjunction 5347 with '--extract' ('--get', '-x'). 5348 5349 5350File: tar.info, Node: Directory Modification Times and Permissions, Next: Writing to Standard Output, Prev: Setting Access Permissions, Up: Writing 5351 5352Directory Modification Times and Permissions 5353............................................ 5354 5355After successfully extracting a file member, GNU 'tar' normally restores 5356its permissions and modification times, as described in the previous 5357sections. This cannot be done for directories, because after extracting 5358a directory 'tar' will almost certainly extract files into that 5359directory and this will cause the directory modification time to be 5360updated. Moreover, restoring that directory permissions may not permit 5361file creation within it. Thus, restoring directory permissions and 5362modification times must be delayed at least until all files have been 5363extracted into that directory. GNU 'tar' restores directories using the 5364following approach. 5365 5366 The extracted directories are created with the mode specified in the 5367archive, as modified by the umask of the user, which gives sufficient 5368permissions to allow file creation. The meta-information about the 5369directory is recorded in the temporary list of directories. When 5370preparing to extract next archive member, GNU 'tar' checks if the 5371directory prefix of this file contains the remembered directory. If it 5372does not, the program assumes that all files have been extracted into 5373that directory, restores its modification time and permissions and 5374removes its entry from the internal list. This approach allows to 5375correctly restore directory meta-information in the majority of cases, 5376while keeping memory requirements sufficiently small. It is based on 5377the fact, that most 'tar' archives use the predefined order of members: 5378first the directory, then all the files and subdirectories in that 5379directory. 5380 5381 However, this is not always true. The most important exception are 5382incremental archives (*note Incremental Dumps::). The member order in 5383an incremental archive is reversed: first all directory members are 5384stored, followed by other (non-directory) members. So, when extracting 5385from incremental archives, GNU 'tar' alters the above procedure. It 5386remembers all restored directories, and restores their meta-data only 5387after the entire archive has been processed. Notice, that you do not 5388need to specify any special options for that, as GNU 'tar' automatically 5389detects archives in incremental format. 5390 5391 There may be cases, when such processing is required for normal 5392archives too. Consider the following example: 5393 5394 $ tar --no-recursion -cvf archive \ 5395 foo foo/file1 bar bar/file foo/file2 5396 foo/ 5397 foo/file1 5398 bar/ 5399 bar/file 5400 foo/file2 5401 5402 During the normal operation, after encountering 'bar' GNU 'tar' will 5403assume that all files from the directory 'foo' were already extracted 5404and will therefore restore its timestamp and permission bits. However, 5405after extracting 'foo/file2' the directory timestamp will be offset 5406again. 5407 5408 To correctly restore directory meta-information in such cases, use 5409the '--delay-directory-restore' command line option: 5410 5411'--delay-directory-restore' 5412 Delays restoring of the modification times and permissions of 5413 extracted directories until the end of extraction. This way, 5414 correct meta-information is restored even if the archive has 5415 unusual member ordering. 5416 5417'--no-delay-directory-restore' 5418 Cancel the effect of the previous '--delay-directory-restore'. Use 5419 this option if you have used '--delay-directory-restore' in 5420 'TAR_OPTIONS' variable (*note TAR_OPTIONS::) and wish to 5421 temporarily disable it. 5422 5423 5424File: tar.info, Node: Writing to Standard Output, Next: Writing to an External Program, Prev: Directory Modification Times and Permissions, Up: Writing 5425 5426Writing to Standard Output 5427.......................... 5428 5429To write the extracted files to the standard output, instead of creating 5430the files on the file system, use '--to-stdout' ('-O') in conjunction 5431with '--extract' ('--get', '-x'). This option is useful if you are 5432extracting files to send them through a pipe, and do not need to 5433preserve them in the file system. If you extract multiple members, they 5434appear on standard output concatenated, in the order they are found in 5435the archive. 5436 5437'--to-stdout' 5438'-O' 5439 Writes files to the standard output. Use only in conjunction with 5440 '--extract' ('--get', '-x'). When this option is used, instead of 5441 creating the files specified, 'tar' writes the contents of the 5442 files extracted to its standard output. This may be useful if you 5443 are only extracting the files in order to send them through a pipe. 5444 This option is meaningless with '--list' ('-t'). 5445 5446 This can be useful, for example, if you have a tar archive containing 5447a big file and don't want to store the file on disk before processing 5448it. You can use a command like this: 5449 5450 tar -xOzf foo.tgz bigfile | process 5451 5452 or even like this if you want to process the concatenation of the 5453files: 5454 5455 tar -xOzf foo.tgz bigfile1 bigfile2 | process 5456 5457 However, '--to-command' may be more convenient for use with multiple 5458files. See the next section. 5459 5460 5461File: tar.info, Node: Writing to an External Program, Next: remove files, Prev: Writing to Standard Output, Up: Writing 5462 5463Writing to an External Program 5464.............................. 5465 5466You can instruct 'tar' to send the contents of each extracted file to 5467the standard input of an external program: 5468 5469'--to-command=COMMAND' 5470 Extract files and pipe their contents to the standard input of 5471 COMMAND. When this option is used, instead of creating the files 5472 specified, 'tar' invokes COMMAND and pipes the contents of the 5473 files to its standard output. The COMMAND may contain command line 5474 arguments (see *note Running External Commands: external, for more 5475 detail). 5476 5477 Notice, that COMMAND is executed once for each regular file 5478 extracted. Non-regular files (directories, etc.) are ignored when 5479 this option is used. 5480 5481 The command can obtain the information about the file it processes 5482from the following environment variables: 5483 5484'TAR_FILETYPE' 5485 Type of the file. It is a single letter with the following 5486 meaning: 5487 5488 f Regular file 5489 d Directory 5490 l Symbolic link 5491 h Hard link 5492 b Block device 5493 c Character device 5494 5495 Currently only regular files are supported. 5496 5497'TAR_MODE' 5498 File mode, an octal number. 5499 5500'TAR_FILENAME' 5501 The name of the file. 5502 5503'TAR_REALNAME' 5504 Name of the file as stored in the archive. 5505 5506'TAR_UNAME' 5507 Name of the file owner. 5508 5509'TAR_GNAME' 5510 Name of the file owner group. 5511 5512'TAR_ATIME' 5513 Time of last access. It is a decimal number, representing seconds 5514 since the Epoch. If the archive provides times with nanosecond 5515 precision, the nanoseconds are appended to the timestamp after a 5516 decimal point. 5517 5518'TAR_MTIME' 5519 Time of last modification. 5520 5521'TAR_CTIME' 5522 Time of last status change. 5523 5524'TAR_SIZE' 5525 Size of the file. 5526 5527'TAR_UID' 5528 UID of the file owner. 5529 5530'TAR_GID' 5531 GID of the file owner. 5532 5533 Additionally, the following variables contain information about tar 5534mode and the archive being processed: 5535 5536'TAR_VERSION' 5537 GNU 'tar' version number. 5538 5539'TAR_ARCHIVE' 5540 The name of the archive 'tar' is processing. 5541 5542'TAR_BLOCKING_FACTOR' 5543 Current blocking factor (*note Blocking::). 5544 5545'TAR_VOLUME' 5546 Ordinal number of the volume 'tar' is processing. 5547 5548'TAR_FORMAT' 5549 Format of the archive being processed. *Note Formats::, for a 5550 complete list of archive format names. 5551 5552 These variables are defined prior to executing the command, so you 5553can pass them as arguments, if you prefer. For example, if the command 5554PROC takes the member name and size as its arguments, then you could do: 5555 5556 $ tar -x -f archive.tar \ 5557 --to-command='proc $TAR_FILENAME $TAR_SIZE' 5558 5559Notice single quotes to prevent variable names from being expanded by 5560the shell when invoking 'tar'. 5561 5562 If COMMAND exits with a non-0 status, 'tar' will print an error 5563message similar to the following: 5564 5565 tar: 2345: Child returned status 1 5566 5567 Here, '2345' is the PID of the finished process. 5568 5569 If this behavior is not wanted, use '--ignore-command-error': 5570 5571'--ignore-command-error' 5572 Ignore exit codes of subprocesses. Notice that if the program 5573 exits on signal or otherwise terminates abnormally, the error 5574 message will be printed even if this option is used. 5575 5576'--no-ignore-command-error' 5577 Cancel the effect of any previous '--ignore-command-error' option. 5578 This option is useful if you have set '--ignore-command-error' in 5579 'TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to temporarily cancel 5580 it. 5581 5582 5583File: tar.info, Node: remove files, Prev: Writing to an External Program, Up: Writing 5584 5585Removing Files 5586.............. 5587 5588'--remove-files' 5589 Remove files after adding them to the archive. 5590 5591 5592File: tar.info, Node: Scarce, Prev: Writing, Up: extract options 5593 55944.4.3 Coping with Scarce Resources 5595---------------------------------- 5596 5597 _(This message will disappear, once this node revised.)_ 5598 5599* Menu: 5600 5601* Starting File:: 5602* Same Order:: 5603 5604 5605File: tar.info, Node: Starting File, Next: Same Order, Up: Scarce 5606 5607Starting File 5608............. 5609 5610'--starting-file=NAME' 5611'-K NAME' 5612 Starts an operation in the middle of an archive. Use in 5613 conjunction with '--extract' ('--get', '-x') or '--list' ('-t'). 5614 5615 If a previous attempt to extract files failed due to lack of disk 5616space, you can use '--starting-file=NAME' ('-K NAME') to start 5617extracting only after member NAME of the archive. This assumes, of 5618course, that there is now free space, or that you are now extracting 5619into a different file system. (You could also choose to suspend 'tar', 5620remove unnecessary files from the file system, and then resume the same 5621'tar' operation. In this case, '--starting-file' is not necessary.) 5622See also *note interactive::, and *note exclude::. 5623 5624 5625File: tar.info, Node: Same Order, Prev: Starting File, Up: Scarce 5626 5627Same Order 5628.......... 5629 5630'--same-order' 5631'--preserve-order' 5632'-s' 5633 To process large lists of file names on machines with small amounts 5634 of memory. Use in conjunction with '--compare' ('--diff', '-d'), 5635 '--list' ('-t') or '--extract' ('--get', '-x'). 5636 5637 The '--same-order' ('--preserve-order', '-s') option tells 'tar' that 5638the list of file names to be listed or extracted is sorted in the same 5639order as the files in the archive. This allows a large list of names to 5640be used, even on a small machine that would not otherwise be able to 5641hold all the names in memory at the same time. Such a sorted list can 5642easily be created by running 'tar -t' on the archive and editing its 5643output. 5644 5645 This option is probably never needed on modern computer systems. 5646 5647 5648File: tar.info, Node: backup, Next: looking ahead, Prev: extract options, Up: operations 5649 56504.5 Backup options 5651================== 5652 5653GNU 'tar' offers options for making backups of files before writing new 5654versions. These options control the details of these backups. They may 5655apply to the archive itself before it is created or rewritten, as well 5656as individual extracted members. Other GNU programs ('cp', 'install', 5657'ln', and 'mv', for example) offer similar options. 5658 5659 Backup options may prove unexpectedly useful when extracting archives 5660containing many members having identical name, or when extracting 5661archives on systems having file name limitations, making different 5662members appear as having similar names through the side-effect of name 5663truncation. 5664 5665 When any existing file is backed up before being overwritten by 5666extraction, then clashing files are automatically be renamed to be 5667unique, and the true name is kept for only the last file of a series of 5668clashing files. By using verbose mode, users may track exactly what 5669happens. 5670 5671 At the detail level, some decisions are still experimental, and may 5672change in the future, we are waiting comments from our users. So, 5673please do not learn to depend blindly on the details of the backup 5674features. For example, currently, directories themselves are never 5675renamed through using these options, so, extracting a file over a 5676directory still has good chances to fail. Also, backup options apply to 5677created archives, not only to extracted members. For created archives, 5678backups will not be attempted when the archive is a block or character 5679device, or when it refers to a remote file. 5680 5681 For the sake of simplicity and efficiency, backups are made by 5682renaming old files prior to creation or extraction, and not by copying. 5683The original name is restored if the file creation fails. If a failure 5684occurs after a partial extraction of a file, both the backup and the 5685partially extracted file are kept. 5686 5687'--backup[=METHOD]' 5688 Back up files that are about to be overwritten or removed. Without 5689 this option, the original versions are destroyed. 5690 5691 Use METHOD to determine the type of backups made. If METHOD is not 5692 specified, use the value of the 'VERSION_CONTROL' environment 5693 variable. And if 'VERSION_CONTROL' is not set, use the 'existing' 5694 method. 5695 5696 This option corresponds to the Emacs variable 'version-control'; 5697 the same values for METHOD are accepted as in Emacs. This option 5698 also allows more descriptive names. The valid METHODs are: 5699 5700 't' 5701 'numbered' 5702 Always make numbered backups. 5703 5704 'nil' 5705 'existing' 5706 Make numbered backups of files that already have them, simple 5707 backups of the others. 5708 5709 'never' 5710 'simple' 5711 Always make simple backups. 5712 5713'--suffix=SUFFIX' 5714 Append SUFFIX to each backup file made with '--backup'. If this 5715 option is not specified, the value of the 'SIMPLE_BACKUP_SUFFIX' 5716 environment variable is used. And if 'SIMPLE_BACKUP_SUFFIX' is not 5717 set, the default is '~', just as in Emacs. 5718 5719 5720File: tar.info, Node: looking ahead, Prev: backup, Up: operations 5721 57224.6 Looking Ahead: The Rest of this Manual 5723========================================== 5724 5725You have now seen how to use all eight of the operations available to 5726'tar', and a number of the possible options. The next chapter explains 5727how to choose and change file and archive names, how to use files to 5728store names of other files which you can then call as arguments to 'tar' 5729(this can help you save time if you expect to archive the same list of 5730files a number of times), and so forth. 5731 5732 If there are too many files to conveniently list on the command line, 5733you can list the names in a file, and 'tar' will read that file. *Note 5734files::. 5735 5736 There are various ways of causing 'tar' to skip over some files, and 5737not archive them. *Note Choosing::. 5738 5739 5740File: tar.info, Node: Backups, Next: Choosing, Prev: operations, Up: Top 5741 57425 Performing Backups and Restoring Files 5743**************************************** 5744 5745GNU 'tar' is distributed along with the scripts for performing backups 5746and restores. Even if there is a good chance those scripts may be 5747satisfying to you, they are not the only scripts or methods available 5748for doing backups and restore. You may well create your own, or use 5749more sophisticated packages dedicated to that purpose. 5750 5751 Some users are enthusiastic about 'Amanda' (The Advanced Maryland 5752Automatic Network Disk Archiver), a backup system developed by James da 5753Silva 'jds@cs.umd.edu' and available on many Unix systems. This is free 5754software, and it is available from <http://www.amanda.org>. 5755 5756 This chapter documents both the provided shell scripts and 'tar' 5757options which are more specific to usage as a backup tool. 5758 5759 To "back up" a file system means to create archives that contain all 5760the files in that file system. Those archives can then be used to 5761restore any or all of those files (for instance if a disk crashes or a 5762file is accidentally deleted). File system "backups" are also called 5763"dumps". 5764 5765* Menu: 5766 5767* Full Dumps:: Using 'tar' to Perform Full Dumps 5768* Incremental Dumps:: Using 'tar' to Perform Incremental Dumps 5769* Backup Levels:: Levels of Backups 5770* Backup Parameters:: Setting Parameters for Backups and Restoration 5771* Scripted Backups:: Using the Backup Scripts 5772* Scripted Restoration:: Using the Restore Script 5773 5774 5775File: tar.info, Node: Full Dumps, Next: Incremental Dumps, Up: Backups 5776 57775.1 Using 'tar' to Perform Full Dumps 5778===================================== 5779 5780 _(This message will disappear, once this node revised.)_ 5781 5782 Full dumps should only be made when no other people or programs are 5783modifying files in the file system. If files are modified while 'tar' 5784is making the backup, they may not be stored properly in the archive, in 5785which case you won't be able to restore them if you have to. (Files not 5786being modified are written with no trouble, and do not corrupt the 5787entire archive.) 5788 5789 You will want to use the '--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL') 5790option to give the archive a volume label, so you can tell what this 5791archive is even if the label falls off the tape, or anything like that. 5792 5793 Unless the file system you are dumping is guaranteed to fit on one 5794volume, you will need to use the '--multi-volume' ('-M') option. Make 5795sure you have enough tapes on hand to complete the backup. 5796 5797 If you want to dump each file system separately you will need to use 5798the '--one-file-system' option to prevent 'tar' from crossing file 5799system boundaries when storing (sub)directories. 5800 5801 The '--incremental' ('-G') (*note Incremental Dumps::) option is not 5802needed, since this is a complete copy of everything in the file system, 5803and a full restore from this backup would only be done onto a completely 5804empty disk. 5805 5806 Unless you are in a hurry, and trust the 'tar' program (and your 5807tapes), it is a good idea to use the '--verify' ('-W') option, to make 5808sure your files really made it onto the dump properly. This will also 5809detect cases where the file was modified while (or just after) it was 5810being archived. Not all media (notably cartridge tapes) are capable of 5811being verified, unfortunately. 5812 5813 5814File: tar.info, Node: Incremental Dumps, Next: Backup Levels, Prev: Full Dumps, Up: Backups 5815 58165.2 Using 'tar' to Perform Incremental Dumps 5817============================================ 5818 5819"Incremental backup" is a special form of GNU 'tar' archive that stores 5820additional metadata so that exact state of the file system can be 5821restored when extracting the archive. 5822 5823 GNU 'tar' currently offers two options for handling incremental 5824backups: '--listed-incremental=SNAPSHOT-FILE' ('-g SNAPSHOT-FILE') and 5825'--incremental' ('-G'). 5826 5827 The option '--listed-incremental' instructs tar to operate on an 5828incremental archive with additional metadata stored in a standalone 5829file, called a "snapshot file". The purpose of this file is to help 5830determine which files have been changed, added or deleted since the last 5831backup, so that the next incremental backup will contain only modified 5832files. The name of the snapshot file is given as an argument to the 5833option: 5834 5835'--listed-incremental=FILE' 5836'-g FILE' 5837 Handle incremental backups with snapshot data in FILE. 5838 5839 To create an incremental backup, you would use '--listed-incremental' 5840together with '--create' (*note create::). For example: 5841 5842 $ tar --create \ 5843 --file=archive.1.tar \ 5844 --listed-incremental=/var/log/usr.snar \ 5845 /usr 5846 5847 This will create in 'archive.1.tar' an incremental backup of the 5848'/usr' file system, storing additional metadata in the file 5849'/var/log/usr.snar'. If this file does not exist, it will be created. 5850The created archive will then be a "level 0 backup"; please see the next 5851section for more on backup levels. 5852 5853 Otherwise, if the file '/var/log/usr.snar' exists, it determines 5854which files are modified. In this case only these files will be stored 5855in the archive. Suppose, for example, that after running the above 5856command, you delete file '/usr/doc/old' and create directory 5857'/usr/local/db' with the following contents: 5858 5859 $ ls /usr/local/db 5860 /usr/local/db/data 5861 /usr/local/db/index 5862 5863 Some time later you create another incremental backup. You will then 5864see: 5865 5866 $ tar --create \ 5867 --file=archive.2.tar \ 5868 --listed-incremental=/var/log/usr.snar \ 5869 /usr 5870 tar: usr/local/db: Directory is new 5871 usr/local/db/ 5872 usr/local/db/data 5873 usr/local/db/index 5874 5875The created archive 'archive.2.tar' will contain only these three 5876members. This archive is called a "level 1 backup". Notice that 5877'/var/log/usr.snar' will be updated with the new data, so if you plan to 5878create more 'level 1' backups, it is necessary to create a working copy 5879of the snapshot file before running 'tar'. The above example will then 5880be modified as follows: 5881 5882 $ cp /var/log/usr.snar /var/log/usr.snar-1 5883 $ tar --create \ 5884 --file=archive.2.tar \ 5885 --listed-incremental=/var/log/usr.snar-1 \ 5886 /usr 5887 5888 You can force 'level 0' backups either by removing the snapshot file 5889before running 'tar', or by supplying the '--level=0' option, e.g.: 5890 5891 $ tar --create \ 5892 --file=archive.2.tar \ 5893 --listed-incremental=/var/log/usr.snar-0 \ 5894 --level=0 \ 5895 /usr 5896 5897 Incremental dumps depend crucially on time stamps, so the results are 5898unreliable if you modify a file's time stamps during dumping (e.g., with 5899the '--atime-preserve=replace' option), or if you set the clock 5900backwards. 5901 5902 Metadata stored in snapshot files include device numbers, which, 5903obviously are supposed to be non-volatile values. However, it turns out 5904that NFS devices have undependable values when an automounter gets in 5905the picture. This can lead to a great deal of spurious redumping in 5906incremental dumps, so it is somewhat useless to compare two NFS devices 5907numbers over time. The solution implemented currently is to consider 5908all NFS devices as being equal when it comes to comparing directories; 5909this is fairly gross, but there does not seem to be a better way to go. 5910 5911 Apart from using NFS, there are a number of cases where relying on 5912device numbers can cause spurious redumping of unmodified files. For 5913example, this occurs when archiving LVM snapshot volumes. To avoid 5914this, use '--no-check-device' option: 5915 5916'--no-check-device' 5917 Do not rely on device numbers when preparing a list of changed 5918 files for an incremental dump. 5919 5920'--check-device' 5921 Use device numbers when preparing a list of changed files for an 5922 incremental dump. This is the default behavior. The purpose of 5923 this option is to undo the effect of the '--no-check-device' if it 5924 was given in 'TAR_OPTIONS' environment variable (*note 5925 TAR_OPTIONS::). 5926 5927 There is also another way to cope with changing device numbers. It 5928is described in detail in *note Fixing Snapshot Files::. 5929 5930 Note that incremental archives use 'tar' extensions and may not be 5931readable by non-GNU versions of the 'tar' program. 5932 5933 To extract from the incremental dumps, use '--listed-incremental' 5934together with '--extract' option (*note extracting files::). In this 5935case, 'tar' does not need to access snapshot file, since all the data 5936necessary for extraction are stored in the archive itself. So, when 5937extracting, you can give whatever argument to '--listed-incremental', 5938the usual practice is to use '--listed-incremental=/dev/null'. 5939Alternatively, you can use '--incremental', which needs no arguments. 5940In general, '--incremental' ('-G') can be used as a shortcut for 5941'--listed-incremental' when listing or extracting incremental backups 5942(for more information regarding this option, *note incremental-op::). 5943 5944 When extracting from the incremental backup GNU 'tar' attempts to 5945restore the exact state the file system had when the archive was 5946created. In particular, it will _delete_ those files in the file system 5947that did not exist in their directories when the archive was created. 5948If you have created several levels of incremental files, then in order 5949to restore the exact contents the file system had when the last level 5950was created, you will need to restore from all backups in turn. 5951Continuing our example, to restore the state of '/usr' file system, one 5952would do(1): 5953 5954 $ tar --extract \ 5955 --listed-incremental=/dev/null \ 5956 --file archive.1.tar 5957 $ tar --extract \ 5958 --listed-incremental=/dev/null \ 5959 --file archive.2.tar 5960 5961 To list the contents of an incremental archive, use '--list' (*note 5962list::), as usual. To obtain more information about the archive, use 5963'--listed-incremental' or '--incremental' combined with two '--verbose' 5964options(2): 5965 5966 tar --list --incremental --verbose --verbose --file archive.tar 5967 5968 This command will print, for each directory in the archive, the list 5969of files in that directory at the time the archive was created. This 5970information is put out in a format which is both human-readable and 5971unambiguous for a program: each file name is printed as 5972 5973 X FILE 5974 5975where X is a letter describing the status of the file: 'Y' if the file 5976is present in the archive, 'N' if the file is not included in the 5977archive, or a 'D' if the file is a directory (and is included in the 5978archive). *Note Dumpdir::, for the detailed description of dumpdirs and 5979status codes. Each such line is terminated by a newline character. The 5980last line is followed by an additional newline to indicate the end of 5981the data. 5982 5983 The option '--incremental' ('-G') gives the same behavior as 5984'--listed-incremental' when used with '--list' and '--extract' options. 5985When used with '--create' option, it creates an incremental archive 5986without creating snapshot file. Thus, it is impossible to create 5987several levels of incremental backups with '--incremental' option. 5988 5989 ---------- Footnotes ---------- 5990 5991 (1) Notice, that since both archives were created without '-P' option 5992(*note absolute::), these commands should be run from the root file 5993system. 5994 5995 (2) Two '--verbose' options were selected to avoid breaking usual 5996verbose listing output ('--list --verbose') when using in scripts. 5997 5998 Versions of GNU 'tar' up to 1.15.1 used to dump verbatim binary 5999contents of the DUMPDIR header (with terminating nulls) when 6000'--incremental' or '--listed-incremental' option was given, no matter 6001what the verbosity level. This behavior, and, especially, the binary 6002output it produced were considered inconvenient and were changed in 6003version 1.16. 6004 6005 6006File: tar.info, Node: Backup Levels, Next: Backup Parameters, Prev: Incremental Dumps, Up: Backups 6007 60085.3 Levels of Backups 6009===================== 6010 6011An archive containing all the files in the file system is called a "full 6012backup" or "full dump". You could insure your data by creating a full 6013dump every day. This strategy, however, would waste a substantial 6014amount of archive media and user time, as unchanged files are daily 6015re-archived. 6016 6017 It is more efficient to do a full dump only occasionally. To back up 6018files between full dumps, you can use "incremental dumps". A "level 6019one" dump archives all the files that have changed since the last full 6020dump. 6021 6022 A typical dump strategy would be to perform a full dump once a week, 6023and a level one dump once a day. This means some versions of files will 6024in fact be archived more than once, but this dump strategy makes it 6025possible to restore a file system to within one day of accuracy by only 6026extracting two archives--the last weekly (full) dump and the last daily 6027(level one) dump. The only information lost would be in files changed 6028or created since the last daily backup. (Doing dumps more than once a 6029day is usually not worth the trouble.) 6030 6031 GNU 'tar' comes with scripts you can use to do full and level-one 6032(actually, even level-two and so on) dumps. Using scripts (shell 6033programs) to perform backups and restoration is a convenient and 6034reliable alternative to typing out file name lists and 'tar' commands by 6035hand. 6036 6037 Before you use these scripts, you need to edit the file 6038'backup-specs', which specifies parameters used by the backup scripts 6039and by the restore script. This file is usually located in 6040'/etc/backup' directory. *Note Backup Parameters::, for its detailed 6041description. Once the backup parameters are set, you can perform 6042backups or restoration by running the appropriate script. 6043 6044 The name of the backup script is 'backup'. The name of the restore 6045script is 'restore'. The following sections describe their use in 6046detail. 6047 6048 _Please Note:_ The backup and restoration scripts are designed to be 6049used together. While it is possible to restore files by hand from an 6050archive which was created using a backup script, and to create an 6051archive by hand which could then be extracted using the restore script, 6052it is easier to use the scripts. *Note Incremental Dumps::, before 6053making such an attempt. 6054 6055 6056File: tar.info, Node: Backup Parameters, Next: Scripted Backups, Prev: Backup Levels, Up: Backups 6057 60585.4 Setting Parameters for Backups and Restoration 6059================================================== 6060 6061The file 'backup-specs' specifies backup parameters for the backup and 6062restoration scripts provided with 'tar'. You must edit 'backup-specs' 6063to fit your system configuration and schedule before using these 6064scripts. 6065 6066 Syntactically, 'backup-specs' is a shell script, containing mainly 6067variable assignments. However, any valid shell construct is allowed in 6068this file. Particularly, you may wish to define functions within that 6069script (e.g., see 'RESTORE_BEGIN' below). For more information about 6070shell script syntax, please refer to the definition of the Shell Command 6071Language 6072(http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta 6073g_02). See also *note Bash Features: (bashref)Top. 6074 6075 The shell variables controlling behavior of 'backup' and 'restore' 6076are described in the following subsections. 6077 6078* Menu: 6079 6080* General-Purpose Variables:: 6081* Magnetic Tape Control:: 6082* User Hooks:: 6083* backup-specs example:: An Example Text of 'Backup-specs' 6084 6085 6086File: tar.info, Node: General-Purpose Variables, Next: Magnetic Tape Control, Up: Backup Parameters 6087 60885.4.1 General-Purpose Variables 6089------------------------------- 6090 6091 -- Backup variable: ADMINISTRATOR 6092 The user name of the backup administrator. 'Backup' scripts sends 6093 a backup report to this address. 6094 6095 -- Backup variable: BACKUP_HOUR 6096 The hour at which the backups are done. This can be a number from 6097 0 to 23, or the time specification in form HOURS:MINUTES, or the 6098 string 'now'. 6099 6100 This variable is used by 'backup'. Its value may be overridden 6101 using '--time' option (*note Scripted Backups::). 6102 6103 -- Backup variable: TAPE_FILE 6104 6105 The device 'tar' writes the archive to. If TAPE_FILE is a remote 6106 archive (*note remote-dev::), backup script will suppose that your 6107 'mt' is able to access remote devices. If RSH (*note RSH::) is 6108 set, '--rsh-command' option will be added to invocations of 'mt'. 6109 6110 -- Backup variable: BLOCKING 6111 6112 The blocking factor 'tar' will use when writing the dump archive. 6113 *Note Blocking Factor::. 6114 6115 -- Backup variable: BACKUP_DIRS 6116 6117 A list of file systems to be dumped (for 'backup'), or restored 6118 (for 'restore'). You can include any directory name in the list -- 6119 subdirectories on that file system will be included, regardless of 6120 how they may look to other networked machines. Subdirectories on 6121 other file systems will be ignored. 6122 6123 The host name specifies which host to run 'tar' on, and should 6124 normally be the host that actually contains the file system. 6125 However, the host machine must have GNU 'tar' installed, and must 6126 be able to access the directory containing the backup scripts and 6127 their support files using the same file name that is used on the 6128 machine where the scripts are run (i.e., what 'pwd' will print when 6129 in that directory on that machine). If the host that contains the 6130 file system does not have this capability, you can specify another 6131 host as long as it can access the file system through NFS. 6132 6133 If the list of file systems is very long you may wish to put it in 6134 a separate file. This file is usually named '/etc/backup/dirs', 6135 but this name may be overridden in 'backup-specs' using 'DIRLIST' 6136 variable. 6137 6138 -- Backup variable: DIRLIST 6139 6140 The name of the file that contains a list of file systems to backup 6141 or restore. By default it is '/etc/backup/dirs'. 6142 6143 -- Backup variable: BACKUP_FILES 6144 6145 A list of individual files to be dumped (for 'backup'), or restored 6146 (for 'restore'). These should be accessible from the machine on 6147 which the backup script is run. 6148 6149 If the list of individual files is very long you may wish to store 6150 it in a separate file. This file is usually named 6151 '/etc/backup/files', but this name may be overridden in 6152 'backup-specs' using 'FILELIST' variable. 6153 6154 -- Backup variable: FILELIST 6155 6156 The name of the file that contains a list of individual files to 6157 backup or restore. By default it is '/etc/backup/files'. 6158 6159 -- Backup variable: MT 6160 6161 Full file name of 'mt' binary. 6162 6163 -- Backup variable: RSH 6164 Full file name of 'rsh' binary or its equivalent. You may wish to 6165 set it to 'ssh', to improve security. In this case you will have 6166 to use public key authentication. 6167 6168 -- Backup variable: RSH_COMMAND 6169 6170 Full file name of 'rsh' binary on remote machines. This will be 6171 passed via '--rsh-command' option to the remote invocation of GNU 6172 'tar'. 6173 6174 -- Backup variable: VOLNO_FILE 6175 6176 Name of temporary file to hold volume numbers. This needs to be 6177 accessible by all the machines which have file systems to be 6178 dumped. 6179 6180 -- Backup variable: XLIST 6181 6182 Name of "exclude file list". An "exclude file list" is a file 6183 located on the remote machine and containing the list of files to 6184 be excluded from the backup. Exclude file lists are searched in 6185 /etc/tar-backup directory. A common use for exclude file lists is 6186 to exclude files containing security-sensitive information (e.g., 6187 '/etc/shadow' from backups). 6188 6189 This variable affects only 'backup'. 6190 6191 -- Backup variable: SLEEP_TIME 6192 6193 Time to sleep between dumps of any two successive file systems 6194 6195 This variable affects only 'backup'. 6196 6197 -- Backup variable: DUMP_REMIND_SCRIPT 6198 6199 Script to be run when it's time to insert a new tape in for the 6200 next volume. Administrators may want to tailor this script for 6201 their site. If this variable isn't set, GNU 'tar' will display its 6202 built-in prompt, and will expect confirmation from the console. 6203 For the description of the default prompt, see *note change volume 6204 prompt::. 6205 6206 -- Backup variable: SLEEP_MESSAGE 6207 6208 Message to display on the terminal while waiting for dump time. 6209 Usually this will just be some literal text. 6210 6211 -- Backup variable: TAR 6212 6213 Full file name of the GNU 'tar' executable. If this is not set, 6214 backup scripts will search 'tar' in the current shell path. 6215 6216 6217File: tar.info, Node: Magnetic Tape Control, Next: User Hooks, Prev: General-Purpose Variables, Up: Backup Parameters 6218 62195.4.2 Magnetic Tape Control 6220--------------------------- 6221 6222Backup scripts access tape device using special "hook functions". These 6223functions take a single argument -- the name of the tape device. Their 6224names are kept in the following variables: 6225 6226 -- Backup variable: MT_BEGIN 6227 The name of "begin" function. This function is called before 6228 accessing the drive. By default it retensions the tape: 6229 6230 MT_BEGIN=mt_begin 6231 6232 mt_begin() { 6233 mt -f "$1" retension 6234 } 6235 6236 -- Backup variable: MT_REWIND 6237 The name of "rewind" function. The default definition is as 6238 follows: 6239 6240 MT_REWIND=mt_rewind 6241 6242 mt_rewind() { 6243 mt -f "$1" rewind 6244 } 6245 6246 -- Backup variable: MT_OFFLINE 6247 The name of the function switching the tape off line. By default 6248 it is defined as follows: 6249 6250 MT_OFFLINE=mt_offline 6251 6252 mt_offline() { 6253 mt -f "$1" offl 6254 } 6255 6256 -- Backup variable: MT_STATUS 6257 The name of the function used to obtain the status of the archive 6258 device, including error count. Default definition: 6259 6260 MT_STATUS=mt_status 6261 6262 mt_status() { 6263 mt -f "$1" status 6264 } 6265 6266 6267File: tar.info, Node: User Hooks, Next: backup-specs example, Prev: Magnetic Tape Control, Up: Backup Parameters 6268 62695.4.3 User Hooks 6270---------------- 6271 6272"User hooks" are shell functions executed before and after each 'tar' 6273invocation. Thus, there are "backup hooks", which are executed before 6274and after dumping each file system, and "restore hooks", executed before 6275and after restoring a file system. Each user hook is a shell function 6276taking four arguments: 6277 6278 -- User Hook Function: hook LEVEL HOST FS FSNAME 6279 Its arguments are: 6280 6281 LEVEL 6282 Current backup or restore level. 6283 6284 HOST 6285 Name or IP address of the host machine being dumped or 6286 restored. 6287 6288 FS 6289 Full file name of the file system being dumped or restored. 6290 6291 FSNAME 6292 File system name with directory separators replaced with 6293 colons. This is useful, e.g., for creating unique files. 6294 6295 Following variables keep the names of user hook functions: 6296 6297 -- Backup variable: DUMP_BEGIN 6298 Dump begin function. It is executed before dumping the file 6299 system. 6300 6301 -- Backup variable: DUMP_END 6302 Executed after dumping the file system. 6303 6304 -- Backup variable: RESTORE_BEGIN 6305 Executed before restoring the file system. 6306 6307 -- Backup variable: RESTORE_END 6308 Executed after restoring the file system. 6309 6310 6311File: tar.info, Node: backup-specs example, Prev: User Hooks, Up: Backup Parameters 6312 63135.4.4 An Example Text of 'Backup-specs' 6314--------------------------------------- 6315 6316The following is an example of 'backup-specs': 6317 6318 # site-specific parameters for file system backup. 6319 6320 ADMINISTRATOR=friedman 6321 BACKUP_HOUR=1 6322 TAPE_FILE=/dev/nrsmt0 6323 6324 # Use ssh instead of the less secure rsh 6325 RSH=/usr/bin/ssh 6326 RSH_COMMAND=/usr/bin/ssh 6327 6328 # Override MT_STATUS function: 6329 my_status() { 6330 mts -t $TAPE_FILE 6331 } 6332 MT_STATUS=my_status 6333 6334 # Disable MT_OFFLINE function 6335 MT_OFFLINE=: 6336 6337 BLOCKING=124 6338 BACKUP_DIRS=" 6339 albert:/fs/fsf 6340 apple-gunkies:/gd 6341 albert:/fs/gd2 6342 albert:/fs/gp 6343 geech:/usr/jla 6344 churchy:/usr/roland 6345 albert:/ 6346 albert:/usr 6347 apple-gunkies:/ 6348 apple-gunkies:/usr 6349 gnu:/hack 6350 gnu:/u 6351 apple-gunkies:/com/mailer/gnu 6352 apple-gunkies:/com/archive/gnu" 6353 6354 BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]" 6355 6356 6357 6358File: tar.info, Node: Scripted Backups, Next: Scripted Restoration, Prev: Backup Parameters, Up: Backups 6359 63605.5 Using the Backup Scripts 6361============================ 6362 6363The syntax for running a backup script is: 6364 6365 backup --level=LEVEL --time=TIME 6366 6367 The '--level' option requests the dump level. Thus, to produce a 6368full dump, specify '--level=0' (this is the default, so '--level' may be 6369omitted if its value is '0')(1). 6370 6371 The '--time' option determines when should the backup be run. TIME 6372may take three forms: 6373 6374HH:MM 6375 6376 The dump must be run at HH hours MM minutes. 6377 6378HH 6379 6380 The dump must be run at HH hours. 6381 6382now 6383 6384 The dump must be run immediately. 6385 6386 You should start a script with a tape or disk mounted. Once you 6387start a script, it prompts you for new tapes or disks as it needs them. 6388Media volumes don't have to correspond to archive files -- a 6389multi-volume archive can be started in the middle of a tape that already 6390contains the end of another multi-volume archive. The 'restore' script 6391prompts for media by its archive volume, so to avoid an error message 6392you should keep track of which tape (or disk) contains which volume of 6393the archive (*note Scripted Restoration::). 6394 6395 The backup scripts write two files on the file system. The first is 6396a record file in '/etc/tar-backup/', which is used by the scripts to 6397store and retrieve information about which files were dumped. This file 6398is not meant to be read by humans, and should not be deleted by them. 6399*Note Snapshot Files::, for a more detailed explanation of this file. 6400 6401 The second file is a log file containing the names of the file 6402systems and files dumped, what time the backup was made, and any error 6403messages that were generated, as well as how much space was left in the 6404media volume after the last volume of the archive was written. You 6405should check this log file after every backup. The file name is 6406'log-MM-DD-YYYY-level-N', where MM-DD-YYYY represents current date, and 6407N represents current dump level number. 6408 6409 The script also prints the name of each system being dumped to the 6410standard output. 6411 6412 Following is the full list of options accepted by 'backup' script: 6413 6414'-l LEVEL' 6415'--level=LEVEL' 6416 Do backup level LEVEL (default 0). 6417 6418'-f' 6419'--force' 6420 Force backup even if today's log file already exists. 6421 6422'-v[LEVEL]' 6423'--verbose[=LEVEL]' 6424 Set verbosity level. The higher the level is, the more debugging 6425 information will be output during execution. Default LEVEL is 100, 6426 which means the highest debugging level. 6427 6428'-t START-TIME' 6429'--time=START-TIME' 6430 Wait till TIME, then do backup. 6431 6432'-h' 6433'--help' 6434 Display short help message and exit. 6435 6436'-V' 6437'--version' 6438 Display information about the program's name, version, origin and 6439 legal status, all on standard output, and then exit successfully. 6440 6441 ---------- Footnotes ---------- 6442 6443 (1) For backward compatibility, the 'backup' will also try to deduce 6444the requested dump level from the name of the script itself. If the 6445name consists of a string 'level-' followed by a single decimal digit, 6446that digit is taken as the dump level number. Thus, you may create a 6447link from 'backup' to 'level-1' and then run 'level-1' whenever you need 6448to create a level one dump. 6449 6450 6451File: tar.info, Node: Scripted Restoration, Prev: Scripted Backups, Up: Backups 6452 64535.6 Using the Restore Script 6454============================ 6455 6456To restore files that were archived using a scripted backup, use the 6457'restore' script. Its usage is quite straightforward. In the simplest 6458form, invoke 'restore --all', it will then restore all the file systems 6459and files specified in 'backup-specs' (*note BACKUP_DIRS: 6460General-Purpose Variables.). 6461 6462 You may select the file systems (and/or files) to restore by giving 6463'restore' a list of "patterns" in its command line. For example, 6464running 6465 6466 restore 'albert:*' 6467 6468will restore all file systems on the machine 'albert'. A more 6469complicated example: 6470 6471 restore 'albert:*' '*:/var' 6472 6473This command will restore all file systems on the machine 'albert' as 6474well as '/var' file system on all machines. 6475 6476 By default 'restore' will start restoring files from the lowest 6477available dump level (usually zero) and will continue through all 6478available dump levels. There may be situations where such a thorough 6479restore is not necessary. For example, you may wish to restore only 6480files from the recent level one backup. To do so, use '--level' option, 6481as shown in the example below: 6482 6483 restore --level=1 6484 6485 The full list of options accepted by 'restore' follows: 6486 6487'-a' 6488'--all' 6489 Restore all file systems and files specified in 'backup-specs'. 6490 6491'-l LEVEL' 6492'--level=LEVEL' 6493 Start restoring from the given backup level, instead of the default 6494 0. 6495 6496'-v[LEVEL]' 6497'--verbose[=LEVEL]' 6498 Set verbosity level. The higher the level is, the more debugging 6499 information will be output during execution. Default LEVEL is 100, 6500 which means the highest debugging level. 6501 6502'-h' 6503'--help' 6504 Display short help message and exit. 6505 6506'-V' 6507'--version' 6508 Display information about the program's name, version, origin and 6509 legal status, all on standard output, and then exit successfully. 6510 6511 You should start the restore script with the media containing the 6512first volume of the archive mounted. The script will prompt for other 6513volumes as they are needed. If the archive is on tape, you don't need 6514to rewind the tape to to its beginning--if the tape head is positioned 6515past the beginning of the archive, the script will rewind the tape as 6516needed. *Note Tape Positioning::, for a discussion of tape positioning. 6517 6518 *Warning:* The script will delete files from the active file system 6519 if they were not in the file system when the archive was made. 6520 6521 *Note Incremental Dumps::, for an explanation of how the script makes 6522that determination. 6523 6524 6525File: tar.info, Node: Choosing, Next: Date input formats, Prev: Backups, Up: Top 6526 65276 Choosing Files and Names for 'tar' 6528************************************ 6529 6530Certain options to 'tar' enable you to specify a name for your archive. 6531Other options let you decide which files to include or exclude from the 6532archive, based on when or whether files were modified, whether the file 6533names do or don't match specified patterns, or whether files are in 6534specified directories. 6535 6536 This chapter discusses these options in detail. 6537 6538* Menu: 6539 6540* file:: Choosing the Archive's Name 6541* Selecting Archive Members:: 6542* files:: Reading Names from a File 6543* exclude:: Excluding Some Files 6544* wildcards:: Wildcards Patterns and Matching 6545* quoting styles:: Ways of Quoting Special Characters in Names 6546* transform:: Modifying File and Member Names 6547* after:: Operating Only on New Files 6548* recurse:: Descending into Directories 6549* one:: Crossing File System Boundaries 6550 6551 6552File: tar.info, Node: file, Next: Selecting Archive Members, Up: Choosing 6553 65546.1 Choosing and Naming Archive Files 6555===================================== 6556 6557By default, 'tar' uses an archive file name that was compiled when it 6558was built on the system; usually this name refers to some physical tape 6559drive on the machine. However, the person who installed 'tar' on the 6560system may not have set the default to a meaningful value as far as most 6561users are concerned. As a result, you will usually want to tell 'tar' 6562where to find (or create) the archive. The '--file=ARCHIVE-NAME' ('-f 6563ARCHIVE-NAME') option allows you to either specify or name a file to use 6564as the archive instead of the default archive file location. 6565 6566'--file=ARCHIVE-NAME' 6567'-f ARCHIVE-NAME' 6568 Name the archive to create or operate on. Use in conjunction with 6569 any operation. 6570 6571 For example, in this 'tar' command, 6572 6573 $ tar -cvf collection.tar blues folk jazz 6574 6575'collection.tar' is the name of the archive. It must directly follow 6576the '-f' option, since whatever directly follows '-f' _will_ end up 6577naming the archive. If you neglect to specify an archive name, you may 6578end up overwriting a file in the working directory with the archive you 6579create since 'tar' will use this file's name for the archive name. 6580 6581 An archive can be saved as a file in the file system, sent through a 6582pipe or over a network, or written to an I/O device such as a tape, 6583floppy disk, or CD write drive. 6584 6585 If you do not name the archive, 'tar' uses the value of the 6586environment variable 'TAPE' as the file name for the archive. If that 6587is not available, 'tar' uses a default, compiled-in archive name, 6588usually that for tape unit zero (i.e., '/dev/tu00'). 6589 6590 If you use '-' as an ARCHIVE-NAME, 'tar' reads the archive from 6591standard input (when listing or extracting files), or writes it to 6592standard output (when creating an archive). If you use '-' as an 6593ARCHIVE-NAME when modifying an archive, 'tar' reads the original archive 6594from its standard input and writes the entire new archive to its 6595standard output. 6596 6597 The following example is a convenient way of copying directory 6598hierarchy from 'sourcedir' to 'targetdir'. 6599 6600 $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -) 6601 6602 The '-C' option allows to avoid using subshells: 6603 6604 $ tar -C sourcedir -cf - . | tar -C targetdir -xpf - 6605 6606 In both examples above, the leftmost 'tar' invocation archives the 6607contents of 'sourcedir' to the standard output, while the rightmost one 6608reads this archive from its standard input and extracts it. The '-p' 6609option tells it to restore permissions of the extracted files. 6610 6611 To specify an archive file on a device attached to a remote machine, 6612use the following: 6613 6614 --file=HOSTNAME:/DEV/FILE-NAME 6615 6616'tar' will set up the remote connection, if possible, and prompt you for 6617a username and password. If you use '--file=@HOSTNAME:/DEV/FILE-NAME', 6618'tar' will attempt to set up the remote connection using your username 6619as the username on the remote machine. 6620 6621 If the archive file name includes a colon (':'), then it is assumed 6622to be a file on another machine. If the archive file is 6623'USER@HOST:FILE', then FILE is used on the host HOST. The remote host 6624is accessed using the 'rsh' program, with a username of USER. If the 6625username is omitted (along with the '@' sign), then your user name will 6626be used. (This is the normal 'rsh' behavior.) It is necessary for the 6627remote machine, in addition to permitting your 'rsh' access, to have the 6628'rmt' program installed (this command is included in the GNU 'tar' 6629distribution and by default is installed under 'PREFIX/libexec/rmt', 6630where PREFIX means your installation prefix). If you need to use a file 6631whose name includes a colon, then the remote tape drive behavior can be 6632inhibited by using the '--force-local' option. 6633 6634 When the archive is being created to '/dev/null', GNU 'tar' tries to 6635minimize input and output operations. The Amanda backup system, when 6636used with GNU 'tar', has an initial sizing pass which uses this feature. 6637 6638 6639File: tar.info, Node: Selecting Archive Members, Next: files, Prev: file, Up: Choosing 6640 66416.2 Selecting Archive Members 6642============================= 6643 6644"File Name arguments" specify which files in the file system 'tar' 6645operates on, when creating or adding to an archive, or which archive 6646members 'tar' operates on, when reading or deleting from an archive. 6647*Note Operations::. 6648 6649 To specify file names, you can include them as the last arguments on 6650the command line, as follows: 6651 tar OPERATION [OPTION1 OPTION2 ...] [FILE NAME-1 FILE NAME-2 ...] 6652 6653 If a file name begins with dash ('-'), precede it with '--add-file' 6654option to prevent it from being treated as an option. 6655 6656 By default GNU 'tar' attempts to "unquote" each file or member name, 6657replacing "escape sequences" according to the following table: 6658 6659Escape Replaced with 6660----------------------------------------------------------- 6661\a Audible bell (ASCII 7) 6662\b Backspace (ASCII 8) 6663\f Form feed (ASCII 12) 6664\n New line (ASCII 10) 6665\r Carriage return (ASCII 13) 6666\t Horizontal tabulation (ASCII 9) 6667\v Vertical tabulation (ASCII 11) 6668\? ASCII 127 6669\N ASCII N (N should be an octal number of 6670 up to 3 digits) 6671 6672 A backslash followed by any other symbol is retained. 6673 6674 This default behavior is controlled by the following command line 6675option: 6676 6677'--unquote' 6678 Enable unquoting input file or member names (default). 6679 6680'--no-unquote' 6681 Disable unquoting input file or member names. 6682 6683 If you specify a directory name as a file name argument, all the 6684files in that directory are operated on by 'tar'. 6685 6686 If you do not specify files, 'tar' behavior differs depending on the 6687operation mode as described below: 6688 6689 When 'tar' is invoked with '--create' ('-c'), 'tar' will stop 6690immediately, reporting the following: 6691 6692 $ tar cf a.tar 6693 tar: Cowardly refusing to create an empty archive 6694 Try 'tar --help' or 'tar --usage' for more information. 6695 6696 If you specify either '--list' ('-t') or '--extract' ('--get', '-x'), 6697'tar' operates on all the archive members in the archive. 6698 6699 If run with '--diff' option, tar will compare the archive with the 6700contents of the current working directory. 6701 6702 If you specify any other operation, 'tar' does nothing. 6703 6704 By default, 'tar' takes file names from the command line. However, 6705there are other ways to specify file or member names, or to modify the 6706manner in which 'tar' selects the files or members upon which to 6707operate. In general, these methods work both for specifying the names 6708of files and archive members. 6709 6710 6711File: tar.info, Node: files, Next: exclude, Prev: Selecting Archive Members, Up: Choosing 6712 67136.3 Reading Names from a File 6714============================= 6715 6716Instead of giving the names of files or archive members on the command 6717line, you can put the names into a file, and then use the 6718'--files-from=FILE-OF-NAMES' ('-T FILE-OF-NAMES') option to 'tar'. Give 6719the name of the file which contains the list of files to include as the 6720argument to '--files-from'. In the list, the file names should be 6721separated by newlines. You will frequently use this option when you 6722have generated the list of files to archive with the 'find' utility. 6723 6724'--files-from=FILE-NAME' 6725'-T FILE-NAME' 6726 Get names to extract or create from file FILE-NAME. 6727 6728 If you give a single dash as a file name for '--files-from', (i.e., 6729you specify either '--files-from=-' or '-T -'), then the file names are 6730read from standard input. 6731 6732 Unless you are running 'tar' with '--create', you cannot use both 6733'--files-from=-' and '--file=-' ('-f -') in the same command. 6734 6735 Any number of '-T' options can be given in the command line. 6736 6737 The following example shows how to use 'find' to generate a list of 6738files smaller than 400K in length and put that list into a file called 6739'small-files'. You can then use the '-T' option to 'tar' to specify the 6740files from that file, 'small-files', to create the archive 'little.tgz'. 6741(The '-z' option to 'tar' compresses the archive with 'gzip'; *note 6742gzip:: for more information.) 6743 6744 $ find . -size -400 -print > small-files 6745 $ tar -c -v -z -T small-files -f little.tgz 6746 6747By default, each line read from the file list is first stripped off any 6748leading and trailing whitespace. If the resulting string begins with 6749'-' character, it is considered a 'tar' option and is processed 6750accordingly(1). Only a subset of GNU 'tar' options is allowed for use 6751in file lists. For a list of such options, *note Position-Sensitive 6752Options::. 6753 6754 For example, the common use of this feature is to change to another 6755directory by specifying '-C' option: 6756 6757 $ cat list 6758 -C/etc 6759 passwd 6760 hosts 6761 -C/lib 6762 libc.a 6763 $ tar -c -f foo.tar --files-from list 6764 6765In this example, 'tar' will first switch to '/etc' directory and add 6766files 'passwd' and 'hosts' to the archive. Then it will change to 6767'/lib' directory and will archive the file 'libc.a'. Thus, the 6768resulting archive 'foo.tar' will contain: 6769 6770 $ tar tf foo.tar 6771 passwd 6772 hosts 6773 libc.a 6774 6775 Note, that any options used in the file list remain in effect for the 6776rest of the command line. For example, using the same 'list' file as 6777above, the following command 6778 6779 $ tar -c -f foo.tar --files-from list libcurses.a 6780 6781will look for file 'libcurses.a' in the directory '/lib', because it was 6782used with the last '-C' option (*note Position-Sensitive Options::). 6783 6784 If such option handling is undesirable, use the 6785'--verbatim-files-from' option. When this option is in effect, each 6786line read from the file list is treated as a file name. Notice, that 6787this means, in particular, that no whitespace trimming is performed. 6788 6789 The '--verbatim-files-from' affects all '-T' options that follow it 6790in the command line. The default behavior can be restored using 6791'--no-verbatim-files-from' option. 6792 6793 To disable option handling for a single file name, use the 6794'--add-file' option, e.g.: '--add-file=--my-file'. 6795 6796 You can use any GNU 'tar' command line options in the file list file, 6797including '--files-from' option itself. This allows for including 6798contents of a file list into another file list file. Note however, that 6799options that control file list processing, such as 6800'--verbatim-files-from' or '--null' won't affect the file they appear 6801in. They will affect next '--files-from' option, if there is any. 6802 6803* Menu: 6804 6805* nul:: 6806 6807 ---------- Footnotes ---------- 6808 6809 (1) Versions of GNU 'tar' up to 1.15.1 recognized only '-C' option in 6810file lists, and only if the option and its argument occupied two 6811consecutive lines. 6812 6813 6814File: tar.info, Node: nul, Up: files 6815 68166.3.1 'NUL'-Terminated File Names 6817--------------------------------- 6818 6819The '--null' option causes '--files-from=FILE-OF-NAMES' ('-T 6820FILE-OF-NAMES') to read file names terminated by a 'NUL' instead of a 6821newline, so files whose names contain newlines can be archived using 6822'--files-from'. 6823 6824'--null' 6825 Only consider 'NUL'-terminated file names, instead of files that 6826 terminate in a newline. 6827 6828'--no-null' 6829 Undo the effect of any previous '--null' option. 6830 6831 The '--null' option is just like the one in GNU 'xargs' and 'cpio', 6832and is useful with the '-print0' predicate of GNU 'find'. In 'tar', 6833'--null' also disables special handling for file names that begin with 6834dash (similar to '--verbatim-files-from' option). 6835 6836 This example shows how to use 'find' to generate a list of files 6837larger than 800K in length and put that list into a file called 6838'long-files'. The '-print0' option to 'find' is just like '-print', 6839except that it separates files with a 'NUL' rather than with a newline. 6840You can then run 'tar' with both the '--null' and '-T' options to 6841specify that 'tar' gets the files from that file, 'long-files', to 6842create the archive 'big.tgz'. The '--null' option to 'tar' will cause 6843'tar' to recognize the 'NUL' separator between files. 6844 6845 $ find . -size +800 -print0 > long-files 6846 $ tar -c -v --null --files-from=long-files --file=big.tar 6847 6848 The '--no-null' option can be used if you need to read both 6849'NUL'-terminated and newline-terminated files on the same command line. 6850For example, if 'flist' is a newline-terminated file, then the following 6851command can be used to combine it with the above command: 6852 6853 $ find . -size +800 -print0 | 6854 tar -c -f big.tar --null -T - --no-null -T flist 6855 6856 This example uses short options for typographic reasons, to avoid 6857very long lines. 6858 6859 GNU 'tar' is tries to automatically detect 'NUL'-terminated file 6860lists, so in many cases it is safe to use them even without the '--null' 6861option. In this case 'tar' will print a warning and continue reading 6862such a file as if '--null' were actually given: 6863 6864 $ find . -size +800 -print0 | tar -c -f big.tar -T - 6865 tar: -: file name read contains nul character 6866 6867 The null terminator, however, remains in effect only for this 6868particular file, any following '-T' options will assume newline 6869termination. Of course, the null autodetection applies to these 6870eventual surplus '-T' options as well. 6871 6872 6873File: tar.info, Node: exclude, Next: wildcards, Prev: files, Up: Choosing 6874 68756.4 Excluding Some Files 6876======================== 6877 6878To avoid operating on files whose names match a particular pattern, use 6879the '--exclude' or '--exclude-from' options. 6880 6881'--exclude=PATTERN' 6882 Causes 'tar' to ignore files that match the PATTERN. 6883 6884 The '--exclude=PATTERN' option prevents any file or member whose name 6885matches the shell wildcard (PATTERN) from being operated on. For 6886example, to create an archive with all the contents of the directory 6887'src' except for files whose names end in '.o', use the command 'tar -cf 6888src.tar --exclude='*.o' src'. 6889 6890 You may give multiple '--exclude' options. 6891 6892'--exclude-from=FILE' 6893'-X FILE' 6894 Causes 'tar' to ignore files that match the patterns listed in 6895 FILE. 6896 6897 Use the '--exclude-from' option to read a list of patterns, one per 6898line, from FILE; 'tar' will ignore files matching those patterns. Thus 6899if 'tar' is called as 'tar -c -X foo .' and the file 'foo' contains a 6900single line '*.o', no files whose names end in '.o' will be added to the 6901archive. 6902 6903 Notice, that lines from FILE are read verbatim. One of the frequent 6904errors is leaving some extra whitespace after a file name, which is 6905difficult to catch using text editors. 6906 6907 However, empty lines are OK. 6908 6909 When archiving directories that are under some version control system 6910(VCS), it is often convenient to read exclusion patterns from this VCS' 6911ignore files (e.g. '.cvsignore', '.gitignore', etc.) The following 6912options provide such possibility: 6913 6914'--exclude-vcs-ignores' 6915 Before archiving a directory, see if it contains any of the 6916 following files: 'cvsignore', '.gitignore', '.bzrignore', or 6917 '.hgignore'. If so, read ignore patterns from these files. 6918 6919 The patterns are treated much as the corresponding VCS would treat 6920 them, i.e.: 6921 6922 '.cvsignore' 6923 Contains shell-style globbing patterns that apply only to the 6924 directory where this file resides. No comments are allowed in 6925 the file. Empty lines are ignored. 6926 6927 '.gitignore' 6928 Contains shell-style globbing patterns. Applies to the 6929 directory where '.gitfile' is located and all its 6930 subdirectories. 6931 6932 Any line beginning with a '#' is a comment. Backslash escapes 6933 the comment character. 6934 6935 '.bzrignore' 6936 Contains shell globbing-patterns and regular expressions (if 6937 prefixed with 'RE:'(1). Patterns affect the directory and all 6938 its subdirectories. 6939 6940 Any line beginning with a '#' is a comment. 6941 6942 '.hgignore' 6943 Contains posix regular expressions(2). The line 'syntax: 6944 glob' switches to shell globbing patterns. The line 'syntax: 6945 regexp' switches back. Comments begin with a '#'. Patterns 6946 affect the directory and all its subdirectories. 6947 6948'--exclude-ignore=FILE' 6949 Before dumping a directory, 'tar' checks if it contains FILE. If 6950 so, exclusion patterns are read from this file. The patterns 6951 affect only the directory itself. 6952 6953'--exclude-ignore-recursive=FILE' 6954 Same as '--exclude-ignore', except that the patterns read affect 6955 both the directory where FILE resides and all its subdirectories. 6956 6957'--exclude-vcs' 6958 Exclude files and directories used by following version control 6959 systems: 'CVS', 'RCS', 'SCCS', 'SVN', 'Arch', 'Bazaar', 6960 'Mercurial', and 'Darcs'. 6961 6962 As of version 1.34, the following files are excluded: 6963 6964 * 'CVS/', and everything under it 6965 * 'RCS/', and everything under it 6966 * 'SCCS/', and everything under it 6967 * '.git/', and everything under it 6968 * '.gitignore' 6969 * '.gitmodules' 6970 * '.gitattributes' 6971 * '.cvsignore' 6972 * '.svn/', and everything under it 6973 * '.arch-ids/', and everything under it 6974 * '{arch}/', and everything under it 6975 * '=RELEASE-ID' 6976 * '=meta-update' 6977 * '=update' 6978 * '.bzr' 6979 * '.bzrignore' 6980 * '.bzrtags' 6981 * '.hg' 6982 * '.hgignore' 6983 * '.hgrags' 6984 * '_darcs' 6985 6986'--exclude-backups' 6987 Exclude backup and lock files. This option causes exclusion of 6988 files that match the following shell globbing patterns: 6989 6990 .#* 6991 *~ 6992 #*# 6993 6994 When creating an archive, the '--exclude-caches' option family causes 6995'tar' to exclude all directories that contain a "cache directory tag". 6996A cache directory tag is a short file with the well-known name 6997'CACHEDIR.TAG' and having a standard header specified in 6998<http://www.brynosaurus.com/cachedir/spec.html>. Various applications 6999write cache directory tags into directories they use to hold 7000regenerable, non-precious data, so that such data can be more easily 7001excluded from backups. 7002 7003 There are three 'exclude-caches' options, each providing a different 7004exclusion semantics: 7005 7006'--exclude-caches' 7007 Do not archive the contents of the directory, but archive the 7008 directory itself and the 'CACHEDIR.TAG' file. 7009 7010'--exclude-caches-under' 7011 Do not archive the contents of the directory, nor the 7012 'CACHEDIR.TAG' file, archive only the directory itself. 7013 7014'--exclude-caches-all' 7015 Omit directories containing 'CACHEDIR.TAG' file entirely. 7016 7017 Another option family, '--exclude-tag', provides a generalization of 7018this concept. It takes a single argument, a file name to look for. Any 7019directory that contains this file will be excluded from the dump. 7020Similarly to 'exclude-caches', there are three options in this option 7021family: 7022 7023'--exclude-tag=FILE' 7024 Do not dump the contents of the directory, but dump the directory 7025 itself and the FILE. 7026 7027'--exclude-tag-under=FILE' 7028 Do not dump the contents of the directory, nor the FILE, archive 7029 only the directory itself. 7030 7031'--exclude-tag-all=FILE' 7032 Omit directories containing FILE file entirely. 7033 7034 Multiple '--exclude-tag*' options can be given. 7035 7036 For example, given this directory: 7037 7038 $ find dir 7039 dir 7040 dir/blues 7041 dir/jazz 7042 dir/folk 7043 dir/folk/tagfile 7044 dir/folk/sanjuan 7045 dir/folk/trote 7046 7047 The '--exclude-tag' will produce the following: 7048 7049 $ tar -cf archive.tar --exclude-tag=tagfile -v dir 7050 dir/ 7051 dir/blues 7052 dir/jazz 7053 dir/folk/ 7054 tar: dir/folk/: contains a cache directory tag tagfile; 7055 contents not dumped 7056 dir/folk/tagfile 7057 7058 Both the 'dir/folk' directory and its tagfile are preserved in the 7059archive, however the rest of files in this directory are not. 7060 7061 Now, using the '--exclude-tag-under' option will exclude 'tagfile' 7062from the dump, while still preserving the directory itself, as shown in 7063this example: 7064 7065 $ tar -cf archive.tar --exclude-tag-under=tagfile -v dir 7066 dir/ 7067 dir/blues 7068 dir/jazz 7069 dir/folk/ 7070 ./tar: dir/folk/: contains a cache directory tag tagfile; 7071 contents not dumped 7072 7073 Finally, using '--exclude-tag-all' omits the 'dir/folk' directory 7074entirely: 7075 7076 $ tar -cf archive.tar --exclude-tag-all=tagfile -v dir 7077 dir/ 7078 dir/blues 7079 dir/jazz 7080 ./tar: dir/folk/: contains a cache directory tag tagfile; 7081 directory not dumped 7082 7083* Menu: 7084 7085* problems with exclude:: 7086 7087 ---------- Footnotes ---------- 7088 7089 (1) According to the Bazaar docs, globbing-patterns are Korn-shell 7090style and regular expressions are perl-style. As of GNU 'tar' version 70911.34, these are treated as shell-style globs and posix extended regexps. 7092This will be fixed in future releases. 7093 7094 (2) Support for perl-style regexps will appear in future releases. 7095 7096 7097File: tar.info, Node: problems with exclude, Up: exclude 7098 7099Problems with Using the 'exclude' Options 7100----------------------------------------- 7101 7102Some users find 'exclude' options confusing. Here are some common 7103pitfalls: 7104 7105 * The main operating mode of 'tar' does not act on a file name 7106 explicitly listed on the command line, if one of its file name 7107 components is excluded. In the example above, if you create an 7108 archive and exclude files that end with '*.o', but explicitly name 7109 the file 'dir.o/foo' after all the options have been listed, 7110 'dir.o/foo' will be excluded from the archive. 7111 7112 * You can sometimes confuse the meanings of '--exclude' and 7113 '--exclude-from'. Be careful: use '--exclude' when files to be 7114 excluded are given as a pattern on the command line. Use 7115 '--exclude-from' to introduce the name of a file which contains a 7116 list of patterns, one per line; each of these patterns can exclude 7117 zero, one, or many files. 7118 7119 * When you use '--exclude=PATTERN', be sure to quote the PATTERN 7120 parameter, so GNU 'tar' sees wildcard characters like '*'. If you 7121 do not do this, the shell might expand the '*' itself using files 7122 at hand, so 'tar' might receive a list of files instead of one 7123 pattern, or none at all, making the command somewhat illegal. This 7124 might not correspond to what you want. 7125 7126 For example, write: 7127 7128 $ tar -c -f ARCHIVE.TAR --exclude '*.o' DIRECTORY 7129 7130 rather than: 7131 7132 # _Wrong!_ 7133 $ tar -c -f ARCHIVE.TAR --exclude *.o DIRECTORY 7134 7135 * You must use use shell syntax, or globbing, rather than 'regexp' 7136 syntax, when using exclude options in 'tar'. If you try to use 7137 'regexp' syntax to describe files to be excluded, your command 7138 might fail. 7139 7140 * 7141 In earlier versions of 'tar', what is now the '--exclude-from' 7142 option was called '--exclude' instead. Now, '--exclude' applies to 7143 patterns listed on the command line and '--exclude-from' applies to 7144 patterns listed in a file. 7145 7146 7147File: tar.info, Node: wildcards, Next: quoting styles, Prev: exclude, Up: Choosing 7148 71496.5 Wildcards Patterns and Matching 7150=================================== 7151 7152"Globbing" is the operation by which "wildcard" characters, '*' or '?' 7153for example, are replaced and expanded into all existing files matching 7154the given pattern. GNU 'tar' can use wildcard patterns for matching (or 7155globbing) archive members when extracting from or listing an archive. 7156Wildcard patterns are also used for verifying volume labels of 'tar' 7157archives. This section has the purpose of explaining wildcard syntax 7158for 'tar'. 7159 7160 A PATTERN should be written according to shell syntax, using wildcard 7161characters to effect globbing. Most characters in the pattern stand for 7162themselves in the matched string, and case is significant: 'a' will 7163match only 'a', and not 'A'. The character '?' in the pattern matches 7164any single character in the matched string. The character '*' in the 7165pattern matches zero, one, or more single characters in the matched 7166string. The character '\' says to take the following character of the 7167pattern _literally_; it is useful when one needs to match the '?', '*', 7168'[' or '\' characters, themselves. 7169 7170 The character '[', up to the matching ']', introduces a character 7171class. A "character class" is a list of acceptable characters for the 7172next single character of the matched string. For example, '[abcde]' 7173would match any of the first five letters of the alphabet. Note that 7174within a character class, all of the "special characters" listed above 7175other than '\' lose their special meaning; for example, '[-\\[*?]]' 7176would match any of the characters, '-', '\', '[', '*', '?', or ']'. 7177(Due to parsing constraints, the characters '-' and ']' must either come 7178_first_ or _last_ in a character class.) 7179 7180 If the first character of the class after the opening '[' is '!' or 7181'^', then the meaning of the class is reversed. Rather than listing 7182character to match, it lists those characters which are _forbidden_ as 7183the next single character of the matched string. 7184 7185 Other characters of the class stand for themselves. The special 7186construction '[A-E]', using an hyphen between two letters, is meant to 7187represent all characters between A and E, inclusive. 7188 7189 Periods ('.') or forward slashes ('/') are not considered special for 7190wildcard matches. However, if a pattern completely matches a directory 7191prefix of a matched string, then it matches the full matched string: 7192thus, excluding a directory also excludes all the files beneath it. 7193 7194* Menu: 7195 7196* controlling pattern-matching:: 7197 7198 7199File: tar.info, Node: controlling pattern-matching, Up: wildcards 7200 7201Controlling Pattern-Matching 7202---------------------------- 7203 7204For the purposes of this section, we call "exclusion members" all member 7205names obtained while processing '--exclude' and '--exclude-from' 7206options, and "inclusion members" those member names that were given in 7207the command line or read from the file specified with '--files-from' 7208option. 7209 7210 These two pairs of member lists are used in the following operations: 7211'--diff', '--extract', '--list', '--update'. 7212 7213 There are no inclusion members in create mode ('--create' and 7214'--append'), since in this mode the names obtained from the command line 7215refer to _files_, not archive members. 7216 7217 By default, inclusion members are compared with archive members 7218literally (1) and exclusion members are treated as globbing patterns. 7219For example: 7220 7221 $ tar tf foo.tar 7222 a.c 7223 b.c 7224 a.txt 7225 [remarks] 7226 # Member names are used verbatim: 7227 $ tar -xf foo.tar -v '[remarks]' 7228 [remarks] 7229 # Exclude member names are globbed: 7230 $ tar -xf foo.tar -v --exclude '*.c' 7231 a.txt 7232 [remarks] 7233 7234 This behavior can be altered by using the following options: 7235 7236'--wildcards' 7237 Treat all member names as wildcards. 7238 7239'--no-wildcards' 7240 Treat all member names as literal strings. 7241 7242 Thus, to extract files whose names end in '.c', you can use: 7243 7244 $ tar -xf foo.tar -v --wildcards '*.c' 7245 a.c 7246 b.c 7247 7248Notice quoting of the pattern to prevent the shell from interpreting it. 7249 7250 The effect of '--wildcards' option is canceled by '--no-wildcards'. 7251This can be used to pass part of the command line arguments verbatim and 7252other part as globbing patterns. For example, the following invocation: 7253 7254 $ tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]' 7255 7256instructs 'tar' to extract from 'foo.tar' all files whose names end in 7257'.txt' and the file named '[remarks]'. 7258 7259 Normally, a pattern matches a name if an initial subsequence of the 7260name's components matches the pattern, where '*', '?', and '[...]' are 7261the usual shell wildcards, '\' escapes wildcards, and wildcards can 7262match '/'. 7263 7264 Other than optionally stripping leading '/' from names (*note 7265absolute::), patterns and names are used as-is. For example, trailing 7266'/' is not trimmed from a user-specified name before deciding whether to 7267exclude it. 7268 7269 However, this matching procedure can be altered by the options listed 7270below. These options accumulate. For example: 7271 7272 --ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme' 7273 7274ignores case when excluding 'makefile', but not when excluding 'readme'. 7275 7276'--anchored' 7277'--no-anchored' 7278 If anchored, a pattern must match an initial subsequence of the 7279 name's components. Otherwise, the pattern can match any 7280 subsequence. Default is '--no-anchored' for exclusion members and 7281 '--anchored' inclusion members. 7282 7283'--ignore-case' 7284'--no-ignore-case' 7285 When ignoring case, upper-case patterns match lower-case names and 7286 vice versa. When not ignoring case (the default), matching is 7287 case-sensitive. 7288 7289'--wildcards-match-slash' 7290'--no-wildcards-match-slash' 7291 When wildcards match slash (the default for exclusion members), a 7292 wildcard like '*' in the pattern can match a '/' in the name. 7293 Otherwise, '/' is matched only by '/'. 7294 7295 The '--recursion' and '--no-recursion' options (*note recurse::) also 7296affect how member patterns are interpreted. If recursion is in effect, 7297a pattern matches a name if it matches any of the name's parent 7298directories. 7299 7300 The following table summarizes pattern-matching default values: 7301 7302Members Default settings 7303-------------------------------------------------------------------------- 7304Inclusion '--no-wildcards --anchored 7305 --no-wildcards-match-slash' 7306Exclusion '--wildcards --no-anchored 7307 --wildcards-match-slash' 7308 7309 ---------- Footnotes ---------- 7310 7311 (1) Notice that earlier GNU 'tar' versions used globbing for 7312inclusion members, which contradicted to UNIX98 specification and was 7313not documented. *Note Changes::, for more information on this and other 7314changes. 7315 7316 7317File: tar.info, Node: quoting styles, Next: transform, Prev: wildcards, Up: Choosing 7318 73196.6 Quoting Member Names 7320======================== 7321 7322When displaying member names, 'tar' takes care to avoid ambiguities 7323caused by certain characters. This is called "name quoting". The 7324characters in question are: 7325 7326 * Non-printable control characters: 7327 Character ASCII Character name 7328 ------------------------------------------------------------------- 7329 \a 7 Audible bell 7330 \b 8 Backspace 7331 \f 12 Form feed 7332 \n 10 New line 7333 \r 13 Carriage return 7334 \t 9 Horizontal tabulation 7335 \v 11 Vertical tabulation 7336 7337 * Space (ASCII 32) 7338 7339 * Single and double quotes (''' and '"') 7340 7341 * Backslash ('\') 7342 7343 The exact way 'tar' uses to quote these characters depends on the 7344"quoting style". The default quoting style, called "escape" (see 7345below), uses backslash notation to represent control characters and 7346backslash. 7347 7348 GNU 'tar' offers seven distinct quoting styles, which can be selected 7349using '--quoting-style' option: 7350 7351'--quoting-style=STYLE' 7352 7353 Sets quoting style. Valid values for STYLE argument are: literal, 7354 shell, shell-always, c, escape, locale, clocale. 7355 7356 These styles are described in detail below. To illustrate their 7357effect, we will use an imaginary tar archive 'arch.tar' containing the 7358following members: 7359 7360 # 1. Contains horizontal tabulation character. 7361 a tab 7362 # 2. Contains newline character 7363 a 7364 newline 7365 # 3. Contains a space 7366 a space 7367 # 4. Contains double quotes 7368 a"double"quote 7369 # 5. Contains single quotes 7370 a'single'quote 7371 # 6. Contains a backslash character: 7372 a\backslash 7373 7374 Here is how usual 'ls' command would have listed them, if they had 7375existed in the current working directory: 7376 7377 $ ls 7378 a\ttab 7379 a\nnewline 7380 a\ space 7381 a"double"quote 7382 a'single'quote 7383 a\\backslash 7384 7385 Quoting styles: 7386 7387'literal' 7388 No quoting, display each character as is: 7389 7390 $ tar tf arch.tar --quoting-style=literal 7391 ./ 7392 ./a space 7393 ./a'single'quote 7394 ./a"double"quote 7395 ./a\backslash 7396 ./a tab 7397 ./a 7398 newline 7399 7400'shell' 7401 Display characters the same way Bourne shell does: control 7402 characters, except '\t' and '\n', are printed using backslash 7403 escapes, '\t' and '\n' are printed as is, and a single quote is 7404 printed as '\''. If a name contains any quoted characters, it is 7405 enclosed in single quotes. In particular, if a name contains 7406 single quotes, it is printed as several single-quoted strings: 7407 7408 $ tar tf arch.tar --quoting-style=shell 7409 ./ 7410 './a space' 7411 './a'\''single'\''quote' 7412 './a"double"quote' 7413 './a\backslash' 7414 './a tab' 7415 './a 7416 newline' 7417 7418'shell-always' 7419 Same as 'shell', but the names are always enclosed in single 7420 quotes: 7421 7422 $ tar tf arch.tar --quoting-style=shell-always 7423 './' 7424 './a space' 7425 './a'\''single'\''quote' 7426 './a"double"quote' 7427 './a\backslash' 7428 './a tab' 7429 './a 7430 newline' 7431 7432'c' 7433 Use the notation of the C programming language. All names are 7434 enclosed in double quotes. Control characters are quoted using 7435 backslash notations, double quotes are represented as '\"', 7436 backslash characters are represented as '\\'. Single quotes and 7437 spaces are not quoted: 7438 7439 $ tar tf arch.tar --quoting-style=c 7440 "./" 7441 "./a space" 7442 "./a'single'quote" 7443 "./a\"double\"quote" 7444 "./a\\backslash" 7445 "./a\ttab" 7446 "./a\nnewline" 7447 7448'escape' 7449 Control characters are printed using backslash notation, and a 7450 backslash as '\\'. This is the default quoting style, unless it 7451 was changed when configured the package. 7452 7453 $ tar tf arch.tar --quoting-style=escape 7454 ./ 7455 ./a space 7456 ./a'single'quote 7457 ./a"double"quote 7458 ./a\\backslash 7459 ./a\ttab 7460 ./a\nnewline 7461 7462'locale' 7463 Control characters, single quote and backslash are printed using 7464 backslash notation. All names are quoted using left and right 7465 quotation marks, appropriate to the current locale. If it does not 7466 define quotation marks, use ''' as left and as right quotation 7467 marks. Any occurrences of the right quotation mark in a name are 7468 escaped with '\', for example: 7469 7470 For example: 7471 7472 $ tar tf arch.tar --quoting-style=locale 7473 './' 7474 './a space' 7475 './a\'single\'quote' 7476 './a"double"quote' 7477 './a\\backslash' 7478 './a\ttab' 7479 './a\nnewline' 7480 7481'clocale' 7482 Same as 'locale', but '"' is used for both left and right quotation 7483 marks, if not provided by the currently selected locale: 7484 7485 $ tar tf arch.tar --quoting-style=clocale 7486 "./" 7487 "./a space" 7488 "./a'single'quote" 7489 "./a\"double\"quote" 7490 "./a\\backslash" 7491 "./a\ttab" 7492 "./a\nnewline" 7493 7494 You can specify which characters should be quoted in addition to 7495those implied by the current quoting style: 7496 7497'--quote-chars=STRING' 7498 Always quote characters from STRING, even if the selected quoting 7499 style would not quote them. 7500 7501 For example, using 'escape' quoting (compare with the usual escape 7502listing above): 7503 7504 $ tar tf arch.tar --quoting-style=escape --quote-chars=' "' 7505 ./ 7506 ./a\ space 7507 ./a'single'quote 7508 ./a\"double\"quote 7509 ./a\\backslash 7510 ./a\ttab 7511 ./a\nnewline 7512 7513 To disable quoting of such additional characters, use the following 7514option: 7515 7516'--no-quote-chars=STRING' 7517 Remove characters listed in STRING from the list of quoted 7518 characters set by the previous '--quote-chars' option. 7519 7520 This option is particularly useful if you have added '--quote-chars' 7521to your 'TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to disable it for 7522the current invocation. 7523 7524 Note, that '--no-quote-chars' does _not_ disable those characters 7525that are quoted by default in the selected quoting style. 7526 7527 7528File: tar.info, Node: transform, Next: after, Prev: quoting styles, Up: Choosing 7529 75306.7 Modifying File and Member Names 7531=================================== 7532 7533'Tar' archives contain detailed information about files stored in them 7534and full file names are part of that information. When storing a file 7535to an archive, its file name is recorded in it, along with the actual 7536file contents. When restoring from an archive, a file is created on 7537disk with exactly the same name as that stored in the archive. In the 7538majority of cases this is the desired behavior of a file archiver. 7539However, there are some cases when it is not. 7540 7541 First of all, it is often unsafe to extract archive members with 7542absolute file names or those that begin with a '../'. GNU 'tar' takes 7543special precautions when extracting such names and provides a special 7544option for handling them, which is described in *note absolute::. 7545 7546 Secondly, you may wish to extract file names without some leading 7547directory components, or with otherwise modified names. In other cases 7548it is desirable to store files under differing names in the archive. 7549 7550 GNU 'tar' provides several options for these needs. 7551 7552'--strip-components=NUMBER' 7553 Strip given NUMBER of leading components from file names before 7554 extraction. 7555 7556 For example, suppose you have archived whole '/usr' hierarchy to a 7557tar archive named 'usr.tar'. Among other files, this archive contains 7558'usr/include/stdlib.h', which you wish to extract to the current working 7559directory. To do so, you type: 7560 7561 $ tar -xf usr.tar --strip=2 usr/include/stdlib.h 7562 7563 The option '--strip=2' instructs 'tar' to strip the two leading 7564components ('usr/' and 'include/') off the file name. 7565 7566 If you add the '--verbose' ('-v') option to the invocation above, you 7567will note that the verbose listing still contains the full file name, 7568with the two removed components still in place. This can be 7569inconvenient, so 'tar' provides a special option for altering this 7570behavior: 7571 7572'--show-transformed-names' 7573 Display file or member names with all requested transformations 7574 applied. 7575 7576For example: 7577 7578 $ tar -xf usr.tar -v --strip=2 usr/include/stdlib.h 7579 usr/include/stdlib.h 7580 $ tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h 7581 stdlib.h 7582 7583 Notice that in both cases the file 'stdlib.h' is extracted to the 7584current working directory, '--show-transformed-names' affects only the 7585way its name is displayed. 7586 7587 This option is especially useful for verifying whether the invocation 7588will have the desired effect. Thus, before running 7589 7590 $ tar -x --strip=N 7591 7592it is often advisable to run 7593 7594 $ tar -t -v --show-transformed --strip=N 7595 7596to make sure the command will produce the intended results. 7597 7598 In case you need to apply more complex modifications to the file 7599name, GNU 'tar' provides a general-purpose transformation option: 7600 7601'--transform=EXPRESSION' 7602'--xform=EXPRESSION' 7603 Modify file names using supplied EXPRESSION. 7604 7605The EXPRESSION is a 'sed'-like replace expression of the form: 7606 7607 s/REGEXP/REPLACE/[FLAGS] 7608 7609where REGEXP is a "regular expression", REPLACE is a replacement for 7610each file name part that matches REGEXP. Both REGEXP and REPLACE are 7611described in detail in *note The "s" Command: (sed)The "s" Command. 7612 7613 Any delimiter can be used in lieu of '/', the only requirement being 7614that it be used consistently throughout the expression. For example, 7615the following two expressions are equivalent: 7616 7617 s/one/two/ 7618 s,one,two, 7619 7620 Changing delimiters is often useful when the REGEX contains slashes. 7621For example, it is more convenient to write 's,/,-,' than 's/\//-/'. 7622 7623 As in 'sed', you can give several replace expressions, separated by a 7624semicolon. 7625 7626 Supported FLAGS are: 7627 7628'g' 7629 Apply the replacement to _all_ matches to the REGEXP, not just the 7630 first. 7631 7632'i' 7633 Use case-insensitive matching. 7634 7635'x' 7636 REGEXP is an "extended regular expression" (*note Extended regular 7637 expressions: (sed)Extended regexps.). 7638 7639'NUMBER' 7640 Only replace the NUMBERth match of the REGEXP. 7641 7642 Note: the POSIX standard does not specify what should happen when 7643 you mix the 'g' and NUMBER modifiers. GNU 'tar' follows the GNU 7644 'sed' implementation in this regard, so the interaction is defined 7645 to be: ignore matches before the NUMBERth, and then match and 7646 replace all matches from the NUMBERth on. 7647 7648 In addition, several "transformation scope" flags are supported, that 7649control to what files transformations apply. These are: 7650 7651'r' 7652 Apply transformation to regular archive members. 7653 7654'R' 7655 Do not apply transformation to regular archive members. 7656 7657's' 7658 Apply transformation to symbolic link targets. 7659 7660'S' 7661 Do not apply transformation to symbolic link targets. 7662 7663'h' 7664 Apply transformation to hard link targets. 7665 7666'H' 7667 Do not apply transformation to hard link targets. 7668 7669 Default is 'rsh', which means to apply transformations to both 7670archive members and targets of symbolic and hard links. 7671 7672 Default scope flags can also be changed using 'flags=' statement in 7673the transform expression. The flags set this way remain in force until 7674next 'flags=' statement or end of expression, whichever occurs first. 7675For example: 7676 7677 --transform 'flags=S;s|^|/usr/local/|' 7678 7679 Here are several examples of '--transform' usage: 7680 7681 1. Extract 'usr/' hierarchy into 'usr/local/': 7682 7683 $ tar --transform='s,usr/,usr/local/,' -x -f arch.tar 7684 7685 2. Strip two leading directory components (equivalent to 7686 '--strip-components=2'): 7687 7688 $ tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar 7689 7690 3. Convert each file name to lower case: 7691 7692 $ tar --transform 's/.*/\L&/' -x -f arch.tar 7693 7694 4. Prepend '/prefix/' to each file name: 7695 7696 $ tar --transform 's,^,/prefix/,' -x -f arch.tar 7697 7698 5. Archive the '/lib' directory, prepending '/usr/local' to each 7699 archive member: 7700 7701 $ tar --transform 's,^,/usr/local/,S' -c -f arch.tar /lib 7702 7703 Notice the use of flags in the last example. The '/lib' directory 7704often contains many symbolic links to files within it. It may look, for 7705example, like this: 7706 7707 $ ls -l 7708 drwxr-xr-x root/root 0 2008-07-08 16:20 /lib/ 7709 -rwxr-xr-x root/root 1250840 2008-05-25 07:44 /lib/libc-2.3.2.so 7710 lrwxrwxrwx root/root 0 2008-06-24 17:12 /lib/libc.so.6 -> libc-2.3.2.so 7711 ... 7712 7713 Using the expression 's,^,/usr/local/,' would mean adding 7714'/usr/local' to both regular archive members and to link targets. In 7715this case, '/lib/libc.so.6' would become: 7716 7717 /usr/local/lib/libc.so.6 -> /usr/local/libc-2.3.2.so 7718 7719 This is definitely not desired. To avoid this, the 'S' flag is used, 7720which excludes symbolic link targets from filename transformations. The 7721result is: 7722 7723 $ tar --transform 's,^,/usr/local/,S' -c -v -f arch.tar \ 7724 --show-transformed /lib 7725 drwxr-xr-x root/root 0 2008-07-08 16:20 /usr/local/lib/ 7726 -rwxr-xr-x root/root 1250840 2008-05-25 07:44 /usr/local/lib/libc-2.3.2.so 7727 lrwxrwxrwx root/root 0 2008-06-24 17:12 /usr/local/lib/libc.so.6 \ 7728 -> libc-2.3.2.so 7729 7730 Unlike '--strip-components', '--transform' can be used in any GNU 7731'tar' operation mode. For example, the following command adds files to 7732the archive while replacing the leading 'usr/' component with 'var/': 7733 7734 $ tar -cf arch.tar --transform='s,^usr/,var/,' / 7735 7736 To test '--transform' effect we suggest using 7737'--show-transformed-names' option: 7738 7739 $ tar -cf arch.tar --transform='s,^usr/,var/,' \ 7740 --verbose --show-transformed-names / 7741 7742 If both '--strip-components' and '--transform' are used together, 7743then '--transform' is applied first, and the required number of 7744components is then stripped from its result. 7745 7746 You can use as many '--transform' options in a single command line as 7747you want. The specified expressions will then be applied in order of 7748their appearance. For example, the following two invocations are 7749equivalent: 7750 7751 $ tar -cf arch.tar --transform='s,/usr/var,/var/' \ 7752 --transform='s,/usr/local,/usr/,' 7753 $ tar -cf arch.tar \ 7754 --transform='s,/usr/var,/var/;s,/usr/local,/usr/,' 7755 7756 7757File: tar.info, Node: after, Next: recurse, Prev: transform, Up: Choosing 7758 77596.8 Operating Only on New Files 7760=============================== 7761 7762The '--after-date=DATE' ('--newer=DATE', '-N DATE') option causes 'tar' 7763to only work on files whose data modification or status change times are 7764newer than the DATE given. If DATE starts with '/' or '.', it is taken 7765to be a file name; the data modification time of that file is used as 7766the date. If you use this option when creating or appending to an 7767archive, the archive will only include new files. If you use 7768'--after-date' when extracting an archive, 'tar' will only extract files 7769newer than the DATE you specify. 7770 7771 If you only want 'tar' to make the date comparison based on 7772modification of the file's data (rather than status changes), then use 7773the '--newer-mtime=DATE' option. 7774 7775 You may use these options with any operation. Note that these 7776options differ from the '--update' ('-u') operation in that they allow 7777you to specify a particular date against which 'tar' can compare when 7778deciding whether or not to archive the files. 7779 7780'--after-date=DATE' 7781'--newer=DATE' 7782'-N DATE' 7783 Only store files newer than DATE. 7784 7785 Acts on files only if their data modification or status change 7786 times are later than DATE. Use in conjunction with any operation. 7787 7788 If DATE starts with '/' or '.', it is taken to be a file name; the 7789 data modification time of that file is used as the date. 7790 7791'--newer-mtime=DATE' 7792 Acts like '--after-date', but only looks at data modification 7793 times. 7794 7795 These options limit 'tar' to operate only on files which have been 7796modified after the date specified. A file's status is considered to 7797have changed if its contents have been modified, or if its owner, 7798permissions, and so forth, have been changed. (For more information on 7799how to specify a date, see *note Date input formats::; remember that the 7800entire date argument must be quoted if it contains any spaces.) 7801 7802 Gurus would say that '--after-date' tests both the data modification 7803time ('mtime', the time the contents of the file were last modified) and 7804the status change time ('ctime', the time the file's status was last 7805changed: owner, permissions, etc.) fields, while '--newer-mtime' tests 7806only the 'mtime' field. 7807 7808 To be precise, '--after-date' checks _both_ 'mtime' and 'ctime' and 7809processes the file if either one is more recent than DATE, while 7810'--newer-mtime' only checks 'mtime' and disregards 'ctime'. Neither 7811does it use 'atime' (the last time the contents of the file were looked 7812at). 7813 7814 Date specifiers can have embedded spaces. Because of this, you may 7815need to quote date arguments to keep the shell from parsing them as 7816separate arguments. For example, the following command will add to the 7817archive all the files modified less than two days ago: 7818 7819 $ tar -cf foo.tar --newer-mtime '2 days ago' 7820 7821 When any of these options is used with the option '--verbose' (*note 7822verbose tutorial::) GNU 'tar' will try to convert the specified date 7823back to its textual representation and compare that with the one given 7824with the option. If the two dates differ, 'tar' will print a warning 7825saying what date it will use. This is to help user ensure he is using 7826the right date. For example: 7827 7828 $ tar -c -f archive.tar --after-date='10 days ago' . 7829 tar: Option --after-date: Treating date '10 days ago' as 2006-06-11 7830 13:19:37.232434 7831 7832 *Please Note:* '--after-date' and '--newer-mtime' should not be 7833 used for incremental backups. *Note Incremental Dumps::, for 7834 proper way of creating incremental backups. 7835 7836 7837File: tar.info, Node: recurse, Next: one, Prev: after, Up: Choosing 7838 78396.9 Descending into Directories 7840=============================== 7841 7842Usually, 'tar' will recursively explore all directories (either those 7843given on the command line or through the '--files-from' option) for the 7844various files they contain. However, you may not always want 'tar' to 7845act this way. 7846 7847 The '--no-recursion' option inhibits 'tar''s recursive descent into 7848specified directories. If you specify '--no-recursion', you can use the 7849'find' (*note find: (find)Top.) utility for hunting through levels of 7850directories to construct a list of file names which you could then pass 7851to 'tar'. 'find' allows you to be more selective when choosing which 7852files to archive; see *note files::, for more information on using 7853'find' with 'tar'. 7854 7855'--no-recursion' 7856 Prevents 'tar' from recursively descending directories. 7857 7858'--recursion' 7859 Requires 'tar' to recursively descend directories. This is the 7860 default. 7861 7862 When you use '--no-recursion', GNU 'tar' grabs directory entries 7863themselves, but does not descend on them recursively. Many people use 7864'find' for locating files they want to back up, and since 'tar' 7865_usually_ recursively descends on directories, they have to use the 7866'-not -type d' test in their 'find' invocation (*note Type: 7867(find)Type.), as they usually do not want all the files in a directory. 7868They then use the '--files-from' option to archive the files located via 7869'find'. 7870 7871 The problem when restoring files archived in this manner is that the 7872directories themselves are not in the archive; so the 7873'--same-permissions' ('--preserve-permissions', '-p') option does not 7874affect them--while users might really like it to. Specifying 7875'--no-recursion' is a way to tell 'tar' to grab only the directory 7876entries given to it, adding no new files on its own. To summarize, if 7877you use 'find' to create a list of files to be stored in an archive, use 7878it as follows: 7879 7880 $ find DIR TESTS | \ 7881 tar -cf ARCHIVE --no-recursion -T - 7882 7883 The '--no-recursion' option also applies when extracting: it causes 7884'tar' to extract only the matched directory entries, not the files under 7885those directories. 7886 7887 The '--no-recursion' option also affects how globbing patterns are 7888interpreted (*note controlling pattern-matching::). 7889 7890 The '--no-recursion' and '--recursion' options apply to later options 7891and operands, and can be overridden by later occurrences of 7892'--no-recursion' and '--recursion'. For example: 7893 7894 $ tar -cf jams.tar --no-recursion grape --recursion grape/concord 7895 7896creates an archive with one entry for 'grape', and the recursive 7897contents of 'grape/concord', but no entries under 'grape' other than 7898'grape/concord'. 7899 7900