1 This is tar.info, produced by makeinfo version 5.9.93 from tar.texi.
3 This manual is for GNU 'tar' (version 1.29, 14 April 2016), which
4 creates and extracts files from archives.
6 Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2016 Free Software
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".
17 (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
18 modify this GNU manual."
19 INFO-DIR-SECTION Archiving
21 * Tar: (tar). Making tape (or disk) archives.
24 INFO-DIR-SECTION Individual utilities
26 * tar: (tar)tar invocation. Invoking GNU 'tar'.
30 File: tar.info, Node: Top, Next: Introduction, Up: (dir)
32 GNU tar: an archiver tool
33 *************************
35 This manual is for GNU 'tar' (version 1.29, 14 April 2016), which
36 creates and extracts files from archives.
38 Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2016 Free Software
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".
49 (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
50 modify this GNU manual."
52 The first part of this master menu lists the major nodes in this Info
53 document. The rest of the menu lists all the lower level nodes.
63 * Date input formats::
66 * Reliability and security::
71 * Configuring Help Summary::
72 * Fixing Snapshot Files::
75 * Free Software Needs Free Documentation::
76 * GNU Free Documentation License::
77 * Index of Command Line Options::
80 -- The Detailed Node Listing --
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
91 Tutorial Introduction to 'tar'
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
103 Two Frequently Used Options
109 How to Create Archives
111 * prepare for examples::
112 * Creating the archive::
121 How to Extract Members from an Archive
123 * extracting archives::
126 * extracting untrusted archives::
132 * using tar options::
142 The Three Option Styles
144 * Long Options:: Long Option Style
145 * Short Options:: Short Option Style
146 * Old Options:: Old Option Style
147 * Mixing:: Mixing Option Styles
151 * Operation Summary::
153 * Short Option Summary::
154 * Position-Sensitive Options::
166 Advanced GNU 'tar' Operations
175 How to Add Files to Existing Archives: '--append'
177 * appending files:: Appending Files to an Archive
184 Options Used by '--create'
186 * override:: Overriding File Metadata.
187 * Extended File Attributes::
188 * Ignore Failed Read::
190 Options Used by '--extract'
192 * Reading:: Options to Help Read Archives
193 * Writing:: Changing How 'tar' Writes Files
194 * Scarce:: Coping with Scarce Resources
196 Options to Help Read Archives
198 * read full records::
201 Changing How 'tar' Writes Files
203 * Dealing with Old Files::
204 * Overwrite Old Files::
209 * Data Modification Times::
210 * Setting Access Permissions::
211 * Directory Modification Times and Permissions::
212 * Writing to Standard Output::
213 * Writing to an External Program::
216 Coping with Scarce Resources
221 Performing Backups and Restoring Files
223 * Full Dumps:: Using 'tar' to Perform Full Dumps
224 * Incremental Dumps:: Using 'tar' to Perform Incremental Dumps
225 * Backup Levels:: Levels of Backups
226 * Backup Parameters:: Setting Parameters for Backups and Restoration
227 * Scripted Backups:: Using the Backup Scripts
228 * Scripted Restoration:: Using the Restore Script
230 Setting Parameters for Backups and Restoration
232 * General-Purpose Variables::
233 * Magnetic Tape Control::
235 * backup-specs example:: An Example Text of 'Backup-specs'
237 Choosing Files and Names for 'tar'
239 * file:: Choosing the Archive's Name
240 * Selecting Archive Members::
241 * files:: Reading Names from a File
242 * exclude:: Excluding Some Files
243 * wildcards:: Wildcards Patterns and Matching
244 * quoting styles:: Ways of Quoting Special Characters in Names
245 * transform:: Modifying File and Member Names
246 * after:: Operating Only on New Files
247 * recurse:: Descending into Directories
248 * one:: Crossing File System Boundaries
250 Reading Names from a File
256 * problems with exclude::
258 Wildcards Patterns and Matching
260 * controlling pattern-matching::
262 Crossing File System Boundaries
264 * directory:: Changing Directory
265 * absolute:: Absolute File Names
269 * General date syntax:: Common rules.
270 * Calendar date items:: 19 Dec 1994.
271 * Time of day items:: 9:20pm.
272 * Time zone items:: EST, PDT, GMT.
273 * Day of week items:: Monday and others.
274 * Relative items in date strings:: next tuesday, 2 years ago.
275 * Pure numbers in date strings:: 19931219, 1440.
276 * Seconds since the Epoch:: @1078100502.
277 * Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
278 * Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al.
280 Controlling the Archive Format
282 * Compression:: Using Less Space through Compression
283 * Attributes:: Handling File Attributes
284 * Portability:: Making 'tar' Archives More Portable
285 * cpio:: Comparison of 'tar' and 'cpio'
287 Using Less Space through Compression
289 * gzip:: Creating and Reading Compressed Archives
290 * sparse:: Archiving Sparse Files
292 Creating and Reading Compressed Archives
294 * lbzip2:: Using lbzip2 with GNU 'tar'.
296 Making 'tar' Archives More Portable
298 * Portable Names:: Portable Names
299 * dereference:: Symbolic Links
300 * hard links:: Hard Links
301 * old:: Old V7 Archives
302 * ustar:: Ustar Archives
303 * gnu:: GNU and old GNU format archives.
304 * posix:: POSIX archives
305 * Checksumming:: Checksumming Problems
306 * Large or Negative Values:: Large files, negative time stamps, etc.
307 * Other Tars:: How to Extract GNU-Specific Data Using
308 Other 'tar' Implementations
310 GNU 'tar' and POSIX 'tar'
312 * PAX keywords:: Controlling Extended Header Keywords.
314 How to Extract GNU-Specific Data Using Other 'tar' Implementations
316 * Split Recovery:: Members Split Between Volumes
317 * Sparse Recovery:: Sparse Members
319 Tapes and Other Archive Media
321 * Device:: Device selection and switching
322 * Remote Tape Server::
323 * Common Problems and Solutions::
324 * Blocking:: Blocking
325 * Many:: Many archives on one tape
326 * Using Multiple Tapes:: Using Multiple Tapes
327 * label:: Including a Label in the Archive
333 * Format Variations:: Format Variations
334 * Blocking Factor:: The Blocking Factor of an Archive
336 Many Archives on One Tape
338 * Tape Positioning:: Tape Positions and Tape Marks
339 * mt:: The 'mt' Utility
343 * Multi-Volume Archives:: Archives Longer than One Tape or Disk
344 * Tape Files:: Tape Files
345 * Tarcat:: Concatenate Volumes into a Single Archive
350 * Standard:: Basic Tar Format
351 * Extensions:: GNU Extensions to the Archive Format
352 * Sparse Formats:: Storing Sparse Files
359 * PAX 0:: PAX Format, Versions 0.0 and 0.1
360 * PAX 1:: PAX Format, Version 1.0
364 * Generate Mode:: File Generation Mode.
365 * Status Mode:: File Status Mode.
366 * Exec Mode:: Synchronous Execution mode.
370 * GNU Free Documentation License:: License for copying this manual
374 File: tar.info, Node: Introduction, Next: Tutorial, Prev: Top, Up: Top
379 GNU 'tar' creates and manipulates "archives" which are actually
380 collections of many other files; the program provides users with an
381 organized and systematic method for controlling a large amount of data.
382 The name "tar" originally came from the phrase "Tape ARchive", but
383 archives need not (and these days, typically do not) reside on tapes.
387 * Book Contents:: What this Book Contains
388 * Definitions:: Some Definitions
389 * What tar Does:: What 'tar' Does
390 * Naming tar Archives:: How 'tar' Archives are Named
391 * Authors:: GNU 'tar' Authors
392 * Reports:: Reporting bugs or suggestions
395 File: tar.info, Node: Book Contents, Next: Definitions, Up: Introduction
397 1.1 What this Book Contains
398 ===========================
400 The first part of this chapter introduces you to various terms that will
401 recur throughout the book. It also tells you who has worked on GNU
402 'tar' and its documentation, and where you should send bug reports or
405 The second chapter is a tutorial (*note Tutorial::) which provides a
406 gentle introduction for people who are new to using 'tar'. It is meant
407 to be self-contained, not requiring any reading from subsequent chapters
408 to make sense. It moves from topic to topic in a logical, progressive
409 order, building on information already explained.
411 Although the tutorial is paced and structured to allow beginners to
412 learn how to use 'tar', it is not intended solely for beginners. The
413 tutorial explains how to use the three most frequently used operations
414 ('create', 'list', and 'extract') as well as two frequently used options
415 ('file' and 'verbose'). The other chapters do not refer to the tutorial
416 frequently; however, if a section discusses something which is a complex
417 variant of a basic concept, there may be a cross-reference to that basic
418 concept. (The entire book, including the tutorial, assumes that the
419 reader understands some basic concepts of using a Unix-type operating
420 system; *note Tutorial::.)
422 The third chapter presents the remaining five operations, and
423 information about using 'tar' options and option syntax.
425 The other chapters are meant to be used as a reference. Each chapter
426 presents everything that needs to be said about a specific topic.
428 One of the chapters (*note Date input formats::) exists in its
429 entirety in other GNU manuals, and is mostly self-contained. In
430 addition, one section of this manual (*note Standard::) contains a big
431 quote which is taken directly from 'tar' sources.
433 In general, we give both long and short (abbreviated) option names at
434 least once in each section where the relevant option is covered, so that
435 novice readers will become familiar with both styles. (A few options
436 have no short versions, and the relevant sections will indicate this.)
439 File: tar.info, Node: Definitions, Next: What tar Does, Prev: Book Contents, Up: Introduction
444 The 'tar' program is used to create and manipulate 'tar' archives. An
445 "archive" is a single file which contains the contents of many files,
446 while still identifying the names of the files, their owner(s), and so
447 forth. (In addition, archives record access permissions, user and
448 group, size in bytes, and data modification time. Some archives also
449 record the file names in each archived directory, as well as other file
450 and directory information.) You can use 'tar' to "create" a new archive
451 in a specified directory.
453 The files inside an archive are called "members". Within this
454 manual, we use the term "file" to refer only to files accessible in the
455 normal ways (by 'ls', 'cat', and so forth), and the term "member" to
456 refer only to the members of an archive. Similarly, a "file name" is
457 the name of a file, as it resides in the file system, and a "member
458 name" is the name of an archive member within the archive.
460 The term "extraction" refers to the process of copying an archive
461 member (or multiple members) into a file in the file system. Extracting
462 all the members of an archive is often called "extracting the archive".
463 The term "unpack" can also be used to refer to the extraction of many or
464 all the members of an archive. Extracting an archive does not destroy
465 the archive's structure, just as creating an archive does not destroy
466 the copies of the files that exist outside of the archive. You may also
467 "list" the members in a given archive (this is often thought of as
468 "printing" them to the standard output, or the command line), or
469 "append" members to a pre-existing archive. All of these operations can
470 be performed using 'tar'.
473 File: tar.info, Node: What tar Does, Next: Naming tar Archives, Prev: Definitions, Up: Introduction
478 The 'tar' program provides the ability to create 'tar' archives, as well
479 as various other kinds of manipulation. For example, you can use 'tar'
480 on previously created archives to extract files, to store additional
481 files, or to update or list files which were already stored.
483 Initially, 'tar' archives were used to store files conveniently on
484 magnetic tape. The name 'tar' comes from this use; it stands for 't'ape
485 'ar'chiver. Despite the utility's name, 'tar' can direct its output to
486 available devices, files, or other programs (using pipes). 'tar' may
487 even access remote devices or files (as archives).
489 You can use 'tar' archives in many ways. We want to stress a few of
490 them: storage, backup, and transportation.
493 Often, 'tar' archives are used to store related files for
494 convenient file transfer over a network. For example, the GNU
495 Project distributes its software bundled into 'tar' archives, so
496 that all the files relating to a particular program (or set of
497 related programs) can be transferred as a single unit.
499 A magnetic tape can store several files in sequence. However, the
500 tape has no names for these files; it only knows their relative
501 position on the tape. One way to store several files on one tape
502 and retain their names is by creating a 'tar' archive. Even when
503 the basic transfer mechanism can keep track of names, as FTP can,
504 the nuisance of handling multiple files, directories, and multiple
505 links makes 'tar' archives useful.
507 Archive files are also used for long-term storage. You can think
508 of this as transportation from the present into the future. (It is
509 a science-fiction idiom that you can move through time as well as
510 in space; the idea here is that 'tar' can be used to move archives
511 in all dimensions, even time!)
514 Because the archive created by 'tar' is capable of preserving file
515 information and directory structure, 'tar' is commonly used for
516 performing full and incremental backups of disks. A backup puts a
517 collection of files (possibly pertaining to many users and
518 projects) together on a disk or a tape. This guards against
519 accidental destruction of the information in those files. GNU
520 'tar' has special features that allow it to be used to make
521 incremental and full dumps of all the files in a file system.
524 You can create an archive on one system, transfer it to another
525 system, and extract the contents there. This allows you to
526 transport a group of files from one system to another.
529 File: tar.info, Node: Naming tar Archives, Next: Authors, Prev: What tar Does, Up: Introduction
531 1.4 How 'tar' Archives are Named
532 ================================
534 Conventionally, 'tar' archives are given names ending with '.tar'. This
535 is not necessary for 'tar' to operate properly, but this manual follows
536 that convention in order to accustom readers to it and to make examples
539 Often, people refer to 'tar' archives as "'tar' files," and archive
540 members as "files" or "entries". For people familiar with the operation
541 of 'tar', this causes no difficulty. However, in this manual, we
542 consistently refer to "archives" and "archive members" to make learning
543 to use 'tar' easier for novice users.
546 File: tar.info, Node: Authors, Next: Reports, Prev: Naming tar Archives, Up: Introduction
548 1.5 GNU 'tar' Authors
549 =====================
551 GNU 'tar' was originally written by John Gilmore, and modified by many
552 people. The GNU enhancements were written by Jay Fenlason, then Joy
553 Kendall, and the whole package has been further maintained by Thomas
554 Bushnell, n/BSG, Franc,ois Pinard, Paul Eggert, and finally Sergey
555 Poznyakoff with the help of numerous and kind users.
557 We wish to stress that 'tar' is a collective work, and owes much to
558 all those people who reported problems, offered solutions and other
559 insights, or shared their thoughts and suggestions. An impressive, yet
560 partial list of those contributors can be found in the 'THANKS' file
561 from the GNU 'tar' distribution.
563 Jay Fenlason put together a draft of a GNU 'tar' manual, borrowing
564 notes from the original man page from John Gilmore. This was withdrawn
565 in version 1.11. Thomas Bushnell, n/BSG and Amy Gorin worked on a
566 tutorial and manual for GNU 'tar'. Franc,ois Pinard put version 1.11.8
567 of the manual together by taking information from all these sources and
568 merging them. Melissa Weisshaus finally edited and redesigned the book
569 to create version 1.12. The book for versions from 1.14 up to 1.29 were
570 edited by the current maintainer, Sergey Poznyakoff.
572 For version 1.12, Daniel Hagerty contributed a great deal of
573 technical consulting. In particular, he is the primary author of *note
576 In July, 2003 GNU 'tar' was put on CVS at savannah.gnu.org (see
577 <http://savannah.gnu.org/projects/tar>), and active development and
578 maintenance work has started again. Currently GNU 'tar' is being
579 maintained by Paul Eggert, Sergey Poznyakoff and Jeff Bailey.
581 Support for POSIX archives was added by Sergey Poznyakoff.
584 File: tar.info, Node: Reports, Prev: Authors, Up: Introduction
586 1.6 Reporting bugs or suggestions
587 =================================
589 If you find problems or have suggestions about this program or manual,
590 please report them to 'bug-tar@gnu.org'.
592 When reporting a bug, please be sure to include as much detail as
593 possible, in order to reproduce it.
596 File: tar.info, Node: Tutorial, Next: tar invocation, Prev: Introduction, Up: Top
598 2 Tutorial Introduction to 'tar'
599 ********************************
601 This chapter guides you through some basic examples of three 'tar'
602 operations: '--create', '--list', and '--extract'. If you already know
603 how to use some other version of 'tar', then you may not need to read
604 this chapter. This chapter omits most complicated details about how
610 * stylistic conventions::
611 * basic tar options:: Basic 'tar' Operations and Options
612 * frequent operations::
613 * Two Frequent Options::
614 * create:: How to Create Archives
615 * list:: How to List Archives
616 * extract:: How to Extract Members from an Archive
620 File: tar.info, Node: assumptions, Next: stylistic conventions, Up: Tutorial
622 2.1 Assumptions this Tutorial Makes
623 ===================================
625 This chapter is paced to allow beginners to learn about 'tar' slowly.
626 At the same time, we will try to cover all the basic aspects of these
627 three operations. In order to accomplish both of these tasks, we have
628 made certain assumptions about your knowledge before reading this
629 manual, and the hardware you will be using:
631 * Before you start to work through this tutorial, you should
632 understand what the terms "archive" and "archive member" mean
633 (*note Definitions::). In addition, you should understand
634 something about how Unix-type operating systems work, and you
635 should know how to use some basic utilities. For example, you
636 should know how to create, list, copy, rename, edit, and delete
637 files and directories; how to change between directories; and how
638 to figure out where you are in the file system. You should have
639 some basic understanding of directory structure and how files are
640 named according to which directory they are in. You should
641 understand concepts such as standard output and standard input,
642 what various definitions of the term 'argument' mean, and the
643 differences between relative and absolute file names.
645 * This manual assumes that you are working from your own home
646 directory (unless we state otherwise). In this tutorial, you will
647 create a directory to practice 'tar' commands in. When we show
648 file names, we will assume that those names are relative to your
649 home directory. For example, my home directory is
650 '/home/fsf/melissa'. All of my examples are in a subdirectory of
651 the directory named by that file name; the subdirectory is called
654 * In general, we show examples of archives which exist on (or can be
655 written to, or worked with from) a directory on a hard disk. In
656 most cases, you could write those archives to, or work with them on
657 any other device, such as a tape drive. However, some of the later
658 examples in the tutorial and next chapter will not work on tape
659 drives. Additionally, working with tapes is much more complicated
660 than working with hard disks. For these reasons, the tutorial does
661 not cover working with tape drives. *Note Media::, for complete
662 information on using 'tar' archives with tape drives.
665 File: tar.info, Node: stylistic conventions, Next: basic tar options, Prev: assumptions, Up: Tutorial
667 2.2 Stylistic Conventions
668 =========================
670 In the examples, '$' represents a typical shell prompt. It precedes
671 lines you should type; to make this more clear, those lines are shown in
672 'this font', as opposed to lines which represent the computer's
673 response; those lines are shown in 'this font', or sometimes 'like
677 File: tar.info, Node: basic tar options, Next: frequent operations, Prev: stylistic conventions, Up: Tutorial
679 2.3 Basic 'tar' Operations and Options
680 ======================================
682 'tar' can take a wide variety of arguments which specify and define the
683 actions it will have on the particular set of files or the archive. The
684 main types of arguments to 'tar' fall into one of two classes:
685 operations, and options.
687 Some arguments fall into a class called "operations"; exactly one of
688 these is both allowed and required for any instance of using 'tar'; you
689 may _not_ specify more than one. People sometimes speak of "operating
690 modes". You are in a particular operating mode when you have specified
691 the operation which specifies it; there are eight operations in total,
692 and thus there are eight operating modes.
694 The other arguments fall into the class known as "options". You are
695 not required to specify any options, and you are allowed to specify more
696 than one at a time (depending on the way you are using 'tar' at that
697 time). Some options are used so frequently, and are so useful for
698 helping you type commands more carefully that they are effectively
699 "required". We will discuss them in this chapter.
701 You can write most of the 'tar' operations and options in any of
702 three forms: long (mnemonic) form, short form, and old style. Some of
703 the operations and options have no short or "old" forms; however, the
704 operations and options which we will cover in this tutorial have
705 corresponding abbreviations. We will indicate those abbreviations
706 appropriately to get you used to seeing them. Note, that the "old
707 style" option forms exist in GNU 'tar' for compatibility with Unix
708 'tar'. In this book we present a full discussion of this way of writing
709 options and operations (*note Old Options::), and we discuss the other
710 two styles of writing options (*Note Long Options::, and *note Short
713 In the examples and in the text of this tutorial, we usually use the
714 long forms of operations and options; but the "short" forms produce the
715 same result and can make typing long 'tar' commands easier. For
716 example, instead of typing
718 tar --create --verbose --file=afiles.tar apple angst aspic
721 tar -c -v -f afiles.tar apple angst aspic
724 tar -cvf afiles.tar apple angst aspic
726 For more information on option syntax, see *note Advanced tar::. In
727 discussions in the text, when we name an option by its long form, we
728 also give the corresponding short option in parentheses.
730 The term, "option", can be confusing at times, since "operations" are
731 often lumped in with the actual, _optional_ "options" in certain general
732 class statements. For example, we just talked about "short and long
733 forms of options and operations". However, experienced 'tar' users
734 often refer to these by shorthand terms such as, "short and long
735 options". This term assumes that the "operations" are included, also.
736 Context will help you determine which definition of "options" to use.
738 Similarly, the term "command" can be confusing, as it is often used
739 in two different ways. People sometimes refer to 'tar' "commands". A
740 'tar' "command" is the entire command line of user input which tells
741 'tar' what to do -- including the operation, options, and any arguments
742 (file names, pipes, other commands, etc.). However, you will also
743 sometimes hear the term "the 'tar' command". When the word "command" is
744 used specifically like this, a person is usually referring to the 'tar'
745 _operation_, not the whole line. Again, use context to figure out which
746 of the meanings the speaker intends.
749 File: tar.info, Node: frequent operations, Next: Two Frequent Options, Prev: basic tar options, Up: Tutorial
751 2.4 The Three Most Frequently Used Operations
752 =============================================
754 Here are the three most frequently used operations (both short and long
755 forms), as well as a brief description of their meanings. The rest of
756 this chapter will cover how to use these operations in detail. We will
757 present the rest of the operations in the next chapter.
761 Create a new 'tar' archive.
764 List the contents of an archive.
767 Extract one or more members from an archive.
770 File: tar.info, Node: Two Frequent Options, Next: create, Prev: frequent operations, Up: Tutorial
772 2.5 Two Frequently Used Options
773 ===============================
775 To understand how to run 'tar' in the three operating modes listed
776 previously, you also need to understand how to use two of the options to
777 'tar': '--file' (which takes an archive file as an argument) and
778 '--verbose'. (You are usually not _required_ to specify either of these
779 options when you run 'tar', but they can be very useful in making things
780 more clear and helping you avoid errors.)
789 File: tar.info, Node: file tutorial, Next: verbose tutorial, Up: Two Frequent Options
794 '--file=ARCHIVE-NAME'
796 Specify the name of an archive file.
798 You can specify an argument for the '--file=ARCHIVE-NAME' ('-f
799 ARCHIVE-NAME') option whenever you use 'tar'; this option determines the
800 name of the archive file that 'tar' will work on.
802 If you don't specify this argument, then 'tar' will examine the
803 environment variable 'TAPE'. If it is set, its value will be used as
804 the archive name. Otherwise, 'tar' will use the default archive,
805 determined at compile time. Usually it is standard output or some
806 physical tape drive attached to your machine (you can verify what the
807 default is by running 'tar --show-defaults', *note defaults::). If
808 there is no tape drive attached, or the default is not meaningful, then
809 'tar' will print an error message. The error message might look roughly
810 like one of the following:
812 tar: can't open /dev/rmt8 : No such device or address
813 tar: can't open /dev/rsmt0 : I/O error
815 To avoid confusion, we recommend that you always specify an archive file
816 name by using '--file=ARCHIVE-NAME' ('-f ARCHIVE-NAME') when writing
817 your 'tar' commands. For more information on using the
818 '--file=ARCHIVE-NAME' ('-f ARCHIVE-NAME') option, see *note file::.
821 File: tar.info, Node: verbose tutorial, Next: help tutorial, Prev: file tutorial, Up: Two Frequent Options
823 The '--verbose' Option
824 ----------------------
828 Show the files being worked on as 'tar' is running.
830 '--verbose' ('-v') shows details about the results of running 'tar'.
831 This can be especially useful when the results might not be obvious.
832 For example, if you want to see the progress of 'tar' as it writes files
833 into the archive, you can use the '--verbose' option. In the beginning,
834 you may find it useful to use '--verbose' at all times; when you are
835 more accustomed to 'tar', you will likely want to use it at certain
836 times but not at others. We will use '--verbose' at times to help make
837 something clear, and we will give many examples both using and not using
838 '--verbose' to show the differences.
840 Each instance of '--verbose' on the command line increases the
841 verbosity level by one, so if you need more details on the output,
844 When reading archives ('--list', '--extract', '--diff'), 'tar' by
845 default prints only the names of the members being extracted. Using
846 '--verbose' will show a full, 'ls' style member listing.
848 In contrast, when writing archives ('--create', '--append',
849 '--update'), 'tar' does not print file names by default. So, a single
850 '--verbose' option shows the file names being added to the archive,
851 while two '--verbose' options enable the full listing.
853 For example, to create an archive in verbose mode:
855 $ tar -cvf afiles.tar apple angst aspic
860 Creating the same archive with the verbosity level 2 could give:
862 $ tar -cvvf afiles.tar apple angst aspic
863 -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
864 -rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst
865 -rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic
867 This works equally well using short or long forms of options. Using
868 long forms, you would simply write out the mnemonic form of the option
871 $ tar --create --verbose --verbose ...
873 Note that you must double the hyphens properly each time.
875 Later in the tutorial, we will give examples using
876 '--verbose --verbose'.
878 The full output consists of six fields:
880 * File type and permissions in symbolic form. These are displayed in
881 the same format as the first column of 'ls -l' output (*note
882 format=verbose: (fileutils)What information is listed.).
884 * Owner name and group separated by a slash character. If these data
885 are not available (for example, when listing a 'v7' format
886 archive), numeric ID values are printed instead.
888 * Size of the file, in bytes.
890 * File modification date in ISO 8601 format.
892 * File modification time.
894 * File name. If the name contains any special characters (white
895 space, newlines, etc.) these are displayed in an unambiguous form
896 using so called "quoting style". For the detailed discussion of
897 available styles and on how to use them, see *note quoting
900 Depending on the file type, the name can be followed by some
901 additional information, described in the following table:
904 The file or archive member is a "symbolic link" and LINK-NAME
905 is the name of file it links to.
908 The file or archive member is a "hard link" and LINK-NAME is
909 the name of file it links to.
912 The archive member is an old GNU format long link. You will
913 normally not encounter this.
916 The archive member is an old GNU format long name. You will
917 normally not encounter this.
920 The archive member is a GNU "volume header" (*note Tape
923 '--Continued at byte N--'
924 Encountered only at the beginning of a multi-volume archive
925 (*note Using Multiple Tapes::). This archive member is a
926 continuation from the previous volume. The number N gives the
927 offset where the original file was split.
929 'unknown file type C'
930 An archive member of unknown type. C is the type character
931 from the archive header. If you encounter such a message, it
932 means that either your archive contains proprietary member
933 types GNU 'tar' is not able to handle, or the archive is
936 For example, here is an archive listing containing most of the
937 special suffixes explained above:
939 V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header--
940 -rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at byte 32456--
941 -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
942 lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple
943 -rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
944 hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues
948 File: tar.info, Node: help tutorial, Prev: verbose tutorial, Up: Two Frequent Options
950 Getting Help: Using the '--help' Option
951 ---------------------------------------
955 The '--help' option to 'tar' prints out a very brief list of all
956 operations and option available for the current version of 'tar'
957 available on your system.
960 File: tar.info, Node: create, Next: list, Prev: Two Frequent Options, Up: Tutorial
962 2.6 How to Create Archives
963 ==========================
965 One of the basic operations of 'tar' is '--create' ('-c'), which you use
966 to create a 'tar' archive. We will explain '--create' first because, in
967 order to learn about the other operations, you will find it useful to
968 have an archive available to practice on.
970 To make this easier, in this section you will first create a
971 directory containing three files. Then, we will show you how to create
972 an _archive_ (inside the new directory). Both the directory, and the
973 archive are specifically for you to practice on. The rest of this
974 chapter and the next chapter will show many examples using this
975 directory and the files you will create: some of those files may be
976 other directories and other archives.
978 The three files you will archive in this example are called 'blues',
979 'folk', and 'jazz'. The archive is called 'collection.tar'.
981 This section will proceed slowly, detailing how to use '--create' in
982 'verbose' mode, and showing examples using both short and long forms.
983 In the rest of the tutorial, and in the examples in the next chapter, we
984 will proceed at a slightly quicker pace. This section moves more slowly
985 to allow beginning users to understand how 'tar' works.
989 * prepare for examples::
990 * Creating the archive::
996 File: tar.info, Node: prepare for examples, Next: Creating the archive, Up: create
998 2.6.1 Preparing a Practice Directory for Examples
999 -------------------------------------------------
1001 To follow along with this and future examples, create a new directory
1002 called 'practice' containing files called 'blues', 'folk' and 'jazz'.
1003 The files can contain any information you like: ideally, they should
1004 contain information which relates to their names, and be of different
1005 lengths. Our examples assume that 'practice' is a subdirectory of your
1008 Now 'cd' to the directory named 'practice'; 'practice' is now your
1009 "working directory". (_Please note_: Although the full file name of
1010 this directory is '/HOMEDIR/practice', in our examples we will refer to
1011 this directory as 'practice'; the HOMEDIR is presumed.)
1013 In general, you should check that the files to be archived exist
1014 where you think they do (in the working directory) by running 'ls'.
1015 Because you just created the directory and the files and have changed to
1016 that directory, you probably don't need to do that this time.
1018 It is very important to make sure there isn't already a file in the
1019 working directory with the archive name you intend to use (in this case,
1020 'collection.tar'), or that you don't care about its contents. Whenever
1021 you use 'create', 'tar' will erase the current contents of the file
1022 named by '--file=ARCHIVE-NAME' ('-f ARCHIVE-NAME') if it exists. 'tar'
1023 will not tell you if you are about to overwrite an archive unless you
1024 specify an option which does this (*note backup::, for the information
1025 on how to do so). To add files to an existing archive, you need to use
1026 a different option, such as '--append' ('-r'); see *note append:: for
1027 information on how to do this.
1030 File: tar.info, Node: Creating the archive, Next: create verbose, Prev: prepare for examples, Up: create
1032 2.6.2 Creating the Archive
1033 --------------------------
1035 To place the files 'blues', 'folk', and 'jazz' into an archive named
1036 'collection.tar', use the following command:
1038 $ tar --create --file=collection.tar blues folk jazz
1040 The order of the arguments is not very important, _when using long
1041 option forms_, however you should always remember to use option as the
1042 first argument to tar. For example, the following is wrong:
1044 $ tar blues -c folk -f collection.tar jazz
1045 tar: -c: Invalid blocking factor
1046 Try 'tar --help' or 'tar --usage' for more information.
1048 The error message is produced because 'tar' always treats its first
1049 argument as an option (or cluster of options), even if it does not start
1050 with dash. This is "traditional" or "old option" style, called so
1051 because all implementations of 'tar' have used it since the very
1052 inception of the tar archiver in 1970s. This option style will be
1053 explained later (*note Old Options::), for now just remember to always
1054 place option as the first argument.
1056 That being said, you could issue the following command:
1058 $ tar --create folk blues --file=collection.tar jazz
1060 However, you can see that this order is harder to understand; this is
1061 why we will list the arguments in the order that makes the commands
1062 easiest to understand (and we encourage you to do the same when you use
1063 'tar', to avoid errors).
1065 Note that the sequence '--file=collection.tar' is considered to be
1066 _one_ argument. If you substituted any other string of characters for
1067 'collection.tar', then that string would become the name of the archive
1070 The order of the options becomes more important when you begin to use
1071 short forms. With short forms, if you type commands in the wrong order
1072 (even if you type them correctly in all other ways), you may end up with
1073 results you don't expect. For this reason, it is a good idea to get
1074 into the habit of typing options in the order that makes inherent sense.
1075 *Note short create::, for more information on this.
1077 In this example, you type the command as shown above: '--create' is
1078 the operation which creates the new archive ('collection.tar'), and
1079 '--file' is the option which lets you give it the name you chose. The
1080 files, 'blues', 'folk', and 'jazz', are now members of the archive,
1081 'collection.tar' (they are "file name arguments" to the '--create'
1082 operation. *Note Choosing::, for the detailed discussion on these.)
1083 Now that they are in the archive, they are called _archive members_, not
1084 files. (*note members: Definitions.).
1086 When you create an archive, you _must_ specify which files you want
1087 placed in the archive. If you do not specify any archive members, GNU
1088 'tar' will complain.
1090 If you now list the contents of the working directory ('ls'), you
1091 will find the archive file listed as well as the files you saw
1094 blues folk jazz collection.tar
1096 Creating the archive 'collection.tar' did not destroy the copies of the
1097 files in the directory.
1099 Keep in mind that if you don't indicate an operation, 'tar' will not
1100 run and will prompt you for one. If you don't name any files, 'tar'
1101 will complain. You must have write access to the working directory, or
1102 else you will not be able to create an archive in that directory.
1104 _Caution_: Do not attempt to use '--create' ('-c') to add files to an
1105 existing archive; it will delete the archive and write a new one. Use
1106 '--append' ('-r') instead. *Note append::.
1109 File: tar.info, Node: create verbose, Next: short create, Prev: Creating the archive, Up: create
1111 2.6.3 Running '--create' with '--verbose'
1112 -----------------------------------------
1114 If you include the '--verbose' ('-v') option on the command line, 'tar'
1115 will list the files it is acting on as it is working. In verbose mode,
1116 the 'create' example above would appear as:
1118 $ tar --create --verbose --file=collection.tar blues folk jazz
1123 This example is just like the example we showed which did not use
1124 '--verbose', except that 'tar' generated the remaining lines.
1126 In the rest of the examples in this chapter, we will frequently use
1127 'verbose' mode so we can show actions or 'tar' responses that you would
1128 otherwise not see, and which are important for you to understand.
1131 File: tar.info, Node: short create, Next: create dir, Prev: create verbose, Up: create
1133 2.6.4 Short Forms with 'create'
1134 -------------------------------
1136 As we said before, the '--create' ('-c') operation is one of the most
1137 basic uses of 'tar', and you will use it countless times. Eventually,
1138 you will probably want to use abbreviated (or "short") forms of options.
1139 A full discussion of the three different forms that options can take
1140 appears in *note Styles::; for now, here is what the previous example
1141 (including the '--verbose' ('-v') option) looks like using short option
1144 $ tar -cvf collection.tar blues folk jazz
1149 As you can see, the system responds the same no matter whether you use
1150 long or short option forms.
1152 One difference between using short and long option forms is that,
1153 although the exact placement of arguments following options is no more
1154 specific when using short forms, it is easier to become confused and
1155 make a mistake when using short forms. For example, suppose you
1156 attempted the above example in the following way:
1158 $ tar -cfv collection.tar blues folk jazz
1160 In this case, 'tar' will make an archive file called 'v', containing the
1161 files 'blues', 'folk', and 'jazz', because the 'v' is the closest "file
1162 name" to the '-f' option, and is thus taken to be the chosen archive
1163 file name. 'tar' will try to add a file called 'collection.tar' to the
1164 'v' archive file; if the file 'collection.tar' did not already exist,
1165 'tar' will report an error indicating that this file does not exist. If
1166 the file 'collection.tar' does already exist (e.g., from a previous
1167 command you may have run), then 'tar' will add this file to the archive.
1168 Because the '-v' option did not get registered, 'tar' will not run under
1169 'verbose' mode, and will not report its progress.
1171 The end result is that you may be quite confused about what happened,
1172 and possibly overwrite a file. To illustrate this further, we will show
1173 you how an example we showed previously would look using short forms.
1177 $ tar --create folk blues --file=collection.tar jazz
1179 is confusing as it is. It becomes even more so when using short forms:
1181 $ tar -c folk blues -f collection.tar jazz
1183 It would be very easy to put the wrong string of characters immediately
1184 following the '-f', but doing that could sacrifice valuable data.
1186 For this reason, we recommend that you pay very careful attention to
1187 the order of options and placement of file and archive names, especially
1188 when using short option forms. Not having the option name written out
1189 mnemonically can affect how well you remember which option does what,
1190 and therefore where different names have to be placed.
1193 File: tar.info, Node: create dir, Prev: short create, Up: create
1195 2.6.5 Archiving Directories
1196 ---------------------------
1198 You can archive a directory by specifying its directory name as a file
1199 name argument to 'tar'. The files in the directory will be archived
1200 relative to the working directory, and the directory will be re-created
1201 along with its contents when the archive is extracted.
1203 To archive a directory, first move to its superior directory. If you
1204 have followed the previous instructions in this tutorial, you should
1210 This will put you into the directory which contains 'practice', i.e.,
1211 your home directory. Once in the superior directory, you can specify
1212 the subdirectory, 'practice', as a file name argument. To store
1213 'practice' in the new archive file 'music.tar', type:
1215 $ tar --create --verbose --file=music.tar practice
1217 'tar' should output:
1223 practice/collection.tar
1225 Note that the archive thus created is not in the subdirectory
1226 'practice', but rather in the current working directory--the directory
1227 from which 'tar' was invoked. Before trying to archive a directory from
1228 its superior directory, you should make sure you have write access to
1229 the superior directory itself, not only the directory you are trying
1230 archive with 'tar'. For example, you will probably not be able to store
1231 your home directory in an archive by invoking 'tar' from the root
1232 directory; *Note absolute::. (Note also that 'collection.tar', the
1233 original archive file, has itself been archived. 'tar' will accept any
1234 file as a file to be archived, regardless of its content. When
1235 'music.tar' is extracted, the archive file 'collection.tar' will be
1236 re-written into the file system).
1238 If you give 'tar' a command such as
1240 $ tar --create --file=foo.tar .
1242 'tar' will report 'tar: ./foo.tar is the archive; not dumped'. This
1243 happens because 'tar' creates the archive 'foo.tar' in the current
1244 directory before putting any files into it. Then, when 'tar' attempts
1245 to add all the files in the directory '.' to the archive, it notices
1246 that the file './foo.tar' is the same as the archive 'foo.tar', and
1247 skips it. (It makes no sense to put an archive into itself.) GNU 'tar'
1248 will continue in this case, and create the archive normally, except for
1249 the exclusion of that one file. (_Please note:_ Other implementations
1250 of 'tar' may not be so clever; they will enter an infinite loop when
1251 this happens, so you should not depend on this behavior unless you are
1252 certain you are running GNU 'tar'. In general, it is wise to always
1253 place the archive outside of the directory being dumped.)
1256 File: tar.info, Node: list, Next: extract, Prev: create, Up: Tutorial
1258 2.7 How to List Archives
1259 ========================
1261 Frequently, you will find yourself wanting to determine exactly what a
1262 particular archive contains. You can use the '--list' ('-t') operation
1263 to get the member names as they currently appear in the archive, as well
1264 as various attributes of the files at the time they were archived. For
1265 example, assuming 'practice' is your working directory, you can examine
1266 the archive 'collection.tar' that you created in the last section with
1269 $ tar --list --file=collection.tar
1271 The output of 'tar' would then be:
1277 Be sure to use a '--file=ARCHIVE-NAME' ('-f ARCHIVE-NAME') option just
1278 as with '--create' ('-c') to specify the name of the archive.
1280 You can specify one or more individual member names as arguments when
1281 using 'list'. In this case, 'tar' will only list the names of members
1282 you identify. For example, 'tar --list --file=collection.tar folk'
1283 would only print 'folk':
1285 $ tar --list --file=collection.tar folk
1288 If you use the '--verbose' ('-v') option with '--list', then 'tar'
1289 will print out a listing reminiscent of 'ls -l', showing owner, file
1290 size, and so forth. This output is described in detail in *note verbose
1293 If you had used '--verbose' ('-v') mode, the example above would look
1296 $ tar --list --verbose --file=collection.tar folk
1297 -rw-r--r-- myself/user 62 1990-05-23 10:55 folk
1299 It is important to notice that the output of 'tar --list --verbose'
1300 does not necessarily match that produced by 'tar --create --verbose'
1301 while creating the archive. It is because GNU 'tar', unless told
1302 explicitly not to do so, removes some directory prefixes from file names
1303 before storing them in the archive (*Note absolute::, for more
1304 information). In other words, in verbose mode GNU 'tar' shows "file
1305 names" when creating an archive and "member names" when listing it.
1306 Consider this example, run from your home directory:
1308 $ tar --create --verbose --file practice.tar ~/practice
1309 tar: Removing leading '/' from member names
1310 /home/myself/practice/
1311 /home/myself/practice/blues
1312 /home/myself/practice/folk
1313 /home/myself/practice/jazz
1314 /home/myself/practice/collection.tar
1315 $ tar --test --file practice.tar
1316 home/myself/practice/
1317 home/myself/practice/blues
1318 home/myself/practice/folk
1319 home/myself/practice/jazz
1320 home/myself/practice/collection.tar
1322 This default behavior can sometimes be inconvenient. You can force
1323 GNU 'tar' show member names when creating archive by supplying
1324 '--show-stored-names' option.
1326 '--show-stored-names'
1327 Print member (as opposed to _file_) names when creating the
1330 With this option, both commands produce the same output:
1332 $ tar --create --verbose --show-stored-names \
1333 --file practice.tar ~/practice
1334 tar: Removing leading '/' from member names
1335 home/myself/practice/
1336 home/myself/practice/blues
1337 home/myself/practice/folk
1338 home/myself/practice/jazz
1339 home/myself/practice/collection.tar
1340 $ tar --test --file practice.tar
1341 home/myself/practice/
1342 home/myself/practice/blues
1343 home/myself/practice/folk
1344 home/myself/practice/jazz
1345 home/myself/practice/collection.tar
1347 Since 'tar' preserves file names, those you wish to list must be
1348 specified as they appear in the archive (i.e., relative to the directory
1349 from which the archive was created). Continuing the example above:
1351 $ tar --list --file=practice.tar folk
1352 tar: folk: Not found in archive
1353 tar: Exiting with failure status due to previous errors
1355 the error message is produced because there is no member named
1356 'folk', only one named 'home/myself/folk'.
1358 If you are not sure of the exact file name, use "globbing patterns",
1361 $ tar --list --file=practice.tar --wildcards '*/folk'
1362 home/myself/practice/folk
1364 *Note wildcards::, for a detailed discussion of globbing patterns and
1365 related 'tar' command line options.
1372 File: tar.info, Node: list dir, Up: list
1374 Listing the Contents of a Stored Directory
1375 ------------------------------------------
1377 To get information about the contents of an archived directory, use the
1378 directory name as a file name argument in conjunction with '--list'
1379 ('-t'). To find out file attributes, include the '--verbose' ('-v')
1382 For example, to find out about files in the directory 'practice', in
1383 the archive file 'music.tar', type:
1385 $ tar --list --verbose --file=music.tar practice
1389 drwxrwxrwx myself/user 0 1990-05-31 21:49 practice/
1390 -rw-r--r-- myself/user 42 1990-05-21 13:29 practice/blues
1391 -rw-r--r-- myself/user 62 1990-05-23 10:55 practice/folk
1392 -rw-r--r-- myself/user 40 1990-05-21 13:30 practice/jazz
1393 -rw-r--r-- myself/user 10240 1990-05-31 21:49 practice/collection.tar
1395 When you use a directory name as a file name argument, 'tar' acts on
1396 all the files (including sub-directories) in that directory.
1399 File: tar.info, Node: extract, Next: going further, Prev: list, Up: Tutorial
1401 2.8 How to Extract Members from an Archive
1402 ==========================================
1404 Creating an archive is only half the job--there is no point in storing
1405 files in an archive if you can't retrieve them. The act of retrieving
1406 members from an archive so they can be used and manipulated as
1407 unarchived files again is called "extraction". To extract files from an
1408 archive, use the '--extract' ('--get' or '-x') operation. As with
1409 '--create', specify the name of the archive with '--file' ('-f') option.
1410 Extracting an archive does not modify the archive in any way; you can
1411 extract it multiple times if you want or need to.
1413 Using '--extract', you can extract an entire archive, or specific
1414 files. The files can be directories containing other files, or not. As
1415 with '--create' ('-c') and '--list' ('-t'), you may use the short or the
1416 long form of the operation without affecting the performance.
1420 * extracting archives::
1421 * extracting files::
1423 * extracting untrusted archives::
1424 * failing commands::
1427 File: tar.info, Node: extracting archives, Next: extracting files, Up: extract
1429 2.8.1 Extracting an Entire Archive
1430 ----------------------------------
1432 To extract an entire archive, specify the archive file name only, with
1433 no individual file names as arguments. For example,
1435 $ tar -xvf collection.tar
1439 -rw-r--r-- myself/user 28 1996-10-18 16:31 jazz
1440 -rw-r--r-- myself/user 21 1996-09-23 16:44 blues
1441 -rw-r--r-- myself/user 20 1996-09-23 16:44 folk
1444 File: tar.info, Node: extracting files, Next: extract dir, Prev: extracting archives, Up: extract
1446 2.8.2 Extracting Specific Files
1447 -------------------------------
1449 To extract specific archive members, give their exact member names as
1450 arguments, as printed by '--list' ('-t'). If you had mistakenly deleted
1451 one of the files you had placed in the archive 'collection.tar' earlier
1452 (say, 'blues'), you can extract it from the archive without changing the
1453 archive's structure. Its contents will be identical to the original
1454 file 'blues' that you deleted.
1456 First, make sure you are in the 'practice' directory, and list the
1457 files in the directory. Now, delete the file, 'blues', and list the
1458 files in the directory again.
1460 You can now extract the member 'blues' from the archive file
1461 'collection.tar' like this:
1463 $ tar --extract --file=collection.tar blues
1465 If you list the files in the directory again, you will see that the file
1466 'blues' has been restored, with its original permissions, data
1467 modification times, and owner.(1) (These parameters will be identical
1468 to those which the file had when you originally placed it in the
1469 archive; any changes you may have made before deleting the file from the
1470 file system, however, will _not_ have been made to the archive member.)
1471 The archive file, 'collection.tar', is the same as it was before you
1472 extracted 'blues'. You can confirm this by running 'tar' with '--list'
1475 Remember that as with other operations, specifying the exact member
1476 name is important (*Note failing commands::, for more examples).
1478 You can extract a file to standard output by combining the above
1479 options with the '--to-stdout' ('-O') option (*note Writing to Standard
1482 If you give the '--verbose' option, then '--extract' will print the
1483 names of the archive members as it extracts them.
1485 ---------- Footnotes ----------
1487 (1) This is only accidentally true, but not in general. Whereas
1488 modification times are always restored, in most cases, one has to be
1489 root for restoring the owner, and use a special option for restoring
1490 permissions. Here, it just happens that the restoring user is also the
1491 owner of the archived members, and that the current 'umask' is
1492 compatible with original permissions.
1495 File: tar.info, Node: extract dir, Next: extracting untrusted archives, Prev: extracting files, Up: extract
1497 2.8.3 Extracting Files that are Directories
1498 -------------------------------------------
1500 Extracting directories which are members of an archive is similar to
1501 extracting other files. The main difference to be aware of is that if
1502 the extracted directory has the same name as any directory already in
1503 the working directory, then files in the extracted directory will be
1504 placed into the directory of the same name. Likewise, if there are
1505 files in the pre-existing directory with the same names as the members
1506 which you extract, the files from the extracted archive will replace the
1507 files already in the working directory (and possible subdirectories).
1508 This will happen regardless of whether or not the files in the working
1509 directory were more recent than those extracted (there exist, however,
1510 special options that alter this behavior *note Writing::).
1512 However, if a file was stored with a directory name as part of its
1513 file name, and that directory does not exist under the working directory
1514 when the file is extracted, 'tar' will create the directory.
1516 We can demonstrate how to use '--extract' to extract a directory file
1517 with an example. Change to the 'practice' directory if you weren't
1518 there, and remove the files 'folk' and 'jazz'. Then, go back to the
1519 parent directory and extract the archive 'music.tar'. You may either
1520 extract the entire archive, or you may extract only the files you just
1521 deleted. To extract the entire archive, don't give any file names as
1522 arguments after the archive name 'music.tar'. To extract only the files
1523 you deleted, use the following command:
1525 $ tar -xvf music.tar practice/folk practice/jazz
1529 If you were to specify two '--verbose' ('-v') options, 'tar' would have
1530 displayed more detail about the extracted files, as shown in the example
1533 $ tar -xvvf music.tar practice/folk practice/jazz
1534 -rw-r--r-- me/user 28 1996-10-18 16:31 practice/jazz
1535 -rw-r--r-- me/user 20 1996-09-23 16:44 practice/folk
1537 Because you created the directory with 'practice' as part of the file
1538 names of each of the files by archiving the 'practice' directory as
1539 'practice', you must give 'practice' as part of the file names when you
1540 extract those files from the archive.
1543 File: tar.info, Node: extracting untrusted archives, Next: failing commands, Prev: extract dir, Up: extract
1545 2.8.4 Extracting Archives from Untrusted Sources
1546 ------------------------------------------------
1548 Extracting files from archives can overwrite files that already exist.
1549 If you receive an archive from an untrusted source, you should make a
1550 new directory and extract into that directory, so that you don't have to
1551 worry about the extraction overwriting one of your existing files. For
1552 example, if 'untrusted.tar' came from somewhere else on the Internet,
1553 and you don't necessarily trust its contents, you can extract it as
1558 $ tar -xvf ../untrusted.tar
1560 It is also a good practice to examine contents of the archive before
1561 extracting it, using '--list' ('-t') option, possibly combined with
1565 File: tar.info, Node: failing commands, Prev: extracting untrusted archives, Up: extract
1567 2.8.5 Commands That Will Fail
1568 -----------------------------
1570 Here are some sample commands you might try which will not work, and why
1573 If you try to use this command,
1575 $ tar -xvf music.tar folk jazz
1577 you will get the following response:
1579 tar: folk: Not found in archive
1580 tar: jazz: Not found in archive
1582 This is because these files were not originally _in_ the parent
1583 directory '..', where the archive is located; they were in the
1584 'practice' directory, and their file names reflect this:
1586 $ tar -tvf music.tar
1591 Likewise, if you try to use this command,
1593 $ tar -tvf music.tar folk jazz
1595 you would get a similar response. Members with those names are not in
1596 the archive. You must use the correct member names, or wildcards, in
1597 order to extract the files from the archive.
1599 If you have forgotten the correct names of the files in the archive,
1600 use 'tar --list --verbose' to list them correctly.
1602 To extract the member named 'practice/folk', you must specify
1604 $ tar --extract --file=music.tar practice/folk
1606 Notice also, that as explained above, the 'practice' directory will be
1607 created, if it didn't already exist. There are options that allow you
1608 to strip away a certain number of leading directory components (*note
1609 transform::). For example,
1611 $ tar --extract --file=music.tar --strip-components=1 folk
1613 will extract the file 'folk' into the current working directory.
1616 File: tar.info, Node: going further, Prev: extract, Up: Tutorial
1618 2.9 Going Further Ahead in this Manual
1619 ======================================
1621 _(This message will disappear, once this node revised.)_
1624 File: tar.info, Node: tar invocation, Next: operations, Prev: Tutorial, Up: Top
1626 3 Invoking GNU 'tar'
1627 ********************
1629 This chapter is about how one invokes the GNU 'tar' command, from the
1630 command synopsis (*note Synopsis::). There are numerous options, and
1631 many styles for writing them. One mandatory option specifies the
1632 operation 'tar' should perform (*note Operation Summary::), other
1633 options are meant to detail how this operation should be performed
1634 (*note Option Summary::). Non-option arguments are not always
1635 interpreted the same way, depending on what the operation is.
1637 You will find in this chapter everything about option styles and
1638 rules for writing them (*note Styles::). On the other hand, operations
1639 and options are fully described elsewhere, in other chapters. Here, you
1640 will find only synthetic descriptions for operations and options,
1641 together with pointers to other parts of the 'tar' manual.
1643 Some options are so special they are fully described right in this
1644 chapter. They have the effect of inhibiting the normal operation of
1645 'tar' or else, they globally alter the amount of feedback the user
1646 receives about what is going on. These are the '--help' and '--version'
1647 (*note help::), '--verbose' (*note verbose::) and '--interactive'
1648 options (*note interactive::).
1653 * using tar options::
1655 * All Options:: All 'tar' Options.
1656 * help:: Where to Get Help.
1657 * defaults:: What are the Default Values.
1658 * verbose:: Checking 'tar' progress.
1659 * checkpoints:: Checkpoints.
1660 * warnings:: Controlling Warning Messages.
1661 * interactive:: Asking for Confirmation During Operations.
1662 * external:: Running External Commands.
1665 File: tar.info, Node: Synopsis, Next: using tar options, Up: tar invocation
1667 3.1 General Synopsis of 'tar'
1668 =============================
1670 The GNU 'tar' program is invoked as either one of:
1672 tar OPTION... [NAME]...
1673 tar LETTER... [ARGUMENT]... [OPTION]... [NAME]...
1675 The second form is for when old options are being used.
1677 You can use 'tar' to store files in an archive, to extract them from
1678 an archive, and to do other types of archive manipulation. The primary
1679 argument to 'tar', which is called the "operation", specifies which
1680 action to take. The other arguments to 'tar' are either "options",
1681 which change the way 'tar' performs an operation, or file names or
1682 archive members, which specify the files or members 'tar' is to act on.
1684 You can actually type in arguments in any order, even if in this
1685 manual the options always precede the other arguments, to make examples
1686 easier to understand. Further, the option stating the main operation
1687 mode (the 'tar' main command) is usually given first.
1689 Each NAME in the synopsis above is interpreted as an archive member
1690 name when the main command is one of '--compare' ('--diff', '-d'),
1691 '--delete', '--extract' ('--get', '-x'), '--list' ('-t') or '--update'
1692 ('-u'). When naming archive members, you must give the exact name of
1693 the member in the archive, as it is printed by '--list'. For '--append'
1694 ('-r') and '--create' ('-c'), these NAME arguments specify the names of
1695 either files or directory hierarchies to place in the archive. These
1696 files or hierarchies should already exist in the file system, prior to
1697 the execution of the 'tar' command.
1699 'tar' interprets relative file names as being relative to the working
1700 directory. 'tar' will make all file names relative (by removing leading
1701 slashes when archiving or restoring files), unless you specify otherwise
1702 (using the '--absolute-names' option). *Note absolute::, for more
1703 information about '--absolute-names'.
1705 If you give the name of a directory as either a file name or a member
1706 name, then 'tar' acts recursively on all the files and directories
1707 beneath that directory. For example, the name '/' identifies all the
1708 files in the file system to 'tar'.
1710 The distinction between file names and archive member names is
1711 especially important when shell globbing is used, and sometimes a source
1712 of confusion for newcomers. *Note wildcards::, for more information
1713 about globbing. The problem is that shells may only glob using existing
1714 files in the file system. Only 'tar' itself may glob on archive
1715 members, so when needed, you must ensure that wildcard characters reach
1716 'tar' without being interpreted by the shell first. Using a backslash
1717 before '*' or '?', or putting the whole argument between quotes, is
1718 usually sufficient for this.
1720 Even if NAMEs are often specified on the command line, they can also
1721 be read from a text file in the file system, using the
1722 '--files-from=FILE-OF-NAMES' ('-T FILE-OF-NAMES') option.
1724 If you don't use any file name arguments, '--append' ('-r'),
1725 '--delete' and '--concatenate' ('--catenate', '-A') will do nothing,
1726 while '--create' ('-c') will usually yield a diagnostic and inhibit
1727 'tar' execution. The other operations of 'tar' ('--list', '--extract',
1728 '--compare', and '--update') will act on the entire contents of the
1731 Besides successful exits, GNU 'tar' may fail for many reasons. Some
1732 reasons correspond to bad usage, that is, when the 'tar' command line is
1733 improperly written. Errors may be encountered later, while processing
1734 the archive or the files. Some errors are recoverable, in which case
1735 the failure is delayed until 'tar' has completed all its work. Some
1736 errors are such that it would be not meaningful, or at least risky, to
1737 continue processing: 'tar' then aborts processing immediately. All
1738 abnormal exits, whether immediate or delayed, should always be clearly
1739 diagnosed on 'stderr', after a line stating the nature of the error.
1741 Possible exit codes of GNU 'tar' are summarized in the following
1745 'Successful termination'.
1748 'Some files differ'. If tar was invoked with '--compare'
1749 ('--diff', '-d') command line option, this means that some files in
1750 the archive differ from their disk counterparts (*note compare::).
1751 If tar was given '--create', '--append' or '--update' option, this
1752 exit code means that some files were changed while being archived
1753 and so the resulting archive does not contain the exact copy of the
1757 'Fatal error'. This means that some fatal, unrecoverable error
1760 If 'tar' has invoked a subprocess and that subprocess exited with a
1761 nonzero exit code, 'tar' exits with that code as well. This can happen,
1762 for example, if 'tar' was given some compression option (*note gzip::)
1763 and the external compressor program failed. Another example is 'rmt'
1764 failure during backup to the remote device (*note Remote Tape Server::).
1767 File: tar.info, Node: using tar options, Next: Styles, Prev: Synopsis, Up: tar invocation
1769 3.2 Using 'tar' Options
1770 =======================
1772 GNU 'tar' has a total of eight operating modes which allow you to
1773 perform a variety of tasks. You are required to choose one operating
1774 mode each time you employ the 'tar' program by specifying one, and only
1775 one operation as an argument to the 'tar' command (the corresponding
1776 options may be found at *note frequent operations:: and *note
1777 Operations::). Depending on circumstances, you may also wish to
1778 customize how the chosen operating mode behaves. For example, you may
1779 wish to change the way the output looks, or the format of the files that
1780 you wish to archive may require you to do something special in order to
1781 make the archive look right.
1783 You can customize and control 'tar''s performance by running 'tar'
1784 with one or more options (such as '--verbose' ('-v'), which we used in
1785 the tutorial). As we said in the tutorial, "options" are arguments to
1786 'tar' which are (as their name suggests) optional. Depending on the
1787 operating mode, you may specify one or more options. Different options
1788 will have different effects, but in general they all change details of
1789 the operation, such as archive format, archive name, or level of user
1790 interaction. Some options make sense with all operating modes, while
1791 others are meaningful only with particular modes. You will likely use
1792 some options frequently, while you will only use others infrequently, or
1793 not at all. (A full list of options is available in *note All
1796 The 'TAR_OPTIONS' environment variable specifies default options to
1797 be placed in front of any explicit options. For example, if
1798 'TAR_OPTIONS' is '-v --unlink-first', 'tar' behaves as if the two
1799 options '-v' and '--unlink-first' had been specified before any explicit
1800 options. Option specifications are separated by whitespace. A
1801 backslash escapes the next character, so it can be used to specify an
1802 option containing whitespace or a backslash.
1804 Note that 'tar' options are case sensitive. For example, the options
1805 '-T' and '-t' are different; the first requires an argument for stating
1806 the name of a file providing a list of NAMEs, while the second does not
1807 require an argument and is another way to write '--list' ('-t').
1809 In addition to the eight operations, there are many options to 'tar',
1810 and three different styles for writing both: long (mnemonic) form, short
1811 form, and old style. These styles are discussed below. Both the
1812 options and the operations can be written in any of these three styles.
1815 File: tar.info, Node: Styles, Next: All Options, Prev: using tar options, Up: tar invocation
1817 3.3 The Three Option Styles
1818 ===========================
1820 There are three styles for writing operations and options to the command
1821 line invoking 'tar'. The different styles were developed at different
1822 times during the history of 'tar'. These styles will be presented
1823 below, from the most recent to the oldest.
1825 Some options must take an argument(1). Where you _place_ the
1826 arguments generally depends on which style of options you choose. We
1827 will detail specific information relevant to each option style in the
1828 sections on the different option styles, below. The differences are
1829 subtle, yet can often be very important; incorrect option placement can
1830 cause you to overwrite a number of important files. We urge you to note
1831 these differences, and only use the option style(s) which makes the most
1832 sense to you until you feel comfortable with the others.
1834 Some options _may_ take an argument. Such options may have at most
1835 long and short forms, they do not have old style equivalent. The rules
1836 for specifying an argument for such options are stricter than those for
1837 specifying mandatory arguments. Please, pay special attention to them.
1841 * Long Options:: Long Option Style
1842 * Short Options:: Short Option Style
1843 * Old Options:: Old Option Style
1844 * Mixing:: Mixing Option Styles
1846 ---------- Footnotes ----------
1848 (1) For example, '--file' ('-f') takes the name of an archive file as
1849 an argument. If you do not supply an archive file name, 'tar' will use
1850 a default, but this can be confusing; thus, we recommend that you always
1851 supply a specific archive file name.
1854 File: tar.info, Node: Long Options, Next: Short Options, Up: Styles
1856 3.3.1 Long Option Style
1857 -----------------------
1859 Each option has at least one "long" (or "mnemonic") name starting with
1860 two dashes in a row, e.g., '--list'. The long names are more clear than
1861 their corresponding short or old names. It sometimes happens that a
1862 single long option has many different names which are synonymous, such
1863 as '--compare' and '--diff'. In addition, long option names can be
1864 given unique abbreviations. For example, '--cre' can be used in place
1865 of '--create' because there is no other long option which begins with
1866 'cre'. (One way to find this out is by trying it and seeing what
1867 happens; if a particular abbreviation could represent more than one
1868 option, 'tar' will tell you that that abbreviation is ambiguous and
1869 you'll know that that abbreviation won't work. You may also choose to
1870 run 'tar --help' to see a list of options. Be aware that if you run
1871 'tar' with a unique abbreviation for the long name of an option you
1872 didn't want to use, you are stuck; 'tar' will perform the command as
1875 Long options are meant to be obvious and easy to remember, and their
1876 meanings are generally easier to discern than those of their
1877 corresponding short options (see below). For example:
1879 $ tar --create --verbose --blocking-factor=20 --file=/dev/rmt0
1881 gives a fairly good set of hints about what the command does, even for
1882 those not fully acquainted with 'tar'.
1884 Long options which require arguments take those arguments immediately
1885 following the option name. There are two ways of specifying a mandatory
1886 argument. It can be separated from the option name either by an equal
1887 sign, or by any amount of white space characters. For example, the
1888 '--file' option (which tells the name of the 'tar' archive) is given a
1889 file such as 'archive.tar' as argument by using any of the following
1890 notations: '--file=archive.tar' or '--file archive.tar'.
1892 In contrast, optional arguments must always be introduced using an
1893 equal sign. For example, the '--backup' option takes an optional
1894 argument specifying backup type. It must be used as
1895 '--backup=BACKUP-TYPE'.
1898 File: tar.info, Node: Short Options, Next: Old Options, Prev: Long Options, Up: Styles
1900 3.3.2 Short Option Style
1901 ------------------------
1903 Most options also have a "short option" name. Short options start with
1904 a single dash, and are followed by a single character, e.g., '-t' (which
1905 is equivalent to '--list'). The forms are absolutely identical in
1906 function; they are interchangeable.
1908 The short option names are faster to type than long option names.
1910 Short options which require arguments take their arguments
1911 immediately following the option, usually separated by white space. It
1912 is also possible to stick the argument right after the short option
1913 name, using no intervening space. For example, you might write
1914 '-f archive.tar' or '-farchive.tar' instead of using
1915 '--file=archive.tar'. Both '--file=ARCHIVE-NAME' and '-f ARCHIVE-NAME'
1916 denote the option which indicates a specific archive, here named
1919 Short options which take optional arguments take their arguments
1920 immediately following the option letter, _without any intervening white
1923 Short options' letters may be clumped together, but you are not
1924 required to do this (as compared to old options; see below). When short
1925 options are clumped as a set, use one (single) dash for them all, e.g.,
1926 ''tar' -cvf'. Only the last option in such a set is allowed to have an
1929 When the options are separated, the argument for each option which
1930 requires an argument directly follows that option, as is usual for Unix
1931 programs. For example:
1933 $ tar -c -v -b 20 -f /dev/rmt0
1935 If you reorder short options' locations, be sure to move any
1936 arguments that belong to them. If you do not move the arguments
1937 properly, you may end up overwriting files.
1939 ---------- Footnotes ----------
1941 (1) Clustering many options, the last of which has an argument, is a
1942 rather opaque way to write options. Some wonder if GNU 'getopt' should
1943 not even be made helpful enough for considering such usages as invalid.
1946 File: tar.info, Node: Old Options, Next: Mixing, Prev: Short Options, Up: Styles
1948 3.3.3 Old Option Style
1949 ----------------------
1951 As far as we know, all 'tar' programs, GNU and non-GNU, support "old
1952 options": that is, if the first argument does not start with '-', it is
1953 assumed to specify option letters. GNU 'tar' supports old options not
1954 only for historical reasons, but also because many people are used to
1955 them. If the first argument does not start with a dash, you are
1956 announcing the old option style instead of the short option style; old
1957 options are decoded differently.
1959 Like short options, old options are single letters. However, old
1960 options must be written together as a single clumped set, without spaces
1961 separating them or dashes preceding them. This set of letters must be
1962 the first to appear on the command line, after the 'tar' program name
1963 and some white space; old options cannot appear anywhere else. The
1964 letter of an old option is exactly the same letter as the corresponding
1965 short option. For example, the old option 't' is the same as the short
1966 option '-t', and consequently, the same as the long option '--list'. So
1967 for example, the command 'tar cv' specifies the option '-v' in addition
1968 to the operation '-c'.
1970 When options that need arguments are given together with the command,
1971 all the associated arguments follow, in the same order as the options.
1972 Thus, the example given previously could also be written in the old
1975 $ tar cvbf 20 /dev/rmt0
1977 Here, '20' is the argument of '-b' and '/dev/rmt0' is the argument of
1980 The old style syntax can make it difficult to match option letters
1981 with their corresponding arguments, and is often confusing. In the
1982 command 'tar cvbf 20 /dev/rmt0', for example, '20' is the argument for
1983 '-b', '/dev/rmt0' is the argument for '-f', and '-v' does not have a
1984 corresponding argument. Even using short options like in
1985 'tar -c -v -b 20 -f /dev/rmt0' is clearer, putting all arguments next to
1986 the option they pertain to.
1988 If you want to reorder the letters in the old option argument, be
1989 sure to reorder any corresponding argument appropriately.
1991 This old way of writing 'tar' options can surprise even experienced
1992 users. For example, the two commands:
1994 tar cfz archive.tar.gz file
1995 tar -cfz archive.tar.gz file
1997 are quite different. The first example uses 'archive.tar.gz' as the
1998 value for option 'f' and recognizes the option 'z'. The second example,
1999 however, uses 'z' as the value for option 'f' -- probably not what was
2002 This second example could be corrected in many ways, among which the
2003 following are equivalent:
2005 tar -czf archive.tar.gz file
2006 tar -cf archive.tar.gz -z file
2007 tar cf archive.tar.gz -z file
2010 File: tar.info, Node: Mixing, Prev: Old Options, Up: Styles
2012 3.3.4 Mixing Option Styles
2013 --------------------------
2015 All three styles may be intermixed in a single 'tar' command, so long as
2016 the rules for each style are fully respected(1). Old style options and
2017 either of the modern styles of options may be mixed within a single
2018 'tar' command. However, old style options must be introduced as the
2019 first arguments only, following the rule for old options (old options
2020 must appear directly after the 'tar' command and some white space).
2021 Modern options may be given only after all arguments to the old options
2022 have been collected. If this rule is not respected, a modern option
2023 might be falsely interpreted as the value of the argument to one of the
2026 For example, all the following commands are wholly equivalent, and
2027 illustrate the many combinations and orderings of option styles.
2029 tar --create --file=archive.tar
2030 tar --create -f archive.tar
2031 tar --create -farchive.tar
2032 tar --file=archive.tar --create
2033 tar --file=archive.tar -c
2034 tar -c --file=archive.tar
2035 tar -c -f archive.tar
2036 tar -c -farchive.tar
2039 tar -f archive.tar --create
2040 tar -f archive.tar -c
2041 tar -farchive.tar --create
2042 tar -farchive.tar -c
2043 tar c --file=archive.tar
2044 tar c -f archive.tar
2047 tar f archive.tar --create
2048 tar f archive.tar -c
2051 On the other hand, the following commands are _not_ equivalent to the
2054 tar -f -c archive.tar
2060 These last examples mean something completely different from what the
2061 user intended (judging based on the example in the previous set which
2062 uses long options, whose intent is therefore very clear). The first
2063 four specify that the 'tar' archive would be a file named '-c', 'c',
2064 'carchive.tar' or 'archive.tarc', respectively. The first two examples
2065 also specify a single non-option, NAME argument having the value
2066 'archive.tar'. The last example contains only old style option letters
2067 (repeating option 'c' twice), not all of which are meaningful (eg., '.',
2068 'h', or 'i'), with no argument value.
2070 ---------- Footnotes ----------
2072 (1) Before GNU 'tar' version 1.11.6, a bug prevented intermixing old
2073 style options with long options in some cases.
2076 File: tar.info, Node: All Options, Next: help, Prev: Styles, Up: tar invocation
2078 3.4 All 'tar' Options
2079 =====================
2081 The coming manual sections contain an alphabetical listing of all 'tar'
2082 operations and options, with brief descriptions and cross-references to
2083 more in-depth explanations in the body of the manual. They also contain
2084 an alphabetically arranged table of the short option forms with their
2085 corresponding long option. You can use this table as a reference for
2086 deciphering 'tar' commands in scripts.
2090 * Operation Summary::
2092 * Short Option Summary::
2093 * Position-Sensitive Options::
2096 File: tar.info, Node: Operation Summary, Next: Option Summary, Up: All Options
2104 Appends files to the end of the archive. *Note append::.
2109 Same as '--concatenate'. *Note concatenate::.
2114 Compares archive members with their counterparts in the file
2115 system, and reports differences in file size, mode, owner,
2116 modification date and contents. *Note compare::.
2121 Appends other 'tar' archives to the end of the archive. *Note
2127 Creates a new 'tar' archive. *Note create::.
2131 Deletes members from the archive. Don't try this on an archive on
2132 a tape! *Note delete::.
2137 Same '--compare'. *Note compare::.
2142 Extracts members from the archive into the file system. *Note
2148 Same as '--extract'. *Note extract::.
2153 Lists the members in an archive. *Note list::.
2158 Adds files to the end of the archive, but only if they are newer
2159 than their counterparts already in the archive, or if they do not
2160 already exist in the archive. *Note update::.
2163 File: tar.info, Node: Option Summary, Next: Short Option Summary, Prev: Operation Summary, Up: All Options
2171 Normally when creating an archive, 'tar' strips an initial '/' from
2172 member names, and when extracting from an archive 'tar' treats
2173 names specially if they have initial '/' or internal '..'. This
2174 option disables that behavior. *Note absolute::.
2177 Enable POSIX ACLs support. *Note acls: Extended File Attributes.
2181 (See '--newer', *note after::)
2184 A pattern must match an initial subsequence of the name's
2185 components. *Note controlling pattern-matching::.
2188 '--atime-preserve=replace'
2189 '--atime-preserve=system'
2191 Attempt to preserve the access time of files when reading them.
2192 This option currently is effective only on files that you own,
2193 unless you have superuser privileges.
2195 '--atime-preserve=replace' remembers the access time of a file
2196 before reading it, and then restores the access time afterwards.
2197 This may cause problems if other programs are reading the file at
2198 the same time, as the times of their accesses will be lost. On
2199 most platforms restoring the access time also requires 'tar' to
2200 restore the data modification time too, so this option may also
2201 cause problems if other programs are writing the file at the same
2202 time ('tar' attempts to detect this situation, but cannot do so
2203 reliably due to race conditions). Worse, on most platforms
2204 restoring the access time also updates the status change time,
2205 which means that this option is incompatible with incremental
2208 '--atime-preserve=system' avoids changing time stamps on files,
2209 without interfering with time stamp updates caused by other
2210 programs, so it works better with incremental backups. However, it
2211 requires a special 'O_NOATIME' option from the underlying operating
2212 and file system implementation, and it also requires that searching
2213 directories does not update their access times. As of this writing
2214 (November 2005) this works only with Linux, and only with Linux
2215 kernels 2.6.8 and later. Worse, there is currently no reliable way
2216 to know whether this feature actually works. Sometimes 'tar' knows
2217 that it does not work, and if you use '--atime-preserve=system'
2218 then 'tar' complains and exits right away. But other times 'tar'
2219 might think that the option works when it actually does not.
2221 Currently '--atime-preserve' with no operand defaults to
2222 '--atime-preserve=replace', but this may change in the future as
2223 support for '--atime-preserve=system' improves.
2225 If your operating or file system does not support
2226 '--atime-preserve=system', you might be able to preserve access
2227 times reliably by using the 'mount' command. For example, you can
2228 mount the file system read-only, or access the file system via a
2229 read-only loopback mount, or use the 'noatime' mount option
2230 available on some systems. However, mounting typically requires
2231 superuser privileges and can be a pain to manage.
2236 During a '--create' operation, enables automatic compressed format
2237 recognition based on the archive suffix. The effect of this option
2238 is cancelled by '--no-auto-compress'. *Note gzip::.
2240 '--backup=BACKUP-TYPE'
2242 Rather than deleting files from the file system, 'tar' will back
2243 them up using simple or numbered backups, depending upon
2244 BACKUP-TYPE. *Note backup::.
2249 With this option present, 'tar' prints error messages for read
2250 errors with the block number in the archive file. *Note
2253 '--blocking-factor=BLOCKING'
2256 Sets the blocking factor 'tar' uses to BLOCKING x 512 bytes per
2257 record. *Note Blocking Factor::.
2262 This option tells 'tar' to read or write archives through 'bzip2'.
2266 Check device numbers when creating a list of modified files for
2267 incremental archiving. This is the default. *Note device
2268 numbers::, for a detailed description.
2270 '--checkpoint[=NUMBER]'
2272 This option directs 'tar' to print periodic checkpoint messages as
2273 it reads through the archive. It is intended for when you want a
2274 visual indication that 'tar' is still running, but don't want to
2275 see '--verbose' output. You can also instruct 'tar' to execute a
2276 list of actions on each checkpoint, see '--checkpoint-action'
2277 below. For a detailed description, see *note checkpoints::.
2279 '--checkpoint-action=ACTION'
2280 Instruct 'tar' to execute an action upon hitting a breakpoint.
2281 Here we give only a brief outline. *Note checkpoints::, for a
2282 complete description.
2284 The ACTION argument can be one of the following:
2287 Produce an audible bell on the console.
2291 Print a single dot on the standard listing stream.
2294 Display a textual message on the standard error, with the
2295 status and number of the checkpoint. This is the default.
2298 Display STRING on the standard error. Before output, the
2299 string is subject to meta-character expansion.
2302 Execute the given COMMAND.
2305 Wait for TIME seconds.
2308 Output STRING on the current console ('/dev/tty').
2310 Several '--checkpoint-action' options can be specified. The
2311 supplied actions will be executed in order of their appearance in
2314 Using '--checkpoint-action' without '--checkpoint' assumes default
2315 checkpoint frequency of one checkpoint per 10 records.
2319 If this option was given, 'tar' will check the number of links
2320 dumped for each processed file. If this number does not match the
2321 total number of hard links for the file, a warning message will be
2330 'tar' will use the 'compress' program when reading or writing the
2331 archive. This allows you to directly act on archives while saving
2332 space. *Note gzip::.
2340 (See '--interactive'.) *Note interactive::.
2342 '--delay-directory-restore'
2344 Delay setting modification times and permissions of extracted
2345 directories until the end of extraction. *Note Directory
2346 Modification Times and Permissions::.
2351 When reading or writing a file to be archived, 'tar' accesses the
2352 file that a symbolic link points to, rather than the symlink
2353 itself. *Note dereference::.
2358 When this option is specified, 'tar' will change its current
2359 directory to DIR before performing any operations. When this
2360 option is used during archive creation, it is order sensitive.
2365 When performing operations, 'tar' will skip files that match
2366 PATTERN. *Note exclude::.
2369 Exclude backup and lock files. *Note exclude-backups: exclude.
2371 '--exclude-from=FILE'
2374 Similar to '--exclude', except 'tar' will use the list of patterns
2375 in the file FILE. *Note exclude::.
2379 Exclude from dump any directory containing a valid cache directory
2380 tag file, but still dump the directory node and the tag file
2383 *Note exclude-caches: exclude.
2385 '--exclude-caches-under'
2387 Exclude from dump any directory containing a valid cache directory
2388 tag file, but still dump the directory node itself.
2392 '--exclude-caches-all'
2394 Exclude from dump any directory containing a valid cache directory
2395 tag file. *Note exclude::.
2397 '--exclude-ignore=FILE'
2398 Before dumping a directory, 'tar' checks if it contains FILE. If
2399 so, exclusion patterns are read from this file. The patterns
2400 affect only the directory itself. *Note exclude::.
2402 '--exclude-ignore-recursive=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 the directory and all itssubdirectories. *Note exclude::.
2407 '--exclude-tag=FILE'
2409 Exclude from dump any directory containing file named FILE, but
2410 dump the directory node and FILE itself. *Note exclude-tag:
2413 '--exclude-tag-under=FILE'
2415 Exclude from dump the contents of any directory containing file
2416 named FILE, but dump the directory node itself. *Note
2417 exclude-tag-under: exclude.
2419 '--exclude-tag-all=FILE'
2421 Exclude from dump any directory containing file named FILE. *Note
2422 exclude-tag-all: exclude.
2426 Exclude from dump directories and files, that are internal for some
2427 widely used version control systems.
2429 *Note exclude-vcs::.
2431 '--exclude-vcs-ignores'
2432 Exclude files that match patterns read from VCS-specific ignore
2433 files. Supported files are: '.cvsignore', '.gitignore',
2434 '.bzrignore', and '.hgignore'. The semantics of each file is the
2435 same as for the corresponding VCS, e.g. patterns read from
2436 '.gitignore' affect the directory and all its subdirectories.
2437 *Note exclude-vcs-ignores::.
2442 'tar' will use the file ARCHIVE as the 'tar' archive it performs
2443 operations on, rather than 'tar''s compilation dependent default.
2444 *Note file tutorial::.
2449 'tar' will use the contents of FILE as a list of archive members or
2450 files to operate on, in addition to those specified on the
2451 command-line. *Note files::.
2455 Forces 'tar' to interpret the file name given to '--file' as a
2456 local file, even if it looks like a remote tape drive name. *Note
2457 local and remote archives::.
2462 Selects output archive format. FORMAT may be one of the following:
2465 Creates an archive that is compatible with Unix V7 'tar'.
2468 Creates an archive that is compatible with GNU 'tar' version
2472 Creates archive in GNU tar 1.13 format. Basically it is the
2473 same as 'oldgnu' with the only difference in the way it
2474 handles long numeric fields.
2477 Creates a POSIX.1-1988 compatible archive.
2480 Creates a POSIX.1-2001 archive.
2482 *Note Formats::, for a detailed discussion of these formats.
2485 This option instructs 'tar' to print file times to their full
2486 resolution. Usually this means 1-second resolution, but that
2487 depends on the underlying file system. The '--full-time' option
2488 takes effect only when detailed output (verbosity level 2 or
2489 higher) has been requested using the '--verbose' option, e.g., when
2490 listing or extracting archives:
2492 $ tar -t -v --full-time -f archive.tar
2494 or, when creating an archive:
2496 $ tar -c -vv --full-time -f archive.tar .
2498 Notice, thar when creating the archive you need to specify
2499 '--verbose' twice to get a detailed output (*note verbose
2504 Files added to the 'tar' archive will have a group ID of GROUP,
2505 rather than the group from the source file. GROUP can specify a
2506 symbolic name, or a numeric ID, or both as NAME:ID. *Note
2509 Also see the '--group-map' option and comments for the
2510 '--owner=USER' option.
2514 Read owner group translation map from FILE. This option allows to
2515 translate only certain group names and/or UIDs. *Note override::,
2516 for a detailed description. When used together with '--group'
2517 option, the latter affects only those files whose owner group is
2518 not listed in the FILE.
2520 This option does not affect extraction from archives.
2527 This option tells 'tar' to read or write archives through 'gzip',
2528 allowing 'tar' to directly operate on several kinds of compressed
2529 archives transparently. *Note gzip::.
2531 '--hard-dereference'
2532 When creating an archive, dereference hard links and store the
2533 files they refer to, instead of creating usual hard link members.
2540 'tar' will print out a short message summarizing the operations and
2541 options to 'tar' and exit. *Note help::.
2543 '--hole-detection=METHOD'
2544 Use METHOD to detect holes in sparse files. This option implies
2545 '--sparse'. Valid methods are 'seek' and 'raw'. Default is 'seek'
2546 with fallback to 'raw' when not applicable. *Note sparse::.
2549 Ignore case when matching member or file names with patterns.
2550 *Note controlling pattern-matching::.
2552 '--ignore-command-error'
2553 Ignore exit codes of subprocesses. *Note Writing to an External
2556 '--ignore-failed-read'
2558 Do not exit unsuccessfully merely because an unreadable file was
2559 encountered. *Note Ignore Failed Read::.
2564 With this option, 'tar' will ignore zeroed blocks in the archive,
2565 which normally signals EOF. *Note Reading::.
2570 Informs 'tar' that it is working with an old GNU-format incremental
2571 backup archive. It is intended primarily for backwards
2572 compatibility only. *Note Incremental Dumps::, for a detailed
2573 discussion of incremental archives.
2577 Send verbose output to FILE instead of to standard output.
2579 '--info-script=COMMAND'
2580 '--new-volume-script=COMMAND'
2583 When 'tar' is performing multi-tape backups, COMMAND is run at the
2584 end of each tape. If it exits with nonzero status, 'tar' fails
2585 immediately. *Note info-script::, for a detailed discussion of
2592 Specifies that 'tar' should ask the user for confirmation before
2593 performing potentially destructive options, such as overwriting
2594 files. *Note interactive::.
2596 '--keep-directory-symlink'
2598 This option changes the behavior of tar when it encounters a
2599 symlink with the same name as the directory that it is about to
2600 extract. By default, in this case tar would first remove the
2601 symlink and then proceed extracting the directory.
2603 The '--keep-directory-symlink' option disables this behavior and
2604 instructs tar to follow symlinks to directories when extracting
2607 It is mainly intended to provide compatibility with the Slackware
2608 installation scripts.
2610 '--keep-newer-files'
2612 Do not replace existing files that are newer than their archive
2613 copies when extracting files from an archive.
2618 Do not overwrite existing files when extracting files from an
2619 archive. Return error if such files exist. See also *note
2622 *Note Keep Old Files::.
2627 When creating an archive, instructs 'tar' to write NAME as a name
2628 record in the archive. When extracting or listing archives, 'tar'
2629 will only operate on archives that have a label matching the
2630 pattern specified in NAME. *Note Tape Files::.
2633 Force incremental backup of level N. As of GNU 'tar' version 1.29,
2634 the option '--level=0' truncates the snapshot file, thereby forcing
2635 the level 0 dump. Other values of N are effectively ignored.
2636 *Note --level=0::, for details and examples.
2638 The use of this option is valid only in conjunction with the
2639 '--listed-incremental' option. *Note Incremental Dumps::, for a
2640 detailed description.
2642 '--listed-incremental=SNAPSHOT-FILE'
2645 During a '--create' operation, specifies that the archive that
2646 'tar' creates is a new GNU-format incremental backup, using
2647 SNAPSHOT-FILE to determine which files to backup. With other
2648 operations, informs 'tar' that the archive is in incremental
2649 format. *Note Incremental Dumps::.
2653 This option tells 'tar' to read or write archives through 'lzip'.
2658 This option tells 'tar' to read or write archives through 'lzma'.
2663 This option tells 'tar' to read or write archives through 'lzop'.
2666 '--mode=PERMISSIONS'
2668 When adding files to an archive, 'tar' will use PERMISSIONS for the
2669 archive members, rather than the permissions from the files.
2670 PERMISSIONS can be specified either as an octal number or as
2671 symbolic permissions, like with 'chmod'. *Note override::.
2675 When adding files to an archive, 'tar' will use DATE as the
2676 modification time of members when creating archives, instead of
2677 their actual modification times. The value of DATE can be either a
2678 textual date representation (*note Date input formats::) or a name
2679 of the existing file, starting with '/' or '.'. In the latter
2680 case, the modification time of that file is used. *Note
2683 When '--clamp-mtime' is also specified, files with modification
2684 times earlier than DATE will retain their actual modification
2685 times, and DATE will only be used for files whose modification
2686 times are later than DATE.
2691 Informs 'tar' that it should create or otherwise operate on a
2692 multi-volume 'tar' archive. *Note Using Multiple Tapes::.
2694 '--new-volume-script'
2696 (see '--info-script')
2702 When creating an archive, 'tar' will only add files that have
2703 changed since DATE. If DATE begins with '/' or '.', it is taken to
2704 be the name of a file whose data modification time specifies the
2705 date. *Note after::.
2707 '--newer-mtime=DATE'
2709 Like '--newer', but add only files whose contents have changed (as
2710 opposed to just '--newer', which will also back up files for which
2711 any status information has changed). *Note after::.
2714 Disable the POSIX ACLs support. *Note acls: Extended File
2718 An exclude pattern can match any subsequence of the name's
2719 components. *Note controlling pattern-matching::.
2721 '--no-auto-compress'
2723 Disables automatic compressed format recognition based on the
2724 archive suffix. *Note --auto-compress::. *Note gzip::.
2727 Do not check device numbers when creating a list of modified files
2728 for incremental archiving. *Note device numbers::, for a detailed
2731 '--no-delay-directory-restore'
2733 Modification times and permissions of extracted directories are set
2734 when all files from this directory have been extracted. This is
2735 the default. *Note Directory Modification Times and Permissions::.
2738 Use case-sensitive matching. *Note controlling pattern-matching::.
2740 '--no-ignore-command-error'
2741 Print warnings about subprocesses that terminated with a nonzero
2742 exit code. *Note Writing to an External Program::.
2746 If the '--null' option was given previously, this option cancels
2747 its effect, so that any following '--files-from' options will
2748 expect their file lists to be newline-terminated.
2750 '--no-overwrite-dir'
2752 Preserve metadata of existing directories when extracting files
2753 from an archive. *Note Overwrite Old Files::.
2755 '--no-quote-chars=STRING'
2756 Remove characters listed in STRING from the list of quoted
2757 characters set by the previous '--quote-chars' option (*note
2762 With this option, 'tar' will not recurse into directories. *Note
2768 When extracting an archive, do not attempt to preserve the owner
2769 specified in the 'tar' archive. This the default behavior for
2772 '--no-same-permissions'
2774 When extracting an archive, subtract the user's umask from files
2775 from the permissions specified in the archive. This is the default
2776 behavior for ordinary users.
2780 The archive media does not support seeks to arbitrary locations.
2781 Usually 'tar' determines automatically whether the archive can be
2782 seeked or not. Use this option to disable this mechanism.
2785 Disable SELinux context support. *Note SELinux: Extended File
2789 Treat all input file or member names literally, do not interpret
2790 escape sequences. *Note input name quoting::.
2792 '--no-verbatim-files-from'
2794 Instructs GNU 'tar' to treat each line read from a file list as if
2795 it were supplied in the command line. I.e., leading and trailing
2796 whitespace is removed and, if the result begins with a dash, it is
2797 treated as a GNU 'tar' command line option.
2799 This is default behavior. This option is provided as a way to
2800 restore it after '--verbatim-files-from' option.
2802 It is implied by the '--no-null' option.
2804 *Note no-verbatim-files-from::.
2807 Do not use wildcards. *Note controlling pattern-matching::.
2809 '--no-wildcards-match-slash'
2810 Wildcards do not match '/'. *Note controlling pattern-matching::.
2813 Disable extended attributes support. *Note xattrs: Extended File
2818 When 'tar' is using the '--files-from' option, this option
2819 instructs 'tar' to expect file names terminated with NUL, and to
2820 process file names verbatim.
2822 This means that 'tar' correctly works with file names that contain
2823 newlines or begin with a dash.
2827 See also *note verbatim-files-from::.
2831 This option will notify 'tar' that it should use numeric user and
2832 group IDs when creating a 'tar' file, rather than names. *Note
2836 The function of this option depends on the action 'tar' is
2837 performing. When extracting files, '-o' is a synonym for
2838 '--no-same-owner', i.e., it prevents 'tar' from restoring ownership
2839 of files being extracted.
2841 When creating an archive, it is a synonym for '--old-archive'.
2842 This behavior is for compatibility with previous versions of GNU
2843 'tar', and will be removed in future releases.
2845 *Note Changes::, for more information.
2847 '--occurrence[=NUMBER]'
2849 This option can be used in conjunction with one of the subcommands
2850 '--delete', '--diff', '--extract' or '--list' when a list of files
2851 is given either on the command line or via '-T' option.
2853 This option instructs 'tar' to process only the NUMBERth occurrence
2854 of each named file. NUMBER defaults to 1, so
2856 tar -x -f archive.tar --occurrence filename
2858 will extract the first occurrence of the member 'filename' from
2859 'archive.tar' and will terminate without scanning to the end of the
2863 Synonym for '--format=v7'.
2866 Used when creating an archive. Prevents 'tar' from recursing into
2867 directories that are on different file systems from the current
2870 '--one-top-level[=DIR]'
2871 Tells 'tar' to create a new directory beneath the extraction
2872 directory (or the one passed to '-C') and use it to guard against
2873 tarbombs. In the absence of DIR argument, the name of the new
2874 directory will be equal to the base name of the archive (file name
2875 minus the archive suffix, if recognized). Any member names that do
2876 not begin with that directory name (after transformations from
2877 '--transform' and '--strip-components') will be prefixed with it.
2878 Recognized file name suffixes are '.tar', and any compression
2879 suffixes recognizable by *Note --auto-compress::.
2883 Overwrite existing files and directory metadata when extracting
2884 files from an archive. *Note Overwrite Old Files::.
2888 Overwrite the metadata of existing directories when extracting
2889 files from an archive. *Note Overwrite Old Files::.
2893 Specifies that 'tar' should use USER as the owner of members when
2894 creating archives, instead of the user associated with the source
2895 file. USER can specify a symbolic name, or a numeric ID, or both
2896 as NAME:ID. *Note override::.
2898 This option does not affect extraction from archives. See also
2899 '--owner-map', below.
2903 Read owner translation map from FILE. This option allows to
2904 translate only certain owner names or UIDs. *Note override::, for
2905 a detailed description. When used together with '--owner' option,
2906 the latter affects only those files whose owner is not listed in
2909 This option does not affect extraction from archives.
2911 '--pax-option=KEYWORD-LIST'
2912 This option enables creation of the archive in POSIX.1-2001 format
2913 (*note posix::) and modifies the way 'tar' handles the extended
2914 header keywords. KEYWORD-LIST is a comma-separated list of keyword
2915 options. *Note PAX keywords::, for a detailed discussion.
2919 Synonym for '--format=v7'.
2922 Same as '--format=posix'.
2926 (See '--same-order'; *note Reading::.)
2928 '--preserve-permissions'
2929 '--same-permissions'
2932 When 'tar' is extracting an archive, it normally subtracts the
2933 users' umask from the permissions specified in the archive and uses
2934 that number as the permissions to create the destination file.
2935 Specifying this option instructs 'tar' that it should use the
2936 permissions directly from the archive. *Note Setting Access
2939 '--quote-chars=STRING'
2940 Always quote characters from STRING, even if the selected quoting
2941 style would not quote them (*note quoting styles::).
2943 '--quoting-style=STYLE'
2944 Set quoting style to use when printing member and file names (*note
2945 quoting styles::). Valid STYLE values are: 'literal', 'shell',
2946 'shell-always', 'c', 'escape', 'locale', and 'clocale'. Default
2947 quoting style is 'escape', unless overridden while configuring the
2950 '--read-full-records'
2953 Specifies that 'tar' should reblock its input, for reading from
2954 pipes on systems with buggy implementations. *Note Reading::.
2956 '--record-size=SIZE[SUF]'
2958 Instructs 'tar' to use SIZE bytes per record when accessing the
2959 archive. The argument can be suffixed with a "size suffix", e.g.
2960 '--record-size=10K' for 10 Kilobytes. *Note Table 9.1:
2961 size-suffixes, for a list of valid suffixes. *Note Blocking
2962 Factor::, for a detailed description of this option.
2966 With this option, 'tar' recurses into directories (default). *Note
2969 '--recursive-unlink'
2971 Remove existing directory hierarchies before extracting directories
2972 of the same name from the archive. *Note Recursive Unlink::.
2976 Directs 'tar' to remove the source file from the file system after
2977 appending it to an archive. *Note remove files::.
2981 Disable use of some potentially harmful 'tar' options. Currently
2982 this option disables shell invocation from multi-volume menu (*note
2983 Using Multiple Tapes::).
2987 Notifies 'tar' that it should use CMD instead of the default
2988 '/usr/libexec/rmt' (*note Remote Tape Server::).
2992 Notifies 'tar' that is should use CMD to communicate with remote
2993 devices. *Note Device::.
2999 This option is an optimization for 'tar' when running on machines
3000 with small amounts of memory. It informs 'tar' that the list of
3001 file arguments has already been sorted to match the order of files
3002 in the archive. *Note Reading::.
3006 When extracting an archive, 'tar' will attempt to preserve the
3007 owner specified in the 'tar' archive with this option present.
3008 This is the default behavior for the superuser; this option has an
3009 effect only for ordinary users. *Note Attributes::.
3011 '--same-permissions'
3013 (See '--preserve-permissions'; *note Setting Access Permissions::.)
3018 Assume that the archive media supports seeks to arbitrary
3019 locations. Usually 'tar' determines automatically whether the
3020 archive can be seeked or not. This option is intended for use in
3021 cases when such recognition fails. It takes effect only if the
3022 archive is open for reading (e.g. with '--list' or '--extract'
3026 Enable the SELinux context support. *Note selinux: Extended File
3031 Displays the default options used by 'tar' and exits successfully.
3032 This option is intended for use in shell scripts. Here is an
3033 example of what you can see using this option:
3035 $ tar --show-defaults
3036 --format=gnu -f- -b20 --quoting-style=escape
3037 --rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
3039 Notice, that this option outputs only one line. The example output
3040 above has been split to fit page boundaries. *Note defaults::.
3042 '--show-omitted-dirs'
3044 Instructs 'tar' to mention the directories it is skipping when
3045 operating on a 'tar' archive. *Note show-omitted-dirs::.
3047 '--show-snapshot-field-ranges'
3049 Displays the range of values allowed by this version of 'tar' for
3050 each field in the snapshot file, then exits successfully. *Note
3053 '--show-transformed-names'
3054 '--show-stored-names'
3056 Display file or member names after applying any transformations
3057 (*note transform::). In particular, when used in conjunction with
3058 one of the archive creation operations it instructs 'tar' to list
3059 the member names stored in the archive, as opposed to the actual
3060 file names. *Note listing member and file names::.
3064 Do not overwrite existing files when extracting files from an
3065 archive. *Note Keep Old Files::.
3067 This option differs from '--keep-old-files' in that it does not
3068 treat such files as an error, instead it just silently avoids
3071 The '--warning=existing-file' option can be used together with this
3072 option to produce warning messages about existing old files (*note
3076 Specify the directory sorting order when reading directories.
3077 ORDER may be one of the following:
3080 No directory sorting is performed. This is the default.
3083 Sort the directory entries on name. The operating system may
3084 deliver directory entries in a more or less random order, and
3085 sorting them makes archive creation reproducible.
3088 Sort the directory entries on inode number. Sorting
3089 directories on inode number may reduce the amount of disk seek
3090 operations when creating an archive for some file systems.
3095 Invokes a GNU extension when adding files to an archive that
3096 handles sparse files efficiently. *Note sparse::.
3098 '--sparse-version=VERSION'
3100 Specifies the "format version" to use when archiving sparse files.
3101 Implies '--sparse'. *Note sparse::. For the description of the
3102 supported sparse formats, *Note Sparse Formats::.
3104 '--starting-file=NAME'
3107 This option affects extraction only; 'tar' will skip extracting
3108 files in the archive until it finds one that matches NAME. *Note
3111 '--strip-components=NUMBER'
3112 Strip given NUMBER of leading components from file names before
3113 extraction. For example, if archive 'archive.tar' contained
3114 '/some/file/name', then running
3116 tar --extract --file archive.tar --strip-components=2
3118 would extract this file to file 'name'.
3124 Alters the suffix 'tar' uses when backing up files from the default
3125 '~'. *Note backup::.
3127 '--tape-length=NUM[SUF]'
3130 Specifies the length of tapes that 'tar' is writing as being
3131 NUM x 1024 bytes long. If optional SUF is given, it specifies a
3132 multiplicative factor to be used instead of 1024. For example,
3133 '-L2M' means 2 megabytes. *Note Table 9.1: size-suffixes, for a
3134 list of allowed suffixes. *Note Using Multiple Tapes::, for a
3135 detailed discussion of this option.
3139 Reads the volume label. If an argument is specified, test whether
3140 it matches the volume label. *Note --test-label option::.
3142 '--to-command=COMMAND'
3144 During extraction 'tar' will pipe extracted files to the standard
3145 input of COMMAND. *Note Writing to an External Program::.
3150 During extraction, 'tar' will extract files to stdout rather than
3151 to the file system. *Note Writing to Standard Output::.
3155 Displays the total number of bytes transferred when processing an
3156 archive. If an argument is given, these data are displayed on
3157 request, when signal SIGNO is delivered to 'tar'. *Note totals::.
3162 Sets the data modification time of extracted files to the
3163 extraction time, rather than the data modification time stored in
3164 the archive. *Note Data Modification Times::.
3166 '--transform=SED-EXPR'
3168 Transform file or member names using 'sed' replacement expression
3169 SED-EXPR. For example,
3171 $ tar cf archive.tar --transform 's,^\./,usr/,' .
3173 will add to 'archive' files from the current working directory,
3174 replacing initial './' prefix with 'usr/'. For the detailed
3175 discussion, *Note transform::.
3177 To see transformed member names in verbose listings, use
3178 '--show-transformed-names' option (*note show-transformed-names::).
3182 (See '--compress', *note gzip::)
3186 (See '--gzip', *note gzip::)
3191 Directs 'tar' to remove the corresponding file from the file system
3192 before extracting it from the archive. *Note Unlink First::.
3195 Enable unquoting input file or member names (default). *Note input
3198 '--use-compress-program=PROG'
3201 Instructs 'tar' to access the archive through PROG, which is
3202 presumed to be a compression program of some sort. *Note gzip::.
3206 Display file modification dates in UTC. This option implies
3209 '--verbatim-files-from'
3211 Instructs GNU 'tar' to treat each line read from a file list as a
3212 file name, even if it starts with a dash.
3214 File lists are supplied with the '--files-from' ('-T') option. By
3215 default, each line read from a file list is first trimmed off the
3216 leading and trailing whitespace and, if the result begins with a
3217 dash, it is treated as a GNU 'tar' command line option.
3219 Use the '--verbatim-files-from' option to disable this special
3220 handling. This facilitates the use of 'tar' with file lists
3221 created by 'file' command.
3223 This option affects all '--files-from' options that occur after it
3224 in the command line. Its effect is reverted by the
3225 '--no-verbatim-files-from' option.
3227 This option is implied by the '--null' option.
3229 *Note verbatim-files-from::.
3234 Specifies that 'tar' should be more verbose about the operations it
3235 is performing. This option can be specified multiple times for
3236 some operations to increase the amount of information displayed.
3242 Verifies that the archive was correctly written when creating an
3243 archive. *Note verify::.
3247 Print information about the program's name, version, origin and
3248 legal status, all on standard output, and then exit successfully.
3253 Used in conjunction with '--multi-volume'. 'tar' will keep track
3254 of which volume of a multi-volume archive it is working in FILE.
3259 Enable or disable warning messages identified by KEYWORD. The
3260 messages are suppressed if KEYWORD is prefixed with 'no-'. *Note
3264 Use wildcards when matching member names with patterns. *Note
3265 controlling pattern-matching::.
3267 '--wildcards-match-slash'
3268 Wildcards match '/'. *Note controlling pattern-matching::.
3271 Enable extended attributes support. *Note xattrs: Extended File
3274 '--xattrs-exclude=PATTERN'
3275 Specify exclude pattern for xattr keys. *Note xattrs-exclude:
3276 Extended File Attributes.
3278 '--xattrs-include=PATTERN.'
3279 Specify include pattern for xattr keys. PATTERN is a POSIX regular
3280 expression, e.g. '--xattrs-exclude='^user\.'' to include only
3281 attributes from the user namespace. *Note xattrs-include: Extended
3286 Use 'xz' for compressing or decompressing the archives. *Note
3289 ---------- Footnotes ----------
3291 (1) Earlier versions of GNU 'tar' understood '-l' as a synonym for
3292 '--one-file-system'. The current semantics, which complies to UNIX98,
3293 was introduced with version 1.15.91. *Note Changes::, for more
3297 File: tar.info, Node: Short Option Summary, Next: Position-Sensitive Options, Prev: Option Summary, Up: All Options
3299 3.4.3 Short Options Cross Reference
3300 -----------------------------------
3302 Here is an alphabetized list of all of the short option forms, matching
3303 them with the equivalent long option.
3305 Short Option Reference
3307 --------------------------------------------------------------------------
3308 -A *note --concatenate::.
3310 -B *note --read-full-records::.
3312 -C *note --directory::.
3314 -F *note --info-script::.
3316 -G *note --incremental::.
3320 -K *note --starting-file::.
3322 -L *note --tape-length::.
3324 -M *note --multi-volume::.
3328 -O *note --to-stdout::.
3330 -P *note --absolute-names::.
3332 -R *note --block-number::.
3334 -S *note --sparse::.
3336 -T *note --files-from::.
3338 -U *note --unlink-first::.
3342 -W *note --verify::.
3344 -X *note --exclude-from::.
3346 -Z *note --compress::.
3348 -b *note --blocking-factor::.
3350 -c *note --create::.
3352 -d *note --compare::.
3356 -g *note --listed-incremental::.
3358 -h *note --dereference::.
3360 -i *note --ignore-zeros::.
3364 -k *note --keep-old-files::.
3366 -l *note --check-links::.
3370 -o When creating, *note --no-same-owner::, when extracting
3371 -- *note --portability::.
3373 The latter usage is deprecated. It is retained for
3374 compatibility with the earlier versions of GNU 'tar'.
3375 In future releases '-o' will be equivalent to
3376 '--no-same-owner' only.
3378 -p *note --preserve-permissions::.
3380 -r *note --append::.
3382 -s *note --same-order::.
3386 -u *note --update::.
3388 -v *note --verbose::.
3390 -w *note --interactive::.
3392 -x *note --extract::.
3398 File: tar.info, Node: Position-Sensitive Options, Prev: Short Option Summary, Up: All Options
3400 3.4.4 Position-Sensitive Options
3401 --------------------------------
3403 Some GNU 'tar' options can be used multiple times in the same invocation
3404 and affect all arguments that appear after them. These are options that
3405 control how file names are selected and what kind of pattern matching is
3408 The most obvious example is the '-C' option. It instructs 'tar' to
3409 change to the directory given as its argument prior to processing the
3410 rest of command line (*note directory::). Thus, in the following
3413 tar -c -f a.tar -C /etc passwd -C /var log spool
3415 the file 'passwd' will be searched in the directory '/etc', and files
3416 'log' and 'spool' - in '/var'.
3418 These options can also be used in a file list supplied with the
3419 '--files-from' ('-T') option (*note files::). In that case they affect
3420 all files (patterns) appearing in that file after them and remain in
3421 effect for any arguments processed after that file. For example, if the
3422 file 'list.txt' contained:
3428 and 'tar' were invoked as follows:
3430 tar -c -f a.tar -T list.txt Makefile
3432 then the file 'README' would be looked up in the current working
3433 directory, and files 'main.c' and 'Makefile' would be looked up in the
3436 Many options can be prefixed with '--no-' to cancel the effect of the
3439 For example, the '--recursion' option controls whether to recurse in
3440 the subdirectories. It's counterpart '--no-recursion' disables this.
3441 Consider the command below. It will store in the archive the directory
3442 '/usr' with all files and directories that are located in it as well as
3443 any files and directories in '/var', without recursing into them(1):
3445 tar -cf a.tar --recursion /usr --no-recursion /var/*
3447 The following table summarizes all position-sensitive options.
3459 *Note input name quoting::.
3461 '--verbatim-files-from'
3462 '--no-verbatim-files-from'
3463 *Note verbatim-files-from::.
3471 *Note anchored patterns::.
3475 *Note case-insensitive matches::.
3479 *Note controlling pattern-matching::.
3481 '--wildcards-match-slash'
3482 '--no-wildcards-match-slash'
3483 *Note controlling pattern-matching::.
3491 '--exclude-caches-under'
3492 '--exclude-caches-all'
3495 '--exclude-ignore-recursive'
3496 '--exclude-tag-under'
3499 '--exclude-vcs-ignores'
3503 ---------- Footnotes ----------
3505 (1) The '--recursion' option is the default and is used here for
3506 clarity. The same example can be written as:
3508 tar -cf a.tar /usr --no-recursion /var/*
3511 File: tar.info, Node: help, Next: defaults, Prev: All Options, Up: tar invocation
3513 3.5 GNU 'tar' documentation
3514 ===========================
3516 Being careful, the first thing is really checking that you are using GNU
3517 'tar', indeed. The '--version' option causes 'tar' to print information
3518 about its name, version, origin and legal status, all on standard
3519 output, and then exit successfully. For example, 'tar --version' might
3523 Copyright (C) 2013-2016 Free Software Foundation, Inc.
3524 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
3525 This is free software: you are free to change and redistribute it.
3526 There is NO WARRANTY, to the extent permitted by law.
3528 Written by John Gilmore and Jay Fenlason.
3530 The first occurrence of 'tar' in the result above is the program name in
3531 the package (for example, 'rmt' is another program), while the second
3532 occurrence of 'tar' is the name of the package itself, containing
3533 possibly many programs. The package is currently named 'tar', after the
3534 name of the main program it contains(1).
3536 Another thing you might want to do is checking the spelling or
3537 meaning of some particular 'tar' option, without resorting to this
3538 manual, for once you have carefully read it. GNU 'tar' has a short help
3539 feature, triggerable through the '--help' option. By using this option,
3540 'tar' will print a usage message listing all available options on
3541 standard output, then exit successfully, without doing anything else and
3542 ignoring all other options. Even if this is only a brief summary, it
3543 may be several screens long. So, if you are not using some kind of
3544 scrollable window, you might prefer to use something like:
3548 presuming, here, that you like using 'less' for a pager. Other popular
3549 pagers are 'more' and 'pg'. If you know about some KEYWORD which
3550 interests you and do not want to read all the '--help' output, another
3551 common idiom is doing:
3553 tar --help | grep KEYWORD
3555 for getting only the pertinent lines. Notice, however, that some 'tar'
3556 options have long description lines and the above command will list only
3559 The exact look of the option summary displayed by 'tar --help' is
3560 configurable. *Note Configuring Help Summary::, for a detailed
3563 If you only wish to check the spelling of an option, running 'tar
3564 --usage' may be a better choice. This will display a terse list of
3565 'tar' options without accompanying explanations.
3567 The short help output is quite succinct, and you might have to get
3568 back to the full documentation for precise points. If you are reading
3569 this paragraph, you already have the 'tar' manual in some form. This
3570 manual is available in a variety of forms from
3571 <http://www.gnu.org/software/tar/manual>. It may be printed out of the
3572 GNU 'tar' distribution, provided you have TeX already installed
3573 somewhere, and a laser printer around. Just configure the distribution,
3574 execute the command 'make dvi', then print 'doc/tar.dvi' the usual way
3575 (contact your local guru to know how). If GNU 'tar' has been
3576 conveniently installed at your place, this manual is also available in
3577 interactive, hypertextual form as an Info file. Just call 'info tar'
3578 or, if you do not have the 'info' program handy, use the Info reader
3579 provided within GNU Emacs, calling 'tar' from the main Info menu.
3581 There is currently no 'man' page for GNU 'tar'. If you observe such
3582 a 'man' page on the system you are running, either it does not belong to
3583 GNU 'tar', or it has not been produced by GNU. Some package maintainers
3584 convert 'tar --help' output to a man page, using 'help2man'. In any
3585 case, please bear in mind that the authoritative source of information
3586 about GNU 'tar' is this Texinfo documentation.
3588 ---------- Footnotes ----------
3590 (1) There are plans to merge the 'cpio' and 'tar' packages into a
3591 single one which would be called 'paxutils'. So, who knows if, one of
3592 this days, the '--version' would not output 'tar (GNU paxutils) 3.2'.
3595 File: tar.info, Node: defaults, Next: verbose, Prev: help, Up: tar invocation
3597 3.6 Obtaining GNU 'tar' default values
3598 ======================================
3600 GNU 'tar' has some predefined defaults that are used when you do not
3601 explicitly specify another values. To obtain a list of such defaults,
3602 use '--show-defaults' option. This will output the values in the form
3603 of 'tar' command line options:
3605 $ tar --show-defaults
3606 --format=gnu -f- -b20 --quoting-style=escape
3607 --rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
3609 Notice, that this option outputs only one line. The example output
3610 above has been split to fit page boundaries.
3612 The above output shows that this version of GNU 'tar' defaults to using
3613 'gnu' archive format (*note Formats::), it uses standard output as the
3614 archive, if no '--file' option has been given (*note file tutorial::),
3615 the default blocking factor is 20 (*note Blocking Factor::). It also
3616 shows the default locations where 'tar' will look for 'rmt' and 'rsh'
3620 File: tar.info, Node: verbose, Next: checkpoints, Prev: defaults, Up: tar invocation
3622 3.7 Checking 'tar' progress
3623 ===========================
3625 Typically, 'tar' performs most operations without reporting any
3626 information to the user except error messages. When using 'tar' with
3627 many options, particularly ones with complicated or difficult-to-predict
3628 behavior, it is possible to make serious mistakes. 'tar' provides
3629 several options that make observing 'tar' easier. These options cause
3630 'tar' to print information as it progresses in its job, and you might
3631 want to use them just for being more careful about what is going on, or
3632 merely for entertaining yourself. If you have encountered a problem
3633 when operating on an archive, however, you may need more information
3634 than just an error message in order to solve the problem. The following
3635 options can be helpful diagnostic tools.
3637 Normally, the '--list' ('-t') command to list an archive prints just
3638 the file names (one per line) and the other commands are silent. When
3639 used with most operations, the '--verbose' ('-v') option causes 'tar' to
3640 print the name of each file or archive member as it is processed. This
3641 and the other options which make 'tar' print status information can be
3642 useful in monitoring 'tar'.
3644 With '--create' or '--extract', '--verbose' used once just prints the
3645 names of the files or members as they are processed. Using it twice
3646 causes 'tar' to print a longer listing (*Note verbose member listing::,
3647 for the description) for each member. Since '--list' already prints the
3648 names of the members, '--verbose' used once with '--list' causes 'tar'
3649 to print an 'ls -l' type listing of the files in the archive. The
3650 following examples both extract members with long list output:
3652 $ tar --extract --file=archive.tar --verbose --verbose
3653 $ tar xvvf archive.tar
3655 Verbose output appears on the standard output except when an archive
3656 is being written to the standard output, as with 'tar --create --file=-
3657 --verbose' ('tar cvf -', or even 'tar cv'--if the installer let standard
3658 output be the default archive). In that case 'tar' writes verbose
3659 output to the standard error stream.
3661 If '--index-file=FILE' is specified, 'tar' sends verbose output to
3662 FILE rather than to standard output or standard error.
3664 The '--totals' option causes 'tar' to print on the standard error the
3665 total amount of bytes transferred when processing an archive. When
3666 creating or appending to an archive, this option prints the number of
3667 bytes written to the archive and the average speed at which they have
3670 $ tar -c -f archive.tar --totals /home
3671 Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
3673 When reading an archive, this option displays the number of bytes
3676 $ tar -x -f archive.tar --totals
3677 Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
3679 Finally, when deleting from an archive, the '--totals' option
3680 displays both numbers plus number of bytes removed from the archive:
3682 $ tar --delete -f foo.tar --totals --wildcards '*~'
3683 Total bytes read: 9543680 (9.2MiB, 201MiB/s)
3684 Total bytes written: 3829760 (3.7MiB, 81MiB/s)
3685 Total bytes deleted: 1474048
3687 You can also obtain this information on request. When '--totals' is
3688 used with an argument, this argument is interpreted as a symbolic name
3689 of a signal, upon delivery of which the statistics is to be printed:
3692 Print statistics upon delivery of signal SIGNO. Valid arguments
3693 are: 'SIGHUP', 'SIGQUIT', 'SIGINT', 'SIGUSR1' and 'SIGUSR2'.
3694 Shortened names without 'SIG' prefix are also accepted.
3696 Both forms of '--totals' option can be used simultaneously. Thus,
3697 'tar -x --totals --totals=USR1' instructs 'tar' to extract all members
3698 from its default archive and print statistics after finishing the
3699 extraction, as well as when receiving signal 'SIGUSR1'.
3701 The '--checkpoint' option prints an occasional message as 'tar' reads
3702 or writes the archive. It is designed for those who don't need the more
3703 detailed (and voluminous) output of '--block-number' ('-R'), but do want
3704 visual confirmation that 'tar' is actually making forward progress. By
3705 default it prints a message each 10 records read or written. This can
3706 be changed by giving it a numeric argument after an equal sign:
3708 $ tar -c --checkpoint=1000 /var
3709 tar: Write checkpoint 1000
3710 tar: Write checkpoint 2000
3711 tar: Write checkpoint 3000
3713 This example shows the default checkpoint message used by 'tar'. If
3714 you place a dot immediately after the equal sign, it will print a '.' at
3715 each checkpoint(1). For example:
3717 $ tar -c --checkpoint=.1000 /var
3720 The '--checkpoint' option provides a flexible mechanism for executing
3721 arbitrary actions upon hitting checkpoints, see the next section (*note
3722 checkpoints::), for more information on it.
3724 The '--show-omitted-dirs' option, when reading an archive--with
3725 '--list' or '--extract', for example--causes a message to be printed for
3726 each directory in the archive which is skipped. This happens regardless
3727 of the reason for skipping: the directory might not have been named on
3728 the command line (implicitly or explicitly), it might be excluded by the
3729 use of the '--exclude=PATTERN' option, or some other reason.
3731 If '--block-number' ('-R') is used, 'tar' prints, along with every
3732 message it would normally produce, the block number within the archive
3733 where the message was triggered. Also, supplementary messages are
3734 triggered when reading blocks full of NULs, or when hitting end of file
3735 on the archive. As of now, if the archive is properly terminated with a
3736 NUL block, the reading of the file may stop before end of file is met,
3737 so the position of end of file will not usually show when
3738 '--block-number' ('-R') is used. Note that GNU 'tar' drains the archive
3739 before exiting when reading the archive from a pipe.
3741 This option is especially useful when reading damaged archives, since
3742 it helps pinpoint the damaged sections. It can also be used with
3743 '--list' ('-t') when listing a file-system backup tape, allowing you to
3744 choose among several backup tapes when retrieving a file later, in favor
3745 of the tape where the file appears earliest (closest to the front of the
3746 tape). *Note backup::.
3748 ---------- Footnotes ----------
3750 (1) This is actually a shortcut for '--checkpoint=N
3751 --checkpoint-action=dot'. *Note dot: checkpoints.
3754 File: tar.info, Node: checkpoints, Next: warnings, Prev: verbose, Up: tar invocation
3759 A "checkpoint" is a moment of time before writing Nth record to the
3760 archive (a "write checkpoint"), or before reading Nth record from the
3761 archive (a "read checkpoint"). Checkpoints allow to periodically
3762 execute arbitrary actions.
3764 The checkpoint facility is enabled using the following option:
3767 Schedule checkpoints before writing or reading each Nth record.
3768 The default value for N is 10.
3770 A list of arbitrary "actions" can be executed at each checkpoint.
3771 These actions include: pausing, displaying textual messages, and
3772 executing arbitrary external programs. Actions are defined using the
3773 '--checkpoint-action' option.
3775 '--checkpoint-action=ACTION'
3776 Execute an ACTION at each checkpoint.
3778 The simplest value of ACTION is 'echo'. It instructs 'tar' to
3779 display the default message on the standard error stream upon arriving
3780 at each checkpoint. The default message is (in POSIX locale) 'Write
3781 checkpoint N', for write checkpoints, and 'Read checkpoint N', for read
3782 checkpoints. Here, N represents ordinal number of the checkpoint.
3784 In another locales, translated versions of this message are used.
3786 This is the default action, so running:
3788 $ tar -c --checkpoint=1000 --checkpoint-action=echo /var
3792 $ tar -c --checkpoint=1000 /var
3794 The 'echo' action also allows to supply a customized message. You do
3795 so by placing an equals sign and the message right after it, e.g.:
3797 --checkpoint-action="echo=Hit %s checkpoint #%u"
3799 The '%s' and '%u' in the above example are "format specifiers". The
3800 '%s' specifier is replaced with the "type" of the checkpoint: 'write' or
3801 'read' (or a corresponding translated version in locales other than
3802 POSIX). The '%u' specifier is replaced with the ordinal number of the
3803 checkpoint. Thus, the above example could produce the following output
3804 when used with the '--create' option:
3806 tar: Hit write checkpoint #10
3807 tar: Hit write checkpoint #20
3808 tar: Hit write checkpoint #30
3810 The complete list of available format specifiers follows. Some of
3811 them can take optional arguments. These arguments, if given, are
3812 supplied in curly braces between the percent sign and the specifier
3816 Print type of the checkpoint ('write' or 'read').
3819 Print number of the checkpoint.
3822 Print number of bytes transferred so far and approximate transfer
3823 speed. Optional arguments supply prefixes to be used before number
3824 of bytes read, written and deleted, correspondingly. If absent,
3825 they default to 'R'. 'W', 'D'. Any or all of them can be omitted,
3826 so, that e.g. '%{}T' means to print corresponding statistics
3827 without any prefixes. Any surplus arguments, if present, are
3830 $ tar --delete -f f.tar --checkpoint-action=echo="#%u: %T" main.c
3831 tar: #1: R: 0 (0B, 0B/s),W: 0 (0B, 0B/s),D: 0
3832 tar: #2: R: 10240 (10KiB, 19MiB/s),W: 0 (0B, 0B/s),D: 10240
3834 See also the 'totals' action, described below.
3837 Output current local time using FMT as format for 'strftime' (*note
3838 strftime: (strftime(3))strftime.). The '{FMT}' part is optional.
3839 If not present, the default format is '%c', i.e. the preferred
3840 date and time representation for the current locale.
3843 Pad output with spaces to the Nth column. If the '{N}' part is
3844 omitted, the current screen width is assumed.
3847 This is a shortcut for '%{%Y-%m-%d %H:%M:%S}t: %ds,
3848 %{read,wrote}T%*\r', intended mainly for use with 'ttyout' action
3851 Aside from format expansion, the message string is subject to
3852 "unquoting", during which the backslash "escape sequences" are replaced
3853 with their corresponding ASCII characters (*note escape sequences::).
3854 E.g. the following action will produce an audible bell and the message
3855 described above at each checkpoint:
3857 --checkpoint-action='echo=\aHit %s checkpoint #%u'
3859 There is also a special action which produces an audible signal:
3860 'bell'. It is not equivalent to 'echo='\a'', because 'bell' sends the
3861 bell directly to the console ('/dev/tty'), whereas 'echo='\a'' sends it
3862 to the standard error.
3864 The 'ttyout=STRING' action outputs STRING to '/dev/tty', so it can be
3865 used even if the standard output is redirected elsewhere. The STRING is
3866 subject to the same modifications as with 'echo' action. In contrast to
3867 the latter, 'ttyout' does not prepend 'tar' executable name to the
3868 string, nor does it output a newline after it. For example, the
3869 following action will print the checkpoint message at the same screen
3870 line, overwriting any previous message:
3872 --checkpoint-action="ttyout=Hit %s checkpoint #%u%*\r"
3874 Notice the use of '%*' specifier to clear out any eventual remains of
3875 the prior output line. As as more complex example, consider this:
3877 --checkpoint-action=ttyout='%{%Y-%m-%d %H:%M:%S}t (%d sec): #%u, %T%*\r'
3879 This prints the current local time, number of seconds expired since tar
3880 was started, the checkpoint ordinal number, transferred bytes and
3881 average computed I/O speed.
3883 Another available checkpoint action is 'dot' (or '.'). It instructs
3884 'tar' to print a single dot on the standard listing stream, e.g.:
3886 $ tar -c --checkpoint=1000 --checkpoint-action=dot /var
3889 For compatibility with previous GNU 'tar' versions, this action can
3890 be abbreviated by placing a dot in front of the checkpoint frequency, as
3891 shown in the previous section.
3893 The 'totals' action prints the total number of bytes transferred so
3894 far. The format of the data is the same as for the '--totals' option
3895 (*note totals::). See also '%T' format specifier of the 'echo' or
3898 Yet another action, 'sleep', pauses 'tar' for a specified amount of
3899 seconds. The following example will stop for 30 seconds at each
3902 $ tar -c --checkpoint=1000 --checkpoint-action=sleep=30
3904 Finally, the 'exec' action executes a given external command. For
3907 $ tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint
3909 The supplied command can be any valid command invocation, with or
3910 without additional command line arguments. If it does contain
3911 arguments, don't forget to quote it to prevent it from being split by
3912 the shell. *Note Running External Commands: external, for more detail.
3914 The command gets a copy of 'tar''s environment plus the following
3918 GNU 'tar' version number.
3921 The name of the archive 'tar' is processing.
3923 'TAR_BLOCKING_FACTOR'
3924 Current blocking factor (*note Blocking::).
3927 Number of the checkpoint.
3930 A short option describing the operation 'tar' is executing. *Note
3931 Operations::, for a complete list of subcommand options.
3934 Format of the archive being processed. *Note Formats::, for a
3935 complete list of archive format names.
3937 These environment variables can also be passed as arguments to the
3938 command, provided that they are properly escaped, for example:
3941 --checkpoint-action='exec=/sbin/cpoint $TAR_CHECKPOINT'
3943 Notice single quotes to prevent variable names from being expanded by
3944 the shell when invoking 'tar'.
3946 Any number of actions can be defined, by supplying several
3947 '--checkpoint-action' options in the command line. For example, the
3948 command below displays two messages, pauses execution for 30 seconds and
3949 executes the '/sbin/cpoint' script:
3951 $ tar -c -f arc.tar \
3952 --checkpoint-action='\aecho=Hit %s checkpoint #%u' \
3953 --checkpoint-action='echo=Sleeping for 30 seconds' \
3954 --checkpoint-action='sleep=30' \
3955 --checkpoint-action='exec=/sbin/cpoint'
3957 This example also illustrates the fact that '--checkpoint-action' can
3958 be used without '--checkpoint'. In this case, the default checkpoint
3959 frequency (at each 10th record) is assumed.
3962 File: tar.info, Node: warnings, Next: interactive, Prev: checkpoints, Up: tar invocation
3964 3.9 Controlling Warning Messages
3965 ================================
3967 Sometimes, while performing the requested task, GNU 'tar' notices some
3968 conditions that are not exactly errors, but which the user should be
3969 aware of. When this happens, 'tar' issues a "warning message"
3970 describing the condition. Warning messages are output to the standard
3971 error and they do not affect the exit code of 'tar' command.
3973 GNU 'tar' allows the user to suppress some or all of its warning
3977 Control display of the warning messages identified by KEYWORD. If
3978 KEYWORD starts with the prefix 'no-', such messages are suppressed.
3979 Otherwise, they are enabled.
3981 Multiple '--warning' messages accumulate.
3983 The tables below list allowed values for KEYWORD along with the
3984 warning messages they control.
3986 Keywords controlling 'tar' operation
3987 ------------------------------------
3990 Enable all warning messages. This is the default.
3992 Disable all warning messages.
3994 '%s: file name read contains nul character'
3996 'A lone zero block at %s'
3998 Keywords applicable for 'tar --create'
3999 --------------------------------------
4002 '%s: contains a cache directory tag %s; %s'
4004 '%s: File shrank by %s bytes; padding with zeros'
4006 '%s: file is on a different filesystem; not dumped'
4008 '%s: Unknown file type; file ignored'
4009 '%s: socket ignored'
4012 '%s: file is unchanged; not dumped'
4014 '%s: file is the archive; not dumped'
4016 '%s: File removed before we read it'
4018 '%s: file changed as we read it'
4020 Keywords applicable for 'tar --extract'
4021 ---------------------------------------
4024 '%s: skipping existing file'
4026 '%s: implausibly old time stamp %s'
4027 '%s: time stamp %s is %s s in the future'
4029 'Extracting contiguous files as regular files'
4031 'Attempting extraction of symbolic links as hard links'
4033 '%s: Unknown file type '%c', extracted as normal file'
4035 'Current %s is newer or same age'
4037 'Ignoring unknown extended header keyword '%s''
4039 Controls verbose description of failures occurring when trying to
4040 run alternative decompressor programs (*note alternative
4041 decompression programs::). This warning is disabled by default
4042 (unless '--verbose' is used). A common example of what you can get
4043 when using this warning is:
4045 $ tar --warning=decompress-program -x -f archive.Z
4046 tar (child): cannot run compress: No such file or directory
4047 tar (child): trying gzip
4049 This means that 'tar' first tried to decompress 'archive.Z' using
4050 'compress', and, when that failed, switched to 'gzip'.
4052 'Record size = %lu blocks'
4054 Keywords controlling incremental extraction:
4055 --------------------------------------------
4058 '%s: Directory has been renamed from %s'
4059 '%s: Directory has been renamed'
4061 '%s: Directory is new'
4063 '%s: directory is on a different device: not purging'
4065 'Malformed dumpdir: 'X' never used'
4068 File: tar.info, Node: interactive, Next: external, Prev: warnings, Up: tar invocation
4070 3.10 Asking for Confirmation During Operations
4071 ==============================================
4073 Typically, 'tar' carries out a command without stopping for further
4074 instructions. In some situations however, you may want to exclude some
4075 files and archive members from the operation (for instance if disk or
4076 storage space is tight). You can do this by excluding certain files
4077 automatically (*note Choosing::), or by performing an operation
4078 interactively, using the '--interactive' ('-w') option. 'tar' also
4079 accepts '--confirmation' for this option.
4081 When the '--interactive' ('-w') option is specified, before reading,
4082 writing, or deleting files, 'tar' first prints a message for each such
4083 file, telling what operation it intends to take, then asks for
4084 confirmation on the terminal. The actions which require confirmation
4085 include adding a file to the archive, extracting a file from the
4086 archive, deleting a file from the archive, and deleting a file from
4087 disk. To confirm the action, you must type a line of input beginning
4088 with 'y'. If your input line begins with anything other than 'y', 'tar'
4091 If 'tar' is reading the archive from the standard input, 'tar' opens
4092 the file '/dev/tty' to support the interactive communications.
4094 Verbose output is normally sent to standard output, separate from
4095 other error messages. However, if the archive is produced directly on
4096 standard output, then verbose output is mixed with errors on 'stderr'.
4097 Producing the archive on standard output may be used as a way to avoid
4098 using disk space, when the archive is soon to be consumed by another
4099 process reading it, say. Some people felt the need of producing an
4100 archive on stdout, still willing to segregate between verbose output and
4101 error output. A possible approach would be using a named pipe to
4102 receive the archive, and having the consumer process to read from that
4103 named pipe. This has the advantage of letting standard output free to
4104 receive verbose output, all separate from errors.
4107 File: tar.info, Node: external, Prev: interactive, Up: tar invocation
4109 3.11 Running External Commands
4110 ==============================
4112 Certain GNU 'tar' operations imply running external commands that you
4113 supply on the command line. One of such operations is checkpointing,
4114 described above (*note checkpoint exec::). Another example of this
4115 feature is the '-I' option, which allows you to supply the program to
4116 use for compressing or decompressing the archive (*note
4117 use-compress-program::).
4119 Whenever such operation is requested, 'tar' first splits the supplied
4120 command into words much like the shell does. It then treats the first
4121 word as the name of the program or the shell script to execute and the
4122 rest of words as its command line arguments. The program, unless given
4123 as an absolute file name, is searched in the shell's 'PATH'.
4125 Any additional information is normally supplied to external commands
4126 in environment variables, specific to each particular operation. For
4127 example, the '--checkpoint-action=exec' option, defines the
4128 'TAR_ARCHIVE' variable to the name of the archive being worked upon.
4129 You can, should the need be, use these variables in the command line of
4130 the external command. For example:
4132 $ tar -x -f archive.tar \
4133 --checkpoint-action=exec='printf "%04d in %32s\r" $TAR_CHECKPOINT $TAR_ARCHIVE'
4135 This command prints for each checkpoint its number and the name of the
4136 archive, using the same output line on the screen.
4138 Notice the use of single quotes to prevent variable names from being
4139 expanded by the shell when invoking 'tar'.
4142 File: tar.info, Node: operations, Next: Backups, Prev: tar invocation, Up: Top
4144 4 GNU 'tar' Operations
4145 **********************
4158 File: tar.info, Node: Basic tar, Next: Advanced tar, Up: operations
4160 4.1 Basic GNU 'tar' Operations
4161 ==============================
4163 The basic 'tar' operations, '--create' ('-c'), '--list' ('-t') and
4164 '--extract' ('--get', '-x'), are currently presented and described in
4165 the tutorial chapter of this manual. This section provides some
4166 complementary notes for these operations.
4171 Creating an empty archive would have some kind of elegance. One
4172 can initialize an empty archive and later use '--append' ('-r') for
4173 adding all members. Some applications would not welcome making an
4174 exception in the way of adding the first archive member. On the
4175 other hand, many people reported that it is dangerously too easy
4176 for 'tar' to destroy a magnetic tape with an empty archive(1). The
4177 two most common errors are:
4179 1. Mistakingly using 'create' instead of 'extract', when the
4180 intent was to extract the full contents of an archive. This
4181 error is likely: keys 'c' and 'x' are right next to each other
4182 on the QWERTY keyboard. Instead of being unpacked, the
4183 archive then gets wholly destroyed. When users speak about
4184 "exploding" an archive, they usually mean something else :-).
4186 2. Forgetting the argument to 'file', when the intent was to
4187 create an archive with a single file in it. This error is
4188 likely because a tired user can easily add the 'f' key to the
4189 cluster of option letters, by the mere force of habit, without
4190 realizing the full consequence of doing so. The usual
4191 consequence is that the single file, which was meant to be
4192 saved, is rather destroyed.
4194 So, recognizing the likelihood and the catastrophic nature of these
4195 errors, GNU 'tar' now takes some distance from elegance, and
4196 cowardly refuses to create an archive when '--create' option is
4197 given, there are no arguments besides options, and '--files-from'
4198 ('-T') option is _not_ used. To get around the cautiousness of GNU
4199 'tar' and nevertheless create an archive with nothing in it, one
4200 may still use, as the value for the '--files-from' option, a file
4201 with no names in it, as shown in the following commands:
4203 tar --create --file=empty-archive.tar --files-from=/dev/null
4204 tar -cf empty-archive.tar -T /dev/null
4210 A socket is stored, within a GNU 'tar' archive, as a pipe.
4214 GNU 'tar' now shows dates as '1996-08-30', while it used to show
4215 them as 'Aug 30 1996'. Preferably, people should get used to ISO
4216 8601 dates. Local American dates should be made available again
4217 with full date localization support, once ready. In the meantime,
4218 programs not being localizable for dates should prefer
4219 international dates, that's really the way to go.
4221 Look up <http://www.cl.cam.ac.uk/~mgk25/iso-time.html> if you are
4222 curious, it contains a detailed explanation of the ISO 8601
4225 ---------- Footnotes ----------
4227 (1) This is well described in 'Unix-haters Handbook', by Simson
4228 Garfinkel, Daniel Weise & Steven Strassmann, IDG Books, ISBN
4232 File: tar.info, Node: Advanced tar, Next: create options, Prev: Basic tar, Up: operations
4234 4.2 Advanced GNU 'tar' Operations
4235 =================================
4237 Now that you have learned the basics of using GNU 'tar', you may want to
4238 learn about further ways in which 'tar' can help you.
4240 This chapter presents five, more advanced operations which you
4241 probably won't use on a daily basis, but which serve more specialized
4242 functions. We also explain the different styles of options and why you
4243 might want to use one or another, or a combination of them in your 'tar'
4244 commands. Additionally, this chapter includes options which allow you
4245 to define the output from 'tar' more carefully, and provide help and
4246 error correction in special circumstances.
4258 File: tar.info, Node: Operations, Next: append, Up: Advanced tar
4260 4.2.1 The Five Advanced 'tar' Operations
4261 ----------------------------------------
4263 In the last chapter, you learned about the first three operations to
4264 'tar'. This chapter presents the remaining five operations to 'tar':
4265 '--append', '--update', '--concatenate', '--delete', and '--compare'.
4267 You are not likely to use these operations as frequently as those
4268 covered in the last chapter; however, since they perform specialized
4269 functions, they are quite useful when you do need to use them. We will
4270 give examples using the same directory and files that you created in the
4271 last chapter. As you may recall, the directory is called 'practice',
4272 the files are 'jazz', 'blues', 'folk', and the two archive files you
4273 created are 'collection.tar' and 'music.tar'.
4275 We will also use the archive files 'afiles.tar' and 'bfiles.tar'.
4276 The archive 'afiles.tar' contains the members 'apple', 'angst', and
4277 'aspic'; 'bfiles.tar' contains the members './birds', 'baboon', and
4280 Unless we state otherwise, all practicing you do and examples you
4281 follow in this chapter will take place in the 'practice' directory that
4282 you created in the previous chapter; see *note prepare for examples::.
4283 (Below in this section, we will remind you of the state of the examples
4284 where the last chapter left them.)
4286 The five operations that we will cover in this chapter are:
4290 Add new entries to an archive that already exists.
4293 Add more recent copies of archive members to the end of an archive,
4298 Add one or more pre-existing archives to the end of another
4301 Delete items from an archive (does not work on tapes).
4305 Compare archive members to their counterparts in the file system.
4308 File: tar.info, Node: append, Next: update, Prev: Operations, Up: Advanced tar
4310 4.2.2 How to Add Files to Existing Archives: '--append'
4311 -------------------------------------------------------
4313 If you want to add files to an existing archive, you don't need to
4314 create a new archive; you can use '--append' ('-r'). The archive must
4315 already exist in order to use '--append'. (A related operation is the
4316 '--update' operation; you can use this to add newer versions of archive
4317 members to an existing archive. To learn how to do this with
4318 '--update', *note update::.)
4320 If you use '--append' to add a file that has the same name as an
4321 archive member to an archive containing that archive member, then the
4322 old member is not deleted. What does happen, however, is somewhat
4323 complex. 'tar' _allows_ you to have infinite number of files with the
4324 same name. Some operations treat these same-named members no
4325 differently than any other set of archive members: for example, if you
4326 view an archive with '--list' ('-t'), you will see all of those members
4327 listed, with their data modification times, owners, etc.
4329 Other operations don't deal with these members as perfectly as you
4330 might prefer; if you were to use '--extract' to extract the archive,
4331 only the most recently added copy of a member with the same name as
4332 other members would end up in the working directory. This is because
4333 '--extract' extracts an archive in the order the members appeared in the
4334 archive; the most recently archived members will be extracted last.
4335 Additionally, an extracted member will _replace_ a file of the same name
4336 which existed in the directory already, and 'tar' will not prompt you
4337 about this(1). Thus, only the most recently archived member will end up
4338 being extracted, as it will replace the one extracted before it, and so
4341 There exists a special option that allows you to get around this
4342 behavior and extract (or list) only a particular copy of the file. This
4343 is '--occurrence' option. If you run 'tar' with this option, it will
4344 extract only the first copy of the file. You may also give this option
4345 an argument specifying the number of copy to be extracted. Thus, for
4346 example if the archive 'archive.tar' contained three copies of file
4347 'myfile', then the command
4349 tar --extract --file archive.tar --occurrence=2 myfile
4351 would extract only the second copy. *Note --occurrence: Option Summary,
4352 for the description of '--occurrence' option.
4354 If you want to replace an archive member, use '--delete' to delete
4355 the member you want to remove from the archive, and then use '--append'
4356 to add the member you want to be in the archive. Note that you can not
4357 change the order of the archive; the most recently added member will
4358 still appear last. In this sense, you cannot truly "replace" one member
4359 with another. (Replacing one member with another will not work on
4360 certain types of media, such as tapes; see *note delete:: and *note
4361 Media::, for more information.)
4365 * appending files:: Appending Files to an Archive
4368 ---------- Footnotes ----------
4370 (1) Unless you give it '--keep-old-files' (or '--skip-old-files')
4371 option, or the disk copy is newer than the one in the archive and you
4372 invoke 'tar' with '--keep-newer-files' option.
4375 File: tar.info, Node: appending files, Next: multiple, Up: append
4377 4.2.2.1 Appending Files to an Archive
4378 .....................................
4380 The simplest way to add a file to an already existing archive is the
4381 '--append' ('-r') operation, which writes specified files into the
4382 archive whether or not they are already among the archived files.
4384 When you use '--append', you _must_ specify file name arguments, as
4385 there is no default. If you specify a file that already exists in the
4386 archive, another copy of the file will be added to the end of the
4387 archive. As with other operations, the member names of the newly added
4388 files will be exactly the same as their names given on the command line.
4389 The '--verbose' ('-v') option will print out the names of the files as
4390 they are written into the archive.
4392 '--append' cannot be performed on some tape drives, unfortunately,
4393 due to deficiencies in the formats those tape drives use. The archive
4394 must be a valid 'tar' archive, or else the results of using this
4395 operation will be unpredictable. *Note Media::.
4397 To demonstrate using '--append' to add a file to an archive, create a
4398 file called 'rock' in the 'practice' directory. Make sure you are in
4399 the 'practice' directory. Then, run the following 'tar' command to add
4400 'rock' to 'collection.tar':
4402 $ tar --append --file=collection.tar rock
4404 If you now use the '--list' ('-t') operation, you will see that 'rock'
4405 has been added to the archive:
4407 $ tar --list --file=collection.tar
4408 -rw-r--r-- me/user 28 1996-10-18 16:31 jazz
4409 -rw-r--r-- me/user 21 1996-09-23 16:44 blues
4410 -rw-r--r-- me/user 20 1996-09-23 16:44 folk
4411 -rw-r--r-- me/user 20 1996-09-23 16:44 rock
4414 File: tar.info, Node: multiple, Prev: appending files, Up: append
4416 4.2.2.2 Multiple Members with the Same Name
4417 ...........................................
4419 You can use '--append' ('-r') to add copies of files which have been
4420 updated since the archive was created. (However, we do not recommend
4421 doing this since there is another 'tar' option called '--update'; *Note
4422 update::, for more information. We describe this use of '--append' here
4423 for the sake of completeness.) When you extract the archive, the older
4424 version will be effectively lost. This works because files are
4425 extracted from an archive in the order in which they were archived.
4426 Thus, when the archive is extracted, a file archived later in time will
4427 replace a file of the same name which was archived earlier, even though
4428 the older version of the file will remain in the archive unless you
4429 delete all versions of the file.
4431 Supposing you change the file 'blues' and then append the changed
4432 version to 'collection.tar'. As you saw above, the original 'blues' is
4433 in the archive 'collection.tar'. If you change the file and append the
4434 new version of the file to the archive, there will be two copies in the
4435 archive. When you extract the archive, the older version of the file
4436 will be extracted first, and then replaced by the newer version when it
4439 You can append the new, changed copy of the file 'blues' to the
4440 archive in this way:
4442 $ tar --append --verbose --file=collection.tar blues
4445 Because you specified the '--verbose' option, 'tar' has printed the name
4446 of the file being appended as it was acted on. Now list the contents of
4449 $ tar --list --verbose --file=collection.tar
4450 -rw-r--r-- me/user 28 1996-10-18 16:31 jazz
4451 -rw-r--r-- me/user 21 1996-09-23 16:44 blues
4452 -rw-r--r-- me/user 20 1996-09-23 16:44 folk
4453 -rw-r--r-- me/user 20 1996-09-23 16:44 rock
4454 -rw-r--r-- me/user 58 1996-10-24 18:30 blues
4456 The newest version of 'blues' is now at the end of the archive (note the
4457 different creation dates and file sizes). If you extract the archive,
4458 the older version of the file 'blues' will be replaced by the newer
4459 version. You can confirm this by extracting the archive and running
4460 'ls' on the directory.
4462 If you wish to extract the first occurrence of the file 'blues' from
4463 the archive, use '--occurrence' option, as shown in the following
4466 $ tar --extract -vv --occurrence --file=collection.tar blues
4467 -rw-r--r-- me/user 21 1996-09-23 16:44 blues
4469 *Note Writing::, for more information on '--extract' and see *note
4470 -occurrence: Option Summary, for a description of '--occurrence' option.
4473 File: tar.info, Node: update, Next: concatenate, Prev: append, Up: Advanced tar
4475 4.2.3 Updating an Archive
4476 -------------------------
4478 In the previous section, you learned how to use '--append' to add a file
4479 to an existing archive. A related operation is '--update' ('-u'). The
4480 '--update' operation updates a 'tar' archive by comparing the date of
4481 the specified archive members against the date of the file with the same
4482 name. If the file has been modified more recently than the archive
4483 member, then the newer version of the file is added to the archive (as
4486 Unfortunately, you cannot use '--update' with magnetic tape drives.
4487 The operation will fail.
4489 Both '--update' and '--append' work by adding to the end of the
4490 archive. When you extract a file from the archive, only the version
4491 stored last will wind up in the file system, unless you use the
4492 '--backup' option. *Note multiple::, for a detailed discussion.
4499 File: tar.info, Node: how to update, Up: update
4501 4.2.3.1 How to Update an Archive Using '--update'
4502 .................................................
4504 You must use file name arguments with the '--update' ('-u') operation.
4505 If you don't specify any files, 'tar' won't act on any files and won't
4506 tell you that it didn't do anything (which may end up confusing you).
4508 To see the '--update' option at work, create a new file, 'classical',
4509 in your practice directory, and some extra text to the file 'blues',
4510 using any text editor. Then invoke 'tar' with the 'update' operation
4511 and the '--verbose' ('-v') option specified, using the names of all the
4512 files in the 'practice' directory as file name arguments:
4514 $ tar --update -v -f collection.tar blues folk rock classical
4519 Because we have specified verbose mode, 'tar' prints out the names of
4520 the files it is working on, which in this case are the names of the
4521 files that needed to be updated. If you run 'tar --list' and look at
4522 the archive, you will see 'blues' and 'classical' at its end. There
4523 will be a total of two versions of the member 'blues'; the one at the
4524 end will be newer and larger, since you added text before updating it.
4526 The reason 'tar' does not overwrite the older file when updating it
4527 is because writing to the middle of a section of tape is a difficult
4528 process. Tapes are not designed to go backward. *Note Media::, for
4529 more information about tapes.
4531 '--update' ('-u') is not suitable for performing backups for two
4532 reasons: it does not change directory content entries, and it lengthens
4533 the archive every time it is used. The GNU 'tar' options intended
4534 specifically for backups are more efficient. If you need to run
4535 backups, please consult *note Backups::.
4538 File: tar.info, Node: concatenate, Next: delete, Prev: update, Up: Advanced tar
4540 4.2.4 Combining Archives with '--concatenate'
4541 ---------------------------------------------
4543 Sometimes it may be convenient to add a second archive onto the end of
4544 an archive rather than adding individual files to the archive. To add
4545 one or more archives to the end of another archive, you should use the
4546 '--concatenate' ('--catenate', '-A') operation.
4548 To use '--concatenate', give the first archive with '--file' option
4549 and name the rest of archives to be concatenated on the command line.
4550 The members, and their member names, will be copied verbatim from those
4551 archives to the first one(1). The new, concatenated archive will be
4552 called by the same name as the one given with the '--file' option. As
4553 usual, if you omit '--file', 'tar' will use the value of the environment
4554 variable 'TAPE', or, if this has not been set, the default archive name.
4556 To demonstrate how '--concatenate' works, create two small archives
4557 called 'bluesrock.tar' and 'folkjazz.tar', using the relevant files from
4560 $ tar -cvf bluesrock.tar blues rock
4563 $ tar -cvf folkjazz.tar folk jazz
4567 If you like, You can run 'tar --list' to make sure the archives contain
4568 what they are supposed to:
4570 $ tar -tvf bluesrock.tar
4571 -rw-r--r-- melissa/user 105 1997-01-21 19:42 blues
4572 -rw-r--r-- melissa/user 33 1997-01-20 15:34 rock
4573 $ tar -tvf jazzfolk.tar
4574 -rw-r--r-- melissa/user 20 1996-09-23 16:44 folk
4575 -rw-r--r-- melissa/user 65 1997-01-30 14:15 jazz
4577 We can concatenate these two archives with 'tar':
4580 $ tar --concatenate --file=bluesrock.tar jazzfolk.tar
4582 If you now list the contents of the 'bluesrock.tar', you will see
4583 that now it also contains the archive members of 'jazzfolk.tar':
4585 $ tar --list --file=bluesrock.tar
4591 When you use '--concatenate', the source and target archives must
4592 already exist and must have been created using compatible format
4593 parameters. Notice, that 'tar' does not check whether the archives it
4594 concatenates have compatible formats, it does not even check if the
4595 files are really tar archives.
4597 Like '--append' ('-r'), this operation cannot be performed on some
4598 tape drives, due to deficiencies in the formats those tape drives use.
4600 It may seem more intuitive to you to want or try to use 'cat' to
4601 concatenate two archives instead of using the '--concatenate' operation;
4602 after all, 'cat' is the utility for combining files.
4604 However, 'tar' archives incorporate an end-of-file marker which must
4605 be removed if the concatenated archives are to be read properly as one
4606 archive. '--concatenate' removes the end-of-archive marker from the
4607 target archive before each new archive is appended. If you use 'cat' to
4608 combine the archives, the result will not be a valid 'tar' format
4609 archive. If you need to retrieve files from an archive that was added
4610 to using the 'cat' utility, use the '--ignore-zeros' ('-i') option.
4611 *Note Ignore Zeros::, for further information on dealing with archives
4612 improperly combined using the 'cat' shell utility.
4614 ---------- Footnotes ----------
4616 (1) This can cause multiple members to have the same name. For
4617 information on how this affects reading the archive, see *note
4621 File: tar.info, Node: delete, Next: compare, Prev: concatenate, Up: Advanced tar
4623 4.2.5 Removing Archive Members Using '--delete'
4624 -----------------------------------------------
4626 You can remove members from an archive by using the '--delete' option.
4627 Specify the name of the archive with '--file' ('-f') and then specify
4628 the names of the members to be deleted; if you list no member names,
4629 nothing will be deleted. The '--verbose' option will cause 'tar' to
4630 print the names of the members as they are deleted. As with
4631 '--extract', you must give the exact member names when using 'tar
4632 --delete'. '--delete' will remove all versions of the named file from
4633 the archive. The '--delete' operation can run very slowly.
4635 Unlike other operations, '--delete' has no short form.
4637 This operation will rewrite the archive. You can only use '--delete'
4638 on an archive if the archive device allows you to write to any point on
4639 the media, such as a disk; because of this, it does not work on magnetic
4640 tapes. Do not try to delete an archive member from a magnetic tape; the
4641 action will not succeed, and you will be likely to scramble the archive
4642 and damage your tape. There is no safe way (except by completely
4643 re-writing the archive) to delete files from most kinds of magnetic
4644 tape. *Note Media::.
4646 To delete all versions of the file 'blues' from the archive
4647 'collection.tar' in the 'practice' directory, make sure you are in that
4648 directory, and then,
4650 $ tar --list --file=collection.tar
4655 $ tar --delete --file=collection.tar blues
4656 $ tar --list --file=collection.tar
4661 The '--delete' option has been reported to work properly when 'tar'
4662 acts as a filter from 'stdin' to 'stdout'.
4665 File: tar.info, Node: compare, Prev: delete, Up: Advanced tar
4667 4.2.6 Comparing Archive Members with the File System
4668 ----------------------------------------------------
4670 The '--compare' ('-d'), or '--diff' operation compares specified archive
4671 members against files with the same names, and then reports differences
4672 in file size, mode, owner, modification date and contents. You should
4673 _only_ specify archive member names, not file names. If you do not name
4674 any members, then 'tar' will compare the entire archive. If a file is
4675 represented in the archive but does not exist in the file system, 'tar'
4676 reports a difference.
4678 You have to specify the record size of the archive when modifying an
4679 archive with a non-default record size.
4681 'tar' ignores files in the file system that do not have corresponding
4682 members in the archive.
4684 The following example compares the archive members 'rock', 'blues'
4685 and 'funk' in the archive 'bluesrock.tar' with files of the same name in
4686 the file system. (Note that there is no file, 'funk'; 'tar' will report
4689 $ tar --compare --file=bluesrock.tar rock blues funk
4692 tar: funk not found in archive
4694 The spirit behind the '--compare' ('--diff', '-d') option is to check
4695 whether the archive represents the current state of files on disk, more
4696 than validating the integrity of the archive media. For this latter
4697 goal, see *note verify::.
4700 File: tar.info, Node: create options, Next: extract options, Prev: Advanced tar, Up: operations
4702 4.3 Options Used by '--create'
4703 ==============================
4705 The previous chapter described the basics of how to use '--create'
4706 ('-c') to create an archive from a set of files. *Note create::. This
4707 section described advanced options to be used with '--create'.
4711 * override:: Overriding File Metadata.
4712 * Extended File Attributes::
4713 * Ignore Failed Read::
4716 File: tar.info, Node: override, Next: Extended File Attributes, Up: create options
4718 4.3.1 Overriding File Metadata
4719 ------------------------------
4721 As described above, a 'tar' archive keeps, for each member it contains,
4722 its "metadata", such as modification time, mode and ownership of the
4723 file. GNU 'tar' allows to replace these data with other values when
4724 adding files to the archive. The options described in this section
4725 affect creation of archives of any type. For POSIX archives, see also
4726 *note PAX keywords::, for additional ways of controlling metadata,
4727 stored in the archive.
4729 '--mode=PERMISSIONS'
4731 When adding files to an archive, 'tar' will use PERMISSIONS for the
4732 archive members, rather than the permissions from the files.
4733 PERMISSIONS can be specified either as an octal number or as
4734 symbolic permissions, like with 'chmod' (*Note Permissions:
4735 (fileutils)File permissions. This reference also has useful
4736 information for those not being overly familiar with the UNIX
4737 permission system). Using latter syntax allows for more
4738 flexibility. For example, the value 'a+rw' adds read and write
4739 permissions for everybody, while retaining executable bits on
4740 directories or on any other file already marked as executable:
4742 $ tar -c -f archive.tar --mode='a+rw' .
4746 When adding files to an archive, 'tar' will use DATE as the
4747 modification time of members when creating archives, instead of
4748 their actual modification times. The argument DATE can be either a
4749 textual date representation in almost arbitrary format (*note Date
4750 input formats::) or a name of an existing file, starting with '/'
4751 or '.'. In the latter case, the modification time of that file
4754 The following example will set the modification date to 00:00:00,
4757 $ tar -c -f archive.tar --mtime='1970-01-01' .
4759 When used with '--verbose' (*note verbose tutorial::) GNU 'tar'
4760 will try to convert the specified date back to its textual
4761 representation and compare it with the one given with '--mtime'
4762 options. If the two dates differ, 'tar' will print a warning
4763 saying what date it will use. This is to help user ensure he is
4764 using the right date.
4768 $ tar -c -f archive.tar -v --mtime=yesterday .
4769 tar: Option --mtime: Treating date 'yesterday' as 2006-06-20
4773 When used with '--clamp-mtime' GNU 'tar' will only set the
4774 modification date to DATE on files whose actual modification date
4775 is later than DATE. This is to make it easy to build reproducible
4776 archives given a common timestamp for generated files while still
4777 retaining the original timestamps of untouched files.
4779 $ tar -c -f archive.tar --clamp-mtime --mtime=@$SOURCE_DATE_EPOCH .
4783 Specifies that 'tar' should use USER as the owner of members when
4784 creating archives, instead of the user associated with the source
4787 If USER contains a colon, it is taken to be of the form NAME:ID
4788 where a nonempty NAME specifies the user name and a nonempty ID
4789 specifies the decimal numeric user ID. If USER does not contain a
4790 colon, it is taken to be a user number if it is one or more decimal
4791 digits; otherwise it is taken to be a user name.
4793 If a name is given but no number, the number is inferred from the
4794 current host's user database if possible, and the file's user
4795 number is used otherwise. If a number is given but no name, the
4796 name is inferred from the number if possible, and an empty name is
4797 used otherwise. If both name and number are given, the user
4798 database is not consulted, and the name and number need not be
4799 valid on the current host.
4801 There is no value indicating a missing number, and '0' usually
4802 means 'root'. Some people like to force '0' as the value to offer
4803 in their distributions for the owner of files, because the 'root'
4804 user is anonymous anyway, so that might as well be the owner of
4805 anonymous archives. For example:
4807 $ tar -c -f archive.tar --owner=0 .
4811 $ tar -c -f archive.tar --owner=root .
4815 Files added to the 'tar' archive will have a group ID of GROUP,
4816 rather than the group from the source file. As with '--owner', the
4817 argument GROUP can be an existing group symbolic name, or a decimal
4818 numeric group ID, or NAME:ID.
4820 The '--owner' and '--group' options affect all files added to the
4821 archive. GNU 'tar' provides also two options that allow for more
4822 detailed control over owner translation:
4825 Read UID translation map from FILE.
4827 When reading, empty lines are ignored. The '#' sign, unless
4828 quoted, introduces a comment, which extends to the end of the line.
4829 Each nonempty line defines mapping for a single UID. It must
4830 consist of two fields separated by any amount of whitespace. The
4831 first field defines original username and UID. It can be a valid
4832 user name or a valid UID prefixed with a plus sign. In both cases
4833 the corresponding UID or user name is inferred from the current
4834 host's user database.
4836 The second field defines the UID and username to map the original
4837 one to. Its format can be the same as described above. Otherwise,
4838 it can have the form NEWNAME:NEWUID, in which case neither NEWNAME
4839 nor NEWUID are required to be valid as per the user database.
4841 For example, consider the following file:
4846 Given this file, each input file that is owner by UID 10 will be
4847 stored in archive with owner name 'bin' and owner UID corresponding
4848 to 'bin'. Each file owned by user 'smith' will be stored with
4849 owner name 'root' and owner ID 0. Other files will remain
4852 When used together with '--owner-map', the '--owner' option affects
4853 only files whose owner is not listed in the map file.
4856 Read GID translation map from FILE.
4858 The format of FILE is the same as for '--owner-map' option:
4860 Each nonempty line defines mapping for a single GID. It must
4861 consist of two fields separated by any amount of whitespace. The
4862 first field defines original group name and GID. It can be a valid
4863 group name or a valid GID prefixed with a plus sign. In both cases
4864 the corresponding GID or user name is inferred from the current
4865 host's group database.
4867 The second field defines the GID and group name to map the original
4868 one to. Its format can be the same as described above. Otherwise,
4869 it can have the form NEWNAME:NEWGID, in which case neither NEWNAME
4870 nor NEWGID are required to be valid as per the group database.
4872 When used together with '--group-map', the '--group' option affects
4873 only files whose owner group is not rewritten using the map file.
4876 File: tar.info, Node: Extended File Attributes, Next: Ignore Failed Read, Prev: override, Up: create options
4878 4.3.2 Extended File Attributes
4879 ------------------------------
4881 Extended file attributes are name-value pairs that can be associated
4882 with each node in a file system. Despite the fact that POSIX.1e draft
4883 which proposed them has been withdrawn, the extended file attributes are
4884 supported by many file systems. GNU 'tar' can store extended file
4885 attributes along with the files. This feature is controlled by the
4886 following command line arguments:
4889 Enable extended attributes support. When used with '--create',
4890 this option instructs GNU 'tar' to store extended file attribute in
4891 the created archive. This implies POSIX.1-2001 archive format
4894 When used with '--extract', this option tells 'tar', for each file
4895 extracted, to read stored attributes from the archive and to apply
4899 Disable extended attributes support. This is the default.
4901 Attribute names are strings prefixed by a "namespace" name and a dot.
4902 Currently, four namespaces exist: 'user', 'trusted', 'security' and
4903 'system'. By default, when '--xattr' is used, all names are stored in
4904 the archive (or extracted, if using '--extract'). This can be
4905 controlled using the following options:
4907 '--xattrs-exclude=PATTERN'
4908 Specify exclude pattern for extended attributes.
4910 '--xattrs-include=PATTERN'
4911 Specify include pattern for extended attributes.
4913 Here, the PATTERN is POSIX regular expression. For example, the
4916 $ tar --xattrs --xattrs-exclude='^user\.' -c a.tar .
4918 will include in the archive 'a.tar' all attributes, except those from
4919 the 'user' namespace.
4921 Any number of these options can be given, thereby creating lists of
4922 include and exclude patterns.
4924 When both options are used, first '--xattrs-inlcude' is applied to
4925 select the set of attribute names to keep, and then '--xattrs-exclude'
4926 is applied to the resulting set. In other words, only those attributes
4927 will be stored, whose names match one of the regexps in
4928 '--xattrs-inlcude' and don't match any of the regexps from
4931 When listing the archive, if both '--xattrs' and '--verbose' options
4932 are given, files that have extended attributes are marked with an
4933 asterisk following their permission mask. For example:
4935 -rw-r--r--* smith/users 110 2016-03-16 16:07 file
4937 When two or more '--verbose' options are given, a detailed listing of
4938 extended attributes is printed after each file entry. Each attribute is
4939 listed on a separate line, which begins with two spaces and the letter
4940 'x' indicating extended attribute. It is followed by a colon, length of
4941 the attribute and its name, e.g.:
4943 -rw-r--r--* smith/users 110 2016-03-16 16:07 file
4945 x: 32 trusted.md5sum
4947 File access control lists ("ACL") are another actively used feature
4948 proposed by the POSIX.1e standard. Each ACL consists of a set of ACL
4949 entries, each of which describes the access permissions on the file for
4950 an individual user or a group of users as a combination of read, write
4951 and search/execute permissions.
4953 Whether or not to use ACLs is controlled by the following two
4957 Enable POSIX ACLs support. When used with '--create', this option
4958 instructs GNU 'tar' to store ACLs in the created archive. This
4959 implies POSIX.1-2001 archive format ('--format=pax').
4961 When used with '--extract', this option tells 'tar', to restore
4962 ACLs for each file extracted (provided they are present in the
4966 Disable POSIX ACLs support. This is the default.
4968 When listing the archive, if both '--acls' and '--verbose' options
4969 are given, files that have ACLs are marked with a plus sing following
4970 their permission mask. For example:
4972 -rw-r--r--+ smith/users 110 2016-03-16 16:07 file
4974 When two or more '--verbose' options are given, a detailed listing of
4975 ACL is printed after each file entry:
4977 -rw-r--r--+ smith/users 110 2016-03-16 16:07 file
4978 a: user::rw-,user:gray:-w-,group::r--,mask::rw-,other::r--
4980 "Security-Enhanced Linux" ("SELinux" for short) is a Linux kernel
4981 security module that provides a mechanism for supporting access control
4982 security policies, including so-called mandatory access controls
4983 ("MAC"). Support for SELinux attributes is controlled by the following
4984 command line options:
4987 Enable the SELinux context support.
4990 Disable SELinux context support.
4993 File: tar.info, Node: Ignore Failed Read, Prev: Extended File Attributes, Up: create options
4995 4.3.3 Ignore Fail Read
4996 ----------------------
4998 '--ignore-failed-read'
4999 Do not exit with nonzero on unreadable files or directories.
5002 File: tar.info, Node: extract options, Next: backup, Prev: create options, Up: operations
5004 4.4 Options Used by '--extract'
5005 ===============================
5007 The previous chapter showed how to use '--extract' to extract an archive
5008 into the file system. Various options cause 'tar' to extract more
5009 information than just file contents, such as the owner, the permissions,
5010 the modification date, and so forth. This section presents options to
5011 be used with '--extract' when certain special considerations arise. You
5012 may review the information presented in *note extract:: for more basic
5013 information about the '--extract' operation.
5017 * Reading:: Options to Help Read Archives
5018 * Writing:: Changing How 'tar' Writes Files
5019 * Scarce:: Coping with Scarce Resources
5022 File: tar.info, Node: Reading, Next: Writing, Up: extract options
5024 4.4.1 Options to Help Read Archives
5025 -----------------------------------
5027 Normally, 'tar' will request data in full record increments from an
5028 archive storage device. If the device cannot return a full record,
5029 'tar' will report an error. However, some devices do not always return
5030 full records, or do not require the last record of an archive to be
5031 padded out to the next record boundary. To keep reading until you
5032 obtain a full record, or to accept an incomplete record if it contains
5033 an end-of-archive marker, specify the '--read-full-records' ('-B')
5034 option in conjunction with the '--extract' or '--list' operations.
5037 The '--read-full-records' ('-B') option is turned on by default when
5038 'tar' reads an archive from standard input, or from a remote machine.
5039 This is because on BSD Unix systems, attempting to read a pipe returns
5040 however much happens to be in the pipe, even if it is less than was
5041 requested. If this option were not enabled, 'tar' would fail as soon as
5042 it read an incomplete record from the pipe.
5044 If you're not sure of the blocking factor of an archive, you can read
5045 the archive by specifying '--read-full-records' ('-B') and
5046 '--blocking-factor=512-SIZE' ('-b 512-SIZE'), using a blocking factor
5047 larger than what the archive uses. This lets you avoid having to
5048 determine the blocking factor of an archive. *Note Blocking Factor::.
5052 * read full records::
5056 File: tar.info, Node: read full records, Next: Ignore Zeros, Up: Reading
5058 Reading Full Records
5059 ....................
5061 '--read-full-records'
5063 Use in conjunction with '--extract' ('--get', '-x') to read an
5064 archive which contains incomplete records, or one which has a
5065 blocking factor less than the one specified.
5068 File: tar.info, Node: Ignore Zeros, Prev: read full records, Up: Reading
5070 Ignoring Blocks of Zeros
5071 ........................
5073 Normally, 'tar' stops reading when it encounters a block of zeros
5074 between file entries (which usually indicates the end of the archive).
5075 '--ignore-zeros' ('-i') allows 'tar' to completely read an archive which
5076 contains a block of zeros before the end (i.e., a damaged archive, or
5077 one that was created by concatenating several archives together).
5079 The '--ignore-zeros' ('-i') option is turned off by default because
5080 many versions of 'tar' write garbage after the end-of-archive entry,
5081 since that part of the media is never supposed to be read. GNU 'tar'
5082 does not write after the end of an archive, but seeks to maintain
5083 compatibility among archiving utilities.
5087 To ignore blocks of zeros (i.e., end-of-archive entries) which may
5088 be encountered while reading an archive. Use in conjunction with
5089 '--extract' or '--list'.
5092 File: tar.info, Node: Writing, Next: Scarce, Prev: Reading, Up: extract options
5094 4.4.2 Changing How 'tar' Writes Files
5095 -------------------------------------
5097 _(This message will disappear, once this node revised.)_
5101 * Dealing with Old Files::
5102 * Overwrite Old Files::
5104 * Keep Newer Files::
5106 * Recursive Unlink::
5107 * Data Modification Times::
5108 * Setting Access Permissions::
5109 * Directory Modification Times and Permissions::
5110 * Writing to Standard Output::
5111 * Writing to an External Program::
5115 File: tar.info, Node: Dealing with Old Files, Next: Overwrite Old Files, Up: Writing
5117 Options Controlling the Overwriting of Existing Files
5118 .....................................................
5120 When extracting files, if 'tar' discovers that the extracted file
5121 already exists, it normally replaces the file by removing it before
5122 extracting it, to prevent confusion in the presence of hard or symbolic
5123 links. (If the existing file is a symbolic link, it is removed, not
5124 followed.) However, if a directory cannot be removed because it is
5125 nonempty, 'tar' normally overwrites its metadata (ownership, permission,
5126 etc.). The '--overwrite-dir' option enables this default behavior. To
5127 be more cautious and preserve the metadata of such a directory, use the
5128 '--no-overwrite-dir' option.
5130 To be even more cautious and prevent existing files from being
5131 replaced, use the '--keep-old-files' ('-k') option. It causes 'tar' to
5132 refuse to replace or update a file that already exists, i.e., a file
5133 with the same name as an archive member prevents extraction of that
5134 archive member. Instead, it reports an error. For example:
5138 $ tar -x -k -f archive.tar
5139 tar: blues: Cannot open: File exists
5140 tar: Exiting with failure status due to previous errors
5142 If you wish to preserve old files untouched, but don't want 'tar' to
5143 treat them as errors, use the '--skip-old-files' option. This option
5144 causes 'tar' to silently skip extracting over existing files.
5146 To be more aggressive about altering existing files, use the
5147 '--overwrite' option. It causes 'tar' to overwrite existing files and
5148 to follow existing symbolic links when extracting.
5150 Some people argue that GNU 'tar' should not hesitate to overwrite
5151 files with other files when extracting. When extracting a 'tar'
5152 archive, they expect to see a faithful copy of the state of the file
5153 system when the archive was created. It is debatable that this would
5154 always be a proper behavior. For example, suppose one has an archive in
5155 which 'usr/local' is a link to 'usr/local2'. Since then, maybe the site
5156 removed the link and renamed the whole hierarchy from '/usr/local2' to
5157 '/usr/local'. Such things happen all the time. I guess it would not be
5158 welcome at all that GNU 'tar' removes the whole hierarchy just to make
5159 room for the link to be reinstated (unless it _also_ simultaneously
5160 restores the full '/usr/local2', of course!) GNU 'tar' is indeed able
5161 to remove a whole hierarchy to reestablish a symbolic link, for example,
5162 but _only if_ '--recursive-unlink' is specified to allow this behavior.
5163 In any case, single files are silently removed.
5165 Finally, the '--unlink-first' ('-U') option can improve performance
5166 in some cases by causing 'tar' to remove files unconditionally before
5170 File: tar.info, Node: Overwrite Old Files, Next: Keep Old Files, Prev: Dealing with Old Files, Up: Writing
5176 Overwrite existing files and directory metadata when extracting
5177 files from an archive.
5179 This causes 'tar' to write extracted files into the file system
5180 without regard to the files already on the system; i.e., files with
5181 the same names as archive members are overwritten when the archive
5182 is extracted. It also causes 'tar' to extract the ownership,
5183 permissions, and time stamps onto any preexisting files or
5184 directories. If the name of a corresponding file name is a
5185 symbolic link, the file pointed to by the symbolic link will be
5186 overwritten instead of the symbolic link itself (if this is
5187 possible). Moreover, special devices, empty directories and even
5188 symbolic links are automatically removed if they are in the way of
5191 Be careful when using the '--overwrite' option, particularly when
5192 combined with the '--absolute-names' ('-P') option, as this
5193 combination can change the contents, ownership or permissions of
5194 any file on your system. Also, many systems do not take kindly to
5195 overwriting files that are currently being executed.
5198 Overwrite the metadata of directories when extracting files from an
5199 archive, but remove other files before extracting.
5202 File: tar.info, Node: Keep Old Files, Next: Keep Newer Files, Prev: Overwrite Old Files, Up: Writing
5207 GNU 'tar' provides two options to control its actions in a situation
5208 when it is about to extract a file which already exists on disk.
5212 Do not replace existing files from archive. When such a file is
5213 encountered, 'tar' issues an error message. Upon end of
5214 extraction, 'tar' exits with code 2 (*note exit status::).
5217 Do not replace existing files from archive, but do not treat that
5218 as error. Such files are silently skipped and do not affect 'tar'
5221 Additional verbosity can be obtained using
5222 '--warning=existing-file' together with that option (*note
5226 File: tar.info, Node: Keep Newer Files, Next: Unlink First, Prev: Keep Old Files, Up: Writing
5231 '--keep-newer-files'
5232 Do not replace existing files that are newer than their archive
5233 copies. This option is meaningless with '--list' ('-t').
5236 File: tar.info, Node: Unlink First, Next: Recursive Unlink, Prev: Keep Newer Files, Up: Writing
5243 Remove files before extracting over them. This can make 'tar' run
5244 a bit faster if you know in advance that the extracted files all
5245 need to be removed. Normally this option slows 'tar' down
5246 slightly, so it is disabled by default.
5249 File: tar.info, Node: Recursive Unlink, Next: Data Modification Times, Prev: Unlink First, Up: Writing
5254 '--recursive-unlink'
5255 When this option is specified, try removing files and directory
5256 hierarchies before extracting over them. _This is a dangerous
5259 If you specify the '--recursive-unlink' option, 'tar' removes
5260 _anything_ that keeps you from extracting a file as far as current
5261 permissions will allow it. This could include removal of the contents
5262 of a full directory hierarchy.
5265 File: tar.info, Node: Data Modification Times, Next: Setting Access Permissions, Prev: Recursive Unlink, Up: Writing
5267 Setting Data Modification Times
5268 ...............................
5270 Normally, 'tar' sets the data modification times of extracted files to
5271 the corresponding times recorded for the files in the archive, but
5272 limits the permissions of extracted files by the current 'umask'
5275 To set the data modification times of extracted files to the time
5276 when the files were extracted, use the '--touch' ('-m') option in
5277 conjunction with '--extract' ('--get', '-x').
5281 Sets the data modification time of extracted archive members to the
5282 time they were extracted, not the time recorded for them in the
5283 archive. Use in conjunction with '--extract' ('--get', '-x').
5286 File: tar.info, Node: Setting Access Permissions, Next: Directory Modification Times and Permissions, Prev: Data Modification Times, Up: Writing
5288 Setting Access Permissions
5289 ..........................
5291 To set the modes (access permissions) of extracted files to those
5292 recorded for those files in the archive, use '--same-permissions' in
5293 conjunction with the '--extract' ('--get', '-x') operation.
5295 '--preserve-permissions'
5296 '--same-permissions'
5298 Set modes of extracted archive members to those recorded in the
5299 archive, instead of current umask settings. Use in conjunction
5300 with '--extract' ('--get', '-x').
5303 File: tar.info, Node: Directory Modification Times and Permissions, Next: Writing to Standard Output, Prev: Setting Access Permissions, Up: Writing
5305 Directory Modification Times and Permissions
5306 ............................................
5308 After successfully extracting a file member, GNU 'tar' normally restores
5309 its permissions and modification times, as described in the previous
5310 sections. This cannot be done for directories, because after extracting
5311 a directory 'tar' will almost certainly extract files into that
5312 directory and this will cause the directory modification time to be
5313 updated. Moreover, restoring that directory permissions may not permit
5314 file creation within it. Thus, restoring directory permissions and
5315 modification times must be delayed at least until all files have been
5316 extracted into that directory. GNU 'tar' restores directories using the
5319 The extracted directories are created with the mode specified in the
5320 archive, as modified by the umask of the user, which gives sufficient
5321 permissions to allow file creation. The meta-information about the
5322 directory is recorded in the temporary list of directories. When
5323 preparing to extract next archive member, GNU 'tar' checks if the
5324 directory prefix of this file contains the remembered directory. If it
5325 does not, the program assumes that all files have been extracted into
5326 that directory, restores its modification time and permissions and
5327 removes its entry from the internal list. This approach allows to
5328 correctly restore directory meta-information in the majority of cases,
5329 while keeping memory requirements sufficiently small. It is based on
5330 the fact, that most 'tar' archives use the predefined order of members:
5331 first the directory, then all the files and subdirectories in that
5334 However, this is not always true. The most important exception are
5335 incremental archives (*note Incremental Dumps::). The member order in
5336 an incremental archive is reversed: first all directory members are
5337 stored, followed by other (non-directory) members. So, when extracting
5338 from incremental archives, GNU 'tar' alters the above procedure. It
5339 remembers all restored directories, and restores their meta-data only
5340 after the entire archive has been processed. Notice, that you do not
5341 need to specify any special options for that, as GNU 'tar' automatically
5342 detects archives in incremental format.
5344 There may be cases, when such processing is required for normal
5345 archives too. Consider the following example:
5347 $ tar --no-recursion -cvf archive \
5348 foo foo/file1 bar bar/file foo/file2
5355 During the normal operation, after encountering 'bar' GNU 'tar' will
5356 assume that all files from the directory 'foo' were already extracted
5357 and will therefore restore its timestamp and permission bits. However,
5358 after extracting 'foo/file2' the directory timestamp will be offset
5361 To correctly restore directory meta-information in such cases, use
5362 the '--delay-directory-restore' command line option:
5364 '--delay-directory-restore'
5365 Delays restoring of the modification times and permissions of
5366 extracted directories until the end of extraction. This way,
5367 correct meta-information is restored even if the archive has
5368 unusual member ordering.
5370 '--no-delay-directory-restore'
5371 Cancel the effect of the previous '--delay-directory-restore'. Use
5372 this option if you have used '--delay-directory-restore' in
5373 'TAR_OPTIONS' variable (*note TAR_OPTIONS::) and wish to
5374 temporarily disable it.
5377 File: tar.info, Node: Writing to Standard Output, Next: Writing to an External Program, Prev: Directory Modification Times and Permissions, Up: Writing
5379 Writing to Standard Output
5380 ..........................
5382 To write the extracted files to the standard output, instead of creating
5383 the files on the file system, use '--to-stdout' ('-O') in conjunction
5384 with '--extract' ('--get', '-x'). This option is useful if you are
5385 extracting files to send them through a pipe, and do not need to
5386 preserve them in the file system. If you extract multiple members, they
5387 appear on standard output concatenated, in the order they are found in
5392 Writes files to the standard output. Use only in conjunction with
5393 '--extract' ('--get', '-x'). When this option is used, instead of
5394 creating the files specified, 'tar' writes the contents of the
5395 files extracted to its standard output. This may be useful if you
5396 are only extracting the files in order to send them through a pipe.
5397 This option is meaningless with '--list' ('-t').
5399 This can be useful, for example, if you have a tar archive containing
5400 a big file and don't want to store the file on disk before processing
5401 it. You can use a command like this:
5403 tar -xOzf foo.tgz bigfile | process
5405 or even like this if you want to process the concatenation of the
5408 tar -xOzf foo.tgz bigfile1 bigfile2 | process
5410 However, '--to-command' may be more convenient for use with multiple
5411 files. See the next section.
5414 File: tar.info, Node: Writing to an External Program, Next: remove files, Prev: Writing to Standard Output, Up: Writing
5416 Writing to an External Program
5417 ..............................
5419 You can instruct 'tar' to send the contents of each extracted file to
5420 the standard input of an external program:
5422 '--to-command=COMMAND'
5423 Extract files and pipe their contents to the standard input of
5424 COMMAND. When this option is used, instead of creating the files
5425 specified, 'tar' invokes COMMAND and pipes the contents of the
5426 files to its standard output. The COMMAND may contain command line
5427 arguments (see *note Running External Commands: external, for more
5430 Notice, that COMMAND is executed once for each regular file
5431 extracted. Non-regular files (directories, etc.) are ignored when
5432 this option is used.
5434 The command can obtain the information about the file it processes
5435 from the following environment variables:
5438 Type of the file. It is a single letter with the following
5448 Currently only regular files are supported.
5451 File mode, an octal number.
5454 The name of the file.
5457 Name of the file as stored in the archive.
5460 Name of the file owner.
5463 Name of the file owner group.
5466 Time of last access. It is a decimal number, representing seconds
5467 since the Epoch. If the archive provides times with nanosecond
5468 precision, the nanoseconds are appended to the timestamp after a
5472 Time of last modification.
5475 Time of last status change.
5481 UID of the file owner.
5484 GID of the file owner.
5486 Additionally, the following variables contain information about tar
5487 mode and the archive being processed:
5490 GNU 'tar' version number.
5493 The name of the archive 'tar' is processing.
5495 'TAR_BLOCKING_FACTOR'
5496 Current blocking factor (*note Blocking::).
5499 Ordinal number of the volume 'tar' is processing.
5502 Format of the archive being processed. *Note Formats::, for a
5503 complete list of archive format names.
5505 These variables are defined prior to executing the command, so you
5506 can pass them as arguments, if you prefer. For example, if the command
5507 PROC takes the member name and size as its arguments, then you could do:
5509 $ tar -x -f archive.tar \
5510 --to-command='proc $TAR_FILENAME $TAR_SIZE'
5512 Notice single quotes to prevent variable names from being expanded by
5513 the shell when invoking 'tar'.
5515 If COMMAND exits with a non-0 status, 'tar' will print an error
5516 message similar to the following:
5518 tar: 2345: Child returned status 1
5520 Here, '2345' is the PID of the finished process.
5522 If this behavior is not wanted, use '--ignore-command-error':
5524 '--ignore-command-error'
5525 Ignore exit codes of subprocesses. Notice that if the program
5526 exits on signal or otherwise terminates abnormally, the error
5527 message will be printed even if this option is used.
5529 '--no-ignore-command-error'
5530 Cancel the effect of any previous '--ignore-command-error' option.
5531 This option is useful if you have set '--ignore-command-error' in
5532 'TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to temporarily cancel
5536 File: tar.info, Node: remove files, Prev: Writing to an External Program, Up: Writing
5542 Remove files after adding them to the archive.
5545 File: tar.info, Node: Scarce, Prev: Writing, Up: extract options
5547 4.4.3 Coping with Scarce Resources
5548 ----------------------------------
5550 _(This message will disappear, once this node revised.)_
5558 File: tar.info, Node: Starting File, Next: Same Order, Up: Scarce
5563 '--starting-file=NAME'
5565 Starts an operation in the middle of an archive. Use in
5566 conjunction with '--extract' ('--get', '-x') or '--list' ('-t').
5568 If a previous attempt to extract files failed due to lack of disk
5569 space, you can use '--starting-file=NAME' ('-K NAME') to start
5570 extracting only after member NAME of the archive. This assumes, of
5571 course, that there is now free space, or that you are now extracting
5572 into a different file system. (You could also choose to suspend 'tar',
5573 remove unnecessary files from the file system, and then resume the same
5574 'tar' operation. In this case, '--starting-file' is not necessary.)
5575 See also *note interactive::, and *note exclude::.
5578 File: tar.info, Node: Same Order, Prev: Starting File, Up: Scarce
5586 To process large lists of file names on machines with small amounts
5587 of memory. Use in conjunction with '--compare' ('--diff', '-d'),
5588 '--list' ('-t') or '--extract' ('--get', '-x').
5590 The '--same-order' ('--preserve-order', '-s') option tells 'tar' that
5591 the list of file names to be listed or extracted is sorted in the same
5592 order as the files in the archive. This allows a large list of names to
5593 be used, even on a small machine that would not otherwise be able to
5594 hold all the names in memory at the same time. Such a sorted list can
5595 easily be created by running 'tar -t' on the archive and editing its
5598 This option is probably never needed on modern computer systems.
5601 File: tar.info, Node: backup, Next: Applications, Prev: extract options, Up: operations
5606 GNU 'tar' offers options for making backups of files before writing new
5607 versions. These options control the details of these backups. They may
5608 apply to the archive itself before it is created or rewritten, as well
5609 as individual extracted members. Other GNU programs ('cp', 'install',
5610 'ln', and 'mv', for example) offer similar options.
5612 Backup options may prove unexpectedly useful when extracting archives
5613 containing many members having identical name, or when extracting
5614 archives on systems having file name limitations, making different
5615 members appear as having similar names through the side-effect of name
5618 When any existing file is backed up before being overwritten by
5619 extraction, then clashing files are automatically be renamed to be
5620 unique, and the true name is kept for only the last file of a series of
5621 clashing files. By using verbose mode, users may track exactly what
5624 At the detail level, some decisions are still experimental, and may
5625 change in the future, we are waiting comments from our users. So,
5626 please do not learn to depend blindly on the details of the backup
5627 features. For example, currently, directories themselves are never
5628 renamed through using these options, so, extracting a file over a
5629 directory still has good chances to fail. Also, backup options apply to
5630 created archives, not only to extracted members. For created archives,
5631 backups will not be attempted when the archive is a block or character
5632 device, or when it refers to a remote file.
5634 For the sake of simplicity and efficiency, backups are made by
5635 renaming old files prior to creation or extraction, and not by copying.
5636 The original name is restored if the file creation fails. If a failure
5637 occurs after a partial extraction of a file, both the backup and the
5638 partially extracted file are kept.
5641 Back up files that are about to be overwritten or removed. Without
5642 this option, the original versions are destroyed.
5644 Use METHOD to determine the type of backups made. If METHOD is not
5645 specified, use the value of the 'VERSION_CONTROL' environment
5646 variable. And if 'VERSION_CONTROL' is not set, use the 'existing'
5649 This option corresponds to the Emacs variable 'version-control';
5650 the same values for METHOD are accepted as in Emacs. This option
5651 also allows more descriptive names. The valid METHODs are:
5655 Always make numbered backups.
5659 Make numbered backups of files that already have them, simple
5660 backups of the others.
5664 Always make simple backups.
5667 Append SUFFIX to each backup file made with '--backup'. If this
5668 option is not specified, the value of the 'SIMPLE_BACKUP_SUFFIX'
5669 environment variable is used. And if 'SIMPLE_BACKUP_SUFFIX' is not
5670 set, the default is '~', just as in Emacs.
5673 File: tar.info, Node: Applications, Next: looking ahead, Prev: backup, Up: operations
5675 4.6 Notable 'tar' Usages
5676 ========================
5678 _(This message will disappear, once this node revised.)_
5680 You can easily use archive files to transport a group of files from
5681 one system to another: put all relevant files into an archive on one
5682 computer system, transfer the archive to another system, and extract the
5683 contents there. The basic transfer medium might be magnetic tape,
5684 Internet FTP, or even electronic mail (though you must encode the
5685 archive with 'uuencode' in order to transport it properly by mail).
5686 Both machines do not have to use the same operating system, as long as
5687 they both support the 'tar' program.
5689 For example, here is how you might copy a directory's contents from
5690 one disk to another, while preserving the dates, modes, owners and
5691 link-structure of all the files therein. In this case, the transfer
5694 $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)
5696 You can avoid subshells by using '-C' option:
5698 $ tar -C sourcedir -cf - . | tar -C targetdir -xf -
5700 The command also works using long option forms:
5702 $ (cd sourcedir; tar --create --file=- . ) \
5703 | (cd targetdir; tar --extract --file=-)
5707 $ tar --directory sourcedir --create --file=- . \
5708 | tar --directory targetdir --extract --file=-
5710 This is one of the easiest methods to transfer a 'tar' archive.
5713 File: tar.info, Node: looking ahead, Prev: Applications, Up: operations
5715 4.7 Looking Ahead: The Rest of this Manual
5716 ==========================================
5718 You have now seen how to use all eight of the operations available to
5719 'tar', and a number of the possible options. The next chapter explains
5720 how to choose and change file and archive names, how to use files to
5721 store names of other files which you can then call as arguments to 'tar'
5722 (this can help you save time if you expect to archive the same list of
5723 files a number of times), and so forth.
5725 If there are too many files to conveniently list on the command line,
5726 you can list the names in a file, and 'tar' will read that file. *Note
5729 There are various ways of causing 'tar' to skip over some files, and
5730 not archive them. *Note Choosing::.
5733 File: tar.info, Node: Backups, Next: Choosing, Prev: operations, Up: Top
5735 5 Performing Backups and Restoring Files
5736 ****************************************
5738 GNU 'tar' is distributed along with the scripts for performing backups
5739 and restores. Even if there is a good chance those scripts may be
5740 satisfying to you, they are not the only scripts or methods available
5741 for doing backups and restore. You may well create your own, or use
5742 more sophisticated packages dedicated to that purpose.
5744 Some users are enthusiastic about 'Amanda' (The Advanced Maryland
5745 Automatic Network Disk Archiver), a backup system developed by James da
5746 Silva 'jds@cs.umd.edu' and available on many Unix systems. This is free
5747 software, and it is available from <http://www.amanda.org>.
5749 This chapter documents both the provided shell scripts and 'tar'
5750 options which are more specific to usage as a backup tool.
5752 To "back up" a file system means to create archives that contain all
5753 the files in that file system. Those archives can then be used to
5754 restore any or all of those files (for instance if a disk crashes or a
5755 file is accidentally deleted). File system "backups" are also called
5760 * Full Dumps:: Using 'tar' to Perform Full Dumps
5761 * Incremental Dumps:: Using 'tar' to Perform Incremental Dumps
5762 * Backup Levels:: Levels of Backups
5763 * Backup Parameters:: Setting Parameters for Backups and Restoration
5764 * Scripted Backups:: Using the Backup Scripts
5765 * Scripted Restoration:: Using the Restore Script
5768 File: tar.info, Node: Full Dumps, Next: Incremental Dumps, Up: Backups
5770 5.1 Using 'tar' to Perform Full Dumps
5771 =====================================
5773 _(This message will disappear, once this node revised.)_
5775 Full dumps should only be made when no other people or programs are
5776 modifying files in the file system. If files are modified while 'tar'
5777 is making the backup, they may not be stored properly in the archive, in
5778 which case you won't be able to restore them if you have to. (Files not
5779 being modified are written with no trouble, and do not corrupt the
5782 You will want to use the '--label=ARCHIVE-LABEL' ('-V ARCHIVE-LABEL')
5783 option to give the archive a volume label, so you can tell what this
5784 archive is even if the label falls off the tape, or anything like that.
5786 Unless the file system you are dumping is guaranteed to fit on one
5787 volume, you will need to use the '--multi-volume' ('-M') option. Make
5788 sure you have enough tapes on hand to complete the backup.
5790 If you want to dump each file system separately you will need to use
5791 the '--one-file-system' option to prevent 'tar' from crossing file
5792 system boundaries when storing (sub)directories.
5794 The '--incremental' ('-G') (*note Incremental Dumps::) option is not
5795 needed, since this is a complete copy of everything in the file system,
5796 and a full restore from this backup would only be done onto a completely
5799 Unless you are in a hurry, and trust the 'tar' program (and your
5800 tapes), it is a good idea to use the '--verify' ('-W') option, to make
5801 sure your files really made it onto the dump properly. This will also
5802 detect cases where the file was modified while (or just after) it was
5803 being archived. Not all media (notably cartridge tapes) are capable of
5804 being verified, unfortunately.
5807 File: tar.info, Node: Incremental Dumps, Next: Backup Levels, Prev: Full Dumps, Up: Backups
5809 5.2 Using 'tar' to Perform Incremental Dumps
5810 ============================================
5812 "Incremental backup" is a special form of GNU 'tar' archive that stores
5813 additional metadata so that exact state of the file system can be
5814 restored when extracting the archive.
5816 GNU 'tar' currently offers two options for handling incremental
5817 backups: '--listed-incremental=SNAPSHOT-FILE' ('-g SNAPSHOT-FILE') and
5818 '--incremental' ('-G').
5820 The option '--listed-incremental' instructs tar to operate on an
5821 incremental archive with additional metadata stored in a standalone
5822 file, called a "snapshot file". The purpose of this file is to help
5823 determine which files have been changed, added or deleted since the last
5824 backup, so that the next incremental backup will contain only modified
5825 files. The name of the snapshot file is given as an argument to the
5828 '--listed-incremental=FILE'
5830 Handle incremental backups with snapshot data in FILE.
5832 To create an incremental backup, you would use '--listed-incremental'
5833 together with '--create' (*note create::). For example:
5836 --file=archive.1.tar \
5837 --listed-incremental=/var/log/usr.snar \
5840 This will create in 'archive.1.tar' an incremental backup of the
5841 '/usr' file system, storing additional metadata in the file
5842 '/var/log/usr.snar'. If this file does not exist, it will be created.
5843 The created archive will then be a "level 0 backup"; please see the next
5844 section for more on backup levels.
5846 Otherwise, if the file '/var/log/usr.snar' exists, it determines
5847 which files are modified. In this case only these files will be stored
5848 in the archive. Suppose, for example, that after running the above
5849 command, you delete file '/usr/doc/old' and create directory
5850 '/usr/local/db' with the following contents:
5856 Some time later you create another incremental backup. You will then
5860 --file=archive.2.tar \
5861 --listed-incremental=/var/log/usr.snar \
5863 tar: usr/local/db: Directory is new
5868 The created archive 'archive.2.tar' will contain only these three
5869 members. This archive is called a "level 1 backup". Notice that
5870 '/var/log/usr.snar' will be updated with the new data, so if you plan to
5871 create more 'level 1' backups, it is necessary to create a working copy
5872 of the snapshot file before running 'tar'. The above example will then
5873 be modified as follows:
5875 $ cp /var/log/usr.snar /var/log/usr.snar-1
5877 --file=archive.2.tar \
5878 --listed-incremental=/var/log/usr.snar-1 \
5881 You can force 'level 0' backups either by removing the snapshot file
5882 before running 'tar', or by supplying the '--level=0' option, e.g.:
5885 --file=archive.2.tar \
5886 --listed-incremental=/var/log/usr.snar-0 \
5890 Incremental dumps depend crucially on time stamps, so the results are
5891 unreliable if you modify a file's time stamps during dumping (e.g., with
5892 the '--atime-preserve=replace' option), or if you set the clock
5895 Metadata stored in snapshot files include device numbers, which,
5896 obviously are supposed to be non-volatile values. However, it turns out
5897 that NFS devices have undependable values when an automounter gets in
5898 the picture. This can lead to a great deal of spurious redumping in
5899 incremental dumps, so it is somewhat useless to compare two NFS devices
5900 numbers over time. The solution implemented currently is to consider
5901 all NFS devices as being equal when it comes to comparing directories;
5902 this is fairly gross, but there does not seem to be a better way to go.
5904 Apart from using NFS, there are a number of cases where relying on
5905 device numbers can cause spurious redumping of unmodified files. For
5906 example, this occurs when archiving LVM snapshot volumes. To avoid
5907 this, use '--no-check-device' option:
5910 Do not rely on device numbers when preparing a list of changed
5911 files for an incremental dump.
5914 Use device numbers when preparing a list of changed files for an
5915 incremental dump. This is the default behavior. The purpose of
5916 this option is to undo the effect of the '--no-check-device' if it
5917 was given in 'TAR_OPTIONS' environment variable (*note
5920 There is also another way to cope with changing device numbers. It
5921 is described in detail in *note Fixing Snapshot Files::.
5923 Note that incremental archives use 'tar' extensions and may not be
5924 readable by non-GNU versions of the 'tar' program.
5926 To extract from the incremental dumps, use '--listed-incremental'
5927 together with '--extract' option (*note extracting files::). In this
5928 case, 'tar' does not need to access snapshot file, since all the data
5929 necessary for extraction are stored in the archive itself. So, when
5930 extracting, you can give whatever argument to '--listed-incremental',
5931 the usual practice is to use '--listed-incremental=/dev/null'.
5932 Alternatively, you can use '--incremental', which needs no arguments.
5933 In general, '--incremental' ('-G') can be used as a shortcut for
5934 '--listed-incremental' when listing or extracting incremental backups
5935 (for more information regarding this option, *note incremental-op::).
5937 When extracting from the incremental backup GNU 'tar' attempts to
5938 restore the exact state the file system had when the archive was
5939 created. In particular, it will _delete_ those files in the file system
5940 that did not exist in their directories when the archive was created.
5941 If you have created several levels of incremental files, then in order
5942 to restore the exact contents the file system had when the last level
5943 was created, you will need to restore from all backups in turn.
5944 Continuing our example, to restore the state of '/usr' file system, one
5948 --listed-incremental=/dev/null \
5949 --file archive.1.tar
5951 --listed-incremental=/dev/null \
5952 --file archive.2.tar
5954 To list the contents of an incremental archive, use '--list' (*note
5955 list::), as usual. To obtain more information about the archive, use
5956 '--listed-incremental' or '--incremental' combined with two '--verbose'
5959 tar --list --incremental --verbose --verbose --file archive.tar
5961 This command will print, for each directory in the archive, the list
5962 of files in that directory at the time the archive was created. This
5963 information is put out in a format which is both human-readable and
5964 unambiguous for a program: each file name is printed as
5968 where X is a letter describing the status of the file: 'Y' if the file
5969 is present in the archive, 'N' if the file is not included in the
5970 archive, or a 'D' if the file is a directory (and is included in the
5971 archive). *Note Dumpdir::, for the detailed description of dumpdirs and
5972 status codes. Each such line is terminated by a newline character. The
5973 last line is followed by an additional newline to indicate the end of
5976 The option '--incremental' ('-G') gives the same behavior as
5977 '--listed-incremental' when used with '--list' and '--extract' options.
5978 When used with '--create' option, it creates an incremental archive
5979 without creating snapshot file. Thus, it is impossible to create
5980 several levels of incremental backups with '--incremental' option.
5982 ---------- Footnotes ----------
5984 (1) Notice, that since both archives were created without '-P' option
5985 (*note absolute::), these commands should be run from the root file
5988 (2) Two '--verbose' options were selected to avoid breaking usual
5989 verbose listing output ('--list --verbose') when using in scripts.
5991 Versions of GNU 'tar' up to 1.15.1 used to dump verbatim binary
5992 contents of the DUMPDIR header (with terminating nulls) when
5993 '--incremental' or '--listed-incremental' option was given, no matter
5994 what the verbosity level. This behavior, and, especially, the binary
5995 output it produced were considered inconvenient and were changed in
5999 File: tar.info, Node: Backup Levels, Next: Backup Parameters, Prev: Incremental Dumps, Up: Backups
6001 5.3 Levels of Backups
6002 =====================
6004 An archive containing all the files in the file system is called a "full
6005 backup" or "full dump". You could insure your data by creating a full
6006 dump every day. This strategy, however, would waste a substantial
6007 amount of archive media and user time, as unchanged files are daily
6010 It is more efficient to do a full dump only occasionally. To back up
6011 files between full dumps, you can use "incremental dumps". A "level
6012 one" dump archives all the files that have changed since the last full
6015 A typical dump strategy would be to perform a full dump once a week,
6016 and a level one dump once a day. This means some versions of files will
6017 in fact be archived more than once, but this dump strategy makes it
6018 possible to restore a file system to within one day of accuracy by only
6019 extracting two archives--the last weekly (full) dump and the last daily
6020 (level one) dump. The only information lost would be in files changed
6021 or created since the last daily backup. (Doing dumps more than once a
6022 day is usually not worth the trouble.)
6024 GNU 'tar' comes with scripts you can use to do full and level-one
6025 (actually, even level-two and so on) dumps. Using scripts (shell
6026 programs) to perform backups and restoration is a convenient and
6027 reliable alternative to typing out file name lists and 'tar' commands by
6030 Before you use these scripts, you need to edit the file
6031 'backup-specs', which specifies parameters used by the backup scripts
6032 and by the restore script. This file is usually located in
6033 '/etc/backup' directory. *Note Backup Parameters::, for its detailed
6034 description. Once the backup parameters are set, you can perform
6035 backups or restoration by running the appropriate script.
6037 The name of the backup script is 'backup'. The name of the restore
6038 script is 'restore'. The following sections describe their use in
6041 _Please Note:_ The backup and restoration scripts are designed to be
6042 used together. While it is possible to restore files by hand from an
6043 archive which was created using a backup script, and to create an
6044 archive by hand which could then be extracted using the restore script,
6045 it is easier to use the scripts. *Note Incremental Dumps::, before
6046 making such an attempt.
6049 File: tar.info, Node: Backup Parameters, Next: Scripted Backups, Prev: Backup Levels, Up: Backups
6051 5.4 Setting Parameters for Backups and Restoration
6052 ==================================================
6054 The file 'backup-specs' specifies backup parameters for the backup and
6055 restoration scripts provided with 'tar'. You must edit 'backup-specs'
6056 to fit your system configuration and schedule before using these
6059 Syntactically, 'backup-specs' is a shell script, containing mainly
6060 variable assignments. However, any valid shell construct is allowed in
6061 this file. Particularly, you may wish to define functions within that
6062 script (e.g., see 'RESTORE_BEGIN' below). For more information about
6063 shell script syntax, please refer to the definition of the Shell Command
6065 (http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
6066 g_02). See also *note Bash Features: (bashref)Top.
6068 The shell variables controlling behavior of 'backup' and 'restore'
6069 are described in the following subsections.
6073 * General-Purpose Variables::
6074 * Magnetic Tape Control::
6076 * backup-specs example:: An Example Text of 'Backup-specs'
6079 File: tar.info, Node: General-Purpose Variables, Next: Magnetic Tape Control, Up: Backup Parameters
6081 5.4.1 General-Purpose Variables
6082 -------------------------------
6084 -- Backup variable: ADMINISTRATOR
6085 The user name of the backup administrator. 'Backup' scripts sends
6086 a backup report to this address.
6088 -- Backup variable: BACKUP_HOUR
6089 The hour at which the backups are done. This can be a number from
6090 0 to 23, or the time specification in form HOURS:MINUTES, or the
6093 This variable is used by 'backup'. Its value may be overridden
6094 using '--time' option (*note Scripted Backups::).
6096 -- Backup variable: TAPE_FILE
6098 The device 'tar' writes the archive to. If TAPE_FILE is a remote
6099 archive (*note remote-dev::), backup script will suppose that your
6100 'mt' is able to access remote devices. If RSH (*note RSH::) is
6101 set, '--rsh-command' option will be added to invocations of 'mt'.
6103 -- Backup variable: BLOCKING
6105 The blocking factor 'tar' will use when writing the dump archive.
6106 *Note Blocking Factor::.
6108 -- Backup variable: BACKUP_DIRS
6110 A list of file systems to be dumped (for 'backup'), or restored
6111 (for 'restore'). You can include any directory name in the list --
6112 subdirectories on that file system will be included, regardless of
6113 how they may look to other networked machines. Subdirectories on
6114 other file systems will be ignored.
6116 The host name specifies which host to run 'tar' on, and should
6117 normally be the host that actually contains the file system.
6118 However, the host machine must have GNU 'tar' installed, and must
6119 be able to access the directory containing the backup scripts and
6120 their support files using the same file name that is used on the
6121 machine where the scripts are run (i.e., what 'pwd' will print when
6122 in that directory on that machine). If the host that contains the
6123 file system does not have this capability, you can specify another
6124 host as long as it can access the file system through NFS.
6126 If the list of file systems is very long you may wish to put it in
6127 a separate file. This file is usually named '/etc/backup/dirs',
6128 but this name may be overridden in 'backup-specs' using 'DIRLIST'
6131 -- Backup variable: DIRLIST
6133 The name of the file that contains a list of file systems to backup
6134 or restore. By default it is '/etc/backup/dirs'.
6136 -- Backup variable: BACKUP_FILES
6138 A list of individual files to be dumped (for 'backup'), or restored
6139 (for 'restore'). These should be accessible from the machine on
6140 which the backup script is run.
6142 If the list of individual files is very long you may wish to store
6143 it in a separate file. This file is usually named
6144 '/etc/backup/files', but this name may be overridden in
6145 'backup-specs' using 'FILELIST' variable.
6147 -- Backup variable: FILELIST
6149 The name of the file that contains a list of individual files to
6150 backup or restore. By default it is '/etc/backup/files'.
6152 -- Backup variable: MT
6154 Full file name of 'mt' binary.
6156 -- Backup variable: RSH
6157 Full file name of 'rsh' binary or its equivalent. You may wish to
6158 set it to 'ssh', to improve security. In this case you will have
6159 to use public key authentication.
6161 -- Backup variable: RSH_COMMAND
6163 Full file name of 'rsh' binary on remote machines. This will be
6164 passed via '--rsh-command' option to the remote invocation of GNU
6167 -- Backup variable: VOLNO_FILE
6169 Name of temporary file to hold volume numbers. This needs to be
6170 accessible by all the machines which have file systems to be
6173 -- Backup variable: XLIST
6175 Name of "exclude file list". An "exclude file list" is a file
6176 located on the remote machine and containing the list of files to
6177 be excluded from the backup. Exclude file lists are searched in
6178 /etc/tar-backup directory. A common use for exclude file lists is
6179 to exclude files containing security-sensitive information (e.g.,
6180 '/etc/shadow' from backups).
6182 This variable affects only 'backup'.
6184 -- Backup variable: SLEEP_TIME
6186 Time to sleep between dumps of any two successive file systems
6188 This variable affects only 'backup'.
6190 -- Backup variable: DUMP_REMIND_SCRIPT
6192 Script to be run when it's time to insert a new tape in for the
6193 next volume. Administrators may want to tailor this script for
6194 their site. If this variable isn't set, GNU 'tar' will display its
6195 built-in prompt, and will expect confirmation from the console.
6196 For the description of the default prompt, see *note change volume
6199 -- Backup variable: SLEEP_MESSAGE
6201 Message to display on the terminal while waiting for dump time.
6202 Usually this will just be some literal text.
6204 -- Backup variable: TAR
6206 Full file name of the GNU 'tar' executable. If this is not set,
6207 backup scripts will search 'tar' in the current shell path.
6210 File: tar.info, Node: Magnetic Tape Control, Next: User Hooks, Prev: General-Purpose Variables, Up: Backup Parameters
6212 5.4.2 Magnetic Tape Control
6213 ---------------------------
6215 Backup scripts access tape device using special "hook functions". These
6216 functions take a single argument -- the name of the tape device. Their
6217 names are kept in the following variables:
6219 -- Backup variable: MT_BEGIN
6220 The name of "begin" function. This function is called before
6221 accessing the drive. By default it retensions the tape:
6226 mt -f "$1" retension
6229 -- Backup variable: MT_REWIND
6230 The name of "rewind" function. The default definition is as
6239 -- Backup variable: MT_OFFLINE
6240 The name of the function switching the tape off line. By default
6241 it is defined as follows:
6243 MT_OFFLINE=mt_offline
6249 -- Backup variable: MT_STATUS
6250 The name of the function used to obtain the status of the archive
6251 device, including error count. Default definition:
6260 File: tar.info, Node: User Hooks, Next: backup-specs example, Prev: Magnetic Tape Control, Up: Backup Parameters
6265 "User hooks" are shell functions executed before and after each 'tar'
6266 invocation. Thus, there are "backup hooks", which are executed before
6267 and after dumping each file system, and "restore hooks", executed before
6268 and after restoring a file system. Each user hook is a shell function
6269 taking four arguments:
6271 -- User Hook Function: hook LEVEL HOST FS FSNAME
6275 Current backup or restore level.
6278 Name or IP address of the host machine being dumped or
6282 Full file name of the file system being dumped or restored.
6285 File system name with directory separators replaced with
6286 colons. This is useful, e.g., for creating unique files.
6288 Following variables keep the names of user hook functions:
6290 -- Backup variable: DUMP_BEGIN
6291 Dump begin function. It is executed before dumping the file
6294 -- Backup variable: DUMP_END
6295 Executed after dumping the file system.
6297 -- Backup variable: RESTORE_BEGIN
6298 Executed before restoring the file system.
6300 -- Backup variable: RESTORE_END
6301 Executed after restoring the file system.
6304 File: tar.info, Node: backup-specs example, Prev: User Hooks, Up: Backup Parameters
6306 5.4.4 An Example Text of 'Backup-specs'
6307 ---------------------------------------
6309 The following is an example of 'backup-specs':
6311 # site-specific parameters for file system backup.
6313 ADMINISTRATOR=friedman
6315 TAPE_FILE=/dev/nrsmt0
6317 # Use ssh instead of the less secure rsh
6319 RSH_COMMAND=/usr/bin/ssh
6321 # Override MT_STATUS function:
6327 # Disable MT_OFFLINE function
6344 apple-gunkies:/com/mailer/gnu
6345 apple-gunkies:/com/archive/gnu"
6347 BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
6351 File: tar.info, Node: Scripted Backups, Next: Scripted Restoration, Prev: Backup Parameters, Up: Backups
6353 5.5 Using the Backup Scripts
6354 ============================
6356 The syntax for running a backup script is:
6358 backup --level=LEVEL --time=TIME
6360 The '--level' option requests the dump level. Thus, to produce a
6361 full dump, specify '--level=0' (this is the default, so '--level' may be
6362 omitted if its value is '0')(1).
6364 The '--time' option determines when should the backup be run. TIME
6365 may take three forms:
6369 The dump must be run at HH hours MM minutes.
6373 The dump must be run at HH hours.
6377 The dump must be run immediately.
6379 You should start a script with a tape or disk mounted. Once you
6380 start a script, it prompts you for new tapes or disks as it needs them.
6381 Media volumes don't have to correspond to archive files -- a
6382 multi-volume archive can be started in the middle of a tape that already
6383 contains the end of another multi-volume archive. The 'restore' script
6384 prompts for media by its archive volume, so to avoid an error message
6385 you should keep track of which tape (or disk) contains which volume of
6386 the archive (*note Scripted Restoration::).
6388 The backup scripts write two files on the file system. The first is
6389 a record file in '/etc/tar-backup/', which is used by the scripts to
6390 store and retrieve information about which files were dumped. This file
6391 is not meant to be read by humans, and should not be deleted by them.
6392 *Note Snapshot Files::, for a more detailed explanation of this file.
6394 The second file is a log file containing the names of the file
6395 systems and files dumped, what time the backup was made, and any error
6396 messages that were generated, as well as how much space was left in the
6397 media volume after the last volume of the archive was written. You
6398 should check this log file after every backup. The file name is
6399 'log-MM-DD-YYYY-level-N', where MM-DD-YYYY represents current date, and
6400 N represents current dump level number.
6402 The script also prints the name of each system being dumped to the
6405 Following is the full list of options accepted by 'backup' script:
6409 Do backup level LEVEL (default 0).
6413 Force backup even if today's log file already exists.
6417 Set verbosity level. The higher the level is, the more debugging
6418 information will be output during execution. Default LEVEL is 100,
6419 which means the highest debugging level.
6423 Wait till TIME, then do backup.
6427 Display short help message and exit.
6431 Display information about the program's name, version, origin and
6432 legal status, all on standard output, and then exit successfully.
6434 ---------- Footnotes ----------
6436 (1) For backward compatibility, the 'backup' will also try to deduce
6437 the requested dump level from the name of the script itself. If the
6438 name consists of a string 'level-' followed by a single decimal digit,
6439 that digit is taken as the dump level number. Thus, you may create a
6440 link from 'backup' to 'level-1' and then run 'level-1' whenever you need
6441 to create a level one dump.
6444 File: tar.info, Node: Scripted Restoration, Prev: Scripted Backups, Up: Backups
6446 5.6 Using the Restore Script
6447 ============================
6449 To restore files that were archived using a scripted backup, use the
6450 'restore' script. Its usage is quite straightforward. In the simplest
6451 form, invoke 'restore --all', it will then restore all the file systems
6452 and files specified in 'backup-specs' (*note BACKUP_DIRS:
6453 General-Purpose Variables.).
6455 You may select the file systems (and/or files) to restore by giving
6456 'restore' a list of "patterns" in its command line. For example,
6461 will restore all file systems on the machine 'albert'. A more
6462 complicated example:
6464 restore 'albert:*' '*:/var'
6466 This command will restore all file systems on the machine 'albert' as
6467 well as '/var' file system on all machines.
6469 By default 'restore' will start restoring files from the lowest
6470 available dump level (usually zero) and will continue through all
6471 available dump levels. There may be situations where such a thorough
6472 restore is not necessary. For example, you may wish to restore only
6473 files from the recent level one backup. To do so, use '--level' option,
6474 as shown in the example below:
6478 The full list of options accepted by 'restore' follows:
6482 Restore all file systems and files specified in 'backup-specs'.
6486 Start restoring from the given backup level, instead of the default
6491 Set verbosity level. The higher the level is, the more debugging
6492 information will be output during execution. Default LEVEL is 100,
6493 which means the highest debugging level.
6497 Display short help message and exit.
6501 Display information about the program's name, version, origin and
6502 legal status, all on standard output, and then exit successfully.
6504 You should start the restore script with the media containing the
6505 first volume of the archive mounted. The script will prompt for other
6506 volumes as they are needed. If the archive is on tape, you don't need
6507 to rewind the tape to to its beginning--if the tape head is positioned
6508 past the beginning of the archive, the script will rewind the tape as
6509 needed. *Note Tape Positioning::, for a discussion of tape positioning.
6511 *Warning:* The script will delete files from the active file system
6512 if they were not in the file system when the archive was made.
6514 *Note Incremental Dumps::, for an explanation of how the script makes
6518 File: tar.info, Node: Choosing, Next: Date input formats, Prev: Backups, Up: Top
6520 6 Choosing Files and Names for 'tar'
6521 ************************************
6523 Certain options to 'tar' enable you to specify a name for your archive.
6524 Other options let you decide which files to include or exclude from the
6525 archive, based on when or whether files were modified, whether the file
6526 names do or don't match specified patterns, or whether files are in
6527 specified directories.
6529 This chapter discusses these options in detail.
6533 * file:: Choosing the Archive's Name
6534 * Selecting Archive Members::
6535 * files:: Reading Names from a File
6536 * exclude:: Excluding Some Files
6537 * wildcards:: Wildcards Patterns and Matching
6538 * quoting styles:: Ways of Quoting Special Characters in Names
6539 * transform:: Modifying File and Member Names
6540 * after:: Operating Only on New Files
6541 * recurse:: Descending into Directories
6542 * one:: Crossing File System Boundaries
6545 File: tar.info, Node: file, Next: Selecting Archive Members, Up: Choosing
6547 6.1 Choosing and Naming Archive Files
6548 =====================================
6550 By default, 'tar' uses an archive file name that was compiled when it
6551 was built on the system; usually this name refers to some physical tape
6552 drive on the machine. However, the person who installed 'tar' on the
6553 system may not have set the default to a meaningful value as far as most
6554 users are concerned. As a result, you will usually want to tell 'tar'
6555 where to find (or create) the archive. The '--file=ARCHIVE-NAME' ('-f
6556 ARCHIVE-NAME') option allows you to either specify or name a file to use
6557 as the archive instead of the default archive file location.
6559 '--file=ARCHIVE-NAME'
6561 Name the archive to create or operate on. Use in conjunction with
6564 For example, in this 'tar' command,
6566 $ tar -cvf collection.tar blues folk jazz
6568 'collection.tar' is the name of the archive. It must directly follow
6569 the '-f' option, since whatever directly follows '-f' _will_ end up
6570 naming the archive. If you neglect to specify an archive name, you may
6571 end up overwriting a file in the working directory with the archive you
6572 create since 'tar' will use this file's name for the archive name.
6574 An archive can be saved as a file in the file system, sent through a
6575 pipe or over a network, or written to an I/O device such as a tape,
6576 floppy disk, or CD write drive.
6578 If you do not name the archive, 'tar' uses the value of the
6579 environment variable 'TAPE' as the file name for the archive. If that
6580 is not available, 'tar' uses a default, compiled-in archive name,
6581 usually that for tape unit zero (i.e., '/dev/tu00').
6583 If you use '-' as an ARCHIVE-NAME, 'tar' reads the archive from
6584 standard input (when listing or extracting files), or writes it to
6585 standard output (when creating an archive). If you use '-' as an
6586 ARCHIVE-NAME when modifying an archive, 'tar' reads the original archive
6587 from its standard input and writes the entire new archive to its
6590 The following example is a convenient way of copying directory
6591 hierarchy from 'sourcedir' to 'targetdir'.
6593 $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)
6595 The '-C' option allows to avoid using subshells:
6597 $ tar -C sourcedir -cf - . | tar -C targetdir -xpf -
6599 In both examples above, the leftmost 'tar' invocation archives the
6600 contents of 'sourcedir' to the standard output, while the rightmost one
6601 reads this archive from its standard input and extracts it. The '-p'
6602 option tells it to restore permissions of the extracted files.
6604 To specify an archive file on a device attached to a remote machine,
6607 --file=HOSTNAME:/DEV/FILE-NAME
6609 'tar' will set up the remote connection, if possible, and prompt you for
6610 a username and password. If you use '--file=@HOSTNAME:/DEV/FILE-NAME',
6611 'tar' will attempt to set up the remote connection using your username
6612 as the username on the remote machine.
6614 If the archive file name includes a colon (':'), then it is assumed
6615 to be a file on another machine. If the archive file is
6616 'USER@HOST:FILE', then FILE is used on the host HOST. The remote host
6617 is accessed using the 'rsh' program, with a username of USER. If the
6618 username is omitted (along with the '@' sign), then your user name will
6619 be used. (This is the normal 'rsh' behavior.) It is necessary for the
6620 remote machine, in addition to permitting your 'rsh' access, to have the
6621 'rmt' program installed (this command is included in the GNU 'tar'
6622 distribution and by default is installed under 'PREFIX/libexec/rmt',
6623 where PREFIX means your installation prefix). If you need to use a file
6624 whose name includes a colon, then the remote tape drive behavior can be
6625 inhibited by using the '--force-local' option.
6627 When the archive is being created to '/dev/null', GNU 'tar' tries to
6628 minimize input and output operations. The Amanda backup system, when
6629 used with GNU 'tar', has an initial sizing pass which uses this feature.
6632 File: tar.info, Node: Selecting Archive Members, Next: files, Prev: file, Up: Choosing
6634 6.2 Selecting Archive Members
6635 =============================
6637 "File Name arguments" specify which files in the file system 'tar'
6638 operates on, when creating or adding to an archive, or which archive
6639 members 'tar' operates on, when reading or deleting from an archive.
6642 To specify file names, you can include them as the last arguments on
6643 the command line, as follows:
6644 tar OPERATION [OPTION1 OPTION2 ...] [FILE NAME-1 FILE NAME-2 ...]
6646 If a file name begins with dash ('-'), precede it with '--add-file'
6647 option to prevent it from being treated as an option.
6649 By default GNU 'tar' attempts to "unquote" each file or member name,
6650 replacing "escape sequences" according to the following table:
6652 Escape Replaced with
6653 -----------------------------------------------------------
6654 \a Audible bell (ASCII 7)
6655 \b Backspace (ASCII 8)
6656 \f Form feed (ASCII 12)
6657 \n New line (ASCII 10)
6658 \r Carriage return (ASCII 13)
6659 \t Horizontal tabulation (ASCII 9)
6660 \v Vertical tabulation (ASCII 11)
6662 \N ASCII N (N should be an octal number of
6665 A backslash followed by any other symbol is retained.
6667 This default behavior is controlled by the following command line
6671 Enable unquoting input file or member names (default).
6674 Disable unquoting input file or member names.
6676 If you specify a directory name as a file name argument, all the
6677 files in that directory are operated on by 'tar'.
6679 If you do not specify files, 'tar' behavior differs depending on the
6680 operation mode as described below:
6682 When 'tar' is invoked with '--create' ('-c'), 'tar' will stop
6683 immediately, reporting the following:
6686 tar: Cowardly refusing to create an empty archive
6687 Try 'tar --help' or 'tar --usage' for more information.
6689 If you specify either '--list' ('-t') or '--extract' ('--get', '-x'),
6690 'tar' operates on all the archive members in the archive.
6692 If run with '--diff' option, tar will compare the archive with the
6693 contents of the current working directory.
6695 If you specify any other operation, 'tar' does nothing.
6697 By default, 'tar' takes file names from the command line. However,
6698 there are other ways to specify file or member names, or to modify the
6699 manner in which 'tar' selects the files or members upon which to
6700 operate. In general, these methods work both for specifying the names
6701 of files and archive members.
6704 File: tar.info, Node: files, Next: exclude, Prev: Selecting Archive Members, Up: Choosing
6706 6.3 Reading Names from a File
6707 =============================
6709 Instead of giving the names of files or archive members on the command
6710 line, you can put the names into a file, and then use the
6711 '--files-from=FILE-OF-NAMES' ('-T FILE-OF-NAMES') option to 'tar'. Give
6712 the name of the file which contains the list of files to include as the
6713 argument to '--files-from'. In the list, the file names should be
6714 separated by newlines. You will frequently use this option when you
6715 have generated the list of files to archive with the 'find' utility.
6717 '--files-from=FILE-NAME'
6719 Get names to extract or create from file FILE-NAME.
6721 If you give a single dash as a file name for '--files-from', (i.e.,
6722 you specify either '--files-from=-' or '-T -'), then the file names are
6723 read from standard input.
6725 Unless you are running 'tar' with '--create', you cannot use both
6726 '--files-from=-' and '--file=-' ('-f -') in the same command.
6728 Any number of '-T' options can be given in the command line.
6730 The following example shows how to use 'find' to generate a list of
6731 files smaller than 400K in length and put that list into a file called
6732 'small-files'. You can then use the '-T' option to 'tar' to specify the
6733 files from that file, 'small-files', to create the archive 'little.tgz'.
6734 (The '-z' option to 'tar' compresses the archive with 'gzip'; *note
6735 gzip:: for more information.)
6737 $ find . -size -400 -print > small-files
6738 $ tar -c -v -z -T small-files -f little.tgz
6740 By default, each line read from the file list is first stripped off any
6741 leading and trailing whitespace. If the resulting string begins with
6742 '-' character, it is considered a 'tar' option and is processed
6743 accordingly(1). For example, the common use of this feature is to
6744 change to another directory by specifying '-C' option:
6752 $ tar -c -f foo.tar --files-from list
6754 In this example, 'tar' will first switch to '/etc' directory and add
6755 files 'passwd' and 'hosts' to the archive. Then it will change to
6756 '/lib' directory and will archive the file 'libc.a'. Thus, the
6757 resulting archive 'foo.tar' will contain:
6764 Note, that any options used in the file list remain in effect for the
6765 rest of the command line. For example, using the same 'list' file as
6766 above, the following command
6768 $ tar -c -f foo.tar --files-from list libcurses.a
6770 will look for file 'libcurses.a' in the directory '/lib', because it was
6771 used with the last '-C' option (*note Position-Sensitive Options::).
6773 If such option handling is undesirable, use the
6774 '--verbatim-files-from' option. When this option is in effect, each
6775 line read from the file list is treated as a file name. Notice, that
6776 this means, in particular, that no whitespace trimming is performed.
6778 The '--verbatim-files-from' affects all '-T' options that follow it
6779 in the command line. The default behavior can be restored using
6780 '--no-verbatim-files-from' option.
6782 To disable option handling for a single file name, use the
6783 '--add-file' option, e.g.: '--add-file=--my-file'.
6785 You can use any GNU 'tar' command line options in the file list file,
6786 including '--files-from' option itself. This allows for including
6787 contents of a file list into another file list file. Note however, that
6788 options that control file list processing, such as
6789 '--verbatim-files-from' or '--null' won't affect the file they appear
6790 in. They will affect next '--files-from' option, if there is any.
6796 ---------- Footnotes ----------
6798 (1) Versions of GNU 'tar' up to 1.15.1 recognized only '-C' option in
6799 file lists, and only if the option and its argument occupied two
6803 File: tar.info, Node: nul, Up: files
6805 6.3.1 'NUL'-Terminated File Names
6806 ---------------------------------
6808 The '--null' option causes '--files-from=FILE-OF-NAMES' ('-T
6809 FILE-OF-NAMES') to read file names terminated by a 'NUL' instead of a
6810 newline, so files whose names contain newlines can be archived using
6814 Only consider 'NUL'-terminated file names, instead of files that
6815 terminate in a newline.
6818 Undo the effect of any previous '--null' option.
6820 The '--null' option is just like the one in GNU 'xargs' and 'cpio',
6821 and is useful with the '-print0' predicate of GNU 'find'. In 'tar',
6822 '--null' also disables special handling for file names that begin with
6823 dash (similar to '--verbatim-files-from' option).
6825 This example shows how to use 'find' to generate a list of files
6826 larger than 800K in length and put that list into a file called
6827 'long-files'. The '-print0' option to 'find' is just like '-print',
6828 except that it separates files with a 'NUL' rather than with a newline.
6829 You can then run 'tar' with both the '--null' and '-T' options to
6830 specify that 'tar' gets the files from that file, 'long-files', to
6831 create the archive 'big.tgz'. The '--null' option to 'tar' will cause
6832 'tar' to recognize the 'NUL' separator between files.
6834 $ find . -size +800 -print0 > long-files
6835 $ tar -c -v --null --files-from=long-files --file=big.tar
6837 The '--no-null' option can be used if you need to read both
6838 'NUL'-terminated and newline-terminated files on the same command line.
6839 For example, if 'flist' is a newline-terminated file, then the following
6840 command can be used to combine it with the above command:
6842 $ find . -size +800 -print0 |
6843 tar -c -f big.tar --null -T - --no-null -T flist
6845 This example uses short options for typographic reasons, to avoid
6848 GNU 'tar' is tries to automatically detect 'NUL'-terminated file
6849 lists, so in many cases it is safe to use them even without the '--null'
6850 option. In this case 'tar' will print a warning and continue reading
6851 such a file as if '--null' were actually given:
6853 $ find . -size +800 -print0 | tar -c -f big.tar -T -
6854 tar: -: file name read contains nul character
6856 The null terminator, however, remains in effect only for this
6857 particular file, any following '-T' options will assume newline
6858 termination. Of course, the null autodetection applies to these
6859 eventual surplus '-T' options as well.
6862 File: tar.info, Node: exclude, Next: wildcards, Prev: files, Up: Choosing
6864 6.4 Excluding Some Files
6865 ========================
6867 To avoid operating on files whose names match a particular pattern, use
6868 the '--exclude' or '--exclude-from' options.
6871 Causes 'tar' to ignore files that match the PATTERN.
6873 The '--exclude=PATTERN' option prevents any file or member whose name
6874 matches the shell wildcard (PATTERN) from being operated on. For
6875 example, to create an archive with all the contents of the directory
6876 'src' except for files whose names end in '.o', use the command 'tar -cf
6877 src.tar --exclude='*.o' src'.
6879 You may give multiple '--exclude' options.
6881 '--exclude-from=FILE'
6883 Causes 'tar' to ignore files that match the patterns listed in
6886 Use the '--exclude-from' option to read a list of patterns, one per
6887 line, from FILE; 'tar' will ignore files matching those patterns. Thus
6888 if 'tar' is called as 'tar -c -X foo .' and the file 'foo' contains a
6889 single line '*.o', no files whose names end in '.o' will be added to the
6892 Notice, that lines from FILE are read verbatim. One of the frequent
6893 errors is leaving some extra whitespace after a file name, which is
6894 difficult to catch using text editors.
6896 However, empty lines are OK.
6898 When archiving directories that are under some version control system
6899 (VCS), it is often convenient to read exclusion patterns from this VCS'
6900 ignore files (e.g. '.cvsignore', '.gitignore', etc.) The following
6901 options provide such possibility:
6903 '--exclude-vcs-ignores'
6904 Before archiving a directory, see if it contains any of the
6905 following files: 'cvsignore', '.gitignore', '.bzrignore', or
6906 '.hgignore'. If so, read ignore patterns from these files.
6908 The patterns are treated much as the corresponding VCS would treat
6912 Contains shell-style globbing patterns that apply only to the
6913 directory where this file resides. No comments are allowed in
6914 the file. Empty lines are ignored.
6917 Contains shell-style globbing patterns. Applies to the
6918 directory where '.gitfile' is located and all its
6921 Any line beginning with a '#' is a comment. Backslash escapes
6922 the comment character.
6925 Contains shell globbing-patterns and regular expressions (if
6926 prefixed with 'RE:'(1). Patterns affect the directory and all
6929 Any line beginning with a '#' is a comment.
6932 Contains posix regular expressions(2). The line 'syntax:
6933 glob' switches to shell globbing patterns. The line 'syntax:
6934 regexp' switches back. Comments begin with a '#'. Patterns
6935 affect the directory and all its subdirectories.
6937 '--exclude-ignore=FILE'
6938 Before dumping a directory, 'tar' checks if it contains FILE. If
6939 so, exclusion patterns are read from this file. The patterns
6940 affect only the directory itself.
6942 '--exclude-ignore-recursive=FILE'
6943 Same as '--exclude-ignore', except that the patterns read affect
6944 both the directory where FILE resides and all its subdirectories.
6947 Exclude files and directories used by following version control
6948 systems: 'CVS', 'RCS', 'SCCS', 'SVN', 'Arch', 'Bazaar',
6949 'Mercurial', and 'Darcs'.
6951 As of version 1.29, the following files are excluded:
6953 * 'CVS/', and everything under it
6954 * 'RCS/', and everything under it
6955 * 'SCCS/', and everything under it
6956 * '.git/', and everything under it
6961 * '.svn/', and everything under it
6962 * '.arch-ids/', and everything under it
6963 * '{arch}/', and everything under it
6976 Exclude backup and lock files. This option causes exclusion of
6977 files that match the following shell globbing patterns:
6983 When creating an archive, the '--exclude-caches' option family causes
6984 'tar' to exclude all directories that contain a "cache directory tag".
6985 A cache directory tag is a short file with the well-known name
6986 'CACHEDIR.TAG' and having a standard header specified in
6987 <http://www.brynosaurus.com/cachedir/spec.html>. Various applications
6988 write cache directory tags into directories they use to hold
6989 regenerable, non-precious data, so that such data can be more easily
6990 excluded from backups.
6992 There are three 'exclude-caches' options, each providing a different
6993 exclusion semantics:
6996 Do not archive the contents of the directory, but archive the
6997 directory itself and the 'CACHEDIR.TAG' file.
6999 '--exclude-caches-under'
7000 Do not archive the contents of the directory, nor the
7001 'CACHEDIR.TAG' file, archive only the directory itself.
7003 '--exclude-caches-all'
7004 Omit directories containing 'CACHEDIR.TAG' file entirely.
7006 Another option family, '--exclude-tag', provides a generalization of
7007 this concept. It takes a single argument, a file name to look for. Any
7008 directory that contains this file will be excluded from the dump.
7009 Similarly to 'exclude-caches', there are three options in this option
7012 '--exclude-tag=FILE'
7013 Do not dump the contents of the directory, but dump the directory
7014 itself and the FILE.
7016 '--exclude-tag-under=FILE'
7017 Do not dump the contents of the directory, nor the FILE, archive
7018 only the directory itself.
7020 '--exclude-tag-all=FILE'
7021 Omit directories containing FILE file entirely.
7023 Multiple '--exclude-tag*' options can be given.
7025 For example, given this directory:
7036 The '--exclude-tag' will produce the following:
7038 $ tar -cf archive.tar --exclude-tag=tagfile -v dir
7043 tar: dir/folk/: contains a cache directory tag tagfile;
7047 Both the 'dir/folk' directory and its tagfile are preserved in the
7048 archive, however the rest of files in this directory are not.
7050 Now, using the '--exclude-tag-under' option will exclude 'tagfile'
7051 from the dump, while still preserving the directory itself, as shown in
7054 $ tar -cf archive.tar --exclude-tag-under=tagfile -v dir
7059 ./tar: dir/folk/: contains a cache directory tag tagfile;
7062 Finally, using '--exclude-tag-all' omits the 'dir/folk' directory
7065 $ tar -cf archive.tar --exclude-tag-all=tagfile -v dir
7069 ./tar: dir/folk/: contains a cache directory tag tagfile;
7070 directory not dumped
7074 * problems with exclude::
7076 ---------- Footnotes ----------
7078 (1) According to the Bazaar docs, globbing-patterns are Korn-shell
7079 style and regular expressions are perl-style. As of GNU 'tar' version
7080 1.29, these are treated as shell-style globs and posix extended regexps.
7081 This will be fixed in future releases.
7083 (2) Support for perl-style regexps will appear in future releases.
7086 File: tar.info, Node: problems with exclude, Up: exclude
7088 Problems with Using the 'exclude' Options
7089 -----------------------------------------
7091 Some users find 'exclude' options confusing. Here are some common
7094 * The main operating mode of 'tar' does not act on a file name
7095 explicitly listed on the command line, if one of its file name
7096 components is excluded. In the example above, if you create an
7097 archive and exclude files that end with '*.o', but explicitly name
7098 the file 'dir.o/foo' after all the options have been listed,
7099 'dir.o/foo' will be excluded from the archive.
7101 * You can sometimes confuse the meanings of '--exclude' and
7102 '--exclude-from'. Be careful: use '--exclude' when files to be
7103 excluded are given as a pattern on the command line. Use
7104 '--exclude-from' to introduce the name of a file which contains a
7105 list of patterns, one per line; each of these patterns can exclude
7106 zero, one, or many files.
7108 * When you use '--exclude=PATTERN', be sure to quote the PATTERN
7109 parameter, so GNU 'tar' sees wildcard characters like '*'. If you
7110 do not do this, the shell might expand the '*' itself using files
7111 at hand, so 'tar' might receive a list of files instead of one
7112 pattern, or none at all, making the command somewhat illegal. This
7113 might not correspond to what you want.
7117 $ tar -c -f ARCHIVE.TAR --exclude '*.o' DIRECTORY
7122 $ tar -c -f ARCHIVE.TAR --exclude *.o DIRECTORY
7124 * You must use use shell syntax, or globbing, rather than 'regexp'
7125 syntax, when using exclude options in 'tar'. If you try to use
7126 'regexp' syntax to describe files to be excluded, your command
7130 In earlier versions of 'tar', what is now the '--exclude-from'
7131 option was called '--exclude' instead. Now, '--exclude' applies to
7132 patterns listed on the command line and '--exclude-from' applies to
7133 patterns listed in a file.
7136 File: tar.info, Node: wildcards, Next: quoting styles, Prev: exclude, Up: Choosing
7138 6.5 Wildcards Patterns and Matching
7139 ===================================
7141 "Globbing" is the operation by which "wildcard" characters, '*' or '?'
7142 for example, are replaced and expanded into all existing files matching
7143 the given pattern. GNU 'tar' can use wildcard patterns for matching (or
7144 globbing) archive members when extracting from or listing an archive.
7145 Wildcard patterns are also used for verifying volume labels of 'tar'
7146 archives. This section has the purpose of explaining wildcard syntax
7149 A PATTERN should be written according to shell syntax, using wildcard
7150 characters to effect globbing. Most characters in the pattern stand for
7151 themselves in the matched string, and case is significant: 'a' will
7152 match only 'a', and not 'A'. The character '?' in the pattern matches
7153 any single character in the matched string. The character '*' in the
7154 pattern matches zero, one, or more single characters in the matched
7155 string. The character '\' says to take the following character of the
7156 pattern _literally_; it is useful when one needs to match the '?', '*',
7157 '[' or '\' characters, themselves.
7159 The character '[', up to the matching ']', introduces a character
7160 class. A "character class" is a list of acceptable characters for the
7161 next single character of the matched string. For example, '[abcde]'
7162 would match any of the first five letters of the alphabet. Note that
7163 within a character class, all of the "special characters" listed above
7164 other than '\' lose their special meaning; for example, '[-\\[*?]]'
7165 would match any of the characters, '-', '\', '[', '*', '?', or ']'.
7166 (Due to parsing constraints, the characters '-' and ']' must either come
7167 _first_ or _last_ in a character class.)
7169 If the first character of the class after the opening '[' is '!' or
7170 '^', then the meaning of the class is reversed. Rather than listing
7171 character to match, it lists those characters which are _forbidden_ as
7172 the next single character of the matched string.
7174 Other characters of the class stand for themselves. The special
7175 construction '[A-E]', using an hyphen between two letters, is meant to
7176 represent all characters between A and E, inclusive.
7178 Periods ('.') or forward slashes ('/') are not considered special for
7179 wildcard matches. However, if a pattern completely matches a directory
7180 prefix of a matched string, then it matches the full matched string:
7181 thus, excluding a directory also excludes all the files beneath it.
7185 * controlling pattern-matching::
7188 File: tar.info, Node: controlling pattern-matching, Up: wildcards
7190 Controlling Pattern-Matching
7191 ----------------------------
7193 For the purposes of this section, we call "exclusion members" all member
7194 names obtained while processing '--exclude' and '--exclude-from'
7195 options, and "inclusion members" those member names that were given in
7196 the command line or read from the file specified with '--files-from'
7199 These two pairs of member lists are used in the following operations:
7200 '--diff', '--extract', '--list', '--update'.
7202 There are no inclusion members in create mode ('--create' and
7203 '--append'), since in this mode the names obtained from the command line
7204 refer to _files_, not archive members.
7206 By default, inclusion members are compared with archive members
7207 literally (1) and exclusion members are treated as globbing patterns.
7215 # Member names are used verbatim:
7216 $ tar -xf foo.tar -v '[remarks]'
7218 # Exclude member names are globbed:
7219 $ tar -xf foo.tar -v --exclude '*.c'
7223 This behavior can be altered by using the following options:
7226 Treat all member names as wildcards.
7229 Treat all member names as literal strings.
7231 Thus, to extract files whose names end in '.c', you can use:
7233 $ tar -xf foo.tar -v --wildcards '*.c'
7237 Notice quoting of the pattern to prevent the shell from interpreting it.
7239 The effect of '--wildcards' option is canceled by '--no-wildcards'.
7240 This can be used to pass part of the command line arguments verbatim and
7241 other part as globbing patterns. For example, the following invocation:
7243 $ tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'
7245 instructs 'tar' to extract from 'foo.tar' all files whose names end in
7246 '.txt' and the file named '[remarks]'.
7248 Normally, a pattern matches a name if an initial subsequence of the
7249 name's components matches the pattern, where '*', '?', and '[...]' are
7250 the usual shell wildcards, '\' escapes wildcards, and wildcards can
7253 Other than optionally stripping leading '/' from names (*note
7254 absolute::), patterns and names are used as-is. For example, trailing
7255 '/' is not trimmed from a user-specified name before deciding whether to
7258 However, this matching procedure can be altered by the options listed
7259 below. These options accumulate. For example:
7261 --ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
7263 ignores case when excluding 'makefile', but not when excluding 'readme'.
7267 If anchored, a pattern must match an initial subsequence of the
7268 name's components. Otherwise, the pattern can match any
7269 subsequence. Default is '--no-anchored' for exclusion members and
7270 '--anchored' inclusion members.
7274 When ignoring case, upper-case patterns match lower-case names and
7275 vice versa. When not ignoring case (the default), matching is
7278 '--wildcards-match-slash'
7279 '--no-wildcards-match-slash'
7280 When wildcards match slash (the default for exclusion members), a
7281 wildcard like '*' in the pattern can match a '/' in the name.
7282 Otherwise, '/' is matched only by '/'.
7284 The '--recursion' and '--no-recursion' options (*note recurse::) also
7285 affect how member patterns are interpreted. If recursion is in effect,
7286 a pattern matches a name if it matches any of the name's parent
7289 The following table summarizes pattern-matching default values:
7291 Members Default settings
7292 --------------------------------------------------------------------------
7293 Inclusion '--no-wildcards --anchored
7294 --no-wildcards-match-slash'
7295 Exclusion '--wildcards --no-anchored
7296 --wildcards-match-slash'
7298 ---------- Footnotes ----------
7300 (1) Notice that earlier GNU 'tar' versions used globbing for
7301 inclusion members, which contradicted to UNIX98 specification and was
7302 not documented. *Note Changes::, for more information on this and other
7306 File: tar.info, Node: quoting styles, Next: transform, Prev: wildcards, Up: Choosing
7308 6.6 Quoting Member Names
7309 ========================
7311 When displaying member names, 'tar' takes care to avoid ambiguities
7312 caused by certain characters. This is called "name quoting". The
7313 characters in question are:
7315 * Non-printable control characters:
7316 Character ASCII Character name
7317 -------------------------------------------------------------------
7322 \r 13 Carriage return
7323 \t 9 Horizontal tabulation
7324 \v 11 Vertical tabulation
7328 * Single and double quotes (''' and '"')
7332 The exact way 'tar' uses to quote these characters depends on the
7333 "quoting style". The default quoting style, called "escape" (see
7334 below), uses backslash notation to represent control characters, space
7335 and backslash. Using this quoting style, control characters are
7336 represented as listed in column 'Character' in the above table, a space
7337 is printed as '\ ' and a backslash as '\\'.
7339 GNU 'tar' offers seven distinct quoting styles, which can be selected
7340 using '--quoting-style' option:
7342 '--quoting-style=STYLE'
7344 Sets quoting style. Valid values for STYLE argument are: literal,
7345 shell, shell-always, c, escape, locale, clocale.
7347 These styles are described in detail below. To illustrate their
7348 effect, we will use an imaginary tar archive 'arch.tar' containing the
7351 # 1. Contains horizontal tabulation character.
7353 # 2. Contains newline character
7356 # 3. Contains a space
7358 # 4. Contains double quotes
7360 # 5. Contains single quotes
7362 # 6. Contains a backslash character:
7365 Here is how usual 'ls' command would have listed them, if they had
7366 existed in the current working directory:
7379 No quoting, display each character as is:
7381 $ tar tf arch.tar --quoting-style=literal
7392 Display characters the same way Bourne shell does: control
7393 characters, except '\t' and '\n', are printed using backslash
7394 escapes, '\t' and '\n' are printed as is, and a single quote is
7395 printed as '\''. If a name contains any quoted characters, it is
7396 enclosed in single quotes. In particular, if a name contains
7397 single quotes, it is printed as several single-quoted strings:
7399 $ tar tf arch.tar --quoting-style=shell
7402 './a'\''single'\''quote'
7410 Same as 'shell', but the names are always enclosed in single
7413 $ tar tf arch.tar --quoting-style=shell-always
7416 './a'\''single'\''quote'
7424 Use the notation of the C programming language. All names are
7425 enclosed in double quotes. Control characters are quoted using
7426 backslash notations, double quotes are represented as '\"',
7427 backslash characters are represented as '\\'. Single quotes and
7428 spaces are not quoted:
7430 $ tar tf arch.tar --quoting-style=c
7434 "./a\"double\"quote"
7440 Control characters are printed using backslash notation, a space is
7441 printed as '\ ' and a backslash as '\\'. This is the default
7442 quoting style, unless it was changed when configured the package.
7444 $ tar tf arch.tar --quoting-style=escape
7454 Control characters, single quote and backslash are printed using
7455 backslash notation. All names are quoted using left and right
7456 quotation marks, appropriate to the current locale. If it does not
7457 define quotation marks, use ''' as left and as right quotation
7458 marks. Any occurrences of the right quotation mark in a name are
7459 escaped with '\', for example:
7463 $ tar tf arch.tar --quoting-style=locale
7466 './a\'single\'quote'
7473 Same as 'locale', but '"' is used for both left and right quotation
7474 marks, if not provided by the currently selected locale:
7476 $ tar tf arch.tar --quoting-style=clocale
7480 "./a\"double\"quote"
7485 You can specify which characters should be quoted in addition to
7486 those implied by the current quoting style:
7488 '--quote-chars=STRING'
7489 Always quote characters from STRING, even if the selected quoting
7490 style would not quote them.
7492 For example, using 'escape' quoting (compare with the usual escape
7495 $ tar tf arch.tar --quoting-style=escape --quote-chars=' "'
7504 To disable quoting of such additional characters, use the following
7507 '--no-quote-chars=STRING'
7508 Remove characters listed in STRING from the list of quoted
7509 characters set by the previous '--quote-chars' option.
7511 This option is particularly useful if you have added '--quote-chars'
7512 to your 'TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to disable it for
7513 the current invocation.
7515 Note, that '--no-quote-chars' does _not_ disable those characters
7516 that are quoted by default in the selected quoting style.
7519 File: tar.info, Node: transform, Next: after, Prev: quoting styles, Up: Choosing
7521 6.7 Modifying File and Member Names
7522 ===================================
7524 'Tar' archives contain detailed information about files stored in them
7525 and full file names are part of that information. When storing a file
7526 to an archive, its file name is recorded in it, along with the actual
7527 file contents. When restoring from an archive, a file is created on
7528 disk with exactly the same name as that stored in the archive. In the
7529 majority of cases this is the desired behavior of a file archiver.
7530 However, there are some cases when it is not.
7532 First of all, it is often unsafe to extract archive members with
7533 absolute file names or those that begin with a '../'. GNU 'tar' takes
7534 special precautions when extracting such names and provides a special
7535 option for handling them, which is described in *note absolute::.
7537 Secondly, you may wish to extract file names without some leading
7538 directory components, or with otherwise modified names. In other cases
7539 it is desirable to store files under differing names in the archive.
7541 GNU 'tar' provides several options for these needs.
7543 '--strip-components=NUMBER'
7544 Strip given NUMBER of leading components from file names before
7547 For example, suppose you have archived whole '/usr' hierarchy to a
7548 tar archive named 'usr.tar'. Among other files, this archive contains
7549 'usr/include/stdlib.h', which you wish to extract to the current working
7550 directory. To do so, you type:
7552 $ tar -xf usr.tar --strip=2 usr/include/stdlib.h
7554 The option '--strip=2' instructs 'tar' to strip the two leading
7555 components ('usr/' and 'include/') off the file name.
7557 If you add the '--verbose' ('-v') option to the invocation above, you
7558 will note that the verbose listing still contains the full file name,
7559 with the two removed components still in place. This can be
7560 inconvenient, so 'tar' provides a special option for altering this
7563 '--show-transformed-names'
7564 Display file or member names with all requested transformations
7569 $ tar -xf usr.tar -v --strip=2 usr/include/stdlib.h
7570 usr/include/stdlib.h
7571 $ tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h
7574 Notice that in both cases the file 'stdlib.h' is extracted to the
7575 current working directory, '--show-transformed-names' affects only the
7576 way its name is displayed.
7578 This option is especially useful for verifying whether the invocation
7579 will have the desired effect. Thus, before running
7583 it is often advisable to run
7585 $ tar -t -v --show-transformed --strip=N
7587 to make sure the command will produce the intended results.
7589 In case you need to apply more complex modifications to the file
7590 name, GNU 'tar' provides a general-purpose transformation option:
7592 '--transform=EXPRESSION'
7593 '--xform=EXPRESSION'
7594 Modify file names using supplied EXPRESSION.
7596 The EXPRESSION is a 'sed'-like replace expression of the form:
7598 s/REGEXP/REPLACE/[FLAGS]
7600 where REGEXP is a "regular expression", REPLACE is a replacement for
7601 each file name part that matches REGEXP. Both REGEXP and REPLACE are
7602 described in detail in *note The "s" Command: (sed)The "s" Command.
7604 Any delimiter can be used in lieu of '/', the only requirement being
7605 that it be used consistently throughout the expression. For example,
7606 the following two expressions are equivalent:
7611 Changing delimiters is often useful when the REGEX contains slashes.
7612 For example, it is more convenient to write 's,/,-,' than 's/\//-/'.
7614 As in 'sed', you can give several replace expressions, separated by a
7617 Supported FLAGS are:
7620 Apply the replacement to _all_ matches to the REGEXP, not just the
7624 Use case-insensitive matching.
7627 REGEXP is an "extended regular expression" (*note Extended regular
7628 expressions: (sed)Extended regexps.).
7631 Only replace the NUMBERth match of the REGEXP.
7633 Note: the POSIX standard does not specify what should happen when
7634 you mix the 'g' and NUMBER modifiers. GNU 'tar' follows the GNU
7635 'sed' implementation in this regard, so the interaction is defined
7636 to be: ignore matches before the NUMBERth, and then match and
7637 replace all matches from the NUMBERth on.
7639 In addition, several "transformation scope" flags are supported, that
7640 control to what files transformations apply. These are:
7643 Apply transformation to regular archive members.
7646 Do not apply transformation to regular archive members.
7649 Apply transformation to symbolic link targets.
7652 Do not apply transformation to symbolic link targets.
7655 Apply transformation to hard link targets.
7658 Do not apply transformation to hard link targets.
7660 Default is 'rsh', which means to apply transformations to both
7661 archive members and targets of symbolic and hard links.
7663 Default scope flags can also be changed using 'flags=' statement in
7664 the transform expression. The flags set this way remain in force until
7665 next 'flags=' statement or end of expression, whichever occurs first.
7668 --transform 'flags=S;s|^|/usr/local/|'
7670 Here are several examples of '--transform' usage:
7672 1. Extract 'usr/' hierarchy into 'usr/local/':
7674 $ tar --transform='s,usr/,usr/local/,' -x -f arch.tar
7676 2. Strip two leading directory components (equivalent to
7677 '--strip-components=2'):
7679 $ tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar
7681 3. Convert each file name to lower case:
7683 $ tar --transform 's/.*/\L&/' -x -f arch.tar
7685 4. Prepend '/prefix/' to each file name:
7687 $ tar --transform 's,^,/prefix/,' -x -f arch.tar
7689 5. Archive the '/lib' directory, prepending '/usr/local' to each
7692 $ tar --transform 's,^,/usr/local/,S' -c -f arch.tar /lib
7694 Notice the use of flags in the last example. The '/lib' directory
7695 often contains many symbolic links to files within it. It may look, for
7699 drwxr-xr-x root/root 0 2008-07-08 16:20 /lib/
7700 -rwxr-xr-x root/root 1250840 2008-05-25 07:44 /lib/libc-2.3.2.so
7701 lrwxrwxrwx root/root 0 2008-06-24 17:12 /lib/libc.so.6 -> libc-2.3.2.so
7704 Using the expression 's,^,/usr/local/,' would mean adding
7705 '/usr/local' to both regular archive members and to link targets. In
7706 this case, '/lib/libc.so.6' would become:
7708 /usr/local/lib/libc.so.6 -> /usr/local/libc-2.3.2.so
7710 This is definitely not desired. To avoid this, the 'S' flag is used,
7711 which excludes symbolic link targets from filename transformations. The
7714 $ tar --transform 's,^,/usr/local/,S', -c -v -f arch.tar \
7715 --show-transformed /lib
7716 drwxr-xr-x root/root 0 2008-07-08 16:20 /usr/local/lib/
7717 -rwxr-xr-x root/root 1250840 2008-05-25 07:44 /usr/local/lib/libc-2.3.2.so
7718 lrwxrwxrwx root/root 0 2008-06-24 17:12 /usr/local/lib/libc.so.6 \
7721 Unlike '--strip-components', '--transform' can be used in any GNU
7722 'tar' operation mode. For example, the following command adds files to
7723 the archive while replacing the leading 'usr/' component with 'var/':
7725 $ tar -cf arch.tar --transform='s,^usr/,var/,' /
7727 To test '--transform' effect we suggest using
7728 '--show-transformed-names' option:
7730 $ tar -cf arch.tar --transform='s,^usr/,var/,' \
7731 --verbose --show-transformed-names /
7733 If both '--strip-components' and '--transform' are used together,
7734 then '--transform' is applied first, and the required number of
7735 components is then stripped from its result.
7737 You can use as many '--transform' options in a single command line as
7738 you want. The specified expressions will then be applied in order of
7739 their appearance. For example, the following two invocations are
7742 $ tar -cf arch.tar --transform='s,/usr/var,/var/' \
7743 --transform='s,/usr/local,/usr/,'
7744 $ tar -cf arch.tar \
7745 --transform='s,/usr/var,/var/;s,/usr/local,/usr/,'
7748 File: tar.info, Node: after, Next: recurse, Prev: transform, Up: Choosing
7750 6.8 Operating Only on New Files
7751 ===============================
7753 The '--after-date=DATE' ('--newer=DATE', '-N DATE') option causes 'tar'
7754 to only work on files whose data modification or status change times are
7755 newer than the DATE given. If DATE starts with '/' or '.', it is taken
7756 to be a file name; the data modification time of that file is used as
7757 the date. If you use this option when creating or appending to an
7758 archive, the archive will only include new files. If you use
7759 '--after-date' when extracting an archive, 'tar' will only extract files
7760 newer than the DATE you specify.
7762 If you only want 'tar' to make the date comparison based on
7763 modification of the file's data (rather than status changes), then use
7764 the '--newer-mtime=DATE' option.
7766 You may use these options with any operation. Note that these
7767 options differ from the '--update' ('-u') operation in that they allow
7768 you to specify a particular date against which 'tar' can compare when
7769 deciding whether or not to archive the files.
7774 Only store files newer than DATE.
7776 Acts on files only if their data modification or status change
7777 times are later than DATE. Use in conjunction with any operation.
7779 If DATE starts with '/' or '.', it is taken to be a file name; the
7780 data modification time of that file is used as the date.
7782 '--newer-mtime=DATE'
7783 Acts like '--after-date', but only looks at data modification
7786 These options limit 'tar' to operate only on files which have been
7787 modified after the date specified. A file's status is considered to
7788 have changed if its contents have been modified, or if its owner,
7789 permissions, and so forth, have been changed. (For more information on
7790 how to specify a date, see *note Date input formats::; remember that the
7791 entire date argument must be quoted if it contains any spaces.)
7793 Gurus would say that '--after-date' tests both the data modification
7794 time ('mtime', the time the contents of the file were last modified) and
7795 the status change time ('ctime', the time the file's status was last
7796 changed: owner, permissions, etc.) fields, while '--newer-mtime' tests
7797 only the 'mtime' field.
7799 To be precise, '--after-date' checks _both_ 'mtime' and 'ctime' and
7800 processes the file if either one is more recent than DATE, while
7801 '--newer-mtime' only checks 'mtime' and disregards 'ctime'. Neither
7802 does it use 'atime' (the last time the contents of the file were looked
7805 Date specifiers can have embedded spaces. Because of this, you may
7806 need to quote date arguments to keep the shell from parsing them as
7807 separate arguments. For example, the following command will add to the
7808 archive all the files modified less than two days ago:
7810 $ tar -cf foo.tar --newer-mtime '2 days ago'
7812 When any of these options is used with the option '--verbose' (*note
7813 verbose tutorial::) GNU 'tar' will try to convert the specified date
7814 back to its textual representation and compare that with the one given
7815 with the option. If the two dates differ, 'tar' will print a warning
7816 saying what date it will use. This is to help user ensure he is using
7817 the right date. For example:
7819 $ tar -c -f archive.tar --after-date='10 days ago' .
7820 tar: Option --after-date: Treating date '10 days ago' as 2006-06-11
7823 *Please Note:* '--after-date' and '--newer-mtime' should not be
7824 used for incremental backups. *Note Incremental Dumps::, for
7825 proper way of creating incremental backups.
7828 File: tar.info, Node: recurse, Next: one, Prev: after, Up: Choosing
7830 6.9 Descending into Directories
7831 ===============================
7833 Usually, 'tar' will recursively explore all directories (either those
7834 given on the command line or through the '--files-from' option) for the
7835 various files they contain. However, you may not always want 'tar' to
7838 The '--no-recursion' option inhibits 'tar''s recursive descent into
7839 specified directories. If you specify '--no-recursion', you can use the
7840 'find' (*note find: (find)Top.) utility for hunting through levels of
7841 directories to construct a list of file names which you could then pass
7842 to 'tar'. 'find' allows you to be more selective when choosing which
7843 files to archive; see *note files::, for more information on using
7847 Prevents 'tar' from recursively descending directories.
7850 Requires 'tar' to recursively descend directories. This is the
7853 When you use '--no-recursion', GNU 'tar' grabs directory entries
7854 themselves, but does not descend on them recursively. Many people use
7855 'find' for locating files they want to back up, and since 'tar'
7856 _usually_ recursively descends on directories, they have to use the
7857 '-not -type d' test in their 'find' invocation (*note Type:
7858 (find)Type.), as they usually do not want all the files in a directory.
7859 They then use the '--files-from' option to archive the files located via
7862 The problem when restoring files archived in this manner is that the
7863 directories themselves are not in the archive; so the
7864 '--same-permissions' ('--preserve-permissions', '-p') option does not
7865 affect them--while users might really like it to. Specifying
7866 '--no-recursion' is a way to tell 'tar' to grab only the directory
7867 entries given to it, adding no new files on its own. To summarize, if
7868 you use 'find' to create a list of files to be stored in an archive, use
7871 $ find DIR TESTS | \
7872 tar -cf ARCHIVE -T - --no-recursion
7874 The '--no-recursion' option also applies when extracting: it causes
7875 'tar' to extract only the matched directory entries, not the files under
7878 The '--no-recursion' option also affects how globbing patterns are
7879 interpreted (*note controlling pattern-matching::).
7881 The '--no-recursion' and '--recursion' options apply to later options
7882 and operands, and can be overridden by later occurrences of
7883 '--no-recursion' and '--recursion'. For example:
7885 $ tar -cf jams.tar --no-recursion grape --recursion grape/concord
7887 creates an archive with one entry for 'grape', and the recursive
7888 contents of 'grape/concord', but no entries under 'grape' other than
projects / debian / tar / blob