1 This is tar.info, produced by makeinfo version 4.13 from tar.texi.
3 This manual is for GNU `tar' (version 1.23, 9 March 2010), 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, 2009, 2010 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.23, 9 March 2010), 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, 2009, 2010 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::
144 The Three Option Styles
146 * Long Options:: Long Option Style
147 * Short Options:: Short Option Style
148 * Old Options:: Old Option Style
149 * Mixing:: Mixing Option Styles
153 * Operation Summary::
155 * Short Option Summary::
167 Advanced GNU `tar' Operations
176 How to Add Files to Existing Archives: `--append'
178 * appending files:: Appending Files to an Archive
185 Options Used by `--create'
187 * override:: Overriding File Metadata.
188 * Ignore Failed Read::
190 Options Used by `--extract'
192 * Reading:: Options to Help Read Archives
193 * Writing:: Changing How `tar' Writes Files
194 * Scarce:: Coping with Scarce Resources
196 Options to Help Read Archives
198 * read full records::
201 Changing How `tar' Writes Files
203 * Dealing with Old Files::
204 * Overwrite Old Files::
209 * Data Modification Times::
210 * Setting Access Permissions::
211 * Directory Modification Times and Permissions::
212 * Writing to Standard Output::
213 * Writing to an External Program::
216 Coping with Scarce Resources
221 Performing Backups and Restoring Files
223 * Full Dumps:: Using `tar' to Perform Full Dumps
224 * Incremental Dumps:: Using `tar' to Perform Incremental Dumps
225 * Backup Levels:: Levels of Backups
226 * Backup Parameters:: Setting Parameters for Backups and Restoration
227 * Scripted Backups:: Using the Backup Scripts
228 * Scripted Restoration:: Using the Restore Script
230 Setting Parameters for Backups and Restoration
232 * General-Purpose Variables::
233 * Magnetic Tape Control::
235 * backup-specs example:: An Example Text of `Backup-specs'
237 Choosing Files and Names for `tar'
239 * file:: Choosing the Archive's Name
240 * Selecting Archive Members::
241 * files:: Reading Names from a File
242 * exclude:: Excluding Some Files
243 * wildcards:: Wildcards Patterns and Matching
244 * quoting styles:: Ways of Quoting Special Characters in Names
245 * transform:: Modifying File and Member Names
246 * after:: Operating Only on New Files
247 * recurse:: Descending into Directories
248 * one:: Crossing File System Boundaries
250 Reading Names from a File
256 * problems with exclude::
258 Wildcards Patterns and Matching
260 * controlling pattern-matching::
262 Crossing File System Boundaries
264 * directory:: Changing Directory
265 * absolute:: Absolute File Names
269 * General date syntax:: Common rules.
270 * Calendar date items:: 19 Dec 1994.
271 * Time of day items:: 9:20pm.
272 * Time zone items:: EST, PDT, GMT.
273 * Day of week items:: Monday and others.
274 * Relative items in date strings:: next tuesday, 2 years ago.
275 * Pure numbers in date strings:: 19931219, 1440.
276 * Seconds since the Epoch:: @1078100502.
277 * Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
278 * Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
280 Controlling the Archive Format
282 * Compression:: Using Less Space through Compression
283 * Attributes:: Handling File Attributes
284 * Portability:: Making `tar' Archives More Portable
285 * cpio:: Comparison of `tar' and `cpio'
287 Using Less Space through Compression
289 * gzip:: Creating and Reading Compressed Archives
290 * sparse:: Archiving Sparse Files
292 Making `tar' Archives More Portable
294 * Portable Names:: Portable Names
295 * dereference:: Symbolic Links
296 * hard links:: Hard Links
297 * old:: Old V7 Archives
298 * ustar:: Ustar Archives
299 * gnu:: GNU and old GNU format archives.
300 * posix:: POSIX archives
301 * Checksumming:: Checksumming Problems
302 * Large or Negative Values:: Large files, negative time stamps, etc.
303 * Other Tars:: How to Extract GNU-Specific Data Using
304 Other `tar' Implementations
306 GNU `tar' and POSIX `tar'
308 * PAX keywords:: Controlling Extended Header Keywords.
310 How to Extract GNU-Specific Data Using Other `tar' Implementations
312 * Split Recovery:: Members Split Between Volumes
313 * Sparse Recovery:: Sparse Members
315 Tapes and Other Archive Media
317 * Device:: Device selection and switching
318 * Remote Tape Server::
319 * Common Problems and Solutions::
320 * Blocking:: Blocking
321 * Many:: Many archives on one tape
322 * Using Multiple Tapes:: Using Multiple Tapes
323 * label:: Including a Label in the Archive
329 * Format Variations:: Format Variations
330 * Blocking Factor:: The Blocking Factor of an Archive
332 Many Archives on One Tape
334 * Tape Positioning:: Tape Positions and Tape Marks
335 * mt:: The `mt' Utility
339 * Multi-Volume Archives:: Archives Longer than One Tape or Disk
340 * Tape Files:: Tape Files
341 * Tarcat:: Concatenate Volumes into a Single Archive
346 * Standard:: Basic Tar Format
347 * Extensions:: GNU Extensions to the Archive Format
348 * Sparse Formats:: Storing Sparse Files
355 * PAX 0:: PAX Format, Versions 0.0 and 0.1
356 * PAX 1:: PAX Format, Version 1.0
360 * Generate Mode:: File Generation Mode.
361 * Status Mode:: File Status Mode.
362 * Exec Mode:: Synchronous Execution mode.
366 * GNU Free Documentation License:: License for copying this manual
369 File: tar.info, Node: Introduction, Next: Tutorial, Prev: Top, Up: Top
374 GNU `tar' creates and manipulates "archives" which are actually
375 collections of many other files; the program provides users with an
376 organized and systematic method for controlling a large amount of data.
377 The name "tar" originally came from the phrase "Tape ARchive", but
378 archives need not (and these days, typically do not) reside on tapes.
382 * Book Contents:: What this Book Contains
383 * Definitions:: Some Definitions
384 * What tar Does:: What `tar' Does
385 * Naming tar Archives:: How `tar' Archives are Named
386 * Authors:: GNU `tar' Authors
387 * Reports:: Reporting bugs or suggestions
390 File: tar.info, Node: Book Contents, Next: Definitions, Up: Introduction
392 1.1 What this Book Contains
393 ===========================
395 The first part of this chapter introduces you to various terms that will
396 recur throughout the book. It also tells you who has worked on GNU
397 `tar' and its documentation, and where you should send bug reports or
400 The second chapter is a tutorial (*note Tutorial::) which provides a
401 gentle introduction for people who are new to using `tar'. It is meant
402 to be self-contained, not requiring any reading from subsequent
403 chapters to make sense. It moves from topic to topic in a logical,
404 progressive order, building on information already explained.
406 Although the tutorial is paced and structured to allow beginners to
407 learn how to use `tar', it is not intended solely for beginners. The
408 tutorial explains how to use the three most frequently used operations
409 (`create', `list', and `extract') as well as two frequently used
410 options (`file' and `verbose'). The other chapters do not refer to the
411 tutorial frequently; however, if a section discusses something which is
412 a complex variant of a basic concept, there may be a cross reference to
413 that basic concept. (The entire book, including the tutorial, assumes
414 that the reader understands some basic concepts of using a Unix-type
415 operating system; *note Tutorial::.)
417 The third chapter presents the remaining five operations, and
418 information about using `tar' options and option syntax.
420 The other chapters are meant to be used as a reference. Each chapter
421 presents everything that needs to be said about a specific topic.
423 One of the chapters (*note Date input formats::) exists in its
424 entirety in other GNU manuals, and is mostly self-contained. In
425 addition, one section of this manual (*note Standard::) contains a big
426 quote which is taken directly from `tar' sources.
428 In general, we give both long and short (abbreviated) option names
429 at least once in each section where the relevant option is covered, so
430 that novice readers will become familiar with both styles. (A few
431 options have no short versions, and the relevant sections will indicate
435 File: tar.info, Node: Definitions, Next: What tar Does, Prev: Book Contents, Up: Introduction
440 The `tar' program is used to create and manipulate `tar' archives. An
441 "archive" is a single file which contains the contents of many files,
442 while still identifying the names of the files, their owner(s), and so
443 forth. (In addition, archives record access permissions, user and
444 group, size in bytes, and data modification time. Some archives also
445 record the file names in each archived directory, as well as other file
446 and directory information.) You can use `tar' to "create" a new
447 archive in a specified directory.
449 The files inside an archive are called "members". Within this
450 manual, we use the term "file" to refer only to files accessible in the
451 normal ways (by `ls', `cat', and so forth), and the term "member" to
452 refer only to the members of an archive. Similarly, a "file name" is
453 the name of a file, as it resides in the file system, and a "member
454 name" is the name of an archive member within the archive.
456 The term "extraction" refers to the process of copying an archive
457 member (or multiple members) into a file in the file system. Extracting
458 all the members of an archive is often called "extracting the archive".
459 The term "unpack" can also be used to refer to the extraction of many
460 or all the members of an archive. Extracting an archive does not
461 destroy the archive's structure, just as creating an archive does not
462 destroy the copies of the files that exist outside of the archive. You
463 may also "list" the members in a given archive (this is often thought
464 of as "printing" them to the standard output, or the command line), or
465 "append" members to a pre-existing archive. All of these operations
466 can be performed using `tar'.
469 File: tar.info, Node: What tar Does, Next: Naming tar Archives, Prev: Definitions, Up: Introduction
474 The `tar' program provides the ability to create `tar' archives, as
475 well as various other kinds of manipulation. For example, you can use
476 `tar' on previously created archives to extract files, to store
477 additional files, or to update or list files which were already stored.
479 Initially, `tar' archives were used to store files conveniently on
480 magnetic tape. The name `tar' comes from this use; it stands for
481 `t'ape `ar'chiver. Despite the utility's name, `tar' can direct its
482 output to available devices, files, or other programs (using pipes).
483 `tar' may even access remote devices or files (as archives).
485 You can use `tar' archives in many ways. We want to stress a few of
486 them: storage, backup, and transportation.
489 Often, `tar' archives are used to store related files for
490 convenient file transfer over a network. For example, the GNU
491 Project distributes its software bundled into `tar' archives, so
492 that all the files relating to a particular program (or set of
493 related programs) can be transferred as a single unit.
495 A magnetic tape can store several files in sequence. However, the
496 tape has no names for these files; it only knows their relative
497 position on the tape. One way to store several files on one tape
498 and retain their names is by creating a `tar' archive. Even when
499 the basic transfer mechanism can keep track of names, as FTP can,
500 the nuisance of handling multiple files, directories, and multiple
501 links makes `tar' archives useful.
503 Archive files are also used for long-term storage. You can think
504 of this as transportation from the present into the future. (It
505 is a science-fiction idiom that you can move through time as well
506 as in space; the idea here is that `tar' can be used to move
507 archives in all dimensions, even time!)
510 Because the archive created by `tar' is capable of preserving file
511 information and directory structure, `tar' is commonly used for
512 performing full and incremental backups of disks. A backup puts a
513 collection of files (possibly pertaining to many users and
514 projects) together on a disk or a tape. This guards against
515 accidental destruction of the information in those files. GNU
516 `tar' has special features that allow it to be used to make
517 incremental and full dumps of all the files in a file system.
520 You can create an archive on one system, transfer it to another
521 system, and extract the contents there. This allows you to
522 transport a group of files from one system to another.
525 File: tar.info, Node: Naming tar Archives, Next: Authors, Prev: What tar Does, Up: Introduction
527 1.4 How `tar' Archives are Named
528 ================================
530 Conventionally, `tar' archives are given names ending with `.tar'.
531 This is not necessary for `tar' to operate properly, but this manual
532 follows that convention in order to accustom readers to it and to make
535 Often, people refer to `tar' archives as "`tar' files," and archive
536 members as "files" or "entries". For people familiar with the
537 operation of `tar', this causes no difficulty. However, in this
538 manual, we consistently refer to "archives" and "archive members" to
539 make learning to use `tar' easier for novice users.
542 File: tar.info, Node: Authors, Next: Reports, Prev: Naming tar Archives, Up: Introduction
544 1.5 GNU `tar' Authors
545 =====================
547 GNU `tar' was originally written by John Gilmore, and modified by many
548 people. The GNU enhancements were written by Jay Fenlason, then Joy
549 Kendall, and the whole package has been further maintained by Thomas
550 Bushnell, n/BSG, Franc,ois Pinard, Paul Eggert, and finally Sergey
551 Poznyakoff with the help of numerous and kind users.
553 We wish to stress that `tar' is a collective work, and owes much to
554 all those people who reported problems, offered solutions and other
555 insights, or shared their thoughts and suggestions. An impressive, yet
556 partial list of those contributors can be found in the `THANKS' file
557 from the GNU `tar' distribution.
559 Jay Fenlason put together a draft of a GNU `tar' manual, borrowing
560 notes from the original man page from John Gilmore. This was withdrawn
561 in version 1.11. Thomas Bushnell, n/BSG and Amy Gorin worked on a
562 tutorial and manual for GNU `tar'. Franc,ois Pinard put version 1.11.8
563 of the manual together by taking information from all these sources and
564 merging them. Melissa Weisshaus finally edited and redesigned the book
565 to create version 1.12. The book for versions from 1.14 up to 1.23
566 were edited by the current maintainer, Sergey Poznyakoff.
568 For version 1.12, Daniel Hagerty contributed a great deal of
569 technical consulting. In particular, he is the primary author of *note
572 In July, 2003 GNU `tar' was put on CVS at savannah.gnu.org (see
573 `http://savannah.gnu.org/projects/tar'), and active development and
574 maintenance work has started again. Currently GNU `tar' is being
575 maintained by Paul Eggert, Sergey Poznyakoff and Jeff Bailey.
577 Support for POSIX archives was added by Sergey Poznyakoff.
580 File: tar.info, Node: Reports, Prev: Authors, Up: Introduction
582 1.6 Reporting bugs or suggestions
583 =================================
585 If you find problems or have suggestions about this program or manual,
586 please report them to `bug-tar@gnu.org'.
588 When reporting a bug, please be sure to include as much detail as
589 possible, in order to reproduce it.
592 File: tar.info, Node: Tutorial, Next: tar invocation, Prev: Introduction, Up: Top
594 2 Tutorial Introduction to `tar'
595 ********************************
597 This chapter guides you through some basic examples of three `tar'
598 operations: `--create', `--list', and `--extract'. If you already know
599 how to use some other version of `tar', then you may not need to read
600 this chapter. This chapter omits most complicated details about how
606 * stylistic conventions::
607 * basic tar options:: Basic `tar' Operations and Options
608 * frequent operations::
609 * Two Frequent Options::
610 * create:: How to Create Archives
611 * list:: How to List Archives
612 * extract:: How to Extract Members from an Archive
616 File: tar.info, Node: assumptions, Next: stylistic conventions, Up: Tutorial
618 2.1 Assumptions this Tutorial Makes
619 ===================================
621 This chapter is paced to allow beginners to learn about `tar' slowly.
622 At the same time, we will try to cover all the basic aspects of these
623 three operations. In order to accomplish both of these tasks, we have
624 made certain assumptions about your knowledge before reading this
625 manual, and the hardware you will be using:
627 * Before you start to work through this tutorial, you should
628 understand what the terms "archive" and "archive member" mean
629 (*note Definitions::). In addition, you should understand
630 something about how Unix-type operating systems work, and you
631 should know how to use some basic utilities. For example, you
632 should know how to create, list, copy, rename, edit, and delete
633 files and directories; how to change between directories; and how
634 to figure out where you are in the file system. You should have
635 some basic understanding of directory structure and how files are
636 named according to which directory they are in. You should
637 understand concepts such as standard output and standard input,
638 what various definitions of the term `argument' mean, and the
639 differences between relative and absolute file names.
641 * This manual assumes that you are working from your own home
642 directory (unless we state otherwise). In this tutorial, you will
643 create a directory to practice `tar' commands in. When we show
644 file names, we will assume that those names are relative to your
645 home directory. For example, my home directory is
646 `/home/fsf/melissa'. All of my examples are in a subdirectory of
647 the directory named by that file name; the subdirectory is called
650 * In general, we show examples of archives which exist on (or can be
651 written to, or worked with from) a directory on a hard disk. In
652 most cases, you could write those archives to, or work with them
653 on any other device, such as a tape drive. However, some of the
654 later examples in the tutorial and next chapter will not work on
655 tape drives. Additionally, working with tapes is much more
656 complicated than working with hard disks. For these reasons, the
657 tutorial does not cover working with tape drives. *Note Media::,
658 for complete information on using `tar' archives with tape drives.
662 File: tar.info, Node: stylistic conventions, Next: basic tar options, Prev: assumptions, Up: Tutorial
664 2.2 Stylistic Conventions
665 =========================
667 In the examples, `$' represents a typical shell prompt. It precedes
668 lines you should type; to make this more clear, those lines are shown
669 in `this font', as opposed to lines which represent the computer's
670 response; those lines are shown in `this font', or sometimes `like
674 File: tar.info, Node: basic tar options, Next: frequent operations, Prev: stylistic conventions, Up: Tutorial
676 2.3 Basic `tar' Operations and Options
677 ======================================
679 `tar' can take a wide variety of arguments which specify and define the
680 actions it will have on the particular set of files or the archive.
681 The main types of arguments to `tar' fall into one of two classes:
682 operations, and options.
684 Some arguments fall into a class called "operations"; exactly one of
685 these is both allowed and required for any instance of using `tar'; you
686 may _not_ specify more than one. People sometimes speak of "operating
687 modes". You are in a particular operating mode when you have specified
688 the operation which specifies it; there are eight operations in total,
689 and thus there are eight operating modes.
691 The other arguments fall into the class known as "options". You are
692 not required to specify any options, and you are allowed to specify more
693 than one at a time (depending on the way you are using `tar' at that
694 time). Some options are used so frequently, and are so useful for
695 helping you type commands more carefully that they are effectively
696 "required". We will discuss them in this chapter.
698 You can write most of the `tar' operations and options in any of
699 three forms: long (mnemonic) form, short form, and old style. Some of
700 the operations and options have no short or "old" forms; however, the
701 operations and options which we will cover in this tutorial have
702 corresponding abbreviations. We will indicate those abbreviations
703 appropriately to get you used to seeing them. Note, that the "old
704 style" option forms exist in GNU `tar' for compatibility with Unix
705 `tar'. In this book we present a full discussion of this way of
706 writing options and operations (*note Old Options::), and we discuss
707 the other two styles of writing options (*Note Long Options::, and
708 *note Short Options::).
710 In the examples and in the text of this tutorial, we usually use the
711 long forms of operations and options; but the "short" forms produce the
712 same result and can make typing long `tar' commands easier. For
713 example, instead of typing
715 tar --create --verbose --file=afiles.tar apple angst aspic
718 tar -c -v -f afiles.tar apple angst aspic
721 tar -cvf afiles.tar apple angst aspic
723 For more information on option syntax, see *note Advanced tar::. In
724 discussions in the text, when we name an option by its long form, we
725 also give the corresponding short option in parentheses.
727 The term, "option", can be confusing at times, since "operations"
728 are often lumped in with the actual, _optional_ "options" in certain
729 general class statements. For example, we just talked about "short and
730 long forms of options and operations". However, experienced `tar'
731 users often refer to these by shorthand terms such as, "short and long
732 options". This term assumes that the "operations" are included, also.
733 Context will help you determine which definition of "options" to use.
735 Similarly, the term "command" can be confusing, as it is often used
736 in two different ways. People sometimes refer to `tar' "commands". A
737 `tar' "command" is the entire command line of user input which tells
738 `tar' what to do -- including the operation, options, and any arguments
739 (file names, pipes, other commands, etc.). However, you will also
740 sometimes hear the term "the `tar' command". When the word "command"
741 is used specifically like this, a person is usually referring to the
742 `tar' _operation_, not the whole line. Again, use context to figure
743 out which of the meanings the speaker intends.
746 File: tar.info, Node: frequent operations, Next: Two Frequent Options, Prev: basic tar options, Up: Tutorial
748 2.4 The Three Most Frequently Used Operations
749 =============================================
751 Here are the three most frequently used operations (both short and long
752 forms), as well as a brief description of their meanings. The rest of
753 this chapter will cover how to use these operations in detail. We will
754 present the rest of the operations in the next chapter.
758 Create a new `tar' archive.
762 List the contents of an archive.
766 Extract one or more members from an archive.
769 File: tar.info, Node: Two Frequent Options, Next: create, Prev: frequent operations, Up: Tutorial
771 2.5 Two Frequently Used Options
772 ===============================
774 To understand how to run `tar' in the three operating modes listed
775 previously, you also need to understand how to use two of the options to
776 `tar': `--file' (which takes an archive file as an argument) and
777 `--verbose'. (You are usually not _required_ to specify either of
778 these options when you run `tar', but they can be very useful in making
779 things more clear and helping you avoid errors.)
788 File: tar.info, Node: file tutorial, Next: verbose tutorial, Up: Two Frequent Options
793 `--file=ARCHIVE-NAME'
795 Specify the name of an archive file.
797 You can specify an argument for the `--file=ARCHIVE-NAME' (`-f
798 ARCHIVE-NAME') option whenever you use `tar'; this option determines
799 the name of the archive file that `tar' will work on.
801 If you don't specify this argument, then `tar' will examine the
802 environment variable `TAPE'. If it is set, its value will be used as
803 the archive name. Otherwise, `tar' will use the default archive,
804 determined at compile time. Usually it is standard output or some
805 physical tape drive attached to your machine (you can verify what the
806 default is by running `tar --show-defaults', *note defaults::). If
807 there is no tape drive attached, or the default is not meaningful, then
808 `tar' will print an error message. The error message might look
809 roughly like one of the following:
811 tar: can't open /dev/rmt8 : No such device or address
812 tar: can't open /dev/rsmt0 : I/O error
814 To avoid confusion, we recommend that you always specify an archive file
815 name by using `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') when writing
816 your `tar' commands. For more information on using the
817 `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option, see *note file::.
820 File: tar.info, Node: verbose tutorial, Next: help tutorial, Prev: file tutorial, Up: Two Frequent Options
822 The `--verbose' Option
823 ----------------------
827 Show the files being worked on as `tar' is running.
829 `--verbose' (`-v') shows details about the results of running `tar'.
830 This can be especially useful when the results might not be obvious.
831 For example, if you want to see the progress of `tar' as it writes
832 files into the archive, you can use the `--verbose' option. In the
833 beginning, you may find it useful to use `--verbose' at all times; when
834 you are more accustomed to `tar', you will likely want to use it at
835 certain times but not at others. We will use `--verbose' at times to
836 help make something clear, and we will give many examples both using
837 and not using `--verbose' to show the differences.
839 Each instance of `--verbose' on the command line increases the
840 verbosity level by one, so if you need more details on the output,
843 When reading archives (`--list', `--extract', `--diff'), `tar' by
844 default prints only the names of the members being extracted. Using
845 `--verbose' will show a full, `ls' style member listing.
847 In contrast, when writing archives (`--create', `--append',
848 `--update'), `tar' does not print file names by default. So, a single
849 `--verbose' option shows the file names being added to the archive,
850 while two `--verbose' options enable the full listing.
852 For example, to create an archive in verbose mode:
854 $ tar -cvf afiles.tar apple angst aspic
859 Creating the same archive with the verbosity level 2 could give:
861 $ tar -cvvf afiles.tar apple angst aspic
862 -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
863 -rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst
864 -rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic
866 This works equally well using short or long forms of options. Using
867 long forms, you would simply write out the mnemonic form of the option
870 $ tar --create --verbose --verbose ...
872 Note that you must double the hyphens properly each time.
874 Later in the tutorial, we will give examples using
875 `--verbose --verbose'.
877 The full output consists of six fields:
879 * File type and permissions in symbolic form. These are displayed
880 in the same format as the first column of `ls -l' output (*note
881 format=verbose: (fileutils)What information is listed.).
883 * Owner name and group separated by a slash character. If these
884 data are not available (for example, when listing a `v7' format
885 archive), numeric ID values are printed instead.
887 * Size of the file, in bytes.
889 * File modification date in ISO 8601 format.
891 * File modification time.
893 * File name. If the name contains any special characters (white
894 space, newlines, etc.) these are displayed in an unambiguous form
895 using so called "quoting style". For the detailed discussion of
896 available styles and on how to use them, see *note quoting
899 Depending on the file type, the name can be followed by some
900 additional information, described in the following table:
903 The file or archive member is a "symbolic link" and LINK-NAME
904 is the name of file it links to.
907 The file or archive member is a "hard link" and LINK-NAME is
908 the name of file it links to.
911 The archive member is an old GNU format long link. You will
912 normally not encounter this.
915 The archive member is an old GNU format long name. You will
916 normally not encounter this.
919 The archive member is a GNU "volume header" (*note Tape
922 `--Continued at byte N--'
923 Encountered only at the beginning of a multi-volume archive
924 (*note Using Multiple Tapes::). This archive member is a
925 continuation from the previous volume. The number N gives the
926 offset where the original file was split.
928 `unknown file type C'
929 An archive member of unknown type. C is the type character
930 from the archive header. If you encounter such a message, it
931 means that either your archive contains proprietary member
932 types GNU `tar' is not able to handle, or the archive is
936 For example, here is an archive listing containing most of the
937 special suffixes explained above:
939 V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header--
940 -rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at
942 -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
943 lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple
944 -rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
945 hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues
949 File: tar.info, Node: help tutorial, Prev: verbose tutorial, Up: Two Frequent Options
951 Getting Help: Using the `--help' Option
952 ---------------------------------------
955 The `--help' option to `tar' prints out a very brief list of all
956 operations and option available for the current version of `tar'
957 available on your system.
960 File: tar.info, Node: create, Next: list, Prev: Two Frequent Options, Up: Tutorial
962 2.6 How to Create Archives
963 ==========================
965 _(This message will disappear, once this node revised.)_
967 One of the basic operations of `tar' is `--create' (`-c'), which you
968 use to create a `tar' archive. We will explain `--create' first
969 because, in order to learn about the other operations, you will find it
970 useful to have an archive available to practice on.
972 To make this easier, in this section you will first create a
973 directory containing three files. Then, we will show you how to create
974 an _archive_ (inside the new directory). Both the directory, and the
975 archive are specifically for you to practice on. The rest of this
976 chapter and the next chapter will show many examples using this
977 directory and the files you will create: some of those files may be
978 other directories and other archives.
980 The three files you will archive in this example are called `blues',
981 `folk', and `jazz'. The archive is called `collection.tar'.
983 This section will proceed slowly, detailing how to use `--create' in
984 `verbose' mode, and showing examples using both short and long forms.
985 In the rest of the tutorial, and in the examples in the next chapter,
986 we will proceed at a slightly quicker pace. This section moves more
987 slowly to allow beginning users to understand how `tar' works.
991 * prepare for examples::
992 * Creating the archive::
998 File: tar.info, Node: prepare for examples, Next: Creating the archive, Up: create
1000 2.6.1 Preparing a Practice Directory for Examples
1001 -------------------------------------------------
1003 To follow along with this and future examples, create a new directory
1004 called `practice' containing files called `blues', `folk' and `jazz'.
1005 The files can contain any information you like: ideally, they should
1006 contain information which relates to their names, and be of different
1007 lengths. Our examples assume that `practice' is a subdirectory of your
1010 Now `cd' to the directory named `practice'; `practice' is now your
1011 "working directory". (_Please note_: Although the full file name of
1012 this directory is `/HOMEDIR/practice', in our examples we will refer to
1013 this directory as `practice'; the HOMEDIR is presumed.)
1015 In general, you should check that the files to be archived exist
1016 where you think they do (in the working directory) by running `ls'.
1017 Because you just created the directory and the files and have changed to
1018 that directory, you probably don't need to do that this time.
1020 It is very important to make sure there isn't already a file in the
1021 working directory with the archive name you intend to use (in this case,
1022 `collection.tar'), or that you don't care about its contents. Whenever
1023 you use `create', `tar' will erase the current contents of the file
1024 named by `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') if it exists. `tar'
1025 will not tell you if you are about to overwrite an archive unless you
1026 specify an option which does this (*note backup::, for the information
1027 on how to do so). To add files to an existing archive, you need to use
1028 a different option, such as `--append' (`-r'); see *note append:: for
1029 information on how to do this.
1032 File: tar.info, Node: Creating the archive, Next: create verbose, Prev: prepare for examples, Up: create
1034 2.6.2 Creating the Archive
1035 --------------------------
1037 To place the files `blues', `folk', and `jazz' into an archive named
1038 `collection.tar', use the following command:
1040 $ tar --create --file=collection.tar blues folk jazz
1042 The order of the arguments is not very important, _when using long
1043 option forms_. You could also say:
1045 $ tar blues --create folk --file=collection.tar jazz
1047 However, you can see that this order is harder to understand; this is
1048 why we will list the arguments in the order that makes the commands
1049 easiest to understand (and we encourage you to do the same when you use
1050 `tar', to avoid errors).
1052 Note that the sequence `--file=collection.tar' is considered to be
1053 _one_ argument. If you substituted any other string of characters for
1054 `collection.tar', then that string would become the name of the
1055 archive file you create.
1057 The order of the options becomes more important when you begin to use
1058 short forms. With short forms, if you type commands in the wrong order
1059 (even if you type them correctly in all other ways), you may end up with
1060 results you don't expect. For this reason, it is a good idea to get
1061 into the habit of typing options in the order that makes inherent sense.
1062 *Note short create::, for more information on this.
1064 In this example, you type the command as shown above: `--create' is
1065 the operation which creates the new archive (`collection.tar'), and
1066 `--file' is the option which lets you give it the name you chose. The
1067 files, `blues', `folk', and `jazz', are now members of the archive,
1068 `collection.tar' (they are "file name arguments" to the `--create'
1069 operation. *Note Choosing::, for the detailed discussion on these.)
1070 Now that they are in the archive, they are called _archive members_,
1071 not files. (*note members: Definitions.).
1073 When you create an archive, you _must_ specify which files you want
1074 placed in the archive. If you do not specify any archive members, GNU
1075 `tar' will complain.
1077 If you now list the contents of the working directory (`ls'), you
1078 will find the archive file listed as well as the files you saw
1081 blues folk jazz collection.tar
1083 Creating the archive `collection.tar' did not destroy the copies of the
1084 files in the directory.
1086 Keep in mind that if you don't indicate an operation, `tar' will not
1087 run and will prompt you for one. If you don't name any files, `tar'
1088 will complain. You must have write access to the working directory, or
1089 else you will not be able to create an archive in that directory.
1091 _Caution_: Do not attempt to use `--create' (`-c') to add files to
1092 an existing archive; it will delete the archive and write a new one.
1093 Use `--append' (`-r') instead. *Note append::.
1096 File: tar.info, Node: create verbose, Next: short create, Prev: Creating the archive, Up: create
1098 2.6.3 Running `--create' with `--verbose'
1099 -----------------------------------------
1101 If you include the `--verbose' (`-v') option on the command line, `tar'
1102 will list the files it is acting on as it is working. In verbose mode,
1103 the `create' example above would appear as:
1105 $ tar --create --verbose --file=collection.tar blues folk jazz
1110 This example is just like the example we showed which did not use
1111 `--verbose', except that `tar' generated the remaining lines.
1113 In the rest of the examples in this chapter, we will frequently use
1114 `verbose' mode so we can show actions or `tar' responses that you would
1115 otherwise not see, and which are important for you to understand.
1118 File: tar.info, Node: short create, Next: create dir, Prev: create verbose, Up: create
1120 2.6.4 Short Forms with `create'
1121 -------------------------------
1123 As we said before, the `--create' (`-c') operation is one of the most
1124 basic uses of `tar', and you will use it countless times. Eventually,
1125 you will probably want to use abbreviated (or "short") forms of
1126 options. A full discussion of the three different forms that options
1127 can take appears in *note Styles::; for now, here is what the previous
1128 example (including the `--verbose' (`-v') option) looks like using
1131 $ tar -cvf collection.tar blues folk jazz
1136 As you can see, the system responds the same no matter whether you use
1137 long or short option forms.
1139 One difference between using short and long option forms is that,
1140 although the exact placement of arguments following options is no more
1141 specific when using short forms, it is easier to become confused and
1142 make a mistake when using short forms. For example, suppose you
1143 attempted the above example in the following way:
1145 $ tar -cfv collection.tar blues folk jazz
1147 In this case, `tar' will make an archive file called `v', containing
1148 the files `blues', `folk', and `jazz', because the `v' is the closest
1149 "file name" to the `-f' option, and is thus taken to be the chosen
1150 archive file name. `tar' will try to add a file called
1151 `collection.tar' to the `v' archive file; if the file `collection.tar'
1152 did not already exist, `tar' will report an error indicating that this
1153 file does not exist. If the file `collection.tar' does already exist
1154 (e.g., from a previous command you may have run), then `tar' will add
1155 this file to the archive. Because the `-v' option did not get
1156 registered, `tar' will not run under `verbose' mode, and will not
1157 report its progress.
1159 The end result is that you may be quite confused about what happened,
1160 and possibly overwrite a file. To illustrate this further, we will show
1161 you how an example we showed previously would look using short forms.
1165 $ tar blues --create folk --file=collection.tar jazz
1167 is confusing as it is. When shown using short forms, however, it
1168 becomes much more so:
1170 $ tar blues -c folk -f collection.tar jazz
1172 It would be very easy to put the wrong string of characters immediately
1173 following the `-f', but doing that could sacrifice valuable data.
1175 For this reason, we recommend that you pay very careful attention to
1176 the order of options and placement of file and archive names,
1177 especially when using short option forms. Not having the option name
1178 written out mnemonically can affect how well you remember which option
1179 does what, and therefore where different names have to be placed.
1182 File: tar.info, Node: create dir, Prev: short create, Up: create
1184 2.6.5 Archiving Directories
1185 ---------------------------
1187 You can archive a directory by specifying its directory name as a file
1188 name argument to `tar'. The files in the directory will be archived
1189 relative to the working directory, and the directory will be re-created
1190 along with its contents when the archive is extracted.
1192 To archive a directory, first move to its superior directory. If you
1193 have followed the previous instructions in this tutorial, you should
1199 This will put you into the directory which contains `practice', i.e.,
1200 your home directory. Once in the superior directory, you can specify
1201 the subdirectory, `practice', as a file name argument. To store
1202 `practice' in the new archive file `music.tar', type:
1204 $ tar --create --verbose --file=music.tar practice
1206 `tar' should output:
1212 practice/collection.tar
1214 Note that the archive thus created is not in the subdirectory
1215 `practice', but rather in the current working directory--the directory
1216 from which `tar' was invoked. Before trying to archive a directory
1217 from its superior directory, you should make sure you have write access
1218 to the superior directory itself, not only the directory you are trying
1219 archive with `tar'. For example, you will probably not be able to
1220 store your home directory in an archive by invoking `tar' from the root
1221 directory; *Note absolute::. (Note also that `collection.tar', the
1222 original archive file, has itself been archived. `tar' will accept any
1223 file as a file to be archived, regardless of its content. When
1224 `music.tar' is extracted, the archive file `collection.tar' will be
1225 re-written into the file system).
1227 If you give `tar' a command such as
1229 $ tar --create --file=foo.tar .
1231 `tar' will report `tar: ./foo.tar is the archive; not dumped'. This
1232 happens because `tar' creates the archive `foo.tar' in the current
1233 directory before putting any files into it. Then, when `tar' attempts
1234 to add all the files in the directory `.' to the archive, it notices
1235 that the file `./foo.tar' is the same as the archive `foo.tar', and
1236 skips it. (It makes no sense to put an archive into itself.) GNU `tar'
1237 will continue in this case, and create the archive normally, except for
1238 the exclusion of that one file. (_Please note:_ Other implementations
1239 of `tar' may not be so clever; they will enter an infinite loop when
1240 this happens, so you should not depend on this behavior unless you are
1241 certain you are running GNU `tar'. In general, it is wise to always
1242 place the archive outside of the directory being dumped.)
1245 File: tar.info, Node: list, Next: extract, Prev: create, Up: Tutorial
1247 2.7 How to List Archives
1248 ========================
1250 Frequently, you will find yourself wanting to determine exactly what a
1251 particular archive contains. You can use the `--list' (`-t') operation
1252 to get the member names as they currently appear in the archive, as
1253 well as various attributes of the files at the time they were archived.
1254 For example, you can examine the archive `collection.tar' that you
1255 created in the last section with the command,
1257 $ tar --list --file=collection.tar
1259 The output of `tar' would then be:
1265 The archive `bfiles.tar' would list as follows:
1271 Be sure to use a `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option just
1272 as with `--create' (`-c') to specify the name of the archive.
1274 If you use the `--verbose' (`-v') option with `--list', then `tar'
1275 will print out a listing reminiscent of `ls -l', showing owner, file
1276 size, and so forth. This output is described in detail in *note
1277 verbose member listing::.
1279 If you had used `--verbose' (`-v') mode, the example above would
1282 $ tar --list --verbose --file=collection.tar folk
1283 -rw-r--r-- myself user 62 1990-05-23 10:55 folk
1285 It is important to notice that the output of `tar --list --verbose'
1286 does not necessarily match that produced by `tar --create --verbose'
1287 while creating the archive. It is because GNU `tar', unless told
1288 explicitly not to do so, removes some directory prefixes from file
1289 names before storing them in the archive (*Note absolute::, for more
1290 information). In other words, in verbose mode GNU `tar' shows "file
1291 names" when creating an archive and "member names" when listing it.
1292 Consider this example:
1294 $ tar --create --verbose --file archive /etc/mail
1295 tar: Removing leading `/' from member names
1297 /etc/mail/sendmail.cf
1299 $ tar --test --file archive
1301 etc/mail/sendmail.cf
1304 This default behavior can sometimes be inconvenient. You can force
1305 GNU `tar' show member names when creating archive by supplying
1306 `--show-stored-names' option.
1308 `--show-stored-names'
1309 Print member (as opposed to _file_) names when creating the
1312 You can specify one or more individual member names as arguments when
1313 using `list'. In this case, `tar' will only list the names of members
1314 you identify. For example, `tar --list --file=afiles.tar apple' would
1317 Because `tar' preserves file names, these must be specified as they
1318 appear in the archive (i.e., relative to the directory from which the
1319 archive was created). Therefore, it is essential when specifying
1320 member names to `tar' that you give the exact member names. For
1321 example, `tar --list --file=bfiles.tar birds' would produce an error
1322 message something like `tar: birds: Not found in archive', because
1323 there is no member named `birds', only one named `./birds'. While the
1324 names `birds' and `./birds' name the same file, _member_ names by
1325 default are compared verbatim.
1327 However, `tar --list --file=bfiles.tar baboon' would respond with
1328 `baboon', because this exact member name is in the archive file
1329 `bfiles.tar'. If you are not sure of the exact file name, use
1330 "globbing patterns", for example:
1332 $ tar --list --file=bfiles.tar --wildcards '*b*'
1334 will list all members whose name contains `b'. *Note wildcards::, for
1335 a detailed discussion of globbing patterns and related `tar' command
1343 File: tar.info, Node: list dir, Up: list
1345 Listing the Contents of a Stored Directory
1346 ------------------------------------------
1348 To get information about the contents of an archived directory, use the
1349 directory name as a file name argument in conjunction with `--list'
1350 (`-t'). To find out file attributes, include the `--verbose' (`-v')
1353 For example, to find out about files in the directory `practice', in
1354 the archive file `music.tar', type:
1356 $ tar --list --verbose --file=music.tar practice
1360 drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
1361 -rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues
1362 -rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk
1363 -rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz
1364 -rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar
1366 When you use a directory name as a file name argument, `tar' acts on
1367 all the files (including sub-directories) in that directory.
1370 File: tar.info, Node: extract, Next: going further, Prev: list, Up: Tutorial
1372 2.8 How to Extract Members from an Archive
1373 ==========================================
1375 Creating an archive is only half the job--there is no point in storing
1376 files in an archive if you can't retrieve them. The act of retrieving
1377 members from an archive so they can be used and manipulated as
1378 unarchived files again is called "extraction". To extract files from
1379 an archive, use the `--extract' (`--get' or `-x') operation. As with
1380 `--create', specify the name of the archive with `--file' (`-f')
1381 option. Extracting an archive does not modify the archive in any way;
1382 you can extract it multiple times if you want or need to.
1384 Using `--extract', you can extract an entire archive, or specific
1385 files. The files can be directories containing other files, or not. As
1386 with `--create' (`-c') and `--list' (`-t'), you may use the short or the
1387 long form of the operation without affecting the performance.
1391 * extracting archives::
1392 * extracting files::
1394 * extracting untrusted archives::
1395 * failing commands::
1398 File: tar.info, Node: extracting archives, Next: extracting files, Up: extract
1400 2.8.1 Extracting an Entire Archive
1401 ----------------------------------
1403 To extract an entire archive, specify the archive file name only, with
1404 no individual file names as arguments. For example,
1406 $ tar -xvf collection.tar
1410 -rw-r--r-- me user 28 1996-10-18 16:31 jazz
1411 -rw-r--r-- me user 21 1996-09-23 16:44 blues
1412 -rw-r--r-- me user 20 1996-09-23 16:44 folk
1415 File: tar.info, Node: extracting files, Next: extract dir, Prev: extracting archives, Up: extract
1417 2.8.2 Extracting Specific Files
1418 -------------------------------
1420 To extract specific archive members, give their exact member names as
1421 arguments, as printed by `--list' (`-t'). If you had mistakenly
1422 deleted one of the files you had placed in the archive `collection.tar'
1423 earlier (say, `blues'), you can extract it from the archive without
1424 changing the archive's structure. Its contents will be identical to
1425 the original file `blues' that you deleted.
1427 First, make sure you are in the `practice' directory, and list the
1428 files in the directory. Now, delete the file, `blues', and list the
1429 files in the directory again.
1431 You can now extract the member `blues' from the archive file
1432 `collection.tar' like this:
1434 $ tar --extract --file=collection.tar blues
1436 If you list the files in the directory again, you will see that the file
1437 `blues' has been restored, with its original permissions, data
1438 modification times, and owner.(1) (These parameters will be identical
1439 to those which the file had when you originally placed it in the
1440 archive; any changes you may have made before deleting the file from
1441 the file system, however, will _not_ have been made to the archive
1442 member.) The archive file, `collection.tar', is the same as it was
1443 before you extracted `blues'. You can confirm this by running `tar'
1444 with `--list' (`-t').
1446 Remember that as with other operations, specifying the exact member
1447 name is important. `tar --extract --file=bfiles.tar birds' will fail,
1448 because there is no member named `birds'. To extract the member named
1449 `./birds', you must specify `tar --extract --file=bfiles.tar ./birds'.
1450 If you don't remember the exact member names, use `--list' (`-t') option
1451 (*note list::). You can also extract those members that match a
1452 specific "globbing pattern". For example, to extract from `bfiles.tar'
1453 all files that begin with `b', no matter their directory prefix, you
1456 $ tar -x -f bfiles.tar --wildcards --no-anchored 'b*'
1458 Here, `--wildcards' instructs `tar' to treat command line arguments as
1459 globbing patterns and `--no-anchored' informs it that the patterns
1460 apply to member names after any `/' delimiter. The use of globbing
1461 patterns is discussed in detail in *Note wildcards::.
1463 You can extract a file to standard output by combining the above
1464 options with the `--to-stdout' (`-O') option (*note Writing to Standard
1467 If you give the `--verbose' option, then `--extract' will print the
1468 names of the archive members as it extracts them.
1470 ---------- Footnotes ----------
1472 (1) This is only accidentally true, but not in general. Whereas
1473 modification times are always restored, in most cases, one has to be
1474 root for restoring the owner, and use a special option for restoring
1475 permissions. Here, it just happens that the restoring user is also the
1476 owner of the archived members, and that the current `umask' is
1477 compatible with original permissions.
1480 File: tar.info, Node: extract dir, Next: extracting untrusted archives, Prev: extracting files, Up: extract
1482 2.8.3 Extracting Files that are Directories
1483 -------------------------------------------
1485 Extracting directories which are members of an archive is similar to
1486 extracting other files. The main difference to be aware of is that if
1487 the extracted directory has the same name as any directory already in
1488 the working directory, then files in the extracted directory will be
1489 placed into the directory of the same name. Likewise, if there are
1490 files in the pre-existing directory with the same names as the members
1491 which you extract, the files from the extracted archive will replace
1492 the files already in the working directory (and possible
1493 subdirectories). This will happen regardless of whether or not the
1494 files in the working directory were more recent than those extracted
1495 (there exist, however, special options that alter this behavior *note
1498 However, if a file was stored with a directory name as part of its
1499 file name, and that directory does not exist under the working
1500 directory when the file is extracted, `tar' will create the directory.
1502 We can demonstrate how to use `--extract' to extract a directory
1503 file with an example. Change to the `practice' directory if you
1504 weren't there, and remove the files `folk' and `jazz'. Then, go back
1505 to the parent directory and extract the archive `music.tar'. You may
1506 either extract the entire archive, or you may extract only the files
1507 you just deleted. To extract the entire archive, don't give any file
1508 names as arguments after the archive name `music.tar'. To extract only
1509 the files you deleted, use the following command:
1511 $ tar -xvf music.tar practice/folk practice/jazz
1515 If you were to specify two `--verbose' (`-v') options, `tar' would have
1516 displayed more detail about the extracted files, as shown in the
1519 $ tar -xvvf music.tar practice/folk practice/jazz
1520 -rw-r--r-- me user 28 1996-10-18 16:31 practice/jazz
1521 -rw-r--r-- me user 20 1996-09-23 16:44 practice/folk
1523 Because you created the directory with `practice' as part of the file
1524 names of each of the files by archiving the `practice' directory as
1525 `practice', you must give `practice' as part of the file names when you
1526 extract those files from the archive.
1529 File: tar.info, Node: extracting untrusted archives, Next: failing commands, Prev: extract dir, Up: extract
1531 2.8.4 Extracting Archives from Untrusted Sources
1532 ------------------------------------------------
1534 Extracting files from archives can overwrite files that already exist.
1535 If you receive an archive from an untrusted source, you should make a
1536 new directory and extract into that directory, so that you don't have
1537 to worry about the extraction overwriting one of your existing files.
1538 For example, if `untrusted.tar' came from somewhere else on the
1539 Internet, and you don't necessarily trust its contents, you can extract
1544 $ tar -xvf ../untrusted.tar
1546 It is also a good practice to examine contents of the archive before
1547 extracting it, using `--list' (`-t') option, possibly combined with
1551 File: tar.info, Node: failing commands, Prev: extracting untrusted archives, Up: extract
1553 2.8.5 Commands That Will Fail
1554 -----------------------------
1556 Here are some sample commands you might try which will not work, and why
1559 If you try to use this command,
1561 $ tar -xvf music.tar folk jazz
1563 you will get the following response:
1565 tar: folk: Not found in archive
1566 tar: jazz: Not found in archive
1568 This is because these files were not originally _in_ the parent
1569 directory `..', where the archive is located; they were in the
1570 `practice' directory, and their file names reflect this:
1572 $ tar -tvf music.tar
1577 Likewise, if you try to use this command,
1579 $ tar -tvf music.tar folk jazz
1581 you would get a similar response. Members with those names are not in
1582 the archive. You must use the correct member names, or wildcards, in
1583 order to extract the files from the archive.
1585 If you have forgotten the correct names of the files in the archive,
1586 use `tar --list --verbose' to list them correctly.
1589 File: tar.info, Node: going further, Prev: extract, Up: Tutorial
1591 2.9 Going Further Ahead in this Manual
1592 ======================================
1594 _(This message will disappear, once this node revised.)_
1597 File: tar.info, Node: tar invocation, Next: operations, Prev: Tutorial, Up: Top
1599 3 Invoking GNU `tar'
1600 ********************
1602 This chapter is about how one invokes the GNU `tar' command, from the
1603 command synopsis (*note Synopsis::). There are numerous options, and
1604 many styles for writing them. One mandatory option specifies the
1605 operation `tar' should perform (*note Operation Summary::), other
1606 options are meant to detail how this operation should be performed
1607 (*note Option Summary::). Non-option arguments are not always
1608 interpreted the same way, depending on what the operation is.
1610 You will find in this chapter everything about option styles and
1611 rules for writing them (*note Styles::). On the other hand, operations
1612 and options are fully described elsewhere, in other chapters. Here,
1613 you will find only synthetic descriptions for operations and options,
1614 together with pointers to other parts of the `tar' manual.
1616 Some options are so special they are fully described right in this
1617 chapter. They have the effect of inhibiting the normal operation of
1618 `tar' or else, they globally alter the amount of feedback the user
1619 receives about what is going on. These are the `--help' and
1620 `--version' (*note help::), `--verbose' (*note verbose::) and
1621 `--interactive' options (*note interactive::).
1626 * using tar options::
1637 File: tar.info, Node: Synopsis, Next: using tar options, Up: tar invocation
1639 3.1 General Synopsis of `tar'
1640 =============================
1642 The GNU `tar' program is invoked as either one of:
1644 tar OPTION... [NAME]...
1645 tar LETTER... [ARGUMENT]... [OPTION]... [NAME]...
1647 The second form is for when old options are being used.
1649 You can use `tar' to store files in an archive, to extract them from
1650 an archive, and to do other types of archive manipulation. The primary
1651 argument to `tar', which is called the "operation", specifies which
1652 action to take. The other arguments to `tar' are either "options",
1653 which change the way `tar' performs an operation, or file names or
1654 archive members, which specify the files or members `tar' is to act on.
1656 You can actually type in arguments in any order, even if in this
1657 manual the options always precede the other arguments, to make examples
1658 easier to understand. Further, the option stating the main operation
1659 mode (the `tar' main command) is usually given first.
1661 Each NAME in the synopsis above is interpreted as an archive member
1662 name when the main command is one of `--compare' (`--diff', `-d'),
1663 `--delete', `--extract' (`--get', `-x'), `--list' (`-t') or `--update'
1664 (`-u'). When naming archive members, you must give the exact name of
1665 the member in the archive, as it is printed by `--list'. For
1666 `--append' (`-r') and `--create' (`-c'), these NAME arguments specify
1667 the names of either files or directory hierarchies to place in the
1668 archive. These files or hierarchies should already exist in the file
1669 system, prior to the execution of the `tar' command.
1671 `tar' interprets relative file names as being relative to the
1672 working directory. `tar' will make all file names relative (by
1673 removing leading slashes when archiving or restoring files), unless you
1674 specify otherwise (using the `--absolute-names' option). *Note
1675 absolute::, for more information about `--absolute-names'.
1677 If you give the name of a directory as either a file name or a member
1678 name, then `tar' acts recursively on all the files and directories
1679 beneath that directory. For example, the name `/' identifies all the
1680 files in the file system to `tar'.
1682 The distinction between file names and archive member names is
1683 especially important when shell globbing is used, and sometimes a
1684 source of confusion for newcomers. *Note wildcards::, for more
1685 information about globbing. The problem is that shells may only glob
1686 using existing files in the file system. Only `tar' itself may glob on
1687 archive members, so when needed, you must ensure that wildcard
1688 characters reach `tar' without being interpreted by the shell first.
1689 Using a backslash before `*' or `?', or putting the whole argument
1690 between quotes, is usually sufficient for this.
1692 Even if NAMEs are often specified on the command line, they can also
1693 be read from a text file in the file system, using the
1694 `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option.
1696 If you don't use any file name arguments, `--append' (`-r'),
1697 `--delete' and `--concatenate' (`--catenate', `-A') will do nothing,
1698 while `--create' (`-c') will usually yield a diagnostic and inhibit
1699 `tar' execution. The other operations of `tar' (`--list', `--extract',
1700 `--compare', and `--update') will act on the entire contents of the
1703 Besides successful exits, GNU `tar' may fail for many reasons. Some
1704 reasons correspond to bad usage, that is, when the `tar' command line
1705 is improperly written. Errors may be encountered later, while
1706 processing the archive or the files. Some errors are recoverable, in
1707 which case the failure is delayed until `tar' has completed all its
1708 work. Some errors are such that it would be not meaningful, or at
1709 least risky, to continue processing: `tar' then aborts processing
1710 immediately. All abnormal exits, whether immediate or delayed, should
1711 always be clearly diagnosed on `stderr', after a line stating the
1712 nature of the error.
1714 Possible exit codes of GNU `tar' are summarized in the following
1718 `Successful termination'.
1721 `Some files differ'. If tar was invoked with `--compare'
1722 (`--diff', `-d') command line option, this means that some files
1723 in the archive differ from their disk counterparts (*note
1724 compare::). If tar was given `--create', `--append' or `--update'
1725 option, this exit code means that some files were changed while
1726 being archived and so the resulting archive does not contain the
1727 exact copy of the file set.
1730 `Fatal error'. This means that some fatal, unrecoverable error
1733 If `tar' has invoked a subprocess and that subprocess exited with a
1734 nonzero exit code, `tar' exits with that code as well. This can
1735 happen, for example, if `tar' was given some compression option (*note
1736 gzip::) and the external compressor program failed. Another example is
1737 `rmt' failure during backup to the remote device (*note Remote Tape
1741 File: tar.info, Node: using tar options, Next: Styles, Prev: Synopsis, Up: tar invocation
1743 3.2 Using `tar' Options
1744 =======================
1746 GNU `tar' has a total of eight operating modes which allow you to
1747 perform a variety of tasks. You are required to choose one operating
1748 mode each time you employ the `tar' program by specifying one, and only
1749 one operation as an argument to the `tar' command (the corresponding
1750 options may be found at *note frequent operations:: and *note
1751 Operations::). Depending on circumstances, you may also wish to
1752 customize how the chosen operating mode behaves. For example, you may
1753 wish to change the way the output looks, or the format of the files
1754 that you wish to archive may require you to do something special in
1755 order to make the archive look right.
1757 You can customize and control `tar''s performance by running `tar'
1758 with one or more options (such as `--verbose' (`-v'), which we used in
1759 the tutorial). As we said in the tutorial, "options" are arguments to
1760 `tar' which are (as their name suggests) optional. Depending on the
1761 operating mode, you may specify one or more options. Different options
1762 will have different effects, but in general they all change details of
1763 the operation, such as archive format, archive name, or level of user
1764 interaction. Some options make sense with all operating modes, while
1765 others are meaningful only with particular modes. You will likely use
1766 some options frequently, while you will only use others infrequently, or
1767 not at all. (A full list of options is available in *note All
1770 The `TAR_OPTIONS' environment variable specifies default options to
1771 be placed in front of any explicit options. For example, if
1772 `TAR_OPTIONS' is `-v --unlink-first', `tar' behaves as if the two
1773 options `-v' and `--unlink-first' had been specified before any
1774 explicit options. Option specifications are separated by whitespace.
1775 A backslash escapes the next character, so it can be used to specify an
1776 option containing whitespace or a backslash.
1778 Note that `tar' options are case sensitive. For example, the
1779 options `-T' and `-t' are different; the first requires an argument for
1780 stating the name of a file providing a list of NAMEs, while the second
1781 does not require an argument and is another way to write `--list'
1784 In addition to the eight operations, there are many options to
1785 `tar', and three different styles for writing both: long (mnemonic)
1786 form, short form, and old style. These styles are discussed below.
1787 Both the options and the operations can be written in any of these three
1791 File: tar.info, Node: Styles, Next: All Options, Prev: using tar options, Up: tar invocation
1793 3.3 The Three Option Styles
1794 ===========================
1796 There are three styles for writing operations and options to the command
1797 line invoking `tar'. The different styles were developed at different
1798 times during the history of `tar'. These styles will be presented
1799 below, from the most recent to the oldest.
1801 Some options must take an argument(1). Where you _place_ the
1802 arguments generally depends on which style of options you choose. We
1803 will detail specific information relevant to each option style in the
1804 sections on the different option styles, below. The differences are
1805 subtle, yet can often be very important; incorrect option placement can
1806 cause you to overwrite a number of important files. We urge you to
1807 note these differences, and only use the option style(s) which makes
1808 the most sense to you until you feel comfortable with the others.
1810 Some options _may_ take an argument. Such options may have at most
1811 long and short forms, they do not have old style equivalent. The rules
1812 for specifying an argument for such options are stricter than those for
1813 specifying mandatory arguments. Please, pay special attention to them.
1817 * Long Options:: Long Option Style
1818 * Short Options:: Short Option Style
1819 * Old Options:: Old Option Style
1820 * Mixing:: Mixing Option Styles
1822 ---------- Footnotes ----------
1824 (1) For example, `--file' (`-f') takes the name of an archive file
1825 as an argument. If you do not supply an archive file name, `tar' will
1826 use a default, but this can be confusing; thus, we recommend that you
1827 always supply a specific archive file name.
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 Like short options, "old options" are single letters. However, old
1929 options must be written together as a single clumped set, without
1930 spaces separating them or dashes preceding them(1). This set of
1931 letters must be the first to appear on the command line, after the
1932 `tar' program name and some white space; old options cannot appear
1933 anywhere else. The letter of an old option is exactly the same letter
1934 as the corresponding short option. For example, the old option `t' is
1935 the same as the short option `-t', and consequently, the same as the
1936 long option `--list'. So for example, the command `tar cv' specifies
1937 the option `-v' in addition to the operation `-c'.
1939 When options that need arguments are given together with the command,
1940 all the associated arguments follow, in the same order as the options.
1941 Thus, the example given previously could also be written in the old
1944 $ tar cvbf 20 /dev/rmt0
1946 Here, `20' is the argument of `-b' and `/dev/rmt0' is the argument of
1949 On the other hand, this old style syntax makes it difficult to match
1950 option letters with their corresponding arguments, and is often
1951 confusing. In the command `tar cvbf 20 /dev/rmt0', for example, `20'
1952 is the argument for `-b', `/dev/rmt0' is the argument for `-f', and
1953 `-v' does not have a corresponding argument. Even using short options
1954 like in `tar -c -v -b 20 -f /dev/rmt0' is clearer, putting all
1955 arguments next to the option they pertain to.
1957 If you want to reorder the letters in the old option argument, be
1958 sure to reorder any corresponding argument appropriately.
1960 This old way of writing `tar' options can surprise even experienced
1961 users. For example, the two commands:
1963 tar cfz archive.tar.gz file
1964 tar -cfz archive.tar.gz file
1966 are quite different. The first example uses `archive.tar.gz' as the
1967 value for option `f' and recognizes the option `z'. The second
1968 example, however, uses `z' as the value for option `f' -- probably not
1971 Old options are kept for compatibility with old versions of `tar'.
1973 This second example could be corrected in many ways, among which the
1974 following are equivalent:
1976 tar -czf archive.tar.gz file
1977 tar -cf archive.tar.gz -z file
1978 tar cf archive.tar.gz -z file
1980 As far as we know, all `tar' programs, GNU and non-GNU, support old
1981 options. GNU `tar' supports them not only for historical reasons, but
1982 also because many people are used to them. For compatibility with Unix
1983 `tar', the first argument is always treated as containing command and
1984 option letters even if it doesn't start with `-'. Thus, `tar c' is
1985 equivalent to `tar -c': both of them specify the `--create' (`-c')
1986 command to create an archive.
1988 ---------- Footnotes ----------
1990 (1) Beware that if you precede options with a dash, you are
1991 announcing the short option style instead of the old option style;
1992 short options are decoded differently.
1995 File: tar.info, Node: Mixing, Prev: Old Options, Up: Styles
1997 3.3.4 Mixing Option Styles
1998 --------------------------
2000 All three styles may be intermixed in a single `tar' command, so long
2001 as the rules for each style are fully respected(1). Old style options
2002 and either of the modern styles of options may be mixed within a single
2003 `tar' command. However, old style options must be introduced as the
2004 first arguments only, following the rule for old options (old options
2005 must appear directly after the `tar' command and some white space).
2006 Modern options may be given only after all arguments to the old options
2007 have been collected. If this rule is not respected, a modern option
2008 might be falsely interpreted as the value of the argument to one of the
2011 For example, all the following commands are wholly equivalent, and
2012 illustrate the many combinations and orderings of option styles.
2014 tar --create --file=archive.tar
2015 tar --create -f archive.tar
2016 tar --create -farchive.tar
2017 tar --file=archive.tar --create
2018 tar --file=archive.tar -c
2019 tar -c --file=archive.tar
2020 tar -c -f archive.tar
2021 tar -c -farchive.tar
2024 tar -f archive.tar --create
2025 tar -f archive.tar -c
2026 tar -farchive.tar --create
2027 tar -farchive.tar -c
2028 tar c --file=archive.tar
2029 tar c -f archive.tar
2032 tar f archive.tar --create
2033 tar f archive.tar -c
2036 On the other hand, the following commands are _not_ equivalent to
2039 tar -f -c archive.tar
2045 These last examples mean something completely different from what the
2046 user intended (judging based on the example in the previous set which
2047 uses long options, whose intent is therefore very clear). The first
2048 four specify that the `tar' archive would be a file named `-c', `c',
2049 `carchive.tar' or `archive.tarc', respectively. The first two examples
2050 also specify a single non-option, NAME argument having the value
2051 `archive.tar'. The last example contains only old style option letters
2052 (repeating option `c' twice), not all of which are meaningful (eg., `.',
2053 `h', or `i'), with no argument value.
2055 ---------- Footnotes ----------
2057 (1) Before GNU `tar' version 1.11.6, a bug prevented intermixing old
2058 style options with long options in some cases.
2061 File: tar.info, Node: All Options, Next: help, Prev: Styles, Up: tar invocation
2063 3.4 All `tar' Options
2064 =====================
2066 The coming manual sections contain an alphabetical listing of all `tar'
2067 operations and options, with brief descriptions and cross-references to
2068 more in-depth explanations in the body of the manual. They also
2069 contain an alphabetically arranged table of the short option forms with
2070 their corresponding long option. You can use this table as a reference
2071 for deciphering `tar' commands in scripts.
2075 * Operation Summary::
2077 * Short Option Summary::
2080 File: tar.info, Node: Operation Summary, Next: Option Summary, Up: All Options
2087 Appends files to the end of the archive. *Note append::.
2091 Same as `--concatenate'. *Note concatenate::.
2095 Compares archive members with their counterparts in the file
2096 system, and reports differences in file size, mode, owner,
2097 modification date and contents. *Note compare::.
2101 Appends other `tar' archives to the end of the archive. *Note
2106 Creates a new `tar' archive. *Note create::.
2109 Deletes members from the archive. Don't try this on an archive on
2110 a tape! *Note delete::.
2114 Same `--compare'. *Note compare::.
2118 Extracts members from the archive into the file system. *Note
2123 Same as `--extract'. *Note extract::.
2127 Lists the members in an archive. *Note list::.
2131 Adds files to the end of the archive, but only if they are newer
2132 than their counterparts already in the archive, or if they do not
2133 already exist in the archive. *Note update::.
2137 File: tar.info, Node: Option Summary, Next: Short Option Summary, Prev: Operation Summary, Up: All Options
2144 Normally when creating an archive, `tar' strips an initial `/'
2145 from member names. This option disables that behavior. *Note
2149 (See `--newer', *note after::)
2152 A pattern must match an initial subsequence of the name's
2153 components. *Note controlling pattern-matching::.
2156 `--atime-preserve=replace'
2157 `--atime-preserve=system'
2158 Attempt to preserve the access time of files when reading them.
2159 This option currently is effective only on files that you own,
2160 unless you have superuser privileges.
2162 `--atime-preserve=replace' remembers the access time of a file
2163 before reading it, and then restores the access time afterwards.
2164 This may cause problems if other programs are reading the file at
2165 the same time, as the times of their accesses will be lost. On
2166 most platforms restoring the access time also requires `tar' to
2167 restore the data modification time too, so this option may also
2168 cause problems if other programs are writing the file at the same
2169 time (`tar' attempts to detect this situation, but cannot do so
2170 reliably due to race conditions). Worse, on most platforms
2171 restoring the access time also updates the status change time,
2172 which means that this option is incompatible with incremental
2175 `--atime-preserve=system' avoids changing time stamps on files,
2176 without interfering with time stamp updates caused by other
2177 programs, so it works better with incremental backups. However,
2178 it requires a special `O_NOATIME' option from the underlying
2179 operating and file system implementation, and it also requires
2180 that searching directories does not update their access times. As
2181 of this writing (November 2005) this works only with Linux, and
2182 only with Linux kernels 2.6.8 and later. Worse, there is
2183 currently no reliable way to know whether this feature actually
2184 works. Sometimes `tar' knows that it does not work, and if you use
2185 `--atime-preserve=system' then `tar' complains and exits right
2186 away. But other times `tar' might think that the option works
2187 when it actually does not.
2189 Currently `--atime-preserve' with no operand defaults to
2190 `--atime-preserve=replace', but this may change in the future as
2191 support for `--atime-preserve=system' improves.
2193 If your operating or file system does not support
2194 `--atime-preserve=system', you might be able to preserve access
2195 times reliably by using the `mount' command. For example, you can
2196 mount the file system read-only, or access the file system via a
2197 read-only loopback mount, or use the `noatime' mount option
2198 available on some systems. However, mounting typically requires
2199 superuser privileges and can be a pain to manage.
2203 During a `--create' operation, enables automatic compressed format
2204 recognition based on the archive suffix. The effect of this
2205 option is cancelled by `--no-auto-compress'. *Note gzip::.
2207 `--backup=BACKUP-TYPE'
2208 Rather than deleting files from the file system, `tar' will back
2209 them up using simple or numbered backups, depending upon
2210 BACKUP-TYPE. *Note backup::.
2214 With this option present, `tar' prints error messages for read
2215 errors with the block number in the archive file. *Note
2218 `--blocking-factor=BLOCKING'
2220 Sets the blocking factor `tar' uses to BLOCKING x 512 bytes per
2221 record. *Note Blocking Factor::.
2225 This option tells `tar' to read or write archives through `bzip2'.
2229 Check device numbers when creating a list of modified files for
2230 incremental archiving. This is the default. *Note device
2231 numbers::, for a detailed description.
2233 `--checkpoint[=NUMBER]'
2234 This option directs `tar' to print periodic checkpoint messages as
2235 it reads through the archive. It is intended for when you want a
2236 visual indication that `tar' is still running, but don't want to
2237 see `--verbose' output. You can also instruct `tar' to execute a
2238 list of actions on each checkpoint, see `--checkpoint-action'
2239 below. For a detailed description, see *note checkpoints::.
2241 `--checkpoint-action=ACTION'
2242 Instruct `tar' to execute an action upon hitting a breakpoint.
2243 Here we give only a brief outline. *Note checkpoints::, for a
2244 complete description.
2246 The ACTION argument can be one of the following:
2249 Produce an audible bell on the console.
2253 Print a single dot on the standard listing stream.
2256 Display a textual message on the standard error, with the
2257 status and number of the checkpoint. This is the default.
2260 Display STRING on the standard error. Before output, the
2261 string is subject to meta-character expansion.
2264 Execute the given COMMAND.
2267 Wait for TIME seconds.
2270 Output STRING on the current console (`/dev/tty').
2272 Several `--checkpoint-action' options can be specified. The
2273 supplied actions will be executed in order of their appearance in
2276 Using `--checkpoint-action' without `--checkpoint' assumes default
2277 checkpoint frequency of one checkpoint per 10 records.
2281 If this option was given, `tar' will check the number of links
2282 dumped for each processed file. If this number does not match the
2283 total number of hard links for the file, a warning message will be
2291 `tar' will use the `compress' program when reading or writing the
2292 archive. This allows you to directly act on archives while saving
2293 space. *Note gzip::.
2296 (See `--interactive'.) *Note interactive::.
2298 `--delay-directory-restore'
2299 Delay setting modification times and permissions of extracted
2300 directories until the end of extraction. *Note Directory
2301 Modification Times and Permissions::.
2305 When creating a `tar' archive, `tar' will archive the file that a
2306 symbolic link points to, rather than archiving the symlink. *Note
2311 When this option is specified, `tar' will change its current
2312 directory to DIR before performing any operations. When this
2313 option is used during archive creation, it is order sensitive.
2317 When performing operations, `tar' will skip files that match
2318 PATTERN. *Note exclude::.
2321 Exclude backup and lock files. *Note exclude-backups: exclude.
2323 `--exclude-from=FILE'
2325 Similar to `--exclude', except `tar' will use the list of patterns
2326 in the file FILE. *Note exclude::.
2329 Exclude from dump any directory containing a valid cache directory
2330 tag file, but still dump the directory node and the tag file
2333 *Note exclude-caches: exclude.
2335 `--exclude-caches-under'
2336 Exclude from dump any directory containing a valid cache directory
2337 tag file, but still dump the directory node itself.
2341 `--exclude-caches-all'
2342 Exclude from dump any directory containing a valid cache directory
2343 tag file. *Note exclude::.
2345 `--exclude-tag=FILE'
2346 Exclude from dump any directory containing file named FILE, but
2347 dump the directory node and FILE itself. *Note exclude-tag:
2350 `--exclude-tag-under=FILE'
2351 Exclude from dump the contents of any directory containing file
2352 named FILE, but dump the directory node itself. *Note
2353 exclude-tag-under: exclude.
2355 `--exclude-tag-all=FILE'
2356 Exclude from dump any directory containing file named FILE. *Note
2357 exclude-tag-all: exclude.
2360 Exclude from dump directories and files, that are internal for some
2361 widely used version control systems.
2363 *Note exclude-vcs: exclude.
2367 `tar' will use the file ARCHIVE as the `tar' archive it performs
2368 operations on, rather than `tar''s compilation dependent default.
2369 *Note file tutorial::.
2373 `tar' will use the contents of FILE as a list of archive members
2374 or files to operate on, in addition to those specified on the
2375 command-line. *Note files::.
2378 Forces `tar' to interpret the file name given to `--file' as a
2379 local file, even if it looks like a remote tape drive name. *Note
2380 local and remote archives::.
2384 Selects output archive format. FORMAT may be one of the following:
2387 Creates an archive that is compatible with Unix V7 `tar'.
2390 Creates an archive that is compatible with GNU `tar' version
2394 Creates archive in GNU tar 1.13 format. Basically it is the
2395 same as `oldgnu' with the only difference in the way it
2396 handles long numeric fields.
2399 Creates a POSIX.1-1988 compatible archive.
2402 Creates a POSIX.1-2001 archive.
2405 *Note Formats::, for a detailed discussion of these formats.
2408 Files added to the `tar' archive will have a group ID of GROUP,
2409 rather than the group from the source file. GROUP is first decoded
2410 as a group symbolic name, but if this interpretation fails, it has
2411 to be a decimal numeric group ID. *Note override::.
2413 Also see the comments for the `--owner=USER' option.
2419 This option tells `tar' to read or write archives through `gzip',
2420 allowing `tar' to directly operate on several kinds of compressed
2421 archives transparently. *Note gzip::.
2423 `--hard-dereference'
2424 When creating an archive, dereference hard links and store the
2425 files they refer to, instead of creating usual hard link members.
2431 `tar' will print out a short message summarizing the operations and
2432 options to `tar' and exit. *Note help::.
2435 Ignore case when matching member or file names with patterns.
2436 *Note controlling pattern-matching::.
2438 `--ignore-command-error'
2439 Ignore exit codes of subprocesses. *Note Writing to an External
2442 `--ignore-failed-read'
2443 Do not exit unsuccessfully merely because an unreadable file was
2444 encountered. *Note Reading::.
2448 With this option, `tar' will ignore zeroed blocks in the archive,
2449 which normally signals EOF. *Note Reading::.
2453 Informs `tar' that it is working with an old GNU-format
2454 incremental backup archive. It is intended primarily for
2455 backwards compatibility only. *Note Incremental Dumps::, for a
2456 detailed discussion of incremental archives.
2459 Send verbose output to FILE instead of to standard output.
2461 `--info-script=SCRIPT-FILE'
2462 `--new-volume-script=SCRIPT-FILE'
2464 When `tar' is performing multi-tape backups, SCRIPT-FILE is run at
2465 the end of each tape. If SCRIPT-FILE exits with nonzero status,
2466 `tar' fails immediately. *Note info-script::, for a detailed
2467 discussion of SCRIPT-FILE.
2472 Specifies that `tar' should ask the user for confirmation before
2473 performing potentially destructive options, such as overwriting
2474 files. *Note interactive::.
2476 `--keep-newer-files'
2477 Do not replace existing files that are newer than their archive
2478 copies when extracting files from an archive.
2482 Do not overwrite existing files when extracting files from an
2483 archive. *Note Keep Old Files::.
2487 When creating an archive, instructs `tar' to write NAME as a name
2488 record in the archive. When extracting or listing archives, `tar'
2489 will only operate on archives that have a label matching the
2490 pattern specified in NAME. *Note Tape Files::.
2493 Force incremental backup of level N. As of GNU `tar' version
2494 1.23, the option `--level=0' truncates the snapshot file, thereby
2495 forcing the level 0 dump. Other values of N are effectively
2496 ignored. *Note --level=0::, for details and examples.
2498 The use of this option is valid only in conjunction with the
2499 `--listed-incremental' option. *Note Incremental Dumps::, for a
2500 detailed description.
2502 `--listed-incremental=SNAPSHOT-FILE'
2504 During a `--create' operation, specifies that the archive that
2505 `tar' creates is a new GNU-format incremental backup, using
2506 SNAPSHOT-FILE to determine which files to backup. With other
2507 operations, informs `tar' that the archive is in incremental
2508 format. *Note Incremental Dumps::.
2511 This option tells `tar' to read or write archives through `lzip'.
2515 This option tells `tar' to read or write archives through `lzma'.
2519 This option tells `tar' to read or write archives through `lzop'.
2522 `--mode=PERMISSIONS'
2523 When adding files to an archive, `tar' will use PERMISSIONS for
2524 the archive members, rather than the permissions from the files.
2525 PERMISSIONS can be specified either as an octal number or as
2526 symbolic permissions, like with `chmod'. *Note override::.
2529 When adding files to an archive, `tar' will use DATE as the
2530 modification time of members when creating archives, instead of
2531 their actual modification times. The value of DATE can be either
2532 a textual date representation (*note Date input formats::) or a
2533 name of the existing file, starting with `/' or `.'. In the
2534 latter case, the modification time of that file is used. *Note
2539 Informs `tar' that it should create or otherwise operate on a
2540 multi-volume `tar' archive. *Note Using Multiple Tapes::.
2542 `--new-volume-script'
2543 (see `--info-script')
2548 When creating an archive, `tar' will only add files that have
2549 changed since DATE. If DATE begins with `/' or `.', it is taken
2550 to be the name of a file whose data modification time specifies
2551 the date. *Note after::.
2553 `--newer-mtime=DATE'
2554 Like `--newer', but add only files whose contents have changed (as
2555 opposed to just `--newer', which will also back up files for which
2556 any status information has changed). *Note after::.
2559 An exclude pattern can match any subsequence of the name's
2560 components. *Note controlling pattern-matching::.
2562 `--no-auto-compress'
2563 Disables automatic compressed format recognition based on the
2564 archive suffix. *Note --auto-compress::. *Note gzip::.
2567 Do not check device numbers when creating a list of modified files
2568 for incremental archiving. *Note device numbers::, for a detailed
2571 `--no-delay-directory-restore'
2572 Modification times and permissions of extracted directories are
2573 set when all files from this directory have been extracted. This
2574 is the default. *Note Directory Modification Times and
2578 Use case-sensitive matching. *Note controlling pattern-matching::.
2580 `--no-ignore-command-error'
2581 Print warnings about subprocesses that terminated with a nonzero
2582 exit code. *Note Writing to an External Program::.
2585 If the `--null' option was given previously, this option cancels
2586 its effect, so that any following `--files-from' options will
2587 expect their file lists to be newline-terminated.
2589 `--no-overwrite-dir'
2590 Preserve metadata of existing directories when extracting files
2591 from an archive. *Note Overwrite Old Files::.
2593 `--no-quote-chars=STRING'
2594 Remove characters listed in STRING from the list of quoted
2595 characters set by the previous `--quote-chars' option (*note
2599 With this option, `tar' will not recurse into directories. *Note
2604 When extracting an archive, do not attempt to preserve the owner
2605 specified in the `tar' archive. This the default behavior for
2608 `--no-same-permissions'
2609 When extracting an archive, subtract the user's umask from files
2610 from the permissions specified in the archive. This is the
2611 default behavior for ordinary users.
2614 The archive media does not support seeks to arbitrary locations.
2615 Usually `tar' determines automatically whether the archive can be
2616 seeked or not. Use this option to disable this mechanism.
2619 Treat all input file or member names literally, do not interpret
2620 escape sequences. *Note input name quoting::.
2623 Do not use wildcards. *Note controlling pattern-matching::.
2625 `--no-wildcards-match-slash'
2626 Wildcards do not match `/'. *Note controlling pattern-matching::.
2629 When `tar' is using the `--files-from' option, this option
2630 instructs `tar' to expect file names terminated with NUL, so `tar'
2631 can correctly work with file names that contain newlines. *Note
2635 This option will notify `tar' that it should use numeric user and
2636 group IDs when creating a `tar' file, rather than names. *Note
2640 The function of this option depends on the action `tar' is
2641 performing. When extracting files, `-o' is a synonym for
2642 `--no-same-owner', i.e., it prevents `tar' from restoring
2643 ownership of files being extracted.
2645 When creating an archive, it is a synonym for `--old-archive'.
2646 This behavior is for compatibility with previous versions of GNU
2647 `tar', and will be removed in future releases.
2649 *Note Changes::, for more information.
2651 `--occurrence[=NUMBER]'
2652 This option can be used in conjunction with one of the subcommands
2653 `--delete', `--diff', `--extract' or `--list' when a list of files
2654 is given either on the command line or via `-T' option.
2656 This option instructs `tar' to process only the NUMBERth
2657 occurrence of each named file. NUMBER defaults to 1, so
2659 tar -x -f archive.tar --occurrence filename
2661 will extract the first occurrence of the member `filename' from
2662 `archive.tar' and will terminate without scanning to the end of
2666 Synonym for `--format=v7'.
2669 Used when creating an archive. Prevents `tar' from recursing into
2670 directories that are on different file systems from the current
2674 Overwrite existing files and directory metadata when extracting
2675 files from an archive. *Note Overwrite Old Files::.
2678 Overwrite the metadata of existing directories when extracting
2679 files from an archive. *Note Overwrite Old Files::.
2682 Specifies that `tar' should use USER as the owner of members when
2683 creating archives, instead of the user associated with the source
2684 file. USER is first decoded as a user symbolic name, but if this
2685 interpretation fails, it has to be a decimal numeric user ID.
2688 This option does not affect extraction from archives.
2690 `--pax-option=KEYWORD-LIST'
2691 This option enables creation of the archive in POSIX.1-2001 format
2692 (*note posix::) and modifies the way `tar' handles the extended
2693 header keywords. KEYWORD-LIST is a comma-separated list of
2694 keyword options. *Note PAX keywords::, for a detailed discussion.
2698 Synonym for `--format=v7'.
2701 Same as `--format=posix'.
2704 Synonymous with specifying both `--preserve-permissions' and
2705 `--same-order'. *Note Setting Access Permissions::.
2708 (See `--same-order'; *note Reading::.)
2710 `--preserve-permissions'
2711 `--same-permissions'
2713 When `tar' is extracting an archive, it normally subtracts the
2714 users' umask from the permissions specified in the archive and uses
2715 that number as the permissions to create the destination file.
2716 Specifying this option instructs `tar' that it should use the
2717 permissions directly from the archive. *Note Setting Access
2720 `--quote-chars=STRING'
2721 Always quote characters from STRING, even if the selected quoting
2722 style would not quote them (*note quoting styles::).
2724 `--quoting-style=STYLE'
2725 Set quoting style to use when printing member and file names
2726 (*note quoting styles::). Valid STYLE values are: `literal',
2727 `shell', `shell-always', `c', `escape', `locale', and `clocale'.
2728 Default quoting style is `escape', unless overridden while
2729 configuring the package.
2731 `--read-full-records'
2733 Specifies that `tar' should reblock its input, for reading from
2734 pipes on systems with buggy implementations. *Note Reading::.
2736 `--record-size=SIZE'
2737 Instructs `tar' to use SIZE bytes per record when accessing the
2738 archive. *Note Blocking Factor::.
2741 With this option, `tar' recurses into directories (default).
2744 `--recursive-unlink'
2745 Remove existing directory hierarchies before extracting
2746 directories of the same name from the archive. *Note Recursive
2750 Directs `tar' to remove the source file from the file system after
2751 appending it to an archive. *Note remove files::.
2754 Disable use of some potentially harmful `tar' options. Currently
2755 this option disables shell invocation from multi-volume menu
2756 (*note Using Multiple Tapes::).
2759 Notifies `tar' that it should use CMD instead of the default
2760 `/usr/libexec/rmt' (*note Remote Tape Server::).
2763 Notifies `tar' that is should use CMD to communicate with remote
2764 devices. *Note Device::.
2769 This option is an optimization for `tar' when running on machines
2770 with small amounts of memory. It informs `tar' that the list of
2771 file arguments has already been sorted to match the order of files
2772 in the archive. *Note Reading::.
2775 When extracting an archive, `tar' will attempt to preserve the
2776 owner specified in the `tar' archive with this option present.
2777 This is the default behavior for the superuser; this option has an
2778 effect only for ordinary users. *Note Attributes::.
2780 `--same-permissions'
2781 (See `--preserve-permissions'; *note Setting Access Permissions::.)
2785 Assume that the archive media supports seeks to arbitrary
2786 locations. Usually `tar' determines automatically whether the
2787 archive can be seeked or not. This option is intended for use in
2788 cases when such recognition fails. It takes effect only if the
2789 archive is open for reading (e.g. with `--list' or `--extract'
2793 Displays the default options used by `tar' and exits successfully.
2794 This option is intended for use in shell scripts. Here is an
2795 example of what you can see using this option:
2797 $ tar --show-defaults
2798 --format=gnu -f- -b20 --quoting-style=escape
2799 --rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
2801 Notice, that this option outputs only one line. The example output
2802 above has been split to fit page boundaries.
2804 `--show-omitted-dirs'
2805 Instructs `tar' to mention the directories it is skipping when
2806 operating on a `tar' archive. *Note show-omitted-dirs::.
2808 `--show-transformed-names'
2809 `--show-stored-names'
2810 Display file or member names after applying any transformations
2811 (*note transform::). In particular, when used in conjunction with
2812 one of the archive creation operations it instructs `tar' to list
2813 the member names stored in the archive, as opposed to the actual
2814 file names. *Note listing member and file names::.
2818 Invokes a GNU extension when adding files to an archive that
2819 handles sparse files efficiently. *Note sparse::.
2821 `--sparse-version=VERSION'
2822 Specifies the "format version" to use when archiving sparse files.
2823 Implies `--sparse'. *Note sparse::. For the description of the
2824 supported sparse formats, *Note Sparse Formats::.
2826 `--starting-file=NAME'
2828 This option affects extraction only; `tar' will skip extracting
2829 files in the archive until it finds one that matches NAME. *Note
2832 `--strip-components=NUMBER'
2833 Strip given NUMBER of leading components from file names before
2834 extraction. For example, if archive `archive.tar' contained
2835 `/some/file/name', then running
2837 tar --extract --file archive.tar --strip-components=2
2839 would extract this file to file `name'.
2842 Alters the suffix `tar' uses when backing up files from the default
2843 `~'. *Note backup::.
2847 Specifies the length of tapes that `tar' is writing as being
2848 NUM x 1024 bytes long. *Note Using Multiple Tapes::.
2851 Reads the volume label. If an argument is specified, test whether
2852 it matches the volume label. *Note --test-label option::.
2854 `--to-command=COMMAND'
2855 During extraction `tar' will pipe extracted files to the standard
2856 input of COMMAND. *Note Writing to an External Program::.
2860 During extraction, `tar' will extract files to stdout rather than
2861 to the file system. *Note Writing to Standard Output::.
2864 Displays the total number of bytes transferred when processing an
2865 archive. If an argument is given, these data are displayed on
2866 request, when signal SIGNO is delivered to `tar'. *Note totals::.
2870 Sets the data modification time of extracted files to the
2871 extraction time, rather than the data modification time stored in
2872 the archive. *Note Data Modification Times::.
2874 `--transform=SED-EXPR'
2876 Transform file or member names using `sed' replacement expression
2877 SED-EXPR. For example,
2879 $ tar cf archive.tar --transform 's,^\./,usr/,' .
2881 will add to `archive' files from the current working directory,
2882 replacing initial `./' prefix with `usr/'. For the detailed
2883 discussion, *Note transform::.
2885 To see transformed member names in verbose listings, use
2886 `--show-transformed-names' option (*note show-transformed-names::).
2889 (See `--compress'. *note gzip::)
2892 (See `--gzip'. *note gzip::)
2896 Directs `tar' to remove the corresponding file from the file
2897 system before extracting it from the archive. *Note Unlink
2901 Enable unquoting input file or member names (default). *Note
2902 input name quoting::.
2904 `--use-compress-program=PROG'
2906 Instructs `tar' to access the archive through PROG, which is
2907 presumed to be a compression program of some sort. *Note gzip::.
2910 Display file modification dates in UTC. This option implies
2915 Specifies that `tar' should be more verbose about the operations
2916 it is performing. This option can be specified multiple times for
2917 some operations to increase the amount of information displayed.
2922 Verifies that the archive was correctly written when creating an
2923 archive. *Note verify::.
2926 Print information about the program's name, version, origin and
2927 legal status, all on standard output, and then exit successfully.
2931 Used in conjunction with `--multi-volume'. `tar' will keep track
2932 of which volume of a multi-volume archive it is working in FILE.
2936 Enable or disable warning messages identified by KEYWORD. The
2937 messages are suppressed if KEYWORD is prefixed with `no-'. *Note
2941 Use wildcards when matching member names with patterns. *Note
2942 controlling pattern-matching::.
2944 `--wildcards-match-slash'
2945 Wildcards match `/'. *Note controlling pattern-matching::.
2949 Use `xz' for compressing or decompressing the archives. *Note
2953 ---------- Footnotes ----------
2955 (1) Earlier versions of GNU `tar' understood `-l' as a synonym for
2956 `--one-file-system'. The current semantics, which complies to UNIX98,
2957 was introduced with version 1.15.91. *Note Changes::, for more
2961 File: tar.info, Node: Short Option Summary, Prev: Option Summary, Up: All Options
2963 3.4.3 Short Options Cross Reference
2964 -----------------------------------
2966 Here is an alphabetized list of all of the short option forms, matching
2967 them with the equivalent long option.
2969 Short Option Reference
2970 --------------------------------------------------------------------------
2971 -A *note --concatenate::.
2972 -B *note --read-full-records::.
2973 -C *note --directory::.
2974 -F *note --info-script::.
2975 -G *note --incremental::.
2977 -K *note --starting-file::.
2978 -L *note --tape-length::.
2979 -M *note --multi-volume::.
2981 -O *note --to-stdout::.
2982 -P *note --absolute-names::.
2983 -R *note --block-number::.
2984 -S *note --sparse::.
2985 -T *note --files-from::.
2986 -U *note --unlink-first::.
2988 -W *note --verify::.
2989 -X *note --exclude-from::.
2990 -Z *note --compress::.
2991 -b *note --blocking-factor::.
2992 -c *note --create::.
2993 -d *note --compare::.
2995 -g *note --listed-incremental::.
2996 -h *note --dereference::.
2997 -i *note --ignore-zeros::.
2999 -k *note --keep-old-files::.
3000 -l *note --check-links::.
3002 -o When creating, *note --no-same-owner::, when extracting --
3003 *note --portability::.
3005 The latter usage is deprecated. It is retained for
3006 compatibility with the earlier versions of GNU `tar'. In
3007 future releases `-o' will be equivalent to
3008 `--no-same-owner' only.
3009 -p *note --preserve-permissions::.
3010 -r *note --append::.
3011 -s *note --same-order::.
3013 -u *note --update::.
3014 -v *note --verbose::.
3015 -w *note --interactive::.
3016 -x *note --extract::.
3020 File: tar.info, Node: help, Next: defaults, Prev: All Options, Up: tar invocation
3022 3.5 GNU `tar' documentation
3023 ===========================
3025 Being careful, the first thing is really checking that you are using
3026 GNU `tar', indeed. The `--version' option causes `tar' to print
3027 information about its name, version, origin and legal status, all on
3028 standard output, and then exit successfully. For example,
3029 `tar --version' might print:
3032 Copyright (C) 2010 Free Software Foundation, Inc.
3033 Copyright (C) 2010 Free Software Foundation, Inc.
3034 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
3035 This is free software: you are free to change and redistribute it.
3036 There is NO WARRANTY, to the extent permitted by law.
3038 Written by John Gilmore and Jay Fenlason.
3040 The first occurrence of `tar' in the result above is the program name
3041 in the package (for example, `rmt' is another program), while the
3042 second occurrence of `tar' is the name of the package itself,
3043 containing possibly many programs. The package is currently named
3044 `tar', after the name of the main program it contains(1).
3046 Another thing you might want to do is checking the spelling or
3047 meaning of some particular `tar' option, without resorting to this
3048 manual, for once you have carefully read it. GNU `tar' has a short
3049 help feature, triggerable through the `--help' option. By using this
3050 option, `tar' will print a usage message listing all available options
3051 on standard output, then exit successfully, without doing anything else
3052 and ignoring all other options. Even if this is only a brief summary,
3053 it may be several screens long. So, if you are not using some kind of
3054 scrollable window, you might prefer to use something like:
3058 presuming, here, that you like using `less' for a pager. Other popular
3059 pagers are `more' and `pg'. If you know about some KEYWORD which
3060 interests you and do not want to read all the `--help' output, another
3061 common idiom is doing:
3063 tar --help | grep KEYWORD
3065 for getting only the pertinent lines. Notice, however, that some `tar'
3066 options have long description lines and the above command will list
3067 only the first of them.
3069 The exact look of the option summary displayed by `tar --help' is
3070 configurable. *Note Configuring Help Summary::, for a detailed
3073 If you only wish to check the spelling of an option, running `tar
3074 --usage' may be a better choice. This will display a terse list of
3075 `tar' options without accompanying explanations.
3077 The short help output is quite succinct, and you might have to get
3078 back to the full documentation for precise points. If you are reading
3079 this paragraph, you already have the `tar' manual in some form. This
3080 manual is available in a variety of forms from
3081 `http://www.gnu.org/software/tar/manual'. It may be printed out of the
3082 GNU `tar' distribution, provided you have TeX already installed
3083 somewhere, and a laser printer around. Just configure the
3084 distribution, execute the command `make dvi', then print `doc/tar.dvi'
3085 the usual way (contact your local guru to know how). If GNU `tar' has
3086 been conveniently installed at your place, this manual is also
3087 available in interactive, hypertextual form as an Info file. Just call
3088 `info tar' or, if you do not have the `info' program handy, use the
3089 Info reader provided within GNU Emacs, calling `tar' from the main Info
3092 There is currently no `man' page for GNU `tar'. If you observe such
3093 a `man' page on the system you are running, either it does not belong
3094 to GNU `tar', or it has not been produced by GNU. Some package
3095 maintainers convert `tar --help' output to a man page, using
3096 `help2man'. In any case, please bear in mind that the authoritative
3097 source of information about GNU `tar' is this Texinfo documentation.
3099 ---------- Footnotes ----------
3101 (1) There are plans to merge the `cpio' and `tar' packages into a
3102 single one which would be called `paxutils'. So, who knows if, one of
3103 this days, the `--version' would not output `tar (GNU paxutils) 3.2'.
3106 File: tar.info, Node: defaults, Next: verbose, Prev: help, Up: tar invocation
3108 3.6 Obtaining GNU `tar' default values
3109 ======================================
3111 GNU `tar' has some predefined defaults that are used when you do not
3112 explicitly specify another values. To obtain a list of such defaults,
3113 use `--show-defaults' option. This will output the values in the form
3114 of `tar' command line options:
3116 $ tar --show-defaults
3117 --format=gnu -f- -b20 --quoting-style=escape
3118 --rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
3120 Notice, that this option outputs only one line. The example output
3121 above has been split to fit page boundaries.
3123 The above output shows that this version of GNU `tar' defaults to using
3124 `gnu' archive format (*note Formats::), it uses standard output as the
3125 archive, if no `--file' option has been given (*note file tutorial::),
3126 the default blocking factor is 20 (*note Blocking Factor::). It also
3127 shows the default locations where `tar' will look for `rmt' and `rsh'
3131 File: tar.info, Node: verbose, Next: checkpoints, Prev: defaults, Up: tar invocation
3133 3.7 Checking `tar' progress
3134 ===========================
3136 Typically, `tar' performs most operations without reporting any
3137 information to the user except error messages. When using `tar' with
3138 many options, particularly ones with complicated or
3139 difficult-to-predict behavior, it is possible to make serious mistakes.
3140 `tar' provides several options that make observing `tar' easier. These
3141 options cause `tar' to print information as it progresses in its job,
3142 and you might want to use them just for being more careful about what
3143 is going on, or merely for entertaining yourself. If you have
3144 encountered a problem when operating on an archive, however, you may
3145 need more information than just an error message in order to solve the
3146 problem. The following options can be helpful diagnostic tools.
3148 Normally, the `--list' (`-t') command to list an archive prints just
3149 the file names (one per line) and the other commands are silent. When
3150 used with most operations, the `--verbose' (`-v') option causes `tar'
3151 to print the name of each file or archive member as it is processed.
3152 This and the other options which make `tar' print status information
3153 can be useful in monitoring `tar'.
3155 With `--create' or `--extract', `--verbose' used once just prints
3156 the names of the files or members as they are processed. Using it
3157 twice causes `tar' to print a longer listing (*Note verbose member
3158 listing::, for the description) for each member. Since `--list'
3159 already prints the names of the members, `--verbose' used once with
3160 `--list' causes `tar' to print an `ls -l' type listing of the files in
3161 the archive. The following examples both extract members with long
3164 $ tar --extract --file=archive.tar --verbose --verbose
3165 $ tar xvvf archive.tar
3167 Verbose output appears on the standard output except when an archive
3168 is being written to the standard output, as with `tar --create --file=-
3169 --verbose' (`tar cfv -', or even `tar cv'--if the installer let
3170 standard output be the default archive). In that case `tar' writes
3171 verbose output to the standard error stream.
3173 If `--index-file=FILE' is specified, `tar' sends verbose output to
3174 FILE rather than to standard output or standard error.
3176 The `--totals' option causes `tar' to print on the standard error
3177 the total amount of bytes transferred when processing an archive. When
3178 creating or appending to an archive, this option prints the number of
3179 bytes written to the archive and the average speed at which they have
3182 $ tar -c -f archive.tar --totals /home
3183 Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
3185 When reading an archive, this option displays the number of bytes
3188 $ tar -x -f archive.tar --totals
3189 Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
3191 Finally, when deleting from an archive, the `--totals' option
3192 displays both numbers plus number of bytes removed from the archive:
3194 $ tar --delete -f foo.tar --totals --wildcards '*~'
3195 Total bytes read: 9543680 (9.2MiB, 201MiB/s)
3196 Total bytes written: 3829760 (3.7MiB, 81MiB/s)
3197 Total bytes deleted: 1474048
3199 You can also obtain this information on request. When `--totals' is
3200 used with an argument, this argument is interpreted as a symbolic name
3201 of a signal, upon delivery of which the statistics is to be printed:
3204 Print statistics upon delivery of signal SIGNO. Valid arguments
3205 are: `SIGHUP', `SIGQUIT', `SIGINT', `SIGUSR1' and `SIGUSR2'.
3206 Shortened names without `SIG' prefix are also accepted.
3208 Both forms of `--totals' option can be used simultaneously. Thus,
3209 `tar -x --totals --totals=USR1' instructs `tar' to extract all members
3210 from its default archive and print statistics after finishing the
3211 extraction, as well as when receiving signal `SIGUSR1'.
3213 The `--checkpoint' option prints an occasional message as `tar'
3214 reads or writes the archive. It is designed for those who don't need
3215 the more detailed (and voluminous) output of `--block-number' (`-R'),
3216 but do want visual confirmation that `tar' is actually making forward
3217 progress. By default it prints a message each 10 records read or
3218 written. This can be changed by giving it a numeric argument after an
3221 $ tar -c --checkpoint=1000 /var
3222 tar: Write checkpoint 1000
3223 tar: Write checkpoint 2000
3224 tar: Write checkpoint 3000
3226 This example shows the default checkpoint message used by `tar'. If
3227 you place a dot immediately after the equal sign, it will print a `.'
3228 at each checkpoint(1). For example:
3230 $ tar -c --checkpoint=.1000 /var
3233 The `--checkpoint' option provides a flexible mechanism for
3234 executing arbitrary actions upon hitting checkpoints, see the next
3235 section (*note checkpoints::), for more information on it.
3237 The `--show-omitted-dirs' option, when reading an archive--with
3238 `--list' or `--extract', for example--causes a message to be printed
3239 for each directory in the archive which is skipped. This happens
3240 regardless of the reason for skipping: the directory might not have
3241 been named on the command line (implicitly or explicitly), it might be
3242 excluded by the use of the `--exclude=PATTERN' option, or some other
3245 If `--block-number' (`-R') is used, `tar' prints, along with every
3246 message it would normally produce, the block number within the archive
3247 where the message was triggered. Also, supplementary messages are
3248 triggered when reading blocks full of NULs, or when hitting end of file
3249 on the archive. As of now, if the archive is properly terminated with
3250 a NUL block, the reading of the file may stop before end of file is
3251 met, so the position of end of file will not usually show when
3252 `--block-number' (`-R') is used. Note that GNU `tar' drains the
3253 archive before exiting when reading the archive from a pipe.
3255 This option is especially useful when reading damaged archives, since
3256 it helps pinpoint the damaged sections. It can also be used with
3257 `--list' (`-t') when listing a file-system backup tape, allowing you to
3258 choose among several backup tapes when retrieving a file later, in
3259 favor of the tape where the file appears earliest (closest to the front
3260 of the tape). *Note backup::.
3262 ---------- Footnotes ----------
3264 (1) This is actually a shortcut for `--checkpoint=N
3265 --checkpoint-action=dot'. *Note dot: checkpoints.
3268 File: tar.info, Node: checkpoints, Next: warnings, Prev: verbose, Up: tar invocation
3273 A "checkpoint" is a moment of time before writing Nth record to the
3274 archive (a "write checkpoint"), or before reading Nth record from the
3275 archive (a "read checkpoint"). Checkpoints allow to periodically
3276 execute arbitrary actions.
3278 The checkpoint facility is enabled using the following option:
3281 Schedule checkpoints before writing or reading each Nth record.
3282 The default value for N is 10.
3284 A list of arbitrary "actions" can be executed at each checkpoint.
3285 These actions include: pausing, displaying textual messages, and
3286 executing arbitrary external programs. Actions are defined using the
3287 `--checkpoint-action' option.
3289 `--checkpoint-action=ACTION'
3290 Execute an ACTION at each checkpoint.
3292 The simplest value of ACTION is `echo'. It instructs `tar' to
3293 display the default message on the standard error stream upon arriving
3294 at each checkpoint. The default message is (in POSIX locale) `Write
3295 checkpoint N', for write checkpoints, and `Read checkpoint N', for read
3296 checkpoints. Here, N represents ordinal number of the checkpoint.
3298 In another locales, translated versions of this message are used.
3300 This is the default action, so running:
3302 $ tar -c --checkpoint=1000 --checkpoint-action=echo /var
3306 $ tar -c --checkpoint=1000 /var
3308 The `echo' action also allows to supply a customized message. You
3309 do so by placing an equals sign and the message right after it, e.g.:
3311 --checkpoint-action="echo=Hit %s checkpoint #%u"
3313 The `%s' and `%u' in the above example are "meta-characters". The
3314 `%s' meta-character is replaced with the "type" of the checkpoint:
3315 `write' or `read' (or a corresponding translated version in locales
3316 other than POSIX). The `%u' meta-character is replaced with the
3317 ordinal number of the checkpoint. Thus, the above example could
3318 produce the following output when used with the `--create' option:
3320 tar: Hit write checkpoint #10
3321 tar: Hit write checkpoint #20
3322 tar: Hit write checkpoint #30
3324 Aside from meta-character expansion, the message string is subject to
3325 "unquoting", during which the backslash "escape sequences" are replaced
3326 with their corresponding ASCII characters (*note escape sequences::).
3327 E.g. the following action will produce an audible bell and the message
3328 described above at each checkpoint:
3330 --checkpoint-action='echo=\aHit %s checkpoint #%u'
3332 There is also a special action which produces an audible signal:
3333 `bell'. It is not equivalent to `echo='\a'', because `bell' sends the
3334 bell directly to the console (`/dev/tty'), whereas `echo='\a'' sends it
3335 to the standard error.
3337 The `ttyout=STRING' action outputs STRING to `/dev/tty', so it can
3338 be used even if the standard output is redirected elsewhere. The
3339 STRING is subject to the same modifications as with `echo' action. In
3340 contrast to the latter, `ttyout' does not prepend `tar' executable name
3341 to the string, nor does it output a newline after it. For example, the
3342 following action will print the checkpoint message at the same screen
3343 line, overwriting any previous message:
3345 --checkpoint-action="ttyout=\rHit %s checkpoint #%u"
3347 Another available checkpoint action is `dot' (or `.'). It instructs
3348 `tar' to print a single dot on the standard listing stream, e.g.:
3350 $ tar -c --checkpoint=1000 --checkpoint-action=dot /var
3353 For compatibility with previous GNU `tar' versions, this action can
3354 be abbreviated by placing a dot in front of the checkpoint frequency,
3355 as shown in the previous section.
3357 Yet another action, `sleep', pauses `tar' for a specified amount of
3358 seconds. The following example will stop for 30 seconds at each
3361 $ tar -c --checkpoint=1000 --checkpoint-action=sleep=30
3363 Finally, the `exec' action executes a given external program. For
3366 $ tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint
3368 This program is executed using `/bin/sh -c', with no additional
3369 arguments. Its exit code is ignored. It gets a copy of `tar''s
3370 environment plus the following variables:
3373 GNU `tar' version number.
3376 The name of the archive `tar' is processing.
3378 `TAR_BLOCKING_FACTOR'
3379 Current blocking factor (*note Blocking::).
3382 Number of the checkpoint.
3385 A short option describing the operation `tar' is executing. *Note
3386 Operations::, for a complete list of subcommand options.
3389 Format of the archive being processed. *Note Formats::, for a
3390 complete list of archive format names.
3392 Any number of actions can be defined, by supplying several
3393 `--checkpoint-action' options in the command line. For example, the
3394 command below displays two messages, pauses execution for 30 seconds
3395 and executes the `/sbin/cpoint' script:
3397 $ tar -c -f arc.tar \
3398 --checkpoint-action='\aecho=Hit %s checkpoint #%u' \
3399 --checkpoint-action='echo=Sleeping for 30 seconds' \
3400 --checkpoint-action='sleep=30' \
3401 --checkpoint-action='exec=/sbin/cpoint'
3403 This example also illustrates the fact that `--checkpoint-action'
3404 can be used without `--checkpoint'. In this case, the default
3405 checkpoint frequency (at each 10th record) is assumed.
3408 File: tar.info, Node: warnings, Next: interactive, Prev: checkpoints, Up: tar invocation
3410 3.9 Controlling Warning Messages
3411 ================================
3413 Sometimes, while performing the requested task, GNU `tar' notices some
3414 conditions that are not exactly errors, but which the user should be
3415 aware of. When this happens, `tar' issues a "warning message"
3416 describing the condition. Warning messages are output to the standard
3417 error and they do not affect the exit code of `tar' command.
3419 GNU `tar' allows the user to suppress some or all of its warning
3423 Control display of the warning messages identified by KEYWORD. If
3424 KEYWORD starts with the prefix `no-', such messages are
3425 suppressed. Otherwise, they are enabled.
3427 Multiple `--warning' messages accumulate.
3429 The tables below list allowed values for KEYWORD along with the
3430 warning messages they control.
3432 Keywords controlling `tar' operation
3433 ------------------------------------
3436 Enable all warning messages. This is the default.
3439 Disable all warning messages.
3442 `%s: file name read contains nul character'
3445 `A lone zero block at %s'
3447 Keywords applicable for `tar --create'
3448 --------------------------------------
3451 `%s: contains a cache directory tag %s; %s'
3454 `%s: File shrank by %s bytes; padding with zeros'
3457 `%s: file is on a different filesystem; not dumped'
3460 `%s: Unknown file type; file ignored'
3461 `%s: socket ignored'
3465 `%s: file is unchanged; not dumped'
3468 `%s: file is the archive; not dumped'
3471 `%s: File removed before we read it'
3474 `%s: file changed as we read it'
3476 Keywords applicable for `tar --extract'
3477 ---------------------------------------
3480 `%s: implausibly old time stamp %s'
3481 `%s: time stamp %s is %s s in the future'
3484 `Extracting contiguous files as regular files'
3487 `Attempting extraction of symbolic links as hard links'
3490 `%s: Unknown file type `%c', extracted as normal file'
3493 `Current %s is newer or same age'
3496 `Ignoring unknown extended header keyword `%s''
3498 Keywords controlling incremental extraction:
3499 --------------------------------------------
3502 `%s: Directory has been renamed from %s'
3503 `%s: Directory has been renamed'
3506 `%s: Directory is new'
3509 `%s: directory is on a different device: not purging'
3512 `Malformed dumpdir: 'X' never used'
3515 File: tar.info, Node: interactive, Prev: warnings, Up: tar invocation
3517 3.10 Asking for Confirmation During Operations
3518 ==============================================
3520 Typically, `tar' carries out a command without stopping for further
3521 instructions. In some situations however, you may want to exclude some
3522 files and archive members from the operation (for instance if disk or
3523 storage space is tight). You can do this by excluding certain files
3524 automatically (*note Choosing::), or by performing an operation
3525 interactively, using the `--interactive' (`-w') option. `tar' also
3526 accepts `--confirmation' for this option.
3528 When the `--interactive' (`-w') option is specified, before reading,
3529 writing, or deleting files, `tar' first prints a message for each such
3530 file, telling what operation it intends to take, then asks for
3531 confirmation on the terminal. The actions which require confirmation
3532 include adding a file to the archive, extracting a file from the
3533 archive, deleting a file from the archive, and deleting a file from
3534 disk. To confirm the action, you must type a line of input beginning
3535 with `y'. If your input line begins with anything other than `y',
3536 `tar' skips that file.
3538 If `tar' is reading the archive from the standard input, `tar' opens
3539 the file `/dev/tty' to support the interactive communications.
3541 Verbose output is normally sent to standard output, separate from
3542 other error messages. However, if the archive is produced directly on
3543 standard output, then verbose output is mixed with errors on `stderr'.
3544 Producing the archive on standard output may be used as a way to avoid
3545 using disk space, when the archive is soon to be consumed by another
3546 process reading it, say. Some people felt the need of producing an
3547 archive on stdout, still willing to segregate between verbose output
3548 and error output. A possible approach would be using a named pipe to
3549 receive the archive, and having the consumer process to read from that
3550 named pipe. This has the advantage of letting standard output free to
3551 receive verbose output, all separate from errors.
3554 File: tar.info, Node: operations, Next: Backups, Prev: tar invocation, Up: Top
3556 4 GNU `tar' Operations
3557 **********************
3570 File: tar.info, Node: Basic tar, Next: Advanced tar, Up: operations
3572 4.1 Basic GNU `tar' Operations
3573 ==============================
3575 The basic `tar' operations, `--create' (`-c'), `--list' (`-t') and
3576 `--extract' (`--get', `-x'), are currently presented and described in
3577 the tutorial chapter of this manual. This section provides some
3578 complementary notes for these operations.
3582 Creating an empty archive would have some kind of elegance. One
3583 can initialize an empty archive and later use `--append' (`-r')
3584 for adding all members. Some applications would not welcome
3585 making an exception in the way of adding the first archive member.
3586 On the other hand, many people reported that it is dangerously too
3587 easy for `tar' to destroy a magnetic tape with an empty
3588 archive(1). The two most common errors are:
3590 1. Mistakingly using `create' instead of `extract', when the
3591 intent was to extract the full contents of an archive. This
3592 error is likely: keys `c' and `x' are right next to each
3593 other on the QWERTY keyboard. Instead of being unpacked, the
3594 archive then gets wholly destroyed. When users speak about
3595 "exploding" an archive, they usually mean something else :-).
3597 2. Forgetting the argument to `file', when the intent was to
3598 create an archive with a single file in it. This error is
3599 likely because a tired user can easily add the `f' key to the
3600 cluster of option letters, by the mere force of habit,
3601 without realizing the full consequence of doing so. The
3602 usual consequence is that the single file, which was meant to
3603 be saved, is rather destroyed.
3605 So, recognizing the likelihood and the catastrophic nature of these
3606 errors, GNU `tar' now takes some distance from elegance, and
3607 cowardly refuses to create an archive when `--create' option is
3608 given, there are no arguments besides options, and `--files-from'
3609 (`-T') option is _not_ used. To get around the cautiousness of
3610 GNU `tar' and nevertheless create an archive with nothing in it,
3611 one may still use, as the value for the `--files-from' option, a
3612 file with no names in it, as shown in the following commands:
3614 tar --create --file=empty-archive.tar --files-from=/dev/null
3615 tar cfT empty-archive.tar /dev/null
3620 A socket is stored, within a GNU `tar' archive, as a pipe.
3623 GNU `tar' now shows dates as `1996-08-30', while it used to show
3624 them as `Aug 30 1996'. Preferably, people should get used to ISO
3625 8601 dates. Local American dates should be made available again
3626 with full date localization support, once ready. In the meantime,
3627 programs not being localizable for dates should prefer
3628 international dates, that's really the way to go.
3630 Look up `http://www.cl.cam.ac.uk/~mgk25/iso-time.html' if you are
3631 curious, it contains a detailed explanation of the ISO 8601
3635 ---------- Footnotes ----------
3637 (1) This is well described in `Unix-haters Handbook', by Simson
3638 Garfinkel, Daniel Weise & Steven Strassmann, IDG Books, ISBN
3642 File: tar.info, Node: Advanced tar, Next: create options, Prev: Basic tar, Up: operations
3644 4.2 Advanced GNU `tar' Operations
3645 =================================
3647 Now that you have learned the basics of using GNU `tar', you may want
3648 to learn about further ways in which `tar' can help you.
3650 This chapter presents five, more advanced operations which you
3651 probably won't use on a daily basis, but which serve more specialized
3652 functions. We also explain the different styles of options and why you
3653 might want to use one or another, or a combination of them in your `tar'
3654 commands. Additionally, this chapter includes options which allow you
3655 to define the output from `tar' more carefully, and provide help and
3656 error correction in special circumstances.
3668 File: tar.info, Node: Operations, Next: append, Up: Advanced tar
3670 4.2.1 The Five Advanced `tar' Operations
3671 ----------------------------------------
3673 In the last chapter, you learned about the first three operations to
3674 `tar'. This chapter presents the remaining five operations to `tar':
3675 `--append', `--update', `--concatenate', `--delete', and `--compare'.
3677 You are not likely to use these operations as frequently as those
3678 covered in the last chapter; however, since they perform specialized
3679 functions, they are quite useful when you do need to use them. We will
3680 give examples using the same directory and files that you created in
3681 the last chapter. As you may recall, the directory is called
3682 `practice', the files are `jazz', `blues', `folk', and the two archive
3683 files you created are `collection.tar' and `music.tar'.
3685 We will also use the archive files `afiles.tar' and `bfiles.tar'.
3686 The archive `afiles.tar' contains the members `apple', `angst', and
3687 `aspic'; `bfiles.tar' contains the members `./birds', `baboon', and
3690 Unless we state otherwise, all practicing you do and examples you
3691 follow in this chapter will take place in the `practice' directory that
3692 you created in the previous chapter; see *note prepare for examples::.
3693 (Below in this section, we will remind you of the state of the examples
3694 where the last chapter left them.)
3696 The five operations that we will cover in this chapter are:
3700 Add new entries to an archive that already exists.
3704 Add more recent copies of archive members to the end of an
3705 archive, if they exist.
3710 Add one or more pre-existing archives to the end of another
3714 Delete items from an archive (does not work on tapes).
3719 Compare archive members to their counterparts in the file system.
3722 File: tar.info, Node: append, Next: update, Prev: Operations, Up: Advanced tar
3724 4.2.2 How to Add Files to Existing Archives: `--append'
3725 -------------------------------------------------------
3727 If you want to add files to an existing archive, you don't need to
3728 create a new archive; you can use `--append' (`-r'). The archive must
3729 already exist in order to use `--append'. (A related operation is the
3730 `--update' operation; you can use this to add newer versions of archive
3731 members to an existing archive. To learn how to do this with
3732 `--update', *note update::.)
3734 If you use `--append' to add a file that has the same name as an
3735 archive member to an archive containing that archive member, then the
3736 old member is not deleted. What does happen, however, is somewhat
3737 complex. `tar' _allows_ you to have infinite number of files with the
3738 same name. Some operations treat these same-named members no
3739 differently than any other set of archive members: for example, if you
3740 view an archive with `--list' (`-t'), you will see all of those members
3741 listed, with their data modification times, owners, etc.
3743 Other operations don't deal with these members as perfectly as you
3744 might prefer; if you were to use `--extract' to extract the archive,
3745 only the most recently added copy of a member with the same name as
3746 other members would end up in the working directory. This is because
3747 `--extract' extracts an archive in the order the members appeared in
3748 the archive; the most recently archived members will be extracted last.
3749 Additionally, an extracted member will _replace_ a file of the same
3750 name which existed in the directory already, and `tar' will not prompt
3751 you about this(1). Thus, only the most recently archived member will
3752 end up being extracted, as it will replace the one extracted before it,
3755 There exists a special option that allows you to get around this
3756 behavior and extract (or list) only a particular copy of the file.
3757 This is `--occurrence' option. If you run `tar' with this option, it
3758 will extract only the first copy of the file. You may also give this
3759 option an argument specifying the number of copy to be extracted.
3760 Thus, for example if the archive `archive.tar' contained three copies
3761 of file `myfile', then the command
3763 tar --extract --file archive.tar --occurrence=2 myfile
3765 would extract only the second copy. *Note --occurrence: Option
3766 Summary, for the description of `--occurrence' option.
3768 If you want to replace an archive member, use `--delete' to delete
3769 the member you want to remove from the archive, and then use `--append'
3770 to add the member you want to be in the archive. Note that you can not
3771 change the order of the archive; the most recently added member will
3772 still appear last. In this sense, you cannot truly "replace" one
3773 member with another. (Replacing one member with another will not work
3774 on certain types of media, such as tapes; see *note delete:: and *note
3775 Media::, for more information.)
3779 * appending files:: Appending Files to an Archive
3782 ---------- Footnotes ----------
3784 (1) Unless you give it `--keep-old-files' option, or the disk copy
3785 is newer than the one in the archive and you invoke `tar' with
3786 `--keep-newer-files' option.
3789 File: tar.info, Node: appending files, Next: multiple, Up: append
3791 4.2.2.1 Appending Files to an Archive
3792 .....................................
3794 The simplest way to add a file to an already existing archive is the
3795 `--append' (`-r') operation, which writes specified files into the
3796 archive whether or not they are already among the archived files.
3798 When you use `--append', you _must_ specify file name arguments, as
3799 there is no default. If you specify a file that already exists in the
3800 archive, another copy of the file will be added to the end of the
3801 archive. As with other operations, the member names of the newly added
3802 files will be exactly the same as their names given on the command
3803 line. The `--verbose' (`-v') option will print out the names of the
3804 files as they are written into the archive.
3806 `--append' cannot be performed on some tape drives, unfortunately,
3807 due to deficiencies in the formats those tape drives use. The archive
3808 must be a valid `tar' archive, or else the results of using this
3809 operation will be unpredictable. *Note Media::.
3811 To demonstrate using `--append' to add a file to an archive, create
3812 a file called `rock' in the `practice' directory. Make sure you are in
3813 the `practice' directory. Then, run the following `tar' command to add
3814 `rock' to `collection.tar':
3816 $ tar --append --file=collection.tar rock
3818 If you now use the `--list' (`-t') operation, you will see that `rock'
3819 has been added to the archive:
3821 $ tar --list --file=collection.tar
3822 -rw-r--r-- me user 28 1996-10-18 16:31 jazz
3823 -rw-r--r-- me user 21 1996-09-23 16:44 blues
3824 -rw-r--r-- me user 20 1996-09-23 16:44 folk
3825 -rw-r--r-- me user 20 1996-09-23 16:44 rock
3828 File: tar.info, Node: multiple, Prev: appending files, Up: append
3830 4.2.2.2 Multiple Members with the Same Name
3831 ...........................................
3833 You can use `--append' (`-r') to add copies of files which have been
3834 updated since the archive was created. (However, we do not recommend
3835 doing this since there is another `tar' option called `--update'; *Note
3836 update::, for more information. We describe this use of `--append'
3837 here for the sake of completeness.) When you extract the archive, the
3838 older version will be effectively lost. This works because files are
3839 extracted from an archive in the order in which they were archived.
3840 Thus, when the archive is extracted, a file archived later in time will
3841 replace a file of the same name which was archived earlier, even though
3842 the older version of the file will remain in the archive unless you
3843 delete all versions of the file.
3845 Supposing you change the file `blues' and then append the changed
3846 version to `collection.tar'. As you saw above, the original `blues' is
3847 in the archive `collection.tar'. If you change the file and append the
3848 new version of the file to the archive, there will be two copies in the
3849 archive. When you extract the archive, the older version of the file
3850 will be extracted first, and then replaced by the newer version when it
3853 You can append the new, changed copy of the file `blues' to the
3854 archive in this way:
3856 $ tar --append --verbose --file=collection.tar blues
3859 Because you specified the `--verbose' option, `tar' has printed the
3860 name of the file being appended as it was acted on. Now list the
3861 contents of the archive:
3863 $ tar --list --verbose --file=collection.tar
3864 -rw-r--r-- me user 28 1996-10-18 16:31 jazz
3865 -rw-r--r-- me user 21 1996-09-23 16:44 blues
3866 -rw-r--r-- me user 20 1996-09-23 16:44 folk
3867 -rw-r--r-- me user 20 1996-09-23 16:44 rock
3868 -rw-r--r-- me user 58 1996-10-24 18:30 blues
3870 The newest version of `blues' is now at the end of the archive (note
3871 the different creation dates and file sizes). If you extract the
3872 archive, the older version of the file `blues' will be replaced by the
3873 newer version. You can confirm this by extracting the archive and
3874 running `ls' on the directory.
3876 If you wish to extract the first occurrence of the file `blues' from
3877 the archive, use `--occurrence' option, as shown in the following
3880 $ tar --extract -vv --occurrence --file=collection.tar blues
3881 -rw-r--r-- me user 21 1996-09-23 16:44 blues
3883 *Note Writing::, for more information on `--extract' and *Note
3884 -occurrence: Option Summary, for the description of `--occurrence'
3888 File: tar.info, Node: update, Next: concatenate, Prev: append, Up: Advanced tar
3890 4.2.3 Updating an Archive
3891 -------------------------
3893 In the previous section, you learned how to use `--append' to add a
3894 file to an existing archive. A related operation is `--update' (`-u').
3895 The `--update' operation updates a `tar' archive by comparing the date
3896 of the specified archive members against the date of the file with the
3897 same name. If the file has been modified more recently than the
3898 archive member, then the newer version of the file is added to the
3899 archive (as with `--append').
3901 Unfortunately, you cannot use `--update' with magnetic tape drives.
3902 The operation will fail.
3904 Both `--update' and `--append' work by adding to the end of the
3905 archive. When you extract a file from the archive, only the version
3906 stored last will wind up in the file system, unless you use the
3907 `--backup' option. *Note multiple::, for a detailed discussion.
3914 File: tar.info, Node: how to update, Up: update
3916 4.2.3.1 How to Update an Archive Using `--update'
3917 .................................................
3919 You must use file name arguments with the `--update' (`-u') operation.
3920 If you don't specify any files, `tar' won't act on any files and won't
3921 tell you that it didn't do anything (which may end up confusing you).
3923 To see the `--update' option at work, create a new file,
3924 `classical', in your practice directory, and some extra text to the
3925 file `blues', using any text editor. Then invoke `tar' with the
3926 `update' operation and the `--verbose' (`-v') option specified, using
3927 the names of all the files in the practice directory as file name
3930 $ tar --update -v -f collection.tar blues folk rock classical
3935 Because we have specified verbose mode, `tar' prints out the names of
3936 the files it is working on, which in this case are the names of the
3937 files that needed to be updated. If you run `tar --list' and look at
3938 the archive, you will see `blues' and `classical' at its end. There
3939 will be a total of two versions of the member `blues'; the one at the
3940 end will be newer and larger, since you added text before updating it.
3942 The reason `tar' does not overwrite the older file when updating it
3943 is because writing to the middle of a section of tape is a difficult
3944 process. Tapes are not designed to go backward. *Note Media::, for
3945 more information about tapes.
3947 `--update' (`-u') is not suitable for performing backups for two
3948 reasons: it does not change directory content entries, and it lengthens
3949 the archive every time it is used. The GNU `tar' options intended
3950 specifically for backups are more efficient. If you need to run
3951 backups, please consult *note Backups::.
3954 File: tar.info, Node: concatenate, Next: delete, Prev: update, Up: Advanced tar
3956 4.2.4 Combining Archives with `--concatenate'
3957 ---------------------------------------------
3959 Sometimes it may be convenient to add a second archive onto the end of
3960 an archive rather than adding individual files to the archive. To add
3961 one or more archives to the end of another archive, you should use the
3962 `--concatenate' (`--catenate', `-A') operation.
3964 To use `--concatenate', give the first archive with `--file' option
3965 and name the rest of archives to be concatenated on the command line.
3966 The members, and their member names, will be copied verbatim from those
3967 archives to the first one(1). The new, concatenated archive will be
3968 called by the same name as the one given with the `--file' option. As
3969 usual, if you omit `--file', `tar' will use the value of the environment
3970 variable `TAPE', or, if this has not been set, the default archive name.
3972 To demonstrate how `--concatenate' works, create two small archives
3973 called `bluesrock.tar' and `folkjazz.tar', using the relevant files
3976 $ tar -cvf bluesrock.tar blues rock
3979 $ tar -cvf folkjazz.tar folk jazz
3983 If you like, You can run `tar --list' to make sure the archives contain
3984 what they are supposed to:
3986 $ tar -tvf bluesrock.tar
3987 -rw-r--r-- melissa user 105 1997-01-21 19:42 blues
3988 -rw-r--r-- melissa user 33 1997-01-20 15:34 rock
3989 $ tar -tvf jazzfolk.tar
3990 -rw-r--r-- melissa user 20 1996-09-23 16:44 folk
3991 -rw-r--r-- melissa user 65 1997-01-30 14:15 jazz
3993 We can concatenate these two archives with `tar':
3996 $ tar --concatenate --file=bluesrock.tar jazzfolk.tar
3998 If you now list the contents of the `bluesrock.tar', you will see
3999 that now it also contains the archive members of `jazzfolk.tar':
4001 $ tar --list --file=bluesrock.tar
4007 When you use `--concatenate', the source and target archives must
4008 already exist and must have been created using compatible format
4009 parameters. Notice, that `tar' does not check whether the archives it
4010 concatenates have compatible formats, it does not even check if the
4011 files are really tar archives.
4013 Like `--append' (`-r'), this operation cannot be performed on some
4014 tape drives, due to deficiencies in the formats those tape drives use.
4016 It may seem more intuitive to you to want or try to use `cat' to
4017 concatenate two archives instead of using the `--concatenate'
4018 operation; after all, `cat' is the utility for combining files.
4020 However, `tar' archives incorporate an end-of-file marker which must
4021 be removed if the concatenated archives are to be read properly as one
4022 archive. `--concatenate' removes the end-of-archive marker from the
4023 target archive before each new archive is appended. If you use `cat'
4024 to combine the archives, the result will not be a valid `tar' format
4025 archive. If you need to retrieve files from an archive that was added
4026 to using the `cat' utility, use the `--ignore-zeros' (`-i') option.
4027 *Note Ignore Zeros::, for further information on dealing with archives
4028 improperly combined using the `cat' shell utility.
4030 ---------- Footnotes ----------
4032 (1) This can cause multiple members to have the same name, for
4033 information on how this affects reading the archive, *note multiple::.
4036 File: tar.info, Node: delete, Next: compare, Prev: concatenate, Up: Advanced tar
4038 4.2.5 Removing Archive Members Using `--delete'
4039 -----------------------------------------------
4041 You can remove members from an archive by using the `--delete' option.
4042 Specify the name of the archive with `--file' (`-f') and then specify
4043 the names of the members to be deleted; if you list no member names,
4044 nothing will be deleted. The `--verbose' option will cause `tar' to
4045 print the names of the members as they are deleted. As with
4046 `--extract', you must give the exact member names when using `tar
4047 --delete'. `--delete' will remove all versions of the named file from
4048 the archive. The `--delete' operation can run very slowly.
4050 Unlike other operations, `--delete' has no short form.
4052 This operation will rewrite the archive. You can only use
4053 `--delete' on an archive if the archive device allows you to write to
4054 any point on the media, such as a disk; because of this, it does not
4055 work on magnetic tapes. Do not try to delete an archive member from a
4056 magnetic tape; the action will not succeed, and you will be likely to
4057 scramble the archive and damage your tape. There is no safe way
4058 (except by completely re-writing the archive) to delete files from most
4059 kinds of magnetic tape. *Note Media::.
4061 To delete all versions of the file `blues' from the archive
4062 `collection.tar' in the `practice' directory, make sure you are in that
4063 directory, and then,
4065 $ tar --list --file=collection.tar
4070 $ tar --delete --file=collection.tar blues
4071 $ tar --list --file=collection.tar
4076 The `--delete' option has been reported to work properly when `tar'
4077 acts as a filter from `stdin' to `stdout'.
4080 File: tar.info, Node: compare, Prev: delete, Up: Advanced tar
4082 4.2.6 Comparing Archive Members with the File System
4083 ----------------------------------------------------
4085 The `--compare' (`-d'), or `--diff' operation compares specified
4086 archive members against files with the same names, and then reports
4087 differences in file size, mode, owner, modification date and contents.
4088 You should _only_ specify archive member names, not file names. If you
4089 do not name any members, then `tar' will compare the entire archive.
4090 If a file is represented in the archive but does not exist in the file
4091 system, `tar' reports a difference.
4093 You have to specify the record size of the archive when modifying an
4094 archive with a non-default record size.
4096 `tar' ignores files in the file system that do not have
4097 corresponding members in the archive.
4099 The following example compares the archive members `rock', `blues'
4100 and `funk' in the archive `bluesrock.tar' with files of the same name
4101 in the file system. (Note that there is no file, `funk'; `tar' will
4102 report an error message.)
4104 $ tar --compare --file=bluesrock.tar rock blues funk
4107 tar: funk not found in archive
4109 The spirit behind the `--compare' (`--diff', `-d') option is to
4110 check whether the archive represents the current state of files on
4111 disk, more than validating the integrity of the archive media. For
4112 this latter goal, *Note verify::.
4115 File: tar.info, Node: create options, Next: extract options, Prev: Advanced tar, Up: operations
4117 4.3 Options Used by `--create'
4118 ==============================
4120 The previous chapter described the basics of how to use `--create'
4121 (`-c') to create an archive from a set of files. *Note create::. This
4122 section described advanced options to be used with `--create'.
4126 * override:: Overriding File Metadata.
4127 * Ignore Failed Read::
4130 File: tar.info, Node: override, Next: Ignore Failed Read, Up: create options
4132 4.3.1 Overriding File Metadata
4133 ------------------------------
4135 As described above, a `tar' archive keeps, for each member it contains,
4136 its "metadata", such as modification time, mode and ownership of the
4137 file. GNU `tar' allows to replace these data with other values when
4138 adding files to the archive. The options described in this section
4139 affect creation of archives of any type. For POSIX archives, see also
4140 *note PAX keywords::, for additional ways of controlling metadata,
4141 stored in the archive.
4143 `--mode=PERMISSIONS'
4144 When adding files to an archive, `tar' will use PERMISSIONS for
4145 the archive members, rather than the permissions from the files.
4146 PERMISSIONS can be specified either as an octal number or as
4147 symbolic permissions, like with `chmod' (*Note Permissions:
4148 (fileutils)File permissions. This reference also has useful
4149 information for those not being overly familiar with the UNIX
4150 permission system). Using latter syntax allows for more
4151 flexibility. For example, the value `a+rw' adds read and write
4152 permissions for everybody, while retaining executable bits on
4153 directories or on any other file already marked as executable:
4155 $ tar -c -f archive.tar --mode='a+rw' .
4158 When adding files to an archive, `tar' will use DATE as the
4159 modification time of members when creating archives, instead of
4160 their actual modification times. The argument DATE can be either
4161 a textual date representation in almost arbitrary format (*note
4162 Date input formats::) or a name of an existing file, starting with
4163 `/' or `.'. In the latter case, the modification time of that
4166 The following example will set the modification date to 00:00:00
4167 UTC, January 1, 1970:
4169 $ tar -c -f archive.tar --mtime='1970-01-01' .
4171 When used with `--verbose' (*note verbose tutorial::) GNU `tar'
4172 will try to convert the specified date back to its textual
4173 representation and compare it with the one given with `--mtime'
4174 options. If the two dates differ, `tar' will print a warning
4175 saying what date it will use. This is to help user ensure he is
4176 using the right date.
4180 $ tar -c -f archive.tar -v --mtime=yesterday .
4181 tar: Option --mtime: Treating date `yesterday' as 2006-06-20
4186 Specifies that `tar' should use USER as the owner of members when
4187 creating archives, instead of the user associated with the source
4188 file. The argument USER can be either an existing user symbolic
4189 name, or a decimal numeric user ID.
4191 There is no value indicating a missing number, and `0' usually
4192 means `root'. Some people like to force `0' as the value to offer
4193 in their distributions for the owner of files, because the `root'
4194 user is anonymous anyway, so that might as well be the owner of
4195 anonymous archives. For example:
4197 $ tar -c -f archive.tar --owner=0 .
4201 $ tar -c -f archive.tar --owner=root .
4204 Files added to the `tar' archive will have a group ID of GROUP,
4205 rather than the group from the source file. The argument GROUP
4206 can be either an existing group symbolic name, or a decimal
4210 File: tar.info, Node: Ignore Failed Read, Prev: override, Up: create options
4212 4.3.2 Ignore Fail Read
4213 ----------------------
4215 `--ignore-failed-read'
4216 Do not exit with nonzero on unreadable files or directories.
4219 File: tar.info, Node: extract options, Next: backup, Prev: create options, Up: operations
4221 4.4 Options Used by `--extract'
4222 ===============================
4224 The previous chapter showed how to use `--extract' to extract an
4225 archive into the file system. Various options cause `tar' to extract
4226 more information than just file contents, such as the owner, the
4227 permissions, the modification date, and so forth. This section
4228 presents options to be used with `--extract' when certain special
4229 considerations arise. You may review the information presented in
4230 *note extract:: for more basic information about the `--extract'
4235 * Reading:: Options to Help Read Archives
4236 * Writing:: Changing How `tar' Writes Files
4237 * Scarce:: Coping with Scarce Resources
4240 File: tar.info, Node: Reading, Next: Writing, Up: extract options
4242 4.4.1 Options to Help Read Archives
4243 -----------------------------------
4245 Normally, `tar' will request data in full record increments from an
4246 archive storage device. If the device cannot return a full record,
4247 `tar' will report an error. However, some devices do not always return
4248 full records, or do not require the last record of an archive to be
4249 padded out to the next record boundary. To keep reading until you
4250 obtain a full record, or to accept an incomplete record if it contains
4251 an end-of-archive marker, specify the `--read-full-records' (`-B')
4252 option in conjunction with the `--extract' or `--list' operations.
4255 The `--read-full-records' (`-B') option is turned on by default when
4256 `tar' reads an archive from standard input, or from a remote machine.
4257 This is because on BSD Unix systems, attempting to read a pipe returns
4258 however much happens to be in the pipe, even if it is less than was
4259 requested. If this option were not enabled, `tar' would fail as soon
4260 as it read an incomplete record from the pipe.
4262 If you're not sure of the blocking factor of an archive, you can
4263 read the archive by specifying `--read-full-records' (`-B') and
4264 `--blocking-factor=512-SIZE' (`-b 512-SIZE'), using a blocking factor
4265 larger than what the archive uses. This lets you avoid having to
4266 determine the blocking factor of an archive. *Note Blocking Factor::.
4270 * read full records::
4274 File: tar.info, Node: read full records, Next: Ignore Zeros, Up: Reading
4276 Reading Full Records
4277 ....................
4279 `--read-full-records'
4282 Use in conjunction with `--extract' (`--get', `-x') to read an
4283 archive which contains incomplete records, or one which has a
4284 blocking factor less than the one specified.
4287 File: tar.info, Node: Ignore Zeros, Prev: read full records, Up: Reading
4289 Ignoring Blocks of Zeros
4290 ........................
4292 Normally, `tar' stops reading when it encounters a block of zeros
4293 between file entries (which usually indicates the end of the archive).
4294 `--ignore-zeros' (`-i') allows `tar' to completely read an archive
4295 which contains a block of zeros before the end (i.e., a damaged
4296 archive, or one that was created by concatenating several archives
4299 The `--ignore-zeros' (`-i') option is turned off by default because
4300 many versions of `tar' write garbage after the end-of-archive entry,
4301 since that part of the media is never supposed to be read. GNU `tar'
4302 does not write after the end of an archive, but seeks to maintain
4303 compatibility among archiving utilities.
4307 To ignore blocks of zeros (i.e., end-of-archive entries) which may
4308 be encountered while reading an archive. Use in conjunction with
4309 `--extract' or `--list'.
4312 File: tar.info, Node: Writing, Next: Scarce, Prev: Reading, Up: extract options
4314 4.4.2 Changing How `tar' Writes Files
4315 -------------------------------------
4317 _(This message will disappear, once this node revised.)_
4321 * Dealing with Old Files::
4322 * Overwrite Old Files::
4324 * Keep Newer Files::
4326 * Recursive Unlink::
4327 * Data Modification Times::
4328 * Setting Access Permissions::
4329 * Directory Modification Times and Permissions::
4330 * Writing to Standard Output::
4331 * Writing to an External Program::
4335 File: tar.info, Node: Dealing with Old Files, Next: Overwrite Old Files, Up: Writing
4337 Options Controlling the Overwriting of Existing Files
4338 .....................................................
4340 When extracting files, if `tar' discovers that the extracted file
4341 already exists, it normally replaces the file by removing it before
4342 extracting it, to prevent confusion in the presence of hard or symbolic
4343 links. (If the existing file is a symbolic link, it is removed, not
4344 followed.) However, if a directory cannot be removed because it is
4345 nonempty, `tar' normally overwrites its metadata (ownership,
4346 permission, etc.). The `--overwrite-dir' option enables this default
4347 behavior. To be more cautious and preserve the metadata of such a
4348 directory, use the `--no-overwrite-dir' option.
4350 To be even more cautious and prevent existing files from being
4351 replaced, use the `--keep-old-files' (`-k') option. It causes `tar' to
4352 refuse to replace or update a file that already exists, i.e., a file
4353 with the same name as an archive member prevents extraction of that
4354 archive member. Instead, it reports an error.
4356 To be more aggressive about altering existing files, use the
4357 `--overwrite' option. It causes `tar' to overwrite existing files and
4358 to follow existing symbolic links when extracting.
4360 Some people argue that GNU `tar' should not hesitate to overwrite
4361 files with other files when extracting. When extracting a `tar'
4362 archive, they expect to see a faithful copy of the state of the file
4363 system when the archive was created. It is debatable that this would
4364 always be a proper behavior. For example, suppose one has an archive
4365 in which `usr/local' is a link to `usr/local2'. Since then, maybe the
4366 site removed the link and renamed the whole hierarchy from
4367 `/usr/local2' to `/usr/local'. Such things happen all the time. I
4368 guess it would not be welcome at all that GNU `tar' removes the whole
4369 hierarchy just to make room for the link to be reinstated (unless it
4370 _also_ simultaneously restores the full `/usr/local2', of course!) GNU
4371 `tar' is indeed able to remove a whole hierarchy to reestablish a
4372 symbolic link, for example, but _only if_ `--recursive-unlink' is
4373 specified to allow this behavior. In any case, single files are
4376 Finally, the `--unlink-first' (`-U') option can improve performance
4377 in some cases by causing `tar' to remove files unconditionally before
4381 File: tar.info, Node: Overwrite Old Files, Next: Keep Old Files, Prev: Dealing with Old Files, Up: Writing
4387 Overwrite existing files and directory metadata when extracting
4388 files from an archive.
4390 This causes `tar' to write extracted files into the file system
4391 without regard to the files already on the system; i.e., files
4392 with the same names as archive members are overwritten when the
4393 archive is extracted. It also causes `tar' to extract the
4394 ownership, permissions, and time stamps onto any preexisting files
4395 or directories. If the name of a corresponding file name is a
4396 symbolic link, the file pointed to by the symbolic link will be
4397 overwritten instead of the symbolic link itself (if this is
4398 possible). Moreover, special devices, empty directories and even
4399 symbolic links are automatically removed if they are in the way of
4402 Be careful when using the `--overwrite' option, particularly when
4403 combined with the `--absolute-names' (`-P') option, as this
4404 combination can change the contents, ownership or permissions of
4405 any file on your system. Also, many systems do not take kindly to
4406 overwriting files that are currently being executed.
4409 Overwrite the metadata of directories when extracting files from an
4410 archive, but remove other files before extracting.
4413 File: tar.info, Node: Keep Old Files, Next: Keep Newer Files, Prev: Overwrite Old Files, Up: Writing
4420 Do not replace existing files from archive. The
4421 `--keep-old-files' (`-k') option prevents `tar' from replacing
4422 existing files with files with the same name from the archive. The
4423 `--keep-old-files' option is meaningless with `--list' (`-t').
4424 Prevents `tar' from replacing files in the file system during
4428 File: tar.info, Node: Keep Newer Files, Next: Unlink First, Prev: Keep Old Files, Up: Writing
4433 `--keep-newer-files'
4434 Do not replace existing files that are newer than their archive
4435 copies. This option is meaningless with `--list' (`-t').
4438 File: tar.info, Node: Unlink First, Next: Recursive Unlink, Prev: Keep Newer Files, Up: Writing
4445 Remove files before extracting over them. This can make `tar' run
4446 a bit faster if you know in advance that the extracted files all
4447 need to be removed. Normally this option slows `tar' down
4448 slightly, so it is disabled by default.
4451 File: tar.info, Node: Recursive Unlink, Next: Data Modification Times, Prev: Unlink First, Up: Writing
4456 `--recursive-unlink'
4457 When this option is specified, try removing files and directory
4458 hierarchies before extracting over them. _This is a dangerous
4461 If you specify the `--recursive-unlink' option, `tar' removes
4462 _anything_ that keeps you from extracting a file as far as current
4463 permissions will allow it. This could include removal of the contents
4464 of a full directory hierarchy.
4467 File: tar.info, Node: Data Modification Times, Next: Setting Access Permissions, Prev: Recursive Unlink, Up: Writing
4469 Setting Data Modification Times
4470 ...............................
4472 Normally, `tar' sets the data modification times of extracted files to
4473 the corresponding times recorded for the files in the archive, but
4474 limits the permissions of extracted files by the current `umask'
4477 To set the data modification times of extracted files to the time
4478 when the files were extracted, use the `--touch' (`-m') option in
4479 conjunction with `--extract' (`--get', `-x').
4483 Sets the data modification time of extracted archive members to
4484 the time they were extracted, not the time recorded for them in
4485 the archive. Use in conjunction with `--extract' (`--get', `-x').
4488 File: tar.info, Node: Setting Access Permissions, Next: Directory Modification Times and Permissions, Prev: Data Modification Times, Up: Writing
4490 Setting Access Permissions
4491 ..........................
4493 To set the modes (access permissions) of extracted files to those
4494 recorded for those files in the archive, use `--same-permissions' in
4495 conjunction with the `--extract' (`--get', `-x') operation.
4497 `--preserve-permissions'
4498 `--same-permissions'
4500 Set modes of extracted archive members to those recorded in the
4501 archive, instead of current umask settings. Use in conjunction
4502 with `--extract' (`--get', `-x').
4505 File: tar.info, Node: Directory Modification Times and Permissions, Next: Writing to Standard Output, Prev: Setting Access Permissions, Up: Writing
4507 Directory Modification Times and Permissions
4508 ............................................
4510 After successfully extracting a file member, GNU `tar' normally
4511 restores its permissions and modification times, as described in the
4512 previous sections. This cannot be done for directories, because after
4513 extracting a directory `tar' will almost certainly extract files into
4514 that directory and this will cause the directory modification time to
4515 be updated. Moreover, restoring that directory permissions may not
4516 permit file creation within it. Thus, restoring directory permissions
4517 and modification times must be delayed at least until all files have
4518 been extracted into that directory. GNU `tar' restores directories
4519 using the following approach.
4521 The extracted directories are created with the mode specified in the
4522 archive, as modified by the umask of the user, which gives sufficient
4523 permissions to allow file creation. The meta-information about the
4524 directory is recorded in the temporary list of directories. When
4525 preparing to extract next archive member, GNU `tar' checks if the
4526 directory prefix of this file contains the remembered directory. If it
4527 does not, the program assumes that all files have been extracted into
4528 that directory, restores its modification time and permissions and
4529 removes its entry from the internal list. This approach allows to
4530 correctly restore directory meta-information in the majority of cases,
4531 while keeping memory requirements sufficiently small. It is based on
4532 the fact, that most `tar' archives use the predefined order of members:
4533 first the directory, then all the files and subdirectories in that
4536 However, this is not always true. The most important exception are
4537 incremental archives (*note Incremental Dumps::). The member order in
4538 an incremental archive is reversed: first all directory members are
4539 stored, followed by other (non-directory) members. So, when extracting
4540 from incremental archives, GNU `tar' alters the above procedure. It
4541 remembers all restored directories, and restores their meta-data only
4542 after the entire archive has been processed. Notice, that you do not
4543 need to specify any special options for that, as GNU `tar'
4544 automatically detects archives in incremental format.
4546 There may be cases, when such processing is required for normal
4547 archives too. Consider the following example:
4549 $ tar --no-recursion -cvf archive \
4550 foo foo/file1 bar bar/file foo/file2
4557 During the normal operation, after encountering `bar' GNU `tar' will
4558 assume that all files from the directory `foo' were already extracted
4559 and will therefore restore its timestamp and permission bits. However,
4560 after extracting `foo/file2' the directory timestamp will be offset
4563 To correctly restore directory meta-information in such cases, use
4564 the `--delay-directory-restore' command line option:
4566 `--delay-directory-restore'
4567 Delays restoring of the modification times and permissions of
4568 extracted directories until the end of extraction. This way,
4569 correct meta-information is restored even if the archive has
4570 unusual member ordering.
4572 `--no-delay-directory-restore'
4573 Cancel the effect of the previous `--delay-directory-restore'.
4574 Use this option if you have used `--delay-directory-restore' in
4575 `TAR_OPTIONS' variable (*note TAR_OPTIONS::) and wish to
4576 temporarily disable it.
4579 File: tar.info, Node: Writing to Standard Output, Next: Writing to an External Program, Prev: Directory Modification Times and Permissions, Up: Writing
4581 Writing to Standard Output
4582 ..........................
4584 To write the extracted files to the standard output, instead of
4585 creating the files on the file system, use `--to-stdout' (`-O') in
4586 conjunction with `--extract' (`--get', `-x'). This option is useful if
4587 you are extracting files to send them through a pipe, and do not need to
4588 preserve them in the file system. If you extract multiple members,
4589 they appear on standard output concatenated, in the order they are
4590 found in the archive.
4594 Writes files to the standard output. Use only in conjunction with
4595 `--extract' (`--get', `-x'). When this option is used, instead of
4596 creating the files specified, `tar' writes the contents of the
4597 files extracted to its standard output. This may be useful if you
4598 are only extracting the files in order to send them through a
4599 pipe. This option is meaningless with `--list' (`-t').
4601 This can be useful, for example, if you have a tar archive containing
4602 a big file and don't want to store the file on disk before processing
4603 it. You can use a command like this:
4605 tar -xOzf foo.tgz bigfile | process
4607 or even like this if you want to process the concatenation of the
4610 tar -xOzf foo.tgz bigfile1 bigfile2 | process
4612 However, `--to-command' may be more convenient for use with multiple
4613 files. See the next section.
4616 File: tar.info, Node: Writing to an External Program, Next: remove files, Prev: Writing to Standard Output, Up: Writing
4618 Writing to an External Program
4619 ..............................
4621 You can instruct `tar' to send the contents of each extracted file to
4622 the standard input of an external program:
4624 `--to-command=COMMAND'
4625 Extract files and pipe their contents to the standard input of
4626 COMMAND. When this option is used, instead of creating the files
4627 specified, `tar' invokes COMMAND and pipes the contents of the
4628 files to its standard output. The COMMAND may contain command line
4629 arguments. The program is executed via `sh -c'. Notice, that
4630 COMMAND is executed once for each regular file extracted.
4631 Non-regular files (directories, etc.) are ignored when this option
4634 The command can obtain the information about the file it processes
4635 from the following environment variables:
4638 Type of the file. It is a single letter with the following meaning:
4647 Currently only regular files are supported.
4650 File mode, an octal number.
4653 The name of the file.
4656 Name of the file as stored in the archive.
4659 Name of the file owner.
4662 Name of the file owner group.
4665 Time of last access. It is a decimal number, representing seconds
4666 since the Epoch. If the archive provides times with nanosecond
4667 precision, the nanoseconds are appended to the timestamp after a
4671 Time of last modification.
4674 Time of last status change.
4680 UID of the file owner.
4683 GID of the file owner.
4685 Additionally, the following variables contain information about tar
4686 mode and the archive being processed:
4689 GNU `tar' version number.
4692 The name of the archive `tar' is processing.
4694 `TAR_BLOCKING_FACTOR'
4695 Current blocking factor (*note Blocking::).
4698 Ordinal number of the volume `tar' is processing.
4701 Format of the archive being processed. *Note Formats::, for a
4702 complete list of archive format names.
4704 If COMMAND exits with a non-0 status, `tar' will print an error
4705 message similar to the following:
4707 tar: 2345: Child returned status 1
4709 Here, `2345' is the PID of the finished process.
4711 If this behavior is not wanted, use `--ignore-command-error':
4713 `--ignore-command-error'
4714 Ignore exit codes of subprocesses. Notice that if the program
4715 exits on signal or otherwise terminates abnormally, the error
4716 message will be printed even if this option is used.
4718 `--no-ignore-command-error'
4719 Cancel the effect of any previous `--ignore-command-error' option.
4720 This option is useful if you have set `--ignore-command-error' in
4721 `TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to temporarily cancel
4725 File: tar.info, Node: remove files, Prev: Writing to an External Program, Up: Writing
4731 Remove files after adding them to the archive.
4734 File: tar.info, Node: Scarce, Prev: Writing, Up: extract options
4736 4.4.3 Coping with Scarce Resources
4737 ----------------------------------
4739 _(This message will disappear, once this node revised.)_
4747 File: tar.info, Node: Starting File, Next: Same Order, Up: Scarce
4752 `--starting-file=NAME'
4754 Starts an operation in the middle of an archive. Use in
4755 conjunction with `--extract' (`--get', `-x') or `--list' (`-t').
4757 If a previous attempt to extract files failed due to lack of disk
4758 space, you can use `--starting-file=NAME' (`-K NAME') to start
4759 extracting only after member NAME of the archive. This assumes, of
4760 course, that there is now free space, or that you are now extracting
4761 into a different file system. (You could also choose to suspend `tar',
4762 remove unnecessary files from the file system, and then restart the
4763 same `tar' operation. In this case, `--starting-file' is not necessary.
4764 *Note Incremental Dumps::, *Note interactive::, and *note exclude::.)
4767 File: tar.info, Node: Same Order, Prev: Starting File, Up: Scarce
4775 To process large lists of file names on machines with small
4776 amounts of memory. Use in conjunction with `--compare' (`--diff',
4777 `-d'), `--list' (`-t') or `--extract' (`--get', `-x').
4779 The `--same-order' (`--preserve-order', `-s') option tells `tar'
4780 that the list of file names to be listed or extracted is sorted in the
4781 same order as the files in the archive. This allows a large list of
4782 names to be used, even on a small machine that would not otherwise be
4783 able to hold all the names in memory at the same time. Such a sorted
4784 list can easily be created by running `tar -t' on the archive and
4787 This option is probably never needed on modern computer systems.
4790 File: tar.info, Node: backup, Next: Applications, Prev: extract options, Up: operations
4795 GNU `tar' offers options for making backups of files before writing new
4796 versions. These options control the details of these backups. They
4797 may apply to the archive itself before it is created or rewritten, as
4798 well as individual extracted members. Other GNU programs (`cp',
4799 `install', `ln', and `mv', for example) offer similar options.
4801 Backup options may prove unexpectedly useful when extracting archives
4802 containing many members having identical name, or when extracting
4803 archives on systems having file name limitations, making different
4804 members appear as having similar names through the side-effect of name
4807 When any existing file is backed up before being overwritten by
4808 extraction, then clashing files are automatically be renamed to be
4809 unique, and the true name is kept for only the last file of a series of
4810 clashing files. By using verbose mode, users may track exactly what
4813 At the detail level, some decisions are still experimental, and may
4814 change in the future, we are waiting comments from our users. So,
4815 please do not learn to depend blindly on the details of the backup
4816 features. For example, currently, directories themselves are never
4817 renamed through using these options, so, extracting a file over a
4818 directory still has good chances to fail. Also, backup options apply
4819 to created archives, not only to extracted members. For created
4820 archives, backups will not be attempted when the archive is a block or
4821 character device, or when it refers to a remote file.
4823 For the sake of simplicity and efficiency, backups are made by
4824 renaming old files prior to creation or extraction, and not by copying.
4825 The original name is restored if the file creation fails. If a failure
4826 occurs after a partial extraction of a file, both the backup and the
4827 partially extracted file are kept.
4830 Back up files that are about to be overwritten or removed.
4831 Without this option, the original versions are destroyed.
4833 Use METHOD to determine the type of backups made. If METHOD is
4834 not specified, use the value of the `VERSION_CONTROL' environment
4835 variable. And if `VERSION_CONTROL' is not set, use the `existing'
4838 This option corresponds to the Emacs variable `version-control';
4839 the same values for METHOD are accepted as in Emacs. This option
4840 also allows more descriptive names. The valid METHODs are:
4844 Always make numbered backups.
4848 Make numbered backups of files that already have them, simple
4849 backups of the others.
4853 Always make simple backups.
4857 Append SUFFIX to each backup file made with `--backup'. If this
4858 option is not specified, the value of the `SIMPLE_BACKUP_SUFFIX'
4859 environment variable is used. And if `SIMPLE_BACKUP_SUFFIX' is not
4860 set, the default is `~', just as in Emacs.
4864 File: tar.info, Node: Applications, Next: looking ahead, Prev: backup, Up: operations
4866 4.6 Notable `tar' Usages
4867 ========================
4869 _(This message will disappear, once this node revised.)_
4871 You can easily use archive files to transport a group of files from one
4872 system to another: put all relevant files into an archive on one
4873 computer system, transfer the archive to another system, and extract
4874 the contents there. The basic transfer medium might be magnetic tape,
4875 Internet FTP, or even electronic mail (though you must encode the
4876 archive with `uuencode' in order to transport it properly by mail).
4877 Both machines do not have to use the same operating system, as long as
4878 they both support the `tar' program.
4880 For example, here is how you might copy a directory's contents from
4881 one disk to another, while preserving the dates, modes, owners and
4882 link-structure of all the files therein. In this case, the transfer
4885 $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)
4887 You can avoid subshells by using `-C' option:
4889 $ tar -C sourcedir -cf - . | tar -C targetdir -xf -
4891 The command also works using long option forms:
4893 $ (cd sourcedir; tar --create --file=- . ) \
4894 | (cd targetdir; tar --extract --file=-)
4898 $ tar --directory sourcedir --create --file=- . ) \
4899 | tar --directory targetdir --extract --file=-
4901 This is one of the easiest methods to transfer a `tar' archive.
4904 File: tar.info, Node: looking ahead, Prev: Applications, Up: operations
4906 4.7 Looking Ahead: The Rest of this Manual
4907 ==========================================
4909 You have now seen how to use all eight of the operations available to
4910 `tar', and a number of the possible options. The next chapter explains
4911 how to choose and change file and archive names, how to use files to
4912 store names of other files which you can then call as arguments to
4913 `tar' (this can help you save time if you expect to archive the same
4914 list of files a number of times), and so forth.
4916 If there are too many files to conveniently list on the command line,
4917 you can list the names in a file, and `tar' will read that file. *Note
4920 There are various ways of causing `tar' to skip over some files, and
4921 not archive them. *Note Choosing::.
4924 File: tar.info, Node: Backups, Next: Choosing, Prev: operations, Up: Top
4926 5 Performing Backups and Restoring Files
4927 ****************************************
4929 GNU `tar' is distributed along with the scripts for performing backups
4930 and restores. Even if there is a good chance those scripts may be
4931 satisfying to you, they are not the only scripts or methods available
4932 for doing backups and restore. You may well create your own, or use
4933 more sophisticated packages dedicated to that purpose.
4935 Some users are enthusiastic about `Amanda' (The Advanced Maryland
4936 Automatic Network Disk Archiver), a backup system developed by James da
4937 Silva `jds@cs.umd.edu' and available on many Unix systems. This is
4938 free software, and it is available from `http://www.amanda.org'.
4940 This chapter documents both the provided shell scripts and `tar'
4941 options which are more specific to usage as a backup tool.
4943 To "back up" a file system means to create archives that contain all
4944 the files in that file system. Those archives can then be used to
4945 restore any or all of those files (for instance if a disk crashes or a
4946 file is accidentally deleted). File system "backups" are also called
4951 * Full Dumps:: Using `tar' to Perform Full Dumps
4952 * Incremental Dumps:: Using `tar' to Perform Incremental Dumps
4953 * Backup Levels:: Levels of Backups
4954 * Backup Parameters:: Setting Parameters for Backups and Restoration
4955 * Scripted Backups:: Using the Backup Scripts
4956 * Scripted Restoration:: Using the Restore Script
4959 File: tar.info, Node: Full Dumps, Next: Incremental Dumps, Up: Backups
4961 5.1 Using `tar' to Perform Full Dumps
4962 =====================================
4964 _(This message will disappear, once this node revised.)_
4966 Full dumps should only be made when no other people or programs are
4967 modifying files in the file system. If files are modified while `tar'
4968 is making the backup, they may not be stored properly in the archive,
4969 in which case you won't be able to restore them if you have to. (Files
4970 not being modified are written with no trouble, and do not corrupt the
4973 You will want to use the `--label=ARCHIVE-LABEL' (`-V
4974 ARCHIVE-LABEL') option to give the archive a volume label, so you can
4975 tell what this archive is even if the label falls off the tape, or
4978 Unless the file system you are dumping is guaranteed to fit on one
4979 volume, you will need to use the `--multi-volume' (`-M') option. Make
4980 sure you have enough tapes on hand to complete the backup.
4982 If you want to dump each file system separately you will need to use
4983 the `--one-file-system' option to prevent `tar' from crossing file
4984 system boundaries when storing (sub)directories.
4986 The `--incremental' (`-G') (*note Incremental Dumps::) option is not
4987 needed, since this is a complete copy of everything in the file system,
4988 and a full restore from this backup would only be done onto a completely
4991 Unless you are in a hurry, and trust the `tar' program (and your
4992 tapes), it is a good idea to use the `--verify' (`-W') option, to make
4993 sure your files really made it onto the dump properly. This will also
4994 detect cases where the file was modified while (or just after) it was
4995 being archived. Not all media (notably cartridge tapes) are capable of
4996 being verified, unfortunately.
4999 File: tar.info, Node: Incremental Dumps, Next: Backup Levels, Prev: Full Dumps, Up: Backups
5001 5.2 Using `tar' to Perform Incremental Dumps
5002 ============================================
5004 "Incremental backup" is a special form of GNU `tar' archive that stores
5005 additional metadata so that exact state of the file system can be
5006 restored when extracting the archive.
5008 GNU `tar' currently offers two options for handling incremental
5009 backups: `--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') and
5010 `--incremental' (`-G').
5012 The option `--listed-incremental' instructs tar to operate on an
5013 incremental archive with additional metadata stored in a standalone
5014 file, called a "snapshot file". The purpose of this file is to help
5015 determine which files have been changed, added or deleted since the
5016 last backup, so that the next incremental backup will contain only
5017 modified files. The name of the snapshot file is given as an argument
5020 `--listed-incremental=FILE'
5022 Handle incremental backups with snapshot data in FILE.
5024 To create an incremental backup, you would use
5025 `--listed-incremental' together with `--create' (*note create::). For
5029 --file=archive.1.tar \
5030 --listed-incremental=/var/log/usr.snar \
5033 This will create in `archive.1.tar' an incremental backup of the
5034 `/usr' file system, storing additional metadata in the file
5035 `/var/log/usr.snar'. If this file does not exist, it will be created.
5036 The created archive will then be a "level 0 backup"; please see the
5037 next section for more on backup levels.
5039 Otherwise, if the file `/var/log/usr.snar' exists, it determines
5040 which files are modified. In this case only these files will be stored
5041 in the archive. Suppose, for example, that after running the above
5042 command, you delete file `/usr/doc/old' and create directory
5043 `/usr/local/db' with the following contents:
5049 Some time later you create another incremental backup. You will
5053 --file=archive.2.tar \
5054 --listed-incremental=/var/log/usr.snar \
5056 tar: usr/local/db: Directory is new
5061 The created archive `archive.2.tar' will contain only these three
5062 members. This archive is called a "level 1 backup". Notice that
5063 `/var/log/usr.snar' will be updated with the new data, so if you plan
5064 to create more `level 1' backups, it is necessary to create a working
5065 copy of the snapshot file before running `tar'. The above example will
5066 then be modified as follows:
5068 $ cp /var/log/usr.snar /var/log/usr.snar-1
5070 --file=archive.2.tar \
5071 --listed-incremental=/var/log/usr.snar-1 \
5074 You can force `level 0' backups either by removing the snapshot file
5075 before running `tar', or by supplying the `--level=0' option, e.g.:
5078 --file=archive.2.tar \
5079 --listed-incremental=/var/log/usr.snar-0 \
5083 Incremental dumps depend crucially on time stamps, so the results are
5084 unreliable if you modify a file's time stamps during dumping (e.g.,
5085 with the `--atime-preserve=replace' option), or if you set the clock
5088 Metadata stored in snapshot files include device numbers, which,
5089 obviously are supposed to be non-volatile values. However, it turns
5090 out that NFS devices have undependable values when an automounter gets
5091 in the picture. This can lead to a great deal of spurious redumping in
5092 incremental dumps, so it is somewhat useless to compare two NFS devices
5093 numbers over time. The solution implemented currently is to consider
5094 all NFS devices as being equal when it comes to comparing directories;
5095 this is fairly gross, but there does not seem to be a better way to go.
5097 Apart from using NFS, there are a number of cases where relying on
5098 device numbers can cause spurious redumping of unmodified files. For
5099 example, this occurs when archiving LVM snapshot volumes. To avoid
5100 this, use `--no-check-device' option:
5103 Do not rely on device numbers when preparing a list of changed
5104 files for an incremental dump.
5107 Use device numbers when preparing a list of changed files for an
5108 incremental dump. This is the default behavior. The purpose of
5109 this option is to undo the effect of the `--no-check-device' if it
5110 was given in `TAR_OPTIONS' environment variable (*note
5113 There is also another way to cope with changing device numbers. It
5114 is described in detail in *note Fixing Snapshot Files::.
5116 Note that incremental archives use `tar' extensions and may not be
5117 readable by non-GNU versions of the `tar' program.
5119 To extract from the incremental dumps, use `--listed-incremental'
5120 together with `--extract' option (*note extracting files::). In this
5121 case, `tar' does not need to access snapshot file, since all the data
5122 necessary for extraction are stored in the archive itself. So, when
5123 extracting, you can give whatever argument to `--listed-incremental',
5124 the usual practice is to use `--listed-incremental=/dev/null'.
5125 Alternatively, you can use `--incremental', which needs no arguments.
5126 In general, `--incremental' (`-G') can be used as a shortcut for
5127 `--listed-incremental' when listing or extracting incremental backups
5128 (for more information regarding this option, *note incremental-op::).
5130 When extracting from the incremental backup GNU `tar' attempts to
5131 restore the exact state the file system had when the archive was
5132 created. In particular, it will _delete_ those files in the file
5133 system that did not exist in their directories when the archive was
5134 created. If you have created several levels of incremental files, then
5135 in order to restore the exact contents the file system had when the
5136 last level was created, you will need to restore from all backups in
5137 turn. Continuing our example, to restore the state of `/usr' file
5138 system, one would do(1):
5141 --listed-incremental=/dev/null \
5142 --file archive.1.tar
5144 --listed-incremental=/dev/null \
5145 --file archive.2.tar
5147 To list the contents of an incremental archive, use `--list' (*note
5148 list::), as usual. To obtain more information about the archive, use
5149 `--listed-incremental' or `--incremental' combined with two `--verbose'
5151 `--verbose' options were selected to avoid breaking usual
5152 verbose listing output (`--list --verbose') when using in
5159 Versions of GNU `tar' up to 1.15.1 used to dump verbatim binary
5160 contents of the DUMPDIR header (with terminating nulls) when
5161 `--incremental' or `--listed-incremental' option was
5162 given, no matter what the verbosity level(2):
5164 tar --list --incremental --verbose --verbose archive.tar
5166 This command will print, for each directory in the archive, the list
5167 of files in that directory at the time the archive was created. This
5168 information is put out in a format which is both human-readable and
5169 unambiguous for a program: each file name is printed as
5173 where X is a letter describing the status of the file: `Y' if the file
5174 is present in the archive, `N' if the file is not included in the
5175 archive, or a `D' if the file is a directory (and is included in the
5176 archive). *Note Dumpdir::, for the detailed description of dumpdirs
5177 and status codes. Each such line is terminated by a newline character.
5178 The last line is followed by an additional newline to indicate the end
5181 The option `--incremental' (`-G') gives the same behavior as
5182 `--listed-incremental' when used with `--list' and `--extract' options.
5183 When used with `--create' option, it creates an incremental archive
5184 without creating snapshot file. Thus, it is impossible to create
5185 several levels of incremental backups with `--incremental' option.
5187 ---------- Footnotes ----------
5189 (1) Notice, that since both archives were created without `-P'
5190 option (*note absolute::), these commands should be run from the root
5193 (2) Two `--verbose' options were selected to avoid breaking usual
5194 verbose listing output (`--list --verbose') when using in scripts.
5196 Versions of GNU `tar' up to 1.15.1 used to dump verbatim binary
5197 contents of the DUMPDIR header (with terminating nulls) when
5198 `--incremental' or `--listed-incremental' option was given, no matter
5199 what the verbosity level. This behavior, and, especially, the binary
5200 output it produced were considered inconvenient and were changed in
5204 File: tar.info, Node: Backup Levels, Next: Backup Parameters, Prev: Incremental Dumps, Up: Backups
5206 5.3 Levels of Backups
5207 =====================
5209 An archive containing all the files in the file system is called a
5210 "full backup" or "full dump". You could insure your data by creating a
5211 full dump every day. This strategy, however, would waste a substantial
5212 amount of archive media and user time, as unchanged files are daily
5215 It is more efficient to do a full dump only occasionally. To back up
5216 files between full dumps, you can use "incremental dumps". A "level
5217 one" dump archives all the files that have changed since the last full
5220 A typical dump strategy would be to perform a full dump once a week,
5221 and a level one dump once a day. This means some versions of files
5222 will in fact be archived more than once, but this dump strategy makes
5223 it possible to restore a file system to within one day of accuracy by
5224 only extracting two archives--the last weekly (full) dump and the last
5225 daily (level one) dump. The only information lost would be in files
5226 changed or created since the last daily backup. (Doing dumps more than
5227 once a day is usually not worth the trouble.)
5229 GNU `tar' comes with scripts you can use to do full and level-one
5230 (actually, even level-two and so on) dumps. Using scripts (shell
5231 programs) to perform backups and restoration is a convenient and
5232 reliable alternative to typing out file name lists and `tar' commands
5235 Before you use these scripts, you need to edit the file
5236 `backup-specs', which specifies parameters used by the backup scripts
5237 and by the restore script. This file is usually located in
5238 `/etc/backup' directory. *Note Backup Parameters::, for its detailed
5239 description. Once the backup parameters are set, you can perform
5240 backups or restoration by running the appropriate script.
5242 The name of the backup script is `backup'. The name of the restore
5243 script is `restore'. The following sections describe their use in
5246 _Please Note:_ The backup and restoration scripts are designed to be
5247 used together. While it is possible to restore files by hand from an
5248 archive which was created using a backup script, and to create an
5249 archive by hand which could then be extracted using the restore script,
5250 it is easier to use the scripts. *Note Incremental Dumps::, before
5251 making such an attempt.
5254 File: tar.info, Node: Backup Parameters, Next: Scripted Backups, Prev: Backup Levels, Up: Backups
5256 5.4 Setting Parameters for Backups and Restoration
5257 ==================================================
5259 The file `backup-specs' specifies backup parameters for the backup and
5260 restoration scripts provided with `tar'. You must edit `backup-specs'
5261 to fit your system configuration and schedule before using these
5264 Syntactically, `backup-specs' is a shell script, containing mainly
5265 variable assignments. However, any valid shell construct is allowed in
5266 this file. Particularly, you may wish to define functions within that
5267 script (e.g., see `RESTORE_BEGIN' below). For more information about
5268 shell script syntax, please refer to the definition of the Shell
5270 (http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
5271 g_02). See also *note Bash Features: (bashref)Top.
5273 The shell variables controlling behavior of `backup' and `restore'
5274 are described in the following subsections.
5278 * General-Purpose Variables::
5279 * Magnetic Tape Control::
5281 * backup-specs example:: An Example Text of `Backup-specs'
5284 File: tar.info, Node: General-Purpose Variables, Next: Magnetic Tape Control, Up: Backup Parameters
5286 5.4.1 General-Purpose Variables
5287 -------------------------------
5289 -- Backup variable: ADMINISTRATOR
5290 The user name of the backup administrator. `Backup' scripts sends
5291 a backup report to this address.
5293 -- Backup variable: BACKUP_HOUR
5294 The hour at which the backups are done. This can be a number from
5295 0 to 23, or the time specification in form HOURS:MINUTES, or the
5298 This variable is used by `backup'. Its value may be overridden
5299 using `--time' option (*note Scripted Backups::).
5301 -- Backup variable: TAPE_FILE
5302 The device `tar' writes the archive to. If TAPE_FILE is a remote
5303 archive (*note remote-dev::), backup script will suppose that your
5304 `mt' is able to access remote devices. If RSH (*note RSH::) is
5305 set, `--rsh-command' option will be added to invocations of `mt'.
5307 -- Backup variable: BLOCKING
5308 The blocking factor `tar' will use when writing the dump archive.
5309 *Note Blocking Factor::.
5311 -- Backup variable: BACKUP_DIRS
5312 A list of file systems to be dumped (for `backup'), or restored
5313 (for `restore'). You can include any directory name in the list
5314 -- subdirectories on that file system will be included, regardless
5315 of how they may look to other networked machines. Subdirectories
5316 on other file systems will be ignored.
5318 The host name specifies which host to run `tar' on, and should
5319 normally be the host that actually contains the file system.
5320 However, the host machine must have GNU `tar' installed, and must
5321 be able to access the directory containing the backup scripts and
5322 their support files using the same file name that is used on the
5323 machine where the scripts are run (i.e., what `pwd' will print
5324 when in that directory on that machine). If the host that contains
5325 the file system does not have this capability, you can specify
5326 another host as long as it can access the file system through NFS.
5328 If the list of file systems is very long you may wish to put it in
5329 a separate file. This file is usually named `/etc/backup/dirs',
5330 but this name may be overridden in `backup-specs' using `DIRLIST'
5333 -- Backup variable: DIRLIST
5334 The name of the file that contains a list of file systems to backup
5335 or restore. By default it is `/etc/backup/dirs'.
5337 -- Backup variable: BACKUP_FILES
5338 A list of individual files to be dumped (for `backup'), or restored
5339 (for `restore'). These should be accessible from the machine on
5340 which the backup script is run.
5342 If the list of individual files is very long you may wish to store
5343 it in a separate file. This file is usually named
5344 `/etc/backup/files', but this name may be overridden in
5345 `backup-specs' using `FILELIST' variable.
5347 -- Backup variable: FILELIST
5348 The name of the file that contains a list of individual files to
5349 backup or restore. By default it is `/etc/backup/files'.
5351 -- Backup variable: MT
5352 Full file name of `mt' binary.
5354 -- Backup variable: RSH
5355 Full file name of `rsh' binary or its equivalent. You may wish to
5356 set it to `ssh', to improve security. In this case you will have
5357 to use public key authentication.
5359 -- Backup variable: RSH_COMMAND
5360 Full file name of `rsh' binary on remote machines. This will be
5361 passed via `--rsh-command' option to the remote invocation of GNU
5364 -- Backup variable: VOLNO_FILE
5365 Name of temporary file to hold volume numbers. This needs to be
5366 accessible by all the machines which have file systems to be
5369 -- Backup variable: XLIST
5370 Name of "exclude file list". An "exclude file list" is a file
5371 located on the remote machine and containing the list of files to
5372 be excluded from the backup. Exclude file lists are searched in
5373 /etc/tar-backup directory. A common use for exclude file lists is
5374 to exclude files containing security-sensitive information (e.g.,
5375 `/etc/shadow' from backups).
5377 This variable affects only `backup'.
5379 -- Backup variable: SLEEP_TIME
5380 Time to sleep between dumps of any two successive file systems
5382 This variable affects only `backup'.
5384 -- Backup variable: DUMP_REMIND_SCRIPT
5385 Script to be run when it's time to insert a new tape in for the
5386 next volume. Administrators may want to tailor this script for
5387 their site. If this variable isn't set, GNU `tar' will display
5388 its built-in prompt, and will expect confirmation from the
5389 console. For the description of the default prompt, see *note
5390 change volume prompt::.
5393 -- Backup variable: SLEEP_MESSAGE
5394 Message to display on the terminal while waiting for dump time.
5395 Usually this will just be some literal text.
5397 -- Backup variable: TAR
5398 Full file name of the GNU `tar' executable. If this is not set,
5399 backup scripts will search `tar' in the current shell path.
5402 File: tar.info, Node: Magnetic Tape Control, Next: User Hooks, Prev: General-Purpose Variables, Up: Backup Parameters
5404 5.4.2 Magnetic Tape Control
5405 ---------------------------
5407 Backup scripts access tape device using special "hook functions".
5408 These functions take a single argument -- the name of the tape device.
5409 Their names are kept in the following variables:
5411 -- Backup variable: MT_BEGIN
5412 The name of "begin" function. This function is called before
5413 accessing the drive. By default it retensions the tape:
5418 mt -f "$1" retension
5421 -- Backup variable: MT_REWIND
5422 The name of "rewind" function. The default definition is as
5432 -- Backup variable: MT_OFFLINE
5433 The name of the function switching the tape off line. By default
5434 it is defined as follows:
5436 MT_OFFLINE=mt_offline
5442 -- Backup variable: MT_STATUS
5443 The name of the function used to obtain the status of the archive
5444 device, including error count. Default definition:
5453 File: tar.info, Node: User Hooks, Next: backup-specs example, Prev: Magnetic Tape Control, Up: Backup Parameters
5458 "User hooks" are shell functions executed before and after each `tar'
5459 invocation. Thus, there are "backup hooks", which are executed before
5460 and after dumping each file system, and "restore hooks", executed
5461 before and after restoring a file system. Each user hook is a shell
5462 function taking four arguments:
5464 -- User Hook Function: hook LEVEL HOST FS FSNAME
5468 Current backup or restore level.
5471 Name or IP address of the host machine being dumped or
5475 Full file name of the file system being dumped or restored.
5478 File system name with directory separators replaced with
5479 colons. This is useful, e.g., for creating unique files.
5481 Following variables keep the names of user hook functions:
5483 -- Backup variable: DUMP_BEGIN
5484 Dump begin function. It is executed before dumping the file
5487 -- Backup variable: DUMP_END
5488 Executed after dumping the file system.
5490 -- Backup variable: RESTORE_BEGIN
5491 Executed before restoring the file system.
5493 -- Backup variable: RESTORE_END
5494 Executed after restoring the file system.
5497 File: tar.info, Node: backup-specs example, Prev: User Hooks, Up: Backup Parameters
5499 5.4.4 An Example Text of `Backup-specs'
5500 ---------------------------------------
5502 The following is an example of `backup-specs':
5504 # site-specific parameters for file system backup.
5506 ADMINISTRATOR=friedman
5508 TAPE_FILE=/dev/nrsmt0
5510 # Use `ssh' instead of the less secure `rsh'
5512 RSH_COMMAND=/usr/bin/ssh
5514 # Override MT_STATUS function:
5520 # Disable MT_OFFLINE function
5537 apple-gunkies:/com/mailer/gnu
5538 apple-gunkies:/com/archive/gnu"
5540 BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
5543 File: tar.info, Node: Scripted Backups, Next: Scripted Restoration, Prev: Backup Parameters, Up: Backups
5545 5.5 Using the Backup Scripts
5546 ============================
5548 The syntax for running a backup script is:
5550 backup --level=LEVEL --time=TIME
5552 The `--level' option requests the dump level. Thus, to produce a
5553 full dump, specify `--level=0' (this is the default, so `--level' may
5554 be omitted if its value is `0')(1).
5556 The `--time' option determines when should the backup be run. TIME
5557 may take three forms:
5560 The dump must be run at HH hours MM minutes.
5563 The dump must be run at HH hours.
5566 The dump must be run immediately.
5568 You should start a script with a tape or disk mounted. Once you
5569 start a script, it prompts you for new tapes or disks as it needs them.
5570 Media volumes don't have to correspond to archive files -- a
5571 multi-volume archive can be started in the middle of a tape that
5572 already contains the end of another multi-volume archive. The
5573 `restore' script prompts for media by its archive volume, so to avoid
5574 an error message you should keep track of which tape (or disk) contains
5575 which volume of the archive (*note Scripted Restoration::).
5577 The backup scripts write two files on the file system. The first is
5578 a record file in `/etc/tar-backup/', which is used by the scripts to
5579 store and retrieve information about which files were dumped. This
5580 file is not meant to be read by humans, and should not be deleted by
5581 them. *Note Snapshot Files::, for a more detailed explanation of this
5584 The second file is a log file containing the names of the file
5585 systems and files dumped, what time the backup was made, and any error
5586 messages that were generated, as well as how much space was left in the
5587 media volume after the last volume of the archive was written. You
5588 should check this log file after every backup. The file name is
5589 `log-MM-DD-YYYY-level-N', where MM-DD-YYYY represents current date, and
5590 N represents current dump level number.
5592 The script also prints the name of each system being dumped to the
5595 Following is the full list of options accepted by `backup' script:
5599 Do backup level LEVEL (default 0).
5603 Force backup even if today's log file already exists.
5607 Set verbosity level. The higher the level is, the more debugging
5608 information will be output during execution. Default LEVEL is
5609 100, which means the highest debugging level.
5613 Wait till TIME, then do backup.
5617 Display short help message and exit.
5621 Display information about the program's name, version, origin and
5622 legal status, all on standard output, and then exit successfully.
5624 ---------- Footnotes ----------
5626 (1) For backward compatibility, the `backup' will also try to deduce
5627 the requested dump level from the name of the script itself. If the
5628 name consists of a string `level-' followed by a single decimal digit,
5629 that digit is taken as the dump level number. Thus, you may create a
5630 link from `backup' to `level-1' and then run `level-1' whenever you
5631 need to create a level one dump.
5634 File: tar.info, Node: Scripted Restoration, Prev: Scripted Backups, Up: Backups
5636 5.6 Using the Restore Script
5637 ============================
5639 To restore files that were archived using a scripted backup, use the
5640 `restore' script. Its usage is quite straightforward. In the simplest
5641 form, invoke `restore --all', it will then restore all the file systems
5642 and files specified in `backup-specs' (*note BACKUP_DIRS:
5643 General-Purpose Variables.).
5645 You may select the file systems (and/or files) to restore by giving
5646 `restore' a list of "patterns" in its command line. For example,
5651 will restore all file systems on the machine `albert'. A more
5652 complicated example:
5654 restore 'albert:*' '*:/var'
5656 This command will restore all file systems on the machine `albert' as
5657 well as `/var' file system on all machines.
5659 By default `restore' will start restoring files from the lowest
5660 available dump level (usually zero) and will continue through all
5661 available dump levels. There may be situations where such a thorough
5662 restore is not necessary. For example, you may wish to restore only
5663 files from the recent level one backup. To do so, use `--level'
5664 option, as shown in the example below:
5668 The full list of options accepted by `restore' follows:
5672 Restore all file systems and files specified in `backup-specs'.
5676 Start restoring from the given backup level, instead of the
5681 Set verbosity level. The higher the level is, the more debugging
5682 information will be output during execution. Default LEVEL is
5683 100, which means the highest debugging level.
5687 Display short help message and exit.
5691 Display information about the program's name, version, origin and
5692 legal status, all on standard output, and then exit successfully.
5694 You should start the restore script with the media containing the
5695 first volume of the archive mounted. The script will prompt for other
5696 volumes as they are needed. If the archive is on tape, you don't need
5697 to rewind the tape to to its beginning--if the tape head is positioned
5698 past the beginning of the archive, the script will rewind the tape as
5699 needed. *Note Tape Positioning::, for a discussion of tape positioning.
5701 *Warning:* The script will delete files from the active file
5702 system if they were not in the file system when the archive was
5705 *Note Incremental Dumps::, for an explanation of how the script makes
5709 File: tar.info, Node: Choosing, Next: Date input formats, Prev: Backups, Up: Top
5711 6 Choosing Files and Names for `tar'
5712 ************************************
5714 Certain options to `tar' enable you to specify a name for your archive.
5715 Other options let you decide which files to include or exclude from the
5716 archive, based on when or whether files were modified, whether the file
5717 names do or don't match specified patterns, or whether files are in
5718 specified directories.
5720 This chapter discusses these options in detail.
5724 * file:: Choosing the Archive's Name
5725 * Selecting Archive Members::
5726 * files:: Reading Names from a File
5727 * exclude:: Excluding Some Files
5728 * wildcards:: Wildcards Patterns and Matching
5729 * quoting styles:: Ways of Quoting Special Characters in Names
5730 * transform:: Modifying File and Member Names
5731 * after:: Operating Only on New Files
5732 * recurse:: Descending into Directories
5733 * one:: Crossing File System Boundaries
5736 File: tar.info, Node: file, Next: Selecting Archive Members, Up: Choosing
5738 6.1 Choosing and Naming Archive Files
5739 =====================================
5741 By default, `tar' uses an archive file name that was compiled when it
5742 was built on the system; usually this name refers to some physical tape
5743 drive on the machine. However, the person who installed `tar' on the
5744 system may not have set the default to a meaningful value as far as
5745 most users are concerned. As a result, you will usually want to tell
5746 `tar' where to find (or create) the archive. The `--file=ARCHIVE-NAME'
5747 (`-f ARCHIVE-NAME') option allows you to either specify or name a file
5748 to use as the archive instead of the default archive file location.
5750 `--file=ARCHIVE-NAME'
5752 Name the archive to create or operate on. Use in conjunction with
5755 For example, in this `tar' command,
5757 $ tar -cvf collection.tar blues folk jazz
5759 `collection.tar' is the name of the archive. It must directly follow
5760 the `-f' option, since whatever directly follows `-f' _will_ end up
5761 naming the archive. If you neglect to specify an archive name, you may
5762 end up overwriting a file in the working directory with the archive you
5763 create since `tar' will use this file's name for the archive name.
5765 An archive can be saved as a file in the file system, sent through a
5766 pipe or over a network, or written to an I/O device such as a tape,
5767 floppy disk, or CD write drive.
5769 If you do not name the archive, `tar' uses the value of the
5770 environment variable `TAPE' as the file name for the archive. If that
5771 is not available, `tar' uses a default, compiled-in archive name,
5772 usually that for tape unit zero (i.e., `/dev/tu00').
5774 If you use `-' as an ARCHIVE-NAME, `tar' reads the archive from
5775 standard input (when listing or extracting files), or writes it to
5776 standard output (when creating an archive). If you use `-' as an
5777 ARCHIVE-NAME when modifying an archive, `tar' reads the original
5778 archive from its standard input and writes the entire new archive to
5779 its standard output.
5781 The following example is a convenient way of copying directory
5782 hierarchy from `sourcedir' to `targetdir'.
5784 $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)
5786 The `-C' option allows to avoid using subshells:
5788 $ tar -C sourcedir -cf - . | tar -C targetdir -xpf -
5790 In both examples above, the leftmost `tar' invocation archives the
5791 contents of `sourcedir' to the standard output, while the rightmost one
5792 reads this archive from its standard input and extracts it. The `-p'
5793 option tells it to restore permissions of the extracted files.
5795 To specify an archive file on a device attached to a remote machine,
5798 --file=HOSTNAME:/DEV/FILE-NAME
5800 `tar' will set up the remote connection, if possible, and prompt you
5801 for a username and password. If you use
5802 `--file=@HOSTNAME:/DEV/FILE-NAME', `tar' will attempt to set up the
5803 remote connection using your username as the username on the remote
5806 If the archive file name includes a colon (`:'), then it is assumed
5807 to be a file on another machine. If the archive file is
5808 `USER@HOST:FILE', then FILE is used on the host HOST. The remote host
5809 is accessed using the `rsh' program, with a username of USER. If the
5810 username is omitted (along with the `@' sign), then your user name will
5811 be used. (This is the normal `rsh' behavior.) It is necessary for the
5812 remote machine, in addition to permitting your `rsh' access, to have
5813 the `rmt' program installed (this command is included in the GNU `tar'
5814 distribution and by default is installed under `PREFIX/libexec/rmt',
5815 where PREFIX means your installation prefix). If you need to use a
5816 file whose name includes a colon, then the remote tape drive behavior
5817 can be inhibited by using the `--force-local' option.
5819 When the archive is being created to `/dev/null', GNU `tar' tries to
5820 minimize input and output operations. The Amanda backup system, when
5821 used with GNU `tar', has an initial sizing pass which uses this feature.
5824 File: tar.info, Node: Selecting Archive Members, Next: files, Prev: file, Up: Choosing
5826 6.2 Selecting Archive Members
5827 =============================
5829 "File Name arguments" specify which files in the file system `tar'
5830 operates on, when creating or adding to an archive, or which archive
5831 members `tar' operates on, when reading or deleting from an archive.
5834 To specify file names, you can include them as the last arguments on
5835 the command line, as follows:
5836 tar OPERATION [OPTION1 OPTION2 ...] [FILE NAME-1 FILE NAME-2 ...]
5838 If a file name begins with dash (`-'), precede it with `--add-file'
5839 option to prevent it from being treated as an option.
5841 By default GNU `tar' attempts to "unquote" each file or member name,
5842 replacing "escape sequences" according to the following table:
5844 Escape Replaced with
5845 -----------------------------------------------------------
5846 \a Audible bell (ASCII 7)
5847 \b Backspace (ASCII 8)
5848 \f Form feed (ASCII 12)
5849 \n New line (ASCII 10)
5850 \r Carriage return (ASCII 13)
5851 \t Horizontal tabulation (ASCII 9)
5852 \v Vertical tabulation (ASCII 11)
5854 \N ASCII N (N should be an octal number
5857 A backslash followed by any other symbol is retained.
5859 This default behavior is controlled by the following command line
5863 Enable unquoting input file or member names (default).
5866 Disable unquoting input file or member names.
5868 If you specify a directory name as a file name argument, all the
5869 files in that directory are operated on by `tar'.
5871 If you do not specify files, `tar' behavior differs depending on the
5872 operation mode as described below:
5874 When `tar' is invoked with `--create' (`-c'), `tar' will stop
5875 immediately, reporting the following:
5878 tar: Cowardly refusing to create an empty archive
5879 Try `tar --help' or `tar --usage' for more information.
5881 If you specify either `--list' (`-t') or `--extract' (`--get',
5882 `-x'), `tar' operates on all the archive members in the archive.
5884 If run with `--diff' option, tar will compare the archive with the
5885 contents of the current working directory.
5887 If you specify any other operation, `tar' does nothing.
5889 By default, `tar' takes file names from the command line. However,
5890 there are other ways to specify file or member names, or to modify the
5891 manner in which `tar' selects the files or members upon which to
5892 operate. In general, these methods work both for specifying the names
5893 of files and archive members.
5896 File: tar.info, Node: files, Next: exclude, Prev: Selecting Archive Members, Up: Choosing
5898 6.3 Reading Names from a File
5899 =============================
5901 Instead of giving the names of files or archive members on the command
5902 line, you can put the names into a file, and then use the
5903 `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option to `tar'.
5904 Give the name of the file which contains the list of files to include
5905 as the argument to `--files-from'. In the list, the file names should
5906 be separated by newlines. You will frequently use this option when you
5907 have generated the list of files to archive with the `find' utility.
5909 `--files-from=FILE-NAME'
5911 Get names to extract or create from file FILE-NAME.
5913 If you give a single dash as a file name for `--files-from', (i.e.,
5914 you specify either `--files-from=-' or `-T -'), then the file names are
5915 read from standard input.
5917 Unless you are running `tar' with `--create', you can not use both
5918 `--files-from=-' and `--file=-' (`-f -') in the same command.
5920 Any number of `-T' options can be given in the command line.
5922 The following example shows how to use `find' to generate a list of
5923 files smaller than 400K in length and put that list into a file called
5924 `small-files'. You can then use the `-T' option to `tar' to specify
5925 the files from that file, `small-files', to create the archive
5926 `little.tgz'. (The `-z' option to `tar' compresses the archive with
5927 `gzip'; *note gzip:: for more information.)
5929 $ find . -size -400 -print > small-files
5930 $ tar -c -v -z -T small-files -f little.tgz
5932 In the file list given by `-T' option, any file name beginning with `-'
5933 character is considered a `tar' option and is processed accordingly(1).
5934 For example, the common use of this feature is to change to another
5935 directory by specifying `-C' option:
5943 $ tar -c -f foo.tar --files-from list
5945 In this example, `tar' will first switch to `/etc' directory and add
5946 files `passwd' and `hosts' to the archive. Then it will change to
5947 `/lib' directory and will archive the file `libc.a'. Thus, the
5948 resulting archive `foo.tar' will contain:
5957 Notice that the option parsing algorithm used with `-T' is stricter
5958 than the one used by shell. Namely, when specifying option arguments,
5959 you should observe the following rules:
5961 * When using short (single-letter) option form, its argument must
5962 immediately follow the option letter, without any intervening
5963 whitespace. For example: `-Cdir'.
5965 * When using long option form, the option argument must be separated
5966 from the option by a single equal sign. No whitespace is allowed
5967 on any side of the equal sign. For example: `--directory=dir'.
5969 * For both short and long option forms, the option argument can be
5970 given on the next line after the option name, e.g.:
5980 If you happen to have a file whose name starts with `-', precede it
5981 with `--add-file' option to prevent it from being recognized as an
5982 option. For example: `--add-file=--my-file'.
5988 ---------- Footnotes ----------
5990 (1) Versions of GNU `tar' up to 1.15.1 recognized only `-C' option
5991 in file lists, and only if the option and its argument occupied two
5995 File: tar.info, Node: nul, Up: files
5997 6.3.1 `NUL'-Terminated File Names
5998 ---------------------------------
6000 The `--null' option causes `--files-from=FILE-OF-NAMES' (`-T
6001 FILE-OF-NAMES') to read file names terminated by a `NUL' instead of a
6002 newline, so files whose names contain newlines can be archived using
6006 Only consider `NUL'-terminated file names, instead of files that
6007 terminate in a newline.
6010 Undo the effect of any previous `--null' option.
6012 The `--null' option is just like the one in GNU `xargs' and `cpio',
6013 and is useful with the `-print0' predicate of GNU `find'. In `tar',
6014 `--null' also disables special handling for file names that begin with
6017 This example shows how to use `find' to generate a list of files
6018 larger than 800K in length and put that list into a file called
6019 `long-files'. The `-print0' option to `find' is just like `-print',
6020 except that it separates files with a `NUL' rather than with a newline.
6021 You can then run `tar' with both the `--null' and `-T' options to
6022 specify that `tar' gets the files from that file, `long-files', to
6023 create the archive `big.tgz'. The `--null' option to `tar' will cause
6024 `tar' to recognize the `NUL' separator between files.
6026 $ find . -size +800 -print0 > long-files
6027 $ tar -c -v --null --files-from=long-files --file=big.tar
6029 The `--no-null' option can be used if you need to read both
6030 `NUL'-terminated and newline-terminated files on the same command line.
6031 For example, if `flist' is a newline-terminated file, then the
6032 following command can be used to combine it with the above command:
6034 $ find . -size +800 -print0 |
6035 tar -c -f big.tar --null -T - --no-null -T flist
6037 This example uses short options for typographic reasons, to avoid
6040 GNU `tar' is able to automatically detect `NUL'-terminated file
6041 lists, so it is safe to use them even without the `--null' option. In
6042 this case `tar' will print a warning and continue reading such a file
6043 as if `--null' were actually given:
6045 $ find . -size +800 -print0 | tar -c -f big.tar -T -
6046 tar: -: file name read contains nul character
6048 The null terminator, however, remains in effect only for this
6049 particular file, any following `-T' options will assume newline
6050 termination. Of course, the null autodetection applies to these
6051 eventual surplus `-T' options as well.
6054 File: tar.info, Node: exclude, Next: wildcards, Prev: files, Up: Choosing
6056 6.4 Excluding Some Files
6057 ========================
6059 To avoid operating on files whose names match a particular pattern, use
6060 the `--exclude' or `--exclude-from' options.
6063 Causes `tar' to ignore files that match the PATTERN.
6065 The `--exclude=PATTERN' option prevents any file or member whose
6066 name matches the shell wildcard (PATTERN) from being operated on. For
6067 example, to create an archive with all the contents of the directory
6068 `src' except for files whose names end in `.o', use the command `tar
6069 -cf src.tar --exclude='*.o' src'.
6071 You may give multiple `--exclude' options.
6073 `--exclude-from=FILE'
6075 Causes `tar' to ignore files that match the patterns listed in
6078 Use the `--exclude-from' option to read a list of patterns, one per
6079 line, from FILE; `tar' will ignore files matching those patterns. Thus
6080 if `tar' is called as `tar -c -X foo .' and the file `foo' contains a
6081 single line `*.o', no files whose names end in `.o' will be added to
6084 Notice, that lines from FILE are read verbatim. One of the frequent
6085 errors is leaving some extra whitespace after a file name, which is
6086 difficult to catch using text editors.
6088 However, empty lines are OK.
6091 Exclude files and directories used by following version control
6092 systems: `CVS', `RCS', `SCCS', `SVN', `Arch', `Bazaar',
6093 `Mercurial', and `Darcs'.
6095 As of version 1.23, the following files are excluded:
6097 * `CVS/', and everything under it
6099 * `RCS/', and everything under it
6101 * `SCCS/', and everything under it
6103 * `.git/', and everything under it
6109 * `.svn/', and everything under it
6111 * `.arch-ids/', and everything under it
6113 * `{arch}/', and everything under it
6136 Exclude backup and lock files. This option causes exclusion of
6137 files that match the following shell globbing patterns:
6146 When creating an archive, the `--exclude-caches' option family
6147 causes `tar' to exclude all directories that contain a "cache directory
6148 tag". A cache directory tag is a short file with the well-known name
6149 `CACHEDIR.TAG' and having a standard header specified in
6150 `http://www.brynosaurus.com/cachedir/spec.html'. Various applications
6151 write cache directory tags into directories they use to hold
6152 regenerable, non-precious data, so that such data can be more easily
6153 excluded from backups.
6155 There are three `exclude-caches' options, each providing a different
6156 exclusion semantics:
6159 Do not archive the contents of the directory, but archive the
6160 directory itself and the `CACHEDIR.TAG' file.
6162 `--exclude-caches-under'
6163 Do not archive the contents of the directory, nor the
6164 `CACHEDIR.TAG' file, archive only the directory itself.
6166 `--exclude-caches-all'
6167 Omit directories containing `CACHEDIR.TAG' file entirely.
6169 Another option family, `--exclude-tag', provides a generalization of
6170 this concept. It takes a single argument, a file name to look for.
6171 Any directory that contains this file will be excluded from the dump.
6172 Similarly to `exclude-caches', there are three options in this option
6175 `--exclude-tag=FILE'
6176 Do not dump the contents of the directory, but dump the directory
6177 itself and the FILE.
6179 `--exclude-tag-under=FILE'
6180 Do not dump the contents of the directory, nor the FILE, archive
6181 only the directory itself.
6183 `--exclude-tag-all=FILE'
6184 Omit directories containing FILE file entirely.
6186 Multiple `--exclude-tag*' options can be given.
6188 For example, given this directory:
6199 The `--exclude-tag' will produce the following:
6201 $ tar -cf archive.tar --exclude-tag=tagfile -v dir
6206 tar: dir/folk/: contains a cache directory tag tagfile;
6210 Both the `dir/folk' directory and its tagfile are preserved in the
6211 archive, however the rest of files in this directory are not.
6213 Now, using the `--exclude-tag-under' option will exclude `tagfile'
6214 from the dump, while still preserving the directory itself, as shown in
6217 $ tar -cf archive.tar --exclude-tag-under=tagfile -v dir
6222 ./tar: dir/folk/: contains a cache directory tag tagfile;
6225 Finally, using `--exclude-tag-all' omits the `dir/folk' directory
6228 $ tar -cf archive.tar --exclude-tag-all=tagfile -v dir
6232 ./tar: dir/folk/: contains a cache directory tag tagfile;
6233 directory not dumped
6237 * problems with exclude::
6240 File: tar.info, Node: problems with exclude, Up: exclude
6242 Problems with Using the `exclude' Options
6243 -----------------------------------------
6245 Some users find `exclude' options confusing. Here are some common
6248 * The main operating mode of `tar' does not act on a file name
6249 explicitly listed on the command line, if one of its file name
6250 components is excluded. In the example above, if you create an
6251 archive and exclude files that end with `*.o', but explicitly name
6252 the file `dir.o/foo' after all the options have been listed,
6253 `dir.o/foo' will be excluded from the archive.
6255 * You can sometimes confuse the meanings of `--exclude' and
6256 `--exclude-from'. Be careful: use `--exclude' when files to be
6257 excluded are given as a pattern on the command line. Use
6258 `--exclude-from' to introduce the name of a file which contains a
6259 list of patterns, one per line; each of these patterns can exclude
6260 zero, one, or many files.
6262 * When you use `--exclude=PATTERN', be sure to quote the PATTERN
6263 parameter, so GNU `tar' sees wildcard characters like `*'. If you
6264 do not do this, the shell might expand the `*' itself using files
6265 at hand, so `tar' might receive a list of files instead of one
6266 pattern, or none at all, making the command somewhat illegal.
6267 This might not correspond to what you want.
6271 $ tar -c -f ARCHIVE.TAR --exclude '*.o' DIRECTORY
6276 $ tar -c -f ARCHIVE.TAR --exclude *.o DIRECTORY
6278 * You must use use shell syntax, or globbing, rather than `regexp'
6279 syntax, when using exclude options in `tar'. If you try to use
6280 `regexp' syntax to describe files to be excluded, your command
6283 * In earlier versions of `tar', what is now the `--exclude-from'
6284 option was called `--exclude' instead. Now, `--exclude' applies
6285 to patterns listed on the command line and `--exclude-from'
6286 applies to patterns listed in a file.
6290 File: tar.info, Node: wildcards, Next: quoting styles, Prev: exclude, Up: Choosing
6292 6.5 Wildcards Patterns and Matching
6293 ===================================
6295 "Globbing" is the operation by which "wildcard" characters, `*' or `?'
6296 for example, are replaced and expanded into all existing files matching
6297 the given pattern. GNU `tar' can use wildcard patterns for matching
6298 (or globbing) archive members when extracting from or listing an
6299 archive. Wildcard patterns are also used for verifying volume labels
6300 of `tar' archives. This section has the purpose of explaining wildcard
6303 A PATTERN should be written according to shell syntax, using wildcard
6304 characters to effect globbing. Most characters in the pattern stand
6305 for themselves in the matched string, and case is significant: `a' will
6306 match only `a', and not `A'. The character `?' in the pattern matches
6307 any single character in the matched string. The character `*' in the
6308 pattern matches zero, one, or more single characters in the matched
6309 string. The character `\' says to take the following character of the
6310 pattern _literally_; it is useful when one needs to match the `?', `*',
6311 `[' or `\' characters, themselves.
6313 The character `[', up to the matching `]', introduces a character
6314 class. A "character class" is a list of acceptable characters for the
6315 next single character of the matched string. For example, `[abcde]'
6316 would match any of the first five letters of the alphabet. Note that
6317 within a character class, all of the "special characters" listed above
6318 other than `\' lose their special meaning; for example, `[-\\[*?]]'
6319 would match any of the characters, `-', `\', `[', `*', `?', or `]'.
6320 (Due to parsing constraints, the characters `-' and `]' must either
6321 come _first_ or _last_ in a character class.)
6323 If the first character of the class after the opening `[' is `!' or
6324 `^', then the meaning of the class is reversed. Rather than listing
6325 character to match, it lists those characters which are _forbidden_ as
6326 the next single character of the matched string.
6328 Other characters of the class stand for themselves. The special
6329 construction `[A-E]', using an hyphen between two letters, is meant to
6330 represent all characters between A and E, inclusive.
6332 Periods (`.') or forward slashes (`/') are not considered special
6333 for wildcard matches. However, if a pattern completely matches a
6334 directory prefix of a matched string, then it matches the full matched
6335 string: thus, excluding a directory also excludes all the files beneath
6340 * controlling pattern-matching::
6343 File: tar.info, Node: controlling pattern-matching, Up: wildcards
6345 Controlling Pattern-Matching
6346 ----------------------------
6348 For the purposes of this section, we call "exclusion members" all
6349 member names obtained while processing `--exclude' and `--exclude-from'
6350 options, and "inclusion members" those member names that were given in
6351 the command line or read from the file specified with `--files-from'
6354 These two pairs of member lists are used in the following operations:
6355 `--diff', `--extract', `--list', `--update'.
6357 There are no inclusion members in create mode (`--create' and
6358 `--append'), since in this mode the names obtained from the command
6359 line refer to _files_, not archive members.
6361 By default, inclusion members are compared with archive members
6362 literally (1) and exclusion members are treated as globbing patterns.
6370 # Member names are used verbatim:
6371 $ tar -xf foo.tar -v '[remarks]'
6373 # Exclude member names are globbed:
6374 $ tar -xf foo.tar -v --exclude '*.c'
6378 This behavior can be altered by using the following options:
6381 Treat all member names as wildcards.
6384 Treat all member names as literal strings.
6386 Thus, to extract files whose names end in `.c', you can use:
6388 $ tar -xf foo.tar -v --wildcards '*.c'
6392 Notice quoting of the pattern to prevent the shell from interpreting it.
6394 The effect of `--wildcards' option is canceled by `--no-wildcards'.
6395 This can be used to pass part of the command line arguments verbatim
6396 and other part as globbing patterns. For example, the following
6399 $ tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'
6401 instructs `tar' to extract from `foo.tar' all files whose names end in
6402 `.txt' and the file named `[remarks]'.
6404 Normally, a pattern matches a name if an initial subsequence of the
6405 name's components matches the pattern, where `*', `?', and `[...]' are
6406 the usual shell wildcards, `\' escapes wildcards, and wildcards can
6409 Other than optionally stripping leading `/' from names (*note
6410 absolute::), patterns and names are used as-is. For example, trailing
6411 `/' is not trimmed from a user-specified name before deciding whether
6414 However, this matching procedure can be altered by the options listed
6415 below. These options accumulate. For example:
6417 --ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
6419 ignores case when excluding `makefile', but not when excluding `readme'.
6423 If anchored, a pattern must match an initial subsequence of the
6424 name's components. Otherwise, the pattern can match any
6425 subsequence. Default is `--no-anchored' for exclusion members and
6426 `--anchored' inclusion members.
6430 When ignoring case, upper-case patterns match lower-case names and
6431 vice versa. When not ignoring case (the default), matching is
6434 `--wildcards-match-slash'
6435 `--no-wildcards-match-slash'
6436 When wildcards match slash (the default for exclusion members), a
6437 wildcard like `*' in the pattern can match a `/' in the name.
6438 Otherwise, `/' is matched only by `/'.
6441 The `--recursion' and `--no-recursion' options (*note recurse::)
6442 also affect how member patterns are interpreted. If recursion is in
6443 effect, a pattern matches a name if it matches any of the name's parent
6446 The following table summarizes pattern-matching default values:
6448 Members Default settings
6449 --------------------------------------------------------------------------
6450 Inclusion `--no-wildcards --anchored
6451 --no-wildcards-match-slash'
6452 Exclusion `--wildcards --no-anchored
6453 --wildcards-match-slash'
6455 ---------- Footnotes ----------
6457 (1) Notice that earlier GNU `tar' versions used globbing for
6458 inclusion members, which contradicted to UNIX98 specification and was
6459 not documented. *Note Changes::, for more information on this and other
6463 File: tar.info, Node: quoting styles, Next: transform, Prev: wildcards, Up: Choosing
6465 6.6 Quoting Member Names
6466 ========================
6468 When displaying member names, `tar' takes care to avoid ambiguities
6469 caused by certain characters. This is called "name quoting". The
6470 characters in question are:
6472 * Non-printable control characters:
6473 Character ASCII Character name
6474 ---------------------------------------------------------------
6479 \r 13 Carriage return
6480 \t 9 Horizontal tabulation
6481 \v 11 Vertical tabulation
6485 * Single and double quotes (`'' and `"')
6489 The exact way `tar' uses to quote these characters depends on the
6490 "quoting style". The default quoting style, called "escape" (see
6491 below), uses backslash notation to represent control characters, space
6492 and backslash. Using this quoting style, control characters are
6493 represented as listed in column `Character' in the above table, a space
6494 is printed as `\ ' and a backslash as `\\'.
6496 GNU `tar' offers seven distinct quoting styles, which can be selected
6497 using `--quoting-style' option:
6499 `--quoting-style=STYLE'
6500 Sets quoting style. Valid values for STYLE argument are: literal,
6501 shell, shell-always, c, escape, locale, clocale.
6503 These styles are described in detail below. To illustrate their
6504 effect, we will use an imaginary tar archive `arch.tar' containing the
6507 # 1. Contains horizontal tabulation character.
6509 # 2. Contains newline character
6512 # 3. Contains a space
6514 # 4. Contains double quotes
6516 # 5. Contains single quotes
6518 # 6. Contains a backslash character:
6521 Here is how usual `ls' command would have listed them, if they had
6522 existed in the current working directory:
6535 No quoting, display each character as is:
6537 $ tar tf arch.tar --quoting-style=literal
6548 Display characters the same way Bourne shell does: control
6549 characters, except `\t' and `\n', are printed using backslash
6550 escapes, `\t' and `\n' are printed as is, and a single quote is
6551 printed as `\''. If a name contains any quoted characters, it is
6552 enclosed in single quotes. In particular, if a name contains
6553 single quotes, it is printed as several single-quoted strings:
6555 $ tar tf arch.tar --quoting-style=shell
6558 './a'\''single'\''quote'
6566 Same as `shell', but the names are always enclosed in single
6569 $ tar tf arch.tar --quoting-style=shell-always
6572 './a'\''single'\''quote'
6580 Use the notation of the C programming language. All names are
6581 enclosed in double quotes. Control characters are quoted using
6582 backslash notations, double quotes are represented as `\"',
6583 backslash characters are represented as `\\'. Single quotes and
6584 spaces are not quoted:
6586 $ tar tf arch.tar --quoting-style=c
6590 "./a\"double\"quote"
6596 Control characters are printed using backslash notation, a space is
6597 printed as `\ ' and a backslash as `\\'. This is the default
6598 quoting style, unless it was changed when configured the package.
6600 $ tar tf arch.tar --quoting-style=escape
6610 Control characters, single quote and backslash are printed using
6611 backslash notation. All names are quoted using left and right
6612 quotation marks, appropriate to the current locale. If it does not
6613 define quotation marks, use ``' as left and `'' as right quotation
6614 marks. Any occurrences of the right quotation mark in a name are
6615 escaped with `\', for example:
6619 $ tar tf arch.tar --quoting-style=locale
6622 `./a\'single\'quote'
6629 Same as `locale', but `"' is used for both left and right
6630 quotation marks, if not provided by the currently selected locale:
6632 $ tar tf arch.tar --quoting-style=clocale
6636 "./a\"double\"quote"
6641 You can specify which characters should be quoted in addition to
6642 those implied by the current quoting style:
6644 `--quote-chars=STRING'
6645 Always quote characters from STRING, even if the selected quoting
6646 style would not quote them.
6648 For example, using `escape' quoting (compare with the usual escape
6651 $ tar tf arch.tar --quoting-style=escape --quote-chars=' "'
6660 To disable quoting of such additional characters, use the following
6663 `--no-quote-chars=STRING'
6664 Remove characters listed in STRING from the list of quoted
6665 characters set by the previous `--quote-chars' option.
6667 This option is particularly useful if you have added `--quote-chars'
6668 to your `TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to disable it for
6669 the current invocation.
6671 Note, that `--no-quote-chars' does _not_ disable those characters
6672 that are quoted by default in the selected quoting style.
6675 File: tar.info, Node: transform, Next: after, Prev: quoting styles, Up: Choosing
6677 6.7 Modifying File and Member Names
6678 ===================================
6680 `Tar' archives contain detailed information about files stored in them
6681 and full file names are part of that information. When storing a file
6682 to an archive, its file name is recorded in it, along with the actual
6683 file contents. When restoring from an archive, a file is created on
6684 disk with exactly the same name as that stored in the archive. In the
6685 majority of cases this is the desired behavior of a file archiver.
6686 However, there are some cases when it is not.
6688 First of all, it is often unsafe to extract archive members with
6689 absolute file names or those that begin with a `../'. GNU `tar' takes
6690 special precautions when extracting such names and provides a special
6691 option for handling them, which is described in *note absolute::.
6693 Secondly, you may wish to extract file names without some leading
6694 directory components, or with otherwise modified names. In other cases
6695 it is desirable to store files under differing names in the archive.
6697 GNU `tar' provides several options for these needs.
6699 `--strip-components=NUMBER'
6700 Strip given NUMBER of leading components from file names before
6703 For example, suppose you have archived whole `/usr' hierarchy to a
6704 tar archive named `usr.tar'. Among other files, this archive contains
6705 `usr/include/stdlib.h', which you wish to extract to the current
6706 working directory. To do so, you type:
6708 $ tar -xf usr.tar --strip=2 usr/include/stdlib.h
6710 The option `--strip=2' instructs `tar' to strip the two leading
6711 components (`usr/' and `include/') off the file name.
6713 If you add the `--verbose' (`-v') option to the invocation above,
6714 you will note that the verbose listing still contains the full file
6715 name, with the two removed components still in place. This can be
6716 inconvenient, so `tar' provides a special option for altering this
6719 `--show-transformed-names'
6720 Display file or member names with all requested transformations
6725 $ tar -xf usr.tar -v --strip=2 usr/include/stdlib.h
6726 usr/include/stdlib.h
6727 $ tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h
6730 Notice that in both cases the file `stdlib.h' is extracted to the
6731 current working directory, `--show-transformed-names' affects only the
6732 way its name is displayed.
6734 This option is especially useful for verifying whether the invocation
6735 will have the desired effect. Thus, before running
6739 it is often advisable to run
6741 $ tar -t -v --show-transformed --strip=N
6743 to make sure the command will produce the intended results.
6745 In case you need to apply more complex modifications to the file
6746 name, GNU `tar' provides a general-purpose transformation option:
6748 `--transform=EXPRESSION'
6749 `--xform=EXPRESSION'
6750 Modify file names using supplied EXPRESSION.
6752 The EXPRESSION is a `sed'-like replace expression of the form:
6754 s/REGEXP/REPLACE/[FLAGS]
6756 where REGEXP is a "regular expression", REPLACE is a replacement for
6757 each file name part that matches REGEXP. Both REGEXP and REPLACE are
6758 described in detail in *note The "s" Command: (sed)The "s" Command.
6760 Any delimiter can be used in lieu of `/', the only requirement being
6761 that it be used consistently throughout the expression. For example,
6762 the following two expressions are equivalent:
6767 Changing delimiters is often useful when the REGEX contains slashes.
6768 For example, it is more convenient to write `s,/,-,' than `s/\//-/'.
6770 As in `sed', you can give several replace expressions, separated by
6773 Supported FLAGS are:
6776 Apply the replacement to _all_ matches to the REGEXP, not just the
6780 Use case-insensitive matching.
6783 REGEXP is an "extended regular expression" (*note Extended regular
6784 expressions: (sed)Extended regexps.).
6787 Only replace the NUMBERth match of the REGEXP.
6789 Note: the POSIX standard does not specify what should happen when
6790 you mix the `g' and NUMBER modifiers. GNU `tar' follows the GNU
6791 `sed' implementation in this regard, so the interaction is defined
6792 to be: ignore matches before the NUMBERth, and then match and
6793 replace all matches from the NUMBERth on.
6796 In addition, several "transformation scope" flags are supported,
6797 that control to what files transformations apply. These are:
6800 Apply transformation to regular archive members.
6803 Do not apply transformation to regular archive members.
6806 Apply transformation to symbolic link targets.
6809 Do not apply transformation to symbolic link targets.
6812 Apply transformation to hard link targets.
6815 Do not apply transformation to hard link targets.
6817 Default is `rsh', which means to apply tranformations to both archive
6818 members and targets of symbolic and hard links.
6820 Default scope flags can also be changed using `flags=' statement in
6821 the transform expression. The flags set this way remain in force until
6822 next `flags=' statement or end of expression, whichever occurs first.
6825 --transform 'flags=S;s|^|/usr/local/|'
6827 Here are several examples of `--transform' usage:
6829 1. Extract `usr/' hierarchy into `usr/local/':
6831 $ tar --transform='s,usr/,usr/local/,' -x -f arch.tar
6833 2. Strip two leading directory components (equivalent to
6834 `--strip-components=2'):
6836 $ tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar
6838 3. Convert each file name to lower case:
6840 $ tar --transform 's/.*/\L&/' -x -f arch.tar
6842 4. Prepend `/prefix/' to each file name:
6844 $ tar --transform 's,^,/prefix/,' -x -f arch.tar
6846 5. Archive the `/lib' directory, prepending `/usr/local' to each
6849 $ tar --transform 's,^,/usr/local/,S' -c -f arch.tar /lib
6851 Notice the use of flags in the last example. The `/lib' directory
6852 often contains many symbolic links to files within it. It may look,
6853 for example, like this:
6856 drwxr-xr-x root/root 0 2008-07-08 16:20 /lib/
6857 -rwxr-xr-x root/root 1250840 2008-05-25 07:44 /lib/libc-2.3.2.so
6858 lrwxrwxrwx root/root 0 2008-06-24 17:12 /lib/libc.so.6 -> libc-2.3.2.so
6861 Using the expression `s,^,/usr/local/,' would mean adding
6862 `/usr/local' to both regular archive members and to link targets. In
6863 this case, `/lib/libc.so.6' would become:
6865 /usr/local/lib/libc.so.6 -> /usr/local/libc-2.3.2.so
6867 This is definitely not desired. To avoid this, the `S' flag is
6868 used, which excludes symbolic link targets from filename
6869 transformations. The result is:
6871 $ tar --transform 's,^,/usr/local/,S', -c -v -f arch.tar \
6872 --show-transformed /lib
6873 drwxr-xr-x root/root 0 2008-07-08 16:20 /usr/local/lib/
6874 -rwxr-xr-x root/root 1250840 2008-05-25 07:44 /usr/local/lib/libc-2.3.2.so
6875 lrwxrwxrwx root/root 0 2008-06-24 17:12 /usr/local/lib/libc.so.6 ->
6878 Unlike `--strip-components', `--transform' can be used in any GNU
6879 `tar' operation mode. For example, the following command adds files to
6880 the archive while replacing the leading `usr/' component with `var/':
6882 $ tar -cf arch.tar --transform='s,^usr/,var/,' /
6884 To test `--transform' effect we suggest using
6885 `--show-transformed-names' option:
6887 $ tar -cf arch.tar --transform='s,^usr/,var/,' \
6888 --verbose --show-transformed-names /
6890 If both `--strip-components' and `--transform' are used together,
6891 then `--transform' is applied first, and the required number of
6892 components is then stripped from its result.
6894 You can use as many `--transform' options in a single command line
6895 as you want. The specified expressions will then be applied in order
6896 of their appearance. For example, the following two invocations are
6899 $ tar -cf arch.tar --transform='s,/usr/var,/var/' \
6900 --transform='s,/usr/local,/usr/,'
6901 $ tar -cf arch.tar \
6902 --transform='s,/usr/var,/var/;s,/usr/local,/usr/,'
6905 File: tar.info, Node: after, Next: recurse, Prev: transform, Up: Choosing
6907 6.8 Operating Only on New Files
6908 ===============================
6910 The `--after-date=DATE' (`--newer=DATE', `-N DATE') option causes `tar'
6911 to only work on files whose data modification or status change times
6912 are newer than the DATE given. If DATE starts with `/' or `.', it is
6913 taken to be a file name; the data modification time of that file is
6914 used as the date. If you use this option when creating or appending to
6915 an archive, the archive will only include new files. If you use
6916 `--after-date' when extracting an archive, `tar' will only extract
6917 files newer than the DATE you specify.
6919 If you only want `tar' to make the date comparison based on
6920 modification of the file's data (rather than status changes), then use
6921 the `--newer-mtime=DATE' option.
6923 You may use these options with any operation. Note that these
6924 options differ from the `--update' (`-u') operation in that they allow
6925 you to specify a particular date against which `tar' can compare when
6926 deciding whether or not to archive the files.
6931 Only store files newer than DATE.
6933 Acts on files only if their data modification or status change
6934 times are later than DATE. Use in conjunction with any operation.
6936 If DATE starts with `/' or `.', it is taken to be a file name; the
6937 data modification time of that file is used as the date.
6939 `--newer-mtime=DATE'
6940 Acts like `--after-date', but only looks at data modification
6943 These options limit `tar' to operate only on files which have been
6944 modified after the date specified. A file's status is considered to
6945 have changed if its contents have been modified, or if its owner,
6946 permissions, and so forth, have been changed. (For more information on
6947 how to specify a date, see *note Date input formats::; remember that the
6948 entire date argument must be quoted if it contains any spaces.)
6950 Gurus would say that `--after-date' tests both the data modification
6951 time (`mtime', the time the contents of the file were last modified)
6952 and the status change time (`ctime', the time the file's status was
6953 last changed: owner, permissions, etc.) fields, while `--newer-mtime'
6954 tests only the `mtime' field.
6956 To be precise, `--after-date' checks _both_ `mtime' and `ctime' and
6957 processes the file if either one is more recent than DATE, while
6958 `--newer-mtime' only checks `mtime' and disregards `ctime'. Neither
6959 does it use `atime' (the last time the contents of the file were looked
6962 Date specifiers can have embedded spaces. Because of this, you may
6963 need to quote date arguments to keep the shell from parsing them as
6964 separate arguments. For example, the following command will add to the
6965 archive all the files modified less than two days ago:
6967 $ tar -cf foo.tar --newer-mtime '2 days ago'
6969 When any of these options is used with the option `--verbose' (*note
6970 verbose tutorial::) GNU `tar' will try to convert the specified date
6971 back to its textual representation and compare that with the one given
6972 with the option. If the two dates differ, `tar' will print a warning
6973 saying what date it will use. This is to help user ensure he is using
6974 the right date. For example:
6976 $ tar -c -f archive.tar --after-date='10 days ago' .
6977 tar: Option --after-date: Treating date `10 days ago' as 2006-06-11
6980 *Please Note:* `--after-date' and `--newer-mtime' should not be
6981 used for incremental backups. *Note Incremental Dumps::, for
6982 proper way of creating incremental backups.
6985 File: tar.info, Node: recurse, Next: one, Prev: after, Up: Choosing
6987 6.9 Descending into Directories
6988 ===============================
6990 Usually, `tar' will recursively explore all directories (either those
6991 given on the command line or through the `--files-from' option) for the
6992 various files they contain. However, you may not always want `tar' to
6995 The `--no-recursion' option inhibits `tar''s recursive descent into
6996 specified directories. If you specify `--no-recursion', you can use
6997 the `find' (*note find: (find)Top.) utility for hunting through levels
6998 of directories to construct a list of file names which you could then
6999 pass to `tar'. `find' allows you to be more selective when choosing
7000 which files to archive; see *note files::, for more information on
7001 using `find' with `tar'.
7004 Prevents `tar' from recursively descending directories.
7007 Requires `tar' to recursively descend directories. This is the
7010 When you use `--no-recursion', GNU `tar' grabs directory entries
7011 themselves, but does not descend on them recursively. Many people use
7012 `find' for locating files they want to back up, and since `tar'
7013 _usually_ recursively descends on directories, they have to use the
7014 `-not -type d' test in their `find' invocation (*note Type:
7015 (find)Type.), as they usually do not want all the files in a directory.
7016 They then use the `--files-from' option to archive the files located
7019 The problem when restoring files archived in this manner is that the
7020 directories themselves are not in the archive; so the
7021 `--same-permissions' (`--preserve-permissions', `-p') option does not
7022 affect them--while users might really like it to. Specifying
7023 `--no-recursion' is a way to tell `tar' to grab only the directory
7024 entries given to it, adding no new files on its own. To summarize, if
7025 you use `find' to create a list of files to be stored in an archive,
7028 $ find DIR TESTS | \
7029 tar -cf ARCHIVE -T - --no-recursion
7031 The `--no-recursion' option also applies when extracting: it causes
7032 `tar' to extract only the matched directory entries, not the files
7033 under those directories.
7035 The `--no-recursion' option also affects how globbing patterns are
7036 interpreted (*note controlling pattern-matching::).
7038 The `--no-recursion' and `--recursion' options apply to later
7039 options and operands, and can be overridden by later occurrences of
7040 `--no-recursion' and `--recursion'. For example:
7042 $ tar -cf jams.tar --no-recursion grape --recursion grape/concord
7044 creates an archive with one entry for `grape', and the recursive
7045 contents of `grape/concord', but no entries under `grape' other than
7049 File: tar.info, Node: one, Prev: recurse, Up: Choosing
7051 6.10 Crossing File System Boundaries
7052 ====================================
7054 `tar' will normally automatically cross file system boundaries in order
7055 to archive files which are part of a directory tree. You can change
7056 this behavior by running `tar' and specifying `--one-file-system'.
7057 This option only affects files that are archived because they are in a
7058 directory that is being archived; `tar' will still archive files
7059 explicitly named on the command line or through `--files-from',
7060 regardless of where they reside.
7063 Prevents `tar' from crossing file system boundaries when
7064 archiving. Use in conjunction with any write operation.
7066 The `--one-file-system' option causes `tar' to modify its normal
7067 behavior in archiving the contents of directories. If a file in a
7068 directory is not on the same file system as the directory itself, then
7069 `tar' will not archive that file. If the file is a directory itself,
7070 `tar' will not archive anything beneath it; in other words, `tar' will
7071 not cross mount points.
7073 This option is useful for making full or incremental archival
7074 backups of a file system. If this option is used in conjunction with
7075 `--verbose' (`-v'), files that are excluded are mentioned by name on
7080 * directory:: Changing Directory
7081 * absolute:: Absolute File Names
7084 File: tar.info, Node: directory, Next: absolute, Up: one
7086 6.10.1 Changing the Working Directory
7087 -------------------------------------
7089 To change the working directory in the middle of a list of file names,
7090 either on the command line or in a file specified using `--files-from'
7091 (`-T'), use `--directory' (`-C'). This will change the working
7092 directory to the specified directory after that point in the list.
7094 `--directory=DIRECTORY'
7096 Changes the working directory in the middle of a command line.
7100 $ tar -c -f jams.tar grape prune -C food cherry
7102 will place the files `grape' and `prune' from the current directory
7103 into the archive `jams.tar', followed by the file `cherry' from the
7104 directory `food'. This option is especially useful when you have
7105 several widely separated files that you want to store in the same
7108 Note that the file `cherry' is recorded in the archive under the
7109 precise name `cherry', _not_ `food/cherry'. Thus, the archive will
7110 contain three files that all appear to have come from the same
7111 directory; if the archive is extracted with plain `tar --extract', all
7112 three files will be written in the current directory.
7114 Contrast this with the command,
7116 $ tar -c -f jams.tar grape prune -C food red/cherry
7118 which records the third file in the archive under the name `red/cherry'
7119 so that, if the archive is extracted using `tar --extract', the third
7120 file will be written in a subdirectory named `red'.
7122 You can use the `--directory' option to make the archive independent
7123 of the original name of the directory holding the files. The following
7124 command places the files `/etc/passwd', `/etc/hosts', and `/lib/libc.a'
7125 into the archive `foo.tar':
7127 $ tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a
7129 However, the names of the archive members will be exactly what they were
7130 on the command line: `passwd', `hosts', and `libc.a'. They will not
7131 appear to be related by file name to the original directories where
7132 those files were located.
7134 Note that `--directory' options are interpreted consecutively. If
7135 `--directory' specifies a relative file name, it is interpreted
7136 relative to the then current directory, which might not be the same as
7137 the original current working directory of `tar', due to a previous
7138 `--directory' option.
7140 When using `--files-from' (*note files::), you can put various `tar'
7141 options (including `-C') in the file list. Notice, however, that in
7142 this case the option and its argument may not be separated by
7143 whitespace. If you use short option, its argument must either follow
7144 the option letter immediately, without any intervening whitespace, or
7145 occupy the next line. Otherwise, if you use long option, separate its
7146 argument by an equal sign.
7148 For instance, the file list for the above example will be:
7156 To use it, you would invoke `tar' as follows:
7158 $ tar -c -f foo.tar --files-from list
7160 The interpretation of `--directory' is disabled by `--null' option.
7163 File: tar.info, Node: absolute, Prev: directory, Up: one
7165 6.10.2 Absolute File Names
7166 --------------------------
7168 By default, GNU `tar' drops a leading `/' on input or output, and
7169 complains about file names containing a `..' component. There is an
7170 option that turns off this behavior:
7174 Do not strip leading slashes from file names, and permit file names
7175 containing a `..' file name component.
7177 When `tar' extracts archive members from an archive, it strips any
7178 leading slashes (`/') from the member name. This causes absolute
7179 member names in the archive to be treated as relative file names. This
7180 allows you to have such members extracted wherever you want, instead of
7181 being restricted to extracting the member in the exact directory named
7182 in the archive. For example, if the archive member has the name
7183 `/etc/passwd', `tar' will extract it as if the name were really
7186 File names containing `..' can cause problems when extracting, so
7187 `tar' normally warns you about such files when creating an archive, and
7188 rejects attempts to extracts such files.
7190 Other `tar' programs do not do this. As a result, if you create an
7191 archive whose member names start with a slash, they will be difficult
7192 for other people with a non-GNU `tar' program to use. Therefore, GNU
7193 `tar' also strips leading slashes from member names when putting
7194 members into the archive. For example, if you ask `tar' to add the file
7195 `/bin/ls' to an archive, it will do so, but the member name will be
7198 If you use the `--absolute-names' (`-P') option, `tar' will do none
7199 of these transformations.
7201 To archive or extract files relative to the root directory, specify
7202 the `--absolute-names' (`-P') option.
7204 Normally, `tar' acts on files relative to the working
7205 directory--ignoring superior directory names when archiving, and
7206 ignoring leading slashes when extracting.
7208 When you specify `--absolute-names' (`-P'), `tar' stores file names
7209 including all superior directory names, and preserves leading slashes.
7210 If you only invoked `tar' from the root directory you would never need
7211 the `--absolute-names' option, but using this option may be more
7212 convenient than switching to root.
7215 Preserves full file names (including superior directory names) when
7216 archiving files. Preserves leading slash when extracting files.
7219 `tar' prints out a message about removing the `/' from file names.
7220 This message appears once per GNU `tar' invocation. It represents
7221 something which ought to be told; ignoring what it means can cause very
7222 serious surprises, later.
7224 Some people, nevertheless, do not want to see this message. Wanting
7225 to play really dangerously, one may of course redirect `tar' standard
7226 error to the sink. For example, under `sh':
7228 $ tar -c -f archive.tar /home 2> /dev/null
7230 Another solution, both nicer and simpler, would be to change to the `/'
7231 directory first, and then avoid absolute notation. For example:
7233 $ tar -c -f archive.tar -C / home
7235 ---------- Footnotes ----------
7237 (1) A side effect of this is that when `--create' is used with
7238 `--verbose' the resulting output is not, generally speaking, the same
7239 as the one you'd get running `tar --list' command. This may be
7240 important if you use some scripts for comparing both outputs. *Note
7241 listing member and file names::, for the information on how to handle
7245 File: tar.info, Node: Date input formats, Next: Formats, Prev: Choosing, Up: Top
7247 7 Date input formats
7248 ********************
7252 Our units of temporal measurement, from seconds on up to months,
7253 are so complicated, asymmetrical and disjunctive so as to make
7254 coherent mental reckoning in time all but impossible. Indeed, had
7255 some tyrannical god contrived to enslave our minds to time, to
7256 make it all but impossible for us to escape subjection to sodden
7257 routines and unpleasant surprises, he could hardly have done
7258 better than handing down our present system. It is like a set of
7259 trapezoidal building blocks, with no vertical or horizontal
7260 surfaces, like a language in which the simplest thought demands
7261 ornate constructions, useless particles and lengthy
7262 circumlocutions. Unlike the more successful patterns of language
7263 and science, which enable us to face experience boldly or at least
7264 level-headedly, our system of temporal calculation silently and
7265 persistently encourages our terror of time.
7267 ... It is as though architects had to measure length in feet,
7268 width in meters and height in ells; as though basic instruction
7269 manuals demanded a knowledge of five different languages. It is
7270 no wonder then that we often look into our own immediate past or
7271 future, last Tuesday or a week from Sunday, with feelings of
7272 helpless confusion. ...
7274 -- Robert Grudin, `Time and the Art of Living'.
7276 This section describes the textual date representations that GNU
7277 programs accept. These are the strings you, as a user, can supply as
7278 arguments to the various programs. The C interface (via the `get_date'
7279 function) is not described here.
7283 * General date syntax:: Common rules.
7284 * Calendar date items:: 19 Dec 1994.
7285 * Time of day items:: 9:20pm.
7286 * Time zone items:: EST, PDT, GMT.
7287 * Day of week items:: Monday and others.
7288 * Relative items in date strings:: next tuesday, 2 years ago.
7289 * Pure numbers in date strings:: 19931219, 1440.
7290 * Seconds since the Epoch:: @1078100502.
7291 * Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
7292 * Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
7295 File: tar.info, Node: General date syntax, Next: Calendar date items, Up: Date input formats
7297 7.1 General date syntax
7298 =======================
7300 A "date" is a string, possibly empty, containing many items separated
7301 by whitespace. The whitespace may be omitted when no ambiguity arises.
7302 The empty string means the beginning of today (i.e., midnight). Order
7303 of the items is immaterial. A date string may contain many flavors of
7306 * calendar date items
7312 * day of the week items
7318 We describe each of these item types in turn, below.
7320 A few ordinal numbers may be written out in words in some contexts.
7321 This is most useful for specifying day of the week items or relative
7322 items (see below). Among the most commonly used ordinal numbers, the
7323 word `last' stands for -1, `this' stands for 0, and `first' and `next'
7324 both stand for 1. Because the word `second' stands for the unit of
7325 time there is no way to write the ordinal number 2, but for convenience
7326 `third' stands for 3, `fourth' for 4, `fifth' for 5, `sixth' for 6,
7327 `seventh' for 7, `eighth' for 8, `ninth' for 9, `tenth' for 10,
7328 `eleventh' for 11 and `twelfth' for 12.
7330 When a month is written this way, it is still considered to be
7331 written numerically, instead of being "spelled in full"; this changes
7332 the allowed strings.
7334 In the current implementation, only English is supported for words
7335 and abbreviations like `AM', `DST', `EST', `first', `January',
7336 `Sunday', `tomorrow', and `year'.
7338 The output of the `date' command is not always acceptable as a date
7339 string, not only because of the language problem, but also because
7340 there is no standard meaning for time zone items like `IST'. When using
7341 `date' to generate a date string intended to be parsed later, specify a
7342 date format that is independent of language and that does not use time
7343 zone items other than `UTC' and `Z'. Here are some ways to do this:
7345 $ LC_ALL=C TZ=UTC0 date
7346 Mon Mar 1 00:21:42 UTC 2004
7347 $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
7348 2004-03-01 00:21:42Z
7349 $ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension.
7350 2004-02-29 16:21:42,692722128-0800
7351 $ date --rfc-2822 # a GNU extension
7352 Sun, 29 Feb 2004 16:21:42 -0800
7353 $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension.
7354 2004-02-29 16:21:42 -0800
7355 $ date +'@%s.%N' # %s and %N are GNU extensions.
7356 @1078100502.692722128
7358 Alphabetic case is completely ignored in dates. Comments may be
7359 introduced between round parentheses, as long as included parentheses
7360 are properly nested. Hyphens not followed by a digit are currently
7361 ignored. Leading zeros on numbers are ignored.
7363 Invalid dates like `2005-02-29' or times like `24:00' are rejected.
7364 In the typical case of a host that does not support leap seconds, a
7365 time like `23:59:60' is rejected even if it corresponds to a valid leap
7369 File: tar.info, Node: Calendar date items, Next: Time of day items, Prev: General date syntax, Up: Date input formats
7371 7.2 Calendar date items
7372 =======================
7374 A "calendar date item" specifies a day of the year. It is specified
7375 differently, depending on whether the month is specified numerically or
7376 literally. All these strings specify the same calendar date:
7378 1972-09-24 # ISO 8601.
7379 72-9-24 # Assume 19xx for 69 through 99,
7380 # 20xx for 00 through 68.
7381 72-09-24 # Leading zeros are ignored.
7382 9/24/72 # Common U.S. writing.
7384 24 Sept 72 # September has a special abbreviation.
7385 24 Sep 72 # Three-letter abbreviations always allowed.
7390 The year can also be omitted. In this case, the last specified year
7391 is used, or the current year if none. For example:
7398 For numeric months, the ISO 8601 format `YEAR-MONTH-DAY' is allowed,
7399 where YEAR is any positive number, MONTH is a number between 01 and 12,
7400 and DAY is a number between 01 and 31. A leading zero must be present
7401 if a number is less than ten. If YEAR is 68 or smaller, then 2000 is
7402 added to it; otherwise, if YEAR is less than 100, then 1900 is added to
7403 it. The construct `MONTH/DAY/YEAR', popular in the United States, is
7404 accepted. Also `MONTH/DAY', omitting the year.
7406 Literal months may be spelled out in full: `January', `February',
7407 `March', `April', `May', `June', `July', `August', `September',
7408 `October', `November' or `December'. Literal months may be abbreviated
7409 to their first three letters, possibly followed by an abbreviating dot.
7410 It is also permitted to write `Sept' instead of `September'.
7412 When months are written literally, the calendar date may be given as
7413 any of the following:
7420 Or, omitting the year:
7425 File: tar.info, Node: Time of day items, Next: Time zone items, Prev: Calendar date items, Up: Date input formats
7427 7.3 Time of day items
7428 =====================
7430 A "time of day item" in date strings specifies the time on a given day.
7431 Here are some examples, all of which represent the same time:
7436 20:02-0500 # In EST (U.S. Eastern Standard Time).
7438 More generally, the time of day may be given as
7439 `HOUR:MINUTE:SECOND', where HOUR is a number between 0 and 23, MINUTE
7440 is a number between 0 and 59, and SECOND is a number between 0 and 59
7441 possibly followed by `.' or `,' and a fraction containing one or more
7442 digits. Alternatively, `:SECOND' can be omitted, in which case it is
7443 taken to be zero. On the rare hosts that support leap seconds, SECOND
7446 If the time is followed by `am' or `pm' (or `a.m.' or `p.m.'), HOUR
7447 is restricted to run from 1 to 12, and `:MINUTE' may be omitted (taken
7448 to be zero). `am' indicates the first half of the day, `pm' indicates
7449 the second half of the day. In this notation, 12 is the predecessor of
7450 1: midnight is `12am' while noon is `12pm'. (This is the zero-oriented
7451 interpretation of `12am' and `12pm', as opposed to the old tradition
7452 derived from Latin which uses `12m' for noon and `12pm' for midnight.)
7454 The time may alternatively be followed by a time zone correction,
7455 expressed as `SHHMM', where S is `+' or `-', HH is a number of zone
7456 hours and MM is a number of zone minutes. The zone minutes term, MM,
7457 may be omitted, in which case the one- or two-digit correction is
7458 interpreted as a number of hours. You can also separate HH from MM
7459 with a colon. When a time zone correction is given this way, it forces
7460 interpretation of the time relative to Coordinated Universal Time
7461 (UTC), overriding any previous specification for the time zone or the
7462 local time zone. For example, `+0530' and `+05:30' both stand for the
7463 time zone 5.5 hours ahead of UTC (e.g., India). This is the best way to
7464 specify a time zone correction by fractional parts of an hour. The
7465 maximum zone correction is 24 hours.
7467 Either `am'/`pm' or a time zone correction may be specified, but not
7471 File: tar.info, Node: Time zone items, Next: Day of week items, Prev: Time of day items, Up: Date input formats
7476 A "time zone item" specifies an international time zone, indicated by a
7477 small set of letters, e.g., `UTC' or `Z' for Coordinated Universal
7478 Time. Any included periods are ignored. By following a
7479 non-daylight-saving time zone by the string `DST' in a separate word
7480 (that is, separated by some white space), the corresponding daylight
7481 saving time zone may be specified. Alternatively, a
7482 non-daylight-saving time zone can be followed by a time zone
7483 correction, to add the two values. This is normally done only for
7484 `UTC'; for example, `UTC+05:30' is equivalent to `+05:30'.
7486 Time zone items other than `UTC' and `Z' are obsolescent and are not
7487 recommended, because they are ambiguous; for example, `EST' has a
7488 different meaning in Australia than in the United States. Instead,
7489 it's better to use unambiguous numeric time zone corrections like
7490 `-0500', as described in the previous section.
7492 If neither a time zone item nor a time zone correction is supplied,
7493 time stamps are interpreted using the rules of the default time zone
7494 (*note Specifying time zone rules::).
7497 File: tar.info, Node: Day of week items, Next: Relative items in date strings, Prev: Time zone items, Up: Date input formats
7499 7.5 Day of week items
7500 =====================
7502 The explicit mention of a day of the week will forward the date (only
7503 if necessary) to reach that day of the week in the future.
7505 Days of the week may be spelled out in full: `Sunday', `Monday',
7506 `Tuesday', `Wednesday', `Thursday', `Friday' or `Saturday'. Days may
7507 be abbreviated to their first three letters, optionally followed by a
7508 period. The special abbreviations `Tues' for `Tuesday', `Wednes' for
7509 `Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed.
7511 A number may precede a day of the week item to move forward
7512 supplementary weeks. It is best used in expression like `third
7513 monday'. In this context, `last DAY' or `next DAY' is also acceptable;
7514 they move one week before or after the day that DAY by itself would
7517 A comma following a day of the week item is ignored.
7520 File: tar.info, Node: Relative items in date strings, Next: Pure numbers in date strings, Prev: Day of week items, Up: Date input formats
7522 7.6 Relative items in date strings
7523 ==================================
7525 "Relative items" adjust a date (or the current date if none) forward or
7526 backward. The effects of relative items accumulate. Here are some
7534 The unit of time displacement may be selected by the string `year'
7535 or `month' for moving by whole years or months. These are fuzzy units,
7536 as years and months are not all of equal duration. More precise units
7537 are `fortnight' which is worth 14 days, `week' worth 7 days, `day'
7538 worth 24 hours, `hour' worth 60 minutes, `minute' or `min' worth 60
7539 seconds, and `second' or `sec' worth one second. An `s' suffix on
7540 these units is accepted and ignored.
7542 The unit of time may be preceded by a multiplier, given as an
7543 optionally signed number. Unsigned numbers are taken as positively
7544 signed. No number at all implies 1 for a multiplier. Following a
7545 relative item by the string `ago' is equivalent to preceding the unit
7546 by a multiplier with value -1.
7548 The string `tomorrow' is worth one day in the future (equivalent to
7549 `day'), the string `yesterday' is worth one day in the past (equivalent
7552 The strings `now' or `today' are relative items corresponding to
7553 zero-valued time displacement, these strings come from the fact a
7554 zero-valued time displacement represents the current time when not
7555 otherwise changed by previous items. They may be used to stress other
7556 items, like in `12:00 today'. The string `this' also has the meaning
7557 of a zero-valued time displacement, but is preferred in date strings
7558 like `this thursday'.
7560 When a relative item causes the resulting date to cross a boundary
7561 where the clocks were adjusted, typically for daylight saving time, the
7562 resulting date and time are adjusted accordingly.
7564 The fuzz in units can cause problems with relative items. For
7565 example, `2003-07-31 -1 month' might evaluate to 2003-07-01, because
7566 2003-06-31 is an invalid date. To determine the previous month more
7567 reliably, you can ask for the month before the 15th of the current
7571 Thu, 31 Jul 2003 13:02:39 -0700
7572 $ date --date='-1 month' +'Last month was %B?'
7573 Last month was July?
7574 $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
7575 Last month was June!
7577 Also, take care when manipulating dates around clock changes such as
7578 daylight saving leaps. In a few cases these have added or subtracted
7579 as much as 24 hours from the clock, so it is often wise to adopt
7580 universal time by setting the `TZ' environment variable to `UTC0'
7581 before embarking on calendrical calculations.
7584 File: tar.info, Node: Pure numbers in date strings, Next: Seconds since the Epoch, Prev: Relative items in date strings, Up: Date input formats
7586 7.7 Pure numbers in date strings
7587 ================================
7589 The precise interpretation of a pure decimal number depends on the
7590 context in the date string.
7592 If the decimal number is of the form YYYYMMDD and no other calendar
7593 date item (*note Calendar date items::) appears before it in the date
7594 string, then YYYY is read as the year, MM as the month number and DD as
7595 the day of the month, for the specified calendar date.
7597 If the decimal number is of the form HHMM and no other time of day
7598 item appears before it in the date string, then HH is read as the hour
7599 of the day and MM as the minute of the hour, for the specified time of
7600 day. MM can also be omitted.
7602 If both a calendar date and a time of day appear to the left of a
7603 number in the date string, but no relative item, then the number
7607 File: tar.info, Node: Seconds since the Epoch, Next: Specifying time zone rules, Prev: Pure numbers in date strings, Up: Date input formats
7609 7.8 Seconds since the Epoch
7610 ===========================
7612 If you precede a number with `@', it represents an internal time stamp
7613 as a count of seconds. The number can contain an internal decimal
7614 point (either `.' or `,'); any excess precision not supported by the
7615 internal representation is truncated toward minus infinity. Such a
7616 number cannot be combined with any other date item, as it specifies a
7617 complete time stamp.
7619 Internally, computer times are represented as a count of seconds
7620 since an epoch--a well-defined point of time. On GNU and POSIX
7621 systems, the epoch is 1970-01-01 00:00:00 UTC, so `@0' represents this
7622 time, `@1' represents 1970-01-01 00:00:01 UTC, and so forth. GNU and
7623 most other POSIX-compliant systems support such times as an extension
7624 to POSIX, using negative counts, so that `@-1' represents 1969-12-31
7627 Traditional Unix systems count seconds with 32-bit two's-complement
7628 integers and can represent times from 1901-12-13 20:45:52 through
7629 2038-01-19 03:14:07 UTC. More modern systems use 64-bit counts of
7630 seconds with nanosecond subcounts, and can represent all the times in
7631 the known lifetime of the universe to a resolution of 1 nanosecond.
7633 On most hosts, these counts ignore the presence of leap seconds.
7634 For example, on most hosts `@915148799' represents 1998-12-31 23:59:59
7635 UTC, `@915148800' represents 1999-01-01 00:00:00 UTC, and there is no
7636 way to represent the intervening leap second 1998-12-31 23:59:60 UTC.
7639 File: tar.info, Node: Specifying time zone rules, Next: Authors of get_date, Prev: Seconds since the Epoch, Up: Date input formats
7641 7.9 Specifying time zone rules
7642 ==============================
7644 Normally, dates are interpreted using the rules of the current time
7645 zone, which in turn are specified by the `TZ' environment variable, or
7646 by a system default if `TZ' is not set. To specify a different set of
7647 default time zone rules that apply just to one date, start the date
7648 with a string of the form `TZ="RULE"'. The two quote characters (`"')
7649 must be present in the date, and any quotes or backslashes within RULE
7650 must be escaped by a backslash.
7652 For example, with the GNU `date' command you can answer the question
7653 "What time is it in New York when a Paris clock shows 6:30am on October
7654 31, 2004?" by using a date beginning with `TZ="Europe/Paris"' as shown
7655 in the following shell transcript:
7657 $ export TZ="America/New_York"
7658 $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
7659 Sun Oct 31 01:30:00 EDT 2004
7661 In this example, the `--date' operand begins with its own `TZ'
7662 setting, so the rest of that operand is processed according to
7663 `Europe/Paris' rules, treating the string `2004-10-31 06:30' as if it
7664 were in Paris. However, since the output of the `date' command is
7665 processed according to the overall time zone rules, it uses New York
7666 time. (Paris was normally six hours ahead of New York in 2004, but
7667 this example refers to a brief Halloween period when the gap was five
7670 A `TZ' value is a rule that typically names a location in the `tz'
7671 database (http://www.twinsun.com/tz/tz-link.htm). A recent catalog of
7672 location names appears in the TWiki Date and Time Gateway
7673 (http://twiki.org/cgi-bin/xtra/tzdate). A few non-GNU hosts require a
7674 colon before a location name in a `TZ' setting, e.g.,
7675 `TZ=":America/New_York"'.
7677 The `tz' database includes a wide variety of locations ranging from
7678 `Arctic/Longyearbyen' to `Antarctica/South_Pole', but if you are at sea
7679 and have your own private time zone, or if you are using a non-GNU host
7680 that does not support the `tz' database, you may need to use a POSIX
7681 rule instead. Simple POSIX rules like `UTC0' specify a time zone
7682 without daylight saving time; other rules can specify simple daylight
7683 saving regimes. *Note Specifying the Time Zone with `TZ': (libc)TZ
7687 File: tar.info, Node: Authors of get_date, Prev: Specifying time zone rules, Up: Date input formats
7689 7.10 Authors of `get_date'
7690 ==========================
7692 `get_date' was originally implemented by Steven M. Bellovin
7693 (<smb@research.att.com>) while at the University of North Carolina at
7694 Chapel Hill. The code was later tweaked by a couple of people on
7695 Usenet, then completely overhauled by Rich $alz (<rsalz@bbn.com>) and
7696 Jim Berets (<jberets@bbn.com>) in August, 1990. Various revisions for
7697 the GNU system were made by David MacKenzie, Jim Meyering, Paul Eggert
7700 This chapter was originally produced by Franc,ois Pinard
7701 (<pinard@iro.umontreal.ca>) from the `getdate.y' source code, and then
7702 edited by K. Berry (<kb@cs.umb.edu>).
projects / tar / blob