1 This is tar.info, produced by makeinfo version 4.8.90 from tar.texi.
3 This manual is for GNU `tar' (version 1.20, 14 April 2008), which
4 creates and extracts files from archives.
6 Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003,
7 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
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.1 or any later version published by the Free Software
12 Foundation; with no Invariant Sections, with the Front-Cover Texts
13 being "A GNU Manual," and with the Back-Cover Texts as in (a)
14 below. A copy of the license is included in the section entitled
15 "GNU Free Documentation License".
17 (a) The FSF's Back-Cover Text is: "You have the freedom to copy
18 and modify this GNU manual. Buying copies from the FSF supports
19 it in developing GNU and promoting software freedom."
21 INFO-DIR-SECTION Archiving
23 * Tar: (tar). Making tape (or disk) archives.
26 INFO-DIR-SECTION Individual utilities
28 * tar: (tar)tar invocation. Invoking GNU `tar'.
32 File: tar.info, Node: Top, Next: Introduction, Up: (dir)
34 GNU tar: an archiver tool
35 *************************
37 This manual is for GNU `tar' (version 1.20, 14 April 2008), which
38 creates and extracts files from archives.
40 Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003,
41 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
43 Permission is granted to copy, distribute and/or modify this
44 document under the terms of the GNU Free Documentation License,
45 Version 1.1 or any later version published by the Free Software
46 Foundation; with no Invariant Sections, with the Front-Cover Texts
47 being "A GNU Manual," and with the Back-Cover Texts as in (a)
48 below. A copy of the license is included in the section entitled
49 "GNU Free Documentation License".
51 (a) The FSF's Back-Cover Text is: "You have the freedom to copy
52 and modify this GNU manual. Buying copies from the FSF supports
53 it in developing GNU and promoting software freedom."
55 The first part of this master menu lists the major nodes in this Info
56 document. The rest of the menu lists all the lower level nodes.
66 * Date input formats::
73 * Configuring Help Summary::
74 * Fixing Snapshot Files::
77 * Free Software Needs Free Documentation::
78 * Copying This Manual::
79 * Index of Command Line Options::
82 --- The Detailed Node Listing ---
86 * Book Contents:: What this Book Contains
87 * Definitions:: Some Definitions
88 * What tar Does:: What `tar' Does
89 * Naming tar Archives:: How `tar' Archives are Named
90 * Authors:: GNU `tar' Authors
91 * Reports:: Reporting bugs or suggestions
93 Tutorial Introduction to `tar'
96 * stylistic conventions::
97 * basic tar options:: Basic `tar' Operations and Options
98 * frequent operations::
99 * Two Frequent Options::
100 * create:: How to Create Archives
101 * list:: How to List Archives
102 * extract:: How to Extract Members from an Archive
105 Two Frequently Used Options
111 How to Create Archives
113 * prepare for examples::
114 * Creating the archive::
123 How to Extract Members from an Archive
125 * extracting archives::
128 * extracting untrusted archives::
134 * using tar options::
143 The Three Option Styles
145 * Long Options:: Long Option Style
146 * Short Options:: Short Option Style
147 * Old Options:: Old Option Style
148 * Mixing:: Mixing Option Styles
152 * Operation Summary::
154 * Short Option Summary::
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 * Ignore Failed Read::
189 Options Used by `--extract'
191 * Reading:: Options to Help Read Archives
192 * Writing:: Changing How `tar' Writes Files
193 * Scarce:: Coping with Scarce Resources
195 Options to Help Read Archives
197 * read full records::
200 Changing How `tar' Writes Files
202 * Dealing with Old Files::
203 * Overwrite Old Files::
208 * Data Modification Times::
209 * Setting Access Permissions::
210 * Directory Modification Times and Permissions::
211 * Writing to Standard Output::
212 * Writing to an External Program::
215 Coping with Scarce Resources
220 Performing Backups and Restoring Files
222 * Full Dumps:: Using `tar' to Perform Full Dumps
223 * Incremental Dumps:: Using `tar' to Perform Incremental Dumps
224 * Backup Levels:: Levels of Backups
225 * Backup Parameters:: Setting Parameters for Backups and Restoration
226 * Scripted Backups:: Using the Backup Scripts
227 * Scripted Restoration:: Using the Restore Script
229 Setting Parameters for Backups and Restoration
231 * General-Purpose Variables::
232 * Magnetic Tape Control::
234 * backup-specs example:: An Example Text of `Backup-specs'
236 Choosing Files and Names for `tar'
238 * file:: Choosing the Archive's Name
239 * Selecting Archive Members::
240 * files:: Reading Names from a File
241 * exclude:: Excluding Some Files
242 * wildcards:: Wildcards Patterns and Matching
243 * quoting styles:: Ways of Quoting Special Characters in Names
244 * transform:: Modifying File and Member Names
245 * after:: Operating Only on New Files
246 * recurse:: Descending into Directories
247 * one:: Crossing File System Boundaries
249 Reading Names from a File
255 * problems with exclude::
257 Wildcards Patterns and Matching
259 * controlling pattern-matching::
261 Crossing File System Boundaries
263 * directory:: Changing Directory
264 * absolute:: Absolute File Names
268 * General date syntax:: Common rules.
269 * Calendar date items:: 19 Dec 1994.
270 * Time of day items:: 9:20pm.
271 * Time zone items:: EST, PDT, GMT.
272 * Day of week items:: Monday and others.
273 * Relative items in date strings:: next tuesday, 2 years ago.
274 * Pure numbers in date strings:: 19931219, 1440.
275 * Seconds since the Epoch:: @1078100502.
276 * Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
277 * Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
279 Controlling the Archive Format
281 * Compression:: Using Less Space through Compression
282 * Attributes:: Handling File Attributes
283 * Portability:: Making `tar' Archives More Portable
284 * cpio:: Comparison of `tar' and `cpio'
286 Using Less Space through Compression
288 * gzip:: Creating and Reading Compressed Archives
289 * sparse:: Archiving Sparse Files
291 Making `tar' Archives More Portable
293 * Portable Names:: Portable Names
294 * dereference:: Symbolic Links
295 * hard links:: Hard Links
296 * old:: Old V7 Archives
297 * ustar:: Ustar Archives
298 * gnu:: GNU and old GNU format archives.
299 * posix:: POSIX archives
300 * Checksumming:: Checksumming Problems
301 * Large or Negative Values:: Large files, negative time stamps, etc.
302 * Other Tars:: How to Extract GNU-Specific Data Using
303 Other `tar' Implementations
305 GNU `tar' and POSIX `tar'
307 * PAX keywords:: Controlling Extended Header Keywords.
309 How to Extract GNU-Specific Data Using Other `tar' Implementations
311 * Split Recovery:: Members Split Between Volumes
312 * Sparse Recovery:: Sparse Members
314 Tapes and Other Archive Media
316 * Device:: Device selection and switching
317 * Remote Tape Server::
318 * Common Problems and Solutions::
319 * Blocking:: Blocking
320 * Many:: Many archives on one tape
321 * Using Multiple Tapes:: Using Multiple Tapes
322 * label:: Including a Label in the Archive
328 * Format Variations:: Format Variations
329 * Blocking Factor:: The Blocking Factor of an Archive
331 Many Archives on One Tape
333 * Tape Positioning:: Tape Positions and Tape Marks
334 * mt:: The `mt' Utility
338 * Multi-Volume Archives:: Archives Longer than One Tape or Disk
339 * Tape Files:: Tape Files
340 * Tarcat:: Concatenate Volumes into a Single Archive
345 * Standard:: Basic Tar Format
346 * Extensions:: GNU Extensions to the Archive Format
347 * Sparse Formats:: Storing Sparse Files
354 * PAX 0:: PAX Format, Versions 0.0 and 0.1
355 * PAX 1:: PAX Format, Version 1.0
359 * Generate Mode:: File Generation Mode.
360 * Status Mode:: File Status Mode.
361 * Exec Mode:: Synchronous Execution mode.
365 * GNU Free Documentation License:: License for copying this manual
368 File: tar.info, Node: Introduction, Next: Tutorial, Prev: Top, Up: Top
373 GNU `tar' creates and manipulates "archives" which are actually
374 collections of many other files; the program provides users with an
375 organized and systematic method for controlling a large amount of data.
376 The name "tar" originally came from the phrase "Tape ARchive", but
377 archives need not (and these days, typically do not) reside on tapes.
381 * Book Contents:: What this Book Contains
382 * Definitions:: Some Definitions
383 * What tar Does:: What `tar' Does
384 * Naming tar Archives:: How `tar' Archives are Named
385 * Authors:: GNU `tar' Authors
386 * Reports:: Reporting bugs or suggestions
389 File: tar.info, Node: Book Contents, Next: Definitions, Up: Introduction
391 1.1 What this Book Contains
392 ===========================
394 The first part of this chapter introduces you to various terms that will
395 recur throughout the book. It also tells you who has worked on GNU
396 `tar' and its documentation, and where you should send bug reports or
399 The second chapter is a tutorial (*note Tutorial::) which provides a
400 gentle introduction for people who are new to using `tar'. It is meant
401 to be self contained, not requiring any reading from subsequent
402 chapters to make sense. It moves from topic to topic in a logical,
403 progressive order, building on information already explained.
405 Although the tutorial is paced and structured to allow beginners to
406 learn how to use `tar', it is not intended solely for beginners. The
407 tutorial explains how to use the three most frequently used operations
408 (`create', `list', and `extract') as well as two frequently used
409 options (`file' and `verbose'). The other chapters do not refer to the
410 tutorial frequently; however, if a section discusses something which is
411 a complex variant of a basic concept, there may be a cross reference to
412 that basic concept. (The entire book, including the tutorial, assumes
413 that the reader understands some basic concepts of using a Unix-type
414 operating system; *note Tutorial::.)
416 The third chapter presents the remaining five operations, and
417 information about using `tar' options and option syntax.
419 The other chapters are meant to be used as a reference. Each chapter
420 presents everything that needs to be said about a specific topic.
422 One of the chapters (*note Date input formats::) exists in its
423 entirety in other GNU manuals, and is mostly self-contained. In
424 addition, one section of this manual (*note Standard::) contains a big
425 quote which is taken directly from `tar' sources.
427 In general, we give both long and short (abbreviated) option names
428 at least once in each section where the relevant option is covered, so
429 that novice readers will become familiar with both styles. (A few
430 options have no short versions, and the relevant sections will indicate
434 File: tar.info, Node: Definitions, Next: What tar Does, Prev: Book Contents, Up: Introduction
439 The `tar' program is used to create and manipulate `tar' archives. An
440 "archive" is a single file which contains the contents of many files,
441 while still identifying the names of the files, their owner(s), and so
442 forth. (In addition, archives record access permissions, user and
443 group, size in bytes, and data modification time. Some archives also
444 record the file names in each archived directory, as well as other file
445 and directory information.) You can use `tar' to "create" a new
446 archive in a specified directory.
448 The files inside an archive are called "members". Within this
449 manual, we use the term "file" to refer only to files accessible in the
450 normal ways (by `ls', `cat', and so forth), and the term "member" to
451 refer only to the members of an archive. Similarly, a "file name" is
452 the name of a file, as it resides in the file system, and a "member
453 name" is the name of an archive member within the archive.
455 The term "extraction" refers to the process of copying an archive
456 member (or multiple members) into a file in the file system. Extracting
457 all the members of an archive is often called "extracting the archive".
458 The term "unpack" can also be used to refer to the extraction of many
459 or all the members of an archive. Extracting an archive does not
460 destroy the archive's structure, just as creating an archive does not
461 destroy the copies of the files that exist outside of the archive. You
462 may also "list" the members in a given archive (this is often thought
463 of as "printing" them to the standard output, or the command line), or
464 "append" members to a pre-existing archive. All of these operations
465 can be performed using `tar'.
468 File: tar.info, Node: What tar Does, Next: Naming tar Archives, Prev: Definitions, Up: Introduction
473 The `tar' program provides the ability to create `tar' archives, as
474 well as various other kinds of manipulation. For example, you can use
475 `tar' on previously created archives to extract files, to store
476 additional files, or to update or list files which were already stored.
478 Initially, `tar' archives were used to store files conveniently on
479 magnetic tape. The name `tar' comes from this use; it stands for
480 `t'ape `ar'chiver. Despite the utility's name, `tar' can direct its
481 output to available devices, files, or other programs (using pipes).
482 `tar' may even access remote devices or files (as archives).
484 You can use `tar' archives in many ways. We want to stress a few of
485 them: storage, backup, and transportation.
488 Often, `tar' archives are used to store related files for
489 convenient file transfer over a network. For example, the GNU
490 Project distributes its software bundled into `tar' archives, so
491 that all the files relating to a particular program (or set of
492 related programs) can be transferred as a single unit.
494 A magnetic tape can store several files in sequence. However, the
495 tape has no names for these files; it only knows their relative
496 position on the tape. One way to store several files on one tape
497 and retain their names is by creating a `tar' archive. Even when
498 the basic transfer mechanism can keep track of names, as FTP can,
499 the nuisance of handling multiple files, directories, and multiple
500 links makes `tar' archives useful.
502 Archive files are also used for long-term storage. You can think
503 of this as transportation from the present into the future. (It
504 is a science-fiction idiom that you can move through time as well
505 as in space; the idea here is that `tar' can be used to move
506 archives in all dimensions, even time!)
509 Because the archive created by `tar' is capable of preserving file
510 information and directory structure, `tar' is commonly used for
511 performing full and incremental backups of disks. A backup puts a
512 collection of files (possibly pertaining to many users and
513 projects) together on a disk or a tape. This guards against
514 accidental destruction of the information in those files. GNU
515 `tar' has special features that allow it to be used to make
516 incremental and full dumps of all the files in a file system.
519 You can create an archive on one system, transfer it to another
520 system, and extract the contents there. This allows you to
521 transport a group of files from one system to another.
524 File: tar.info, Node: Naming tar Archives, Next: Authors, Prev: What tar Does, Up: Introduction
526 1.4 How `tar' Archives are Named
527 ================================
529 Conventionally, `tar' archives are given names ending with `.tar'.
530 This is not necessary for `tar' to operate properly, but this manual
531 follows that convention in order to accustom readers to it and to make
534 Often, people refer to `tar' archives as "`tar' files," and archive
535 members as "files" or "entries". For people familiar with the
536 operation of `tar', this causes no difficulty. However, in this
537 manual, we consistently refer to "archives" and "archive members" to
538 make learning to use `tar' easier for novice users.
541 File: tar.info, Node: Authors, Next: Reports, Prev: Naming tar Archives, Up: Introduction
543 1.5 GNU `tar' Authors
544 =====================
546 GNU `tar' was originally written by John Gilmore, and modified by many
547 people. The GNU enhancements were written by Jay Fenlason, then Joy
548 Kendall, and the whole package has been further maintained by Thomas
549 Bushnell, n/BSG, Franc,ois Pinard, Paul Eggert, and finally Sergey
550 Poznyakoff with the help of numerous and kind users.
552 We wish to stress that `tar' is a collective work, and owes much to
553 all those people who reported problems, offered solutions and other
554 insights, or shared their thoughts and suggestions. An impressive, yet
555 partial list of those contributors can be found in the `THANKS' file
556 from the GNU `tar' distribution.
558 Jay Fenlason put together a draft of a GNU `tar' manual, borrowing
559 notes from the original man page from John Gilmore. This was withdrawn
560 in version 1.11. Thomas Bushnell, n/BSG and Amy Gorin worked on a
561 tutorial and manual for GNU `tar'. Franc,ois Pinard put version 1.11.8
562 of the manual together by taking information from all these sources and
563 merging them. Melissa Weisshaus finally edited and redesigned the book
564 to create version 1.12. The book for versions from 1.14 up to 1.20
565 were edited by the current maintainer, Sergey Poznyakoff.
567 For version 1.12, Daniel Hagerty contributed a great deal of
568 technical consulting. In particular, he is the primary author of *note
571 In July, 2003 GNU `tar' was put on CVS at savannah.gnu.org (see
572 `http://savannah.gnu.org/projects/tar'), and active development and
573 maintenance work has started again. Currently GNU `tar' is being
574 maintained by Paul Eggert, Sergey Poznyakoff and Jeff Bailey.
576 Support for POSIX archives was added by Sergey Poznyakoff.
579 File: tar.info, Node: Reports, Prev: Authors, Up: Introduction
581 1.6 Reporting bugs or suggestions
582 =================================
584 If you find problems or have suggestions about this program or manual,
585 please report them to `bug-tar@gnu.org'.
587 When reporting a bug, please be sure to include as much detail as
588 possible, in order to reproduce it. .
591 File: tar.info, Node: Tutorial, Next: tar invocation, Prev: Introduction, Up: Top
593 2 Tutorial Introduction to `tar'
594 ********************************
596 This chapter guides you through some basic examples of three `tar'
597 operations: `--create', `--list', and `--extract'. If you already know
598 how to use some other version of `tar', then you may not need to read
599 this chapter. This chapter omits most complicated details about how
605 * stylistic conventions::
606 * basic tar options:: Basic `tar' Operations and Options
607 * frequent operations::
608 * Two Frequent Options::
609 * create:: How to Create Archives
610 * list:: How to List Archives
611 * extract:: How to Extract Members from an Archive
615 File: tar.info, Node: assumptions, Next: stylistic conventions, Up: Tutorial
617 2.1 Assumptions this Tutorial Makes
618 ===================================
620 This chapter is paced to allow beginners to learn about `tar' slowly.
621 At the same time, we will try to cover all the basic aspects of these
622 three operations. In order to accomplish both of these tasks, we have
623 made certain assumptions about your knowledge before reading this
624 manual, and the hardware you will be using:
626 * Before you start to work through this tutorial, you should
627 understand what the terms "archive" and "archive member" mean
628 (*note Definitions::). In addition, you should understand
629 something about how Unix-type operating systems work, and you
630 should know how to use some basic utilities. For example, you
631 should know how to create, list, copy, rename, edit, and delete
632 files and directories; how to change between directories; and how
633 to figure out where you are in the file system. You should have
634 some basic understanding of directory structure and how files are
635 named according to which directory they are in. You should
636 understand concepts such as standard output and standard input,
637 what various definitions of the term `argument' mean, and the
638 differences between relative and absolute file names.
640 * This manual assumes that you are working from your own home
641 directory (unless we state otherwise). In this tutorial, you will
642 create a directory to practice `tar' commands in. When we show
643 file names, we will assume that those names are relative to your
644 home directory. For example, my home directory is
645 `/home/fsf/melissa'. All of my examples are in a subdirectory of
646 the directory named by that file name; the subdirectory is called
649 * In general, we show examples of archives which exist on (or can be
650 written to, or worked with from) a directory on a hard disk. In
651 most cases, you could write those archives to, or work with them
652 on any other device, such as a tape drive. However, some of the
653 later examples in the tutorial and next chapter will not work on
654 tape drives. Additionally, working with tapes is much more
655 complicated than working with hard disks. For these reasons, the
656 tutorial does not cover working with tape drives. *Note Media::,
657 for complete information on using `tar' archives with tape drives.
661 File: tar.info, Node: stylistic conventions, Next: basic tar options, Prev: assumptions, Up: Tutorial
663 2.2 Stylistic Conventions
664 =========================
666 In the examples, `$' represents a typical shell prompt. It precedes
667 lines you should type; to make this more clear, those lines are shown
668 in `this font', as opposed to lines which represent the computer's
669 response; those lines are shown in `this font', or sometimes `like
673 File: tar.info, Node: basic tar options, Next: frequent operations, Prev: stylistic conventions, Up: Tutorial
675 2.3 Basic `tar' Operations and Options
676 ======================================
678 `tar' can take a wide variety of arguments which specify and define the
679 actions it will have on the particular set of files or the archive.
680 The main types of arguments to `tar' fall into one of two classes:
681 operations, and options.
683 Some arguments fall into a class called "operations"; exactly one of
684 these is both allowed and required for any instance of using `tar'; you
685 may _not_ specify more than one. People sometimes speak of "operating
686 modes". You are in a particular operating mode when you have specified
687 the operation which specifies it; there are eight operations in total,
688 and thus there are eight operating modes.
690 The other arguments fall into the class known as "options". You are
691 not required to specify any options, and you are allowed to specify more
692 than one at a time (depending on the way you are using `tar' at that
693 time). Some options are used so frequently, and are so useful for
694 helping you type commands more carefully that they are effectively
695 "required". We will discuss them in this chapter.
697 You can write most of the `tar' operations and options in any of
698 three forms: long (mnemonic) form, short form, and old style. Some of
699 the operations and options have no short or "old" forms; however, the
700 operations and options which we will cover in this tutorial have
701 corresponding abbreviations. We will indicate those abbreviations
702 appropriately to get you used to seeing them. (Note that the "old
703 style" option forms exist in GNU `tar' for compatibility with Unix
704 `tar'. In this book we present a full discussion of this way of
705 writing options and operations (*note Old Options::), and we discuss
706 the other two styles of writing options (*Note Long Options::, and
707 *note Short Options::).
709 In the examples and in the text of this tutorial, we usually use the
710 long forms of operations and options; but the "short" forms produce the
711 same result and can make typing long `tar' commands easier. For
712 example, instead of typing
714 tar --create --verbose --file=afiles.tar apple angst aspic
717 tar -c -v -f afiles.tar apple angst aspic
720 tar -cvf afiles.tar apple angst aspic
722 For more information on option syntax, see *note Advanced tar::. In
723 discussions in the text, when we name an option by its long form, we
724 also give the corresponding short option in parentheses.
726 The term, "option", can be confusing at times, since "operations"
727 are often lumped in with the actual, _optional_ "options" in certain
728 general class statements. For example, we just talked about "short and
729 long forms of options and operations". However, experienced `tar'
730 users often refer to these by shorthand terms such as, "short and long
731 options". This term assumes that the "operations" are included, also.
732 Context will help you determine which definition of "options" to use.
734 Similarly, the term "command" can be confusing, as it is often used
735 in two different ways. People sometimes refer to `tar' "commands". A
736 `tar' "command" is the entire command line of user input which tells
737 `tar' what to do -- including the operation, options, and any arguments
738 (file names, pipes, other commands, etc.). However, you will also
739 sometimes hear the term "the `tar' command". When the word "command"
740 is used specifically like this, a person is usually referring to the
741 `tar' _operation_, not the whole line. Again, use context to figure
742 out which of the meanings the speaker intends.
745 File: tar.info, Node: frequent operations, Next: Two Frequent Options, Prev: basic tar options, Up: Tutorial
747 2.4 The Three Most Frequently Used Operations
748 =============================================
750 Here are the three most frequently used operations (both short and long
751 forms), as well as a brief description of their meanings. The rest of
752 this chapter will cover how to use these operations in detail. We will
753 present the rest of the operations in the next chapter.
757 Create a new `tar' archive.
761 List the contents of an archive.
765 Extract one or more members from an archive.
768 File: tar.info, Node: Two Frequent Options, Next: create, Prev: frequent operations, Up: Tutorial
770 2.5 Two Frequently Used Options
771 ===============================
773 To understand how to run `tar' in the three operating modes listed
774 previously, you also need to understand how to use two of the options to
775 `tar': `--file' (which takes an archive file as an argument) and
776 `--verbose'. (You are usually not _required_ to specify either of
777 these options when you run `tar', but they can be very useful in making
778 things more clear and helping you avoid errors.)
787 File: tar.info, Node: file tutorial, Next: verbose tutorial, Up: Two Frequent Options
792 `--file=ARCHIVE-NAME'
794 Specify the name of an archive file.
796 You can specify an argument for the `--file=ARCHIVE-NAME' (`-f
797 ARCHIVE-NAME') option whenever you use `tar'; this option determines
798 the name of the archive file that `tar' will work on.
800 If you don't specify this argument, then `tar' will examine the
801 environment variable `TAPE'. If it is set, its value will be used as
802 the archive name. Otherwise, `tar' will use the default archive,
803 determined at the compile time. Usually it is standard output or some
804 physical tape drive attached to your machine (you can verify what the
805 default is by running `tar --show-defaults', *note defaults::). If
806 there is no tape drive attached, or the default is not meaningful, then
807 `tar' will print an error message. The error message might look
808 roughly like one of the following:
810 tar: can't open /dev/rmt8 : No such device or address
811 tar: can't open /dev/rsmt0 : I/O error
813 To avoid confusion, we recommend that you always specify an archive file
814 name by using `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') when writing
815 your `tar' commands. For more information on using the
816 `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option, see *note file::.
819 File: tar.info, Node: verbose tutorial, Next: help tutorial, Prev: file tutorial, Up: Two Frequent Options
821 The `--verbose' Option
822 ----------------------
826 Show the files being worked on as `tar' is running.
828 `--verbose' (`-v') shows details about the results of running `tar'.
829 This can be especially useful when the results might not be obvious.
830 For example, if you want to see the progress of `tar' as it writes
831 files into the archive, you can use the `--verbose' option. In the
832 beginning, you may find it useful to use `--verbose' at all times; when
833 you are more accustomed to `tar', you will likely want to use it at
834 certain times but not at others. We will use `--verbose' at times to
835 help make something clear, and we will give many examples both using
836 and not using `--verbose' to show the differences.
838 Each instance of `--verbose' on the command line increases the
839 verbosity level by one, so if you need more details on the output,
842 When reading archives (`--list', `--extract', `--diff'), `tar' by
843 default prints only the names of the members being extracted. Using
844 `--verbose' will show a full, `ls' style member listing.
846 In contrast, when writing archives (`--create', `--append',
847 `--update'), `tar' does not print file names by default. So, a single
848 `--verbose' option shows the file names being added to the archive,
849 while two `--verbose' options enable the full listing.
851 For example, to create an archive in verbose mode:
853 $ tar -cvf afiles.tar apple angst aspic
858 Creating the same archive with the verbosity level 2 could give:
860 $ tar -cvvf afiles.tar apple angst aspic
861 -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
862 -rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst
863 -rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic
865 This works equally well using short or long forms of options. Using
866 long forms, you would simply write out the mnemonic form of the option
869 $ tar --create --verbose --verbose ...
871 Note that you must double the hyphens properly each time.
873 Later in the tutorial, we will give examples using
874 `--verbose --verbose'.
876 The full output consists of six fields:
878 * File type and permissions in symbolic form. These are displayed
879 in the same format as the first column of `ls -l' output (*note
880 format=verbose: (fileutils)What information is listed.).
882 * Owner name and group separated by a slash character. If these
883 data are not available (for example, when listing a `v7' format
884 archive), numeric ID values are printed instead.
886 * Size of the file, in bytes.
888 * File modification date in ISO 8601 format.
890 * File modification time.
892 * File name. If the name contains any special characters (white
893 space, newlines, etc.) these are displayed in an unambiguous form
894 using so called "quoting style". For the detailed discussion of
895 available styles and on how to use them, see *note quoting
898 Depending on the file type, the name can be followed by some
899 additional information, described in the following table:
902 The file or archive member is a "symbolic link" and LINK-NAME
903 is the name of file it links to.
906 The file or archive member is a "hard link" and LINK-NAME is
907 the name of file it links to.
910 The archive member is an old GNU format long link. You will
911 normally not encounter this.
914 The archive member is an old GNU format long name. You will
915 normally not encounter this.
918 The archive member is a GNU "volume header" (*note Tape
921 `--Continued at byte N--'
922 Encountered only at the beginning of a multi-volume archive
923 (*note Using Multiple Tapes::). This archive member is a
924 continuation from the previous volume. The number N gives the
925 offset where the original file was split.
927 `unknown file type C'
928 An archive member of unknown type. C is the type character
929 from the archive header. If you encounter such a message, it
930 means that either your archive contains proprietary member
931 types GNU `tar' is not able to handle, or the archive is
935 For example, here is an archive listing containing most of the
936 special suffixes explained above:
938 V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header--
939 -rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at
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 ---------------------------------------
954 The `--help' option to `tar' prints out a very brief list of all
955 operations and option available for the current version of `tar'
956 available on your system.
959 File: tar.info, Node: create, Next: list, Prev: Two Frequent Options, Up: Tutorial
961 2.6 How to Create Archives
962 ==========================
964 _(This message will disappear, once this node revised.)_
966 One of the basic operations of `tar' is `--create' (`-c'), which you
967 use to create a `tar' archive. We will explain `--create' first
968 because, in order to learn about the other operations, you will find it
969 useful to have an archive available to practice on.
971 To make this easier, in this section you will first create a
972 directory containing three files. Then, we will show you how to create
973 an _archive_ (inside the new directory). Both the directory, and the
974 archive are specifically for you to practice on. The rest of this
975 chapter and the next chapter will show many examples using this
976 directory and the files you will create: some of those files may be
977 other directories and other archives.
979 The three files you will archive in this example are called `blues',
980 `folk', and `jazz'. The archive is called `collection.tar'.
982 This section will proceed slowly, detailing how to use `--create' in
983 `verbose' mode, and showing examples using both short and long forms.
984 In the rest of the tutorial, and in the examples in the next chapter,
985 we will proceed at a slightly quicker pace. This section moves more
986 slowly to allow beginning users to understand how `tar' works.
990 * prepare for examples::
991 * Creating the archive::
997 File: tar.info, Node: prepare for examples, Next: Creating the archive, Up: create
999 2.6.1 Preparing a Practice Directory for Examples
1000 -------------------------------------------------
1002 To follow along with this and future examples, create a new directory
1003 called `practice' containing files called `blues', `folk' and `jazz'.
1004 The files can contain any information you like: ideally, they should
1005 contain information which relates to their names, and be of different
1006 lengths. Our examples assume that `practice' is a subdirectory of your
1009 Now `cd' to the directory named `practice'; `practice' is now your
1010 "working directory". (_Please note_: Although the full file name of
1011 this directory is `/HOMEDIR/practice', in our examples we will refer to
1012 this directory as `practice'; the HOMEDIR is presumed.
1014 In general, you should check that the files to be archived exist
1015 where you think they do (in the working directory) by running `ls'.
1016 Because you just created the directory and the files and have changed to
1017 that directory, you probably don't need to do that this time.
1019 It is very important to make sure there isn't already a file in the
1020 working directory with the archive name you intend to use (in this case,
1021 `collection.tar'), or that you don't care about its contents. Whenever
1022 you use `create', `tar' will erase the current contents of the file
1023 named by `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') if it exists. `tar'
1024 will not tell you if you are about to overwrite an archive unless you
1025 specify an option which does this (*note backup::, for the information
1026 on how to do so). To add files to an existing archive, you need to use
1027 a different option, such as `--append' (`-r'); see *note append:: for
1028 information on how to do this.
1031 File: tar.info, Node: Creating the archive, Next: create verbose, Prev: prepare for examples, Up: create
1033 2.6.2 Creating the Archive
1034 --------------------------
1036 To place the files `blues', `folk', and `jazz' into an archive named
1037 `collection.tar', use the following command:
1039 $ tar --create --file=collection.tar blues folk jazz
1041 The order of the arguments is not very important, _when using long
1042 option forms_. You could also say:
1044 $ tar blues --create folk --file=collection.tar jazz
1046 However, you can see that this order is harder to understand; this is
1047 why we will list the arguments in the order that makes the commands
1048 easiest to understand (and we encourage you to do the same when you use
1049 `tar', to avoid errors).
1051 Note that the sequence `--file=collection.tar' is considered to be
1052 _one_ argument. If you substituted any other string of characters for
1053 `collection.tar', then that string would become the name of the
1054 archive file you create.
1056 The order of the options becomes more important when you begin to use
1057 short forms. With short forms, if you type commands in the wrong order
1058 (even if you type them correctly in all other ways), you may end up with
1059 results you don't expect. For this reason, it is a good idea to get
1060 into the habit of typing options in the order that makes inherent sense.
1061 *Note short create::, for more information on this.
1063 In this example, you type the command as shown above: `--create' is
1064 the operation which creates the new archive (`collection.tar'), and
1065 `--file' is the option which lets you give it the name you chose. The
1066 files, `blues', `folk', and `jazz', are now members of the archive,
1067 `collection.tar' (they are "file name arguments" to the `--create'
1068 operation. *Note Choosing::, for the detailed discussion on these.)
1069 Now that they are in the archive, they are called _archive members_,
1070 not files. (*note members: Definitions.).
1072 When you create an archive, you _must_ specify which files you want
1073 placed in the archive. If you do not specify any archive members, GNU
1074 `tar' will complain.
1076 If you now list the contents of the working directory (`ls'), you
1077 will find the archive file listed as well as the files you saw
1080 blues folk jazz collection.tar
1082 Creating the archive `collection.tar' did not destroy the copies of the
1083 files in the directory.
1085 Keep in mind that if you don't indicate an operation, `tar' will not
1086 run and will prompt you for one. If you don't name any files, `tar'
1087 will complain. You must have write access to the working directory, or
1088 else you will not be able to create an archive in that directory.
1090 _Caution_: Do not attempt to use `--create' (`-c') to add files to
1091 an existing archive; it will delete the archive and write a new one.
1092 Use `--append' (`-r') instead. *Note append::.
1095 File: tar.info, Node: create verbose, Next: short create, Prev: Creating the archive, Up: create
1097 2.6.3 Running `--create' with `--verbose'
1098 -----------------------------------------
1100 If you include the `--verbose' (`-v') option on the command line, `tar'
1101 will list the files it is acting on as it is working. In verbose mode,
1102 the `create' example above would appear as:
1104 $ tar --create --verbose --file=collection.tar blues folk jazz
1109 This example is just like the example we showed which did not use
1110 `--verbose', except that `tar' generated the remaining lines .
1112 In the rest of the examples in this chapter, we will frequently use
1113 `verbose' mode so we can show actions or `tar' responses that you would
1114 otherwise not see, and which are important for you to understand.
1117 File: tar.info, Node: short create, Next: create dir, Prev: create verbose, Up: create
1119 2.6.4 Short Forms with `create'
1120 -------------------------------
1122 As we said before, the `--create' (`-c') operation is one of the most
1123 basic uses of `tar', and you will use it countless times. Eventually,
1124 you will probably want to use abbreviated (or "short") forms of
1125 options. A full discussion of the three different forms that options
1126 can take appears in *note Styles::; for now, here is what the previous
1127 example (including the `--verbose' (`-v') option) looks like using
1130 $ tar -cvf collection.tar blues folk jazz
1135 As you can see, the system responds the same no matter whether you use
1136 long or short option forms.
1138 One difference between using short and long option forms is that,
1139 although the exact placement of arguments following options is no more
1140 specific when using short forms, it is easier to become confused and
1141 make a mistake when using short forms. For example, suppose you
1142 attempted the above example in the following way:
1144 $ tar -cfv collection.tar blues folk jazz
1146 In this case, `tar' will make an archive file called `v', containing
1147 the files `blues', `folk', and `jazz', because the `v' is the closest
1148 "file name" to the `-f' option, and is thus taken to be the chosen
1149 archive file name. `tar' will try to add a file called
1150 `collection.tar' to the `v' archive file; if the file `collection.tar'
1151 did not already exist, `tar' will report an error indicating that this
1152 file does not exist. If the file `collection.tar' does already exist
1153 (e.g., from a previous command you may have run), then `tar' will add
1154 this file to the archive. Because the `-v' option did not get
1155 registered, `tar' will not run under `verbose' mode, and will not
1156 report its progress.
1158 The end result is that you may be quite confused about what happened,
1159 and possibly overwrite a file. To illustrate this further, we will show
1160 you how an example we showed previously would look using short forms.
1164 $ tar blues --create folk --file=collection.tar jazz
1166 is confusing as it is. When shown using short forms, however, it
1167 becomes much more so:
1169 $ tar blues -c folk -f collection.tar jazz
1171 It would be very easy to put the wrong string of characters immediately
1172 following the `-f', but doing that could sacrifice valuable data.
1174 For this reason, we recommend that you pay very careful attention to
1175 the order of options and placement of file and archive names,
1176 especially when using short option forms. Not having the option name
1177 written out mnemonically can affect how well you remember which option
1178 does what, and therefore where different names have to be placed.
1181 File: tar.info, Node: create dir, Prev: short create, Up: create
1183 2.6.5 Archiving Directories
1184 ---------------------------
1186 You can archive a directory by specifying its directory name as a file
1187 name argument to `tar'. The files in the directory will be archived
1188 relative to the working directory, and the directory will be re-created
1189 along with its contents when the archive is extracted.
1191 To archive a directory, first move to its superior directory. If you
1192 have followed the previous instructions in this tutorial, you should
1198 This will put you into the directory which contains `practice', i.e.,
1199 your home directory. Once in the superior directory, you can specify
1200 the subdirectory, `practice', as a file name argument. To store
1201 `practice' in the new archive file `music.tar', type:
1203 $ tar --create --verbose --file=music.tar practice
1205 `tar' should output:
1211 practice/collection.tar
1213 Note that the archive thus created is not in the subdirectory
1214 `practice', but rather in the current working directory--the directory
1215 from which `tar' was invoked. Before trying to archive a directory
1216 from its superior directory, you should make sure you have write access
1217 to the superior directory itself, not only the directory you are trying
1218 archive with `tar'. For example, you will probably not be able to
1219 store your home directory in an archive by invoking `tar' from the root
1220 directory; *Note absolute::. (Note also that `collection.tar', the
1221 original archive file, has itself been archived. `tar' will accept any
1222 file as a file to be archived, regardless of its content. When
1223 `music.tar' is extracted, the archive file `collection.tar' will be
1224 re-written into the file system).
1226 If you give `tar' a command such as
1228 $ tar --create --file=foo.tar .
1230 `tar' will report `tar: ./foo.tar is the archive; not dumped'. This
1231 happens because `tar' creates the archive `foo.tar' in the current
1232 directory before putting any files into it. Then, when `tar' attempts
1233 to add all the files in the directory `.' to the archive, it notices
1234 that the file `./foo.tar' is the same as the archive `foo.tar', and
1235 skips it. (It makes no sense to put an archive into itself.) GNU `tar'
1236 will continue in this case, and create the archive normally, except for
1237 the exclusion of that one file. (_Please note:_ Other implementations
1238 of `tar' may not be so clever; they will enter an infinite loop when
1239 this happens, so you should not depend on this behavior unless you are
1240 certain you are running GNU `tar'. In general, it is wise to always
1241 place the archive outside of the directory being dumped.
1244 File: tar.info, Node: list, Next: extract, Prev: create, Up: Tutorial
1246 2.7 How to List Archives
1247 ========================
1249 Frequently, you will find yourself wanting to determine exactly what a
1250 particular archive contains. You can use the `--list' (`-t') operation
1251 to get the member names as they currently appear in the archive, as
1252 well as various attributes of the files at the time they were archived.
1253 For example, you can examine the archive `collection.tar' that you
1254 created in the last section with the command,
1256 $ tar --list --file=collection.tar
1258 The output of `tar' would then be:
1264 The archive `bfiles.tar' would list as follows:
1270 Be sure to use a `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option just
1271 as with `--create' (`-c') to specify the name of the archive.
1273 If you use the `--verbose' (`-v') option with `--list', then `tar'
1274 will print out a listing reminiscent of `ls -l', showing owner, file
1275 size, and so forth. This output is described in detail in *note
1276 verbose member listing::.
1278 If you had used `--verbose' (`-v') mode, the example above would
1281 $ tar --list --verbose --file=collection.tar folk
1282 -rw-r--r-- myself user 62 1990-05-23 10:55 folk
1284 It is important to notice that the output of `tar --list --verbose'
1285 does not necessarily match that produced by `tar --create --verbose'
1286 while creating the archive. It is because GNU `tar', unless told
1287 explicitly not to do so, removes some directory prefixes from file
1288 names before storing them in the archive (*Note absolute::, for more
1289 information). In other words, in verbose mode GNU `tar' shows "file
1290 names" when creating an archive and "member names" when listing it.
1291 Consider this example:
1293 $ tar cfv archive /etc/mail
1294 tar: Removing leading `/' from member names
1296 /etc/mail/sendmail.cf
1300 etc/mail/sendmail.cf
1303 This default behavior can sometimes be inconvenient. You can force
1304 GNU `tar' show member names when creating archive by supplying
1305 `--show-stored-names' option.
1307 `--show-stored-names'
1308 Print member (as opposed to _file_) names when creating the
1311 You can specify one or more individual member names as arguments when
1312 using `list'. In this case, `tar' will only list the names of members
1313 you identify. For example, `tar --list --file=afiles.tar apple' would
1316 Because `tar' preserves file names, these must be specified as they
1317 appear in the archive (i.e., relative to the directory from which the
1318 archive was created). Therefore, it is essential when specifying
1319 member names to `tar' that you give the exact member names. For
1320 example, `tar --list --file=bfiles.tar birds' would produce an error
1321 message something like `tar: birds: Not found in archive', because
1322 there is no member named `birds', only one named `./birds'. While the
1323 names `birds' and `./birds' name the same file, _member_ names by
1324 default are compared verbatim.
1326 However, `tar --list --file=bfiles.tar baboon' would respond with
1327 `baboon', because this exact member name is in the archive file
1328 `bfiles.tar'. If you are not sure of the exact file name, use
1329 "globbing patterns", for example:
1331 $ tar --list --file=bfiles.tar --wildcards '*b*'
1333 will list all members whose name contains `b'. *Note wildcards::, for
1334 a detailed discussion of globbing patterns and related `tar' command
1342 File: tar.info, Node: list dir, Up: list
1344 Listing the Contents of a Stored Directory
1345 ------------------------------------------
1347 To get information about the contents of an archived directory, use the
1348 directory name as a file name argument in conjunction with `--list'
1349 (`-t'). To find out file attributes, include the `--verbose' (`-v')
1352 For example, to find out about files in the directory `practice', in
1353 the archive file `music.tar', type:
1355 $ tar --list --verbose --file=music.tar practice
1359 drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
1360 -rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues
1361 -rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk
1362 -rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz
1363 -rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar
1365 When you use a directory name as a file name argument, `tar' acts on
1366 all the files (including sub-directories) in that directory.
1369 File: tar.info, Node: extract, Next: going further, Prev: list, Up: Tutorial
1371 2.8 How to Extract Members from an Archive
1372 ==========================================
1374 _(This message will disappear, once this node revised.)_
1376 Creating an archive is only half the job--there is no point in storing
1377 files in an archive if you can't retrieve them. The act of retrieving
1378 members from an archive so they can be used and manipulated as
1379 unarchived files again is called "extraction". To extract files from
1380 an archive, use the `--extract' (`--get' or `-x') operation. As with
1381 `--create', specify the name of the archive with `--file' (`-f')
1382 option. Extracting an archive does not modify the archive in any way;
1383 you can extract it multiple times if you want or need to.
1385 Using `--extract', you can extract an entire archive, or specific
1386 files. The files can be directories containing other files, or not. As
1387 with `--create' (`-c') and `--list' (`-t'), you may use the short or the
1388 long form of the operation without affecting the performance.
1392 * extracting archives::
1393 * extracting files::
1395 * extracting untrusted archives::
1396 * failing commands::
1399 File: tar.info, Node: extracting archives, Next: extracting files, Up: extract
1401 2.8.1 Extracting an Entire Archive
1402 ----------------------------------
1404 To extract an entire archive, specify the archive file name only, with
1405 no individual file names as arguments. For example,
1407 $ tar -xvf collection.tar
1411 -rw-r--r-- me user 28 1996-10-18 16:31 jazz
1412 -rw-r--r-- me user 21 1996-09-23 16:44 blues
1413 -rw-r--r-- me user 20 1996-09-23 16:44 folk
1416 File: tar.info, Node: extracting files, Next: extract dir, Prev: extracting archives, Up: extract
1418 2.8.2 Extracting Specific Files
1419 -------------------------------
1421 To extract specific archive members, give their exact member names as
1422 arguments, as printed by `--list' (`-t'). If you had mistakenly
1423 deleted one of the files you had placed in the archive `collection.tar'
1424 earlier (say, `blues'), you can extract it from the archive without
1425 changing the archive's structure. Its contents will be identical to
1426 the original file `blues' that you deleted.
1428 First, make sure you are in the `practice' directory, and list the
1429 files in the directory. Now, delete the file, `blues', and list the
1430 files in the directory again.
1432 You can now extract the member `blues' from the archive file
1433 `collection.tar' like this:
1435 $ tar --extract --file=collection.tar blues
1437 If you list the files in the directory again, you will see that the file
1438 `blues' has been restored, with its original permissions, data
1439 modification times, and owner.(1) (These parameters will be identical
1440 to those which the file had when you originally placed it in the
1441 archive; any changes you may have made before deleting the file from
1442 the file system, however, will _not_ have been made to the archive
1443 member.) The archive file, `collection.tar', is the same as it was
1444 before you extracted `blues'. You can confirm this by running `tar'
1445 with `--list' (`-t').
1447 Remember that as with other operations, specifying the exact member
1448 name is important. `tar --extract --file=bfiles.tar birds' will fail,
1449 because there is no member named `birds'. To extract the member named
1450 `./birds', you must specify `tar --extract --file=bfiles.tar ./birds'.
1451 If you don't remember the exact member names, use `--list' (`-t') option
1452 (*note list::). You can also extract those members that match a
1453 specific "globbing pattern". For example, to extract from `bfiles.tar'
1454 all files that begin with `b', no matter their directory prefix, you
1457 $ tar -x -f bfiles.tar --wildcards --no-anchored 'b*'
1459 Here, `--wildcards' instructs `tar' to treat command line arguments as
1460 globbing patterns and `--no-anchored' informs it that the patterns
1461 apply to member names after any `/' delimiter. The use of globbing
1462 patterns is discussed in detail in *Note wildcards::.
1464 You can extract a file to standard output by combining the above
1465 options with the `--to-stdout' (`-O') option (*note Writing to Standard
1468 If you give the `--verbose' option, then `--extract' will print the
1469 names of the archive members as it extracts them.
1471 ---------- Footnotes ----------
1473 (1) This is only accidentally true, but not in general. Whereas
1474 modification times are always restored, in most cases, one has to be
1475 root for restoring the owner, and use a special option for restoring
1476 permissions. Here, it just happens that the restoring user is also the
1477 owner of the archived members, and that the current `umask' is
1478 compatible with original permissions.
1481 File: tar.info, Node: extract dir, Next: extracting untrusted archives, Prev: extracting files, Up: extract
1483 2.8.3 Extracting Files that are Directories
1484 -------------------------------------------
1486 Extracting directories which are members of an archive is similar to
1487 extracting other files. The main difference to be aware of is that if
1488 the extracted directory has the same name as any directory already in
1489 the working directory, then files in the extracted directory will be
1490 placed into the directory of the same name. Likewise, if there are
1491 files in the pre-existing directory with the same names as the members
1492 which you extract, the files from the extracted archive will replace
1493 the files already in the working directory (and possible
1494 subdirectories). This will happen regardless of whether or not the
1495 files in the working directory were more recent than those extracted
1496 (there exist, however, special options that alter this behavior *note
1499 However, if a file was stored with a directory name as part of its
1500 file name, and that directory does not exist under the working
1501 directory when the file is extracted, `tar' will create the directory.
1503 We can demonstrate how to use `--extract' to extract a directory
1504 file with an example. Change to the `practice' directory if you
1505 weren't there, and remove the files `folk' and `jazz'. Then, go back
1506 to the parent directory and extract the archive `music.tar'. You may
1507 either extract the entire archive, or you may extract only the files
1508 you just deleted. To extract the entire archive, don't give any file
1509 names as arguments after the archive name `music.tar'. To extract only
1510 the files you deleted, use the following command:
1512 $ tar -xvf music.tar practice/folk practice/jazz
1516 If you were to specify two `--verbose' (`-v') options, `tar' would have
1517 displayed more detail about the extracted files, as shown in the
1520 $ tar -xvvf music.tar practice/folk practice/jazz
1521 -rw-r--r-- me user 28 1996-10-18 16:31 practice/jazz
1522 -rw-r--r-- me user 20 1996-09-23 16:44 practice/folk
1524 Because you created the directory with `practice' as part of the file
1525 names of each of the files by archiving the `practice' directory as
1526 `practice', you must give `practice' as part of the file names when you
1527 extract those files from the archive.
1530 File: tar.info, Node: extracting untrusted archives, Next: failing commands, Prev: extract dir, Up: extract
1532 2.8.4 Extracting Archives from Untrusted Sources
1533 ------------------------------------------------
1535 Extracting files from archives can overwrite files that already exist.
1536 If you receive an archive from an untrusted source, you should make a
1537 new directory and extract into that directory, so that you don't have
1538 to worry about the extraction overwriting one of your existing files.
1539 For example, if `untrusted.tar' came from somewhere else on the
1540 Internet, and you don't necessarily trust its contents, you can extract
1545 $ tar -xvf ../untrusted.tar
1547 It is also a good practice to examine contents of the archive before
1548 extracting it, using `--list' (`-t') option, possibly combined with
1552 File: tar.info, Node: failing commands, Prev: extracting untrusted archives, Up: extract
1554 2.8.5 Commands That Will Fail
1555 -----------------------------
1557 Here are some sample commands you might try which will not work, and why
1560 If you try to use this command,
1562 $ tar -xvf music.tar folk jazz
1564 you will get the following response:
1566 tar: folk: Not found in archive
1567 tar: jazz: Not found in archive
1570 This is because these files were not originally _in_ the parent
1571 directory `..', where the archive is located; they were in the
1572 `practice' directory, and their file names reflect this:
1574 $ tar -tvf music.tar
1579 Likewise, if you try to use this command,
1581 $ tar -tvf music.tar folk jazz
1583 you would get a similar response. Members with those names are not in
1584 the archive. You must use the correct member names, or wildcards, in
1585 order to extract the files from the archive.
1587 If you have forgotten the correct names of the files in the archive,
1588 use `tar --list --verbose' to list them correctly.
1591 File: tar.info, Node: going further, Prev: extract, Up: Tutorial
1593 2.9 Going Further Ahead in this Manual
1594 ======================================
1596 _(This message will disappear, once this node revised.)_
1599 File: tar.info, Node: tar invocation, Next: operations, Prev: Tutorial, Up: Top
1601 3 Invoking GNU `tar'
1602 ********************
1604 _(This message will disappear, once this node revised.)_
1606 This chapter is about how one invokes the GNU `tar' command, from the
1607 command synopsis (*note Synopsis::). There are numerous options, and
1608 many styles for writing them. One mandatory option specifies the
1609 operation `tar' should perform (*note Operation Summary::), other
1610 options are meant to detail how this operation should be performed
1611 (*note Option Summary::). Non-option arguments are not always
1612 interpreted the same way, depending on what the operation is.
1614 You will find in this chapter everything about option styles and
1615 rules for writing them (*note Styles::). On the other hand, operations
1616 and options are fully described elsewhere, in other chapters. Here,
1617 you will find only synthetic descriptions for operations and options,
1618 together with pointers to other parts of the `tar' manual.
1620 Some options are so special they are fully described right in this
1621 chapter. They have the effect of inhibiting the normal operation of
1622 `tar' or else, they globally alter the amount of feedback the user
1623 receives about what is going on. These are the `--help' and
1624 `--version' (*note help::), `--verbose' (*note verbose::) and
1625 `--interactive' options (*note interactive::).
1630 * using tar options::
1640 File: tar.info, Node: Synopsis, Next: using tar options, Up: tar invocation
1642 3.1 General Synopsis of `tar'
1643 =============================
1645 The GNU `tar' program is invoked as either one of:
1647 tar OPTION... [NAME]...
1648 tar LETTER... [ARGUMENT]... [OPTION]... [NAME]...
1650 The second form is for when old options are being used.
1652 You can use `tar' to store files in an archive, to extract them from
1653 an archive, and to do other types of archive manipulation. The primary
1654 argument to `tar', which is called the "operation", specifies which
1655 action to take. The other arguments to `tar' are either "options",
1656 which change the way `tar' performs an operation, or file names or
1657 archive members, which specify the files or members `tar' is to act on.
1659 You can actually type in arguments in any order, even if in this
1660 manual the options always precede the other arguments, to make examples
1661 easier to understand. Further, the option stating the main operation
1662 mode (the `tar' main command) is usually given first.
1664 Each NAME in the synopsis above is interpreted as an archive member
1665 name when the main command is one of `--compare' (`--diff', `-d'),
1666 `--delete', `--extract' (`--get', `-x'), `--list' (`-t') or `--update'
1667 (`-u'). When naming archive members, you must give the exact name of
1668 the member in the archive, as it is printed by `--list'. For
1669 `--append' (`-r') and `--create' (`-c'), these NAME arguments specify
1670 the names of either files or directory hierarchies to place in the
1671 archive. These files or hierarchies should already exist in the file
1672 system, prior to the execution of the `tar' command.
1674 `tar' interprets relative file names as being relative to the
1675 working directory. `tar' will make all file names relative (by
1676 removing leading slashes when archiving or restoring files), unless you
1677 specify otherwise (using the `--absolute-names' option). *Note
1678 absolute::, for more information about `--absolute-names'.
1680 If you give the name of a directory as either a file name or a member
1681 name, then `tar' acts recursively on all the files and directories
1682 beneath that directory. For example, the name `/' identifies all the
1683 files in the file system to `tar'.
1685 The distinction between file names and archive member names is
1686 especially important when shell globbing is used, and sometimes a
1687 source of confusion for newcomers. *Note wildcards::, for more
1688 information about globbing. The problem is that shells may only glob
1689 using existing files in the file system. Only `tar' itself may glob on
1690 archive members, so when needed, you must ensure that wildcard
1691 characters reach `tar' without being interpreted by the shell first.
1692 Using a backslash before `*' or `?', or putting the whole argument
1693 between quotes, is usually sufficient for this.
1695 Even if NAMEs are often specified on the command line, they can also
1696 be read from a text file in the file system, using the
1697 `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option.
1699 If you don't use any file name arguments, `--append' (`-r'),
1700 `--delete' and `--concatenate' (`--catenate', `-A') will do nothing,
1701 while `--create' (`-c') will usually yield a diagnostic and inhibit
1702 `tar' execution. The other operations of `tar' (`--list', `--extract',
1703 `--compare', and `--update') will act on the entire contents of the
1706 Besides successful exits, GNU `tar' may fail for many reasons. Some
1707 reasons correspond to bad usage, that is, when the `tar' command is
1708 improperly written. Errors may be encountered later, while
1709 encountering an error processing the archive or the files. Some errors
1710 are recoverable, in which case the failure is delayed until `tar' has
1711 completed all its work. Some errors are such that it would not
1712 meaningful, or at least risky, to continue processing: `tar' then
1713 aborts processing immediately. All abnormal exits, whether immediate
1714 or delayed, should always be clearly diagnosed on `stderr', after a
1715 line stating the nature of the error.
1717 Possible exit codes of GNU `tar' are summarized in the following
1721 `Successful termination'.
1724 `Some files differ'. If tar was invoked with `--compare'
1725 (`--diff', `-d') command line option, this means that some files
1726 in the archive differ from their disk counterparts (*note
1727 compare::). If tar was given `--create', `--append' or `--update'
1728 option, this exit code means that some files were changed while
1729 being archived and so the resulting archive does not contain the
1730 exact copy of the file set.
1733 `Fatal error'. This means that some fatal, unrecoverable error
1736 If `tar' has invoked a subprocess and that subprocess exited with a
1737 nonzero exit code, `tar' exits with that code as well. This can
1738 happen, for example, if `tar' was given some compression option (*note
1739 gzip::) and the external compressor program failed. Another example is
1740 `rmt' failure during backup to the remote device (*note Remote Tape
1744 File: tar.info, Node: using tar options, Next: Styles, Prev: Synopsis, Up: tar invocation
1746 3.2 Using `tar' Options
1747 =======================
1749 GNU `tar' has a total of eight operating modes which allow you to
1750 perform a variety of tasks. You are required to choose one operating
1751 mode each time you employ the `tar' program by specifying one, and only
1752 one operation as an argument to the `tar' command (two lists of four
1753 operations each may be found at *note frequent operations:: and *note
1754 Operations::). Depending on circumstances, you may also wish to
1755 customize how the chosen operating mode behaves. For example, you may
1756 wish to change the way the output looks, or the format of the files
1757 that you wish to archive may require you to do something special in
1758 order to make the archive look right.
1760 You can customize and control `tar''s performance by running `tar'
1761 with one or more options (such as `--verbose' (`-v'), which we used in
1762 the tutorial). As we said in the tutorial, "options" are arguments to
1763 `tar' which are (as their name suggests) optional. Depending on the
1764 operating mode, you may specify one or more options. Different options
1765 will have different effects, but in general they all change details of
1766 the operation, such as archive format, archive name, or level of user
1767 interaction. Some options make sense with all operating modes, while
1768 others are meaningful only with particular modes. You will likely use
1769 some options frequently, while you will only use others infrequently, or
1770 not at all. (A full list of options is available in *note All
1773 The `TAR_OPTIONS' environment variable specifies default options to
1774 be placed in front of any explicit options. For example, if
1775 `TAR_OPTIONS' is `-v --unlink-first', `tar' behaves as if the two
1776 options `-v' and `--unlink-first' had been specified before any
1777 explicit options. Option specifications are separated by whitespace.
1778 A backslash escapes the next character, so it can be used to specify an
1779 option containing whitespace or a backslash.
1781 Note that `tar' options are case sensitive. For example, the
1782 options `-T' and `-t' are different; the first requires an argument for
1783 stating the name of a file providing a list of NAMEs, while the second
1784 does not require an argument and is another way to write `--list'
1787 In addition to the eight operations, there are many options to
1788 `tar', and three different styles for writing both: long (mnemonic)
1789 form, short form, and old style. These styles are discussed below.
1790 Both the options and the operations can be written in any of these three
1794 File: tar.info, Node: Styles, Next: All Options, Prev: using tar options, Up: tar invocation
1796 3.3 The Three Option Styles
1797 ===========================
1799 There are three styles for writing operations and options to the command
1800 line invoking `tar'. The different styles were developed at different
1801 times during the history of `tar'. These styles will be presented
1802 below, from the most recent to the oldest.
1804 Some options must take an argument. (For example, `--file' (`-f'))
1805 takes the name of an archive file as an argument. If you do not supply
1806 an archive file name, `tar' will use a default, but this can be
1807 confusing; thus, we recommend that you always supply a specific archive
1808 file name.) Where you _place_ the arguments generally depends on which
1809 style of options you choose. We will detail specific information
1810 relevant to each option style in the sections on the different option
1811 styles, below. The differences are subtle, yet can often be very
1812 important; incorrect option placement can cause you to overwrite a
1813 number of important files. We urge you to note these differences, and
1814 only use the option style(s) which makes the most sense to you until
1815 you feel comfortable with the others.
1817 Some options _may_ take an argument. Such options may have at most
1818 long and short forms, they do not have old style equivalent. The rules
1819 for specifying an argument for such options are stricter than those for
1820 specifying mandatory arguments. Please, pay special attention to them.
1824 * Long Options:: Long Option Style
1825 * Short Options:: Short Option Style
1826 * Old Options:: Old Option Style
1827 * Mixing:: Mixing Option Styles
1830 File: tar.info, Node: Long Options, Next: Short Options, Up: Styles
1832 3.3.1 Long Option Style
1833 -----------------------
1835 Each option has at least one "long" (or "mnemonic") name starting with
1836 two dashes in a row, e.g., `--list'. The long names are more clear than
1837 their corresponding short or old names. It sometimes happens that a
1838 single long option has many different names which are synonymous, such
1839 as `--compare' and `--diff'. In addition, long option names can be
1840 given unique abbreviations. For example, `--cre' can be used in place
1841 of `--create' because there is no other long option which begins with
1842 `cre'. (One way to find this out is by trying it and seeing what
1843 happens; if a particular abbreviation could represent more than one
1844 option, `tar' will tell you that that abbreviation is ambiguous and
1845 you'll know that that abbreviation won't work. You may also choose to
1846 run `tar --help' to see a list of options. Be aware that if you run
1847 `tar' with a unique abbreviation for the long name of an option you
1848 didn't want to use, you are stuck; `tar' will perform the command as
1851 Long options are meant to be obvious and easy to remember, and their
1852 meanings are generally easier to discern than those of their
1853 corresponding short options (see below). For example:
1855 $ tar --create --verbose --blocking-factor=20 --file=/dev/rmt0
1857 gives a fairly good set of hints about what the command does, even for
1858 those not fully acquainted with `tar'.
1860 Long options which require arguments take those arguments
1861 immediately following the option name. There are two ways of
1862 specifying a mandatory argument. It can be separated from the option
1863 name either by an equal sign, or by any amount of white space
1864 characters. For example, the `--file' option (which tells the name of
1865 the `tar' archive) is given a file such as `archive.tar' as argument by
1866 using any of the following notations: `--file=archive.tar' or `--file
1869 In contrast, optional arguments must always be introduced using an
1870 equal sign. For example, the `--backup' option takes an optional
1871 argument specifying backup type. It must be used as
1872 `--backup=BACKUP-TYPE'.
1875 File: tar.info, Node: Short Options, Next: Old Options, Prev: Long Options, Up: Styles
1877 3.3.2 Short Option Style
1878 ------------------------
1880 Most options also have a "short option" name. Short options start with
1881 a single dash, and are followed by a single character, e.g., `-t'
1882 (which is equivalent to `--list'). The forms are absolutely identical
1883 in function; they are interchangeable.
1885 The short option names are faster to type than long option names.
1887 Short options which require arguments take their arguments
1888 immediately following the option, usually separated by white space. It
1889 is also possible to stick the argument right after the short option
1890 name, using no intervening space. For example, you might write
1891 `-f archive.tar' or `-farchive.tar' instead of using
1892 `--file=archive.tar'. Both `--file=ARCHIVE-NAME' and `-f ARCHIVE-NAME'
1893 denote the option which indicates a specific archive, here named
1896 Short options which take optional arguments take their arguments
1897 immediately following the option letter, _without any intervening white
1900 Short options' letters may be clumped together, but you are not
1901 required to do this (as compared to old options; see below). When
1902 short options are clumped as a set, use one (single) dash for them all,
1903 e.g., ``tar' -cvf'. Only the last option in such a set is allowed to
1904 have an argument(1).
1906 When the options are separated, the argument for each option which
1907 requires an argument directly follows that option, as is usual for Unix
1908 programs. For example:
1910 $ tar -c -v -b 20 -f /dev/rmt0
1912 If you reorder short options' locations, be sure to move any
1913 arguments that belong to them. If you do not move the arguments
1914 properly, you may end up overwriting files.
1916 ---------- Footnotes ----------
1918 (1) Clustering many options, the last of which has an argument, is a
1919 rather opaque way to write options. Some wonder if GNU `getopt' should
1920 not even be made helpful enough for considering such usages as invalid.
1923 File: tar.info, Node: Old Options, Next: Mixing, Prev: Short Options, Up: Styles
1925 3.3.3 Old Option Style
1926 ----------------------
1928 _(This message will disappear, once this node revised.)_
1930 Like short options, "old options" are single letters. However, old
1931 options must be written together as a single clumped set, without
1932 spaces separating them or dashes preceding them(1). This set of
1933 letters must be the first to appear on the command line, after the
1934 `tar' program name and some white space; old options cannot appear
1935 anywhere else. The letter of an old option is exactly the same letter
1936 as the corresponding short option. For example, the old option `t' is
1937 the same as the short option `-t', and consequently, the same as the
1938 long option `--list'. So for example, the command `tar cv' specifies
1939 the option `-v' in addition to the operation `-c'.
1941 When options that need arguments are given together with the command,
1942 all the associated arguments follow, in the same order as the options.
1943 Thus, the example given previously could also be written in the old
1946 $ tar cvbf 20 /dev/rmt0
1948 Here, `20' is the argument of `-b' and `/dev/rmt0' is the argument of
1951 On the other hand, this old style syntax makes it difficult to match
1952 option letters with their corresponding arguments, and is often
1953 confusing. In the command `tar cvbf 20 /dev/rmt0', for example, `20'
1954 is the argument for `-b', `/dev/rmt0' is the argument for `-f', and
1955 `-v' does not have a corresponding argument. Even using short options
1956 like in `tar -c -v -b 20 -f /dev/rmt0' is clearer, putting all
1957 arguments next to the option they pertain to.
1959 If you want to reorder the letters in the old option argument, be
1960 sure to reorder any corresponding argument appropriately.
1962 This old way of writing `tar' options can surprise even experienced
1963 users. For example, the two commands:
1965 tar cfz archive.tar.gz file
1966 tar -cfz archive.tar.gz file
1968 are quite different. The first example uses `archive.tar.gz' as the
1969 value for option `f' and recognizes the option `z'. The second
1970 example, however, uses `z' as the value for option `f' -- probably not
1973 Old options are kept for compatibility with old versions of `tar'.
1975 This second example could be corrected in many ways, among which the
1976 following are equivalent:
1978 tar -czf archive.tar.gz file
1979 tar -cf archive.tar.gz -z file
1980 tar cf archive.tar.gz -z file
1982 As far as we know, all `tar' programs, GNU and non-GNU, support old
1983 options. GNU `tar' supports them not only for historical reasons, but
1984 also because many people are used to them. For compatibility with Unix
1985 `tar', the first argument is always treated as containing command and
1986 option letters even if it doesn't start with `-'. Thus, `tar c' is
1987 equivalent to `tar -c': both of them specify the `--create' (`-c')
1988 command to create an archive.
1990 ---------- Footnotes ----------
1992 (1) Beware that if you precede options with a dash, you are
1993 announcing the short option style instead of the old option style;
1994 short options are decoded differently.
1997 File: tar.info, Node: Mixing, Prev: Old Options, Up: Styles
1999 3.3.4 Mixing Option Styles
2000 --------------------------
2002 All three styles may be intermixed in a single `tar' command, so long
2003 as the rules for each style are fully respected(1). Old style options
2004 and either of the modern styles of options may be mixed within a single
2005 `tar' command. However, old style options must be introduced as the
2006 first arguments only, following the rule for old options (old options
2007 must appear directly after the `tar' command and some white space).
2008 Modern options may be given only after all arguments to the old options
2009 have been collected. If this rule is not respected, a modern option
2010 might be falsely interpreted as the value of the argument to one of the
2013 For example, all the following commands are wholly equivalent, and
2014 illustrate the many combinations and orderings of option styles.
2016 tar --create --file=archive.tar
2017 tar --create -f archive.tar
2018 tar --create -farchive.tar
2019 tar --file=archive.tar --create
2020 tar --file=archive.tar -c
2021 tar -c --file=archive.tar
2022 tar -c -f archive.tar
2023 tar -c -farchive.tar
2026 tar -f archive.tar --create
2027 tar -f archive.tar -c
2028 tar -farchive.tar --create
2029 tar -farchive.tar -c
2030 tar c --file=archive.tar
2031 tar c -f archive.tar
2034 tar f archive.tar --create
2035 tar f archive.tar -c
2038 On the other hand, the following commands are _not_ equivalent to
2041 tar -f -c archive.tar
2047 These last examples mean something completely different from what the
2048 user intended (judging based on the example in the previous set which
2049 uses long options, whose intent is therefore very clear). The first
2050 four specify that the `tar' archive would be a file named `-c', `c',
2051 `carchive.tar' or `archive.tarc', respectively. The first two examples
2052 also specify a single non-option, NAME argument having the value
2053 `archive.tar'. The last example contains only old style option letters
2054 (repeating option `c' twice), not all of which are meaningful (eg., `.',
2055 `h', or `i'), with no argument value.
2057 ---------- Footnotes ----------
2059 (1) Before GNU `tar' version 1.11.6, a bug prevented intermixing old
2060 style options with long options in some cases.
2063 File: tar.info, Node: All Options, Next: help, Prev: Styles, Up: tar invocation
2065 3.4 All `tar' Options
2066 =====================
2068 The coming manual sections contain an alphabetical listing of all `tar'
2069 operations and options, with brief descriptions and cross references to
2070 more in-depth explanations in the body of the manual. They also
2071 contain an alphabetically arranged table of the short option forms with
2072 their corresponding long option. You can use this table as a reference
2073 for deciphering `tar' commands in scripts.
2077 * Operation Summary::
2079 * Short Option Summary::
2082 File: tar.info, Node: Operation Summary, Next: Option Summary, Up: All Options
2089 Appends files to the end of the archive. *Note append::.
2093 Same as `--concatenate'. *Note concatenate::.
2097 Compares archive members with their counterparts in the file
2098 system, and reports differences in file size, mode, owner,
2099 modification date and contents. *Note compare::.
2103 Appends other `tar' archives to the end of the archive. *Note
2108 Creates a new `tar' archive. *Note create::.
2111 Deletes members from the archive. Don't try this on a archive on a
2112 tape! *Note delete::.
2116 Same `--compare'. *Note compare::.
2120 Extracts members from the archive into the file system. *Note
2125 Same as `--extract'. *Note extract::.
2129 Lists the members in an archive. *Note list::.
2133 Adds files to the end of the archive, but only if they are newer
2134 than their counterparts already in the archive, or if they do not
2135 already exist in the archive. *Note update::.
2139 File: tar.info, Node: Option Summary, Next: Short Option Summary, Prev: Operation Summary, Up: All Options
2146 Normally when creating an archive, `tar' strips an initial `/'
2147 from member names. This option disables that behavior. *Note
2151 (See `--newer', *note after::)
2154 A pattern must match an initial subsequence of the name's
2155 components. *Note controlling pattern-matching::.
2158 `--atime-preserve=replace'
2159 `--atime-preserve=system'
2160 Attempt to preserve the access time of files when reading them.
2161 This option currently is effective only on files that you own,
2162 unless you have superuser privileges.
2164 `--atime-preserve=replace' remembers the access time of a file
2165 before reading it, and then restores the access time afterwards.
2166 This may cause problems if other programs are reading the file at
2167 the same time, as the times of their accesses will be lost. On
2168 most platforms restoring the access time also requires `tar' to
2169 restore the data modification time too, so this option may also
2170 cause problems if other programs are writing the file at the same
2171 time. (Tar attempts to detect this situation, but cannot do so
2172 reliably due to race conditions.) Worse, on most platforms
2173 restoring the access time also updates the status change time,
2174 which means that this option is incompatible with incremental
2177 `--atime-preserve=system' avoids changing time stamps on files,
2178 without interfering with time stamp updates caused by other
2179 programs, so it works better with incremental backups. However,
2180 it requires a special `O_NOATIME' option from the underlying
2181 operating and file system implementation, and it also requires
2182 that searching directories does not update their access times. As
2183 of this writing (November 2005) this works only with Linux, and
2184 only with Linux kernels 2.6.8 and later. Worse, there is
2185 currently no reliable way to know whether this feature actually
2186 works. Sometimes `tar' knows that it does not work, and if you use
2187 `--atime-preserve=system' then `tar' complains and exits right
2188 away. But other times `tar' might think that the option works
2189 when it actually does not.
2191 Currently `--atime-preserve' with no operand defaults to
2192 `--atime-preserve=replace', but this may change in the future as
2193 support for `--atime-preserve=system' improves.
2195 If your operating system does not support
2196 `--atime-preserve=system', you might be able to preserve access
2197 times reliably by by using the `mount' command. For example, you
2198 can mount the file system read-only, or access the file system via
2199 a read-only loopback mount, or use the `noatime' mount option
2200 available on some systems. However, mounting typically requires
2201 superuser privileges and can be a pain to manage.
2205 During a `--create' operation, enables automatic compressed format
2206 recognition based on the archive suffix. *Note gzip::.
2208 `--backup=BACKUP-TYPE'
2209 Rather than deleting files from the file system, `tar' will back
2210 them up using simple or numbered backups, depending upon
2211 BACKUP-TYPE. *Note backup::.
2215 With this option present, `tar' prints error messages for read
2216 errors with the block number in the archive file. *Note
2219 `--blocking-factor=BLOCKING'
2221 Sets the blocking factor `tar' uses to BLOCKING x 512 bytes per
2222 record. *Note Blocking Factor::.
2226 This option tells `tar' to read or write archives through `bzip2'.
2230 Check device numbers when creating a list of modified files for
2231 incremental archiving. This is the default. *Note device
2232 numbers::, for a detailed description.
2234 `--checkpoint[=NUMBER]'
2235 This option directs `tar' to print periodic checkpoint messages as
2236 it reads through the archive. It is intended for when you want a
2237 visual indication that `tar' is still running, but don't want to
2238 see `--verbose' output. You can also instruct `tar' to execute a
2239 list of actions on each checkpoint, see `--checklist-action'
2240 below. For a detailed description, see *note checkpoints::.
2242 `--checkpoint-action=ACTION'
2243 Instruct `tar' to execute an action upon hitting a breakpoint.
2244 Here we give only a brief outline. *Note checkpoints::, for a
2245 complete description.
2247 The ACTION argument can be one of the following:
2250 Produce an audible bell on the console.
2254 Print a single dot on the standard listing stream.
2257 Display a textual message on the standard error, with the
2258 status and number of the checkpoint. This is the default.
2261 Display STRING on the standard error. Before output, the
2262 string is subject to meta-character expansion.
2265 Execute the given COMMAND.
2268 Wait for TIME seconds.
2271 Output STRING on the current console (`/dev/tty').
2273 Several `--checkpoint-action' options can be specified. The
2274 supplied actions will be executed in order of their appearance in
2277 Using `--checkpoint-action' without `--checkpoint' assumes default
2278 checkpoint frequency of one checkpoint per 10 records.
2282 If this option was given, `tar' will check the number of links
2283 dumped for each processed file. If this number does not match the
2284 total number of hard links for the file, a warning message will be
2292 `tar' will use the `compress' program when reading or writing the
2293 archive. This allows you to directly act on archives while saving
2294 space. *Note gzip::.
2297 (See `--interactive'.) *Note interactive::.
2299 `--delay-directory-restore'
2300 Delay setting modification times and permissions of extracted
2301 directories until the end of extraction. *Note Directory
2302 Modification Times and Permissions::.
2306 When creating a `tar' archive, `tar' will archive the file that a
2307 symbolic link points to, rather than archiving the symlink. *Note
2312 When this option is specified, `tar' will change its current
2313 directory to DIR before performing any operations. When this
2314 option is used during archive creation, it is order sensitive.
2318 When performing operations, `tar' will skip files that match
2319 PATTERN. *Note exclude::.
2321 `--exclude-from=FILE'
2323 Similar to `--exclude', except `tar' will use the list of patterns
2324 in the file FILE. *Note exclude::.
2327 Exclude from dump any directory containing a valid cache directory
2328 tag file, but still dump the directory node and the tag file
2333 `--exclude-caches-under'
2334 Exclude from dump any directory containing a valid cache directory
2335 tag file, but still dump the directory node itself.
2339 `--exclude-caches-all'
2340 Exclude from dump any directory containing a valid cache directory
2341 tag file. *Note exclude::.
2343 `--exclude-tag=FILE'
2344 Exclude from dump any directory containing file named FILE, but
2345 dump the directory node and FILE itself. *Note exclude::.
2347 `--exclude-tag-under=FILE'
2348 Exclude from dump the contents of any directory containing file
2349 named FILE, but dump the directory node itself. *Note exclude::.
2351 `--exclude-tag-all=FILE'
2352 Exclude from dump any directory containing file named FILE. *Note
2356 Exclude from dump directories and files, that are internal for some
2357 widely used version control systems.
2363 `tar' will use the file ARCHIVE as the `tar' archive it performs
2364 operations on, rather than `tar''s compilation dependent default.
2365 *Note file tutorial::.
2369 `tar' will use the contents of FILE as a list of archive members
2370 or files to operate on, in addition to those specified on the
2371 command-line. *Note files::.
2374 Forces `tar' to interpret the file name given to `--file' as a
2375 local file, even if it looks like a remote tape drive name. *Note
2376 local and remote archives::.
2380 Selects output archive format. FORMAT may be one of the following:
2383 Creates an archive that is compatible with Unix V7 `tar'.
2386 Creates an archive that is compatible with GNU `tar' version
2390 Creates archive in GNU tar 1.13 format. Basically it is the
2391 same as `oldgnu' with the only difference in the way it
2392 handles long numeric fields.
2395 Creates a POSIX.1-1988 compatible archive.
2398 Creates a POSIX.1-2001 archive.
2401 *Note Formats::, for a detailed discussion of these formats.
2404 Files added to the `tar' archive will have a group ID of GROUP,
2405 rather than the group from the source file. GROUP is first decoded
2406 as a group symbolic name, but if this interpretation fails, it has
2407 to be a decimal numeric group ID. *Note override::.
2409 Also see the comments for the `--owner=USER' option.
2415 This option tells `tar' to read or write archives through `gzip',
2416 allowing `tar' to directly operate on several kinds of compressed
2417 archives transparently. *Note gzip::.
2419 `--hard-dereference'
2420 When creating an archive, dereference hard links and store the
2421 files they refer to, instead of creating usual hard link members.
2427 `tar' will print out a short message summarizing the operations and
2428 options to `tar' and exit. *Note help::.
2431 Ignore case when matching member or file names with patterns.
2432 *Note controlling pattern-matching::.
2434 `--ignore-command-error'
2435 Ignore exit codes of subprocesses. *Note Writing to an External
2438 `--ignore-failed-read'
2439 Do not exit unsuccessfully merely because an unreadable file was
2440 encountered. *Note Reading::.
2444 With this option, `tar' will ignore zeroed blocks in the archive,
2445 which normally signals EOF. *Note Reading::.
2449 Informs `tar' that it is working with an old GNU-format
2450 incremental backup archive. It is intended primarily for
2451 backwards compatibility only. *Note Incremental Dumps::, for a
2452 detailed discussion of incremental archives.
2455 Send verbose output to FILE instead of to standard output.
2457 `--info-script=SCRIPT-FILE'
2458 `--new-volume-script=SCRIPT-FILE'
2460 When `tar' is performing multi-tape backups, SCRIPT-FILE is run at
2461 the end of each tape. If SCRIPT-FILE exits with nonzero status,
2462 `tar' fails immediately. *Note info-script::, for a detailed
2463 discussion of SCRIPT-FILE.
2468 Specifies that `tar' should ask the user for confirmation before
2469 performing potentially destructive options, such as overwriting
2470 files. *Note interactive::.
2472 `--keep-newer-files'
2473 Do not replace existing files that are newer than their archive
2474 copies when extracting files from an archive.
2478 Do not overwrite existing files when extracting files from an
2479 archive. *Note Keep Old Files::.
2483 When creating an archive, instructs `tar' to write NAME as a name
2484 record in the archive. When extracting or listing archives, `tar'
2485 will only operate on archives that have a label matching the
2486 pattern specified in NAME. *Note Tape Files::.
2488 `--listed-incremental=SNAPSHOT-FILE'
2490 During a `--create' operation, specifies that the archive that
2491 `tar' creates is a new GNU-format incremental backup, using
2492 SNAPSHOT-FILE to determine which files to backup. With other
2493 operations, informs `tar' that the archive is in incremental
2494 format. *Note Incremental Dumps::.
2497 This option tells `tar' to read or write archives through `lzma'.
2500 `--mode=PERMISSIONS'
2501 When adding files to an archive, `tar' will use PERMISSIONS for
2502 the archive members, rather than the permissions from the files.
2503 PERMISSIONS can be specified either as an octal number or as
2504 symbolic permissions, like with `chmod'. *Note override::.
2507 When adding files to an archive, `tar' will use DATE as the
2508 modification time of members when creating archives, instead of
2509 their actual modification times. The value of DATE can be either
2510 a textual date representation (*note Date input formats::) or a
2511 name of the existing file, starting with `/' or `.'. In the
2512 latter case, the modification time of that file is used. *Note
2517 Informs `tar' that it should create or otherwise operate on a
2518 multi-volume `tar' archive. *Note Using Multiple Tapes::.
2520 `--new-volume-script'
2526 When creating an archive, `tar' will only add files that have
2527 changed since DATE. If DATE begins with `/' or `.', it is taken
2528 to be the name of a file whose data modification time specifies
2529 the date. *Note after::.
2531 `--newer-mtime=DATE'
2532 Like `--newer', but add only files whose contents have changed (as
2533 opposed to just `--newer', which will also back up files for which
2534 any status information has changed). *Note after::.
2537 An exclude pattern can match any subsequence of the name's
2538 components. *Note controlling pattern-matching::.
2541 Do not check device numbers when creating a list of modified files
2542 for incremental archiving. *Note device numbers::, for a detailed
2545 `--no-delay-directory-restore'
2546 Modification times and permissions of extracted directories are
2547 set when all files from this directory have been extracted. This
2548 is the default. *Note Directory Modification Times and
2552 Use case-sensitive matching. *Note controlling pattern-matching::.
2554 `--no-ignore-command-error'
2555 Print warnings about subprocesses that terminated with a nonzero
2556 exit code. *Note Writing to an External Program::.
2558 `--no-overwrite-dir'
2559 Preserve metadata of existing directories when extracting files
2560 from an archive. *Note Overwrite Old Files::.
2562 `--no-quote-chars=STRING'
2563 Remove characters listed in STRING from the list of quoted
2564 characters set by the previous `--quote-chars' option (*note
2568 With this option, `tar' will not recurse into directories. *Note
2573 When extracting an archive, do not attempt to preserve the owner
2574 specified in the `tar' archive. This the default behavior for
2577 `--no-same-permissions'
2578 When extracting an archive, subtract the user's umask from files
2579 from the permissions specified in the archive. This is the
2580 default behavior for ordinary users.
2583 Treat all input file or member names literally, do not interpret
2584 escape sequences. *Note input name quoting::.
2587 Do not use wildcards. *Note controlling pattern-matching::.
2589 `--no-wildcards-match-slash'
2590 Wildcards do not match `/'. *Note controlling pattern-matching::.
2593 When `tar' is using the `--files-from' option, this option
2594 instructs `tar' to expect file names terminated with NUL, so `tar'
2595 can correctly work with file names that contain newlines. *Note
2599 This option will notify `tar' that it should use numeric user and
2600 group IDs when creating a `tar' file, rather than names. *Note
2604 The function of this option depends on the action `tar' is
2605 performing. When extracting files, `-o' is a synonym for
2606 `--no-same-owner', i.e., it prevents `tar' from restoring
2607 ownership of files being extracted.
2609 When creating an archive, it is a synonym for `--old-archive'.
2610 This behavior is for compatibility with previous versions of GNU
2611 `tar', and will be removed in future releases.
2613 *Note Changes::, for more information.
2615 `--occurrence[=NUMBER]'
2616 This option can be used in conjunction with one of the subcommands
2617 `--delete', `--diff', `--extract' or `--list' when a list of files
2618 is given either on the command line or via `-T' option.
2620 This option instructs `tar' to process only the NUMBERth
2621 occurrence of each named file. NUMBER defaults to 1, so
2623 tar -x -f archive.tar --occurrence filename
2625 will extract the first occurrence of the member `filename' from
2626 `archive.tar' and will terminate without scanning to the end of
2630 Synonym for `--format=v7'.
2633 Used when creating an archive. Prevents `tar' from recursing into
2634 directories that are on different file systems from the current
2638 Overwrite existing files and directory metadata when extracting
2639 files from an archive. *Note Overwrite Old Files::.
2642 Overwrite the metadata of existing directories when extracting
2643 files from an archive. *Note Overwrite Old Files::.
2646 Specifies that `tar' should use USER as the owner of members when
2647 creating archives, instead of the user associated with the source
2648 file. USER is first decoded as a user symbolic name, but if this
2649 interpretation fails, it has to be a decimal numeric user ID.
2652 This option does not affect extraction from archives.
2654 `--pax-option=KEYWORD-LIST'
2655 This option is meaningful only with POSIX.1-2001 archives (*note
2656 posix::). It modifies the way `tar' handles the extended header
2657 keywords. KEYWORD-LIST is a comma-separated list of keyword
2658 options. *Note PAX keywords::, for a detailed discussion.
2662 Synonym for `--format=v7'.
2665 Same as `--format=posix'.
2668 Synonymous with specifying both `--preserve-permissions' and
2669 `--same-order'. *Note Setting Access Permissions::.
2672 (See `--same-order'; *note Reading::.)
2674 `--preserve-permissions'
2675 `--same-permissions'
2677 When `tar' is extracting an archive, it normally subtracts the
2678 users' umask from the permissions specified in the archive and uses
2679 that number as the permissions to create the destination file.
2680 Specifying this option instructs `tar' that it should use the
2681 permissions directly from the archive. *Note Setting Access
2684 `--quote-chars=STRING'
2685 Always quote characters from STRING, even if the selected quoting
2686 style would not quote them (*note quoting styles::).
2688 `--quoting-style=STYLE'
2689 Set quoting style to use when printing member and file names
2690 (*note quoting styles::). Valid STYLE values are: `literal',
2691 `shell', `shell-always', `c', `escape', `locale', and `clocale'.
2692 Default quoting style is `escape', unless overridden while
2693 configuring the package.
2695 `--read-full-records'
2697 Specifies that `tar' should reblock its input, for reading from
2698 pipes on systems with buggy implementations. *Note Reading::.
2700 `--record-size=SIZE'
2701 Instructs `tar' to use SIZE bytes per record when accessing the
2702 archive. *Note Blocking Factor::.
2705 With this option, `tar' recurses into directories (default).
2708 `--recursive-unlink'
2709 Remove existing directory hierarchies before extracting
2710 directories of the same name from the archive. *Note Recursive
2714 Directs `tar' to remove the source file from the file system after
2715 appending it to an archive. *Note remove files::.
2718 Disable use of some potentially harmful `tar' options. Currently
2719 this option disables shell invocation from multi-volume menu
2720 (*note Using Multiple Tapes::).
2723 Notifies `tar' that it should use CMD instead of the default
2724 `/usr/libexec/rmt' (*note Remote Tape Server::).
2727 Notifies `tar' that is should use CMD to communicate with remote
2728 devices. *Note Device::.
2733 This option is an optimization for `tar' when running on machines
2734 with small amounts of memory. It informs `tar' that the list of
2735 file arguments has already been sorted to match the order of files
2736 in the archive. *Note Reading::.
2739 When extracting an archive, `tar' will attempt to preserve the
2740 owner specified in the `tar' archive with this option present.
2741 This is the default behavior for the superuser; this option has an
2742 effect only for ordinary users. *Note Attributes::.
2744 `--same-permissions'
2745 (See `--preserve-permissions'; *note Setting Access Permissions::.)
2749 Assume that the archive media supports seeks to arbitrary
2750 locations. Usually `tar' determines automatically whether the
2751 archive can be seeked or not. This option is intended for use in
2752 cases when such recognition fails.
2755 Displays the default options used by `tar' and exits successfully.
2756 This option is intended for use in shell scripts. Here is an
2757 example of what you can see using this option:
2759 $ tar --show-defaults
2760 --format=gnu -f- -b20 --quoting-style=escape \
2761 --rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
2763 `--show-omitted-dirs'
2764 Instructs `tar' to mention the directories it is skipping when
2765 operating on a `tar' archive. *Note show-omitted-dirs::.
2767 `--show-transformed-names'
2768 `--show-stored-names'
2769 Display file or member names after applying any transformations
2770 (*note transform::). In particular, when used in conjunction with
2771 one of the archive creation operations it instructs `tar' to list
2772 the member names stored in the archive, as opposed to the actual
2773 file names. *Note listing member and file names::.
2777 Invokes a GNU extension when adding files to an archive that
2778 handles sparse files efficiently. *Note sparse::.
2780 `--sparse-version=VERSION'
2781 Specifies the "format version" to use when archiving sparse files.
2782 Implies `--sparse'. *Note sparse::. For the description of the
2783 supported sparse formats, *Note Sparse Formats::.
2785 `--starting-file=NAME'
2787 This option affects extraction only; `tar' will skip extracting
2788 files in the archive until it finds one that matches NAME. *Note
2791 `--strip-components=NUMBER'
2792 Strip given NUMBER of leading components from file names before
2793 extraction. For example, if archive `archive.tar' contained
2794 `/some/file/name', then running
2796 tar --extract --file archive.tar --strip-components=2
2798 would extract this file to file `name'.
2803 Alters the suffix `tar' uses when backing up files from the default
2804 `~'. *Note backup::.
2808 Specifies the length of tapes that `tar' is writing as being
2809 NUM x 1024 bytes long. *Note Using Multiple Tapes::.
2812 Reads the volume label. If an argument is specified, test whether
2813 it matches the volume label. *Note --test-label option::.
2815 `--to-command=COMMAND'
2816 During extraction `tar' will pipe extracted files to the standard
2817 input of COMMAND. *Note Writing to an External Program::.
2821 During extraction, `tar' will extract files to stdout rather than
2822 to the file system. *Note Writing to Standard Output::.
2825 Displays the total number of bytes transferred when processing an
2826 archive. If an argument is given, these data are displayed on
2827 request, when signal SIGNO is delivered to `tar'. *Note totals::.
2831 Sets the data modification time of extracted files to the
2832 extraction time, rather than the data modification time stored in
2833 the archive. *Note Data Modification Times::.
2835 `--transform=SED-EXPR'
2836 Transform file or member names using `sed' replacement expression
2837 SED-EXPR. For example,
2839 $ tar cf archive.tar --transform 's,^\./,usr/,' .
2841 will add to `archive' files from the current working directory,
2842 replacing initial `./' prefix with `usr/'. For the detailed
2843 discussion, *Note transform::.
2845 To see transformed member names in verbose listings, use
2846 `--show-transformed-names' option (*note show-transformed-names::).
2849 (See `--compress'. *note gzip::)
2852 (See `--gzip'. *note gzip::)
2856 Directs `tar' to remove the corresponding file from the file
2857 system before extracting it from the archive. *Note Unlink
2861 Enable unquoting input file or member names (default). *Note
2862 input name quoting::.
2864 `--use-compress-program=PROG'
2865 Instructs `tar' to access the archive through PROG, which is
2866 presumed to be a compression program of some sort. *Note gzip::.
2869 Display file modification dates in UTC. This option implies
2874 Specifies that `tar' should be more verbose about the operations
2875 it is performing. This option can be specified multiple times for
2876 some operations to increase the amount of information displayed.
2881 Verifies that the archive was correctly written when creating an
2882 archive. *Note verify::.
2885 Print information about the program's name, version, origin and
2886 legal status, all on standard output, and then exit successfully.
2890 Used in conjunction with `--multi-volume'. `tar' will keep track
2891 of which volume of a multi-volume archive it is working in FILE.
2895 Use wildcards when matching member names with patterns. *Note
2896 controlling pattern-matching::.
2898 `--wildcards-match-slash'
2899 Wildcards match `/'. *Note controlling pattern-matching::.
2901 ---------- Footnotes ----------
2903 (1) Earlier versions of GNU `tar' understood `-l' as a synonym for
2904 `--one-file-system'. The current semantics, which complies to UNIX98,
2905 was introduced with version 1.15.91. *Note Changes::, for more
2909 File: tar.info, Node: Short Option Summary, Prev: Option Summary, Up: All Options
2911 3.4.3 Short Options Cross Reference
2912 -----------------------------------
2914 Here is an alphabetized list of all of the short option forms, matching
2915 them with the equivalent long option.
2917 Short Option Reference
2918 --------------------------------------------------------------------------
2919 -A *note --concatenate::.
2920 -B *note --read-full-records::.
2921 -C *note --directory::.
2922 -F *note --info-script::.
2923 -G *note --incremental::.
2924 -K *note --starting-file::.
2925 -L *note --tape-length::.
2926 -M *note --multi-volume::.
2928 -O *note --to-stdout::.
2929 -P *note --absolute-names::.
2930 -R *note --block-number::.
2931 -S *note --sparse::.
2932 -T *note --files-from::.
2933 -U *note --unlink-first::.
2935 -W *note --verify::.
2936 -X *note --exclude-from::.
2937 -Z *note --compress::.
2938 -b *note --blocking-factor::.
2939 -c *note --create::.
2940 -d *note --compare::.
2942 -g *note --listed-incremental::.
2943 -h *note --dereference::.
2944 -i *note --ignore-zeros::.
2946 -k *note --keep-old-files::.
2947 -l *note --check-links::.
2949 -o When creating, *note --no-same-owner::, when extracting --
2950 *note --portability::.
2952 The later usage is deprecated. It is retained for
2953 compatibility with the earlier versions of GNU `tar'. In
2954 future releases `-o' will be equivalent to
2955 `--no-same-owner' only.
2956 -p *note --preserve-permissions::.
2957 -r *note --append::.
2958 -s *note --same-order::.
2960 -u *note --update::.
2961 -v *note --verbose::.
2962 -w *note --interactive::.
2963 -x *note --extract::.
2967 File: tar.info, Node: help, Next: defaults, Prev: All Options, Up: tar invocation
2969 3.5 GNU `tar' documentation
2970 ===========================
2972 Being careful, the first thing is really checking that you are using
2973 GNU `tar', indeed. The `--version' option causes `tar' to print
2974 information about its name, version, origin and legal status, all on
2975 standard output, and then exit successfully. For example,
2976 `tar --version' might print:
2979 Copyright (C) 2008 Free Software Foundation, Inc.
2980 This is free software. You may redistribute copies of it under the terms
2981 of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
2982 There is NO WARRANTY, to the extent permitted by law.
2984 Written by John Gilmore and Jay Fenlason.
2986 The first occurrence of `tar' in the result above is the program name
2987 in the package (for example, `rmt' is another program), while the
2988 second occurrence of `tar' is the name of the package itself,
2989 containing possibly many programs. The package is currently named
2990 `tar', after the name of the main program it contains(1).
2992 Another thing you might want to do is checking the spelling or
2993 meaning of some particular `tar' option, without resorting to this
2994 manual, for once you have carefully read it. GNU `tar' has a short
2995 help feature, triggerable through the `--help' option. By using this
2996 option, `tar' will print a usage message listing all available options
2997 on standard output, then exit successfully, without doing anything else
2998 and ignoring all other options. Even if this is only a brief summary,
2999 it may be several screens long. So, if you are not using some kind of
3000 scrollable window, you might prefer to use something like:
3004 presuming, here, that you like using `less' for a pager. Other popular
3005 pagers are `more' and `pg'. If you know about some KEYWORD which
3006 interests you and do not want to read all the `--help' output, another
3007 common idiom is doing:
3009 tar --help | grep KEYWORD
3011 for getting only the pertinent lines. Notice, however, that some `tar'
3012 options have long description lines and the above command will list
3013 only the first of them.
3015 The exact look of the option summary displayed by `tar --help' is
3016 configurable. *Note Configuring Help Summary::, for a detailed
3019 If you only wish to check the spelling of an option, running `tar
3020 --usage' may be a better choice. This will display a terse list of
3021 `tar' option without accompanying explanations.
3023 The short help output is quite succinct, and you might have to get
3024 back to the full documentation for precise points. If you are reading
3025 this paragraph, you already have the `tar' manual in some form. This
3026 manual is available in a variety of forms from
3027 `http://www.gnu.org/software/tar/manual'. It may be printed out of the
3028 GNU `tar' distribution, provided you have TeX already installed
3029 somewhere, and a laser printer around. Just configure the
3030 distribution, execute the command `make dvi', then print `doc/tar.dvi'
3031 the usual way (contact your local guru to know how). If GNU `tar' has
3032 been conveniently installed at your place, this manual is also
3033 available in interactive, hypertextual form as an Info file. Just call
3034 `info tar' or, if you do not have the `info' program handy, use the
3035 Info reader provided within GNU Emacs, calling `tar' from the main Info
3038 There is currently no `man' page for GNU `tar'. If you observe such
3039 a `man' page on the system you are running, either it does not belong
3040 to GNU `tar', or it has not been produced by GNU. Some package
3041 maintainers convert `tar --help' output to a man page, using
3042 `help2man'. In any case, please bear in mind that the authoritative
3043 source of information about GNU `tar' is this Texinfo documentation.
3045 ---------- Footnotes ----------
3047 (1) There are plans to merge the `cpio' and `tar' packages into a
3048 single one which would be called `paxutils'. So, who knows if, one of
3049 this days, the `--version' would not output `tar (GNU paxutils) 3.2'
3052 File: tar.info, Node: defaults, Next: verbose, Prev: help, Up: tar invocation
3054 3.6 Obtaining GNU `tar' default values
3055 ======================================
3057 GNU `tar' has some predefined defaults that are used when you do not
3058 explicitly specify another values. To obtain a list of such defaults,
3059 use `--show-defaults' option. This will output the values in the form
3060 of `tar' command line options:
3063 --format=gnu -f- -b20 --quoting-style=escape
3064 --rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
3066 Notice, that this option outputs only one line. The example output
3067 above has been split to fit page boundaries.
3069 The above output shows that this version of GNU `tar' defaults to using
3070 `gnu' archive format (*note Formats::), it uses standard output as the
3071 archive, if no `--file' option has been given (*note file tutorial::),
3072 the default blocking factor is 20 (*note Blocking Factor::). It also
3073 shows the default locations where `tar' will look for `rmt' and `rsh'
3077 File: tar.info, Node: verbose, Next: checkpoints, Prev: defaults, Up: tar invocation
3079 3.7 Checking `tar' progress
3080 ===========================
3082 Typically, `tar' performs most operations without reporting any
3083 information to the user except error messages. When using `tar' with
3084 many options, particularly ones with complicated or
3085 difficult-to-predict behavior, it is possible to make serious mistakes.
3086 `tar' provides several options that make observing `tar' easier. These
3087 options cause `tar' to print information as it progresses in its job,
3088 and you might want to use them just for being more careful about what
3089 is going on, or merely for entertaining yourself. If you have
3090 encountered a problem when operating on an archive, however, you may
3091 need more information than just an error message in order to solve the
3092 problem. The following options can be helpful diagnostic tools.
3094 Normally, the `--list' (`-t') command to list an archive prints just
3095 the file names (one per line) and the other commands are silent. When
3096 used with most operations, the `--verbose' (`-v') option causes `tar'
3097 to print the name of each file or archive member as it is processed.
3098 This and the other options which make `tar' print status information
3099 can be useful in monitoring `tar'.
3101 With `--create' or `--extract', `--verbose' used once just prints
3102 the names of the files or members as they are processed. Using it
3103 twice causes `tar' to print a longer listing (*Note verbose member
3104 listing::, for the description) for each member. Since `--list'
3105 already prints the names of the members, `--verbose' used once with
3106 `--list' causes `tar' to print an `ls -l' type listing of the files in
3107 the archive. The following examples both extract members with long
3110 $ tar --extract --file=archive.tar --verbose --verbose
3111 $ tar xvvf archive.tar
3113 Verbose output appears on the standard output except when an archive
3114 is being written to the standard output, as with `tar --create --file=-
3115 --verbose' (`tar cfv -', or even `tar cv'--if the installer let
3116 standard output be the default archive). In that case `tar' writes
3117 verbose output to the standard error stream.
3119 If `--index-file=FILE' is specified, `tar' sends verbose output to
3120 FILE rather than to standard output or standard error.
3122 The `--totals' option causes `tar' to print on the standard error
3123 the total amount of bytes transferred when processing an archive. When
3124 creating or appending to an archive, this option prints the number of
3125 bytes written to the archive and the average speed at which they have
3128 $ tar -c -f archive.tar --totals /home
3129 Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
3131 When reading an archive, this option displays the number of bytes
3134 $ tar -x -f archive.tar --totals
3135 Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
3137 Finally, when deleting from an archive, the `--totals' option
3138 displays both numbers plus number of bytes removed from the archive:
3140 $ tar --delete -f foo.tar --totals --wildcards '*~'
3141 Total bytes read: 9543680 (9.2MiB, 201MiB/s)
3142 Total bytes written: 3829760 (3.7MiB, 81MiB/s)
3143 Total bytes deleted: 1474048
3145 You can also obtain this information on request. When `--totals' is
3146 used with an argument, this argument is interpreted as a symbolic name
3147 of a signal, upon delivery of which the statistics is to be printed:
3150 Print statistics upon delivery of signal SIGNO. Valid arguments
3151 are: `SIGHUP', `SIGQUIT', `SIGINT', `SIGUSR1' and `SIGUSR2'.
3152 Shortened names without `SIG' prefix are also accepted.
3154 Both forms of `--totals' option can be used simultaneously. Thus,
3155 `tar -x --totals --totals=USR1' instructs `tar' to extract all members
3156 from its default archive and print statistics after finishing the
3157 extraction, as well as when receiving signal `SIGUSR1'.
3159 The `--checkpoint' option prints an occasional message as `tar'
3160 reads or writes the archive. It is designed for those who don't need
3161 the more detailed (and voluminous) output of `--block-number' (`-R'),
3162 but do want visual confirmation that `tar' is actually making forward
3163 progress. By default it prints a message each 10 records read or
3164 written. This can be changed by giving it a numeric argument after an
3167 $ tar -c --checkpoint=1000 /var
3168 tar: Write checkpoint 1000
3169 tar: Write checkpoint 2000
3170 tar: Write checkpoint 3000
3172 This example shows the default checkpoint message used by `tar'. If
3173 you place a dot immediately after the equal sign, it will print a `.'
3174 at each checkpoint(1). For example:
3176 $ tar -c --checkpoint=.1000 /var
3179 The `--checkpoint' option provides a flexible mechanism for
3180 executing arbitrary actions upon hitting checkpoints, see the next
3181 section (*note checkpoints::), for more information on it.
3183 The `--show-omitted-dirs' option, when reading an archive--with
3184 `--list' or `--extract', for example--causes a message to be printed
3185 for each directory in the archive which is skipped. This happens
3186 regardless of the reason for skipping: the directory might not have
3187 been named on the command line (implicitly or explicitly), it might be
3188 excluded by the use of the `--exclude=PATTERN' option, or some other
3191 If `--block-number' (`-R') is used, `tar' prints, along with every
3192 message it would normally produce, the block number within the archive
3193 where the message was triggered. Also, supplementary messages are
3194 triggered when reading blocks full of NULs, or when hitting end of file
3195 on the archive. As of now, if the archive if properly terminated with
3196 a NUL block, the reading of the file may stop before end of file is
3197 met, so the position of end of file will not usually show when
3198 `--block-number' (`-R') is used. Note that GNU `tar' drains the
3199 archive before exiting when reading the archive from a pipe.
3201 This option is especially useful when reading damaged archives, since
3202 it helps pinpoint the damaged sections. It can also be used with
3203 `--list' (`-t') when listing a file-system backup tape, allowing you to
3204 choose among several backup tapes when retrieving a file later, in
3205 favor of the tape where the file appears earliest (closest to the front
3206 of the tape). *Note backup::.
3208 ---------- Footnotes ----------
3210 (1) This is actually a shortcut for `--checkpoint=N
3211 --checkpoint-action=dot'. *Note dot: checkpoints.
3214 File: tar.info, Node: checkpoints, Next: interactive, Prev: verbose, Up: tar invocation
3219 A "checkpoint" is a moment of time before writing Nth record to the
3220 archive (a "write checkpoint"), or before reading Nth record from the
3221 archive (a "read checkpoint"). Checkpoints allow to periodically
3222 execute arbitrary actions.
3224 The checkpoint facility is enabled using the following option:
3227 Schedule checkpoints before writing or reading each Nth record.
3228 The default value for N is 10.
3230 A list of arbitrary "actions" can be executed at each checkpoint.
3231 These actions include: pausing, displaying textual messages, and
3232 executing arbitrary external programs. Actions are defined using the
3233 `--checkpoint-action' option.
3235 `--checkpoint-action=ACTION'
3236 Execute an ACTION at each checkpoint.
3238 The simplest value of ACTION is `echo'. It instructs `tar' to
3239 display the default message on the standard error stream upon arriving
3240 at each checkpoint. The default message is (in POSIX locale) `Write
3241 checkpoint N', for write checkpoints, and `Read checkpoint N', for read
3242 checkpoints. Here, N represents ordinal number of the checkpoint.
3244 In another locales, translated versions of this message are used.
3246 This is the default action, so running:
3248 $ tar -c --checkpoint=1000 --checkpoint-action=echo /var
3252 $ tar -c --checkpoint=1000 /var
3254 The `echo' action also allows to supply a customized message. You
3255 do so by placing an equals sign and the message right after it, e.g.:
3257 --checkpoint-action="echo=Hit %s checkpoint #%u"
3259 The `%s' and `%u' in the above example are "meta-characters". The
3260 `%s' meta-character is replaced with the "type" of the checkpoint:
3261 `write' or `read' (or a corresponding translated version in locales
3262 other than POSIX). The `%u' meta-character is replaced with the
3263 ordinal number of the checkpoint. Thus, the above example could
3264 produce the following output when used with the `--create' option:
3266 tar: Hit write checkpoint #10
3267 tar: Hit write checkpoint #20
3268 tar: Hit write checkpoint #30
3270 Aside from meta-character expansion, the message string is subject to
3271 "unquoting", during which the backslash "escape sequences" are replaced
3272 with their corresponding ASCII characters (*note escape sequences::).
3273 E.g. the following action will produce an audible bell and the message
3274 described above at each checkpoint:
3276 --checkpoint-action='echo=\aHit %s checkpoint #%u'
3278 There is also a special action which produces an audible signal:
3279 `bell'. It is not equivalent to `echo='\a'', because `bell' sends the
3280 bell directly to the console (`/dev/tty'), whereas `echo='\a'' sends it
3281 to the standard error.
3283 The `ttyout=STRING' action outputs STRING to `/dev/tty', so it can
3284 be used even if the standard output is redirected elsewhere. The
3285 STRING is subject to the same modifications as with `echo' action. In
3286 contrast to the latter, `ttyout' does not prepend `tar' executable name
3287 to the string, nor does it output a newline after it. For example, the
3288 following action will print the checkpoint message at the same screen
3289 line, overwriting any previous message:
3291 --checkpoint-action="ttyout=\rHit %s checkpoint #%u"
3293 Another available checkpoint action is `dot' (or `.'). It instructs
3294 `tar' to print a single dot on the standard listing stream, e.g.:
3296 $ tar -c --checkpoint=1000 --checkpoint-action=dot /var
3299 For compatibility with previous GNU `tar' versions, this action can
3300 be abbreviated by placing a dot in front of the checkpoint frequency,
3301 as shown in the previous section.
3303 Yet another action, `sleep', pauses `tar' for a specified amount of
3304 seconds. The following example will stop for 30 seconds at each
3307 $ tar -c --checkpoint=1000 --checkpoint-action=sleep=30
3309 Finally, the `exec' action executes a given external program. For
3312 $ tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint
3314 This program is executed using `/bin/sh -c', with no additional
3315 arguments. Its exit code is ignored. It gets a copy of `tar''s
3316 environment plus the following variables:
3319 GNU `tar' version number.
3322 The name of the archive `tar' is processing.
3324 `TAR_BLOCKING_FACTOR'
3325 Current blocking factor (*note Blocking::.
3328 The checkpoint number.
3331 A short option describing the operation `tar' is executing *Note
3332 Operations::, for a complete list of subcommand options.
3335 Format of the archive being processed. *Note Formats::, for a
3336 complete list of archive format names.
3338 Any number of actions can be defined, by supplying several
3339 `--checkpoint-action' options in the command line. For example, the
3340 command below displays two messages, pauses execution for 30 seconds
3341 and executes the `/sbin/cpoint' script:
3343 $ tar -c -f arc.tar \
3344 --checkpoint-action='\aecho=Hit %s checkpoint #%u' \
3345 --checkpoint-action='echo=Sleeping for 30 seconds' \
3346 --checkpoint-action='sleep=30' \
3347 --checkpoint-action='exec=/sbin/cpoint'
3349 This example also illustrates the fact that `--checkpoint-action'
3350 can be used without `--checkpoint'. In this case, the default
3351 checkpoint frequency (at each 10th record) is assumed.
3354 File: tar.info, Node: interactive, Prev: checkpoints, Up: tar invocation
3356 3.9 Asking for Confirmation During Operations
3357 =============================================
3359 Typically, `tar' carries out a command without stopping for further
3360 instructions. In some situations however, you may want to exclude some
3361 files and archive members from the operation (for instance if disk or
3362 storage space is tight). You can do this by excluding certain files
3363 automatically (*note Choosing::), or by performing an operation
3364 interactively, using the `--interactive' (`-w') option. `tar' also
3365 accepts `--confirmation' for this option.
3367 When the `--interactive' (`-w') option is specified, before reading,
3368 writing, or deleting files, `tar' first prints a message for each such
3369 file, telling what operation it intends to take, then asks for
3370 confirmation on the terminal. The actions which require confirmation
3371 include adding a file to the archive, extracting a file from the
3372 archive, deleting a file from the archive, and deleting a file from
3373 disk. To confirm the action, you must type a line of input beginning
3374 with `y'. If your input line begins with anything other than `y',
3375 `tar' skips that file.
3377 If `tar' is reading the archive from the standard input, `tar' opens
3378 the file `/dev/tty' to support the interactive communications.
3380 Verbose output is normally sent to standard output, separate from
3381 other error messages. However, if the archive is produced directly on
3382 standard output, then verbose output is mixed with errors on `stderr'.
3383 Producing the archive on standard output may be used as a way to avoid
3384 using disk space, when the archive is soon to be consumed by another
3385 process reading it, say. Some people felt the need of producing an
3386 archive on stdout, still willing to segregate between verbose output
3387 and error output. A possible approach would be using a named pipe to
3388 receive the archive, and having the consumer process to read from that
3389 named pipe. This has the advantage of letting standard output free to
3390 receive verbose output, all separate from errors.
3393 File: tar.info, Node: operations, Next: Backups, Prev: tar invocation, Up: Top
3395 4 GNU `tar' Operations
3396 **********************
3409 File: tar.info, Node: Basic tar, Next: Advanced tar, Up: operations
3411 4.1 Basic GNU `tar' Operations
3412 ==============================
3414 The basic `tar' operations, `--create' (`-c'), `--list' (`-t') and
3415 `--extract' (`--get', `-x'), are currently presented and described in
3416 the tutorial chapter of this manual. This section provides some
3417 complementary notes for these operations.
3421 Creating an empty archive would have some kind of elegance. One
3422 can initialize an empty archive and later use `--append' (`-r')
3423 for adding all members. Some applications would not welcome
3424 making an exception in the way of adding the first archive member.
3425 On the other hand, many people reported that it is dangerously
3426 too easy for `tar' to destroy a magnetic tape with an empty
3427 archive(1). The two most common errors are:
3429 1. Mistakingly using `create' instead of `extract', when the
3430 intent was to extract the full contents of an archive. This
3431 error is likely: keys `c' and `x' are right next to each
3432 other on the QWERTY keyboard. Instead of being unpacked, the
3433 archive then gets wholly destroyed. When users speak about
3434 "exploding" an archive, they usually mean something else :-).
3436 2. Forgetting the argument to `file', when the intent was to
3437 create an archive with a single file in it. This error is
3438 likely because a tired user can easily add the `f' key to the
3439 cluster of option letters, by the mere force of habit,
3440 without realizing the full consequence of doing so. The
3441 usual consequence is that the single file, which was meant to
3442 be saved, is rather destroyed.
3444 So, recognizing the likelihood and the catastrophic nature of these
3445 errors, GNU `tar' now takes some distance from elegance, and
3446 cowardly refuses to create an archive when `--create' option is
3447 given, there are no arguments besides options, and `--files-from'
3448 (`-T') option is _not_ used. To get around the cautiousness of
3449 GNU `tar' and nevertheless create an archive with nothing in it,
3450 one may still use, as the value for the `--files-from' option, a
3451 file with no names in it, as shown in the following commands:
3453 tar --create --file=empty-archive.tar --files-from=/dev/null
3454 tar cfT empty-archive.tar /dev/null
3459 A socket is stored, within a GNU `tar' archive, as a pipe.
3462 GNU `tar' now shows dates as `1996-08-30', while it used to show
3463 them as `Aug 30 1996'. Preferably, people should get used to ISO
3464 8601 dates. Local American dates should be made available again
3465 with full date localization support, once ready. In the meantime,
3466 programs not being localizable for dates should prefer
3467 international dates, that's really the way to go.
3469 Look up `http://www.cl.cam.ac.uk/~mgk25/iso-time.html' if you are
3470 curious, it contains a detailed explanation of the ISO 8601
3474 ---------- Footnotes ----------
3476 (1) This is well described in `Unix-haters Handbook', by Simson
3477 Garfinkel, Daniel Weise & Steven Strassmann, IDG Books, ISBN
3481 File: tar.info, Node: Advanced tar, Next: create options, Prev: Basic tar, Up: operations
3483 4.2 Advanced GNU `tar' Operations
3484 =================================
3486 Now that you have learned the basics of using GNU `tar', you may want
3487 to learn about further ways in which `tar' can help you.
3489 This chapter presents five, more advanced operations which you
3490 probably won't use on a daily basis, but which serve more specialized
3491 functions. We also explain the different styles of options and why you
3492 might want to use one or another, or a combination of them in your `tar'
3493 commands. Additionally, this chapter includes options which allow you
3494 to define the output from `tar' more carefully, and provide help and
3495 error correction in special circumstances.
3507 File: tar.info, Node: Operations, Next: append, Up: Advanced tar
3509 4.2.1 The Five Advanced `tar' Operations
3510 ----------------------------------------
3512 _(This message will disappear, once this node revised.)_
3514 In the last chapter, you learned about the first three operations to
3515 `tar'. This chapter presents the remaining five operations to `tar':
3516 `--append', `--update', `--concatenate', `--delete', and `--compare'.
3518 You are not likely to use these operations as frequently as those
3519 covered in the last chapter; however, since they perform specialized
3520 functions, they are quite useful when you do need to use them. We will
3521 give examples using the same directory and files that you created in
3522 the last chapter. As you may recall, the directory is called
3523 `practice', the files are `jazz', `blues', `folk', `rock', and the two
3524 archive files you created are `collection.tar' and `music.tar'.
3526 We will also use the archive files `afiles.tar' and `bfiles.tar'.
3527 The archive `afiles.tar' contains the members `apple', `angst', and
3528 `aspic'; `bfiles.tar' contains the members `./birds', `baboon', and
3531 Unless we state otherwise, all practicing you do and examples you
3532 follow in this chapter will take place in the `practice' directory that
3533 you created in the previous chapter; see *note prepare for examples::.
3534 (Below in this section, we will remind you of the state of the examples
3535 where the last chapter left them.)
3537 The five operations that we will cover in this chapter are:
3541 Add new entries to an archive that already exists.
3545 Add more recent copies of archive members to the end of an
3546 archive, if they exist.
3551 Add one or more pre-existing archives to the end of another
3555 Delete items from an archive (does not work on tapes).
3560 Compare archive members to their counterparts in the file system.
3563 File: tar.info, Node: append, Next: update, Prev: Operations, Up: Advanced tar
3565 4.2.2 How to Add Files to Existing Archives: `--append'
3566 -------------------------------------------------------
3568 _(This message will disappear, once this node revised.)_
3570 If you want to add files to an existing archive, you don't need to
3571 create a new archive; you can use `--append' (`-r'). The archive must
3572 already exist in order to use `--append'. (A related operation is the
3573 `--update' operation; you can use this to add newer versions of archive
3574 members to an existing archive. To learn how to do this with
3575 `--update', *note update::.)
3577 If you use `--append' to add a file that has the same name as an
3578 archive member to an archive containing that archive member, then the
3579 old member is not deleted. What does happen, however, is somewhat
3580 complex. `tar' _allows_ you to have infinite number of files with the
3581 same name. Some operations treat these same-named members no
3582 differently than any other set of archive members: for example, if you
3583 view an archive with `--list' (`-t'), you will see all of those members
3584 listed, with their data modification times, owners, etc.
3586 Other operations don't deal with these members as perfectly as you
3587 might prefer; if you were to use `--extract' to extract the archive,
3588 only the most recently added copy of a member with the same name as four
3589 other members would end up in the working directory. This is because
3590 `--extract' extracts an archive in the order the members appeared in
3591 the archive; the most recently archived members will be extracted last.
3592 Additionally, an extracted member will _replace_ a file of the same
3593 name which existed in the directory already, and `tar' will not prompt
3594 you about this(1). Thus, only the most recently archived member will
3595 end up being extracted, as it will replace the one extracted before it,
3598 There exists a special option that allows you to get around this
3599 behavior and extract (or list) only a particular copy of the file.
3600 This is `--occurrence' option. If you run `tar' with this option, it
3601 will extract only the first copy of the file. You may also give this
3602 option an argument specifying the number of copy to be extracted.
3603 Thus, for example if the archive `archive.tar' contained three copies
3604 of file `myfile', then the command
3606 tar --extract --file archive.tar --occurrence=2 myfile
3608 would extract only the second copy. *Note --occurrence: Option
3609 Summary, for the description of `--occurrence' option.
3611 If you want to replace an archive member, use `--delete' to delete
3612 the member you want to remove from the archive, , and then use
3613 `--append' to add the member you want to be in the archive. Note that
3614 you can not change the order of the archive; the most recently added
3615 member will still appear last. In this sense, you cannot truly
3616 "replace" one member with another. (Replacing one member with another
3617 will not work on certain types of media, such as tapes; see *note
3618 delete:: and *note Media::, for more information.)
3622 * appending files:: Appending Files to an Archive
3625 ---------- Footnotes ----------
3627 (1) Unless you give it `--keep-old-files' option, or the disk copy
3628 is newer than the the one in the archive and you invoke `tar' with
3629 `--keep-newer-files' option
3632 File: tar.info, Node: appending files, Next: multiple, Up: append
3634 4.2.2.1 Appending Files to an Archive
3635 .....................................
3637 _(This message will disappear, once this node revised.)_
3639 The simplest way to add a file to an already existing archive is the
3640 `--append' (`-r') operation, which writes specified files into the
3641 archive whether or not they are already among the archived files.
3643 When you use `--append', you _must_ specify file name arguments, as
3644 there is no default. If you specify a file that already exists in the
3645 archive, another copy of the file will be added to the end of the
3646 archive. As with other operations, the member names of the newly added
3647 files will be exactly the same as their names given on the command
3648 line. The `--verbose' (`-v') option will print out the names of the
3649 files as they are written into the archive.
3651 `--append' cannot be performed on some tape drives, unfortunately,
3652 due to deficiencies in the formats those tape drives use. The archive
3653 must be a valid `tar' archive, or else the results of using this
3654 operation will be unpredictable. *Note Media::.
3656 To demonstrate using `--append' to add a file to an archive, create
3657 a file called `rock' in the `practice' directory. Make sure you are in
3658 the `practice' directory. Then, run the following `tar' command to add
3659 `rock' to `collection.tar':
3661 $ tar --append --file=collection.tar rock
3663 If you now use the `--list' (`-t') operation, you will see that `rock'
3664 has been added to the archive:
3666 $ tar --list --file=collection.tar
3667 -rw-r--r-- me user 28 1996-10-18 16:31 jazz
3668 -rw-r--r-- me user 21 1996-09-23 16:44 blues
3669 -rw-r--r-- me user 20 1996-09-23 16:44 folk
3670 -rw-r--r-- me user 20 1996-09-23 16:44 rock
3673 File: tar.info, Node: multiple, Prev: appending files, Up: append
3675 4.2.2.2 Multiple Members with the Same Name
3676 ...........................................
3678 You can use `--append' (`-r') to add copies of files which have been
3679 updated since the archive was created. (However, we do not recommend
3680 doing this since there is another `tar' option called `--update'; *Note
3681 update::, for more information. We describe this use of `--append'
3682 here for the sake of completeness.) When you extract the archive, the
3683 older version will be effectively lost. This works because files are
3684 extracted from an archive in the order in which they were archived.
3685 Thus, when the archive is extracted, a file archived later in time will
3686 replace a file of the same name which was archived earlier, even though
3687 the older version of the file will remain in the archive unless you
3688 delete all versions of the file.
3690 Supposing you change the file `blues' and then append the changed
3691 version to `collection.tar'. As you saw above, the original `blues' is
3692 in the archive `collection.tar'. If you change the file and append the
3693 new version of the file to the archive, there will be two copies in the
3694 archive. When you extract the archive, the older version of the file
3695 will be extracted first, and then replaced by the newer version when it
3698 You can append the new, changed copy of the file `blues' to the
3699 archive in this way:
3701 $ tar --append --verbose --file=collection.tar blues
3704 Because you specified the `--verbose' option, `tar' has printed the
3705 name of the file being appended as it was acted on. Now list the
3706 contents of the archive:
3708 $ tar --list --verbose --file=collection.tar
3709 -rw-r--r-- me user 28 1996-10-18 16:31 jazz
3710 -rw-r--r-- me user 21 1996-09-23 16:44 blues
3711 -rw-r--r-- me user 20 1996-09-23 16:44 folk
3712 -rw-r--r-- me user 20 1996-09-23 16:44 rock
3713 -rw-r--r-- me user 58 1996-10-24 18:30 blues
3715 The newest version of `blues' is now at the end of the archive (note
3716 the different creation dates and file sizes). If you extract the
3717 archive, the older version of the file `blues' will be replaced by the
3718 newer version. You can confirm this by extracting the archive and
3719 running `ls' on the directory.
3721 If you wish to extract the first occurrence of the file `blues' from
3722 the archive, use `--occurrence' option, as shown in the following
3725 $ tar --extract -vv --occurrence --file=collection.tar blues
3726 -rw-r--r-- me user 21 1996-09-23 16:44 blues
3728 *Note Writing::, for more information on `--extract' and *Note
3729 -occurrence: Option Summary, for the description of `--occurrence'
3733 File: tar.info, Node: update, Next: concatenate, Prev: append, Up: Advanced tar
3735 4.2.3 Updating an Archive
3736 -------------------------
3738 _(This message will disappear, once this node revised.)_
3740 In the previous section, you learned how to use `--append' to add a
3741 file to an existing archive. A related operation is `--update' (`-u').
3742 The `--update' operation updates a `tar' archive by comparing the date
3743 of the specified archive members against the date of the file with the
3744 same name. If the file has been modified more recently than the
3745 archive member, then the newer version of the file is added to the
3746 archive (as with `--append').
3748 Unfortunately, you cannot use `--update' with magnetic tape drives.
3749 The operation will fail.
3751 Both `--update' and `--append' work by adding to the end of the
3752 archive. When you extract a file from the archive, only the version
3753 stored last will wind up in the file system, unless you use the
3754 `--backup' option. *Note multiple::, for a detailed discussion.
3761 File: tar.info, Node: how to update, Up: update
3763 4.2.3.1 How to Update an Archive Using `--update'
3764 .................................................
3766 You must use file name arguments with the `--update' (`-u') operation.
3767 If you don't specify any files, `tar' won't act on any files and won't
3768 tell you that it didn't do anything (which may end up confusing you).
3770 To see the `--update' option at work, create a new file,
3771 `classical', in your practice directory, and some extra text to the
3772 file `blues', using any text editor. Then invoke `tar' with the
3773 `update' operation and the `--verbose' (`-v') option specified, using
3774 the names of all the files in the practice directory as file name
3777 $ tar --update -v -f collection.tar blues folk rock classical
3782 Because we have specified verbose mode, `tar' prints out the names of
3783 the files it is working on, which in this case are the names of the
3784 files that needed to be updated. If you run `tar --list' and look at
3785 the archive, you will see `blues' and `classical' at its end. There
3786 will be a total of two versions of the member `blues'; the one at the
3787 end will be newer and larger, since you added text before updating it.
3789 (The reason `tar' does not overwrite the older file when updating it
3790 is because writing to the middle of a section of tape is a difficult
3791 process. Tapes are not designed to go backward. *Note Media::, for
3792 more information about tapes.
3794 `--update' (`-u') is not suitable for performing backups for two
3795 reasons: it does not change directory content entries, and it lengthens
3796 the archive every time it is used. The GNU `tar' options intended
3797 specifically for backups are more efficient. If you need to run
3798 backups, please consult *note Backups::.
3801 File: tar.info, Node: concatenate, Next: delete, Prev: update, Up: Advanced tar
3803 4.2.4 Combining Archives with `--concatenate'
3804 ---------------------------------------------
3806 Sometimes it may be convenient to add a second archive onto the end of
3807 an archive rather than adding individual files to the archive. To add
3808 one or more archives to the end of another archive, you should use the
3809 `--concatenate' (`--catenate', `-A') operation.
3811 To use `--concatenate', give the first archive with `--file' option
3812 and name the rest of archives to be concatenated on the command line.
3813 The members, and their member names, will be copied verbatim from those
3814 archives to the first one. (1) The new, concatenated archive will be
3815 called by the same name as the one given with the `--file' option. As
3816 usual, if you omit `--file', `tar' will use the value of the environment
3817 variable `TAPE', or, if this has not been set, the default archive name.
3819 To demonstrate how `--concatenate' works, create two small archives
3820 called `bluesrock.tar' and `folkjazz.tar', using the relevant files
3823 $ tar -cvf bluesrock.tar blues rock
3826 $ tar -cvf folkjazz.tar folk jazz
3830 If you like, You can run `tar --list' to make sure the archives contain
3831 what they are supposed to:
3833 $ tar -tvf bluesrock.tar
3834 -rw-r--r-- melissa user 105 1997-01-21 19:42 blues
3835 -rw-r--r-- melissa user 33 1997-01-20 15:34 rock
3836 $ tar -tvf jazzfolk.tar
3837 -rw-r--r-- melissa user 20 1996-09-23 16:44 folk
3838 -rw-r--r-- melissa user 65 1997-01-30 14:15 jazz
3840 We can concatenate these two archives with `tar':
3843 $ tar --concatenate --file=bluesrock.tar jazzfolk.tar
3845 If you now list the contents of the `bluesrock.tar', you will see
3846 that now it also contains the archive members of `jazzfolk.tar':
3848 $ tar --list --file=bluesrock.tar
3854 When you use `--concatenate', the source and target archives must
3855 already exist and must have been created using compatible format
3856 parameters. Notice, that `tar' does not check whether the archives it
3857 concatenates have compatible formats, it does not even check if the
3858 files are really tar archives.
3860 Like `--append' (`-r'), this operation cannot be performed on some
3861 tape drives, due to deficiencies in the formats those tape drives use.
3863 It may seem more intuitive to you to want or try to use `cat' to
3864 concatenate two archives instead of using the `--concatenate'
3865 operation; after all, `cat' is the utility for combining files.
3867 However, `tar' archives incorporate an end-of-file marker which must
3868 be removed if the concatenated archives are to be read properly as one
3869 archive. `--concatenate' removes the end-of-archive marker from the
3870 target archive before each new archive is appended. If you use `cat'
3871 to combine the archives, the result will not be a valid `tar' format
3872 archive. If you need to retrieve files from an archive that was added
3873 to using the `cat' utility, use the `--ignore-zeros' (`-i') option.
3874 *Note Ignore Zeros::, for further information on dealing with archives
3875 improperly combined using the `cat' shell utility.
3877 ---------- Footnotes ----------
3879 (1) This can cause multiple members to have the same name, for
3880 information on how this affects reading the archive, *note multiple::.
3883 File: tar.info, Node: delete, Next: compare, Prev: concatenate, Up: Advanced tar
3885 4.2.5 Removing Archive Members Using `--delete'
3886 -----------------------------------------------
3888 _(This message will disappear, once this node revised.)_
3890 You can remove members from an archive by using the `--delete' option.
3891 Specify the name of the archive with `--file' (`-f') and then specify
3892 the names of the members to be deleted; if you list no member names,
3893 nothing will be deleted. The `--verbose' option will cause `tar' to
3894 print the names of the members as they are deleted. As with
3895 `--extract', you must give the exact member names when using `tar
3896 --delete'. `--delete' will remove all versions of the named file from
3897 the archive. The `--delete' operation can run very slowly.
3899 Unlike other operations, `--delete' has no short form.
3901 This operation will rewrite the archive. You can only use
3902 `--delete' on an archive if the archive device allows you to write to
3903 any point on the media, such as a disk; because of this, it does not
3904 work on magnetic tapes. Do not try to delete an archive member from a
3905 magnetic tape; the action will not succeed, and you will be likely to
3906 scramble the archive and damage your tape. There is no safe way
3907 (except by completely re-writing the archive) to delete files from most
3908 kinds of magnetic tape. *Note Media::.
3910 To delete all versions of the file `blues' from the archive
3911 `collection.tar' in the `practice' directory, make sure you are in that
3912 directory, and then,
3914 $ tar --list --file=collection.tar
3919 $ tar --delete --file=collection.tar blues
3920 $ tar --list --file=collection.tar
3926 The `--delete' option has been reported to work properly when `tar'
3927 acts as a filter from `stdin' to `stdout'.
3930 File: tar.info, Node: compare, Prev: delete, Up: Advanced tar
3932 4.2.6 Comparing Archive Members with the File System
3933 ----------------------------------------------------
3935 _(This message will disappear, once this node revised.)_
3937 The `--compare' (`-d'), or `--diff' operation compares specified
3938 archive members against files with the same names, and then reports
3939 differences in file size, mode, owner, modification date and contents.
3940 You should _only_ specify archive member names, not file names. If you
3941 do not name any members, then `tar' will compare the entire archive.
3942 If a file is represented in the archive but does not exist in the file
3943 system, `tar' reports a difference.
3945 You have to specify the record size of the archive when modifying an
3946 archive with a non-default record size.
3948 `tar' ignores files in the file system that do not have
3949 corresponding members in the archive.
3951 The following example compares the archive members `rock', `blues'
3952 and `funk' in the archive `bluesrock.tar' with files of the same name
3953 in the file system. (Note that there is no file, `funk'; `tar' will
3954 report an error message.)
3956 $ tar --compare --file=bluesrock.tar rock blues funk
3959 tar: funk not found in archive
3961 The spirit behind the `--compare' (`--diff', `-d') option is to
3962 check whether the archive represents the current state of files on
3963 disk, more than validating the integrity of the archive media. For
3964 this later goal, *Note verify::.
3967 File: tar.info, Node: create options, Next: extract options, Prev: Advanced tar, Up: operations
3969 4.3 Options Used by `--create'
3970 ==============================
3972 The previous chapter described the basics of how to use `--create'
3973 (`-c') to create an archive from a set of files. *Note create::. This
3974 section described advanced options to be used with `--create'.
3978 * override:: Overriding File Metadata.
3979 * Ignore Failed Read::
3982 File: tar.info, Node: override, Next: Ignore Failed Read, Up: create options
3984 4.3.1 Overriding File Metadata
3985 ------------------------------
3987 As described above, a `tar' archive keeps, for each member it contains,
3988 its "metadata", such as modification time, mode and ownership of the
3989 file. GNU `tar' allows to replace these data with other values when
3990 adding files to the archive. The options described in this section
3991 affect creation of archives of any type. For POSIX archives, see also
3992 *note PAX keywords::, for additional ways of controlling metadata,
3993 stored in the archive.
3995 `--mode=PERMISSIONS'
3996 When adding files to an archive, `tar' will use PERMISSIONS for
3997 the archive members, rather than the permissions from the files.
3998 PERMISSIONS can be specified either as an octal number or as
3999 symbolic permissions, like with `chmod' (*Note Permissions:
4000 (fileutils)File permissions. This reference also has useful
4001 information for those not being overly familiar with the UNIX
4002 permission system). Using latter syntax allows for more
4003 flexibility. For example, the value `a+rw' adds read and write
4004 permissions for everybody, while retaining executable bits on
4005 directories or on any other file already marked as executable:
4007 $ tar -c -f archive.tar --mode='a+rw' .
4010 When adding files to an archive, `tar' will use DATE as the
4011 modification time of members when creating archives, instead of
4012 their actual modification times. The argument DATE can be either
4013 a textual date representation in almost arbitrary format (*note
4014 Date input formats::) or a name of the existing file, starting
4015 with `/' or `.'. In the latter case, the modification time of
4016 that file will be used.
4018 The following example will set the modification date to 00:00:00
4019 UTC, January 1, 1970:
4021 $ tar -c -f archive.tar --mtime='1970-01-01' .
4023 When used with `--verbose' (*note verbose tutorial::) GNU `tar'
4024 will try to convert the specified date back to its textual
4025 representation and compare it with the one given with `--mtime'
4026 options. If the two dates differ, `tar' will print a warning
4027 saying what date it will use. This is to help user ensure he is
4028 using the right date.
4032 $ tar -c -f archive.tar -v --mtime=yesterday .
4033 tar: Option --mtime: Treating date `yesterday' as 2006-06-20
4038 Specifies that `tar' should use USER as the owner of members when
4039 creating archives, instead of the user associated with the source
4040 file. The argument USER can be either an existing user symbolic
4041 name, or a decimal numeric user ID.
4043 There is no value indicating a missing number, and `0' usually
4044 means `root'. Some people like to force `0' as the value to offer
4045 in their distributions for the owner of files, because the `root'
4046 user is anonymous anyway, so that might as well be the owner of
4047 anonymous archives. For example:
4049 $ tar -c -f archive.tar --owner=0 .
4051 $ tar -c -f archive.tar --owner=root .
4054 Files added to the `tar' archive will have a group ID of GROUP,
4055 rather than the group from the source file. The argument GROUP
4056 can be either an existing group symbolic name, or a decimal
4060 File: tar.info, Node: Ignore Failed Read, Prev: override, Up: create options
4062 4.3.2 Ignore Fail Read
4063 ----------------------
4065 `--ignore-failed-read'
4066 Do not exit with nonzero on unreadable files or directories.
4069 File: tar.info, Node: extract options, Next: backup, Prev: create options, Up: operations
4071 4.4 Options Used by `--extract'
4072 ===============================
4074 _(This message will disappear, once this node revised.)_
4076 The previous chapter showed how to use `--extract' to extract an
4077 archive into the file system. Various options cause `tar' to extract
4078 more information than just file contents, such as the owner, the
4079 permissions, the modification date, and so forth. This section
4080 presents options to be used with `--extract' when certain special
4081 considerations arise. You may review the information presented in
4082 *note extract:: for more basic information about the `--extract'
4087 * Reading:: Options to Help Read Archives
4088 * Writing:: Changing How `tar' Writes Files
4089 * Scarce:: Coping with Scarce Resources
4092 File: tar.info, Node: Reading, Next: Writing, Up: extract options
4094 4.4.1 Options to Help Read Archives
4095 -----------------------------------
4097 _(This message will disappear, once this node revised.)_
4099 Normally, `tar' will request data in full record increments from an
4100 archive storage device. If the device cannot return a full record,
4101 `tar' will report an error. However, some devices do not always return
4102 full records, or do not require the last record of an archive to be
4103 padded out to the next record boundary. To keep reading until you
4104 obtain a full record, or to accept an incomplete record if it contains
4105 an end-of-archive marker, specify the `--read-full-records' (`-B')
4106 option in conjunction with the `--extract' or `--list' operations.
4109 The `--read-full-records' (`-B') option is turned on by default when
4110 `tar' reads an archive from standard input, or from a remote machine.
4111 This is because on BSD Unix systems, attempting to read a pipe returns
4112 however much happens to be in the pipe, even if it is less than was
4113 requested. If this option were not enabled, `tar' would fail as soon
4114 as it read an incomplete record from the pipe.
4116 If you're not sure of the blocking factor of an archive, you can
4117 read the archive by specifying `--read-full-records' (`-B') and
4118 `--blocking-factor=512-SIZE' (`-b 512-SIZE'), using a blocking factor
4119 larger than what the archive uses. This lets you avoid having to
4120 determine the blocking factor of an archive. *Note Blocking Factor::.
4124 * read full records::
4128 File: tar.info, Node: read full records, Next: Ignore Zeros, Up: Reading
4130 Reading Full Records
4131 ....................
4133 `--read-full-records'
4136 Use in conjunction with `--extract' (`--get', `-x') to read an
4137 archive which contains incomplete records, or one which has a
4138 blocking factor less than the one specified.
4141 File: tar.info, Node: Ignore Zeros, Prev: read full records, Up: Reading
4143 Ignoring Blocks of Zeros
4144 ........................
4146 Normally, `tar' stops reading when it encounters a block of zeros
4147 between file entries (which usually indicates the end of the archive).
4148 `--ignore-zeros' (`-i') allows `tar' to completely read an archive
4149 which contains a block of zeros before the end (i.e., a damaged
4150 archive, or one that was created by concatenating several archives
4153 The `--ignore-zeros' (`-i') option is turned off by default because
4154 many versions of `tar' write garbage after the end-of-archive entry,
4155 since that part of the media is never supposed to be read. GNU `tar'
4156 does not write after the end of an archive, but seeks to maintain
4157 compatibility among archiving utilities.
4161 To ignore blocks of zeros (i.e., end-of-archive entries) which may
4162 be encountered while reading an archive. Use in conjunction with
4163 `--extract' or `--list'.
4166 File: tar.info, Node: Writing, Next: Scarce, Prev: Reading, Up: extract options
4168 4.4.2 Changing How `tar' Writes Files
4169 -------------------------------------
4171 _(This message will disappear, once this node revised.)_
4175 * Dealing with Old Files::
4176 * Overwrite Old Files::
4178 * Keep Newer Files::
4180 * Recursive Unlink::
4181 * Data Modification Times::
4182 * Setting Access Permissions::
4183 * Directory Modification Times and Permissions::
4184 * Writing to Standard Output::
4185 * Writing to an External Program::
4189 File: tar.info, Node: Dealing with Old Files, Next: Overwrite Old Files, Up: Writing
4191 Options Controlling the Overwriting of Existing Files
4192 .....................................................
4194 When extracting files, if `tar' discovers that the extracted file
4195 already exists, it normally replaces the file by removing it before
4196 extracting it, to prevent confusion in the presence of hard or symbolic
4197 links. (If the existing file is a symbolic link, it is removed, not
4198 followed.) However, if a directory cannot be removed because it is
4199 nonempty, `tar' normally overwrites its metadata (ownership,
4200 permission, etc.). The `--overwrite-dir' option enables this default
4201 behavior. To be more cautious and preserve the metadata of such a
4202 directory, use the `--no-overwrite-dir' option.
4204 To be even more cautious and prevent existing files from being
4205 replaced, use the `--keep-old-files' (`-k') option. It causes `tar' to
4206 refuse to replace or update a file that already exists, i.e., a file
4207 with the same name as an archive member prevents extraction of that
4208 archive member. Instead, it reports an error.
4210 To be more aggressive about altering existing files, use the
4211 `--overwrite' option. It causes `tar' to overwrite existing files and
4212 to follow existing symbolic links when extracting.
4214 Some people argue that GNU `tar' should not hesitate to overwrite
4215 files with other files when extracting. When extracting a `tar'
4216 archive, they expect to see a faithful copy of the state of the file
4217 system when the archive was created. It is debatable that this would
4218 always be a proper behavior. For example, suppose one has an archive
4219 in which `usr/local' is a link to `usr/local2'. Since then, maybe the
4220 site removed the link and renamed the whole hierarchy from
4221 `/usr/local2' to `/usr/local'. Such things happen all the time. I
4222 guess it would not be welcome at all that GNU `tar' removes the whole
4223 hierarchy just to make room for the link to be reinstated (unless it
4224 _also_ simultaneously restores the full `/usr/local2', of course!) GNU
4225 `tar' is indeed able to remove a whole hierarchy to reestablish a
4226 symbolic link, for example, but _only if_ `--recursive-unlink' is
4227 specified to allow this behavior. In any case, single files are
4230 Finally, the `--unlink-first' (`-U') option can improve performance
4231 in some cases by causing `tar' to remove files unconditionally before
4235 File: tar.info, Node: Overwrite Old Files, Next: Keep Old Files, Prev: Dealing with Old Files, Up: Writing
4241 Overwrite existing files and directory metadata when extracting
4242 files from an archive.
4244 This causes `tar' to write extracted files into the file system
4245 without regard to the files already on the system; i.e., files
4246 with the same names as archive members are overwritten when the
4247 archive is extracted. It also causes `tar' to extract the
4248 ownership, permissions, and time stamps onto any preexisting files
4249 or directories. If the name of a corresponding file name is a
4250 symbolic link, the file pointed to by the symbolic link will be
4251 overwritten instead of the symbolic link itself (if this is
4252 possible). Moreover, special devices, empty directories and even
4253 symbolic links are automatically removed if they are in the way of
4256 Be careful when using the `--overwrite' option, particularly when
4257 combined with the `--absolute-names' (`-P') option, as this
4258 combination can change the contents, ownership or permissions of
4259 any file on your system. Also, many systems do not take kindly to
4260 overwriting files that are currently being executed.
4263 Overwrite the metadata of directories when extracting files from an
4264 archive, but remove other files before extracting.
4267 File: tar.info, Node: Keep Old Files, Next: Keep Newer Files, Prev: Overwrite Old Files, Up: Writing
4274 Do not replace existing files from archive. The
4275 `--keep-old-files' (`-k') option prevents `tar' from replacing
4276 existing files with files with the same name from the archive. The
4277 `--keep-old-files' option is meaningless with `--list' (`-t').
4278 Prevents `tar' from replacing files in the file system during
4282 File: tar.info, Node: Keep Newer Files, Next: Unlink First, Prev: Keep Old Files, Up: Writing
4287 `--keep-newer-files'
4288 Do not replace existing files that are newer than their archive
4289 copies. This option is meaningless with `--list' (`-t').
4292 File: tar.info, Node: Unlink First, Next: Recursive Unlink, Prev: Keep Newer Files, Up: Writing
4299 Remove files before extracting over them. This can make `tar' run
4300 a bit faster if you know in advance that the extracted files all
4301 need to be removed. Normally this option slows `tar' down
4302 slightly, so it is disabled by default.
4305 File: tar.info, Node: Recursive Unlink, Next: Data Modification Times, Prev: Unlink First, Up: Writing
4310 `--recursive-unlink'
4311 When this option is specified, try removing files and directory
4312 hierarchies before extracting over them. _This is a dangerous
4315 If you specify the `--recursive-unlink' option, `tar' removes
4316 _anything_ that keeps you from extracting a file as far as current
4317 permissions will allow it. This could include removal of the contents
4318 of a full directory hierarchy.
4321 File: tar.info, Node: Data Modification Times, Next: Setting Access Permissions, Prev: Recursive Unlink, Up: Writing
4323 Setting Data Modification Times
4324 ...............................
4326 Normally, `tar' sets the data modification times of extracted files to
4327 the corresponding times recorded for the files in the archive, but
4328 limits the permissions of extracted files by the current `umask'
4331 To set the data modification times of extracted files to the time
4332 when the files were extracted, use the `--touch' (`-m') option in
4333 conjunction with `--extract' (`--get', `-x').
4337 Sets the data modification time of extracted archive members to
4338 the time they were extracted, not the time recorded for them in
4339 the archive. Use in conjunction with `--extract' (`--get', `-x').
4342 File: tar.info, Node: Setting Access Permissions, Next: Directory Modification Times and Permissions, Prev: Data Modification Times, Up: Writing
4344 Setting Access Permissions
4345 ..........................
4347 To set the modes (access permissions) of extracted files to those
4348 recorded for those files in the archive, use `--same-permissions' in
4349 conjunction with the `--extract' (`--get', `-x') operation.
4351 `--preserve-permissions'
4352 `--same-permissions'
4354 Set modes of extracted archive members to those recorded in the
4355 archive, instead of current umask settings. Use in conjunction
4356 with `--extract' (`--get', `-x').
4359 File: tar.info, Node: Directory Modification Times and Permissions, Next: Writing to Standard Output, Prev: Setting Access Permissions, Up: Writing
4361 Directory Modification Times and Permissions
4362 ............................................
4364 After successfully extracting a file member, GNU `tar' normally
4365 restores its permissions and modification times, as described in the
4366 previous sections. This cannot be done for directories, because after
4367 extracting a directory `tar' will almost certainly extract files into
4368 that directory and this will cause the directory modification time to
4369 be updated. Moreover, restoring that directory permissions may not
4370 permit file creation within it. Thus, restoring directory permissions
4371 and modification times must be delayed at least until all files have
4372 been extracted into that directory. GNU `tar' restores directories
4373 using the following approach.
4375 The extracted directories are created with the mode specified in the
4376 archive, as modified by the umask of the user, which gives sufficient
4377 permissions to allow file creation. The meta-information about the
4378 directory is recorded in the temporary list of directories. When
4379 preparing to extract next archive member, GNU `tar' checks if the
4380 directory prefix of this file contains the remembered directory. If it
4381 does not, the program assumes that all files have been extracted into
4382 that directory, restores its modification time and permissions and
4383 removes its entry from the internal list. This approach allows to
4384 correctly restore directory meta-information in the majority of cases,
4385 while keeping memory requirements sufficiently small. It is based on
4386 the fact, that most `tar' archives use the predefined order of members:
4387 first the directory, then all the files and subdirectories in that
4390 However, this is not always true. The most important exception are
4391 incremental archives (*note Incremental Dumps::). The member order in
4392 an incremental archive is reversed: first all directory members are
4393 stored, followed by other (non-directory) members. So, when extracting
4394 from incremental archives, GNU `tar' alters the above procedure. It
4395 remembers all restored directories, and restores their meta-data only
4396 after the entire archive has been processed. Notice, that you do not
4397 need to specify any special options for that, as GNU `tar'
4398 automatically detects archives in incremental format.
4400 There may be cases, when such processing is required for normal
4401 archives too. Consider the following example:
4403 $ tar --no-recursion -cvf archive \
4404 foo foo/file1 bar bar/file foo/file2
4411 During the normal operation, after encountering `bar' GNU `tar' will
4412 assume that all files from the directory `foo' were already extracted
4413 and will therefore restore its timestamp and permission bits. However,
4414 after extracting `foo/file2' the directory timestamp will be offset
4417 To correctly restore directory meta-information in such cases, use
4418 `delay-directory-restore' command line option:
4420 `--delay-directory-restore'
4421 Delays restoring of the modification times and permissions of
4422 extracted directories until the end of extraction. This way,
4423 correct meta-information is restored even if the archive has
4424 unusual member ordering.
4426 `--no-delay-directory-restore'
4427 Cancel the effect of the previous `--delay-directory-restore'.
4428 Use this option if you have used `--delay-directory-restore' in
4429 `TAR_OPTIONS' variable (*note TAR_OPTIONS::) and wish to
4430 temporarily disable it.
4433 File: tar.info, Node: Writing to Standard Output, Next: Writing to an External Program, Prev: Directory Modification Times and Permissions, Up: Writing
4435 Writing to Standard Output
4436 ..........................
4438 To write the extracted files to the standard output, instead of
4439 creating the files on the file system, use `--to-stdout' (`-O') in
4440 conjunction with `--extract' (`--get', `-x'). This option is useful if
4441 you are extracting files to send them through a pipe, and do not need to
4442 preserve them in the file system. If you extract multiple members,
4443 they appear on standard output concatenated, in the order they are
4444 found in the archive.
4448 Writes files to the standard output. Use only in conjunction with
4449 `--extract' (`--get', `-x'). When this option is used, instead of
4450 creating the files specified, `tar' writes the contents of the
4451 files extracted to its standard output. This may be useful if you
4452 are only extracting the files in order to send them through a
4453 pipe. This option is meaningless with `--list' (`-t').
4455 This can be useful, for example, if you have a tar archive containing
4456 a big file and don't want to store the file on disk before processing
4457 it. You can use a command like this:
4459 tar -xOzf foo.tgz bigfile | process
4461 or even like this if you want to process the concatenation of the
4464 tar -xOzf foo.tgz bigfile1 bigfile2 | process
4466 However, `--to-command' may be more convenient for use with multiple
4467 files. See the next section.
4470 File: tar.info, Node: Writing to an External Program, Next: remove files, Prev: Writing to Standard Output, Up: Writing
4472 Writing to an External Program
4473 ..............................
4475 You can instruct `tar' to send the contents of each extracted file to
4476 the standard input of an external program:
4478 `--to-command=COMMAND'
4479 Extract files and pipe their contents to the standard input of
4480 COMMAND. When this option is used, instead of creating the files
4481 specified, `tar' invokes COMMAND and pipes the contents of the
4482 files to its standard output. COMMAND may contain command line
4483 arguments. The program is executed via `sh -c'. Notice, that
4484 COMMAND is executed once for each regular file extracted.
4485 Non-regular files (directories, etc.) are ignored when this option
4488 The command can obtain the information about the file it processes
4489 from the following environment variables:
4492 Type of the file. It is a single letter with the following meaning:
4501 Currently only regular files are supported.
4504 File mode, an octal number.
4507 The name of the file.
4510 Name of the file as stored in the archive.
4513 Name of the file owner.
4516 Name of the file owner group.
4519 Time of last access. It is a decimal number, representing seconds
4520 since the epoch. If the archive provides times with nanosecond
4521 precision, the nanoseconds are appended to the timestamp after a
4525 Time of last modification.
4528 Time of last status change.
4534 UID of the file owner.
4537 GID of the file owner.
4539 In addition to these variables, `TAR_VERSION' contains the GNU `tar'
4542 If COMMAND exits with a non-0 status, `tar' will print an error
4543 message similar to the following:
4545 tar: 2345: Child returned status 1
4547 Here, `2345' is the PID of the finished process.
4549 If this behavior is not wanted, use `--ignore-command-error':
4551 `--ignore-command-error'
4552 Ignore exit codes of subprocesses. Notice that if the program
4553 exits on signal or otherwise terminates abnormally, the error
4554 message will be printed even if this option is used.
4556 `--no-ignore-command-error'
4557 Cancel the effect of any previous `--ignore-command-error' option.
4558 This option is useful if you have set `--ignore-command-error' in
4559 `TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to temporarily cancel
4563 File: tar.info, Node: remove files, Prev: Writing to an External Program, Up: Writing
4569 Remove files after adding them to the archive.
4572 File: tar.info, Node: Scarce, Prev: Writing, Up: extract options
4574 4.4.3 Coping with Scarce Resources
4575 ----------------------------------
4577 _(This message will disappear, once this node revised.)_
4585 File: tar.info, Node: Starting File, Next: Same Order, Up: Scarce
4590 `--starting-file=NAME'
4592 Starts an operation in the middle of an archive. Use in
4593 conjunction with `--extract' (`--get', `-x') or `--list' (`-t').
4595 If a previous attempt to extract files failed due to lack of disk
4596 space, you can use `--starting-file=NAME' (`-K NAME') to start
4597 extracting only after member NAME of the archive. This assumes, of
4598 course, that there is now free space, or that you are now extracting
4599 into a different file system. (You could also choose to suspend `tar',
4600 remove unnecessary files from the file system, and then restart the
4601 same `tar' operation. In this case, `--starting-file' is not necessary.
4602 *Note Incremental Dumps::, *Note interactive::, and *note exclude::.)
4605 File: tar.info, Node: Same Order, Prev: Starting File, Up: Scarce
4613 To process large lists of file names on machines with small
4614 amounts of memory. Use in conjunction with `--compare' (`--diff',
4615 `-d'), `--list' (`-t') or `--extract' (`--get', `-x').
4617 The `--same-order' (`--preserve-order', `-s') option tells `tar'
4618 that the list of file names to be listed or extracted is sorted in the
4619 same order as the files in the archive. This allows a large list of
4620 names to be used, even on a small machine that would not otherwise be
4621 able to hold all the names in memory at the same time. Such a sorted
4622 list can easily be created by running `tar -t' on the archive and
4625 This option is probably never needed on modern computer systems.
4628 File: tar.info, Node: backup, Next: Applications, Prev: extract options, Up: operations
4633 GNU `tar' offers options for making backups of files before writing new
4634 versions. These options control the details of these backups. They
4635 may apply to the archive itself before it is created or rewritten, as
4636 well as individual extracted members. Other GNU programs (`cp',
4637 `install', `ln', and `mv', for example) offer similar options.
4639 Backup options may prove unexpectedly useful when extracting archives
4640 containing many members having identical name, or when extracting
4641 archives on systems having file name limitations, making different
4642 members appear has having similar names through the side-effect of name
4643 truncation. (This is true only if we have a good scheme for truncated
4644 backup names, which I'm not sure at all: I suspect work is needed in
4645 this area.) When any existing file is backed up before being
4646 overwritten by extraction, then clashing files are automatically be
4647 renamed to be unique, and the true name is kept for only the last file
4648 of a series of clashing files. By using verbose mode, users may track
4649 exactly what happens.
4651 At the detail level, some decisions are still experimental, and may
4652 change in the future, we are waiting comments from our users. So,
4653 please do not learn to depend blindly on the details of the backup
4654 features. For example, currently, directories themselves are never
4655 renamed through using these options, so, extracting a file over a
4656 directory still has good chances to fail. Also, backup options apply
4657 to created archives, not only to extracted members. For created
4658 archives, backups will not be attempted when the archive is a block or
4659 character device, or when it refers to a remote file.
4661 For the sake of simplicity and efficiency, backups are made by
4662 renaming old files prior to creation or extraction, and not by copying.
4663 The original name is restored if the file creation fails. If a
4664 failure occurs after a partial extraction of a file, both the backup
4665 and the partially extracted file are kept.
4668 Back up files that are about to be overwritten or removed.
4669 Without this option, the original versions are destroyed.
4671 Use METHOD to determine the type of backups made. If METHOD is
4672 not specified, use the value of the `VERSION_CONTROL' environment
4673 variable. And if `VERSION_CONTROL' is not set, use the `existing'
4676 This option corresponds to the Emacs variable `version-control';
4677 the same values for METHOD are accepted as in Emacs. This option
4678 also allows more descriptive names. The valid METHODs are:
4682 Always make numbered backups.
4686 Make numbered backups of files that already have them, simple
4687 backups of the others.
4691 Always make simple backups.
4695 Append SUFFIX to each backup file made with `--backup'. If this
4696 option is not specified, the value of the `SIMPLE_BACKUP_SUFFIX'
4697 environment variable is used. And if `SIMPLE_BACKUP_SUFFIX' is not
4698 set, the default is `~', just as in Emacs.
4702 File: tar.info, Node: Applications, Next: looking ahead, Prev: backup, Up: operations
4704 4.6 Notable `tar' Usages
4705 ========================
4707 _(This message will disappear, once this node revised.)_
4709 You can easily use archive files to transport a group of files from one
4710 system to another: put all relevant files into an archive on one
4711 computer system, transfer the archive to another system, and extract
4712 the contents there. The basic transfer medium might be magnetic tape,
4713 Internet FTP, or even electronic mail (though you must encode the
4714 archive with `uuencode' in order to transport it properly by mail).
4715 Both machines do not have to use the same operating system, as long as
4716 they both support the `tar' program.
4718 For example, here is how you might copy a directory's contents from
4719 one disk to another, while preserving the dates, modes, owners and
4720 link-structure of all the files therein. In this case, the transfer
4721 medium is a "pipe", which is one a Unix redirection mechanism:
4723 $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)
4725 You can avoid subshells by using `-C' option:
4727 $ tar -C sourcedir -cf - . | tar -C targetdir -xf -
4729 The command also works using short option forms:
4731 $ (cd sourcedir; tar --create --file=- . ) \
4732 | (cd targetdir; tar --extract --file=-)
4734 $ tar --directory sourcedir --create --file=- . ) \
4735 | tar --directory targetdir --extract --file=-
4737 This is one of the easiest methods to transfer a `tar' archive.
4740 File: tar.info, Node: looking ahead, Prev: Applications, Up: operations
4742 4.7 Looking Ahead: The Rest of this Manual
4743 ==========================================
4745 You have now seen how to use all eight of the operations available to
4746 `tar', and a number of the possible options. The next chapter explains
4747 how to choose and change file and archive names, how to use files to
4748 store names of other files which you can then call as arguments to
4749 `tar' (this can help you save time if you expect to archive the same
4750 list of files a number of times), and so forth.
4752 If there are too many files to conveniently list on the command line,
4753 you can list the names in a file, and `tar' will read that file. *Note
4756 There are various ways of causing `tar' to skip over some files, and
4757 not archive them. *Note Choosing::.
4760 File: tar.info, Node: Backups, Next: Choosing, Prev: operations, Up: Top
4762 5 Performing Backups and Restoring Files
4763 ****************************************
4765 _(This message will disappear, once this node revised.)_
4767 GNU `tar' is distributed along with the scripts which the Free Software
4768 Foundation uses for performing backups. There is no corresponding
4769 scripts available yet for doing restoration of files. Even if there is
4770 a good chance those scripts may be satisfying to you, they are not the
4771 only scripts or methods available for doing backups and restore. You
4772 may well create your own, or use more sophisticated packages dedicated
4775 Some users are enthusiastic about `Amanda' (The Advanced Maryland
4776 Automatic Network Disk Archiver), a backup system developed by James da
4777 Silva `jds@cs.umd.edu' and available on many Unix systems. This is
4778 free software, and it is available at these places:
4780 http://www.cs.umd.edu/projects/amanda/amanda.html
4781 ftp://ftp.cs.umd.edu/pub/amanda
4783 This chapter documents both the provided shell scripts and `tar'
4784 options which are more specific to usage as a backup tool.
4786 To "back up" a file system means to create archives that contain all
4787 the files in that file system. Those archives can then be used to
4788 restore any or all of those files (for instance if a disk crashes or a
4789 file is accidentally deleted). File system "backups" are also called
4794 * Full Dumps:: Using `tar' to Perform Full Dumps
4795 * Incremental Dumps:: Using `tar' to Perform Incremental Dumps
4796 * Backup Levels:: Levels of Backups
4797 * Backup Parameters:: Setting Parameters for Backups and Restoration
4798 * Scripted Backups:: Using the Backup Scripts
4799 * Scripted Restoration:: Using the Restore Script
4802 File: tar.info, Node: Full Dumps, Next: Incremental Dumps, Up: Backups
4804 5.1 Using `tar' to Perform Full Dumps
4805 =====================================
4807 _(This message will disappear, once this node revised.)_
4809 Full dumps should only be made when no other people or programs are
4810 modifying files in the file system. If files are modified while `tar'
4811 is making the backup, they may not be stored properly in the archive,
4812 in which case you won't be able to restore them if you have to. (Files
4813 not being modified are written with no trouble, and do not corrupt the
4816 You will want to use the `--label=ARCHIVE-LABEL' (`-V
4817 ARCHIVE-LABEL') option to give the archive a volume label, so you can
4818 tell what this archive is even if the label falls off the tape, or
4821 Unless the file system you are dumping is guaranteed to fit on one
4822 volume, you will need to use the `--multi-volume' (`-M') option. Make
4823 sure you have enough tapes on hand to complete the backup.
4825 If you want to dump each file system separately you will need to use
4826 the `--one-file-system' option to prevent `tar' from crossing file
4827 system boundaries when storing (sub)directories.
4829 The `--incremental' (`-G') (*note Incremental Dumps::) option is not
4830 needed, since this is a complete copy of everything in the file system,
4831 and a full restore from this backup would only be done onto a completely
4834 Unless you are in a hurry, and trust the `tar' program (and your
4835 tapes), it is a good idea to use the `--verify' (`-W') option, to make
4836 sure your files really made it onto the dump properly. This will also
4837 detect cases where the file was modified while (or just after) it was
4838 being archived. Not all media (notably cartridge tapes) are capable of
4839 being verified, unfortunately.
4842 File: tar.info, Node: Incremental Dumps, Next: Backup Levels, Prev: Full Dumps, Up: Backups
4844 5.2 Using `tar' to Perform Incremental Dumps
4845 ============================================
4847 "Incremental backup" is a special form of GNU `tar' archive that stores
4848 additional metadata so that exact state of the file system can be
4849 restored when extracting the archive.
4851 GNU `tar' currently offers two options for handling incremental
4852 backups: `--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') and
4853 `--incremental' (`-G').
4855 The option `--listed-incremental' instructs tar to operate on an
4856 incremental archive with additional metadata stored in a standalone
4857 file, called a "snapshot file". The purpose of this file is to help
4858 determine which files have been changed, added or deleted since the
4859 last backup, so that the next incremental backup will contain only
4860 modified files. The name of the snapshot file is given as an argument
4863 `--listed-incremental=FILE'
4865 Handle incremental backups with snapshot data in FILE.
4867 To create an incremental backup, you would use
4868 `--listed-incremental' together with `--create' (*note create::). For
4872 --file=archive.1.tar \
4873 --listed-incremental=/var/log/usr.snar \
4876 This will create in `archive.1.tar' an incremental backup of the
4877 `/usr' file system, storing additional metadata in the file
4878 `/var/log/usr.snar'. If this file does not exist, it will be created.
4879 The created archive will then be a "level 0 backup"; please see the
4880 next section for more on backup levels.
4882 Otherwise, if the file `/var/log/usr.snar' exists, it determines
4883 which files are modified. In this case only these files will be stored
4884 in the archive. Suppose, for example, that after running the above
4885 command, you delete file `/usr/doc/old' and create directory
4886 `/usr/local/db' with the following contents:
4892 Some time later you create another incremental backup. You will
4896 --file=archive.2.tar \
4897 --listed-incremental=/var/log/usr.snar \
4899 tar: usr/local/db: Directory is new
4904 The created archive `archive.2.tar' will contain only these three
4905 members. This archive is called a "level 1 backup". Notice that
4906 `/var/log/usr.snar' will be updated with the new data, so if you plan
4907 to create more `level 1' backups, it is necessary to create a working
4908 copy of the snapshot file before running `tar'. The above example will
4909 then be modified as follows:
4911 $ cp /var/log/usr.snar /var/log/usr.snar-1
4913 --file=archive.2.tar \
4914 --listed-incremental=/var/log/usr.snar-1 \
4917 Incremental dumps depend crucially on time stamps, so the results are
4918 unreliable if you modify a file's time stamps during dumping (e.g.,
4919 with the `--atime-preserve=replace' option), or if you set the clock
4922 Metadata stored in snapshot files include device numbers, which,
4923 obviously are supposed to be a non-volatile values. However, it turns
4924 out that NFS devices have undependable values when an automounter gets
4925 in the picture. This can lead to a great deal of spurious redumping in
4926 incremental dumps, so it is somewhat useless to compare two NFS devices
4927 numbers over time. The solution implemented currently is to considers
4928 all NFS devices as being equal when it comes to comparing directories;
4929 this is fairly gross, but there does not seem to be a better way to go.
4931 Apart from using NFS, there are a number of cases where relying on
4932 device numbers can cause spurious redumping of unmodified files. For
4933 example, this occurs when archiving LVM snapshot volumes. To avoid
4934 this, use `--no-check-device' option:
4937 Do not rely on device numbers when preparing a list of changed
4938 files for an incremental dump.
4941 Use device numbers when preparing a list of changed files for an
4942 incremental dump. This is the default behavior. The purpose of
4943 this option is to undo the effect of the `--no-check-device' if it
4944 was given in `TAR_OPTIONS' environment variable (*note
4947 There is also another way to cope with changing device numbers. It
4948 is described in detail in *note Fixing Snapshot Files::.
4950 Note that incremental archives use `tar' extensions and may not be
4951 readable by non-GNU versions of the `tar' program.
4953 To extract from the incremental dumps, use `--listed-incremental'
4954 together with `--extract' option (*note extracting files::). In this
4955 case, `tar' does not need to access snapshot file, since all the data
4956 necessary for extraction are stored in the archive itself. So, when
4957 extracting, you can give whatever argument to `--listed-incremental',
4958 the usual practice is to use `--listed-incremental=/dev/null'.
4959 Alternatively, you can use `--incremental', which needs no arguments.
4960 In general, `--incremental' (`-G') can be used as a shortcut for
4961 `--listed-incremental' when listing or extracting incremental backups
4962 (for more information, regarding this option, *note incremental-op::).
4964 When extracting from the incremental backup GNU `tar' attempts to
4965 restore the exact state the file system had when the archive was
4966 created. In particular, it will _delete_ those files in the file
4967 system that did not exist in their directories when the archive was
4968 created. If you have created several levels of incremental files, then
4969 in order to restore the exact contents the file system had when the
4970 last level was created, you will need to restore from all backups in
4971 turn. Continuing our example, to restore the state of `/usr' file
4972 system, one would do(1):
4975 --listed-incremental=/dev/null \
4976 --file archive.1.tar
4978 --listed-incremental=/dev/null \
4979 --file archive.2.tar
4981 To list the contents of an incremental archive, use `--list' (*note
4982 list::), as usual. To obtain more information about the archive, use
4983 `--listed-incremental' or `--incremental' combined with two `--verbose'
4986 tar --list --incremental --verbose --verbose archive.tar
4988 This command will print, for each directory in the archive, the list
4989 of files in that directory at the time the archive was created. This
4990 information is put out in a format which is both human-readable and
4991 unambiguous for a program: each file name is printed as
4995 where X is a letter describing the status of the file: `Y' if the file
4996 is present in the archive, `N' if the file is not included in the
4997 archive, or a `D' if the file is a directory (and is included in the
4998 archive). *Note Dumpdir::, for the detailed description of dumpdirs
4999 and status codes. Each such line is terminated by a newline character.
5000 The last line is followed by an additional newline to indicate the end
5003 The option `--incremental' (`-G') gives the same behavior as
5004 `--listed-incremental' when used with `--list' and `--extract' options.
5005 When used with `--create' option, it creates an incremental archive
5006 without creating snapshot file. Thus, it is impossible to create
5007 several levels of incremental backups with `--incremental' option.
5009 ---------- Footnotes ----------
5011 (1) Notice, that since both archives were created without `-P'
5012 option (*note absolute::), these commands should be run from the root
5015 (2) Two `--verbose' options were selected to avoid breaking usual
5016 verbose listing output (`--list --verbose') when using in scripts.
5018 Versions of GNU `tar' up to 1.15.1 used to dump verbatim binary
5019 contents of the DUMPDIR header (with terminating nulls) when
5020 `--incremental' or `--listed-incremental' option was given, no matter
5021 what the verbosity level. This behavior, and, especially, the binary
5022 output it produced were considered inconvenient and were changed in
5026 File: tar.info, Node: Backup Levels, Next: Backup Parameters, Prev: Incremental Dumps, Up: Backups
5028 5.3 Levels of Backups
5029 =====================
5031 An archive containing all the files in the file system is called a
5032 "full backup" or "full dump". You could insure your data by creating a
5033 full dump every day. This strategy, however, would waste a substantial
5034 amount of archive media and user time, as unchanged files are daily
5037 It is more efficient to do a full dump only occasionally. To back up
5038 files between full dumps, you can use "incremental dumps". A "level
5039 one" dump archives all the files that have changed since the last full
5042 A typical dump strategy would be to perform a full dump once a week,
5043 and a level one dump once a day. This means some versions of files
5044 will in fact be archived more than once, but this dump strategy makes
5045 it possible to restore a file system to within one day of accuracy by
5046 only extracting two archives--the last weekly (full) dump and the last
5047 daily (level one) dump. The only information lost would be in files
5048 changed or created since the last daily backup. (Doing dumps more than
5049 once a day is usually not worth the trouble).
5051 GNU `tar' comes with scripts you can use to do full and level-one
5052 (actually, even level-two and so on) dumps. Using scripts (shell
5053 programs) to perform backups and restoration is a convenient and
5054 reliable alternative to typing out file name lists and `tar' commands
5057 Before you use these scripts, you need to edit the file
5058 `backup-specs', which specifies parameters used by the backup scripts
5059 and by the restore script. This file is usually located in
5060 `/etc/backup' directory. *Note Backup Parameters::, for its detailed
5061 description. Once the backup parameters are set, you can perform
5062 backups or restoration by running the appropriate script.
5064 The name of the backup script is `backup'. The name of the restore
5065 script is `restore'. The following sections describe their use in
5068 _Please Note:_ The backup and restoration scripts are designed to be
5069 used together. While it is possible to restore files by hand from an
5070 archive which was created using a backup script, and to create an
5071 archive by hand which could then be extracted using the restore script,
5072 it is easier to use the scripts. *Note Incremental Dumps::, before
5073 making such an attempt.
5076 File: tar.info, Node: Backup Parameters, Next: Scripted Backups, Prev: Backup Levels, Up: Backups
5078 5.4 Setting Parameters for Backups and Restoration
5079 ==================================================
5081 The file `backup-specs' specifies backup parameters for the backup and
5082 restoration scripts provided with `tar'. You must edit `backup-specs'
5083 to fit your system configuration and schedule before using these
5086 Syntactically, `backup-specs' is a shell script, containing mainly
5087 variable assignments. However, any valid shell construct is allowed in
5088 this file. Particularly, you may wish to define functions within that
5089 script (e.g., see `RESTORE_BEGIN' below). For more information about
5090 shell script syntax, please refer to the definition of the Shell
5092 (http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
5093 g_02). See also *note Bash Features: (bashref)Top.
5095 The shell variables controlling behavior of `backup' and `restore'
5096 are described in the following subsections.
5100 * General-Purpose Variables::
5101 * Magnetic Tape Control::
5103 * backup-specs example:: An Example Text of `Backup-specs'
5106 File: tar.info, Node: General-Purpose Variables, Next: Magnetic Tape Control, Up: Backup Parameters
5108 5.4.1 General-Purpose Variables
5109 -------------------------------
5111 -- Backup variable: ADMINISTRATOR
5112 The user name of the backup administrator. `Backup' scripts sends
5113 a backup report to this address.
5115 -- Backup variable: BACKUP_HOUR
5116 The hour at which the backups are done. This can be a number from
5117 0 to 23, or the time specification in form HOURS:MINUTES, or the
5120 This variable is used by `backup'. Its value may be overridden
5121 using `--time' option (*note Scripted Backups::).
5123 -- Backup variable: TAPE_FILE
5124 The device `tar' writes the archive to. If TAPE_FILE is a remote
5125 archive (*note remote-dev::), backup script will suppose that your
5126 `mt' is able to access remote devices. If RSH (*note RSH::) is
5127 set, `--rsh-command' option will be added to invocations of `mt'.
5129 -- Backup variable: BLOCKING
5130 The blocking factor `tar' will use when writing the dump archive.
5131 *Note Blocking Factor::.
5133 -- Backup variable: BACKUP_DIRS
5134 A list of file systems to be dumped (for `backup'), or restored
5135 (for `restore'). You can include any directory name in the list
5136 -- subdirectories on that file system will be included, regardless
5137 of how they may look to other networked machines. Subdirectories
5138 on other file systems will be ignored.
5140 The host name specifies which host to run `tar' on, and should
5141 normally be the host that actually contains the file system.
5142 However, the host machine must have GNU `tar' installed, and must
5143 be able to access the directory containing the backup scripts and
5144 their support files using the same file name that is used on the
5145 machine where the scripts are run (i.e., what `pwd' will print
5146 when in that directory on that machine). If the host that contains
5147 the file system does not have this capability, you can specify
5148 another host as long as it can access the file system through NFS.
5150 If the list of file systems is very long you may wish to put it in
5151 a separate file. This file is usually named `/etc/backup/dirs',
5152 but this name may be overridden in `backup-specs' using `DIRLIST'
5155 -- Backup variable: DIRLIST
5156 The name of the file that contains a list of file systems to backup
5157 or restore. By default it is `/etc/backup/dirs'.
5159 -- Backup variable: BACKUP_FILES
5160 A list of individual files to be dumped (for `backup'), or restored
5161 (for `restore'). These should be accessible from the machine on
5162 which the backup script is run.
5164 If the list of file systems is very long you may wish to store it
5165 in a separate file. This file is usually named
5166 `/etc/backup/files', but this name may be overridden in
5167 `backup-specs' using `FILELIST' variable.
5169 -- Backup variable: FILELIST
5170 The name of the file that contains a list of individual files to
5171 backup or restore. By default it is `/etc/backup/files'.
5173 -- Backup variable: MT
5174 Full file name of `mt' binary.
5176 -- Backup variable: RSH
5177 Full file name of `rsh' binary or its equivalent. You may wish to
5178 set it to `ssh', to improve security. In this case you will have
5179 to use public key authentication.
5181 -- Backup variable: RSH_COMMAND
5182 Full file name of `rsh' binary on remote machines. This will be
5183 passed via `--rsh-command' option to the remote invocation of GNU
5186 -- Backup variable: VOLNO_FILE
5187 Name of temporary file to hold volume numbers. This needs to be
5188 accessible by all the machines which have file systems to be
5191 -- Backup variable: XLIST
5192 Name of "exclude file list". An "exclude file list" is a file
5193 located on the remote machine and containing the list of files to
5194 be excluded from the backup. Exclude file lists are searched in
5195 /etc/tar-backup directory. A common use for exclude file lists is
5196 to exclude files containing security-sensitive information (e.g.,
5197 `/etc/shadow' from backups).
5199 This variable affects only `backup'.
5201 -- Backup variable: SLEEP_TIME
5202 Time to sleep between dumps of any two successive file systems
5204 This variable affects only `backup'.
5206 -- Backup variable: DUMP_REMIND_SCRIPT
5207 Script to be run when it's time to insert a new tape in for the
5208 next volume. Administrators may want to tailor this script for
5209 their site. If this variable isn't set, GNU `tar' will display
5210 its built-in prompt, and will expect confirmation from the
5211 console. For the description of the default prompt, see *note
5212 change volume prompt::.
5215 -- Backup variable: SLEEP_MESSAGE
5216 Message to display on the terminal while waiting for dump time.
5217 Usually this will just be some literal text.
5219 -- Backup variable: TAR
5220 Full file name of the GNU `tar' executable. If this is not set,
5221 backup scripts will search `tar' in the current shell path.
5224 File: tar.info, Node: Magnetic Tape Control, Next: User Hooks, Prev: General-Purpose Variables, Up: Backup Parameters
5226 5.4.2 Magnetic Tape Control
5227 ---------------------------
5229 Backup scripts access tape device using special "hook functions".
5230 These functions take a single argument - the name of the tape device.
5231 Their names are kept in the following variables:
5233 -- Backup variable: MT_BEGIN
5234 The name of "begin" function. This function is called before
5235 accessing the drive. By default it retensions the tape:
5240 mt -f "$1" retension
5243 -- Backup variable: MT_REWIND
5244 The name of "rewind" function. The default definition is as
5254 -- Backup variable: MT_OFFLINE
5255 The name of the function switching the tape off line. By default
5256 it is defined as follows:
5258 MT_OFFLINE=mt_offline
5264 -- Backup variable: MT_STATUS
5265 The name of the function used to obtain the status of the archive
5266 device, including error count. Default definition:
5275 File: tar.info, Node: User Hooks, Next: backup-specs example, Prev: Magnetic Tape Control, Up: Backup Parameters
5280 "User hooks" are shell functions executed before and after each `tar'
5281 invocation. Thus, there are "backup hooks", which are executed before
5282 and after dumping each file system, and "restore hooks", executed
5283 before and after restoring a file system. Each user hook is a shell
5284 function taking four arguments:
5286 -- User Hook Function: hook LEVEL HOST FS FSNAME
5290 Current backup or restore level.
5293 Name or IP address of the host machine being dumped or
5297 Full file name of the file system being dumped or restored.
5300 File system name with directory separators replaced with
5301 colons. This is useful, e.g., for creating unique files.
5303 Following variables keep the names of user hook functions
5305 -- Backup variable: DUMP_BEGIN
5306 Dump begin function. It is executed before dumping the file
5309 -- Backup variable: DUMP_END
5310 Executed after dumping the file system.
5312 -- Backup variable: RESTORE_BEGIN
5313 Executed before restoring the file system.
5315 -- Backup variable: RESTORE_END
5316 Executed after restoring the file system.
5319 File: tar.info, Node: backup-specs example, Prev: User Hooks, Up: Backup Parameters
5321 5.4.4 An Example Text of `Backup-specs'
5322 ---------------------------------------
5324 The following is an example of `backup-specs':
5326 # site-specific parameters for file system backup.
5328 ADMINISTRATOR=friedman
5330 TAPE_FILE=/dev/nrsmt0
5332 # Use `ssh' instead of the less secure `rsh'
5334 RSH_COMMAND=/usr/bin/ssh
5336 # Override MT_STATUS function:
5342 # Disable MT_OFFLINE function
5359 apple-gunkies:/com/mailer/gnu
5360 apple-gunkies:/com/archive/gnu"
5362 BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
5365 File: tar.info, Node: Scripted Backups, Next: Scripted Restoration, Prev: Backup Parameters, Up: Backups
5367 5.5 Using the Backup Scripts
5368 ============================
5370 The syntax for running a backup script is:
5372 backup --level=LEVEL --time=TIME
5374 The `level' option requests the dump level. Thus, to produce a full
5375 dump, specify `--level=0' (this is the default, so `--level' may be
5376 omitted if its value is `0'). (1)
5378 The `--time' option determines when should the backup be run. TIME
5379 may take three forms:
5382 The dump must be run at HH hours MM minutes.
5385 The dump must be run at HH hours
5388 The dump must be run immediately.
5390 You should start a script with a tape or disk mounted. Once you
5391 start a script, it prompts you for new tapes or disks as it needs them.
5392 Media volumes don't have to correspond to archive files -- a
5393 multi-volume archive can be started in the middle of a tape that
5394 already contains the end of another multi-volume archive. The
5395 `restore' script prompts for media by its archive volume, so to avoid
5396 an error message you should keep track of which tape (or disk) contains
5397 which volume of the archive (*note Scripted Restoration::).
5399 The backup scripts write two files on the file system. The first is
5400 a record file in `/etc/tar-backup/', which is used by the scripts to
5401 store and retrieve information about which files were dumped. This
5402 file is not meant to be read by humans, and should not be deleted by
5403 them. *Note Snapshot Files::, for a more detailed explanation of this
5406 The second file is a log file containing the names of the file
5407 systems and files dumped, what time the backup was made, and any error
5408 messages that were generated, as well as how much space was left in the
5409 media volume after the last volume of the archive was written. You
5410 should check this log file after every backup. The file name is
5411 `log-MM-DD-YYYY-level-N', where MM-DD-YYYY represents current date, and
5412 N represents current dump level number.
5414 The script also prints the name of each system being dumped to the
5417 Following is the full list of options accepted by `backup' script:
5421 Do backup level LEVEL (default 0).
5425 Force backup even if today's log file already exists.
5429 Set verbosity level. The higher the level is, the more debugging
5430 information will be output during execution. Default LEVEL is
5431 100, which means the highest debugging level.
5435 Wait till TIME, then do backup.
5439 Display short help message and exit.
5443 Display information about the program's name, version, origin and
5444 legal status, all on standard output, and then exit successfully.
5446 ---------- Footnotes ----------
5448 (1) For backward compatibility, the `backup' will also try to deduce
5449 the requested dump level from the name of the script itself. If the
5450 name consists of a string `level-' followed by a single decimal digit,
5451 that digit is taken as the dump level number. Thus, you may create a
5452 link from `backup' to `level-1' and then run `level-1' whenever you
5453 need to create a level one dump.
5456 File: tar.info, Node: Scripted Restoration, Prev: Scripted Backups, Up: Backups
5458 5.6 Using the Restore Script
5459 ============================
5461 To restore files that were archived using a scripted backup, use the
5462 `restore' script. Its usage is quite straightforward. In the simplest
5463 form, invoke `restore --all', it will then restore all the file systems
5464 and files specified in `backup-specs' (*note BACKUP_DIRS:
5465 General-Purpose Variables.).
5467 You may select the file systems (and/or files) to restore by giving
5468 `restore' list of "patterns" in its command line. For example, running
5472 will restore all file systems on the machine `albert'. A more
5473 complicated example:
5475 restore 'albert:*' '*:/var'
5477 This command will restore all file systems on the machine `albert' as
5478 well as `/var' file system on all machines.
5480 By default `restore' will start restoring files from the lowest
5481 available dump level (usually zero) and will continue through all
5482 available dump levels. There may be situations where such a thorough
5483 restore is not necessary. For example, you may wish to restore only
5484 files from the recent level one backup. To do so, use `--level'
5485 option, as shown in the example below:
5489 The full list of options accepted by `restore' follows:
5493 Restore all file systems and files specified in `backup-specs'
5497 Start restoring from the given backup level, instead of the
5502 Set verbosity level. The higher the level is, the more debugging
5503 information will be output during execution. Default LEVEL is
5504 100, which means the highest debugging level.
5508 Display short help message and exit.
5512 Display information about the program's name, version, origin and
5513 legal status, all on standard output, and then exit successfully.
5515 You should start the restore script with the media containing the
5516 first volume of the archive mounted. The script will prompt for other
5517 volumes as they are needed. If the archive is on tape, you don't need
5518 to rewind the tape to to its beginning--if the tape head is positioned
5519 past the beginning of the archive, the script will rewind the tape as
5520 needed. *Note Tape Positioning::, for a discussion of tape positioning.
5522 *Warning:* The script will delete files from the active file
5523 system if they were not in the file system when the archive was
5526 *Note Incremental Dumps::, for an explanation of how the script makes
5530 File: tar.info, Node: Choosing, Next: Date input formats, Prev: Backups, Up: Top
5532 6 Choosing Files and Names for `tar'
5533 ************************************
5535 _(This message will disappear, once this node revised.)_
5537 Certain options to `tar' enable you to specify a name for your archive.
5538 Other options let you decide which files to include or exclude from
5539 the archive, based on when or whether files were modified, whether the
5540 file names do or don't match specified patterns, or whether files are
5541 in specified directories.
5543 This chapter discusses these options in detail.
5547 * file:: Choosing the Archive's Name
5548 * Selecting Archive Members::
5549 * files:: Reading Names from a File
5550 * exclude:: Excluding Some Files
5551 * wildcards:: Wildcards Patterns and Matching
5552 * quoting styles:: Ways of Quoting Special Characters in Names
5553 * transform:: Modifying File and Member Names
5554 * after:: Operating Only on New Files
5555 * recurse:: Descending into Directories
5556 * one:: Crossing File System Boundaries
5559 File: tar.info, Node: file, Next: Selecting Archive Members, Up: Choosing
5561 6.1 Choosing and Naming Archive Files
5562 =====================================
5564 _(This message will disappear, once this node revised.)_
5566 By default, `tar' uses an archive file name that was compiled when it
5567 was built on the system; usually this name refers to some physical tape
5568 drive on the machine. However, the person who installed `tar' on the
5569 system may not have set the default to a meaningful value as far as
5570 most users are concerned. As a result, you will usually want to tell
5571 `tar' where to find (or create) the archive. The `--file=ARCHIVE-NAME'
5572 (`-f ARCHIVE-NAME') option allows you to either specify or name a file
5573 to use as the archive instead of the default archive file location.
5575 `--file=ARCHIVE-NAME'
5577 Name the archive to create or operate on. Use in conjunction with
5580 For example, in this `tar' command,
5582 $ tar -cvf collection.tar blues folk jazz
5584 `collection.tar' is the name of the archive. It must directly follow
5585 the `-f' option, since whatever directly follows `-f' _will_ end up
5586 naming the archive. If you neglect to specify an archive name, you may
5587 end up overwriting a file in the working directory with the archive you
5588 create since `tar' will use this file's name for the archive name.
5590 An archive can be saved as a file in the file system, sent through a
5591 pipe or over a network, or written to an I/O device such as a tape,
5592 floppy disk, or CD write drive.
5594 If you do not name the archive, `tar' uses the value of the
5595 environment variable `TAPE' as the file name for the archive. If that
5596 is not available, `tar' uses a default, compiled-in archive name,
5597 usually that for tape unit zero (i.e., `/dev/tu00').
5599 If you use `-' as an ARCHIVE-NAME, `tar' reads the archive from
5600 standard input (when listing or extracting files), or writes it to
5601 standard output (when creating an archive). If you use `-' as an
5602 ARCHIVE-NAME when modifying an archive, `tar' reads the original
5603 archive from its standard input and writes the entire new archive to
5604 its standard output.
5606 The following example is a convenient way of copying directory
5607 hierarchy from `sourcedir' to `targetdir'.
5609 $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)
5611 The `-C' option allows to avoid using subshells:
5613 $ tar -C sourcedir -cf - . | tar -C targetdir -xpf -
5615 In both examples above, the leftmost `tar' invocation archives the
5616 contents of `sourcedir' to the standard output, while the rightmost one
5617 reads this archive from its standard input and extracts it. The `-p'
5618 option tells it to restore permissions of the extracted files.
5620 To specify an archive file on a device attached to a remote machine,
5623 --file=HOSTNAME:/DEV/FILE-NAME
5625 `tar' will complete the remote connection, if possible, and prompt you
5626 for a username and password. If you use
5627 `--file=@HOSTNAME:/DEV/FILE-NAME', `tar' will complete the remote
5628 connection, if possible, using your username as the username on the
5631 If the archive file name includes a colon (`:'), then it is assumed
5632 to be a file on another machine. If the archive file is
5633 `USER@HOST:FILE', then FILE is used on the host HOST. The remote host
5634 is accessed using the `rsh' program, with a username of USER. If the
5635 username is omitted (along with the `@' sign), then your user name will
5636 be used. (This is the normal `rsh' behavior.) It is necessary for the
5637 remote machine, in addition to permitting your `rsh' access, to have
5638 the `rmt' program installed (This command is included in the GNU `tar'
5639 distribution and by default is installed under `PREFIX/libexec/rmt',
5640 were PREFIX means your installation prefix). If you need to use a file
5641 whose name includes a colon, then the remote tape drive behavior can be
5642 inhibited by using the `--force-local' option.
5644 When the archive is being created to `/dev/null', GNU `tar' tries to
5645 minimize input and output operations. The Amanda backup system, when
5646 used with GNU `tar', has an initial sizing pass which uses this feature.
5649 File: tar.info, Node: Selecting Archive Members, Next: files, Prev: file, Up: Choosing
5651 6.2 Selecting Archive Members
5652 =============================
5654 "File Name arguments" specify which files in the file system `tar'
5655 operates on, when creating or adding to an archive, or which archive
5656 members `tar' operates on, when reading or deleting from an archive.
5659 To specify file names, you can include them as the last arguments on
5660 the command line, as follows:
5661 tar OPERATION [OPTION1 OPTION2 ...] [FILE NAME-1 FILE NAME-2 ...]
5663 If a file name begins with dash (`-'), precede it with `--add-file'
5664 option to prevent it from being treated as an option.
5666 By default GNU `tar' attempts to "unquote" each file or member name,
5667 replacing "escape sequences" according to the following table:
5669 Escape Replaced with
5670 -----------------------------------------------------------
5671 \a Audible bell (ASCII 7)
5672 \b Backspace (ASCII 8)
5673 \f Form feed (ASCII 12)
5674 \n New line (ASCII 10)
5675 \r Carriage return (ASCII 13)
5676 \t Horizontal tabulation (ASCII 9)
5677 \v Vertical tabulation (ASCII 11)
5679 \N ASCII N (N should be an octal number
5682 A backslash followed by any other symbol is retained.
5684 This default behavior is controlled by the following command line
5688 Enable unquoting input file or member names (default).
5691 Disable unquoting input file or member names.
5693 If you specify a directory name as a file name argument, all the
5694 files in that directory are operated on by `tar'.
5696 If you do not specify files, `tar' behavior differs depending on the
5697 operation mode as described below:
5699 When `tar' is invoked with `--create' (`-c'), `tar' will stop
5700 immediately, reporting the following:
5703 tar: Cowardly refusing to create an empty archive
5704 Try `tar --help' or `tar --usage' for more information.
5706 If you specify either `--list' (`-t') or `--extract' (`--get',
5707 `-x'), `tar' operates on all the archive members in the archive.
5709 If run with `--diff' option, tar will compare the archive with the
5710 contents of the current working directory.
5712 If you specify any other operation, `tar' does nothing.
5714 By default, `tar' takes file names from the command line. However,
5715 there are other ways to specify file or member names, or to modify the
5716 manner in which `tar' selects the files or members upon which to
5717 operate. In general, these methods work both for specifying the names
5718 of files and archive members.
5721 File: tar.info, Node: files, Next: exclude, Prev: Selecting Archive Members, Up: Choosing
5723 6.3 Reading Names from a File
5724 =============================
5726 Instead of giving the names of files or archive members on the command
5727 line, you can put the names into a file, and then use the
5728 `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option to `tar'.
5729 Give the name of the file which contains the list of files to include
5730 as the argument to `--files-from'. In the list, the file names should
5731 be separated by newlines. You will frequently use this option when you
5732 have generated the list of files to archive with the `find' utility.
5734 `--files-from=FILE-NAME'
5736 Get names to extract or create from file FILE-NAME.
5738 If you give a single dash as a file name for `--files-from', (i.e.,
5739 you specify either `--files-from=-' or `-T -'), then the file names are
5740 read from standard input.
5742 Unless you are running `tar' with `--create', you can not use both
5743 `--files-from=-' and `--file=-' (`-f -') in the same command.
5745 Any number of `-T' options can be given in the command line.
5747 The following example shows how to use `find' to generate a list of
5748 files smaller than 400K in length and put that list into a file called
5749 `small-files'. You can then use the `-T' option to `tar' to specify
5750 the files from that file, `small-files', to create the archive
5751 `little.tgz'. (The `-z' option to `tar' compresses the archive with
5752 `gzip'; *note gzip:: for more information.)
5754 $ find . -size -400 -print > small-files
5755 $ tar -c -v -z -T small-files -f little.tgz
5757 In the file list given by `-T' option, any file name beginning with `-'
5758 character is considered a `tar' option and is processed accordingly.(1)
5759 For example, the common use of this feature is to change to another
5760 directory by specifying `-C' option:
5768 $ tar -c -f foo.tar --files-from list
5770 In this example, `tar' will first switch to `/etc' directory and add
5771 files `passwd' and `hosts' to the archive. Then it will change to
5772 `/lib' directory and will archive the file `libc.a'. Thus, the
5773 resulting archive `foo.tar' will contain:
5781 Notice that the option parsing algorithm used with `-T' is stricter
5782 than the one used by shell. Namely, when specifying option arguments,
5783 you should observe the following rules:
5785 * When using short (single-letter) option form, its argument must
5786 immediately follow the option letter, without any intervening
5787 whitespace. For example: `-Cdir'.
5789 * When using long option form, the option argument must be separated
5790 from the option by a single equal sign. No whitespace is allowed
5791 on any side of the equal sign. For example: `--directory=dir'.
5793 * For both short and long option forms, the option argument can be
5794 given on the next line after the option name, e.g.:
5804 If you happen to have a file whose name starts with `-', precede it
5805 with `--add-file' option to prevent it from being recognized as an
5806 option. For example: `--add-file=--my-file'.
5812 ---------- Footnotes ----------
5814 (1) Versions of GNU `tar' up to 1.15.1 recognized only `-C' option
5815 in file lists, and only if the option and its argument occupied two
5819 File: tar.info, Node: nul, Up: files
5821 6.3.1 `NUL' Terminated File Names
5822 ---------------------------------
5824 The `--null' option causes `--files-from=FILE-OF-NAMES' (`-T
5825 FILE-OF-NAMES') to read file names terminated by a `NUL' instead of a
5826 newline, so files whose names contain newlines can be archived using
5830 Only consider `NUL' terminated file names, instead of files that
5831 terminate in a newline.
5833 The `--null' option is just like the one in GNU `xargs' and `cpio',
5834 and is useful with the `-print0' predicate of GNU `find'. In `tar',
5835 `--null' also disables special handling for file names that begin with
5838 This example shows how to use `find' to generate a list of files
5839 larger than 800K in length and put that list into a file called
5840 `long-files'. The `-print0' option to `find' is just like `-print',
5841 except that it separates files with a `NUL' rather than with a newline.
5842 You can then run `tar' with both the `--null' and `-T' options to
5843 specify that `tar' get the files from that file, `long-files', to
5844 create the archive `big.tgz'. The `--null' option to `tar' will cause
5845 `tar' to recognize the `NUL' separator between files.
5847 $ find . -size +800 -print0 > long-files
5848 $ tar -c -v --null --files-from=long-files --file=big.tar
5851 File: tar.info, Node: exclude, Next: wildcards, Prev: files, Up: Choosing
5853 6.4 Excluding Some Files
5854 ========================
5856 _(This message will disappear, once this node revised.)_
5858 To avoid operating on files whose names match a particular pattern, use
5859 the `--exclude' or `--exclude-from' options.
5862 Causes `tar' to ignore files that match the PATTERN.
5864 The `--exclude=PATTERN' option prevents any file or member whose
5865 name matches the shell wildcard (PATTERN) from being operated on. For
5866 example, to create an archive with all the contents of the directory
5867 `src' except for files whose names end in `.o', use the command `tar
5868 -cf src.tar --exclude='*.o' src'.
5870 You may give multiple `--exclude' options.
5872 `--exclude-from=FILE'
5874 Causes `tar' to ignore files that match the patterns listed in
5877 Use the `--exclude-from' option to read a list of patterns, one per
5878 line, from FILE; `tar' will ignore files matching those patterns. Thus
5879 if `tar' is called as `tar -c -X foo .' and the file `foo' contains a
5880 single line `*.o', no files whose names end in `.o' will be added to
5883 Notice, that lines from FILE are read verbatim. One of the frequent
5884 errors is leaving some extra whitespace after a file name, which is
5885 difficult to catch using text editors.
5887 However, empty lines are OK.
5890 Exclude files and directories used by some version control systems.
5892 As of version 1.20, the following files are excluded:
5894 * `CVS/', and everything under it
5896 * `RCS/', and everything under it
5898 * `SCCS/', and everything under it
5900 * `.git/', and everything under it
5906 * `.svn/', and everything under it
5908 * `.arch-ids/', and everything under it
5910 * `{arch}/', and everything under it
5918 When creating an archive, the `--exclude-caches' option family
5919 causes `tar' to exclude all directories that contain a "cache directory
5920 tag". A cache directory tag is a short file with the well-known name
5921 `CACHEDIR.TAG' and having a standard header specified in
5922 `http://www.brynosaurus.com/cachedir/spec.html'. Various applications
5923 write cache directory tags into directories they use to hold
5924 regenerable, non-precious data, so that such data can be more easily
5925 excluded from backups.
5927 There are three `exclude-caches' options, each providing a different
5928 exclusion semantics:
5931 Do not archive the contents of the directory, but archive the
5932 directory itself and the `CACHEDIR.TAG' file.
5934 `--exclude-caches-under'
5935 Do not archive the contents of the directory, nor the
5936 `CACHEDIR.TAG' file, archive only the directory itself.
5938 `--exclude-caches-all'
5939 Omit directories containing `CACHEDIR.TAG' file entirely.
5941 Another option family, `--exclude-tag', provides a generalization of
5942 this concept. It takes a single argument, a file name to look for.
5943 Any directory that contains this file will be excluded from the dump.
5944 Similarly to `exclude-caches', there are three options in this option
5947 `--exclude-tag=FILE'
5948 Do not dump the contents of the directory, but dump the directory
5949 itself and the FILE.
5951 `--exclude-tag-under=FILE'
5952 Do not dump the contents of the directory, nor the FILE, archive
5953 only the directory itself.
5955 `--exclude-tag-all=FILE'
5956 Omit directories containing FILE file entirely.
5958 Multiple `--exclude-tag*' options can be given.
5960 For example, given this directory:
5971 The `--exclude-tag' will produce the following:
5973 $ tar -cf archive.tar --exclude-tag=tagfile -v dir
5978 tar: dir/folk/: contains a cache directory tag tagfile;
5982 Both the `dir/folk' directory and its tagfile are preserved in the
5983 archive, however the rest of files in this directory are not.
5985 Now, using the `--exclude-tag-under' option will exclude `tagfile'
5986 from the dump, while still preserving the directory itself, as shown in
5989 $ tar -cf archive.tar --exclude-tag-under=tagfile -v dir
5994 ./tar: dir/folk/: contains a cache directory tag tagfile;
5997 Finally, using `--exclude-tag-all' omits the `dir/folk' directory
6000 $ tar -cf archive.tar --exclude-tag-all=tagfile -v dir
6004 ./tar: dir/folk/: contains a cache directory tag tagfile;
6005 directory not dumped
6009 * problems with exclude::
6012 File: tar.info, Node: problems with exclude, Up: exclude
6014 Problems with Using the `exclude' Options
6015 -----------------------------------------
6017 Some users find `exclude' options confusing. Here are some common
6020 * The main operating mode of `tar' does not act on a file name
6021 explicitly listed on the command line, if one of its file name
6022 components is excluded. In the example above, if you create an
6023 archive and exclude files that end with `*.o', but explicitly name
6024 the file `dir.o/foo' after all the options have been listed,
6025 `dir.o/foo' will be excluded from the archive.
6027 * You can sometimes confuse the meanings of `--exclude' and
6028 `--exclude-from'. Be careful: use `--exclude' when files to be
6029 excluded are given as a pattern on the command line. Use
6030 `--exclude-from' to introduce the name of a file which contains a
6031 list of patterns, one per line; each of these patterns can exclude
6032 zero, one, or many files.
6034 * When you use `--exclude=PATTERN', be sure to quote the PATTERN
6035 parameter, so GNU `tar' sees wildcard characters like `*'. If you
6036 do not do this, the shell might expand the `*' itself using files
6037 at hand, so `tar' might receive a list of files instead of one
6038 pattern, or none at all, making the command somewhat illegal.
6039 This might not correspond to what you want.
6043 $ tar -c -f ARCHIVE.TAR --exclude '*.o' DIRECTORY
6048 $ tar -c -f ARCHIVE.TAR --exclude *.o DIRECTORY
6050 * You must use use shell syntax, or globbing, rather than `regexp'
6051 syntax, when using exclude options in `tar'. If you try to use
6052 `regexp' syntax to describe files to be excluded, your command
6055 * In earlier versions of `tar', what is now the `--exclude-from'
6056 option was called `--exclude' instead. Now, `--exclude' applies
6057 to patterns listed on the command line and `--exclude-from'
6058 applies to patterns listed in a file.
6062 File: tar.info, Node: wildcards, Next: quoting styles, Prev: exclude, Up: Choosing
6064 6.5 Wildcards Patterns and Matching
6065 ===================================
6067 "Globbing" is the operation by which "wildcard" characters, `*' or `?'
6068 for example, are replaced and expanded into all existing files matching
6069 the given pattern. GNU `tar' can use wildcard patterns for matching
6070 (or globbing) archive members when extracting from or listing an
6071 archive. Wildcard patterns are also used for verifying volume labels
6072 of `tar' archives. This section has the purpose of explaining wildcard
6075 A PATTERN should be written according to shell syntax, using wildcard
6076 characters to effect globbing. Most characters in the pattern stand
6077 for themselves in the matched string, and case is significant: `a' will
6078 match only `a', and not `A'. The character `?' in the pattern matches
6079 any single character in the matched string. The character `*' in the
6080 pattern matches zero, one, or more single characters in the matched
6081 string. The character `\' says to take the following character of the
6082 pattern _literally_; it is useful when one needs to match the `?', `*',
6083 `[' or `\' characters, themselves.
6085 The character `[', up to the matching `]', introduces a character
6086 class. A "character class" is a list of acceptable characters for the
6087 next single character of the matched string. For example, `[abcde]'
6088 would match any of the first five letters of the alphabet. Note that
6089 within a character class, all of the "special characters" listed above
6090 other than `\' lose their special meaning; for example, `[-\\[*?]]'
6091 would match any of the characters, `-', `\', `[', `*', `?', or `]'.
6092 (Due to parsing constraints, the characters `-' and `]' must either
6093 come _first_ or _last_ in a character class.)
6095 If the first character of the class after the opening `[' is `!' or
6096 `^', then the meaning of the class is reversed. Rather than listing
6097 character to match, it lists those characters which are _forbidden_ as
6098 the next single character of the matched string.
6100 Other characters of the class stand for themselves. The special
6101 construction `[A-E]', using an hyphen between two letters, is meant to
6102 represent all characters between A and E, inclusive.
6104 Periods (`.') or forward slashes (`/') are not considered special
6105 for wildcard matches. However, if a pattern completely matches a
6106 directory prefix of a matched string, then it matches the full matched
6107 string: thus, excluding a directory also excludes all the files beneath
6112 * controlling pattern-matching::
6115 File: tar.info, Node: controlling pattern-matching, Up: wildcards
6117 Controlling Pattern-Matching
6118 ----------------------------
6120 For the purposes of this section, we call "exclusion members" all
6121 member names obtained while processing `--exclude' and `--exclude-from'
6122 options, and "inclusion members" those member names that were given in
6123 the command line or read from the file specified with `--files-from'
6126 These two pairs of member lists are used in the following operations:
6127 `--diff', `--extract', `--list', `--update'.
6129 There are no inclusion members in create mode (`--create' and
6130 `--append'), since in this mode the names obtained from the command
6131 line refer to _files_, not archive members.
6133 By default, inclusion members are compared with archive members
6134 literally (1) and exclusion members are treated as globbing patterns.
6142 # Member names are used verbatim:
6143 $ tar -xf foo.tar -v '[remarks]'
6145 # Exclude member names are globbed:
6146 $ tar -xf foo.tar -v --exclude '*.c'
6150 This behavior can be altered by using the following options:
6153 Treat all member names as wildcards.
6156 Treat all member names as literal strings.
6158 Thus, to extract files whose names end in `.c', you can use:
6160 $ tar -xf foo.tar -v --wildcards '*.c'
6164 Notice quoting of the pattern to prevent the shell from interpreting it.
6166 The effect of `--wildcards' option is canceled by `--no-wildcards'.
6167 This can be used to pass part of the command line arguments verbatim
6168 and other part as globbing patterns. For example, the following
6171 $ tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'
6173 instructs `tar' to extract from `foo.tar' all files whose names end in
6174 `.txt' and the file named `[remarks]'.
6176 Normally, a pattern matches a name if an initial subsequence of the
6177 name's components matches the pattern, where `*', `?', and `[...]' are
6178 the usual shell wildcards, `\' escapes wildcards, and wildcards can
6181 Other than optionally stripping leading `/' from names (*note
6182 absolute::), patterns and names are used as-is. For example, trailing
6183 `/' is not trimmed from a user-specified name before deciding whether
6186 However, this matching procedure can be altered by the options listed
6187 below. These options accumulate. For example:
6189 --ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
6191 ignores case when excluding `makefile', but not when excluding `readme'.
6195 If anchored, a pattern must match an initial subsequence of the
6196 name's components. Otherwise, the pattern can match any
6197 subsequence. Default is `--no-anchored' for exclusion members and
6198 `--anchored' inclusion members.
6202 When ignoring case, upper-case patterns match lower-case names and
6203 vice versa. When not ignoring case (the default), matching is
6206 `--wildcards-match-slash'
6207 `--no-wildcards-match-slash'
6208 When wildcards match slash (the default for exclusion members), a
6209 wildcard like `*' in the pattern can match a `/' in the name.
6210 Otherwise, `/' is matched only by `/'.
6213 The `--recursion' and `--no-recursion' options (*note recurse::)
6214 also affect how member patterns are interpreted. If recursion is in
6215 effect, a pattern matches a name if it matches any of the name's parent
6218 The following table summarizes pattern-matching default values:
6220 Members Default settings
6221 --------------------------------------------------------------------------
6222 Inclusion `--no-wildcards --anchored
6223 --no-wildcards-match-slash'
6224 Exclusion `--wildcards --no-anchored
6225 --wildcards-match-slash'
6227 ---------- Footnotes ----------
6229 (1) Notice that earlier GNU `tar' versions used globbing for
6230 inclusion members, which contradicted to UNIX98 specification and was
6231 not documented. *Note Changes::, for more information on this and other
6235 File: tar.info, Node: quoting styles, Next: transform, Prev: wildcards, Up: Choosing
6237 6.6 Quoting Member Names
6238 ========================
6240 When displaying member names, `tar' takes care to avoid ambiguities
6241 caused by certain characters. This is called "name quoting". The
6242 characters in question are:
6244 * Non-printable control characters:
6246 Character ASCII Character name
6247 ---------------------------------------------------------------
6252 \r 13 Carriage return
6253 \t 9 Horizontal tabulation
6254 \v 11 Vertical tabulation
6258 * Single and double quotes (`'' and `"')
6262 The exact way `tar' uses to quote these characters depends on the
6263 "quoting style". The default quoting style, called "escape" (see
6264 below), uses backslash notation to represent control characters, space
6265 and backslash. Using this quoting style, control characters are
6266 represented as listed in column `Character' in the above table, a space
6267 is printed as `\ ' and a backslash as `\\'.
6269 GNU `tar' offers seven distinct quoting styles, which can be selected
6270 using `--quoting-style' option:
6272 `--quoting-style=STYLE'
6273 Sets quoting style. Valid values for STYLE argument are: literal,
6274 shell, shell-always, c, escape, locale, clocale.
6276 These styles are described in detail below. To illustrate their
6277 effect, we will use an imaginary tar archive `arch.tar' containing the
6280 # 1. Contains horizontal tabulation character.
6282 # 2. Contains newline character
6285 # 3. Contains a space
6287 # 4. Contains double quotes
6289 # 5. Contains single quotes
6291 # 6. Contains a backslash character:
6294 Here is how usual `ls' command would have listed them, if they had
6295 existed in the current working directory:
6308 No quoting, display each character as is:
6310 $ tar tf arch.tar --quoting-style=literal
6321 Display characters the same way Bourne shell does: control
6322 characters, except `\t' and `\n', are printed using backslash
6323 escapes, `\t' and `\n' are printed as is, and a single quote is
6324 printed as `\''. If a name contains any quoted characters, it is
6325 enclosed in single quotes. In particular, if a name contains
6326 single quotes, it is printed as several single-quoted strings:
6328 $ tar tf arch.tar --quoting-style=shell
6331 './a'\''single'\''quote'
6339 Same as `shell', but the names are always enclosed in single
6342 $ tar tf arch.tar --quoting-style=shell-always
6345 './a'\''single'\''quote'
6353 Use the notation of the C programming language. All names are
6354 enclosed in double quotes. Control characters are quoted using
6355 backslash notations, double quotes are represented as `\"',
6356 backslash characters are represented as `\\'. Single quotes and
6357 spaces are not quoted:
6359 $ tar tf arch.tar --quoting-style=c
6363 "./a\"double\"quote"
6369 Control characters are printed using backslash notation, a space is
6370 printed as `\ ' and a backslash as `\\'. This is the default
6371 quoting style, unless it was changed when configured the package.
6373 $ tar tf arch.tar --quoting-style=escape
6383 Control characters, single quote and backslash are printed using
6384 backslash notation. All names are quoted using left and right
6385 quotation marks, appropriate to the current locale. If it does not
6386 define quotation marks, use ``' as left and `'' as right quotation
6387 marks. Any occurrences of the right quotation mark in a name are
6388 escaped with `\', for example:
6392 $ tar tf arch.tar --quoting-style=locale
6395 `./a\'single\'quote'
6402 Same as `locale', but `"' is used for both left and right
6403 quotation marks, if not provided by the currently selected locale:
6405 $ tar tf arch.tar --quoting-style=clocale
6409 "./a\"double\"quote"
6414 You can specify which characters should be quoted in addition to
6415 those implied by the current quoting style:
6417 `--quote-chars=STRING'
6418 Always quote characters from STRING, even if the selected quoting
6419 style would not quote them.
6421 For example, using `escape' quoting (compare with the usual escape
6424 $ tar tf arch.tar --quoting-style=escape --quote-chars=' "'
6433 To disable quoting of such additional characters, use the following
6436 `--no-quote-chars=STRING'
6437 Remove characters listed in STRING from the list of quoted
6438 characters set by the previous `--quote-chars' option.
6440 This option is particularly useful if you have added `--quote-chars'
6441 to your `TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to disable it for
6442 the current invocation.
6444 Note, that `--no-quote-chars' does _not_ disable those characters
6445 that are quoted by default in the selected quoting style.
6448 File: tar.info, Node: transform, Next: after, Prev: quoting styles, Up: Choosing
6450 6.7 Modifying File and Member Names
6451 ===================================
6453 `Tar' archives contain detailed information about files stored in them
6454 and full file names are part of that information. When storing file to
6455 an archive, its file name is recorded in the archive along with the
6456 actual file contents. When restoring from an archive, a file is
6457 created on disk with exactly the same name as that stored in the
6458 archive. In the majority of cases this is the desired behavior of a
6459 file archiver. However, there are some cases when it is not.
6461 First of all, it is often unsafe to extract archive members with
6462 absolute file names or those that begin with a `../'. GNU `tar' takes
6463 special precautions when extracting such names and provides a special
6464 option for handling them, which is described in *note absolute::.
6466 Secondly, you may wish to extract file names without some leading
6467 directory components, or with otherwise modified names. In other cases
6468 it is desirable to store files under differing names in the archive.
6470 GNU `tar' provides two options for these needs.
6472 `--strip-components=NUMBER'
6473 Strip given NUMBER of leading components from file names before
6476 For example, suppose you have archived whole `/usr' hierarchy to a
6477 tar archive named `usr.tar'. Among other files, this archive contains
6478 `usr/include/stdlib.h', which you wish to extract to the current
6479 working directory. To do so, you type:
6481 $ tar -xf usr.tar --strip=2 usr/include/stdlib.h
6483 The option `--strip=2' instructs `tar' to strip the two leading
6484 components (`usr/' and `include/') off the file name.
6486 If you add to the above invocation `--verbose' (`-v') option, you
6487 will note that the verbose listing still contains the full file name,
6488 with the two removed components still in place. This can be
6489 inconvenient, so `tar' provides a special option for altering this
6492 `--show-transformed-names'
6493 Display file or member names with all requested transformations
6498 $ tar -xf usr.tar -v --strip=2 usr/include/stdlib.h
6499 usr/include/stdlib.h
6500 $ tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h
6503 Notice that in both cases the file is `stdlib.h' extracted to the
6504 current working directory, `--show-transformed-names' affects only the
6505 way its name is displayed.
6507 This option is especially useful for verifying whether the invocation
6508 will have the desired effect. Thus, before running
6512 it is often advisable to run
6514 $ tar -t -v --show-transformed --strip=N
6516 to make sure the command will produce the intended results.
6518 In case you need to apply more complex modifications to the file
6519 name, GNU `tar' provides a general-purpose transformation option:
6521 `--transform=EXPRESSION'
6522 Modify file names using supplied EXPRESSION.
6524 The EXPRESSION is a `sed'-like replace expression of the form:
6526 s/REGEXP/REPLACE/[FLAGS]
6528 where REGEXP is a "regular expression", REPLACE is a replacement for
6529 each file name part that matches REGEXP. Both REGEXP and REPLACE are
6530 described in detail in *note The "s" Command: (sed)The "s" Command.
6532 As in `sed', you can give several replace expressions, separated by
6535 Supported FLAGS are:
6538 Apply the replacement to _all_ matches to the REGEXP, not just the
6542 Use case-insensitive matching
6545 REGEXP is an "extended regular expression" (*note Extended regular
6546 expressions: (sed)Extended regexps.).
6549 Only replace the NUMBERth match of the REGEXP.
6551 Note: the POSIX standard does not specify what should happen when
6552 you mix the `g' and NUMBER modifiers. GNU `tar' follows the GNU
6553 `sed' implementation in this regard, so the interaction is defined
6554 to be: ignore matches before the NUMBERth, and then match and
6555 replace all matches from the NUMBERth on.
6558 Any delimiter can be used in lieue of `/', the only requirement being
6559 that it be used consistently throughout the expression. For example,
6560 the following two expressions are equivalent:
6565 Changing delimiters is often useful when the REGEX contains slashes.
6566 For example, it is more convenient to write `s,/,-,' than `s/\//-/'.
6568 Here are several examples of `--transform' usage:
6570 1. Extract `usr/' hierarchy into `usr/local/':
6572 $ tar --transform='s,usr/,usr/local/,' -x -f arch.tar
6574 2. Strip two leading directory components (equivalent to
6575 `--strip-components=2'):
6577 $ tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar
6579 3. Prepend `/prefix/' to each file name:
6581 $ tar --transform 's,^,/prefix/,' -x -f arch.tar
6583 4. Convert each file name to lower case:
6585 $ tar --transform 's/.*/\L&/' -x -f arch.tar
6588 Unlike `--strip-components', `--transform' can be used in any GNU
6589 `tar' operation mode. For example, the following command adds files to
6590 the archive while replacing the leading `usr/' component with `var/':
6592 $ tar -cf arch.tar --transform='s,^usr/,var/,' /
6594 To test `--transform' effect we suggest using
6595 `--show-transformed-names' option:
6597 $ tar -cf arch.tar --transform='s,^usr/,var/,' \
6598 --verbose --show-transformed-names /
6600 If both `--strip-components' and `--transform' are used together,
6601 then `--transform' is applied first, and the required number of
6602 components is then stripped from its result.
6604 You can use as many `--transform' options in a single command line
6605 as you want. The specified expressions will then be applied in order
6606 of their appearance. For example, the following two invocations are
6609 $ tar -cf arch.tar --transform='s,/usr/var,/var/' \
6610 --transform='s,/usr/local,/usr/,'
6611 $ tar -cf arch.tar \
6612 --transform='s,/usr/var,/var/;s,/usr/local,/usr/,'
6615 File: tar.info, Node: after, Next: recurse, Prev: transform, Up: Choosing
6617 6.8 Operating Only on New Files
6618 ===============================
6620 _(This message will disappear, once this node revised.)_
6622 The `--after-date=DATE' (`--newer=DATE', `-N DATE') option causes `tar'
6623 to only work on files whose data modification or status change times
6624 are newer than the DATE given. If DATE starts with `/' or `.', it is
6625 taken to be a file name; the data modification time of that file is
6626 used as the date. If you use this option when creating or appending to
6627 an archive, the archive will only include new files. If you use
6628 `--after-date' when extracting an archive, `tar' will only extract
6629 files newer than the DATE you specify.
6631 If you only want `tar' to make the date comparison based on
6632 modification of the file's data (rather than status changes), then use
6633 the `--newer-mtime=DATE' option.
6635 You may use these options with any operation. Note that these
6636 options differ from the `--update' (`-u') operation in that they allow
6637 you to specify a particular date against which `tar' can compare when
6638 deciding whether or not to archive the files.
6643 Only store files newer than DATE.
6645 Acts on files only if their data modification or status change
6646 times are later than DATE. Use in conjunction with any operation.
6648 If DATE starts with `/' or `.', it is taken to be a file name; the
6649 data modification time of that file is used as the date.
6651 `--newer-mtime=DATE'
6652 Acts like `--after-date', but only looks at data modification
6655 These options limit `tar' to operate only on files which have been
6656 modified after the date specified. A file's status is considered to
6657 have changed if its contents have been modified, or if its owner,
6658 permissions, and so forth, have been changed. (For more information on
6659 how to specify a date, see *note Date input formats::; remember that the
6660 entire date argument must be quoted if it contains any spaces.)
6662 Gurus would say that `--after-date' tests both the data modification
6663 time (`mtime', the time the contents of the file were last modified)
6664 and the status change time (`ctime', the time the file's status was
6665 last changed: owner, permissions, etc.) fields, while `--newer-mtime'
6666 tests only the `mtime' field.
6668 To be precise, `--after-date' checks _both_ `mtime' and `ctime' and
6669 processes the file if either one is more recent than DATE, while
6670 `--newer-mtime' only checks `mtime' and disregards `ctime'. Neither
6671 does it use `atime' (the last time the contents of the file were looked
6674 Date specifiers can have embedded spaces. Because of this, you may
6675 need to quote date arguments to keep the shell from parsing them as
6676 separate arguments. For example, the following command will add to the
6677 archive all the files modified less than two days ago:
6679 $ tar -cf foo.tar --newer-mtime '2 days ago'
6681 When any of these options is used with the option `--verbose' (*note
6682 verbose tutorial::) GNU `tar' will try to convert the specified date
6683 back to its textual representation and compare that with the one given
6684 with the option. If the two dates differ, `tar' will print a warning
6685 saying what date it will use. This is to help user ensure he is using
6686 the right date. For example:
6688 $ tar -c -f archive.tar --after-date='10 days ago' .
6689 tar: Option --after-date: Treating date `10 days ago' as 2006-06-11
6692 *Please Note:* `--after-date' and `--newer-mtime' should not be
6693 used for incremental backups. *Note Incremental Dumps::, for
6694 proper way of creating incremental backups.
6697 File: tar.info, Node: recurse, Next: one, Prev: after, Up: Choosing
6699 6.9 Descending into Directories
6700 ===============================
6702 _(This message will disappear, once this node revised.)_
6704 Usually, `tar' will recursively explore all directories (either those
6705 given on the command line or through the `--files-from' option) for the
6706 various files they contain. However, you may not always want `tar' to
6709 The `--no-recursion' option inhibits `tar''s recursive descent into
6710 specified directories. If you specify `--no-recursion', you can use
6711 the `find' utility for hunting through levels of directories to
6712 construct a list of file names which you could then pass to `tar'.
6713 `find' allows you to be more selective when choosing which files to
6714 archive; see *note files::, for more information on using `find' with
6718 Prevents `tar' from recursively descending directories.
6721 Requires `tar' to recursively descend directories. This is the
6724 When you use `--no-recursion', GNU `tar' grabs directory entries
6725 themselves, but does not descend on them recursively. Many people use
6726 `find' for locating files they want to back up, and since `tar'
6727 _usually_ recursively descends on directories, they have to use the
6728 `-not -type d' test in their `find' invocation (*note Type:
6729 (find)Type.), as they usually do not want all the files in a directory.
6730 They then use the `--files-from' option to archive the files located
6733 The problem when restoring files archived in this manner is that the
6734 directories themselves are not in the archive; so the
6735 `--same-permissions' (`--preserve-permissions', `-p') option does not
6736 affect them--while users might really like it to. Specifying
6737 `--no-recursion' is a way to tell `tar' to grab only the directory
6738 entries given to it, adding no new files on its own. To summarize, if
6739 you use `find' to create a list of files to be stored in an archive,
6742 $ find DIR TESTS | \
6743 tar -cf ARCHIVE -T - --no-recursion
6745 The `--no-recursion' option also applies when extracting: it causes
6746 `tar' to extract only the matched directory entries, not the files
6747 under those directories.
6749 The `--no-recursion' option also affects how globbing patterns are
6750 interpreted (*note controlling pattern-matching::).
6752 The `--no-recursion' and `--recursion' options apply to later
6753 options and operands, and can be overridden by later occurrences of
6754 `--no-recursion' and `--recursion'. For example:
6756 $ tar -cf jams.tar --no-recursion grape --recursion grape/concord
6758 creates an archive with one entry for `grape', and the recursive
6759 contents of `grape/concord', but no entries under `grape' other than
6763 File: tar.info, Node: one, Prev: recurse, Up: Choosing
6765 6.10 Crossing File System Boundaries
6766 ====================================
6768 _(This message will disappear, once this node revised.)_
6770 `tar' will normally automatically cross file system boundaries in order
6771 to archive files which are part of a directory tree. You can change
6772 this behavior by running `tar' and specifying `--one-file-system'.
6773 This option only affects files that are archived because they are in a
6774 directory that is being archived; `tar' will still archive files
6775 explicitly named on the command line or through `--files-from',
6776 regardless of where they reside.
6779 Prevents `tar' from crossing file system boundaries when
6780 archiving. Use in conjunction with any write operation.
6782 The `--one-file-system' option causes `tar' to modify its normal
6783 behavior in archiving the contents of directories. If a file in a
6784 directory is not on the same file system as the directory itself, then
6785 `tar' will not archive that file. If the file is a directory itself,
6786 `tar' will not archive anything beneath it; in other words, `tar' will
6787 not cross mount points.
6789 This option is useful for making full or incremental archival
6790 backups of a file system. If this option is used in conjunction with
6791 `--verbose' (`-v'), files that are excluded are mentioned by name on
6796 * directory:: Changing Directory
6797 * absolute:: Absolute File Names
6800 File: tar.info, Node: directory, Next: absolute, Up: one
6802 6.10.1 Changing the Working Directory
6803 -------------------------------------
6805 To change the working directory in the middle of a list of file names,
6806 either on the command line or in a file specified using `--files-from'
6807 (`-T'), use `--directory' (`-C'). This will change the working
6808 directory to the specified directory after that point in the list.
6810 `--directory=DIRECTORY'
6812 Changes the working directory in the middle of a command line.
6816 $ tar -c -f jams.tar grape prune -C food cherry
6818 will place the files `grape' and `prune' from the current directory
6819 into the archive `jams.tar', followed by the file `cherry' from the
6820 directory `food'. This option is especially useful when you have
6821 several widely separated files that you want to store in the same
6824 Note that the file `cherry' is recorded in the archive under the
6825 precise name `cherry', _not_ `food/cherry'. Thus, the archive will
6826 contain three files that all appear to have come from the same
6827 directory; if the archive is extracted with plain `tar --extract', all
6828 three files will be written in the current directory.
6830 Contrast this with the command,
6832 $ tar -c -f jams.tar grape prune -C food red/cherry
6834 which records the third file in the archive under the name `red/cherry'
6835 so that, if the archive is extracted using `tar --extract', the third
6836 file will be written in a subdirectory named `orange-colored'.
6838 You can use the `--directory' option to make the archive independent
6839 of the original name of the directory holding the files. The following
6840 command places the files `/etc/passwd', `/etc/hosts', and `/lib/libc.a'
6841 into the archive `foo.tar':
6843 $ tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a
6845 However, the names of the archive members will be exactly what they were
6846 on the command line: `passwd', `hosts', and `libc.a'. They will not
6847 appear to be related by file name to the original directories where
6848 those files were located.
6850 Note that `--directory' options are interpreted consecutively. If
6851 `--directory' specifies a relative file name, it is interpreted
6852 relative to the then current directory, which might not be the same as
6853 the original current working directory of `tar', due to a previous
6854 `--directory' option.
6856 When using `--files-from' (*note files::), you can put various `tar'
6857 options (including `-C') in the file list. Notice, however, that in
6858 this case the option and its argument may not be separated by
6859 whitespace. If you use short option, its argument must either follow
6860 the option letter immediately, without any intervening whitespace, or
6861 occupy the next line. Otherwise, if you use long option, separate its
6862 argument by an equal sign.
6864 For instance, the file list for the above example will be:
6872 To use it, you would invoke `tar' as follows:
6874 $ tar -c -f foo.tar --files-from list
6876 The interpretation of `--directory' is disabled by `--null' option.
6879 File: tar.info, Node: absolute, Prev: directory, Up: one
6881 6.10.2 Absolute File Names
6882 --------------------------
6884 _(This message will disappear, once this node revised.)_
6888 Do not strip leading slashes from file names, and permit file names
6889 containing a `..' file name component.
6891 By default, GNU `tar' drops a leading `/' on input or output, and
6892 complains about file names containing a `..' component. This option
6893 turns off this behavior.
6895 When `tar' extracts archive members from an archive, it strips any
6896 leading slashes (`/') from the member name. This causes absolute
6897 member names in the archive to be treated as relative file names. This
6898 allows you to have such members extracted wherever you want, instead of
6899 being restricted to extracting the member in the exact directory named
6900 in the archive. For example, if the archive member has the name
6901 `/etc/passwd', `tar' will extract it as if the name were really
6904 File names containing `..' can cause problems when extracting, so
6905 `tar' normally warns you about such files when creating an archive, and
6906 rejects attempts to extracts such files.
6908 Other `tar' programs do not do this. As a result, if you create an
6909 archive whose member names start with a slash, they will be difficult
6910 for other people with a non-GNU `tar' program to use. Therefore, GNU
6911 `tar' also strips leading slashes from member names when putting
6912 members into the archive. For example, if you ask `tar' to add the file
6913 `/bin/ls' to an archive, it will do so, but the member name will be
6916 If you use the `--absolute-names' (`-P') option, `tar' will do none
6917 of these transformations.
6919 To archive or extract files relative to the root directory, specify
6920 the `--absolute-names' (`-P') option.
6922 Normally, `tar' acts on files relative to the working
6923 directory--ignoring superior directory names when archiving, and
6924 ignoring leading slashes when extracting.
6926 When you specify `--absolute-names' (`-P'), `tar' stores file names
6927 including all superior directory names, and preserves leading slashes.
6928 If you only invoked `tar' from the root directory you would never need
6929 the `--absolute-names' option, but using this option may be more
6930 convenient than switching to root.
6933 Preserves full file names (including superior directory names) when
6934 archiving files. Preserves leading slash when extracting files.
6937 `tar' prints out a message about removing the `/' from file names.
6938 This message appears once per GNU `tar' invocation. It represents
6939 something which ought to be told; ignoring what it means can cause very
6940 serious surprises, later.
6942 Some people, nevertheless, do not want to see this message. Wanting
6943 to play really dangerously, one may of course redirect `tar' standard
6944 error to the sink. For example, under `sh':
6946 $ tar -c -f archive.tar /home 2> /dev/null
6948 Another solution, both nicer and simpler, would be to change to the `/'
6949 directory first, and then avoid absolute notation. For example:
6951 $ (cd / && tar -c -f archive.tar home)
6953 $ tar -c -f archive.tar -C / home
6955 ---------- Footnotes ----------
6957 (1) A side effect of this is that when `--create' is used with
6958 `--verbose' the resulting output is not, generally speaking, the same
6959 as the one you'd get running `tar --list' command. This may be
6960 important if you use some scripts for comparing both outputs. *Note
6961 listing member and file names::, for the information on how to handle
6965 File: tar.info, Node: Date input formats, Next: Formats, Prev: Choosing, Up: Top
6967 7 Date input formats
6968 ********************
6972 Our units of temporal measurement, from seconds on up to months,
6973 are so complicated, asymmetrical and disjunctive so as to make
6974 coherent mental reckoning in time all but impossible. Indeed, had
6975 some tyrannical god contrived to enslave our minds to time, to
6976 make it all but impossible for us to escape subjection to sodden
6977 routines and unpleasant surprises, he could hardly have done
6978 better than handing down our present system. It is like a set of
6979 trapezoidal building blocks, with no vertical or horizontal
6980 surfaces, like a language in which the simplest thought demands
6981 ornate constructions, useless particles and lengthy
6982 circumlocutions. Unlike the more successful patterns of language
6983 and science, which enable us to face experience boldly or at least
6984 level-headedly, our system of temporal calculation silently and
6985 persistently encourages our terror of time.
6987 ... It is as though architects had to measure length in feet,
6988 width in meters and height in ells; as though basic instruction
6989 manuals demanded a knowledge of five different languages. It is
6990 no wonder then that we often look into our own immediate past or
6991 future, last Tuesday or a week from Sunday, with feelings of
6992 helpless confusion. ...
6994 -- Robert Grudin, `Time and the Art of Living'.
6996 This section describes the textual date representations that GNU
6997 programs accept. These are the strings you, as a user, can supply as
6998 arguments to the various programs. The C interface (via the `get_date'
6999 function) is not described here.
7003 * General date syntax:: Common rules.
7004 * Calendar date items:: 19 Dec 1994.
7005 * Time of day items:: 9:20pm.
7006 * Time zone items:: EST, PDT, GMT.
7007 * Day of week items:: Monday and others.
7008 * Relative items in date strings:: next tuesday, 2 years ago.
7009 * Pure numbers in date strings:: 19931219, 1440.
7010 * Seconds since the Epoch:: @1078100502.
7011 * Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
7012 * Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
7015 File: tar.info, Node: General date syntax, Next: Calendar date items, Up: Date input formats
7017 7.1 General date syntax
7018 =======================
7020 A "date" is a string, possibly empty, containing many items separated
7021 by whitespace. The whitespace may be omitted when no ambiguity arises.
7022 The empty string means the beginning of today (i.e., midnight). Order
7023 of the items is immaterial. A date string may contain many flavors of
7026 * calendar date items
7032 * day of the week items
7038 We describe each of these item types in turn, below.
7040 A few ordinal numbers may be written out in words in some contexts.
7041 This is most useful for specifying day of the week items or relative
7042 items (see below). Among the most commonly used ordinal numbers, the
7043 word `last' stands for -1, `this' stands for 0, and `first' and `next'
7044 both stand for 1. Because the word `second' stands for the unit of
7045 time there is no way to write the ordinal number 2, but for convenience
7046 `third' stands for 3, `fourth' for 4, `fifth' for 5, `sixth' for 6,
7047 `seventh' for 7, `eighth' for 8, `ninth' for 9, `tenth' for 10,
7048 `eleventh' for 11 and `twelfth' for 12.
7050 When a month is written this way, it is still considered to be
7051 written numerically, instead of being "spelled in full"; this changes
7052 the allowed strings.
7054 In the current implementation, only English is supported for words
7055 and abbreviations like `AM', `DST', `EST', `first', `January',
7056 `Sunday', `tomorrow', and `year'.
7058 The output of the `date' command is not always acceptable as a date
7059 string, not only because of the language problem, but also because
7060 there is no standard meaning for time zone items like `IST'. When using
7061 `date' to generate a date string intended to be parsed later, specify a
7062 date format that is independent of language and that does not use time
7063 zone items other than `UTC' and `Z'. Here are some ways to do this:
7065 $ LC_ALL=C TZ=UTC0 date
7066 Mon Mar 1 00:21:42 UTC 2004
7067 $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
7068 2004-03-01 00:21:42Z
7069 $ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension.
7070 2004-02-29 16:21:42,692722128-0800
7071 $ date --rfc-2822 # a GNU extension
7072 Sun, 29 Feb 2004 16:21:42 -0800
7073 $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension.
7074 2004-02-29 16:21:42 -0800
7075 $ date +'@%s.%N' # %s and %N are GNU extensions.
7076 @1078100502.692722128
7078 Alphabetic case is completely ignored in dates. Comments may be
7079 introduced between round parentheses, as long as included parentheses
7080 are properly nested. Hyphens not followed by a digit are currently
7081 ignored. Leading zeros on numbers are ignored.
7083 Invalid dates like `2005-02-29' or times like `24:00' are rejected.
7084 In the typical case of a host that does not support leap seconds, a
7085 time like `23:59:60' is rejected even if it corresponds to a valid leap
7089 File: tar.info, Node: Calendar date items, Next: Time of day items, Prev: General date syntax, Up: Date input formats
7091 7.2 Calendar date items
7092 =======================
7094 A "calendar date item" specifies a day of the year. It is specified
7095 differently, depending on whether the month is specified numerically or
7096 literally. All these strings specify the same calendar date:
7098 1972-09-24 # ISO 8601.
7099 72-9-24 # Assume 19xx for 69 through 99,
7100 # 20xx for 00 through 68.
7101 72-09-24 # Leading zeros are ignored.
7102 9/24/72 # Common U.S. writing.
7104 24 Sept 72 # September has a special abbreviation.
7105 24 Sep 72 # Three-letter abbreviations always allowed.
7110 The year can also be omitted. In this case, the last specified year
7111 is used, or the current year if none. For example:
7118 For numeric months, the ISO 8601 format `YEAR-MONTH-DAY' is allowed,
7119 where YEAR is any positive number, MONTH is a number between 01 and 12,
7120 and DAY is a number between 01 and 31. A leading zero must be present
7121 if a number is less than ten. If YEAR is 68 or smaller, then 2000 is
7122 added to it; otherwise, if YEAR is less than 100, then 1900 is added to
7123 it. The construct `MONTH/DAY/YEAR', popular in the United States, is
7124 accepted. Also `MONTH/DAY', omitting the year.
7126 Literal months may be spelled out in full: `January', `February',
7127 `March', `April', `May', `June', `July', `August', `September',
7128 `October', `November' or `December'. Literal months may be abbreviated
7129 to their first three letters, possibly followed by an abbreviating dot.
7130 It is also permitted to write `Sept' instead of `September'.
7132 When months are written literally, the calendar date may be given as
7133 any of the following:
7140 Or, omitting the year:
7145 File: tar.info, Node: Time of day items, Next: Time zone items, Prev: Calendar date items, Up: Date input formats
7147 7.3 Time of day items
7148 =====================
7150 A "time of day item" in date strings specifies the time on a given day.
7151 Here are some examples, all of which represent the same time:
7156 20:02-0500 # In EST (U.S. Eastern Standard Time).
7158 More generally, the time of day may be given as
7159 `HOUR:MINUTE:SECOND', where HOUR is a number between 0 and 23, MINUTE
7160 is a number between 0 and 59, and SECOND is a number between 0 and 59
7161 possibly followed by `.' or `,' and a fraction containing one or more
7162 digits. Alternatively, `:SECOND' can be omitted, in which case it is
7163 taken to be zero. On the rare hosts that support leap seconds, SECOND
7166 If the time is followed by `am' or `pm' (or `a.m.' or `p.m.'), HOUR
7167 is restricted to run from 1 to 12, and `:MINUTE' may be omitted (taken
7168 to be zero). `am' indicates the first half of the day, `pm' indicates
7169 the second half of the day. In this notation, 12 is the predecessor of
7170 1: midnight is `12am' while noon is `12pm'. (This is the zero-oriented
7171 interpretation of `12am' and `12pm', as opposed to the old tradition
7172 derived from Latin which uses `12m' for noon and `12pm' for midnight.)
7174 The time may alternatively be followed by a time zone correction,
7175 expressed as `SHHMM', where S is `+' or `-', HH is a number of zone
7176 hours and MM is a number of zone minutes. You can also separate HH
7177 from MM with a colon. When a time zone correction is given this way, it
7178 forces interpretation of the time relative to Coordinated Universal
7179 Time (UTC), overriding any previous specification for the time zone or
7180 the local time zone. For example, `+0530' and `+05:30' both stand for
7181 the time zone 5.5 hours ahead of UTC (e.g., India). The MINUTE part of
7182 the time of day may not be elided when a time zone correction is used.
7183 This is the best way to specify a time zone correction by fractional
7186 Either `am'/`pm' or a time zone correction may be specified, but not
7190 File: tar.info, Node: Time zone items, Next: Day of week items, Prev: Time of day items, Up: Date input formats
7195 A "time zone item" specifies an international time zone, indicated by a
7196 small set of letters, e.g., `UTC' or `Z' for Coordinated Universal
7197 Time. Any included periods are ignored. By following a
7198 non-daylight-saving time zone by the string `DST' in a separate word
7199 (that is, separated by some white space), the corresponding daylight
7200 saving time zone may be specified. Alternatively, a
7201 non-daylight-saving time zone can be followed by a time zone
7202 correction, to add the two values. This is normally done only for
7203 `UTC'; for example, `UTC+05:30' is equivalent to `+05:30'.
7205 Time zone items other than `UTC' and `Z' are obsolescent and are not
7206 recommended, because they are ambiguous; for example, `EST' has a
7207 different meaning in Australia than in the United States. Instead,
7208 it's better to use unambiguous numeric time zone corrections like
7209 `-0500', as described in the previous section.
7211 If neither a time zone item nor a time zone correction is supplied,
7212 time stamps are interpreted using the rules of the default time zone
7213 (*note Specifying time zone rules::).
7216 File: tar.info, Node: Day of week items, Next: Relative items in date strings, Prev: Time zone items, Up: Date input formats
7218 7.5 Day of week items
7219 =====================
7221 The explicit mention of a day of the week will forward the date (only
7222 if necessary) to reach that day of the week in the future.
7224 Days of the week may be spelled out in full: `Sunday', `Monday',
7225 `Tuesday', `Wednesday', `Thursday', `Friday' or `Saturday'. Days may
7226 be abbreviated to their first three letters, optionally followed by a
7227 period. The special abbreviations `Tues' for `Tuesday', `Wednes' for
7228 `Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed.
7230 A number may precede a day of the week item to move forward
7231 supplementary weeks. It is best used in expression like `third
7232 monday'. In this context, `last DAY' or `next DAY' is also acceptable;
7233 they move one week before or after the day that DAY by itself would
7236 A comma following a day of the week item is ignored.
7239 File: tar.info, Node: Relative items in date strings, Next: Pure numbers in date strings, Prev: Day of week items, Up: Date input formats
7241 7.6 Relative items in date strings
7242 ==================================
7244 "Relative items" adjust a date (or the current date if none) forward or
7245 backward. The effects of relative items accumulate. Here are some
7253 The unit of time displacement may be selected by the string `year'
7254 or `month' for moving by whole years or months. These are fuzzy units,
7255 as years and months are not all of equal duration. More precise units
7256 are `fortnight' which is worth 14 days, `week' worth 7 days, `day'
7257 worth 24 hours, `hour' worth 60 minutes, `minute' or `min' worth 60
7258 seconds, and `second' or `sec' worth one second. An `s' suffix on
7259 these units is accepted and ignored.
7261 The unit of time may be preceded by a multiplier, given as an
7262 optionally signed number. Unsigned numbers are taken as positively
7263 signed. No number at all implies 1 for a multiplier. Following a
7264 relative item by the string `ago' is equivalent to preceding the unit
7265 by a multiplier with value -1.
7267 The string `tomorrow' is worth one day in the future (equivalent to
7268 `day'), the string `yesterday' is worth one day in the past (equivalent
7271 The strings `now' or `today' are relative items corresponding to
7272 zero-valued time displacement, these strings come from the fact a
7273 zero-valued time displacement represents the current time when not
7274 otherwise changed by previous items. They may be used to stress other
7275 items, like in `12:00 today'. The string `this' also has the meaning
7276 of a zero-valued time displacement, but is preferred in date strings
7277 like `this thursday'.
7279 When a relative item causes the resulting date to cross a boundary
7280 where the clocks were adjusted, typically for daylight saving time, the
7281 resulting date and time are adjusted accordingly.
7283 The fuzz in units can cause problems with relative items. For
7284 example, `2003-07-31 -1 month' might evaluate to 2003-07-01, because
7285 2003-06-31 is an invalid date. To determine the previous month more
7286 reliably, you can ask for the month before the 15th of the current
7290 Thu, 31 Jul 2003 13:02:39 -0700
7291 $ date --date='-1 month' +'Last month was %B?'
7292 Last month was July?
7293 $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
7294 Last month was June!
7296 Also, take care when manipulating dates around clock changes such as
7297 daylight saving leaps. In a few cases these have added or subtracted
7298 as much as 24 hours from the clock, so it is often wise to adopt
7299 universal time by setting the `TZ' environment variable to `UTC0'
7300 before embarking on calendrical calculations.
7303 File: tar.info, Node: Pure numbers in date strings, Next: Seconds since the Epoch, Prev: Relative items in date strings, Up: Date input formats
7305 7.7 Pure numbers in date strings
7306 ================================
7308 The precise interpretation of a pure decimal number depends on the
7309 context in the date string.
7311 If the decimal number is of the form YYYYMMDD and no other calendar
7312 date item (*note Calendar date items::) appears before it in the date
7313 string, then YYYY is read as the year, MM as the month number and DD as
7314 the day of the month, for the specified calendar date.
7316 If the decimal number is of the form HHMM and no other time of day
7317 item appears before it in the date string, then HH is read as the hour
7318 of the day and MM as the minute of the hour, for the specified time of
7319 day. MM can also be omitted.
7321 If both a calendar date and a time of day appear to the left of a
7322 number in the date string, but no relative item, then the number
7326 File: tar.info, Node: Seconds since the Epoch, Next: Specifying time zone rules, Prev: Pure numbers in date strings, Up: Date input formats
7328 7.8 Seconds since the Epoch
7329 ===========================
7331 If you precede a number with `@', it represents an internal time stamp
7332 as a count of seconds. The number can contain an internal decimal
7333 point (either `.' or `,'); any excess precision not supported by the
7334 internal representation is truncated toward minus infinity. Such a
7335 number cannot be combined with any other date item, as it specifies a
7336 complete time stamp.
7338 Internally, computer times are represented as a count of seconds
7339 since an epoch--a well-defined point of time. On GNU and POSIX
7340 systems, the epoch is 1970-01-01 00:00:00 UTC, so `@0' represents this
7341 time, `@1' represents 1970-01-01 00:00:01 UTC, and so forth. GNU and
7342 most other POSIX-compliant systems support such times as an extension
7343 to POSIX, using negative counts, so that `@-1' represents 1969-12-31
7346 Traditional Unix systems count seconds with 32-bit two's-complement
7347 integers and can represent times from 1901-12-13 20:45:52 through
7348 2038-01-19 03:14:07 UTC. More modern systems use 64-bit counts of
7349 seconds with nanosecond subcounts, and can represent all the times in
7350 the known lifetime of the universe to a resolution of 1 nanosecond.
7352 On most hosts, these counts ignore the presence of leap seconds.
7353 For example, on most hosts `@915148799' represents 1998-12-31 23:59:59
7354 UTC, `@915148800' represents 1999-01-01 00:00:00 UTC, and there is no
7355 way to represent the intervening leap second 1998-12-31 23:59:60 UTC.
7358 File: tar.info, Node: Specifying time zone rules, Next: Authors of get_date, Prev: Seconds since the Epoch, Up: Date input formats
7360 7.9 Specifying time zone rules
7361 ==============================
7363 Normally, dates are interpreted using the rules of the current time
7364 zone, which in turn are specified by the `TZ' environment variable, or
7365 by a system default if `TZ' is not set. To specify a different set of
7366 default time zone rules that apply just to one date, start the date
7367 with a string of the form `TZ="RULE"'. The two quote characters (`"')
7368 must be present in the date, and any quotes or backslashes within RULE
7369 must be escaped by a backslash.
7371 For example, with the GNU `date' command you can answer the question
7372 "What time is it in New York when a Paris clock shows 6:30am on October
7373 31, 2004?" by using a date beginning with `TZ="Europe/Paris"' as shown
7374 in the following shell transcript:
7376 $ export TZ="America/New_York"
7377 $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
7378 Sun Oct 31 01:30:00 EDT 2004
7380 In this example, the `--date' operand begins with its own `TZ'
7381 setting, so the rest of that operand is processed according to
7382 `Europe/Paris' rules, treating the string `2004-10-31 06:30' as if it
7383 were in Paris. However, since the output of the `date' command is
7384 processed according to the overall time zone rules, it uses New York
7385 time. (Paris was normally six hours ahead of New York in 2004, but
7386 this example refers to a brief Halloween period when the gap was five
7389 A `TZ' value is a rule that typically names a location in the `tz'
7390 database (http://www.twinsun.com/tz/tz-link.htm). A recent catalog of
7391 location names appears in the TWiki Date and Time Gateway
7392 (http://twiki.org/cgi-bin/xtra/tzdate). A few non-GNU hosts require a
7393 colon before a location name in a `TZ' setting, e.g.,
7394 `TZ=":America/New_York"'.
7396 The `tz' database includes a wide variety of locations ranging from
7397 `Arctic/Longyearbyen' to `Antarctica/South_Pole', but if you are at sea
7398 and have your own private time zone, or if you are using a non-GNU host
7399 that does not support the `tz' database, you may need to use a POSIX
7400 rule instead. Simple POSIX rules like `UTC0' specify a time zone
7401 without daylight saving time; other rules can specify simple daylight
7402 saving regimes. *Note Specifying the Time Zone with `TZ': (libc)TZ
7406 File: tar.info, Node: Authors of get_date, Prev: Specifying time zone rules, Up: Date input formats
7408 7.10 Authors of `get_date'
7409 ==========================
7411 `get_date' was originally implemented by Steven M. Bellovin
7412 (<smb@research.att.com>) while at the University of North Carolina at
7413 Chapel Hill. The code was later tweaked by a couple of people on
7414 Usenet, then completely overhauled by Rich $alz (<rsalz@bbn.com>) and
7415 Jim Berets (<jberets@bbn.com>) in August, 1990. Various revisions for
7416 the GNU system were made by David MacKenzie, Jim Meyering, Paul Eggert
7419 This chapter was originally produced by Franc,ois Pinard
7420 (<pinard@iro.umontreal.ca>) from the `getdate.y' source code, and then
7421 edited by K. Berry (<kb@cs.umb.edu>).
7424 File: tar.info, Node: Formats, Next: Media, Prev: Date input formats, Up: Top
7426 8 Controlling the Archive Format
7427 ********************************
7429 Due to historical reasons, there are several formats of tar archives.
7430 All of them are based on the same principles, but have some subtle
7431 differences that often make them incompatible with each other.
7433 GNU tar is able to create and handle archives in a variety of
7434 formats. The most frequently used formats are (in alphabetical order):
7437 Format used by GNU `tar' versions up to 1.13.25. This format
7438 derived from an early POSIX standard, adding some improvements
7439 such as sparse file handling and incremental archives.
7440 Unfortunately these features were implemented in a way
7441 incompatible with other archive formats.
7443 Archives in `gnu' format are able to hold file names of unlimited
7447 Format used by GNU `tar' of versions prior to 1.12.
7450 Archive format, compatible with the V7 implementation of tar. This
7451 format imposes a number of limitations. The most important of them
7454 1. The maximum length of a file name is limited to 99 characters.
7456 2. The maximum length of a symbolic link is limited to 99
7459 3. It is impossible to store special files (block and character
7460 devices, fifos etc.)
7462 4. Maximum value of user or group ID is limited to 2097151
7465 5. V7 archives do not contain symbolic ownership information
7466 (user and group name of the file owner).
7468 This format has traditionally been used by Automake when producing
7469 Makefiles. This practice will change in the future, in the
7470 meantime, however this means that projects containing file names
7471 more than 99 characters long will not be able to use GNU `tar'
7472 1.20 and Automake prior to 1.9.
7475 Archive format defined by POSIX.1-1988 specification. It stores
7476 symbolic ownership information. It is also able to store special
7477 files. However, it imposes several restrictions as well:
7479 1. The maximum length of a file name is limited to 256
7480 characters, provided that the file name can be split at a
7481 directory separator in two parts, first of them being at most
7482 155 bytes long. So, in most cases the maximum file name
7483 length will be shorter than 256 characters.
7485 2. The maximum length of a symbolic link name is limited to 100
7488 3. Maximum size of a file the archive is able to accommodate is
7491 4. Maximum value of UID/GID is 2097151.
7493 5. Maximum number of bits in device major and minor numbers is
7497 Format used by Jo"rg Schilling `star' implementation. GNU `tar'
7498 is able to read `star' archives but currently does not produce
7502 Archive format defined by POSIX.1-2001 specification. This is the
7503 most flexible and feature-rich format. It does not impose any
7504 restrictions on file sizes or file name lengths. This format is
7505 quite recent, so not all tar implementations are able to handle it
7506 properly. However, this format is designed in such a way that any
7507 tar implementation able to read `ustar' archives will be able to
7508 read most `posix' archives as well, with the only exception that
7509 any additional information (such as long file names etc.) will in
7510 such case be extracted as plain text files along with the files it
7513 This archive format will be the default format for future versions
7517 The following table summarizes the limitations of each of these
7520 Format UID File Size File Name Devn
7521 --------------------------------------------------------------------
7522 gnu 1.8e19 Unlimited Unlimited 63
7523 oldgnu 1.8e19 Unlimited Unlimited 63
7524 v7 2097151 8GB 99 n/a
7525 ustar 2097151 8GB 256 21
7526 posix Unlimited Unlimited Unlimited Unlimited
7528 The default format for GNU `tar' is defined at compilation time.
7529 You may check it by running `tar --help', and examining the last lines
7530 of its output. Usually, GNU `tar' is configured to create archives in
7531 `gnu' format, however, future version will switch to `posix'.
7535 * Compression:: Using Less Space through Compression
7536 * Attributes:: Handling File Attributes
7537 * Portability:: Making `tar' Archives More Portable
7538 * cpio:: Comparison of `tar' and `cpio'
7541 File: tar.info, Node: Compression, Next: Attributes, Up: Formats
7543 8.1 Using Less Space through Compression
7544 ========================================
7548 * gzip:: Creating and Reading Compressed Archives
7549 * sparse:: Archiving Sparse Files
7552 File: tar.info, Node: gzip, Next: sparse, Up: Compression
7554 8.1.1 Creating and Reading Compressed Archives
7555 ----------------------------------------------
7557 GNU `tar' is able to create and read compressed archives. It supports
7558 `gzip', `bzip2' and `lzma' compression programs. For backward
7559 compatibility, it also supports `compress' command, although we
7560 strongly recommend against using it, because it is by far less
7561 effective than other compression programs(1).
7563 Creating a compressed archive is simple: you just specify a
7564 "compression option" along with the usual archive creation commands.
7565 The compression option is `-z' (`--gzip') to create a `gzip' compressed
7566 archive, `-j' (`--bzip2') to create a `bzip2' compressed archive,
7567 `--lzma' to create an LZMA compressed archive and `-Z' (`--compress')
7568 to use `compress' program. For example:
7570 $ tar cfz archive.tar.gz .
7572 You can also let GNU `tar' select the compression program basing on
7573 the suffix of the archive file name. This is done using
7574 `--auto-compress' (`-a') command line option. For example, the
7575 following invocation will use `bzip2' for compression:
7577 $ tar cfa archive.tar.bz2 .
7579 whereas the following one will use `lzma':
7581 $ tar cfa archive.tar.lzma .
7583 For a complete list of file name suffixes recognized by GNU `tar',
7584 *note auto-compress::.
7586 Reading compressed archive is even simpler: you don't need to specify
7587 any additional options as GNU `tar' recognizes its format
7588 automatically. Thus, the following commands will list and extract the
7589 archive created in previous example:
7591 # List the compressed archive
7592 $ tar tf archive.tar.gz
7593 # Extract the compressed archive
7594 $ tar xf archive.tar.gz
7596 The only case when you have to specify a decompression option while
7597 reading the archive is when reading from a pipe or from a tape drive
7598 that does not support random access. However, in this case GNU `tar'
7599 will indicate which option you should use. For example:
7601 $ cat archive.tar.gz | tar tf -
7602 tar: Archive is compressed. Use -z option
7603 tar: Error is not recoverable: exiting now
7605 If you see such diagnostics, just add the suggested option to the
7606 invocation of GNU `tar':
7608 $ cat archive.tar.gz | tar tfz -
7610 Notice also, that there are several restrictions on operations on
7611 compressed archives. First of all, compressed archives cannot be
7612 modified, i.e., you cannot update (`--update' (`-u')) them or delete
7613 (`--delete') members from them or add (`--append' (`-r')) members to
7614 them. Likewise, you cannot append another `tar' archive to a
7615 compressed archive using `--concatenate' (`-A')). Secondly,
7616 multi-volume archives cannot be compressed.
7618 The following table summarizes compression options used by GNU `tar'.
7622 Select a compression program to use by the archive file name
7623 suffix. The following suffixes are recognized:
7625 Suffix Compression program
7626 --------------------------------------------------------------
7642 Filter the archive through `gzip'.
7644 You can use `--gzip' and `--gunzip' on physical devices (tape
7645 drives, etc.) and remote files as well as on normal files; data to
7646 or from such devices or remote files is reblocked by another copy
7647 of the `tar' program to enforce the specified (or default) record
7648 size. The default compression parameters are used; if you need to
7649 override them, set `GZIP' environment variable, e.g.:
7651 $ GZIP=--best tar cfz archive.tar.gz subdir
7653 Another way would be to avoid the `--gzip' (`--gunzip',
7654 `--ungzip', `-z') option and run `gzip' explicitly:
7656 $ tar cf - subdir | gzip --best -c - > archive.tar.gz
7658 About corrupted compressed archives: `gzip''ed files have no
7659 redundancy, for maximum compression. The adaptive nature of the
7660 compression scheme means that the compression tables are implicitly
7661 spread all over the archive. If you lose a few blocks, the dynamic
7662 construction of the compression tables becomes unsynchronized, and
7663 there is little chance that you could recover later in the archive.
7665 There are pending suggestions for having a per-volume or per-file
7666 compression in GNU `tar'. This would allow for viewing the
7667 contents without decompression, and for resynchronizing
7668 decompression at every volume or file, in case of corrupted
7669 archives. Doing so, we might lose some compressibility. But this
7670 would have make recovering easier. So, there are pros and cons.
7675 Filter the archive through `bzip2'. Otherwise like `--gzip'.
7678 Filter the archive through `lzma'. Otherwise like `--gzip'.
7683 Filter the archive through `compress'. Otherwise like `--gzip'.
7685 `--use-compress-program=PROG'
7686 Use external compression program PROG. Use this option if you
7687 have a compression program that GNU `tar' does not support. There
7688 are two requirements to which PROG should comply:
7690 First, when called without options, it should read data from
7691 standard input, compress it and output it on standard output.
7693 Secondly, if called with `-d' argument, it should do exactly the
7694 opposite, i.e., read the compressed data from the standard input
7695 and produce uncompressed data on the standard output.
7697 The `--use-compress-program' option, in particular, lets you
7698 implement your own filters, not necessarily dealing with
7699 compression/decompression. For example, suppose you wish to implement
7700 PGP encryption on top of compression, using `gpg' (*note gpg:
7701 (gpg)Top.). The following script does that:
7705 -d) gpg --decrypt - | gzip -d -c;;
7706 '') gzip -c | gpg -s ;;
7707 *) echo "Unknown option $1">&2; exit 1;;
7710 Suppose you name it `gpgz' and save it somewhere in your `PATH'.
7711 Then the following command will create a compressed archive signed with
7714 $ tar -cf foo.tar.gpgz --use-compress=gpgz .
7716 Likewise, the following command will list its contents:
7718 $ tar -tf foo.tar.gpgz --use-compress=gpgz .
7720 ---------- Footnotes ----------
7722 (1) It also had patent problems in the past.
projects / tar / blob