1 This is tar.info, produced by makeinfo version 4.13 from tar.texi.
3 This manual is for GNU `tar' (version 1.28, 22 July 2014), which
4 creates and extracts files from archives.
6 Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2013 Free Software
9 Permission is granted to copy, distribute and/or modify this
10 document under the terms of the GNU Free Documentation License,
11 Version 1.3 or any later version published by the Free Software
12 Foundation; with the Invariant Sections being "GNU General Public
13 License", with the Front-Cover Texts being "A GNU Manual", and
14 with the Back-Cover Texts as in (a) below. A copy of the license
15 is included in the section entitled "GNU Free Documentation
18 (a) The FSF's Back-Cover Text is: "You have the freedom to copy
19 and modify this GNU manual."
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.28, 22 July 2014), which
38 creates and extracts files from archives.
40 Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2013 Free Software
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.3 or any later version published by the Free Software
46 Foundation; with the Invariant Sections being "GNU General Public
47 License", with the Front-Cover Texts being "A GNU Manual", and
48 with the Back-Cover Texts as in (a) below. A copy of the license
49 is included in the section entitled "GNU Free Documentation
52 (a) The FSF's Back-Cover Text is: "You have the freedom to copy
53 and modify this GNU manual."
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::
69 * Reliability and security::
74 * Configuring Help Summary::
75 * Fixing Snapshot Files::
78 * Free Software Needs Free Documentation::
79 * GNU Free Documentation License::
80 * Index of Command Line Options::
83 --- The Detailed Node Listing ---
87 * Book Contents:: What this Book Contains
88 * Definitions:: Some Definitions
89 * What tar Does:: What `tar' Does
90 * Naming tar Archives:: How `tar' Archives are Named
91 * Authors:: GNU `tar' Authors
92 * Reports:: Reporting bugs or suggestions
94 Tutorial Introduction to `tar'
97 * stylistic conventions::
98 * basic tar options:: Basic `tar' Operations and Options
99 * frequent operations::
100 * Two Frequent Options::
101 * create:: How to Create Archives
102 * list:: How to List Archives
103 * extract:: How to Extract Members from an Archive
106 Two Frequently Used Options
112 How to Create Archives
114 * prepare for examples::
115 * Creating the archive::
124 How to Extract Members from an Archive
126 * extracting archives::
129 * extracting untrusted archives::
135 * using tar options::
145 The Three Option Styles
147 * Long Options:: Long Option Style
148 * Short Options:: Short Option Style
149 * Old Options:: Old Option Style
150 * Mixing:: Mixing Option Styles
154 * Operation Summary::
156 * Short Option Summary::
168 Advanced GNU `tar' Operations
177 How to Add Files to Existing Archives: `--append'
179 * appending files:: Appending Files to an Archive
186 Options Used by `--create'
188 * override:: Overriding File Metadata.
189 * Ignore Failed Read::
191 Options Used by `--extract'
193 * Reading:: Options to Help Read Archives
194 * Writing:: Changing How `tar' Writes Files
195 * Scarce:: Coping with Scarce Resources
197 Options to Help Read Archives
199 * read full records::
202 Changing How `tar' Writes Files
204 * Dealing with Old Files::
205 * Overwrite Old Files::
210 * Data Modification Times::
211 * Setting Access Permissions::
212 * Directory Modification Times and Permissions::
213 * Writing to Standard Output::
214 * Writing to an External Program::
217 Coping with Scarce Resources
222 Performing Backups and Restoring Files
224 * Full Dumps:: Using `tar' to Perform Full Dumps
225 * Incremental Dumps:: Using `tar' to Perform Incremental Dumps
226 * Backup Levels:: Levels of Backups
227 * Backup Parameters:: Setting Parameters for Backups and Restoration
228 * Scripted Backups:: Using the Backup Scripts
229 * Scripted Restoration:: Using the Restore Script
231 Setting Parameters for Backups and Restoration
233 * General-Purpose Variables::
234 * Magnetic Tape Control::
236 * backup-specs example:: An Example Text of `Backup-specs'
238 Choosing Files and Names for `tar'
240 * file:: Choosing the Archive's Name
241 * Selecting Archive Members::
242 * files:: Reading Names from a File
243 * exclude:: Excluding Some Files
244 * wildcards:: Wildcards Patterns and Matching
245 * quoting styles:: Ways of Quoting Special Characters in Names
246 * transform:: Modifying File and Member Names
247 * after:: Operating Only on New Files
248 * recurse:: Descending into Directories
249 * one:: Crossing File System Boundaries
251 Reading Names from a File
257 * problems with exclude::
259 Wildcards Patterns and Matching
261 * controlling pattern-matching::
263 Crossing File System Boundaries
265 * directory:: Changing Directory
266 * absolute:: Absolute File Names
270 * General date syntax:: Common rules.
271 * Calendar date items:: 19 Dec 1994.
272 * Time of day items:: 9:20pm.
273 * Time zone items:: EST, PDT, GMT.
274 * Day of week items:: Monday and others.
275 * Relative items in date strings:: next tuesday, 2 years ago.
276 * Pure numbers in date strings:: 19931219, 1440.
277 * Seconds since the Epoch:: @1078100502.
278 * Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
279 * Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al.
281 Controlling the Archive Format
283 * Compression:: Using Less Space through Compression
284 * Attributes:: Handling File Attributes
285 * Portability:: Making `tar' Archives More Portable
286 * cpio:: Comparison of `tar' and `cpio'
288 Using Less Space through Compression
290 * gzip:: Creating and Reading Compressed Archives
291 * sparse:: Archiving Sparse Files
293 Creating and Reading Compressed Archives
295 * lbzip2:: Using lbzip2 with GNU `tar'.
297 Making `tar' Archives More Portable
299 * Portable Names:: Portable Names
300 * dereference:: Symbolic Links
301 * hard links:: Hard Links
302 * old:: Old V7 Archives
303 * ustar:: Ustar Archives
304 * gnu:: GNU and old GNU format archives.
305 * posix:: POSIX archives
306 * Checksumming:: Checksumming Problems
307 * Large or Negative Values:: Large files, negative time stamps, etc.
308 * Other Tars:: How to Extract GNU-Specific Data Using
309 Other `tar' Implementations
311 GNU `tar' and POSIX `tar'
313 * PAX keywords:: Controlling Extended Header Keywords.
315 How to Extract GNU-Specific Data Using Other `tar' Implementations
317 * Split Recovery:: Members Split Between Volumes
318 * Sparse Recovery:: Sparse Members
320 Tapes and Other Archive Media
322 * Device:: Device selection and switching
323 * Remote Tape Server::
324 * Common Problems and Solutions::
325 * Blocking:: Blocking
326 * Many:: Many archives on one tape
327 * Using Multiple Tapes:: Using Multiple Tapes
328 * label:: Including a Label in the Archive
334 * Format Variations:: Format Variations
335 * Blocking Factor:: The Blocking Factor of an Archive
337 Many Archives on One Tape
339 * Tape Positioning:: Tape Positions and Tape Marks
340 * mt:: The `mt' Utility
344 * Multi-Volume Archives:: Archives Longer than One Tape or Disk
345 * Tape Files:: Tape Files
346 * Tarcat:: Concatenate Volumes into a Single Archive
351 * Standard:: Basic Tar Format
352 * Extensions:: GNU Extensions to the Archive Format
353 * Sparse Formats:: Storing Sparse Files
360 * PAX 0:: PAX Format, Versions 0.0 and 0.1
361 * PAX 1:: PAX Format, Version 1.0
365 * Generate Mode:: File Generation Mode.
366 * Status Mode:: File Status Mode.
367 * Exec Mode:: Synchronous Execution mode.
371 * GNU Free Documentation License:: License for copying this manual
374 File: tar.info, Node: Introduction, Next: Tutorial, Prev: Top, Up: Top
379 GNU `tar' creates and manipulates "archives" which are actually
380 collections of many other files; the program provides users with an
381 organized and systematic method for controlling a large amount of data.
382 The name "tar" originally came from the phrase "Tape ARchive", but
383 archives need not (and these days, typically do not) reside on tapes.
387 * Book Contents:: What this Book Contains
388 * Definitions:: Some Definitions
389 * What tar Does:: What `tar' Does
390 * Naming tar Archives:: How `tar' Archives are Named
391 * Authors:: GNU `tar' Authors
392 * Reports:: Reporting bugs or suggestions
395 File: tar.info, Node: Book Contents, Next: Definitions, Up: Introduction
397 1.1 What this Book Contains
398 ===========================
400 The first part of this chapter introduces you to various terms that will
401 recur throughout the book. It also tells you who has worked on GNU
402 `tar' and its documentation, and where you should send bug reports or
405 The second chapter is a tutorial (*note Tutorial::) which provides a
406 gentle introduction for people who are new to using `tar'. It is meant
407 to be self-contained, not requiring any reading from subsequent
408 chapters to make sense. It moves from topic to topic in a logical,
409 progressive order, building on information already explained.
411 Although the tutorial is paced and structured to allow beginners to
412 learn how to use `tar', it is not intended solely for beginners. The
413 tutorial explains how to use the three most frequently used operations
414 (`create', `list', and `extract') as well as two frequently used
415 options (`file' and `verbose'). The other chapters do not refer to the
416 tutorial frequently; however, if a section discusses something which is
417 a complex variant of a basic concept, there may be a cross-reference to
418 that basic concept. (The entire book, including the tutorial, assumes
419 that the reader understands some basic concepts of using a Unix-type
420 operating system; *note Tutorial::.)
422 The third chapter presents the remaining five operations, and
423 information about using `tar' options and option syntax.
425 The other chapters are meant to be used as a reference. Each chapter
426 presents everything that needs to be said about a specific topic.
428 One of the chapters (*note Date input formats::) exists in its
429 entirety in other GNU manuals, and is mostly self-contained. In
430 addition, one section of this manual (*note Standard::) contains a big
431 quote which is taken directly from `tar' sources.
433 In general, we give both long and short (abbreviated) option names
434 at least once in each section where the relevant option is covered, so
435 that novice readers will become familiar with both styles. (A few
436 options have no short versions, and the relevant sections will indicate
440 File: tar.info, Node: Definitions, Next: What tar Does, Prev: Book Contents, Up: Introduction
445 The `tar' program is used to create and manipulate `tar' archives. An
446 "archive" is a single file which contains the contents of many files,
447 while still identifying the names of the files, their owner(s), and so
448 forth. (In addition, archives record access permissions, user and
449 group, size in bytes, and data modification time. Some archives also
450 record the file names in each archived directory, as well as other file
451 and directory information.) You can use `tar' to "create" a new
452 archive in a specified directory.
454 The files inside an archive are called "members". Within this
455 manual, we use the term "file" to refer only to files accessible in the
456 normal ways (by `ls', `cat', and so forth), and the term "member" to
457 refer only to the members of an archive. Similarly, a "file name" is
458 the name of a file, as it resides in the file system, and a "member
459 name" is the name of an archive member within the archive.
461 The term "extraction" refers to the process of copying an archive
462 member (or multiple members) into a file in the file system. Extracting
463 all the members of an archive is often called "extracting the archive".
464 The term "unpack" can also be used to refer to the extraction of many
465 or all the members of an archive. Extracting an archive does not
466 destroy the archive's structure, just as creating an archive does not
467 destroy the copies of the files that exist outside of the archive. You
468 may also "list" the members in a given archive (this is often thought
469 of as "printing" them to the standard output, or the command line), or
470 "append" members to a pre-existing archive. All of these operations
471 can be performed using `tar'.
474 File: tar.info, Node: What tar Does, Next: Naming tar Archives, Prev: Definitions, Up: Introduction
479 The `tar' program provides the ability to create `tar' archives, as
480 well as various other kinds of manipulation. For example, you can use
481 `tar' on previously created archives to extract files, to store
482 additional files, or to update or list files which were already stored.
484 Initially, `tar' archives were used to store files conveniently on
485 magnetic tape. The name `tar' comes from this use; it stands for
486 `t'ape `ar'chiver. Despite the utility's name, `tar' can direct its
487 output to available devices, files, or other programs (using pipes).
488 `tar' may even access remote devices or files (as archives).
490 You can use `tar' archives in many ways. We want to stress a few of
491 them: storage, backup, and transportation.
494 Often, `tar' archives are used to store related files for
495 convenient file transfer over a network. For example, the GNU
496 Project distributes its software bundled into `tar' archives, so
497 that all the files relating to a particular program (or set of
498 related programs) can be transferred as a single unit.
500 A magnetic tape can store several files in sequence. However, the
501 tape has no names for these files; it only knows their relative
502 position on the tape. One way to store several files on one tape
503 and retain their names is by creating a `tar' archive. Even when
504 the basic transfer mechanism can keep track of names, as FTP can,
505 the nuisance of handling multiple files, directories, and multiple
506 links makes `tar' archives useful.
508 Archive files are also used for long-term storage. You can think
509 of this as transportation from the present into the future. (It
510 is a science-fiction idiom that you can move through time as well
511 as in space; the idea here is that `tar' can be used to move
512 archives in all dimensions, even time!)
515 Because the archive created by `tar' is capable of preserving file
516 information and directory structure, `tar' is commonly used for
517 performing full and incremental backups of disks. A backup puts a
518 collection of files (possibly pertaining to many users and
519 projects) together on a disk or a tape. This guards against
520 accidental destruction of the information in those files. GNU
521 `tar' has special features that allow it to be used to make
522 incremental and full dumps of all the files in a file system.
525 You can create an archive on one system, transfer it to another
526 system, and extract the contents there. This allows you to
527 transport a group of files from one system to another.
530 File: tar.info, Node: Naming tar Archives, Next: Authors, Prev: What tar Does, Up: Introduction
532 1.4 How `tar' Archives are Named
533 ================================
535 Conventionally, `tar' archives are given names ending with `.tar'.
536 This is not necessary for `tar' to operate properly, but this manual
537 follows that convention in order to accustom readers to it and to make
540 Often, people refer to `tar' archives as "`tar' files," and archive
541 members as "files" or "entries". For people familiar with the
542 operation of `tar', this causes no difficulty. However, in this
543 manual, we consistently refer to "archives" and "archive members" to
544 make learning to use `tar' easier for novice users.
547 File: tar.info, Node: Authors, Next: Reports, Prev: Naming tar Archives, Up: Introduction
549 1.5 GNU `tar' Authors
550 =====================
552 GNU `tar' was originally written by John Gilmore, and modified by many
553 people. The GNU enhancements were written by Jay Fenlason, then Joy
554 Kendall, and the whole package has been further maintained by Thomas
555 Bushnell, n/BSG, Franc,ois Pinard, Paul Eggert, and finally Sergey
556 Poznyakoff with the help of numerous and kind users.
558 We wish to stress that `tar' is a collective work, and owes much to
559 all those people who reported problems, offered solutions and other
560 insights, or shared their thoughts and suggestions. An impressive, yet
561 partial list of those contributors can be found in the `THANKS' file
562 from the GNU `tar' distribution.
564 Jay Fenlason put together a draft of a GNU `tar' manual, borrowing
565 notes from the original man page from John Gilmore. This was withdrawn
566 in version 1.11. Thomas Bushnell, n/BSG and Amy Gorin worked on a
567 tutorial and manual for GNU `tar'. Franc,ois Pinard put version 1.11.8
568 of the manual together by taking information from all these sources and
569 merging them. Melissa Weisshaus finally edited and redesigned the book
570 to create version 1.12. The book for versions from 1.14 up to 1.28
571 were edited by the current maintainer, Sergey Poznyakoff.
573 For version 1.12, Daniel Hagerty contributed a great deal of
574 technical consulting. In particular, he is the primary author of *note
577 In July, 2003 GNU `tar' was put on CVS at savannah.gnu.org (see
578 `http://savannah.gnu.org/projects/tar'), and active development and
579 maintenance work has started again. Currently GNU `tar' is being
580 maintained by Paul Eggert, Sergey Poznyakoff and Jeff Bailey.
582 Support for POSIX archives was added by Sergey Poznyakoff.
585 File: tar.info, Node: Reports, Prev: Authors, Up: Introduction
587 1.6 Reporting bugs or suggestions
588 =================================
590 If you find problems or have suggestions about this program or manual,
591 please report them to `bug-tar@gnu.org'.
593 When reporting a bug, please be sure to include as much detail as
594 possible, in order to reproduce it.
597 File: tar.info, Node: Tutorial, Next: tar invocation, Prev: Introduction, Up: Top
599 2 Tutorial Introduction to `tar'
600 ********************************
602 This chapter guides you through some basic examples of three `tar'
603 operations: `--create', `--list', and `--extract'. If you already know
604 how to use some other version of `tar', then you may not need to read
605 this chapter. This chapter omits most complicated details about how
611 * stylistic conventions::
612 * basic tar options:: Basic `tar' Operations and Options
613 * frequent operations::
614 * Two Frequent Options::
615 * create:: How to Create Archives
616 * list:: How to List Archives
617 * extract:: How to Extract Members from an Archive
621 File: tar.info, Node: assumptions, Next: stylistic conventions, Up: Tutorial
623 2.1 Assumptions this Tutorial Makes
624 ===================================
626 This chapter is paced to allow beginners to learn about `tar' slowly.
627 At the same time, we will try to cover all the basic aspects of these
628 three operations. In order to accomplish both of these tasks, we have
629 made certain assumptions about your knowledge before reading this
630 manual, and the hardware you will be using:
632 * Before you start to work through this tutorial, you should
633 understand what the terms "archive" and "archive member" mean
634 (*note Definitions::). In addition, you should understand
635 something about how Unix-type operating systems work, and you
636 should know how to use some basic utilities. For example, you
637 should know how to create, list, copy, rename, edit, and delete
638 files and directories; how to change between directories; and how
639 to figure out where you are in the file system. You should have
640 some basic understanding of directory structure and how files are
641 named according to which directory they are in. You should
642 understand concepts such as standard output and standard input,
643 what various definitions of the term `argument' mean, and the
644 differences between relative and absolute file names.
646 * This manual assumes that you are working from your own home
647 directory (unless we state otherwise). In this tutorial, you will
648 create a directory to practice `tar' commands in. When we show
649 file names, we will assume that those names are relative to your
650 home directory. For example, my home directory is
651 `/home/fsf/melissa'. All of my examples are in a subdirectory of
652 the directory named by that file name; the subdirectory is called
655 * In general, we show examples of archives which exist on (or can be
656 written to, or worked with from) a directory on a hard disk. In
657 most cases, you could write those archives to, or work with them
658 on any other device, such as a tape drive. However, some of the
659 later examples in the tutorial and next chapter will not work on
660 tape drives. Additionally, working with tapes is much more
661 complicated than working with hard disks. For these reasons, the
662 tutorial does not cover working with tape drives. *Note Media::,
663 for complete information on using `tar' archives with tape drives.
667 File: tar.info, Node: stylistic conventions, Next: basic tar options, Prev: assumptions, Up: Tutorial
669 2.2 Stylistic Conventions
670 =========================
672 In the examples, `$' represents a typical shell prompt. It precedes
673 lines you should type; to make this more clear, those lines are shown
674 in `this font', as opposed to lines which represent the computer's
675 response; those lines are shown in `this font', or sometimes `like
679 File: tar.info, Node: basic tar options, Next: frequent operations, Prev: stylistic conventions, Up: Tutorial
681 2.3 Basic `tar' Operations and Options
682 ======================================
684 `tar' can take a wide variety of arguments which specify and define the
685 actions it will have on the particular set of files or the archive.
686 The main types of arguments to `tar' fall into one of two classes:
687 operations, and options.
689 Some arguments fall into a class called "operations"; exactly one of
690 these is both allowed and required for any instance of using `tar'; you
691 may _not_ specify more than one. People sometimes speak of "operating
692 modes". You are in a particular operating mode when you have specified
693 the operation which specifies it; there are eight operations in total,
694 and thus there are eight operating modes.
696 The other arguments fall into the class known as "options". You are
697 not required to specify any options, and you are allowed to specify more
698 than one at a time (depending on the way you are using `tar' at that
699 time). Some options are used so frequently, and are so useful for
700 helping you type commands more carefully that they are effectively
701 "required". We will discuss them in this chapter.
703 You can write most of the `tar' operations and options in any of
704 three forms: long (mnemonic) form, short form, and old style. Some of
705 the operations and options have no short or "old" forms; however, the
706 operations and options which we will cover in this tutorial have
707 corresponding abbreviations. We will indicate those abbreviations
708 appropriately to get you used to seeing them. Note, that the "old
709 style" option forms exist in GNU `tar' for compatibility with Unix
710 `tar'. In this book we present a full discussion of this way of
711 writing options and operations (*note Old Options::), and we discuss
712 the other two styles of writing options (*Note Long Options::, and
713 *note Short Options::).
715 In the examples and in the text of this tutorial, we usually use the
716 long forms of operations and options; but the "short" forms produce the
717 same result and can make typing long `tar' commands easier. For
718 example, instead of typing
720 tar --create --verbose --file=afiles.tar apple angst aspic
723 tar -c -v -f afiles.tar apple angst aspic
726 tar -cvf afiles.tar apple angst aspic
728 For more information on option syntax, see *note Advanced tar::. In
729 discussions in the text, when we name an option by its long form, we
730 also give the corresponding short option in parentheses.
732 The term, "option", can be confusing at times, since "operations"
733 are often lumped in with the actual, _optional_ "options" in certain
734 general class statements. For example, we just talked about "short and
735 long forms of options and operations". However, experienced `tar'
736 users often refer to these by shorthand terms such as, "short and long
737 options". This term assumes that the "operations" are included, also.
738 Context will help you determine which definition of "options" to use.
740 Similarly, the term "command" can be confusing, as it is often used
741 in two different ways. People sometimes refer to `tar' "commands". A
742 `tar' "command" is the entire command line of user input which tells
743 `tar' what to do -- including the operation, options, and any arguments
744 (file names, pipes, other commands, etc.). However, you will also
745 sometimes hear the term "the `tar' command". When the word "command"
746 is used specifically like this, a person is usually referring to the
747 `tar' _operation_, not the whole line. Again, use context to figure
748 out which of the meanings the speaker intends.
751 File: tar.info, Node: frequent operations, Next: Two Frequent Options, Prev: basic tar options, Up: Tutorial
753 2.4 The Three Most Frequently Used Operations
754 =============================================
756 Here are the three most frequently used operations (both short and long
757 forms), as well as a brief description of their meanings. The rest of
758 this chapter will cover how to use these operations in detail. We will
759 present the rest of the operations in the next chapter.
763 Create a new `tar' archive.
767 List the contents of an archive.
771 Extract one or more members from an archive.
774 File: tar.info, Node: Two Frequent Options, Next: create, Prev: frequent operations, Up: Tutorial
776 2.5 Two Frequently Used Options
777 ===============================
779 To understand how to run `tar' in the three operating modes listed
780 previously, you also need to understand how to use two of the options to
781 `tar': `--file' (which takes an archive file as an argument) and
782 `--verbose'. (You are usually not _required_ to specify either of
783 these options when you run `tar', but they can be very useful in making
784 things more clear and helping you avoid errors.)
793 File: tar.info, Node: file tutorial, Next: verbose tutorial, Up: Two Frequent Options
798 `--file=ARCHIVE-NAME'
800 Specify the name of an archive file.
802 You can specify an argument for the `--file=ARCHIVE-NAME' (`-f
803 ARCHIVE-NAME') option whenever you use `tar'; this option determines
804 the name of the archive file that `tar' will work on.
806 If you don't specify this argument, then `tar' will examine the
807 environment variable `TAPE'. If it is set, its value will be used as
808 the archive name. Otherwise, `tar' will use the default archive,
809 determined at compile time. Usually it is standard output or some
810 physical tape drive attached to your machine (you can verify what the
811 default is by running `tar --show-defaults', *note defaults::). If
812 there is no tape drive attached, or the default is not meaningful, then
813 `tar' will print an error message. The error message might look
814 roughly like one of the following:
816 tar: can't open /dev/rmt8 : No such device or address
817 tar: can't open /dev/rsmt0 : I/O error
819 To avoid confusion, we recommend that you always specify an archive file
820 name by using `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') when writing
821 your `tar' commands. For more information on using the
822 `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option, see *note file::.
825 File: tar.info, Node: verbose tutorial, Next: help tutorial, Prev: file tutorial, Up: Two Frequent Options
827 The `--verbose' Option
828 ----------------------
832 Show the files being worked on as `tar' is running.
834 `--verbose' (`-v') shows details about the results of running `tar'.
835 This can be especially useful when the results might not be obvious.
836 For example, if you want to see the progress of `tar' as it writes
837 files into the archive, you can use the `--verbose' option. In the
838 beginning, you may find it useful to use `--verbose' at all times; when
839 you are more accustomed to `tar', you will likely want to use it at
840 certain times but not at others. We will use `--verbose' at times to
841 help make something clear, and we will give many examples both using
842 and not using `--verbose' to show the differences.
844 Each instance of `--verbose' on the command line increases the
845 verbosity level by one, so if you need more details on the output,
848 When reading archives (`--list', `--extract', `--diff'), `tar' by
849 default prints only the names of the members being extracted. Using
850 `--verbose' will show a full, `ls' style member listing.
852 In contrast, when writing archives (`--create', `--append',
853 `--update'), `tar' does not print file names by default. So, a single
854 `--verbose' option shows the file names being added to the archive,
855 while two `--verbose' options enable the full listing.
857 For example, to create an archive in verbose mode:
859 $ tar -cvf afiles.tar apple angst aspic
864 Creating the same archive with the verbosity level 2 could give:
866 $ tar -cvvf afiles.tar apple angst aspic
867 -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
868 -rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst
869 -rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic
871 This works equally well using short or long forms of options. Using
872 long forms, you would simply write out the mnemonic form of the option
875 $ tar --create --verbose --verbose ...
877 Note that you must double the hyphens properly each time.
879 Later in the tutorial, we will give examples using
880 `--verbose --verbose'.
882 The full output consists of six fields:
884 * File type and permissions in symbolic form. These are displayed
885 in the same format as the first column of `ls -l' output (*note
886 format=verbose: (fileutils)What information is listed.).
888 * Owner name and group separated by a slash character. If these
889 data are not available (for example, when listing a `v7' format
890 archive), numeric ID values are printed instead.
892 * Size of the file, in bytes.
894 * File modification date in ISO 8601 format.
896 * File modification time.
898 * File name. If the name contains any special characters (white
899 space, newlines, etc.) these are displayed in an unambiguous form
900 using so called "quoting style". For the detailed discussion of
901 available styles and on how to use them, see *note quoting
904 Depending on the file type, the name can be followed by some
905 additional information, described in the following table:
908 The file or archive member is a "symbolic link" and LINK-NAME
909 is the name of file it links to.
912 The file or archive member is a "hard link" and LINK-NAME is
913 the name of file it links to.
916 The archive member is an old GNU format long link. You will
917 normally not encounter this.
920 The archive member is an old GNU format long name. You will
921 normally not encounter this.
924 The archive member is a GNU "volume header" (*note Tape
927 `--Continued at byte N--'
928 Encountered only at the beginning of a multi-volume archive
929 (*note Using Multiple Tapes::). This archive member is a
930 continuation from the previous volume. The number N gives the
931 offset where the original file was split.
933 `unknown file type C'
934 An archive member of unknown type. C is the type character
935 from the archive header. If you encounter such a message, it
936 means that either your archive contains proprietary member
937 types GNU `tar' is not able to handle, or the archive is
941 For example, here is an archive listing containing most of the
942 special suffixes explained above:
944 V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header--
945 -rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at byte 32456--
946 -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
947 lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple
948 -rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
949 hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues
953 File: tar.info, Node: help tutorial, Prev: verbose tutorial, Up: Two Frequent Options
955 Getting Help: Using the `--help' Option
956 ---------------------------------------
959 The `--help' option to `tar' prints out a very brief list of all
960 operations and option available for the current version of `tar'
961 available on your system.
964 File: tar.info, Node: create, Next: list, Prev: Two Frequent Options, Up: Tutorial
966 2.6 How to Create Archives
967 ==========================
969 _(This message will disappear, once this node revised.)_
971 One of the basic operations of `tar' is `--create' (`-c'), which you
972 use to create a `tar' archive. We will explain `--create' first
973 because, in order to learn about the other operations, you will find it
974 useful to have an archive available to practice on.
976 To make this easier, in this section you will first create a
977 directory containing three files. Then, we will show you how to create
978 an _archive_ (inside the new directory). Both the directory, and the
979 archive are specifically for you to practice on. The rest of this
980 chapter and the next chapter will show many examples using this
981 directory and the files you will create: some of those files may be
982 other directories and other archives.
984 The three files you will archive in this example are called `blues',
985 `folk', and `jazz'. The archive is called `collection.tar'.
987 This section will proceed slowly, detailing how to use `--create' in
988 `verbose' mode, and showing examples using both short and long forms.
989 In the rest of the tutorial, and in the examples in the next chapter,
990 we will proceed at a slightly quicker pace. This section moves more
991 slowly to allow beginning users to understand how `tar' works.
995 * prepare for examples::
996 * Creating the archive::
1002 File: tar.info, Node: prepare for examples, Next: Creating the archive, Up: create
1004 2.6.1 Preparing a Practice Directory for Examples
1005 -------------------------------------------------
1007 To follow along with this and future examples, create a new directory
1008 called `practice' containing files called `blues', `folk' and `jazz'.
1009 The files can contain any information you like: ideally, they should
1010 contain information which relates to their names, and be of different
1011 lengths. Our examples assume that `practice' is a subdirectory of your
1014 Now `cd' to the directory named `practice'; `practice' is now your
1015 "working directory". (_Please note_: Although the full file name of
1016 this directory is `/HOMEDIR/practice', in our examples we will refer to
1017 this directory as `practice'; the HOMEDIR is presumed.)
1019 In general, you should check that the files to be archived exist
1020 where you think they do (in the working directory) by running `ls'.
1021 Because you just created the directory and the files and have changed to
1022 that directory, you probably don't need to do that this time.
1024 It is very important to make sure there isn't already a file in the
1025 working directory with the archive name you intend to use (in this case,
1026 `collection.tar'), or that you don't care about its contents. Whenever
1027 you use `create', `tar' will erase the current contents of the file
1028 named by `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') if it exists. `tar'
1029 will not tell you if you are about to overwrite an archive unless you
1030 specify an option which does this (*note backup::, for the information
1031 on how to do so). To add files to an existing archive, you need to use
1032 a different option, such as `--append' (`-r'); see *note append:: for
1033 information on how to do this.
1036 File: tar.info, Node: Creating the archive, Next: create verbose, Prev: prepare for examples, Up: create
1038 2.6.2 Creating the Archive
1039 --------------------------
1041 To place the files `blues', `folk', and `jazz' into an archive named
1042 `collection.tar', use the following command:
1044 $ tar --create --file=collection.tar blues folk jazz
1046 The order of the arguments is not very important, _when using long
1047 option forms_. You could also say:
1049 $ tar blues --create folk --file=collection.tar jazz
1051 However, you can see that this order is harder to understand; this is
1052 why we will list the arguments in the order that makes the commands
1053 easiest to understand (and we encourage you to do the same when you use
1054 `tar', to avoid errors).
1056 Note that the sequence `--file=collection.tar' is considered to be
1057 _one_ argument. If you substituted any other string of characters for
1058 `collection.tar', then that string would become the name of the
1059 archive file you create.
1061 The order of the options becomes more important when you begin to use
1062 short forms. With short forms, if you type commands in the wrong order
1063 (even if you type them correctly in all other ways), you may end up with
1064 results you don't expect. For this reason, it is a good idea to get
1065 into the habit of typing options in the order that makes inherent sense.
1066 *Note short create::, for more information on this.
1068 In this example, you type the command as shown above: `--create' is
1069 the operation which creates the new archive (`collection.tar'), and
1070 `--file' is the option which lets you give it the name you chose. The
1071 files, `blues', `folk', and `jazz', are now members of the archive,
1072 `collection.tar' (they are "file name arguments" to the `--create'
1073 operation. *Note Choosing::, for the detailed discussion on these.)
1074 Now that they are in the archive, they are called _archive members_,
1075 not files. (*note members: Definitions.).
1077 When you create an archive, you _must_ specify which files you want
1078 placed in the archive. If you do not specify any archive members, GNU
1079 `tar' will complain.
1081 If you now list the contents of the working directory (`ls'), you
1082 will find the archive file listed as well as the files you saw
1085 blues folk jazz collection.tar
1087 Creating the archive `collection.tar' did not destroy the copies of the
1088 files in the directory.
1090 Keep in mind that if you don't indicate an operation, `tar' will not
1091 run and will prompt you for one. If you don't name any files, `tar'
1092 will complain. You must have write access to the working directory, or
1093 else you will not be able to create an archive in that directory.
1095 _Caution_: Do not attempt to use `--create' (`-c') to add files to
1096 an existing archive; it will delete the archive and write a new one.
1097 Use `--append' (`-r') instead. *Note append::.
1100 File: tar.info, Node: create verbose, Next: short create, Prev: Creating the archive, Up: create
1102 2.6.3 Running `--create' with `--verbose'
1103 -----------------------------------------
1105 If you include the `--verbose' (`-v') option on the command line, `tar'
1106 will list the files it is acting on as it is working. In verbose mode,
1107 the `create' example above would appear as:
1109 $ tar --create --verbose --file=collection.tar blues folk jazz
1114 This example is just like the example we showed which did not use
1115 `--verbose', except that `tar' generated the remaining lines.
1117 In the rest of the examples in this chapter, we will frequently use
1118 `verbose' mode so we can show actions or `tar' responses that you would
1119 otherwise not see, and which are important for you to understand.
1122 File: tar.info, Node: short create, Next: create dir, Prev: create verbose, Up: create
1124 2.6.4 Short Forms with `create'
1125 -------------------------------
1127 As we said before, the `--create' (`-c') operation is one of the most
1128 basic uses of `tar', and you will use it countless times. Eventually,
1129 you will probably want to use abbreviated (or "short") forms of
1130 options. A full discussion of the three different forms that options
1131 can take appears in *note Styles::; for now, here is what the previous
1132 example (including the `--verbose' (`-v') option) looks like using
1135 $ tar -cvf collection.tar blues folk jazz
1140 As you can see, the system responds the same no matter whether you use
1141 long or short option forms.
1143 One difference between using short and long option forms is that,
1144 although the exact placement of arguments following options is no more
1145 specific when using short forms, it is easier to become confused and
1146 make a mistake when using short forms. For example, suppose you
1147 attempted the above example in the following way:
1149 $ tar -cfv collection.tar blues folk jazz
1151 In this case, `tar' will make an archive file called `v', containing
1152 the files `blues', `folk', and `jazz', because the `v' is the closest
1153 "file name" to the `-f' option, and is thus taken to be the chosen
1154 archive file name. `tar' will try to add a file called
1155 `collection.tar' to the `v' archive file; if the file `collection.tar'
1156 did not already exist, `tar' will report an error indicating that this
1157 file does not exist. If the file `collection.tar' does already exist
1158 (e.g., from a previous command you may have run), then `tar' will add
1159 this file to the archive. Because the `-v' option did not get
1160 registered, `tar' will not run under `verbose' mode, and will not
1161 report its progress.
1163 The end result is that you may be quite confused about what happened,
1164 and possibly overwrite a file. To illustrate this further, we will show
1165 you how an example we showed previously would look using short forms.
1169 $ tar blues --create folk --file=collection.tar jazz
1171 is confusing as it is. When shown using short forms, however, it
1172 becomes much more so:
1174 $ tar blues -c folk -f collection.tar jazz
1176 It would be very easy to put the wrong string of characters immediately
1177 following the `-f', but doing that could sacrifice valuable data.
1179 For this reason, we recommend that you pay very careful attention to
1180 the order of options and placement of file and archive names,
1181 especially when using short option forms. Not having the option name
1182 written out mnemonically can affect how well you remember which option
1183 does what, and therefore where different names have to be placed.
1186 File: tar.info, Node: create dir, Prev: short create, Up: create
1188 2.6.5 Archiving Directories
1189 ---------------------------
1191 You can archive a directory by specifying its directory name as a file
1192 name argument to `tar'. The files in the directory will be archived
1193 relative to the working directory, and the directory will be re-created
1194 along with its contents when the archive is extracted.
1196 To archive a directory, first move to its superior directory. If you
1197 have followed the previous instructions in this tutorial, you should
1203 This will put you into the directory which contains `practice', i.e.,
1204 your home directory. Once in the superior directory, you can specify
1205 the subdirectory, `practice', as a file name argument. To store
1206 `practice' in the new archive file `music.tar', type:
1208 $ tar --create --verbose --file=music.tar practice
1210 `tar' should output:
1216 practice/collection.tar
1218 Note that the archive thus created is not in the subdirectory
1219 `practice', but rather in the current working directory--the directory
1220 from which `tar' was invoked. Before trying to archive a directory
1221 from its superior directory, you should make sure you have write access
1222 to the superior directory itself, not only the directory you are trying
1223 archive with `tar'. For example, you will probably not be able to
1224 store your home directory in an archive by invoking `tar' from the root
1225 directory; *Note absolute::. (Note also that `collection.tar', the
1226 original archive file, has itself been archived. `tar' will accept any
1227 file as a file to be archived, regardless of its content. When
1228 `music.tar' is extracted, the archive file `collection.tar' will be
1229 re-written into the file system).
1231 If you give `tar' a command such as
1233 $ tar --create --file=foo.tar .
1235 `tar' will report `tar: ./foo.tar is the archive; not dumped'. This
1236 happens because `tar' creates the archive `foo.tar' in the current
1237 directory before putting any files into it. Then, when `tar' attempts
1238 to add all the files in the directory `.' to the archive, it notices
1239 that the file `./foo.tar' is the same as the archive `foo.tar', and
1240 skips it. (It makes no sense to put an archive into itself.) GNU `tar'
1241 will continue in this case, and create the archive normally, except for
1242 the exclusion of that one file. (_Please note:_ Other implementations
1243 of `tar' may not be so clever; they will enter an infinite loop when
1244 this happens, so you should not depend on this behavior unless you are
1245 certain you are running GNU `tar'. In general, it is wise to always
1246 place the archive outside of the directory being dumped.)
1249 File: tar.info, Node: list, Next: extract, Prev: create, Up: Tutorial
1251 2.7 How to List Archives
1252 ========================
1254 Frequently, you will find yourself wanting to determine exactly what a
1255 particular archive contains. You can use the `--list' (`-t') operation
1256 to get the member names as they currently appear in the archive, as
1257 well as various attributes of the files at the time they were archived.
1258 For example, you can examine the archive `collection.tar' that you
1259 created in the last section with the command,
1261 $ tar --list --file=collection.tar
1263 The output of `tar' would then be:
1269 The archive `bfiles.tar' would list as follows:
1275 Be sure to use a `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option just
1276 as with `--create' (`-c') to specify the name of the archive.
1278 If you use the `--verbose' (`-v') option with `--list', then `tar'
1279 will print out a listing reminiscent of `ls -l', showing owner, file
1280 size, and so forth. This output is described in detail in *note
1281 verbose member listing::.
1283 If you had used `--verbose' (`-v') mode, the example above would
1286 $ tar --list --verbose --file=collection.tar folk
1287 -rw-r--r-- myself/user 62 1990-05-23 10:55 folk
1289 It is important to notice that the output of `tar --list --verbose'
1290 does not necessarily match that produced by `tar --create --verbose'
1291 while creating the archive. It is because GNU `tar', unless told
1292 explicitly not to do so, removes some directory prefixes from file
1293 names before storing them in the archive (*Note absolute::, for more
1294 information). In other words, in verbose mode GNU `tar' shows "file
1295 names" when creating an archive and "member names" when listing it.
1296 Consider this example:
1298 $ tar --create --verbose --file archive /etc/mail
1299 tar: Removing leading '/' from member names
1301 /etc/mail/sendmail.cf
1303 $ tar --test --file archive
1305 etc/mail/sendmail.cf
1308 This default behavior can sometimes be inconvenient. You can force
1309 GNU `tar' show member names when creating archive by supplying
1310 `--show-stored-names' option.
1312 `--show-stored-names'
1313 Print member (as opposed to _file_) names when creating the
1316 You can specify one or more individual member names as arguments when
1317 using `list'. In this case, `tar' will only list the names of members
1318 you identify. For example, `tar --list --file=afiles.tar apple' would
1321 Because `tar' preserves file names, these must be specified as they
1322 appear in the archive (i.e., relative to the directory from which the
1323 archive was created). Therefore, it is essential when specifying
1324 member names to `tar' that you give the exact member names. For
1325 example, `tar --list --file=bfiles.tar birds' would produce an error
1326 message something like `tar: birds: Not found in archive', because
1327 there is no member named `birds', only one named `./birds'. While the
1328 names `birds' and `./birds' name the same file, _member_ names by
1329 default are compared verbatim.
1331 However, `tar --list --file=bfiles.tar baboon' would respond with
1332 `baboon', because this exact member name is in the archive file
1333 `bfiles.tar'. If you are not sure of the exact file name, use
1334 "globbing patterns", for example:
1336 $ tar --list --file=bfiles.tar --wildcards '*b*'
1338 will list all members whose name contains `b'. *Note wildcards::, for
1339 a detailed discussion of globbing patterns and related `tar' command
1347 File: tar.info, Node: list dir, Up: list
1349 Listing the Contents of a Stored Directory
1350 ------------------------------------------
1352 To get information about the contents of an archived directory, use the
1353 directory name as a file name argument in conjunction with `--list'
1354 (`-t'). To find out file attributes, include the `--verbose' (`-v')
1357 For example, to find out about files in the directory `practice', in
1358 the archive file `music.tar', type:
1360 $ tar --list --verbose --file=music.tar practice
1364 drwxrwxrwx myself/user 0 1990-05-31 21:49 practice/
1365 -rw-r--r-- myself/user 42 1990-05-21 13:29 practice/blues
1366 -rw-r--r-- myself/user 62 1990-05-23 10:55 practice/folk
1367 -rw-r--r-- myself/user 40 1990-05-21 13:30 practice/jazz
1368 -rw-r--r-- myself/user 10240 1990-05-31 21:49 practice/collection.tar
1370 When you use a directory name as a file name argument, `tar' acts on
1371 all the files (including sub-directories) in that directory.
1374 File: tar.info, Node: extract, Next: going further, Prev: list, Up: Tutorial
1376 2.8 How to Extract Members from an Archive
1377 ==========================================
1379 Creating an archive is only half the job--there is no point in storing
1380 files in an archive if you can't retrieve them. The act of retrieving
1381 members from an archive so they can be used and manipulated as
1382 unarchived files again is called "extraction". To extract files from
1383 an archive, use the `--extract' (`--get' or `-x') operation. As with
1384 `--create', specify the name of the archive with `--file' (`-f')
1385 option. Extracting an archive does not modify the archive in any way;
1386 you can extract it multiple times if you want or need to.
1388 Using `--extract', you can extract an entire archive, or specific
1389 files. The files can be directories containing other files, or not. As
1390 with `--create' (`-c') and `--list' (`-t'), you may use the short or the
1391 long form of the operation without affecting the performance.
1395 * extracting archives::
1396 * extracting files::
1398 * extracting untrusted archives::
1399 * failing commands::
1402 File: tar.info, Node: extracting archives, Next: extracting files, Up: extract
1404 2.8.1 Extracting an Entire Archive
1405 ----------------------------------
1407 To extract an entire archive, specify the archive file name only, with
1408 no individual file names as arguments. For example,
1410 $ tar -xvf collection.tar
1414 -rw-r--r-- me/user 28 1996-10-18 16:31 jazz
1415 -rw-r--r-- me/user 21 1996-09-23 16:44 blues
1416 -rw-r--r-- me/user 20 1996-09-23 16:44 folk
1419 File: tar.info, Node: extracting files, Next: extract dir, Prev: extracting archives, Up: extract
1421 2.8.2 Extracting Specific Files
1422 -------------------------------
1424 To extract specific archive members, give their exact member names as
1425 arguments, as printed by `--list' (`-t'). If you had mistakenly
1426 deleted one of the files you had placed in the archive `collection.tar'
1427 earlier (say, `blues'), you can extract it from the archive without
1428 changing the archive's structure. Its contents will be identical to
1429 the original file `blues' that you deleted.
1431 First, make sure you are in the `practice' directory, and list the
1432 files in the directory. Now, delete the file, `blues', and list the
1433 files in the directory again.
1435 You can now extract the member `blues' from the archive file
1436 `collection.tar' like this:
1438 $ tar --extract --file=collection.tar blues
1440 If you list the files in the directory again, you will see that the file
1441 `blues' has been restored, with its original permissions, data
1442 modification times, and owner.(1) (These parameters will be identical
1443 to those which the file had when you originally placed it in the
1444 archive; any changes you may have made before deleting the file from
1445 the file system, however, will _not_ have been made to the archive
1446 member.) The archive file, `collection.tar', is the same as it was
1447 before you extracted `blues'. You can confirm this by running `tar'
1448 with `--list' (`-t').
1450 Remember that as with other operations, specifying the exact member
1451 name is important. `tar --extract --file=bfiles.tar birds' will fail,
1452 because there is no member named `birds'. To extract the member named
1453 `./birds', you must specify `tar --extract --file=bfiles.tar ./birds'.
1454 If you don't remember the exact member names, use `--list' (`-t') option
1455 (*note list::). You can also extract those members that match a
1456 specific "globbing pattern". For example, to extract from `bfiles.tar'
1457 all files that begin with `b', no matter their directory prefix, you
1460 $ tar -x -f bfiles.tar --wildcards --no-anchored 'b*'
1462 Here, `--wildcards' instructs `tar' to treat command line arguments as
1463 globbing patterns and `--no-anchored' informs it that the patterns
1464 apply to member names after any `/' delimiter. The use of globbing
1465 patterns is discussed in detail in *Note wildcards::.
1467 You can extract a file to standard output by combining the above
1468 options with the `--to-stdout' (`-O') option (*note Writing to Standard
1471 If you give the `--verbose' option, then `--extract' will print the
1472 names of the archive members as it extracts them.
1474 ---------- Footnotes ----------
1476 (1) This is only accidentally true, but not in general. Whereas
1477 modification times are always restored, in most cases, one has to be
1478 root for restoring the owner, and use a special option for restoring
1479 permissions. Here, it just happens that the restoring user is also the
1480 owner of the archived members, and that the current `umask' is
1481 compatible with original permissions.
1484 File: tar.info, Node: extract dir, Next: extracting untrusted archives, Prev: extracting files, Up: extract
1486 2.8.3 Extracting Files that are Directories
1487 -------------------------------------------
1489 Extracting directories which are members of an archive is similar to
1490 extracting other files. The main difference to be aware of is that if
1491 the extracted directory has the same name as any directory already in
1492 the working directory, then files in the extracted directory will be
1493 placed into the directory of the same name. Likewise, if there are
1494 files in the pre-existing directory with the same names as the members
1495 which you extract, the files from the extracted archive will replace
1496 the files already in the working directory (and possible
1497 subdirectories). This will happen regardless of whether or not the
1498 files in the working directory were more recent than those extracted
1499 (there exist, however, special options that alter this behavior *note
1502 However, if a file was stored with a directory name as part of its
1503 file name, and that directory does not exist under the working
1504 directory when the file is extracted, `tar' will create the directory.
1506 We can demonstrate how to use `--extract' to extract a directory
1507 file with an example. Change to the `practice' directory if you
1508 weren't there, and remove the files `folk' and `jazz'. Then, go back
1509 to the parent directory and extract the archive `music.tar'. You may
1510 either extract the entire archive, or you may extract only the files
1511 you just deleted. To extract the entire archive, don't give any file
1512 names as arguments after the archive name `music.tar'. To extract only
1513 the files you deleted, use the following command:
1515 $ tar -xvf music.tar practice/folk practice/jazz
1519 If you were to specify two `--verbose' (`-v') options, `tar' would have
1520 displayed more detail about the extracted files, as shown in the
1523 $ tar -xvvf music.tar practice/folk practice/jazz
1524 -rw-r--r-- me/user 28 1996-10-18 16:31 practice/jazz
1525 -rw-r--r-- me/user 20 1996-09-23 16:44 practice/folk
1527 Because you created the directory with `practice' as part of the file
1528 names of each of the files by archiving the `practice' directory as
1529 `practice', you must give `practice' as part of the file names when you
1530 extract those files from the archive.
1533 File: tar.info, Node: extracting untrusted archives, Next: failing commands, Prev: extract dir, Up: extract
1535 2.8.4 Extracting Archives from Untrusted Sources
1536 ------------------------------------------------
1538 Extracting files from archives can overwrite files that already exist.
1539 If you receive an archive from an untrusted source, you should make a
1540 new directory and extract into that directory, so that you don't have
1541 to worry about the extraction overwriting one of your existing files.
1542 For example, if `untrusted.tar' came from somewhere else on the
1543 Internet, and you don't necessarily trust its contents, you can extract
1548 $ tar -xvf ../untrusted.tar
1550 It is also a good practice to examine contents of the archive before
1551 extracting it, using `--list' (`-t') option, possibly combined with
1555 File: tar.info, Node: failing commands, Prev: extracting untrusted archives, Up: extract
1557 2.8.5 Commands That Will Fail
1558 -----------------------------
1560 Here are some sample commands you might try which will not work, and why
1563 If you try to use this command,
1565 $ tar -xvf music.tar folk jazz
1567 you will get the following response:
1569 tar: folk: Not found in archive
1570 tar: jazz: Not found in archive
1572 This is because these files were not originally _in_ the parent
1573 directory `..', where the archive is located; they were in the
1574 `practice' directory, and their file names reflect this:
1576 $ tar -tvf music.tar
1581 Likewise, if you try to use this command,
1583 $ tar -tvf music.tar folk jazz
1585 you would get a similar response. Members with those names are not in
1586 the archive. You must use the correct member names, or wildcards, in
1587 order to extract the files from the archive.
1589 If you have forgotten the correct names of the files in the archive,
1590 use `tar --list --verbose' to list them correctly.
1593 File: tar.info, Node: going further, Prev: extract, Up: Tutorial
1595 2.9 Going Further Ahead in this Manual
1596 ======================================
1598 _(This message will disappear, once this node revised.)_
1601 File: tar.info, Node: tar invocation, Next: operations, Prev: Tutorial, Up: Top
1603 3 Invoking GNU `tar'
1604 ********************
1606 This chapter is about how one invokes the GNU `tar' command, from the
1607 command synopsis (*note Synopsis::). There are numerous options, and
1608 many styles for writing them. One mandatory option specifies the
1609 operation `tar' should perform (*note Operation Summary::), other
1610 options are meant to detail how this operation should be performed
1611 (*note Option Summary::). Non-option arguments are not always
1612 interpreted the same way, depending on what the operation is.
1614 You will find in this chapter everything about option styles and
1615 rules for writing them (*note Styles::). On the other hand, operations
1616 and options are fully described elsewhere, in other chapters. Here,
1617 you will find only synthetic descriptions for operations and options,
1618 together with pointers to other parts of the `tar' manual.
1620 Some options are so special they are fully described right in this
1621 chapter. They have the effect of inhibiting the normal operation of
1622 `tar' or else, they globally alter the amount of feedback the user
1623 receives about what is going on. These are the `--help' and
1624 `--version' (*note help::), `--verbose' (*note verbose::) and
1625 `--interactive' options (*note interactive::).
1630 * using tar options::
1632 * All Options:: All `tar' Options.
1633 * help:: Where to Get Help.
1634 * defaults:: What are the Default Values.
1635 * verbose:: Checking `tar' progress.
1636 * checkpoints:: Checkpoints.
1637 * warnings:: Controlling Warning Messages.
1638 * interactive:: Asking for Confirmation During Operations.
1639 * external:: Running External Commands.
1642 File: tar.info, Node: Synopsis, Next: using tar options, Up: tar invocation
1644 3.1 General Synopsis of `tar'
1645 =============================
1647 The GNU `tar' program is invoked as either one of:
1649 tar OPTION... [NAME]...
1650 tar LETTER... [ARGUMENT]... [OPTION]... [NAME]...
1652 The second form is for when old options are being used.
1654 You can use `tar' to store files in an archive, to extract them from
1655 an archive, and to do other types of archive manipulation. The primary
1656 argument to `tar', which is called the "operation", specifies which
1657 action to take. The other arguments to `tar' are either "options",
1658 which change the way `tar' performs an operation, or file names or
1659 archive members, which specify the files or members `tar' is to act on.
1661 You can actually type in arguments in any order, even if in this
1662 manual the options always precede the other arguments, to make examples
1663 easier to understand. Further, the option stating the main operation
1664 mode (the `tar' main command) is usually given first.
1666 Each NAME in the synopsis above is interpreted as an archive member
1667 name when the main command is one of `--compare' (`--diff', `-d'),
1668 `--delete', `--extract' (`--get', `-x'), `--list' (`-t') or `--update'
1669 (`-u'). When naming archive members, you must give the exact name of
1670 the member in the archive, as it is printed by `--list'. For
1671 `--append' (`-r') and `--create' (`-c'), these NAME arguments specify
1672 the names of either files or directory hierarchies to place in the
1673 archive. These files or hierarchies should already exist in the file
1674 system, prior to the execution of the `tar' command.
1676 `tar' interprets relative file names as being relative to the
1677 working directory. `tar' will make all file names relative (by
1678 removing leading slashes when archiving or restoring files), unless you
1679 specify otherwise (using the `--absolute-names' option). *Note
1680 absolute::, for more information about `--absolute-names'.
1682 If you give the name of a directory as either a file name or a member
1683 name, then `tar' acts recursively on all the files and directories
1684 beneath that directory. For example, the name `/' identifies all the
1685 files in the file system to `tar'.
1687 The distinction between file names and archive member names is
1688 especially important when shell globbing is used, and sometimes a
1689 source of confusion for newcomers. *Note wildcards::, for more
1690 information about globbing. The problem is that shells may only glob
1691 using existing files in the file system. Only `tar' itself may glob on
1692 archive members, so when needed, you must ensure that wildcard
1693 characters reach `tar' without being interpreted by the shell first.
1694 Using a backslash before `*' or `?', or putting the whole argument
1695 between quotes, is usually sufficient for this.
1697 Even if NAMEs are often specified on the command line, they can also
1698 be read from a text file in the file system, using the
1699 `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option.
1701 If you don't use any file name arguments, `--append' (`-r'),
1702 `--delete' and `--concatenate' (`--catenate', `-A') will do nothing,
1703 while `--create' (`-c') will usually yield a diagnostic and inhibit
1704 `tar' execution. The other operations of `tar' (`--list', `--extract',
1705 `--compare', and `--update') will act on the entire contents of the
1708 Besides successful exits, GNU `tar' may fail for many reasons. Some
1709 reasons correspond to bad usage, that is, when the `tar' command line
1710 is improperly written. Errors may be encountered later, while
1711 processing the archive or the files. Some errors are recoverable, in
1712 which case the failure is delayed until `tar' has completed all its
1713 work. Some errors are such that it would be not meaningful, or at
1714 least risky, to continue processing: `tar' then aborts processing
1715 immediately. All abnormal exits, whether immediate or delayed, should
1716 always be clearly diagnosed on `stderr', after a line stating the
1717 nature of the error.
1719 Possible exit codes of GNU `tar' are summarized in the following
1723 `Successful termination'.
1726 `Some files differ'. If tar was invoked with `--compare'
1727 (`--diff', `-d') command line option, this means that some files
1728 in the archive differ from their disk counterparts (*note
1729 compare::). If tar was given `--create', `--append' or `--update'
1730 option, this exit code means that some files were changed while
1731 being archived and so the resulting archive does not contain the
1732 exact copy of the file set.
1735 `Fatal error'. This means that some fatal, unrecoverable error
1738 If `tar' has invoked a subprocess and that subprocess exited with a
1739 nonzero exit code, `tar' exits with that code as well. This can
1740 happen, for example, if `tar' was given some compression option (*note
1741 gzip::) and the external compressor program failed. Another example is
1742 `rmt' failure during backup to the remote device (*note Remote Tape
1746 File: tar.info, Node: using tar options, Next: Styles, Prev: Synopsis, Up: tar invocation
1748 3.2 Using `tar' Options
1749 =======================
1751 GNU `tar' has a total of eight operating modes which allow you to
1752 perform a variety of tasks. You are required to choose one operating
1753 mode each time you employ the `tar' program by specifying one, and only
1754 one operation as an argument to the `tar' command (the corresponding
1755 options may be found at *note frequent operations:: and *note
1756 Operations::). Depending on circumstances, you may also wish to
1757 customize how the chosen operating mode behaves. For example, you may
1758 wish to change the way the output looks, or the format of the files
1759 that you wish to archive may require you to do something special in
1760 order to make the archive look right.
1762 You can customize and control `tar''s performance by running `tar'
1763 with one or more options (such as `--verbose' (`-v'), which we used in
1764 the tutorial). As we said in the tutorial, "options" are arguments to
1765 `tar' which are (as their name suggests) optional. Depending on the
1766 operating mode, you may specify one or more options. Different options
1767 will have different effects, but in general they all change details of
1768 the operation, such as archive format, archive name, or level of user
1769 interaction. Some options make sense with all operating modes, while
1770 others are meaningful only with particular modes. You will likely use
1771 some options frequently, while you will only use others infrequently, or
1772 not at all. (A full list of options is available in *note All
1775 The `TAR_OPTIONS' environment variable specifies default options to
1776 be placed in front of any explicit options. For example, if
1777 `TAR_OPTIONS' is `-v --unlink-first', `tar' behaves as if the two
1778 options `-v' and `--unlink-first' had been specified before any
1779 explicit options. Option specifications are separated by whitespace.
1780 A backslash escapes the next character, so it can be used to specify an
1781 option containing whitespace or a backslash.
1783 Note that `tar' options are case sensitive. For example, the
1784 options `-T' and `-t' are different; the first requires an argument for
1785 stating the name of a file providing a list of NAMEs, while the second
1786 does not require an argument and is another way to write `--list'
1789 In addition to the eight operations, there are many options to
1790 `tar', and three different styles for writing both: long (mnemonic)
1791 form, short form, and old style. These styles are discussed below.
1792 Both the options and the operations can be written in any of these three
1796 File: tar.info, Node: Styles, Next: All Options, Prev: using tar options, Up: tar invocation
1798 3.3 The Three Option Styles
1799 ===========================
1801 There are three styles for writing operations and options to the command
1802 line invoking `tar'. The different styles were developed at different
1803 times during the history of `tar'. These styles will be presented
1804 below, from the most recent to the oldest.
1806 Some options must take an argument(1). Where you _place_ the
1807 arguments generally depends on which style of options you choose. We
1808 will detail specific information relevant to each option style in the
1809 sections on the different option styles, below. The differences are
1810 subtle, yet can often be very important; incorrect option placement can
1811 cause you to overwrite a number of important files. We urge you to
1812 note these differences, and only use the option style(s) which makes
1813 the most sense to you until you feel comfortable with the others.
1815 Some options _may_ take an argument. Such options may have at most
1816 long and short forms, they do not have old style equivalent. The rules
1817 for specifying an argument for such options are stricter than those for
1818 specifying mandatory arguments. Please, pay special attention to them.
1822 * Long Options:: Long Option Style
1823 * Short Options:: Short Option Style
1824 * Old Options:: Old Option Style
1825 * Mixing:: Mixing Option Styles
1827 ---------- Footnotes ----------
1829 (1) For example, `--file' (`-f') takes the name of an archive file
1830 as an argument. If you do not supply an archive file name, `tar' will
1831 use a default, but this can be confusing; thus, we recommend that you
1832 always supply a specific archive file name.
1835 File: tar.info, Node: Long Options, Next: Short Options, Up: Styles
1837 3.3.1 Long Option Style
1838 -----------------------
1840 Each option has at least one "long" (or "mnemonic") name starting with
1841 two dashes in a row, e.g., `--list'. The long names are more clear than
1842 their corresponding short or old names. It sometimes happens that a
1843 single long option has many different names which are synonymous, such
1844 as `--compare' and `--diff'. In addition, long option names can be
1845 given unique abbreviations. For example, `--cre' can be used in place
1846 of `--create' because there is no other long option which begins with
1847 `cre'. (One way to find this out is by trying it and seeing what
1848 happens; if a particular abbreviation could represent more than one
1849 option, `tar' will tell you that that abbreviation is ambiguous and
1850 you'll know that that abbreviation won't work. You may also choose to
1851 run `tar --help' to see a list of options. Be aware that if you run
1852 `tar' with a unique abbreviation for the long name of an option you
1853 didn't want to use, you are stuck; `tar' will perform the command as
1856 Long options are meant to be obvious and easy to remember, and their
1857 meanings are generally easier to discern than those of their
1858 corresponding short options (see below). For example:
1860 $ tar --create --verbose --blocking-factor=20 --file=/dev/rmt0
1862 gives a fairly good set of hints about what the command does, even for
1863 those not fully acquainted with `tar'.
1865 Long options which require arguments take those arguments
1866 immediately following the option name. There are two ways of
1867 specifying a mandatory argument. It can be separated from the option
1868 name either by an equal sign, or by any amount of white space
1869 characters. For example, the `--file' option (which tells the name of
1870 the `tar' archive) is given a file such as `archive.tar' as argument by
1871 using any of the following notations: `--file=archive.tar' or `--file
1874 In contrast, optional arguments must always be introduced using an
1875 equal sign. For example, the `--backup' option takes an optional
1876 argument specifying backup type. It must be used as
1877 `--backup=BACKUP-TYPE'.
1880 File: tar.info, Node: Short Options, Next: Old Options, Prev: Long Options, Up: Styles
1882 3.3.2 Short Option Style
1883 ------------------------
1885 Most options also have a "short option" name. Short options start with
1886 a single dash, and are followed by a single character, e.g., `-t'
1887 (which is equivalent to `--list'). The forms are absolutely identical
1888 in function; they are interchangeable.
1890 The short option names are faster to type than long option names.
1892 Short options which require arguments take their arguments
1893 immediately following the option, usually separated by white space. It
1894 is also possible to stick the argument right after the short option
1895 name, using no intervening space. For example, you might write
1896 `-f archive.tar' or `-farchive.tar' instead of using
1897 `--file=archive.tar'. Both `--file=ARCHIVE-NAME' and `-f ARCHIVE-NAME'
1898 denote the option which indicates a specific archive, here named
1901 Short options which take optional arguments take their arguments
1902 immediately following the option letter, _without any intervening white
1905 Short options' letters may be clumped together, but you are not
1906 required to do this (as compared to old options; see below). When
1907 short options are clumped as a set, use one (single) dash for them all,
1908 e.g., ``tar' -cvf'. Only the last option in such a set is allowed to
1909 have an argument(1).
1911 When the options are separated, the argument for each option which
1912 requires an argument directly follows that option, as is usual for Unix
1913 programs. For example:
1915 $ tar -c -v -b 20 -f /dev/rmt0
1917 If you reorder short options' locations, be sure to move any
1918 arguments that belong to them. If you do not move the arguments
1919 properly, you may end up overwriting files.
1921 ---------- Footnotes ----------
1923 (1) Clustering many options, the last of which has an argument, is a
1924 rather opaque way to write options. Some wonder if GNU `getopt' should
1925 not even be made helpful enough for considering such usages as invalid.
1928 File: tar.info, Node: Old Options, Next: Mixing, Prev: Short Options, Up: Styles
1930 3.3.3 Old Option Style
1931 ----------------------
1933 As far as we know, all `tar' programs, GNU and non-GNU, support "old
1934 options": that is, if the first argument does not start with `-', it is
1935 assumed to specify option letters. GNU `tar' supports old options not
1936 only for historical reasons, but also because many people are used to
1937 them. If the first argument does not start with a dash, you are
1938 announcing the old option style instead of the short option style; old
1939 options are decoded differently.
1941 Like short options, old options are single letters. However, old
1942 options must be written together as a single clumped set, without
1943 spaces separating them or dashes preceding them. This set of letters
1944 must be the first to appear on the command line, after the `tar'
1945 program name and some white space; old options cannot appear anywhere
1946 else. The letter of an old option is exactly the same letter as the
1947 corresponding short option. For example, the old option `t' is the
1948 same as the short option `-t', and consequently, the same as the long
1949 option `--list'. So for example, the command `tar cv' specifies the
1950 option `-v' in addition to the operation `-c'.
1952 When options that need arguments are given together with the command,
1953 all the associated arguments follow, in the same order as the options.
1954 Thus, the example given previously could also be written in the old
1957 $ tar cvbf 20 /dev/rmt0
1959 Here, `20' is the argument of `-b' and `/dev/rmt0' is the argument of
1962 The old style syntax can make it difficult to match option letters
1963 with their corresponding arguments, and is often confusing. In the
1964 command `tar cvbf 20 /dev/rmt0', for example, `20' is the argument for
1965 `-b', `/dev/rmt0' is the argument for `-f', and `-v' does not have a
1966 corresponding argument. Even using short options like in
1967 `tar -c -v -b 20 -f /dev/rmt0' is clearer, putting all arguments next
1968 to the option they pertain to.
1970 If you want to reorder the letters in the old option argument, be
1971 sure to reorder any corresponding argument appropriately.
1973 This old way of writing `tar' options can surprise even experienced
1974 users. For example, the two commands:
1976 tar cfz archive.tar.gz file
1977 tar -cfz archive.tar.gz file
1979 are quite different. The first example uses `archive.tar.gz' as the
1980 value for option `f' and recognizes the option `z'. The second
1981 example, however, uses `z' as the value for option `f' -- probably not
1984 This second example could be corrected in many ways, among which the
1985 following are equivalent:
1987 tar -czf archive.tar.gz file
1988 tar -cf archive.tar.gz -z file
1989 tar cf archive.tar.gz -z file
1992 File: tar.info, Node: Mixing, Prev: Old Options, Up: Styles
1994 3.3.4 Mixing Option Styles
1995 --------------------------
1997 All three styles may be intermixed in a single `tar' command, so long
1998 as the rules for each style are fully respected(1). Old style options
1999 and either of the modern styles of options may be mixed within a single
2000 `tar' command. However, old style options must be introduced as the
2001 first arguments only, following the rule for old options (old options
2002 must appear directly after the `tar' command and some white space).
2003 Modern options may be given only after all arguments to the old options
2004 have been collected. If this rule is not respected, a modern option
2005 might be falsely interpreted as the value of the argument to one of the
2008 For example, all the following commands are wholly equivalent, and
2009 illustrate the many combinations and orderings of option styles.
2011 tar --create --file=archive.tar
2012 tar --create -f archive.tar
2013 tar --create -farchive.tar
2014 tar --file=archive.tar --create
2015 tar --file=archive.tar -c
2016 tar -c --file=archive.tar
2017 tar -c -f archive.tar
2018 tar -c -farchive.tar
2021 tar -f archive.tar --create
2022 tar -f archive.tar -c
2023 tar -farchive.tar --create
2024 tar -farchive.tar -c
2025 tar c --file=archive.tar
2026 tar c -f archive.tar
2029 tar f archive.tar --create
2030 tar f archive.tar -c
2033 On the other hand, the following commands are _not_ equivalent to
2036 tar -f -c archive.tar
2042 These last examples mean something completely different from what the
2043 user intended (judging based on the example in the previous set which
2044 uses long options, whose intent is therefore very clear). The first
2045 four specify that the `tar' archive would be a file named `-c', `c',
2046 `carchive.tar' or `archive.tarc', respectively. The first two examples
2047 also specify a single non-option, NAME argument having the value
2048 `archive.tar'. The last example contains only old style option letters
2049 (repeating option `c' twice), not all of which are meaningful (eg., `.',
2050 `h', or `i'), with no argument value.
2052 ---------- Footnotes ----------
2054 (1) Before GNU `tar' version 1.11.6, a bug prevented intermixing old
2055 style options with long options in some cases.
2058 File: tar.info, Node: All Options, Next: help, Prev: Styles, Up: tar invocation
2060 3.4 All `tar' Options
2061 =====================
2063 The coming manual sections contain an alphabetical listing of all `tar'
2064 operations and options, with brief descriptions and cross-references to
2065 more in-depth explanations in the body of the manual. They also
2066 contain an alphabetically arranged table of the short option forms with
2067 their corresponding long option. You can use this table as a reference
2068 for deciphering `tar' commands in scripts.
2072 * Operation Summary::
2074 * Short Option Summary::
2077 File: tar.info, Node: Operation Summary, Next: Option Summary, Up: All Options
2084 Appends files to the end of the archive. *Note append::.
2088 Same as `--concatenate'. *Note concatenate::.
2092 Compares archive members with their counterparts in the file
2093 system, and reports differences in file size, mode, owner,
2094 modification date and contents. *Note compare::.
2098 Appends other `tar' archives to the end of the archive. *Note
2103 Creates a new `tar' archive. *Note create::.
2106 Deletes members from the archive. Don't try this on an archive on
2107 a tape! *Note delete::.
2111 Same `--compare'. *Note compare::.
2115 Extracts members from the archive into the file system. *Note
2120 Same as `--extract'. *Note extract::.
2124 Lists the members in an archive. *Note list::.
2128 Adds files to the end of the archive, but only if they are newer
2129 than their counterparts already in the archive, or if they do not
2130 already exist in the archive. *Note update::.
2134 File: tar.info, Node: Option Summary, Next: Short Option Summary, Prev: Operation Summary, Up: All Options
2141 Normally when creating an archive, `tar' strips an initial `/'
2142 from member names, and when extracting from an archive `tar'
2143 treats names specially if they have initial `/' or internal `..'.
2144 This option disables that behavior. *Note absolute::.
2147 (See `--newer', *note after::)
2150 A pattern must match an initial subsequence of the name's
2151 components. *Note controlling pattern-matching::.
2154 `--atime-preserve=replace'
2155 `--atime-preserve=system'
2156 Attempt to preserve the access time of files when reading them.
2157 This option currently is effective only on files that you own,
2158 unless you have superuser privileges.
2160 `--atime-preserve=replace' remembers the access time of a file
2161 before reading it, and then restores the access time afterwards.
2162 This may cause problems if other programs are reading the file at
2163 the same time, as the times of their accesses will be lost. On
2164 most platforms restoring the access time also requires `tar' to
2165 restore the data modification time too, so this option may also
2166 cause problems if other programs are writing the file at the same
2167 time (`tar' attempts to detect this situation, but cannot do so
2168 reliably due to race conditions). Worse, on most platforms
2169 restoring the access time also updates the status change time,
2170 which means that this option is incompatible with incremental
2173 `--atime-preserve=system' avoids changing time stamps on files,
2174 without interfering with time stamp updates caused by other
2175 programs, so it works better with incremental backups. However,
2176 it requires a special `O_NOATIME' option from the underlying
2177 operating and file system implementation, and it also requires
2178 that searching directories does not update their access times. As
2179 of this writing (November 2005) this works only with Linux, and
2180 only with Linux kernels 2.6.8 and later. Worse, there is
2181 currently no reliable way to know whether this feature actually
2182 works. Sometimes `tar' knows that it does not work, and if you use
2183 `--atime-preserve=system' then `tar' complains and exits right
2184 away. But other times `tar' might think that the option works
2185 when it actually does not.
2187 Currently `--atime-preserve' with no operand defaults to
2188 `--atime-preserve=replace', but this may change in the future as
2189 support for `--atime-preserve=system' improves.
2191 If your operating or file system does not support
2192 `--atime-preserve=system', you might be able to preserve access
2193 times reliably by using the `mount' command. For example, you can
2194 mount the file system read-only, or access the file system via a
2195 read-only loopback mount, or use the `noatime' mount option
2196 available on some systems. However, mounting typically requires
2197 superuser privileges and can be a pain to manage.
2201 During a `--create' operation, enables automatic compressed format
2202 recognition based on the archive suffix. The effect of this
2203 option is cancelled by `--no-auto-compress'. *Note gzip::.
2205 `--backup=BACKUP-TYPE'
2206 Rather than deleting files from the file system, `tar' will back
2207 them up using simple or numbered backups, depending upon
2208 BACKUP-TYPE. *Note backup::.
2212 With this option present, `tar' prints error messages for read
2213 errors with the block number in the archive file. *Note
2216 `--blocking-factor=BLOCKING'
2218 Sets the blocking factor `tar' uses to BLOCKING x 512 bytes per
2219 record. *Note Blocking Factor::.
2223 This option tells `tar' to read or write archives through `bzip2'.
2227 Check device numbers when creating a list of modified files for
2228 incremental archiving. This is the default. *Note device
2229 numbers::, for a detailed description.
2231 `--checkpoint[=NUMBER]'
2232 This option directs `tar' to print periodic checkpoint messages as
2233 it reads through the archive. It is intended for when you want a
2234 visual indication that `tar' is still running, but don't want to
2235 see `--verbose' output. You can also instruct `tar' to execute a
2236 list of actions on each checkpoint, see `--checkpoint-action'
2237 below. For a detailed description, see *note checkpoints::.
2239 `--checkpoint-action=ACTION'
2240 Instruct `tar' to execute an action upon hitting a breakpoint.
2241 Here we give only a brief outline. *Note checkpoints::, for a
2242 complete description.
2244 The ACTION argument can be one of the following:
2247 Produce an audible bell on the console.
2251 Print a single dot on the standard listing stream.
2254 Display a textual message on the standard error, with the
2255 status and number of the checkpoint. This is the default.
2258 Display STRING on the standard error. Before output, the
2259 string is subject to meta-character expansion.
2262 Execute the given COMMAND.
2265 Wait for TIME seconds.
2268 Output STRING on the current console (`/dev/tty').
2270 Several `--checkpoint-action' options can be specified. The
2271 supplied actions will be executed in order of their appearance in
2274 Using `--checkpoint-action' without `--checkpoint' assumes default
2275 checkpoint frequency of one checkpoint per 10 records.
2279 If this option was given, `tar' will check the number of links
2280 dumped for each processed file. If this number does not match the
2281 total number of hard links for the file, a warning message will be
2289 `tar' will use the `compress' program when reading or writing the
2290 archive. This allows you to directly act on archives while saving
2291 space. *Note gzip::.
2294 (See `--interactive'.) *Note interactive::.
2296 `--delay-directory-restore'
2297 Delay setting modification times and permissions of extracted
2298 directories until the end of extraction. *Note Directory
2299 Modification Times and Permissions::.
2303 When reading or writing a file to be archived, `tar' accesses the
2304 file that a symbolic link points to, rather than the symlink
2305 itself. *Note dereference::.
2309 When this option is specified, `tar' will change its current
2310 directory to DIR before performing any operations. When this
2311 option is used during archive creation, it is order sensitive.
2315 When performing operations, `tar' will skip files that match
2316 PATTERN. *Note exclude::.
2319 Exclude backup and lock files. *Note exclude-backups: exclude.
2321 `--exclude-from=FILE'
2323 Similar to `--exclude', except `tar' will use the list of patterns
2324 in the file FILE. *Note exclude::.
2327 Exclude from dump any directory containing a valid cache directory
2328 tag file, but still dump the directory node and the tag file
2331 *Note exclude-caches: exclude.
2333 `--exclude-caches-under'
2334 Exclude from dump any directory containing a valid cache directory
2335 tag file, but still dump the directory node itself.
2339 `--exclude-caches-all'
2340 Exclude from dump any directory containing a valid cache directory
2341 tag file. *Note exclude::.
2343 `--exclude-ignore=FILE'
2344 Before dumping a directory, `tar' checks if it contains FILE. If
2345 so, exclusion patterns are read from this file. The patterns
2346 affect only the directory itself. *Note exclude::.
2348 `--exclude-ignore-recursive=FILE'
2349 Before dumping a directory, `tar' checks if it contains FILE. If
2350 so, exclusion patterns are read from this file. The patterns
2351 affect the directory and all itssubdirectories. *Note exclude::.
2353 `--exclude-tag=FILE'
2354 Exclude from dump any directory containing file named FILE, but
2355 dump the directory node and FILE itself. *Note exclude-tag:
2358 `--exclude-tag-under=FILE'
2359 Exclude from dump the contents of any directory containing file
2360 named FILE, but dump the directory node itself. *Note
2361 exclude-tag-under: exclude.
2363 `--exclude-tag-all=FILE'
2364 Exclude from dump any directory containing file named FILE. *Note
2365 exclude-tag-all: exclude.
2368 Exclude from dump directories and files, that are internal for some
2369 widely used version control systems.
2371 *Note exclude-vcs::.
2373 `--exclude-vcs-ignores'
2374 Exclude files that match patterns read from VCS-specific ignore
2375 files. Supported files are: `.cvsignore', `.gitignore',
2376 `.bzrignore', and `.hgignore'. The semantics of each file is the
2377 same as for the corresponding VCS, e.g. patterns read from
2378 `.gitignore' affect the directory and all its subdirectories.
2379 *Note exclude-vcs-ignores::.
2383 `tar' will use the file ARCHIVE as the `tar' archive it performs
2384 operations on, rather than `tar''s compilation dependent default.
2385 *Note file tutorial::.
2389 `tar' will use the contents of FILE as a list of archive members
2390 or files to operate on, in addition to those specified on the
2391 command-line. *Note files::.
2394 Forces `tar' to interpret the file name given to `--file' as a
2395 local file, even if it looks like a remote tape drive name. *Note
2396 local and remote archives::.
2400 Selects output archive format. FORMAT may be one of the following:
2403 Creates an archive that is compatible with Unix V7 `tar'.
2406 Creates an archive that is compatible with GNU `tar' version
2410 Creates archive in GNU tar 1.13 format. Basically it is the
2411 same as `oldgnu' with the only difference in the way it
2412 handles long numeric fields.
2415 Creates a POSIX.1-1988 compatible archive.
2418 Creates a POSIX.1-2001 archive.
2421 *Note Formats::, for a detailed discussion of these formats.
2424 This option instructs `tar' to print file times to their full
2425 resolution. Usually this means 1-second resolution, but that
2426 depends on the underlying file system. The `--full-time' option
2427 takes effect only when detailed output (verbosity level 2 or
2428 higher) has been requested using the `--verbose' option, e.g.,
2429 when listing or extracting archives:
2431 $ tar -t -v --full-time -f archive.tar
2433 or, when creating an archive:
2435 $ tar -c -vv --full-time -f archive.tar .
2437 Notice, thar when creating the archive you need to specify
2438 `--verbose' twice to get a detailed output (*note verbose
2442 Files added to the `tar' archive will have a group ID of GROUP,
2443 rather than the group from the source file. GROUP can specify a
2444 symbolic name, or a numeric ID, or both as NAME:ID. *Note
2447 Also see the comments for the `--owner=USER' option.
2453 This option tells `tar' to read or write archives through `gzip',
2454 allowing `tar' to directly operate on several kinds of compressed
2455 archives transparently. *Note gzip::.
2457 `--hard-dereference'
2458 When creating an archive, dereference hard links and store the
2459 files they refer to, instead of creating usual hard link members.
2465 `tar' will print out a short message summarizing the operations and
2466 options to `tar' and exit. *Note help::.
2469 Ignore case when matching member or file names with patterns.
2470 *Note controlling pattern-matching::.
2472 `--ignore-command-error'
2473 Ignore exit codes of subprocesses. *Note Writing to an External
2476 `--ignore-failed-read'
2477 Do not exit unsuccessfully merely because an unreadable file was
2478 encountered. *Note Ignore Failed Read::.
2482 With this option, `tar' will ignore zeroed blocks in the archive,
2483 which normally signals EOF. *Note Reading::.
2487 Informs `tar' that it is working with an old GNU-format
2488 incremental backup archive. It is intended primarily for
2489 backwards compatibility only. *Note Incremental Dumps::, for a
2490 detailed discussion of incremental archives.
2493 Send verbose output to FILE instead of to standard output.
2495 `--info-script=COMMAND'
2496 `--new-volume-script=COMMAND'
2498 When `tar' is performing multi-tape backups, COMMAND is run at the
2499 end of each tape. If it exits with nonzero status, `tar' fails
2500 immediately. *Note info-script::, for a detailed discussion of
2506 Specifies that `tar' should ask the user for confirmation before
2507 performing potentially destructive options, such as overwriting
2508 files. *Note interactive::.
2510 `--keep-directory-symlink'
2511 This option changes the behavior of tar when it encounters a
2512 symlink with the same name as the directory that it is about to
2513 extract. By default, in this case tar would first remove the
2514 symlink and then proceed extracting the directory.
2516 The `--keep-directory-symlink' option disables this behavior and
2517 instructs tar to follow symlinks to directories when extracting
2520 It is mainly intended to provide compatibility with the Slackware
2521 installation scripts.
2523 `--keep-newer-files'
2524 Do not replace existing files that are newer than their archive
2525 copies when extracting files from an archive.
2529 Do not overwrite existing files when extracting files from an
2530 archive. Return error if such files exist. See also *note
2533 *Note Keep Old Files::.
2537 When creating an archive, instructs `tar' to write NAME as a name
2538 record in the archive. When extracting or listing archives, `tar'
2539 will only operate on archives that have a label matching the
2540 pattern specified in NAME. *Note Tape Files::.
2543 Force incremental backup of level N. As of GNU `tar' version
2544 1.28, the option `--level=0' truncates the snapshot file, thereby
2545 forcing the level 0 dump. Other values of N are effectively
2546 ignored. *Note --level=0::, for details and examples.
2548 The use of this option is valid only in conjunction with the
2549 `--listed-incremental' option. *Note Incremental Dumps::, for a
2550 detailed description.
2552 `--listed-incremental=SNAPSHOT-FILE'
2554 During a `--create' operation, specifies that the archive that
2555 `tar' creates is a new GNU-format incremental backup, using
2556 SNAPSHOT-FILE to determine which files to backup. With other
2557 operations, informs `tar' that the archive is in incremental
2558 format. *Note Incremental Dumps::.
2561 This option tells `tar' to read or write archives through `lzip'.
2565 This option tells `tar' to read or write archives through `lzma'.
2569 This option tells `tar' to read or write archives through `lzop'.
2572 `--mode=PERMISSIONS'
2573 When adding files to an archive, `tar' will use PERMISSIONS for
2574 the archive members, rather than the permissions from the files.
2575 PERMISSIONS can be specified either as an octal number or as
2576 symbolic permissions, like with `chmod'. *Note override::.
2579 When adding files to an archive, `tar' will use DATE as the
2580 modification time of members when creating archives, instead of
2581 their actual modification times. The value of DATE can be either
2582 a textual date representation (*note Date input formats::) or a
2583 name of the existing file, starting with `/' or `.'. In the
2584 latter case, the modification time of that file is used. *Note
2589 Informs `tar' that it should create or otherwise operate on a
2590 multi-volume `tar' archive. *Note Using Multiple Tapes::.
2592 `--new-volume-script'
2593 (see `--info-script')
2598 When creating an archive, `tar' will only add files that have
2599 changed since DATE. If DATE begins with `/' or `.', it is taken
2600 to be the name of a file whose data modification time specifies
2601 the date. *Note after::.
2603 `--newer-mtime=DATE'
2604 Like `--newer', but add only files whose contents have changed (as
2605 opposed to just `--newer', which will also back up files for which
2606 any status information has changed). *Note after::.
2609 An exclude pattern can match any subsequence of the name's
2610 components. *Note controlling pattern-matching::.
2612 `--no-auto-compress'
2613 Disables automatic compressed format recognition based on the
2614 archive suffix. *Note --auto-compress::. *Note gzip::.
2617 Do not check device numbers when creating a list of modified files
2618 for incremental archiving. *Note device numbers::, for a detailed
2621 `--no-delay-directory-restore'
2622 Modification times and permissions of extracted directories are
2623 set when all files from this directory have been extracted. This
2624 is the default. *Note Directory Modification Times and
2628 Use case-sensitive matching. *Note controlling pattern-matching::.
2630 `--no-ignore-command-error'
2631 Print warnings about subprocesses that terminated with a nonzero
2632 exit code. *Note Writing to an External Program::.
2635 If the `--null' option was given previously, this option cancels
2636 its effect, so that any following `--files-from' options will
2637 expect their file lists to be newline-terminated.
2639 `--no-overwrite-dir'
2640 Preserve metadata of existing directories when extracting files
2641 from an archive. *Note Overwrite Old Files::.
2643 `--no-quote-chars=STRING'
2644 Remove characters listed in STRING from the list of quoted
2645 characters set by the previous `--quote-chars' option (*note
2649 With this option, `tar' will not recurse into directories. *Note
2654 When extracting an archive, do not attempt to preserve the owner
2655 specified in the `tar' archive. This the default behavior for
2658 `--no-same-permissions'
2659 When extracting an archive, subtract the user's umask from files
2660 from the permissions specified in the archive. This is the
2661 default behavior for ordinary users.
2664 The archive media does not support seeks to arbitrary locations.
2665 Usually `tar' determines automatically whether the archive can be
2666 seeked or not. Use this option to disable this mechanism.
2669 Treat all input file or member names literally, do not interpret
2670 escape sequences. *Note input name quoting::.
2673 Do not use wildcards. *Note controlling pattern-matching::.
2675 `--no-wildcards-match-slash'
2676 Wildcards do not match `/'. *Note controlling pattern-matching::.
2679 When `tar' is using the `--files-from' option, this option
2680 instructs `tar' to expect file names terminated with NUL, so `tar'
2681 can correctly work with file names that contain newlines. *Note
2685 This option will notify `tar' that it should use numeric user and
2686 group IDs when creating a `tar' file, rather than names. *Note
2690 The function of this option depends on the action `tar' is
2691 performing. When extracting files, `-o' is a synonym for
2692 `--no-same-owner', i.e., it prevents `tar' from restoring
2693 ownership of files being extracted.
2695 When creating an archive, it is a synonym for `--old-archive'.
2696 This behavior is for compatibility with previous versions of GNU
2697 `tar', and will be removed in future releases.
2699 *Note Changes::, for more information.
2701 `--occurrence[=NUMBER]'
2702 This option can be used in conjunction with one of the subcommands
2703 `--delete', `--diff', `--extract' or `--list' when a list of files
2704 is given either on the command line or via `-T' option.
2706 This option instructs `tar' to process only the NUMBERth
2707 occurrence of each named file. NUMBER defaults to 1, so
2709 tar -x -f archive.tar --occurrence filename
2711 will extract the first occurrence of the member `filename' from
2712 `archive.tar' and will terminate without scanning to the end of
2716 Synonym for `--format=v7'.
2719 Used when creating an archive. Prevents `tar' from recursing into
2720 directories that are on different file systems from the current
2723 `--one-top-level[=DIR]'
2724 Tells `tar' to create a new directory beneath the extraction
2725 directory (or the one passed to `-C') and use it to guard against
2726 tarbombs. In the absence of DIR argument, the name of the new
2727 directory will be equal to the base name of the archive (file name
2728 minus the archive suffix, if recognized). Any member names that
2729 do not begin with that directory name (after transformations from
2730 `--transform' and `--strip-components') will be prefixed with it.
2731 Recognized file name suffixes are `.tar', and any compression
2732 suffixes recognizable by *Note --auto-compress::.
2735 Overwrite existing files and directory metadata when extracting
2736 files from an archive. *Note Overwrite Old Files::.
2739 Overwrite the metadata of existing directories when extracting
2740 files from an archive. *Note Overwrite Old Files::.
2743 Specifies that `tar' should use USER as the owner of members when
2744 creating archives, instead of the user associated with the source
2745 file. USER can specify a symbolic name, or a numeric ID, or both
2746 as NAME:ID. *Note override::.
2748 This option does not affect extraction from archives.
2750 `--pax-option=KEYWORD-LIST'
2751 This option enables creation of the archive in POSIX.1-2001 format
2752 (*note posix::) and modifies the way `tar' handles the extended
2753 header keywords. KEYWORD-LIST is a comma-separated list of
2754 keyword options. *Note PAX keywords::, for a detailed discussion.
2758 Synonym for `--format=v7'.
2761 Same as `--format=posix'.
2764 Synonymous with specifying both `--preserve-permissions' and
2765 `--same-order'. *Note Setting Access Permissions::.
2768 (See `--same-order'; *note Reading::.)
2770 `--preserve-permissions'
2771 `--same-permissions'
2773 When `tar' is extracting an archive, it normally subtracts the
2774 users' umask from the permissions specified in the archive and uses
2775 that number as the permissions to create the destination file.
2776 Specifying this option instructs `tar' that it should use the
2777 permissions directly from the archive. *Note Setting Access
2780 `--quote-chars=STRING'
2781 Always quote characters from STRING, even if the selected quoting
2782 style would not quote them (*note quoting styles::).
2784 `--quoting-style=STYLE'
2785 Set quoting style to use when printing member and file names
2786 (*note quoting styles::). Valid STYLE values are: `literal',
2787 `shell', `shell-always', `c', `escape', `locale', and `clocale'.
2788 Default quoting style is `escape', unless overridden while
2789 configuring the package.
2791 `--read-full-records'
2793 Specifies that `tar' should reblock its input, for reading from
2794 pipes on systems with buggy implementations. *Note Reading::.
2796 `--record-size=SIZE[SUF]'
2797 Instructs `tar' to use SIZE bytes per record when accessing the
2798 archive. The argument can be suffixed with a "size suffix", e.g.
2799 `--record-size=10K' for 10 Kilobytes. *Note size-suffixes::, for
2800 a list of valid suffixes. *Note Blocking Factor::, for a detailed
2801 description of this option.
2804 With this option, `tar' recurses into directories (default).
2807 `--recursive-unlink'
2808 Remove existing directory hierarchies before extracting
2809 directories of the same name from the archive. *Note Recursive
2813 Directs `tar' to remove the source file from the file system after
2814 appending it to an archive. *Note remove files::.
2817 Disable use of some potentially harmful `tar' options. Currently
2818 this option disables shell invocation from multi-volume menu
2819 (*note Using Multiple Tapes::).
2822 Notifies `tar' that it should use CMD instead of the default
2823 `/usr/libexec/rmt' (*note Remote Tape Server::).
2826 Notifies `tar' that is should use CMD to communicate with remote
2827 devices. *Note Device::.
2832 This option is an optimization for `tar' when running on machines
2833 with small amounts of memory. It informs `tar' that the list of
2834 file arguments has already been sorted to match the order of files
2835 in the archive. *Note Reading::.
2838 When extracting an archive, `tar' will attempt to preserve the
2839 owner specified in the `tar' archive with this option present.
2840 This is the default behavior for the superuser; this option has an
2841 effect only for ordinary users. *Note Attributes::.
2843 `--same-permissions'
2844 (See `--preserve-permissions'; *note Setting Access Permissions::.)
2848 Assume that the archive media supports seeks to arbitrary
2849 locations. Usually `tar' determines automatically whether the
2850 archive can be seeked or not. This option is intended for use in
2851 cases when such recognition fails. It takes effect only if the
2852 archive is open for reading (e.g. with `--list' or `--extract'
2856 Displays the default options used by `tar' and exits successfully.
2857 This option is intended for use in shell scripts. Here is an
2858 example of what you can see using this option:
2860 $ tar --show-defaults
2861 --format=gnu -f- -b20 --quoting-style=escape
2862 --rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
2864 Notice, that this option outputs only one line. The example output
2865 above has been split to fit page boundaries. *Note defaults::.
2867 `--show-omitted-dirs'
2868 Instructs `tar' to mention the directories it is skipping when
2869 operating on a `tar' archive. *Note show-omitted-dirs::.
2871 `--show-snapshot-field-ranges'
2872 Displays the range of values allowed by this version of `tar' for
2873 each field in the snapshot file, then exits successfully. *Note
2876 `--show-transformed-names'
2877 `--show-stored-names'
2878 Display file or member names after applying any transformations
2879 (*note transform::). In particular, when used in conjunction with
2880 one of the archive creation operations it instructs `tar' to list
2881 the member names stored in the archive, as opposed to the actual
2882 file names. *Note listing member and file names::.
2885 Do not overwrite existing files when extracting files from an
2886 archive. *Note Keep Old Files::.
2888 This option differs from `--keep-old-files' in that it does not
2889 treat such files as an error, instead it just silently avoids
2892 The `--warning=existing-file' option can be used together with
2893 this option to produce warning messages about existing old files
2897 Specify the directory sorting order when reading directories.
2898 ORDER may be one of the following:
2901 No directory sorting is performed. This is the default.
2904 Sort the directory entries on name. The operating system may
2905 deliver directory entries in a more or less random order, and
2906 sorting them makes archive creation reproducible.
2909 Sort the directory entries on inode number. Sorting
2910 directories on inode number may reduce the amount of disk
2911 seek operations when creating an archive for some file
2917 Invokes a GNU extension when adding files to an archive that
2918 handles sparse files efficiently. *Note sparse::.
2920 `--sparse-version=VERSION'
2921 Specifies the "format version" to use when archiving sparse files.
2922 Implies `--sparse'. *Note sparse::. For the description of the
2923 supported sparse formats, *Note Sparse Formats::.
2925 `--starting-file=NAME'
2927 This option affects extraction only; `tar' will skip extracting
2928 files in the archive until it finds one that matches NAME. *Note
2931 `--strip-components=NUMBER'
2932 Strip given NUMBER of leading components from file names before
2933 extraction. For example, if archive `archive.tar' contained
2934 `/some/file/name', then running
2936 tar --extract --file archive.tar --strip-components=2
2938 would extract this file to file `name'.
2941 Alters the suffix `tar' uses when backing up files from the default
2942 `~'. *Note backup::.
2944 `--tape-length=NUM[SUF]'
2946 Specifies the length of tapes that `tar' is writing as being
2947 NUM x 1024 bytes long. If optional SUF is given, it specifies a
2948 multiplicative factor to be used instead of 1024. For example,
2949 `-L2M' means 2 megabytes. *Note size-suffixes::, for a list of
2950 allowed suffixes. *Note Using Multiple Tapes::, for a detailed
2951 discussion of this option.
2954 Reads the volume label. If an argument is specified, test whether
2955 it matches the volume label. *Note --test-label option::.
2957 `--to-command=COMMAND'
2958 During extraction `tar' will pipe extracted files to the standard
2959 input of COMMAND. *Note Writing to an External Program::.
2963 During extraction, `tar' will extract files to stdout rather than
2964 to the file system. *Note Writing to Standard Output::.
2967 Displays the total number of bytes transferred when processing an
2968 archive. If an argument is given, these data are displayed on
2969 request, when signal SIGNO is delivered to `tar'. *Note totals::.
2973 Sets the data modification time of extracted files to the
2974 extraction time, rather than the data modification time stored in
2975 the archive. *Note Data Modification Times::.
2977 `--transform=SED-EXPR'
2979 Transform file or member names using `sed' replacement expression
2980 SED-EXPR. For example,
2982 $ tar cf archive.tar --transform 's,^\./,usr/,' .
2984 will add to `archive' files from the current working directory,
2985 replacing initial `./' prefix with `usr/'. For the detailed
2986 discussion, *Note transform::.
2988 To see transformed member names in verbose listings, use
2989 `--show-transformed-names' option (*note show-transformed-names::).
2992 (See `--compress', *note gzip::)
2995 (See `--gzip', *note gzip::)
2999 Directs `tar' to remove the corresponding file from the file
3000 system before extracting it from the archive. *Note Unlink
3004 Enable unquoting input file or member names (default). *Note
3005 input name quoting::.
3007 `--use-compress-program=PROG'
3009 Instructs `tar' to access the archive through PROG, which is
3010 presumed to be a compression program of some sort. *Note gzip::.
3013 Display file modification dates in UTC. This option implies
3018 Specifies that `tar' should be more verbose about the operations
3019 it is performing. This option can be specified multiple times for
3020 some operations to increase the amount of information displayed.
3025 Verifies that the archive was correctly written when creating an
3026 archive. *Note verify::.
3029 Print information about the program's name, version, origin and
3030 legal status, all on standard output, and then exit successfully.
3034 Used in conjunction with `--multi-volume'. `tar' will keep track
3035 of which volume of a multi-volume archive it is working in FILE.
3039 Enable or disable warning messages identified by KEYWORD. The
3040 messages are suppressed if KEYWORD is prefixed with `no-'. *Note
3044 Use wildcards when matching member names with patterns. *Note
3045 controlling pattern-matching::.
3047 `--wildcards-match-slash'
3048 Wildcards match `/'. *Note controlling pattern-matching::.
3052 Use `xz' for compressing or decompressing the archives. *Note
3056 ---------- Footnotes ----------
3058 (1) Earlier versions of GNU `tar' understood `-l' as a synonym for
3059 `--one-file-system'. The current semantics, which complies to UNIX98,
3060 was introduced with version 1.15.91. *Note Changes::, for more
3064 File: tar.info, Node: Short Option Summary, Prev: Option Summary, Up: All Options
3066 3.4.3 Short Options Cross Reference
3067 -----------------------------------
3069 Here is an alphabetized list of all of the short option forms, matching
3070 them with the equivalent long option.
3072 Short Option Reference
3073 --------------------------------------------------------------------------
3074 -A *note --concatenate::.
3075 -B *note --read-full-records::.
3076 -C *note --directory::.
3077 -F *note --info-script::.
3078 -G *note --incremental::.
3080 -K *note --starting-file::.
3081 -L *note --tape-length::.
3082 -M *note --multi-volume::.
3084 -O *note --to-stdout::.
3085 -P *note --absolute-names::.
3086 -R *note --block-number::.
3087 -S *note --sparse::.
3088 -T *note --files-from::.
3089 -U *note --unlink-first::.
3091 -W *note --verify::.
3092 -X *note --exclude-from::.
3093 -Z *note --compress::.
3094 -b *note --blocking-factor::.
3095 -c *note --create::.
3096 -d *note --compare::.
3098 -g *note --listed-incremental::.
3099 -h *note --dereference::.
3100 -i *note --ignore-zeros::.
3102 -k *note --keep-old-files::.
3103 -l *note --check-links::.
3105 -o When creating, *note --no-same-owner::, when extracting --
3106 *note --portability::.
3108 The latter usage is deprecated. It is retained for
3109 compatibility with the earlier versions of GNU `tar'. In
3110 future releases `-o' will be equivalent to
3111 `--no-same-owner' only.
3112 -p *note --preserve-permissions::.
3113 -r *note --append::.
3114 -s *note --same-order::.
3116 -u *note --update::.
3117 -v *note --verbose::.
3118 -w *note --interactive::.
3119 -x *note --extract::.
3123 File: tar.info, Node: help, Next: defaults, Prev: All Options, Up: tar invocation
3125 3.5 GNU `tar' documentation
3126 ===========================
3128 Being careful, the first thing is really checking that you are using
3129 GNU `tar', indeed. The `--version' option causes `tar' to print
3130 information about its name, version, origin and legal status, all on
3131 standard output, and then exit successfully. For example,
3132 `tar --version' might print:
3135 Copyright (C) 2013-2014 Free Software Foundation, Inc.
3136 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
3137 This is free software: you are free to change and redistribute it.
3138 There is NO WARRANTY, to the extent permitted by law.
3140 Written by John Gilmore and Jay Fenlason.
3142 The first occurrence of `tar' in the result above is the program name
3143 in the package (for example, `rmt' is another program), while the
3144 second occurrence of `tar' is the name of the package itself,
3145 containing possibly many programs. The package is currently named
3146 `tar', after the name of the main program it contains(1).
3148 Another thing you might want to do is checking the spelling or
3149 meaning of some particular `tar' option, without resorting to this
3150 manual, for once you have carefully read it. GNU `tar' has a short
3151 help feature, triggerable through the `--help' option. By using this
3152 option, `tar' will print a usage message listing all available options
3153 on standard output, then exit successfully, without doing anything else
3154 and ignoring all other options. Even if this is only a brief summary,
3155 it may be several screens long. So, if you are not using some kind of
3156 scrollable window, you might prefer to use something like:
3160 presuming, here, that you like using `less' for a pager. Other popular
3161 pagers are `more' and `pg'. If you know about some KEYWORD which
3162 interests you and do not want to read all the `--help' output, another
3163 common idiom is doing:
3165 tar --help | grep KEYWORD
3167 for getting only the pertinent lines. Notice, however, that some `tar'
3168 options have long description lines and the above command will list
3169 only the first of them.
3171 The exact look of the option summary displayed by `tar --help' is
3172 configurable. *Note Configuring Help Summary::, for a detailed
3175 If you only wish to check the spelling of an option, running `tar
3176 --usage' may be a better choice. This will display a terse list of
3177 `tar' options without accompanying explanations.
3179 The short help output is quite succinct, and you might have to get
3180 back to the full documentation for precise points. If you are reading
3181 this paragraph, you already have the `tar' manual in some form. This
3182 manual is available in a variety of forms from
3183 `http://www.gnu.org/software/tar/manual'. It may be printed out of the
3184 GNU `tar' distribution, provided you have TeX already installed
3185 somewhere, and a laser printer around. Just configure the
3186 distribution, execute the command `make dvi', then print `doc/tar.dvi'
3187 the usual way (contact your local guru to know how). If GNU `tar' has
3188 been conveniently installed at your place, this manual is also
3189 available in interactive, hypertextual form as an Info file. Just call
3190 `info tar' or, if you do not have the `info' program handy, use the
3191 Info reader provided within GNU Emacs, calling `tar' from the main Info
3194 There is currently no `man' page for GNU `tar'. If you observe such
3195 a `man' page on the system you are running, either it does not belong
3196 to GNU `tar', or it has not been produced by GNU. Some package
3197 maintainers convert `tar --help' output to a man page, using
3198 `help2man'. In any case, please bear in mind that the authoritative
3199 source of information about GNU `tar' is this Texinfo documentation.
3201 ---------- Footnotes ----------
3203 (1) There are plans to merge the `cpio' and `tar' packages into a
3204 single one which would be called `paxutils'. So, who knows if, one of
3205 this days, the `--version' would not output `tar (GNU paxutils) 3.2'.
3208 File: tar.info, Node: defaults, Next: verbose, Prev: help, Up: tar invocation
3210 3.6 Obtaining GNU `tar' default values
3211 ======================================
3213 GNU `tar' has some predefined defaults that are used when you do not
3214 explicitly specify another values. To obtain a list of such defaults,
3215 use `--show-defaults' option. This will output the values in the form
3216 of `tar' command line options:
3218 $ tar --show-defaults
3219 --format=gnu -f- -b20 --quoting-style=escape
3220 --rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
3222 Notice, that this option outputs only one line. The example output
3223 above has been split to fit page boundaries.
3225 The above output shows that this version of GNU `tar' defaults to using
3226 `gnu' archive format (*note Formats::), it uses standard output as the
3227 archive, if no `--file' option has been given (*note file tutorial::),
3228 the default blocking factor is 20 (*note Blocking Factor::). It also
3229 shows the default locations where `tar' will look for `rmt' and `rsh'
3233 File: tar.info, Node: verbose, Next: checkpoints, Prev: defaults, Up: tar invocation
3235 3.7 Checking `tar' progress
3236 ===========================
3238 Typically, `tar' performs most operations without reporting any
3239 information to the user except error messages. When using `tar' with
3240 many options, particularly ones with complicated or
3241 difficult-to-predict behavior, it is possible to make serious mistakes.
3242 `tar' provides several options that make observing `tar' easier. These
3243 options cause `tar' to print information as it progresses in its job,
3244 and you might want to use them just for being more careful about what
3245 is going on, or merely for entertaining yourself. If you have
3246 encountered a problem when operating on an archive, however, you may
3247 need more information than just an error message in order to solve the
3248 problem. The following options can be helpful diagnostic tools.
3250 Normally, the `--list' (`-t') command to list an archive prints just
3251 the file names (one per line) and the other commands are silent. When
3252 used with most operations, the `--verbose' (`-v') option causes `tar'
3253 to print the name of each file or archive member as it is processed.
3254 This and the other options which make `tar' print status information
3255 can be useful in monitoring `tar'.
3257 With `--create' or `--extract', `--verbose' used once just prints
3258 the names of the files or members as they are processed. Using it
3259 twice causes `tar' to print a longer listing (*Note verbose member
3260 listing::, for the description) for each member. Since `--list'
3261 already prints the names of the members, `--verbose' used once with
3262 `--list' causes `tar' to print an `ls -l' type listing of the files in
3263 the archive. The following examples both extract members with long
3266 $ tar --extract --file=archive.tar --verbose --verbose
3267 $ tar xvvf archive.tar
3269 Verbose output appears on the standard output except when an archive
3270 is being written to the standard output, as with `tar --create --file=-
3271 --verbose' (`tar cvf -', or even `tar cv'--if the installer let
3272 standard output be the default archive). In that case `tar' writes
3273 verbose output to the standard error stream.
3275 If `--index-file=FILE' is specified, `tar' sends verbose output to
3276 FILE rather than to standard output or standard error.
3278 The `--totals' option causes `tar' to print on the standard error
3279 the total amount of bytes transferred when processing an archive. When
3280 creating or appending to an archive, this option prints the number of
3281 bytes written to the archive and the average speed at which they have
3284 $ tar -c -f archive.tar --totals /home
3285 Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
3287 When reading an archive, this option displays the number of bytes
3290 $ tar -x -f archive.tar --totals
3291 Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
3293 Finally, when deleting from an archive, the `--totals' option
3294 displays both numbers plus number of bytes removed from the archive:
3296 $ tar --delete -f foo.tar --totals --wildcards '*~'
3297 Total bytes read: 9543680 (9.2MiB, 201MiB/s)
3298 Total bytes written: 3829760 (3.7MiB, 81MiB/s)
3299 Total bytes deleted: 1474048
3301 You can also obtain this information on request. When `--totals' is
3302 used with an argument, this argument is interpreted as a symbolic name
3303 of a signal, upon delivery of which the statistics is to be printed:
3306 Print statistics upon delivery of signal SIGNO. Valid arguments
3307 are: `SIGHUP', `SIGQUIT', `SIGINT', `SIGUSR1' and `SIGUSR2'.
3308 Shortened names without `SIG' prefix are also accepted.
3310 Both forms of `--totals' option can be used simultaneously. Thus,
3311 `tar -x --totals --totals=USR1' instructs `tar' to extract all members
3312 from its default archive and print statistics after finishing the
3313 extraction, as well as when receiving signal `SIGUSR1'.
3315 The `--checkpoint' option prints an occasional message as `tar'
3316 reads or writes the archive. It is designed for those who don't need
3317 the more detailed (and voluminous) output of `--block-number' (`-R'),
3318 but do want visual confirmation that `tar' is actually making forward
3319 progress. By default it prints a message each 10 records read or
3320 written. This can be changed by giving it a numeric argument after an
3323 $ tar -c --checkpoint=1000 /var
3324 tar: Write checkpoint 1000
3325 tar: Write checkpoint 2000
3326 tar: Write checkpoint 3000
3328 This example shows the default checkpoint message used by `tar'. If
3329 you place a dot immediately after the equal sign, it will print a `.'
3330 at each checkpoint(1). For example:
3332 $ tar -c --checkpoint=.1000 /var
3335 The `--checkpoint' option provides a flexible mechanism for
3336 executing arbitrary actions upon hitting checkpoints, see the next
3337 section (*note checkpoints::), for more information on it.
3339 The `--show-omitted-dirs' option, when reading an archive--with
3340 `--list' or `--extract', for example--causes a message to be printed
3341 for each directory in the archive which is skipped. This happens
3342 regardless of the reason for skipping: the directory might not have
3343 been named on the command line (implicitly or explicitly), it might be
3344 excluded by the use of the `--exclude=PATTERN' option, or some other
3347 If `--block-number' (`-R') is used, `tar' prints, along with every
3348 message it would normally produce, the block number within the archive
3349 where the message was triggered. Also, supplementary messages are
3350 triggered when reading blocks full of NULs, or when hitting end of file
3351 on the archive. As of now, if the archive is properly terminated with
3352 a NUL block, the reading of the file may stop before end of file is
3353 met, so the position of end of file will not usually show when
3354 `--block-number' (`-R') is used. Note that GNU `tar' drains the
3355 archive before exiting when reading the archive from a pipe.
3357 This option is especially useful when reading damaged archives, since
3358 it helps pinpoint the damaged sections. It can also be used with
3359 `--list' (`-t') when listing a file-system backup tape, allowing you to
3360 choose among several backup tapes when retrieving a file later, in
3361 favor of the tape where the file appears earliest (closest to the front
3362 of the tape). *Note backup::.
3364 ---------- Footnotes ----------
3366 (1) This is actually a shortcut for `--checkpoint=N
3367 --checkpoint-action=dot'. *Note dot: checkpoints.
3370 File: tar.info, Node: checkpoints, Next: warnings, Prev: verbose, Up: tar invocation
3375 A "checkpoint" is a moment of time before writing Nth record to the
3376 archive (a "write checkpoint"), or before reading Nth record from the
3377 archive (a "read checkpoint"). Checkpoints allow to periodically
3378 execute arbitrary actions.
3380 The checkpoint facility is enabled using the following option:
3383 Schedule checkpoints before writing or reading each Nth record.
3384 The default value for N is 10.
3386 A list of arbitrary "actions" can be executed at each checkpoint.
3387 These actions include: pausing, displaying textual messages, and
3388 executing arbitrary external programs. Actions are defined using the
3389 `--checkpoint-action' option.
3391 `--checkpoint-action=ACTION'
3392 Execute an ACTION at each checkpoint.
3394 The simplest value of ACTION is `echo'. It instructs `tar' to
3395 display the default message on the standard error stream upon arriving
3396 at each checkpoint. The default message is (in POSIX locale) `Write
3397 checkpoint N', for write checkpoints, and `Read checkpoint N', for read
3398 checkpoints. Here, N represents ordinal number of the checkpoint.
3400 In another locales, translated versions of this message are used.
3402 This is the default action, so running:
3404 $ tar -c --checkpoint=1000 --checkpoint-action=echo /var
3408 $ tar -c --checkpoint=1000 /var
3410 The `echo' action also allows to supply a customized message. You
3411 do so by placing an equals sign and the message right after it, e.g.:
3413 --checkpoint-action="echo=Hit %s checkpoint #%u"
3415 The `%s' and `%u' in the above example are "format specifiers". The
3416 `%s' specifier is replaced with the "type" of the checkpoint: `write' or
3417 `read' (or a corresponding translated version in locales other than
3418 POSIX). The `%u' specifier is replaced with the ordinal number of the
3419 checkpoint. Thus, the above example could produce the following output
3420 when used with the `--create' option:
3422 tar: Hit write checkpoint #10
3423 tar: Hit write checkpoint #20
3424 tar: Hit write checkpoint #30
3426 The complete list of available format specifiers follows. Some of
3427 them can take optional arguments. These arguments, if given, are
3428 supplied in curly braces between the percent sign and the specifier
3432 Print type of the checkpoint (`write' or `read').
3435 Print number of the checkpoint.
3438 Print number of bytes transferred so far and approximate transfer
3439 speed. Optional arguments supply prefixes to be used before number
3440 of bytes read, written and deleted, correspondingly. If absent,
3441 they default to `R'. `W', `D'. Any or all of them can be omitted,
3442 so, that e.g. `%{}T' means to print corresponding statistics
3443 without any prefixes. Any surplus arguments, if present, are
3446 $ tar --delete -f f.tar --checkpoint-action=echo="#%u: %T" main.c
3447 tar: #1: R: 0 (0B, 0B/s),W: 0 (0B, 0B/s),D: 0
3448 tar: #2: R: 10240 (10KiB, 19MiB/s),W: 0 (0B, 0B/s),D: 10240
3450 See also the `totals' action, described below.
3453 Output current local time using FMT as format for `strftime'
3454 (*note strftime: (strftime(3))strftime.). The `{FMT}' part is
3455 optional. If not present, the default format is `%c', i.e. the
3456 preferred date and time representation for the current locale.
3459 Pad output with spaces to the Nth column. If the `{N}' part is
3460 omitted, the current screen width is assumed.
3463 This is a shortcut for `%{%Y-%m-%d %H:%M:%S}t: %ds,
3464 %{read,wrote}T%*\r', intended mainly for use with `ttyout' action
3467 Aside from format expansion, the message string is subject to
3468 "unquoting", during which the backslash "escape sequences" are replaced
3469 with their corresponding ASCII characters (*note escape sequences::).
3470 E.g. the following action will produce an audible bell and the message
3471 described above at each checkpoint:
3473 --checkpoint-action='echo=\aHit %s checkpoint #%u'
3475 There is also a special action which produces an audible signal:
3476 `bell'. It is not equivalent to `echo='\a'', because `bell' sends the
3477 bell directly to the console (`/dev/tty'), whereas `echo='\a'' sends it
3478 to the standard error.
3480 The `ttyout=STRING' action outputs STRING to `/dev/tty', so it can
3481 be used even if the standard output is redirected elsewhere. The
3482 STRING is subject to the same modifications as with `echo' action. In
3483 contrast to the latter, `ttyout' does not prepend `tar' executable name
3484 to the string, nor does it output a newline after it. For example, the
3485 following action will print the checkpoint message at the same screen
3486 line, overwriting any previous message:
3488 --checkpoint-action="ttyout=Hit %s checkpoint #%u%*\r"
3490 Notice the use of `%*' specifier to clear out any eventual remains of
3491 the prior output line. As as more complex example, consider this:
3493 --checkpoint-action=ttyout='%{%Y-%m-%d %H:%M:%S}t (%d sec): #%u, %T%*\r'
3495 This prints the current local time, number of seconds expired since tar
3496 was started, the checkpoint ordinal number, transferred bytes and
3497 average computed I/O speed.
3499 Another available checkpoint action is `dot' (or `.'). It instructs
3500 `tar' to print a single dot on the standard listing stream, e.g.:
3502 $ tar -c --checkpoint=1000 --checkpoint-action=dot /var
3505 For compatibility with previous GNU `tar' versions, this action can
3506 be abbreviated by placing a dot in front of the checkpoint frequency,
3507 as shown in the previous section.
3509 The `totals' action prints the total number of bytes transferred so
3510 far. The format of the data is the same as for the `--totals' option
3511 (*note totals::). See also `%T' format specifier of the `echo' or
3514 Yet another action, `sleep', pauses `tar' for a specified amount of
3515 seconds. The following example will stop for 30 seconds at each
3518 $ tar -c --checkpoint=1000 --checkpoint-action=sleep=30
3520 Finally, the `exec' action executes a given external command. For
3523 $ tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint
3525 The supplied command can be any valid command invocation, with or
3526 without additional command line arguments. If it does contain
3527 arguments, don't forget to quote it to prevent it from being split by
3528 the shell. *Note Running External Commands: external, for more detail.
3530 The command gets a copy of `tar''s environment plus the following
3534 GNU `tar' version number.
3537 The name of the archive `tar' is processing.
3539 `TAR_BLOCKING_FACTOR'
3540 Current blocking factor (*note Blocking::).
3543 Number of the checkpoint.
3546 A short option describing the operation `tar' is executing. *Note
3547 Operations::, for a complete list of subcommand options.
3550 Format of the archive being processed. *Note Formats::, for a
3551 complete list of archive format names.
3553 These environment variables can also be passed as arguments to the
3554 command, provided that they are properly escaped, for example:
3557 --checkpoint-action='exec=/sbin/cpoint $TAR_FILENAME'
3559 Notice single quotes to prevent variable names from being expanded by
3560 the shell when invoking `tar'.
3562 Any number of actions can be defined, by supplying several
3563 `--checkpoint-action' options in the command line. For example, the
3564 command below displays two messages, pauses execution for 30 seconds
3565 and executes the `/sbin/cpoint' script:
3567 $ tar -c -f arc.tar \
3568 --checkpoint-action='\aecho=Hit %s checkpoint #%u' \
3569 --checkpoint-action='echo=Sleeping for 30 seconds' \
3570 --checkpoint-action='sleep=30' \
3571 --checkpoint-action='exec=/sbin/cpoint'
3573 This example also illustrates the fact that `--checkpoint-action'
3574 can be used without `--checkpoint'. In this case, the default
3575 checkpoint frequency (at each 10th record) is assumed.
3578 File: tar.info, Node: warnings, Next: interactive, Prev: checkpoints, Up: tar invocation
3580 3.9 Controlling Warning Messages
3581 ================================
3583 Sometimes, while performing the requested task, GNU `tar' notices some
3584 conditions that are not exactly errors, but which the user should be
3585 aware of. When this happens, `tar' issues a "warning message"
3586 describing the condition. Warning messages are output to the standard
3587 error and they do not affect the exit code of `tar' command.
3589 GNU `tar' allows the user to suppress some or all of its warning
3593 Control display of the warning messages identified by KEYWORD. If
3594 KEYWORD starts with the prefix `no-', such messages are
3595 suppressed. Otherwise, they are enabled.
3597 Multiple `--warning' messages accumulate.
3599 The tables below list allowed values for KEYWORD along with the
3600 warning messages they control.
3602 Keywords controlling `tar' operation
3603 ------------------------------------
3606 Enable all warning messages. This is the default.
3609 Disable all warning messages.
3612 `%s: file name read contains nul character'
3615 `A lone zero block at %s'
3617 Keywords applicable for `tar --create'
3618 --------------------------------------
3621 `%s: contains a cache directory tag %s; %s'
3624 `%s: File shrank by %s bytes; padding with zeros'
3627 `%s: file is on a different filesystem; not dumped'
3630 `%s: Unknown file type; file ignored'
3631 `%s: socket ignored'
3635 `%s: file is unchanged; not dumped'
3638 `%s: file is the archive; not dumped'
3641 `%s: File removed before we read it'
3644 `%s: file changed as we read it'
3646 Keywords applicable for `tar --extract'
3647 ---------------------------------------
3650 `%s: implausibly old time stamp %s'
3651 `%s: time stamp %s is %s s in the future'
3654 `Extracting contiguous files as regular files'
3657 `Attempting extraction of symbolic links as hard links'
3660 `%s: Unknown file type '%c', extracted as normal file'
3663 `Current %s is newer or same age'
3666 `Ignoring unknown extended header keyword '%s''
3669 Controls verbose description of failures occurring when trying to
3670 run alternative decompressor programs (*note alternative
3671 decompression programs::). This warning is disabled by default
3672 (unless `--verbose' is used). A common example of what you can get
3673 when using this warning is:
3675 $ tar --warning=decompress-program -x -f archive.Z
3676 tar (child): cannot run compress: No such file or directory
3677 tar (child): trying gzip
3679 This means that `tar' first tried to decompress `archive.Z' using
3680 `compress', and, when that failed, switched to `gzip'.
3683 `Record size = %lu blocks'
3685 Keywords controlling incremental extraction:
3686 --------------------------------------------
3689 `%s: Directory has been renamed from %s'
3690 `%s: Directory has been renamed'
3693 `%s: Directory is new'
3696 `%s: directory is on a different device: not purging'
3699 `Malformed dumpdir: 'X' never used'
3702 File: tar.info, Node: interactive, Next: external, Prev: warnings, Up: tar invocation
3704 3.10 Asking for Confirmation During Operations
3705 ==============================================
3707 Typically, `tar' carries out a command without stopping for further
3708 instructions. In some situations however, you may want to exclude some
3709 files and archive members from the operation (for instance if disk or
3710 storage space is tight). You can do this by excluding certain files
3711 automatically (*note Choosing::), or by performing an operation
3712 interactively, using the `--interactive' (`-w') option. `tar' also
3713 accepts `--confirmation' for this option.
3715 When the `--interactive' (`-w') option is specified, before reading,
3716 writing, or deleting files, `tar' first prints a message for each such
3717 file, telling what operation it intends to take, then asks for
3718 confirmation on the terminal. The actions which require confirmation
3719 include adding a file to the archive, extracting a file from the
3720 archive, deleting a file from the archive, and deleting a file from
3721 disk. To confirm the action, you must type a line of input beginning
3722 with `y'. If your input line begins with anything other than `y',
3723 `tar' skips that file.
3725 If `tar' is reading the archive from the standard input, `tar' opens
3726 the file `/dev/tty' to support the interactive communications.
3728 Verbose output is normally sent to standard output, separate from
3729 other error messages. However, if the archive is produced directly on
3730 standard output, then verbose output is mixed with errors on `stderr'.
3731 Producing the archive on standard output may be used as a way to avoid
3732 using disk space, when the archive is soon to be consumed by another
3733 process reading it, say. Some people felt the need of producing an
3734 archive on stdout, still willing to segregate between verbose output
3735 and error output. A possible approach would be using a named pipe to
3736 receive the archive, and having the consumer process to read from that
3737 named pipe. This has the advantage of letting standard output free to
3738 receive verbose output, all separate from errors.
3741 File: tar.info, Node: external, Prev: interactive, Up: tar invocation
3743 3.11 Running External Commands
3744 ==============================
3746 Certain GNU `tar' operations imply running external commands that you
3747 supply on the command line. One of such operations is checkpointing,
3748 described above (*note checkpoint exec::). Another example of this
3749 feature is the `-I' option, which allows you to supply the program to
3750 use for compressing or decompressing the archive (*note
3751 use-compress-program::).
3753 Whenever such operation is requested, `tar' first splits the
3754 supplied command into words much like the shell does. It then treats
3755 the first word as the name of the program or the shell script to execute
3756 and the rest of words as its command line arguments. The program,
3757 unless given as an absolute file name, is searched in the shell's
3760 Any additional information is normally supplied to external commands
3761 in environment variables, specific to each particular operation. For
3762 example, the `--checkpoint-action=exec' option, defines the
3763 `TAR_ARCHIVE' variable to the name of the archive being worked upon.
3764 You can, should the need be, use these variables in the command line of
3765 the external command. For example:
3767 $ tar -x -f archive.tar \
3768 --checkpoint=exec='printf "%04d in %32s\r" $TAR_CHECKPOINT $TAR_ARCHIVE'
3770 This command prints for each checkpoint its number and the name of the
3771 archive, using the same output line on the screen.
3773 Notice the use of single quotes to prevent variable names from being
3774 expanded by the shell when invoking `tar'.
3777 File: tar.info, Node: operations, Next: Backups, Prev: tar invocation, Up: Top
3779 4 GNU `tar' Operations
3780 **********************
3793 File: tar.info, Node: Basic tar, Next: Advanced tar, Up: operations
3795 4.1 Basic GNU `tar' Operations
3796 ==============================
3798 The basic `tar' operations, `--create' (`-c'), `--list' (`-t') and
3799 `--extract' (`--get', `-x'), are currently presented and described in
3800 the tutorial chapter of this manual. This section provides some
3801 complementary notes for these operations.
3805 Creating an empty archive would have some kind of elegance. One
3806 can initialize an empty archive and later use `--append' (`-r')
3807 for adding all members. Some applications would not welcome
3808 making an exception in the way of adding the first archive member.
3809 On the other hand, many people reported that it is dangerously too
3810 easy for `tar' to destroy a magnetic tape with an empty
3811 archive(1). The two most common errors are:
3813 1. Mistakingly using `create' instead of `extract', when the
3814 intent was to extract the full contents of an archive. This
3815 error is likely: keys `c' and `x' are right next to each
3816 other on the QWERTY keyboard. Instead of being unpacked, the
3817 archive then gets wholly destroyed. When users speak about
3818 "exploding" an archive, they usually mean something else :-).
3820 2. Forgetting the argument to `file', when the intent was to
3821 create an archive with a single file in it. This error is
3822 likely because a tired user can easily add the `f' key to the
3823 cluster of option letters, by the mere force of habit,
3824 without realizing the full consequence of doing so. The
3825 usual consequence is that the single file, which was meant to
3826 be saved, is rather destroyed.
3828 So, recognizing the likelihood and the catastrophic nature of these
3829 errors, GNU `tar' now takes some distance from elegance, and
3830 cowardly refuses to create an archive when `--create' option is
3831 given, there are no arguments besides options, and `--files-from'
3832 (`-T') option is _not_ used. To get around the cautiousness of
3833 GNU `tar' and nevertheless create an archive with nothing in it,
3834 one may still use, as the value for the `--files-from' option, a
3835 file with no names in it, as shown in the following commands:
3837 tar --create --file=empty-archive.tar --files-from=/dev/null
3838 tar -cf empty-archive.tar -T /dev/null
3843 A socket is stored, within a GNU `tar' archive, as a pipe.
3846 GNU `tar' now shows dates as `1996-08-30', while it used to show
3847 them as `Aug 30 1996'. Preferably, people should get used to ISO
3848 8601 dates. Local American dates should be made available again
3849 with full date localization support, once ready. In the meantime,
3850 programs not being localizable for dates should prefer
3851 international dates, that's really the way to go.
3853 Look up `http://www.cl.cam.ac.uk/~mgk25/iso-time.html' if you are
3854 curious, it contains a detailed explanation of the ISO 8601
3858 ---------- Footnotes ----------
3860 (1) This is well described in `Unix-haters Handbook', by Simson
3861 Garfinkel, Daniel Weise & Steven Strassmann, IDG Books, ISBN
3865 File: tar.info, Node: Advanced tar, Next: create options, Prev: Basic tar, Up: operations
3867 4.2 Advanced GNU `tar' Operations
3868 =================================
3870 Now that you have learned the basics of using GNU `tar', you may want
3871 to learn about further ways in which `tar' can help you.
3873 This chapter presents five, more advanced operations which you
3874 probably won't use on a daily basis, but which serve more specialized
3875 functions. We also explain the different styles of options and why you
3876 might want to use one or another, or a combination of them in your `tar'
3877 commands. Additionally, this chapter includes options which allow you
3878 to define the output from `tar' more carefully, and provide help and
3879 error correction in special circumstances.
3891 File: tar.info, Node: Operations, Next: append, Up: Advanced tar
3893 4.2.1 The Five Advanced `tar' Operations
3894 ----------------------------------------
3896 In the last chapter, you learned about the first three operations to
3897 `tar'. This chapter presents the remaining five operations to `tar':
3898 `--append', `--update', `--concatenate', `--delete', and `--compare'.
3900 You are not likely to use these operations as frequently as those
3901 covered in the last chapter; however, since they perform specialized
3902 functions, they are quite useful when you do need to use them. We will
3903 give examples using the same directory and files that you created in
3904 the last chapter. As you may recall, the directory is called
3905 `practice', the files are `jazz', `blues', `folk', and the two archive
3906 files you created are `collection.tar' and `music.tar'.
3908 We will also use the archive files `afiles.tar' and `bfiles.tar'.
3909 The archive `afiles.tar' contains the members `apple', `angst', and
3910 `aspic'; `bfiles.tar' contains the members `./birds', `baboon', and
3913 Unless we state otherwise, all practicing you do and examples you
3914 follow in this chapter will take place in the `practice' directory that
3915 you created in the previous chapter; see *note prepare for examples::.
3916 (Below in this section, we will remind you of the state of the examples
3917 where the last chapter left them.)
3919 The five operations that we will cover in this chapter are:
3923 Add new entries to an archive that already exists.
3927 Add more recent copies of archive members to the end of an
3928 archive, if they exist.
3933 Add one or more pre-existing archives to the end of another
3937 Delete items from an archive (does not work on tapes).
3942 Compare archive members to their counterparts in the file system.
3945 File: tar.info, Node: append, Next: update, Prev: Operations, Up: Advanced tar
3947 4.2.2 How to Add Files to Existing Archives: `--append'
3948 -------------------------------------------------------
3950 If you want to add files to an existing archive, you don't need to
3951 create a new archive; you can use `--append' (`-r'). The archive must
3952 already exist in order to use `--append'. (A related operation is the
3953 `--update' operation; you can use this to add newer versions of archive
3954 members to an existing archive. To learn how to do this with
3955 `--update', *note update::.)
3957 If you use `--append' to add a file that has the same name as an
3958 archive member to an archive containing that archive member, then the
3959 old member is not deleted. What does happen, however, is somewhat
3960 complex. `tar' _allows_ you to have infinite number of files with the
3961 same name. Some operations treat these same-named members no
3962 differently than any other set of archive members: for example, if you
3963 view an archive with `--list' (`-t'), you will see all of those members
3964 listed, with their data modification times, owners, etc.
3966 Other operations don't deal with these members as perfectly as you
3967 might prefer; if you were to use `--extract' to extract the archive,
3968 only the most recently added copy of a member with the same name as
3969 other members would end up in the working directory. This is because
3970 `--extract' extracts an archive in the order the members appeared in
3971 the archive; the most recently archived members will be extracted last.
3972 Additionally, an extracted member will _replace_ a file of the same
3973 name which existed in the directory already, and `tar' will not prompt
3974 you about this(1). Thus, only the most recently archived member will
3975 end up being extracted, as it will replace the one extracted before it,
3978 There exists a special option that allows you to get around this
3979 behavior and extract (or list) only a particular copy of the file.
3980 This is `--occurrence' option. If you run `tar' with this option, it
3981 will extract only the first copy of the file. You may also give this
3982 option an argument specifying the number of copy to be extracted.
3983 Thus, for example if the archive `archive.tar' contained three copies
3984 of file `myfile', then the command
3986 tar --extract --file archive.tar --occurrence=2 myfile
3988 would extract only the second copy. *Note --occurrence: Option
3989 Summary, for the description of `--occurrence' option.
3991 If you want to replace an archive member, use `--delete' to delete
3992 the member you want to remove from the archive, and then use `--append'
3993 to add the member you want to be in the archive. Note that you can not
3994 change the order of the archive; the most recently added member will
3995 still appear last. In this sense, you cannot truly "replace" one
3996 member with another. (Replacing one member with another will not work
3997 on certain types of media, such as tapes; see *note delete:: and *note
3998 Media::, for more information.)
4002 * appending files:: Appending Files to an Archive
4005 ---------- Footnotes ----------
4007 (1) Unless you give it `--keep-old-files' (or `--skip-old-files')
4008 option, or the disk copy is newer than the one in the archive and you
4009 invoke `tar' with `--keep-newer-files' option.
4012 File: tar.info, Node: appending files, Next: multiple, Up: append
4014 4.2.2.1 Appending Files to an Archive
4015 .....................................
4017 The simplest way to add a file to an already existing archive is the
4018 `--append' (`-r') operation, which writes specified files into the
4019 archive whether or not they are already among the archived files.
4021 When you use `--append', you _must_ specify file name arguments, as
4022 there is no default. If you specify a file that already exists in the
4023 archive, another copy of the file will be added to the end of the
4024 archive. As with other operations, the member names of the newly added
4025 files will be exactly the same as their names given on the command
4026 line. The `--verbose' (`-v') option will print out the names of the
4027 files as they are written into the archive.
4029 `--append' cannot be performed on some tape drives, unfortunately,
4030 due to deficiencies in the formats those tape drives use. The archive
4031 must be a valid `tar' archive, or else the results of using this
4032 operation will be unpredictable. *Note Media::.
4034 To demonstrate using `--append' to add a file to an archive, create
4035 a file called `rock' in the `practice' directory. Make sure you are in
4036 the `practice' directory. Then, run the following `tar' command to add
4037 `rock' to `collection.tar':
4039 $ tar --append --file=collection.tar rock
4041 If you now use the `--list' (`-t') operation, you will see that `rock'
4042 has been added to the archive:
4044 $ tar --list --file=collection.tar
4045 -rw-r--r-- me/user 28 1996-10-18 16:31 jazz
4046 -rw-r--r-- me/user 21 1996-09-23 16:44 blues
4047 -rw-r--r-- me/user 20 1996-09-23 16:44 folk
4048 -rw-r--r-- me/user 20 1996-09-23 16:44 rock
4051 File: tar.info, Node: multiple, Prev: appending files, Up: append
4053 4.2.2.2 Multiple Members with the Same Name
4054 ...........................................
4056 You can use `--append' (`-r') to add copies of files which have been
4057 updated since the archive was created. (However, we do not recommend
4058 doing this since there is another `tar' option called `--update'; *Note
4059 update::, for more information. We describe this use of `--append'
4060 here for the sake of completeness.) When you extract the archive, the
4061 older version will be effectively lost. This works because files are
4062 extracted from an archive in the order in which they were archived.
4063 Thus, when the archive is extracted, a file archived later in time will
4064 replace a file of the same name which was archived earlier, even though
4065 the older version of the file will remain in the archive unless you
4066 delete all versions of the file.
4068 Supposing you change the file `blues' and then append the changed
4069 version to `collection.tar'. As you saw above, the original `blues' is
4070 in the archive `collection.tar'. If you change the file and append the
4071 new version of the file to the archive, there will be two copies in the
4072 archive. When you extract the archive, the older version of the file
4073 will be extracted first, and then replaced by the newer version when it
4076 You can append the new, changed copy of the file `blues' to the
4077 archive in this way:
4079 $ tar --append --verbose --file=collection.tar blues
4082 Because you specified the `--verbose' option, `tar' has printed the
4083 name of the file being appended as it was acted on. Now list the
4084 contents of the archive:
4086 $ tar --list --verbose --file=collection.tar
4087 -rw-r--r-- me/user 28 1996-10-18 16:31 jazz
4088 -rw-r--r-- me/user 21 1996-09-23 16:44 blues
4089 -rw-r--r-- me/user 20 1996-09-23 16:44 folk
4090 -rw-r--r-- me/user 20 1996-09-23 16:44 rock
4091 -rw-r--r-- me/user 58 1996-10-24 18:30 blues
4093 The newest version of `blues' is now at the end of the archive (note
4094 the different creation dates and file sizes). If you extract the
4095 archive, the older version of the file `blues' will be replaced by the
4096 newer version. You can confirm this by extracting the archive and
4097 running `ls' on the directory.
4099 If you wish to extract the first occurrence of the file `blues' from
4100 the archive, use `--occurrence' option, as shown in the following
4103 $ tar --extract -vv --occurrence --file=collection.tar blues
4104 -rw-r--r-- me/user 21 1996-09-23 16:44 blues
4106 *Note Writing::, for more information on `--extract' and see *note
4107 -occurrence: Option Summary, for a description of `--occurrence' option.
4110 File: tar.info, Node: update, Next: concatenate, Prev: append, Up: Advanced tar
4112 4.2.3 Updating an Archive
4113 -------------------------
4115 In the previous section, you learned how to use `--append' to add a
4116 file to an existing archive. A related operation is `--update' (`-u').
4117 The `--update' operation updates a `tar' archive by comparing the date
4118 of the specified archive members against the date of the file with the
4119 same name. If the file has been modified more recently than the
4120 archive member, then the newer version of the file is added to the
4121 archive (as with `--append').
4123 Unfortunately, you cannot use `--update' with magnetic tape drives.
4124 The operation will fail.
4126 Both `--update' and `--append' work by adding to the end of the
4127 archive. When you extract a file from the archive, only the version
4128 stored last will wind up in the file system, unless you use the
4129 `--backup' option. *Note multiple::, for a detailed discussion.
4136 File: tar.info, Node: how to update, Up: update
4138 4.2.3.1 How to Update an Archive Using `--update'
4139 .................................................
4141 You must use file name arguments with the `--update' (`-u') operation.
4142 If you don't specify any files, `tar' won't act on any files and won't
4143 tell you that it didn't do anything (which may end up confusing you).
4145 To see the `--update' option at work, create a new file,
4146 `classical', in your practice directory, and some extra text to the
4147 file `blues', using any text editor. Then invoke `tar' with the
4148 `update' operation and the `--verbose' (`-v') option specified, using
4149 the names of all the files in the `practice' directory as file name
4152 $ tar --update -v -f collection.tar blues folk rock classical
4157 Because we have specified verbose mode, `tar' prints out the names of
4158 the files it is working on, which in this case are the names of the
4159 files that needed to be updated. If you run `tar --list' and look at
4160 the archive, you will see `blues' and `classical' at its end. There
4161 will be a total of two versions of the member `blues'; the one at the
4162 end will be newer and larger, since you added text before updating it.
4164 The reason `tar' does not overwrite the older file when updating it
4165 is because writing to the middle of a section of tape is a difficult
4166 process. Tapes are not designed to go backward. *Note Media::, for
4167 more information about tapes.
4169 `--update' (`-u') is not suitable for performing backups for two
4170 reasons: it does not change directory content entries, and it lengthens
4171 the archive every time it is used. The GNU `tar' options intended
4172 specifically for backups are more efficient. If you need to run
4173 backups, please consult *note Backups::.
4176 File: tar.info, Node: concatenate, Next: delete, Prev: update, Up: Advanced tar
4178 4.2.4 Combining Archives with `--concatenate'
4179 ---------------------------------------------
4181 Sometimes it may be convenient to add a second archive onto the end of
4182 an archive rather than adding individual files to the archive. To add
4183 one or more archives to the end of another archive, you should use the
4184 `--concatenate' (`--catenate', `-A') operation.
4186 To use `--concatenate', give the first archive with `--file' option
4187 and name the rest of archives to be concatenated on the command line.
4188 The members, and their member names, will be copied verbatim from those
4189 archives to the first one(1). The new, concatenated archive will be
4190 called by the same name as the one given with the `--file' option. As
4191 usual, if you omit `--file', `tar' will use the value of the environment
4192 variable `TAPE', or, if this has not been set, the default archive name.
4194 To demonstrate how `--concatenate' works, create two small archives
4195 called `bluesrock.tar' and `folkjazz.tar', using the relevant files
4198 $ tar -cvf bluesrock.tar blues rock
4201 $ tar -cvf folkjazz.tar folk jazz
4205 If you like, You can run `tar --list' to make sure the archives contain
4206 what they are supposed to:
4208 $ tar -tvf bluesrock.tar
4209 -rw-r--r-- melissa/user 105 1997-01-21 19:42 blues
4210 -rw-r--r-- melissa/user 33 1997-01-20 15:34 rock
4211 $ tar -tvf jazzfolk.tar
4212 -rw-r--r-- melissa/user 20 1996-09-23 16:44 folk
4213 -rw-r--r-- melissa/user 65 1997-01-30 14:15 jazz
4215 We can concatenate these two archives with `tar':
4218 $ tar --concatenate --file=bluesrock.tar jazzfolk.tar
4220 If you now list the contents of the `bluesrock.tar', you will see
4221 that now it also contains the archive members of `jazzfolk.tar':
4223 $ tar --list --file=bluesrock.tar
4229 When you use `--concatenate', the source and target archives must
4230 already exist and must have been created using compatible format
4231 parameters. Notice, that `tar' does not check whether the archives it
4232 concatenates have compatible formats, it does not even check if the
4233 files are really tar archives.
4235 Like `--append' (`-r'), this operation cannot be performed on some
4236 tape drives, due to deficiencies in the formats those tape drives use.
4238 It may seem more intuitive to you to want or try to use `cat' to
4239 concatenate two archives instead of using the `--concatenate'
4240 operation; after all, `cat' is the utility for combining files.
4242 However, `tar' archives incorporate an end-of-file marker which must
4243 be removed if the concatenated archives are to be read properly as one
4244 archive. `--concatenate' removes the end-of-archive marker from the
4245 target archive before each new archive is appended. If you use `cat'
4246 to combine the archives, the result will not be a valid `tar' format
4247 archive. If you need to retrieve files from an archive that was added
4248 to using the `cat' utility, use the `--ignore-zeros' (`-i') option.
4249 *Note Ignore Zeros::, for further information on dealing with archives
4250 improperly combined using the `cat' shell utility.
4252 ---------- Footnotes ----------
4254 (1) This can cause multiple members to have the same name. For
4255 information on how this affects reading the archive, see *note
4259 File: tar.info, Node: delete, Next: compare, Prev: concatenate, Up: Advanced tar
4261 4.2.5 Removing Archive Members Using `--delete'
4262 -----------------------------------------------
4264 You can remove members from an archive by using the `--delete' option.
4265 Specify the name of the archive with `--file' (`-f') and then specify
4266 the names of the members to be deleted; if you list no member names,
4267 nothing will be deleted. The `--verbose' option will cause `tar' to
4268 print the names of the members as they are deleted. As with
4269 `--extract', you must give the exact member names when using `tar
4270 --delete'. `--delete' will remove all versions of the named file from
4271 the archive. The `--delete' operation can run very slowly.
4273 Unlike other operations, `--delete' has no short form.
4275 This operation will rewrite the archive. You can only use
4276 `--delete' on an archive if the archive device allows you to write to
4277 any point on the media, such as a disk; because of this, it does not
4278 work on magnetic tapes. Do not try to delete an archive member from a
4279 magnetic tape; the action will not succeed, and you will be likely to
4280 scramble the archive and damage your tape. There is no safe way
4281 (except by completely re-writing the archive) to delete files from most
4282 kinds of magnetic tape. *Note Media::.
4284 To delete all versions of the file `blues' from the archive
4285 `collection.tar' in the `practice' directory, make sure you are in that
4286 directory, and then,
4288 $ tar --list --file=collection.tar
4293 $ tar --delete --file=collection.tar blues
4294 $ tar --list --file=collection.tar
4299 The `--delete' option has been reported to work properly when `tar'
4300 acts as a filter from `stdin' to `stdout'.
4303 File: tar.info, Node: compare, Prev: delete, Up: Advanced tar
4305 4.2.6 Comparing Archive Members with the File System
4306 ----------------------------------------------------
4308 The `--compare' (`-d'), or `--diff' operation compares specified
4309 archive members against files with the same names, and then reports
4310 differences in file size, mode, owner, modification date and contents.
4311 You should _only_ specify archive member names, not file names. If you
4312 do not name any members, then `tar' will compare the entire archive.
4313 If a file is represented in the archive but does not exist in the file
4314 system, `tar' reports a difference.
4316 You have to specify the record size of the archive when modifying an
4317 archive with a non-default record size.
4319 `tar' ignores files in the file system that do not have
4320 corresponding members in the archive.
4322 The following example compares the archive members `rock', `blues'
4323 and `funk' in the archive `bluesrock.tar' with files of the same name
4324 in the file system. (Note that there is no file, `funk'; `tar' will
4325 report an error message.)
4327 $ tar --compare --file=bluesrock.tar rock blues funk
4330 tar: funk not found in archive
4332 The spirit behind the `--compare' (`--diff', `-d') option is to
4333 check whether the archive represents the current state of files on
4334 disk, more than validating the integrity of the archive media. For
4335 this latter goal, see *note verify::.
4338 File: tar.info, Node: create options, Next: extract options, Prev: Advanced tar, Up: operations
4340 4.3 Options Used by `--create'
4341 ==============================
4343 The previous chapter described the basics of how to use `--create'
4344 (`-c') to create an archive from a set of files. *Note create::. This
4345 section described advanced options to be used with `--create'.
4349 * override:: Overriding File Metadata.
4350 * Ignore Failed Read::
4353 File: tar.info, Node: override, Next: Ignore Failed Read, Up: create options
4355 4.3.1 Overriding File Metadata
4356 ------------------------------
4358 As described above, a `tar' archive keeps, for each member it contains,
4359 its "metadata", such as modification time, mode and ownership of the
4360 file. GNU `tar' allows to replace these data with other values when
4361 adding files to the archive. The options described in this section
4362 affect creation of archives of any type. For POSIX archives, see also
4363 *note PAX keywords::, for additional ways of controlling metadata,
4364 stored in the archive.
4366 `--mode=PERMISSIONS'
4367 When adding files to an archive, `tar' will use PERMISSIONS for
4368 the archive members, rather than the permissions from the files.
4369 PERMISSIONS can be specified either as an octal number or as
4370 symbolic permissions, like with `chmod' (*Note Permissions:
4371 (fileutils)File permissions. This reference also has useful
4372 information for those not being overly familiar with the UNIX
4373 permission system). Using latter syntax allows for more
4374 flexibility. For example, the value `a+rw' adds read and write
4375 permissions for everybody, while retaining executable bits on
4376 directories or on any other file already marked as executable:
4378 $ tar -c -f archive.tar --mode='a+rw' .
4381 When adding files to an archive, `tar' will use DATE as the
4382 modification time of members when creating archives, instead of
4383 their actual modification times. The argument DATE can be either
4384 a textual date representation in almost arbitrary format (*note
4385 Date input formats::) or a name of an existing file, starting with
4386 `/' or `.'. In the latter case, the modification time of that
4389 The following example will set the modification date to 00:00:00,
4392 $ tar -c -f archive.tar --mtime='1970-01-01' .
4394 When used with `--verbose' (*note verbose tutorial::) GNU `tar'
4395 will try to convert the specified date back to its textual
4396 representation and compare it with the one given with `--mtime'
4397 options. If the two dates differ, `tar' will print a warning
4398 saying what date it will use. This is to help user ensure he is
4399 using the right date.
4403 $ tar -c -f archive.tar -v --mtime=yesterday .
4404 tar: Option --mtime: Treating date 'yesterday' as 2006-06-20
4409 Specifies that `tar' should use USER as the owner of members when
4410 creating archives, instead of the user associated with the source
4413 If USER contains a colon, it is taken to be of the form NAME:ID
4414 where a nonempty NAME specifies the user name and a nonempty ID
4415 specifies the decimal numeric user ID. If USER does not contain a
4416 colon, it is taken to be a user number if it is one or more
4417 decimal digits; otherwise it is taken to be a user name.
4419 If a name is given but no number, the number is inferred from the
4420 current host's user database if possible, and the file's user
4421 number is used otherwise. If a number is given but no name, the
4422 name is inferred from the number if possible, and an empty name is
4423 used otherwise. If both name and number are given, the user
4424 database is not consulted, and the name and number need not be
4425 valid on the current host.
4427 There is no value indicating a missing number, and `0' usually
4428 means `root'. Some people like to force `0' as the value to offer
4429 in their distributions for the owner of files, because the `root'
4430 user is anonymous anyway, so that might as well be the owner of
4431 anonymous archives. For example:
4433 $ tar -c -f archive.tar --owner=0 .
4437 $ tar -c -f archive.tar --owner=root .
4440 Files added to the `tar' archive will have a group ID of GROUP,
4441 rather than the group from the source file. As with `--owner',
4442 the argument GROUP can be an existing group symbolic name, or a
4443 decimal numeric group ID, or NAME:ID.
4446 File: tar.info, Node: Ignore Failed Read, Prev: override, Up: create options
4448 4.3.2 Ignore Fail Read
4449 ----------------------
4451 `--ignore-failed-read'
4452 Do not exit with nonzero on unreadable files or directories.
4455 File: tar.info, Node: extract options, Next: backup, Prev: create options, Up: operations
4457 4.4 Options Used by `--extract'
4458 ===============================
4460 The previous chapter showed how to use `--extract' to extract an
4461 archive into the file system. Various options cause `tar' to extract
4462 more information than just file contents, such as the owner, the
4463 permissions, the modification date, and so forth. This section
4464 presents options to be used with `--extract' when certain special
4465 considerations arise. You may review the information presented in
4466 *note extract:: for more basic information about the `--extract'
4471 * Reading:: Options to Help Read Archives
4472 * Writing:: Changing How `tar' Writes Files
4473 * Scarce:: Coping with Scarce Resources
4476 File: tar.info, Node: Reading, Next: Writing, Up: extract options
4478 4.4.1 Options to Help Read Archives
4479 -----------------------------------
4481 Normally, `tar' will request data in full record increments from an
4482 archive storage device. If the device cannot return a full record,
4483 `tar' will report an error. However, some devices do not always return
4484 full records, or do not require the last record of an archive to be
4485 padded out to the next record boundary. To keep reading until you
4486 obtain a full record, or to accept an incomplete record if it contains
4487 an end-of-archive marker, specify the `--read-full-records' (`-B')
4488 option in conjunction with the `--extract' or `--list' operations.
4491 The `--read-full-records' (`-B') option is turned on by default when
4492 `tar' reads an archive from standard input, or from a remote machine.
4493 This is because on BSD Unix systems, attempting to read a pipe returns
4494 however much happens to be in the pipe, even if it is less than was
4495 requested. If this option were not enabled, `tar' would fail as soon
4496 as it read an incomplete record from the pipe.
4498 If you're not sure of the blocking factor of an archive, you can
4499 read the archive by specifying `--read-full-records' (`-B') and
4500 `--blocking-factor=512-SIZE' (`-b 512-SIZE'), using a blocking factor
4501 larger than what the archive uses. This lets you avoid having to
4502 determine the blocking factor of an archive. *Note Blocking Factor::.
4506 * read full records::
4510 File: tar.info, Node: read full records, Next: Ignore Zeros, Up: Reading
4512 Reading Full Records
4513 ....................
4515 `--read-full-records'
4518 Use in conjunction with `--extract' (`--get', `-x') to read an
4519 archive which contains incomplete records, or one which has a
4520 blocking factor less than the one specified.
4523 File: tar.info, Node: Ignore Zeros, Prev: read full records, Up: Reading
4525 Ignoring Blocks of Zeros
4526 ........................
4528 Normally, `tar' stops reading when it encounters a block of zeros
4529 between file entries (which usually indicates the end of the archive).
4530 `--ignore-zeros' (`-i') allows `tar' to completely read an archive
4531 which contains a block of zeros before the end (i.e., a damaged
4532 archive, or one that was created by concatenating several archives
4535 The `--ignore-zeros' (`-i') option is turned off by default because
4536 many versions of `tar' write garbage after the end-of-archive entry,
4537 since that part of the media is never supposed to be read. GNU `tar'
4538 does not write after the end of an archive, but seeks to maintain
4539 compatibility among archiving utilities.
4543 To ignore blocks of zeros (i.e., end-of-archive entries) which may
4544 be encountered while reading an archive. Use in conjunction with
4545 `--extract' or `--list'.
4548 File: tar.info, Node: Writing, Next: Scarce, Prev: Reading, Up: extract options
4550 4.4.2 Changing How `tar' Writes Files
4551 -------------------------------------
4553 _(This message will disappear, once this node revised.)_
4557 * Dealing with Old Files::
4558 * Overwrite Old Files::
4560 * Keep Newer Files::
4562 * Recursive Unlink::
4563 * Data Modification Times::
4564 * Setting Access Permissions::
4565 * Directory Modification Times and Permissions::
4566 * Writing to Standard Output::
4567 * Writing to an External Program::
4571 File: tar.info, Node: Dealing with Old Files, Next: Overwrite Old Files, Up: Writing
4573 Options Controlling the Overwriting of Existing Files
4574 .....................................................
4576 When extracting files, if `tar' discovers that the extracted file
4577 already exists, it normally replaces the file by removing it before
4578 extracting it, to prevent confusion in the presence of hard or symbolic
4579 links. (If the existing file is a symbolic link, it is removed, not
4580 followed.) However, if a directory cannot be removed because it is
4581 nonempty, `tar' normally overwrites its metadata (ownership,
4582 permission, etc.). The `--overwrite-dir' option enables this default
4583 behavior. To be more cautious and preserve the metadata of such a
4584 directory, use the `--no-overwrite-dir' option.
4586 To be even more cautious and prevent existing files from being
4587 replaced, use the `--keep-old-files' (`-k') option. It causes `tar' to
4588 refuse to replace or update a file that already exists, i.e., a file
4589 with the same name as an archive member prevents extraction of that
4590 archive member. Instead, it reports an error. For example:
4594 $ tar -x -k -f archive.tar
4595 tar: blues: Cannot open: File exists
4596 tar: Exiting with failure status due to previous errors
4598 If you wish to preserve old files untouched, but don't want `tar' to
4599 treat them as errors, use the `--skip-old-files' option. This option
4600 causes `tar' to silently skip extracting over existing files.
4602 To be more aggressive about altering existing files, use the
4603 `--overwrite' option. It causes `tar' to overwrite existing files and
4604 to follow existing symbolic links when extracting.
4606 Some people argue that GNU `tar' should not hesitate to overwrite
4607 files with other files when extracting. When extracting a `tar'
4608 archive, they expect to see a faithful copy of the state of the file
4609 system when the archive was created. It is debatable that this would
4610 always be a proper behavior. For example, suppose one has an archive
4611 in which `usr/local' is a link to `usr/local2'. Since then, maybe the
4612 site removed the link and renamed the whole hierarchy from
4613 `/usr/local2' to `/usr/local'. Such things happen all the time. I
4614 guess it would not be welcome at all that GNU `tar' removes the whole
4615 hierarchy just to make room for the link to be reinstated (unless it
4616 _also_ simultaneously restores the full `/usr/local2', of course!) GNU
4617 `tar' is indeed able to remove a whole hierarchy to reestablish a
4618 symbolic link, for example, but _only if_ `--recursive-unlink' is
4619 specified to allow this behavior. In any case, single files are
4622 Finally, the `--unlink-first' (`-U') option can improve performance
4623 in some cases by causing `tar' to remove files unconditionally before
4627 File: tar.info, Node: Overwrite Old Files, Next: Keep Old Files, Prev: Dealing with Old Files, Up: Writing
4633 Overwrite existing files and directory metadata when extracting
4634 files from an archive.
4636 This causes `tar' to write extracted files into the file system
4637 without regard to the files already on the system; i.e., files
4638 with the same names as archive members are overwritten when the
4639 archive is extracted. It also causes `tar' to extract the
4640 ownership, permissions, and time stamps onto any preexisting files
4641 or directories. If the name of a corresponding file name is a
4642 symbolic link, the file pointed to by the symbolic link will be
4643 overwritten instead of the symbolic link itself (if this is
4644 possible). Moreover, special devices, empty directories and even
4645 symbolic links are automatically removed if they are in the way of
4648 Be careful when using the `--overwrite' option, particularly when
4649 combined with the `--absolute-names' (`-P') option, as this
4650 combination can change the contents, ownership or permissions of
4651 any file on your system. Also, many systems do not take kindly to
4652 overwriting files that are currently being executed.
4655 Overwrite the metadata of directories when extracting files from an
4656 archive, but remove other files before extracting.
4659 File: tar.info, Node: Keep Old Files, Next: Keep Newer Files, Prev: Overwrite Old Files, Up: Writing
4664 GNU `tar' provides two options to control its actions in a situation
4665 when it is about to extract a file which already exists on disk.
4669 Do not replace existing files from archive. When such a file is
4670 encountered, `tar' issues an error message. Upon end of
4671 extraction, `tar' exits with code 2 (*note exit status::).
4674 Do not replace existing files from archive, but do not treat that
4675 as error. Such files are silently skipped and do not affect `tar'
4678 Additional verbosity can be obtained using
4679 `--warning=existing-file' together with that option (*note
4683 File: tar.info, Node: Keep Newer Files, Next: Unlink First, Prev: Keep Old Files, Up: Writing
4688 `--keep-newer-files'
4689 Do not replace existing files that are newer than their archive
4690 copies. This option is meaningless with `--list' (`-t').
4693 File: tar.info, Node: Unlink First, Next: Recursive Unlink, Prev: Keep Newer Files, Up: Writing
4700 Remove files before extracting over them. This can make `tar' run
4701 a bit faster if you know in advance that the extracted files all
4702 need to be removed. Normally this option slows `tar' down
4703 slightly, so it is disabled by default.
4706 File: tar.info, Node: Recursive Unlink, Next: Data Modification Times, Prev: Unlink First, Up: Writing
4711 `--recursive-unlink'
4712 When this option is specified, try removing files and directory
4713 hierarchies before extracting over them. _This is a dangerous
4716 If you specify the `--recursive-unlink' option, `tar' removes
4717 _anything_ that keeps you from extracting a file as far as current
4718 permissions will allow it. This could include removal of the contents
4719 of a full directory hierarchy.
4722 File: tar.info, Node: Data Modification Times, Next: Setting Access Permissions, Prev: Recursive Unlink, Up: Writing
4724 Setting Data Modification Times
4725 ...............................
4727 Normally, `tar' sets the data modification times of extracted files to
4728 the corresponding times recorded for the files in the archive, but
4729 limits the permissions of extracted files by the current `umask'
4732 To set the data modification times of extracted files to the time
4733 when the files were extracted, use the `--touch' (`-m') option in
4734 conjunction with `--extract' (`--get', `-x').
4738 Sets the data modification time of extracted archive members to
4739 the time they were extracted, not the time recorded for them in
4740 the archive. Use in conjunction with `--extract' (`--get', `-x').
4743 File: tar.info, Node: Setting Access Permissions, Next: Directory Modification Times and Permissions, Prev: Data Modification Times, Up: Writing
4745 Setting Access Permissions
4746 ..........................
4748 To set the modes (access permissions) of extracted files to those
4749 recorded for those files in the archive, use `--same-permissions' in
4750 conjunction with the `--extract' (`--get', `-x') operation.
4752 `--preserve-permissions'
4753 `--same-permissions'
4755 Set modes of extracted archive members to those recorded in the
4756 archive, instead of current umask settings. Use in conjunction
4757 with `--extract' (`--get', `-x').
4760 File: tar.info, Node: Directory Modification Times and Permissions, Next: Writing to Standard Output, Prev: Setting Access Permissions, Up: Writing
4762 Directory Modification Times and Permissions
4763 ............................................
4765 After successfully extracting a file member, GNU `tar' normally
4766 restores its permissions and modification times, as described in the
4767 previous sections. This cannot be done for directories, because after
4768 extracting a directory `tar' will almost certainly extract files into
4769 that directory and this will cause the directory modification time to
4770 be updated. Moreover, restoring that directory permissions may not
4771 permit file creation within it. Thus, restoring directory permissions
4772 and modification times must be delayed at least until all files have
4773 been extracted into that directory. GNU `tar' restores directories
4774 using the following approach.
4776 The extracted directories are created with the mode specified in the
4777 archive, as modified by the umask of the user, which gives sufficient
4778 permissions to allow file creation. The meta-information about the
4779 directory is recorded in the temporary list of directories. When
4780 preparing to extract next archive member, GNU `tar' checks if the
4781 directory prefix of this file contains the remembered directory. If it
4782 does not, the program assumes that all files have been extracted into
4783 that directory, restores its modification time and permissions and
4784 removes its entry from the internal list. This approach allows to
4785 correctly restore directory meta-information in the majority of cases,
4786 while keeping memory requirements sufficiently small. It is based on
4787 the fact, that most `tar' archives use the predefined order of members:
4788 first the directory, then all the files and subdirectories in that
4791 However, this is not always true. The most important exception are
4792 incremental archives (*note Incremental Dumps::). The member order in
4793 an incremental archive is reversed: first all directory members are
4794 stored, followed by other (non-directory) members. So, when extracting
4795 from incremental archives, GNU `tar' alters the above procedure. It
4796 remembers all restored directories, and restores their meta-data only
4797 after the entire archive has been processed. Notice, that you do not
4798 need to specify any special options for that, as GNU `tar'
4799 automatically detects archives in incremental format.
4801 There may be cases, when such processing is required for normal
4802 archives too. Consider the following example:
4804 $ tar --no-recursion -cvf archive \
4805 foo foo/file1 bar bar/file foo/file2
4812 During the normal operation, after encountering `bar' GNU `tar' will
4813 assume that all files from the directory `foo' were already extracted
4814 and will therefore restore its timestamp and permission bits. However,
4815 after extracting `foo/file2' the directory timestamp will be offset
4818 To correctly restore directory meta-information in such cases, use
4819 the `--delay-directory-restore' command line option:
4821 `--delay-directory-restore'
4822 Delays restoring of the modification times and permissions of
4823 extracted directories until the end of extraction. This way,
4824 correct meta-information is restored even if the archive has
4825 unusual member ordering.
4827 `--no-delay-directory-restore'
4828 Cancel the effect of the previous `--delay-directory-restore'.
4829 Use this option if you have used `--delay-directory-restore' in
4830 `TAR_OPTIONS' variable (*note TAR_OPTIONS::) and wish to
4831 temporarily disable it.
4834 File: tar.info, Node: Writing to Standard Output, Next: Writing to an External Program, Prev: Directory Modification Times and Permissions, Up: Writing
4836 Writing to Standard Output
4837 ..........................
4839 To write the extracted files to the standard output, instead of
4840 creating the files on the file system, use `--to-stdout' (`-O') in
4841 conjunction with `--extract' (`--get', `-x'). This option is useful if
4842 you are extracting files to send them through a pipe, and do not need to
4843 preserve them in the file system. If you extract multiple members,
4844 they appear on standard output concatenated, in the order they are
4845 found in the archive.
4849 Writes files to the standard output. Use only in conjunction with
4850 `--extract' (`--get', `-x'). When this option is used, instead of
4851 creating the files specified, `tar' writes the contents of the
4852 files extracted to its standard output. This may be useful if you
4853 are only extracting the files in order to send them through a
4854 pipe. This option is meaningless with `--list' (`-t').
4856 This can be useful, for example, if you have a tar archive containing
4857 a big file and don't want to store the file on disk before processing
4858 it. You can use a command like this:
4860 tar -xOzf foo.tgz bigfile | process
4862 or even like this if you want to process the concatenation of the
4865 tar -xOzf foo.tgz bigfile1 bigfile2 | process
4867 However, `--to-command' may be more convenient for use with multiple
4868 files. See the next section.
4871 File: tar.info, Node: Writing to an External Program, Next: remove files, Prev: Writing to Standard Output, Up: Writing
4873 Writing to an External Program
4874 ..............................
4876 You can instruct `tar' to send the contents of each extracted file to
4877 the standard input of an external program:
4879 `--to-command=COMMAND'
4880 Extract files and pipe their contents to the standard input of
4881 COMMAND. When this option is used, instead of creating the files
4882 specified, `tar' invokes COMMAND and pipes the contents of the
4883 files to its standard output. The COMMAND may contain command
4884 line arguments (see *note Running External Commands: external, for
4887 Notice, that COMMAND is executed once for each regular file
4888 extracted. Non-regular files (directories, etc.) are ignored when
4889 this option is used.
4891 The command can obtain the information about the file it processes
4892 from the following environment variables:
4895 Type of the file. It is a single letter with the following meaning:
4904 Currently only regular files are supported.
4907 File mode, an octal number.
4910 The name of the file.
4913 Name of the file as stored in the archive.
4916 Name of the file owner.
4919 Name of the file owner group.
4922 Time of last access. It is a decimal number, representing seconds
4923 since the Epoch. If the archive provides times with nanosecond
4924 precision, the nanoseconds are appended to the timestamp after a
4928 Time of last modification.
4931 Time of last status change.
4937 UID of the file owner.
4940 GID of the file owner.
4942 Additionally, the following variables contain information about tar
4943 mode and the archive being processed:
4946 GNU `tar' version number.
4949 The name of the archive `tar' is processing.
4951 `TAR_BLOCKING_FACTOR'
4952 Current blocking factor (*note Blocking::).
4955 Ordinal number of the volume `tar' is processing.
4958 Format of the archive being processed. *Note Formats::, for a
4959 complete list of archive format names.
4961 These variables are defined prior to executing the command, so you
4962 can pass them as arguments, if you prefer. For example, if the command
4963 PROC takes the member name and size as its arguments, then you could do:
4965 $ tar -x -f archive.tar \
4966 --to-command='proc $TAR_FILENAME $TAR_SIZE'
4968 Notice single quotes to prevent variable names from being expanded by
4969 the shell when invoking `tar'.
4971 If COMMAND exits with a non-0 status, `tar' will print an error
4972 message similar to the following:
4974 tar: 2345: Child returned status 1
4976 Here, `2345' is the PID of the finished process.
4978 If this behavior is not wanted, use `--ignore-command-error':
4980 `--ignore-command-error'
4981 Ignore exit codes of subprocesses. Notice that if the program
4982 exits on signal or otherwise terminates abnormally, the error
4983 message will be printed even if this option is used.
4985 `--no-ignore-command-error'
4986 Cancel the effect of any previous `--ignore-command-error' option.
4987 This option is useful if you have set `--ignore-command-error' in
4988 `TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to temporarily cancel
4992 File: tar.info, Node: remove files, Prev: Writing to an External Program, Up: Writing
4998 Remove files after adding them to the archive.
5001 File: tar.info, Node: Scarce, Prev: Writing, Up: extract options
5003 4.4.3 Coping with Scarce Resources
5004 ----------------------------------
5006 _(This message will disappear, once this node revised.)_
5014 File: tar.info, Node: Starting File, Next: Same Order, Up: Scarce
5019 `--starting-file=NAME'
5021 Starts an operation in the middle of an archive. Use in
5022 conjunction with `--extract' (`--get', `-x') or `--list' (`-t').
5024 If a previous attempt to extract files failed due to lack of disk
5025 space, you can use `--starting-file=NAME' (`-K NAME') to start
5026 extracting only after member NAME of the archive. This assumes, of
5027 course, that there is now free space, or that you are now extracting
5028 into a different file system. (You could also choose to suspend `tar',
5029 remove unnecessary files from the file system, and then resume the same
5030 `tar' operation. In this case, `--starting-file' is not necessary.)
5031 See also *note interactive::, and *note exclude::.
5034 File: tar.info, Node: Same Order, Prev: Starting File, Up: Scarce
5042 To process large lists of file names on machines with small
5043 amounts of memory. Use in conjunction with `--compare' (`--diff',
5044 `-d'), `--list' (`-t') or `--extract' (`--get', `-x').
5046 The `--same-order' (`--preserve-order', `-s') option tells `tar'
5047 that the list of file names to be listed or extracted is sorted in the
5048 same order as the files in the archive. This allows a large list of
5049 names to be used, even on a small machine that would not otherwise be
5050 able to hold all the names in memory at the same time. Such a sorted
5051 list can easily be created by running `tar -t' on the archive and
5054 This option is probably never needed on modern computer systems.
5057 File: tar.info, Node: backup, Next: Applications, Prev: extract options, Up: operations
5062 GNU `tar' offers options for making backups of files before writing new
5063 versions. These options control the details of these backups. They
5064 may apply to the archive itself before it is created or rewritten, as
5065 well as individual extracted members. Other GNU programs (`cp',
5066 `install', `ln', and `mv', for example) offer similar options.
5068 Backup options may prove unexpectedly useful when extracting archives
5069 containing many members having identical name, or when extracting
5070 archives on systems having file name limitations, making different
5071 members appear as having similar names through the side-effect of name
5074 When any existing file is backed up before being overwritten by
5075 extraction, then clashing files are automatically be renamed to be
5076 unique, and the true name is kept for only the last file of a series of
5077 clashing files. By using verbose mode, users may track exactly what
5080 At the detail level, some decisions are still experimental, and may
5081 change in the future, we are waiting comments from our users. So,
5082 please do not learn to depend blindly on the details of the backup
5083 features. For example, currently, directories themselves are never
5084 renamed through using these options, so, extracting a file over a
5085 directory still has good chances to fail. Also, backup options apply
5086 to created archives, not only to extracted members. For created
5087 archives, backups will not be attempted when the archive is a block or
5088 character device, or when it refers to a remote file.
5090 For the sake of simplicity and efficiency, backups are made by
5091 renaming old files prior to creation or extraction, and not by copying.
5092 The original name is restored if the file creation fails. If a failure
5093 occurs after a partial extraction of a file, both the backup and the
5094 partially extracted file are kept.
5097 Back up files that are about to be overwritten or removed.
5098 Without this option, the original versions are destroyed.
5100 Use METHOD to determine the type of backups made. If METHOD is
5101 not specified, use the value of the `VERSION_CONTROL' environment
5102 variable. And if `VERSION_CONTROL' is not set, use the `existing'
5105 This option corresponds to the Emacs variable `version-control';
5106 the same values for METHOD are accepted as in Emacs. This option
5107 also allows more descriptive names. The valid METHODs are:
5111 Always make numbered backups.
5115 Make numbered backups of files that already have them, simple
5116 backups of the others.
5120 Always make simple backups.
5124 Append SUFFIX to each backup file made with `--backup'. If this
5125 option is not specified, the value of the `SIMPLE_BACKUP_SUFFIX'
5126 environment variable is used. And if `SIMPLE_BACKUP_SUFFIX' is not
5127 set, the default is `~', just as in Emacs.
5131 File: tar.info, Node: Applications, Next: looking ahead, Prev: backup, Up: operations
5133 4.6 Notable `tar' Usages
5134 ========================
5136 _(This message will disappear, once this node revised.)_
5138 You can easily use archive files to transport a group of files from one
5139 system to another: put all relevant files into an archive on one
5140 computer system, transfer the archive to another system, and extract
5141 the contents there. The basic transfer medium might be magnetic tape,
5142 Internet FTP, or even electronic mail (though you must encode the
5143 archive with `uuencode' in order to transport it properly by mail).
5144 Both machines do not have to use the same operating system, as long as
5145 they both support the `tar' program.
5147 For example, here is how you might copy a directory's contents from
5148 one disk to another, while preserving the dates, modes, owners and
5149 link-structure of all the files therein. In this case, the transfer
5152 $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)
5154 You can avoid subshells by using `-C' option:
5156 $ tar -C sourcedir -cf - . | tar -C targetdir -xf -
5158 The command also works using long option forms:
5160 $ (cd sourcedir; tar --create --file=- . ) \
5161 | (cd targetdir; tar --extract --file=-)
5165 $ tar --directory sourcedir --create --file=- . \
5166 | tar --directory targetdir --extract --file=-
5168 This is one of the easiest methods to transfer a `tar' archive.
5171 File: tar.info, Node: looking ahead, Prev: Applications, Up: operations
5173 4.7 Looking Ahead: The Rest of this Manual
5174 ==========================================
5176 You have now seen how to use all eight of the operations available to
5177 `tar', and a number of the possible options. The next chapter explains
5178 how to choose and change file and archive names, how to use files to
5179 store names of other files which you can then call as arguments to
5180 `tar' (this can help you save time if you expect to archive the same
5181 list of files a number of times), and so forth.
5183 If there are too many files to conveniently list on the command line,
5184 you can list the names in a file, and `tar' will read that file. *Note
5187 There are various ways of causing `tar' to skip over some files, and
5188 not archive them. *Note Choosing::.
5191 File: tar.info, Node: Backups, Next: Choosing, Prev: operations, Up: Top
5193 5 Performing Backups and Restoring Files
5194 ****************************************
5196 GNU `tar' is distributed along with the scripts for performing backups
5197 and restores. Even if there is a good chance those scripts may be
5198 satisfying to you, they are not the only scripts or methods available
5199 for doing backups and restore. You may well create your own, or use
5200 more sophisticated packages dedicated to that purpose.
5202 Some users are enthusiastic about `Amanda' (The Advanced Maryland
5203 Automatic Network Disk Archiver), a backup system developed by James da
5204 Silva `jds@cs.umd.edu' and available on many Unix systems. This is
5205 free software, and it is available from `http://www.amanda.org'.
5207 This chapter documents both the provided shell scripts and `tar'
5208 options which are more specific to usage as a backup tool.
5210 To "back up" a file system means to create archives that contain all
5211 the files in that file system. Those archives can then be used to
5212 restore any or all of those files (for instance if a disk crashes or a
5213 file is accidentally deleted). File system "backups" are also called
5218 * Full Dumps:: Using `tar' to Perform Full Dumps
5219 * Incremental Dumps:: Using `tar' to Perform Incremental Dumps
5220 * Backup Levels:: Levels of Backups
5221 * Backup Parameters:: Setting Parameters for Backups and Restoration
5222 * Scripted Backups:: Using the Backup Scripts
5223 * Scripted Restoration:: Using the Restore Script
5226 File: tar.info, Node: Full Dumps, Next: Incremental Dumps, Up: Backups
5228 5.1 Using `tar' to Perform Full Dumps
5229 =====================================
5231 _(This message will disappear, once this node revised.)_
5233 Full dumps should only be made when no other people or programs are
5234 modifying files in the file system. If files are modified while `tar'
5235 is making the backup, they may not be stored properly in the archive,
5236 in which case you won't be able to restore them if you have to. (Files
5237 not being modified are written with no trouble, and do not corrupt the
5240 You will want to use the `--label=ARCHIVE-LABEL' (`-V
5241 ARCHIVE-LABEL') option to give the archive a volume label, so you can
5242 tell what this archive is even if the label falls off the tape, or
5245 Unless the file system you are dumping is guaranteed to fit on one
5246 volume, you will need to use the `--multi-volume' (`-M') option. Make
5247 sure you have enough tapes on hand to complete the backup.
5249 If you want to dump each file system separately you will need to use
5250 the `--one-file-system' option to prevent `tar' from crossing file
5251 system boundaries when storing (sub)directories.
5253 The `--incremental' (`-G') (*note Incremental Dumps::) option is not
5254 needed, since this is a complete copy of everything in the file system,
5255 and a full restore from this backup would only be done onto a completely
5258 Unless you are in a hurry, and trust the `tar' program (and your
5259 tapes), it is a good idea to use the `--verify' (`-W') option, to make
5260 sure your files really made it onto the dump properly. This will also
5261 detect cases where the file was modified while (or just after) it was
5262 being archived. Not all media (notably cartridge tapes) are capable of
5263 being verified, unfortunately.
5266 File: tar.info, Node: Incremental Dumps, Next: Backup Levels, Prev: Full Dumps, Up: Backups
5268 5.2 Using `tar' to Perform Incremental Dumps
5269 ============================================
5271 "Incremental backup" is a special form of GNU `tar' archive that stores
5272 additional metadata so that exact state of the file system can be
5273 restored when extracting the archive.
5275 GNU `tar' currently offers two options for handling incremental
5276 backups: `--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') and
5277 `--incremental' (`-G').
5279 The option `--listed-incremental' instructs tar to operate on an
5280 incremental archive with additional metadata stored in a standalone
5281 file, called a "snapshot file". The purpose of this file is to help
5282 determine which files have been changed, added or deleted since the
5283 last backup, so that the next incremental backup will contain only
5284 modified files. The name of the snapshot file is given as an argument
5287 `--listed-incremental=FILE'
5289 Handle incremental backups with snapshot data in FILE.
5291 To create an incremental backup, you would use
5292 `--listed-incremental' together with `--create' (*note create::). For
5296 --file=archive.1.tar \
5297 --listed-incremental=/var/log/usr.snar \
5300 This will create in `archive.1.tar' an incremental backup of the
5301 `/usr' file system, storing additional metadata in the file
5302 `/var/log/usr.snar'. If this file does not exist, it will be created.
5303 The created archive will then be a "level 0 backup"; please see the
5304 next section for more on backup levels.
5306 Otherwise, if the file `/var/log/usr.snar' exists, it determines
5307 which files are modified. In this case only these files will be stored
5308 in the archive. Suppose, for example, that after running the above
5309 command, you delete file `/usr/doc/old' and create directory
5310 `/usr/local/db' with the following contents:
5316 Some time later you create another incremental backup. You will
5320 --file=archive.2.tar \
5321 --listed-incremental=/var/log/usr.snar \
5323 tar: usr/local/db: Directory is new
5328 The created archive `archive.2.tar' will contain only these three
5329 members. This archive is called a "level 1 backup". Notice that
5330 `/var/log/usr.snar' will be updated with the new data, so if you plan
5331 to create more `level 1' backups, it is necessary to create a working
5332 copy of the snapshot file before running `tar'. The above example will
5333 then be modified as follows:
5335 $ cp /var/log/usr.snar /var/log/usr.snar-1
5337 --file=archive.2.tar \
5338 --listed-incremental=/var/log/usr.snar-1 \
5341 You can force `level 0' backups either by removing the snapshot file
5342 before running `tar', or by supplying the `--level=0' option, e.g.:
5345 --file=archive.2.tar \
5346 --listed-incremental=/var/log/usr.snar-0 \
5350 Incremental dumps depend crucially on time stamps, so the results are
5351 unreliable if you modify a file's time stamps during dumping (e.g.,
5352 with the `--atime-preserve=replace' option), or if you set the clock
5355 Metadata stored in snapshot files include device numbers, which,
5356 obviously are supposed to be non-volatile values. However, it turns
5357 out that NFS devices have undependable values when an automounter gets
5358 in the picture. This can lead to a great deal of spurious redumping in
5359 incremental dumps, so it is somewhat useless to compare two NFS devices
5360 numbers over time. The solution implemented currently is to consider
5361 all NFS devices as being equal when it comes to comparing directories;
5362 this is fairly gross, but there does not seem to be a better way to go.
5364 Apart from using NFS, there are a number of cases where relying on
5365 device numbers can cause spurious redumping of unmodified files. For
5366 example, this occurs when archiving LVM snapshot volumes. To avoid
5367 this, use `--no-check-device' option:
5370 Do not rely on device numbers when preparing a list of changed
5371 files for an incremental dump.
5374 Use device numbers when preparing a list of changed files for an
5375 incremental dump. This is the default behavior. The purpose of
5376 this option is to undo the effect of the `--no-check-device' if it
5377 was given in `TAR_OPTIONS' environment variable (*note
5380 There is also another way to cope with changing device numbers. It
5381 is described in detail in *note Fixing Snapshot Files::.
5383 Note that incremental archives use `tar' extensions and may not be
5384 readable by non-GNU versions of the `tar' program.
5386 To extract from the incremental dumps, use `--listed-incremental'
5387 together with `--extract' option (*note extracting files::). In this
5388 case, `tar' does not need to access snapshot file, since all the data
5389 necessary for extraction are stored in the archive itself. So, when
5390 extracting, you can give whatever argument to `--listed-incremental',
5391 the usual practice is to use `--listed-incremental=/dev/null'.
5392 Alternatively, you can use `--incremental', which needs no arguments.
5393 In general, `--incremental' (`-G') can be used as a shortcut for
5394 `--listed-incremental' when listing or extracting incremental backups
5395 (for more information regarding this option, *note incremental-op::).
5397 When extracting from the incremental backup GNU `tar' attempts to
5398 restore the exact state the file system had when the archive was
5399 created. In particular, it will _delete_ those files in the file
5400 system that did not exist in their directories when the archive was
5401 created. If you have created several levels of incremental files, then
5402 in order to restore the exact contents the file system had when the
5403 last level was created, you will need to restore from all backups in
5404 turn. Continuing our example, to restore the state of `/usr' file
5405 system, one would do(1):
5408 --listed-incremental=/dev/null \
5409 --file archive.1.tar
5411 --listed-incremental=/dev/null \
5412 --file archive.2.tar
5414 To list the contents of an incremental archive, use `--list' (*note
5415 list::), as usual. To obtain more information about the archive, use
5416 `--listed-incremental' or `--incremental' combined with two `--verbose'
5419 tar --list --incremental --verbose --verbose archive.tar
5421 This command will print, for each directory in the archive, the list
5422 of files in that directory at the time the archive was created. This
5423 information is put out in a format which is both human-readable and
5424 unambiguous for a program: each file name is printed as
5428 where X is a letter describing the status of the file: `Y' if the file
5429 is present in the archive, `N' if the file is not included in the
5430 archive, or a `D' if the file is a directory (and is included in the
5431 archive). *Note Dumpdir::, for the detailed description of dumpdirs
5432 and status codes. Each such line is terminated by a newline character.
5433 The last line is followed by an additional newline to indicate the end
5436 The option `--incremental' (`-G') gives the same behavior as
5437 `--listed-incremental' when used with `--list' and `--extract' options.
5438 When used with `--create' option, it creates an incremental archive
5439 without creating snapshot file. Thus, it is impossible to create
5440 several levels of incremental backups with `--incremental' option.
5442 ---------- Footnotes ----------
5444 (1) Notice, that since both archives were created without `-P'
5445 option (*note absolute::), these commands should be run from the root
5448 (2) Two `--verbose' options were selected to avoid breaking usual
5449 verbose listing output (`--list --verbose') when using in scripts.
5451 Versions of GNU `tar' up to 1.15.1 used to dump verbatim binary
5452 contents of the DUMPDIR header (with terminating nulls) when
5453 `--incremental' or `--listed-incremental' option was given, no matter
5454 what the verbosity level. This behavior, and, especially, the binary
5455 output it produced were considered inconvenient and were changed in
5459 File: tar.info, Node: Backup Levels, Next: Backup Parameters, Prev: Incremental Dumps, Up: Backups
5461 5.3 Levels of Backups
5462 =====================
5464 An archive containing all the files in the file system is called a
5465 "full backup" or "full dump". You could insure your data by creating a
5466 full dump every day. This strategy, however, would waste a substantial
5467 amount of archive media and user time, as unchanged files are daily
5470 It is more efficient to do a full dump only occasionally. To back up
5471 files between full dumps, you can use "incremental dumps". A "level
5472 one" dump archives all the files that have changed since the last full
5475 A typical dump strategy would be to perform a full dump once a week,
5476 and a level one dump once a day. This means some versions of files
5477 will in fact be archived more than once, but this dump strategy makes
5478 it possible to restore a file system to within one day of accuracy by
5479 only extracting two archives--the last weekly (full) dump and the last
5480 daily (level one) dump. The only information lost would be in files
5481 changed or created since the last daily backup. (Doing dumps more than
5482 once a day is usually not worth the trouble.)
5484 GNU `tar' comes with scripts you can use to do full and level-one
5485 (actually, even level-two and so on) dumps. Using scripts (shell
5486 programs) to perform backups and restoration is a convenient and
5487 reliable alternative to typing out file name lists and `tar' commands
5490 Before you use these scripts, you need to edit the file
5491 `backup-specs', which specifies parameters used by the backup scripts
5492 and by the restore script. This file is usually located in
5493 `/etc/backup' directory. *Note Backup Parameters::, for its detailed
5494 description. Once the backup parameters are set, you can perform
5495 backups or restoration by running the appropriate script.
5497 The name of the backup script is `backup'. The name of the restore
5498 script is `restore'. The following sections describe their use in
5501 _Please Note:_ The backup and restoration scripts are designed to be
5502 used together. While it is possible to restore files by hand from an
5503 archive which was created using a backup script, and to create an
5504 archive by hand which could then be extracted using the restore script,
5505 it is easier to use the scripts. *Note Incremental Dumps::, before
5506 making such an attempt.
5509 File: tar.info, Node: Backup Parameters, Next: Scripted Backups, Prev: Backup Levels, Up: Backups
5511 5.4 Setting Parameters for Backups and Restoration
5512 ==================================================
5514 The file `backup-specs' specifies backup parameters for the backup and
5515 restoration scripts provided with `tar'. You must edit `backup-specs'
5516 to fit your system configuration and schedule before using these
5519 Syntactically, `backup-specs' is a shell script, containing mainly
5520 variable assignments. However, any valid shell construct is allowed in
5521 this file. Particularly, you may wish to define functions within that
5522 script (e.g., see `RESTORE_BEGIN' below). For more information about
5523 shell script syntax, please refer to the definition of the Shell
5525 (http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
5526 g_02). See also *note Bash Features: (bashref)Top.
5528 The shell variables controlling behavior of `backup' and `restore'
5529 are described in the following subsections.
5533 * General-Purpose Variables::
5534 * Magnetic Tape Control::
5536 * backup-specs example:: An Example Text of `Backup-specs'
5539 File: tar.info, Node: General-Purpose Variables, Next: Magnetic Tape Control, Up: Backup Parameters
5541 5.4.1 General-Purpose Variables
5542 -------------------------------
5544 -- Backup variable: ADMINISTRATOR
5545 The user name of the backup administrator. `Backup' scripts sends
5546 a backup report to this address.
5548 -- Backup variable: BACKUP_HOUR
5549 The hour at which the backups are done. This can be a number from
5550 0 to 23, or the time specification in form HOURS:MINUTES, or the
5553 This variable is used by `backup'. Its value may be overridden
5554 using `--time' option (*note Scripted Backups::).
5556 -- Backup variable: TAPE_FILE
5557 The device `tar' writes the archive to. If TAPE_FILE is a remote
5558 archive (*note remote-dev::), backup script will suppose that your
5559 `mt' is able to access remote devices. If RSH (*note RSH::) is
5560 set, `--rsh-command' option will be added to invocations of `mt'.
5562 -- Backup variable: BLOCKING
5563 The blocking factor `tar' will use when writing the dump archive.
5564 *Note Blocking Factor::.
5566 -- Backup variable: BACKUP_DIRS
5567 A list of file systems to be dumped (for `backup'), or restored
5568 (for `restore'). You can include any directory name in the list
5569 -- subdirectories on that file system will be included, regardless
5570 of how they may look to other networked machines. Subdirectories
5571 on other file systems will be ignored.
5573 The host name specifies which host to run `tar' on, and should
5574 normally be the host that actually contains the file system.
5575 However, the host machine must have GNU `tar' installed, and must
5576 be able to access the directory containing the backup scripts and
5577 their support files using the same file name that is used on the
5578 machine where the scripts are run (i.e., what `pwd' will print
5579 when in that directory on that machine). If the host that contains
5580 the file system does not have this capability, you can specify
5581 another host as long as it can access the file system through NFS.
5583 If the list of file systems is very long you may wish to put it in
5584 a separate file. This file is usually named `/etc/backup/dirs',
5585 but this name may be overridden in `backup-specs' using `DIRLIST'
5588 -- Backup variable: DIRLIST
5589 The name of the file that contains a list of file systems to backup
5590 or restore. By default it is `/etc/backup/dirs'.
5592 -- Backup variable: BACKUP_FILES
5593 A list of individual files to be dumped (for `backup'), or restored
5594 (for `restore'). These should be accessible from the machine on
5595 which the backup script is run.
5597 If the list of individual files is very long you may wish to store
5598 it in a separate file. This file is usually named
5599 `/etc/backup/files', but this name may be overridden in
5600 `backup-specs' using `FILELIST' variable.
5602 -- Backup variable: FILELIST
5603 The name of the file that contains a list of individual files to
5604 backup or restore. By default it is `/etc/backup/files'.
5606 -- Backup variable: MT
5607 Full file name of `mt' binary.
5609 -- Backup variable: RSH
5610 Full file name of `rsh' binary or its equivalent. You may wish to
5611 set it to `ssh', to improve security. In this case you will have
5612 to use public key authentication.
5614 -- Backup variable: RSH_COMMAND
5615 Full file name of `rsh' binary on remote machines. This will be
5616 passed via `--rsh-command' option to the remote invocation of GNU
5619 -- Backup variable: VOLNO_FILE
5620 Name of temporary file to hold volume numbers. This needs to be
5621 accessible by all the machines which have file systems to be
5624 -- Backup variable: XLIST
5625 Name of "exclude file list". An "exclude file list" is a file
5626 located on the remote machine and containing the list of files to
5627 be excluded from the backup. Exclude file lists are searched in
5628 /etc/tar-backup directory. A common use for exclude file lists is
5629 to exclude files containing security-sensitive information (e.g.,
5630 `/etc/shadow' from backups).
5632 This variable affects only `backup'.
5634 -- Backup variable: SLEEP_TIME
5635 Time to sleep between dumps of any two successive file systems
5637 This variable affects only `backup'.
5639 -- Backup variable: DUMP_REMIND_SCRIPT
5640 Script to be run when it's time to insert a new tape in for the
5641 next volume. Administrators may want to tailor this script for
5642 their site. If this variable isn't set, GNU `tar' will display
5643 its built-in prompt, and will expect confirmation from the
5644 console. For the description of the default prompt, see *note
5645 change volume prompt::.
5648 -- Backup variable: SLEEP_MESSAGE
5649 Message to display on the terminal while waiting for dump time.
5650 Usually this will just be some literal text.
5652 -- Backup variable: TAR
5653 Full file name of the GNU `tar' executable. If this is not set,
5654 backup scripts will search `tar' in the current shell path.
5657 File: tar.info, Node: Magnetic Tape Control, Next: User Hooks, Prev: General-Purpose Variables, Up: Backup Parameters
5659 5.4.2 Magnetic Tape Control
5660 ---------------------------
5662 Backup scripts access tape device using special "hook functions".
5663 These functions take a single argument -- the name of the tape device.
5664 Their names are kept in the following variables:
5666 -- Backup variable: MT_BEGIN
5667 The name of "begin" function. This function is called before
5668 accessing the drive. By default it retensions the tape:
5673 mt -f "$1" retension
5676 -- Backup variable: MT_REWIND
5677 The name of "rewind" function. The default definition is as
5687 -- Backup variable: MT_OFFLINE
5688 The name of the function switching the tape off line. By default
5689 it is defined as follows:
5691 MT_OFFLINE=mt_offline
5697 -- Backup variable: MT_STATUS
5698 The name of the function used to obtain the status of the archive
5699 device, including error count. Default definition:
5708 File: tar.info, Node: User Hooks, Next: backup-specs example, Prev: Magnetic Tape Control, Up: Backup Parameters
5713 "User hooks" are shell functions executed before and after each `tar'
5714 invocation. Thus, there are "backup hooks", which are executed before
5715 and after dumping each file system, and "restore hooks", executed
5716 before and after restoring a file system. Each user hook is a shell
5717 function taking four arguments:
5719 -- User Hook Function: hook LEVEL HOST FS FSNAME
5723 Current backup or restore level.
5726 Name or IP address of the host machine being dumped or
5730 Full file name of the file system being dumped or restored.
5733 File system name with directory separators replaced with
5734 colons. This is useful, e.g., for creating unique files.
5736 Following variables keep the names of user hook functions:
5738 -- Backup variable: DUMP_BEGIN
5739 Dump begin function. It is executed before dumping the file
5742 -- Backup variable: DUMP_END
5743 Executed after dumping the file system.
5745 -- Backup variable: RESTORE_BEGIN
5746 Executed before restoring the file system.
5748 -- Backup variable: RESTORE_END
5749 Executed after restoring the file system.
5752 File: tar.info, Node: backup-specs example, Prev: User Hooks, Up: Backup Parameters
5754 5.4.4 An Example Text of `Backup-specs'
5755 ---------------------------------------
5757 The following is an example of `backup-specs':
5759 # site-specific parameters for file system backup.
5761 ADMINISTRATOR=friedman
5763 TAPE_FILE=/dev/nrsmt0
5765 # Use `ssh' instead of the less secure `rsh'
5767 RSH_COMMAND=/usr/bin/ssh
5769 # Override MT_STATUS function:
5775 # Disable MT_OFFLINE function
5792 apple-gunkies:/com/mailer/gnu
5793 apple-gunkies:/com/archive/gnu"
5795 BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
5798 File: tar.info, Node: Scripted Backups, Next: Scripted Restoration, Prev: Backup Parameters, Up: Backups
5800 5.5 Using the Backup Scripts
5801 ============================
5803 The syntax for running a backup script is:
5805 backup --level=LEVEL --time=TIME
5807 The `--level' option requests the dump level. Thus, to produce a
5808 full dump, specify `--level=0' (this is the default, so `--level' may
5809 be omitted if its value is `0')(1).
5811 The `--time' option determines when should the backup be run. TIME
5812 may take three forms:
5815 The dump must be run at HH hours MM minutes.
5818 The dump must be run at HH hours.
5821 The dump must be run immediately.
5823 You should start a script with a tape or disk mounted. Once you
5824 start a script, it prompts you for new tapes or disks as it needs them.
5825 Media volumes don't have to correspond to archive files -- a
5826 multi-volume archive can be started in the middle of a tape that
5827 already contains the end of another multi-volume archive. The
5828 `restore' script prompts for media by its archive volume, so to avoid
5829 an error message you should keep track of which tape (or disk) contains
5830 which volume of the archive (*note Scripted Restoration::).
5832 The backup scripts write two files on the file system. The first is
5833 a record file in `/etc/tar-backup/', which is used by the scripts to
5834 store and retrieve information about which files were dumped. This
5835 file is not meant to be read by humans, and should not be deleted by
5836 them. *Note Snapshot Files::, for a more detailed explanation of this
5839 The second file is a log file containing the names of the file
5840 systems and files dumped, what time the backup was made, and any error
5841 messages that were generated, as well as how much space was left in the
5842 media volume after the last volume of the archive was written. You
5843 should check this log file after every backup. The file name is
5844 `log-MM-DD-YYYY-level-N', where MM-DD-YYYY represents current date, and
5845 N represents current dump level number.
5847 The script also prints the name of each system being dumped to the
5850 Following is the full list of options accepted by `backup' script:
5854 Do backup level LEVEL (default 0).
5858 Force backup even if today's log file already exists.
5862 Set verbosity level. The higher the level is, the more debugging
5863 information will be output during execution. Default LEVEL is
5864 100, which means the highest debugging level.
5868 Wait till TIME, then do backup.
5872 Display short help message and exit.
5876 Display information about the program's name, version, origin and
5877 legal status, all on standard output, and then exit successfully.
5879 ---------- Footnotes ----------
5881 (1) For backward compatibility, the `backup' will also try to deduce
5882 the requested dump level from the name of the script itself. If the
5883 name consists of a string `level-' followed by a single decimal digit,
5884 that digit is taken as the dump level number. Thus, you may create a
5885 link from `backup' to `level-1' and then run `level-1' whenever you
5886 need to create a level one dump.
5889 File: tar.info, Node: Scripted Restoration, Prev: Scripted Backups, Up: Backups
5891 5.6 Using the Restore Script
5892 ============================
5894 To restore files that were archived using a scripted backup, use the
5895 `restore' script. Its usage is quite straightforward. In the simplest
5896 form, invoke `restore --all', it will then restore all the file systems
5897 and files specified in `backup-specs' (*note BACKUP_DIRS:
5898 General-Purpose Variables.).
5900 You may select the file systems (and/or files) to restore by giving
5901 `restore' a list of "patterns" in its command line. For example,
5906 will restore all file systems on the machine `albert'. A more
5907 complicated example:
5909 restore 'albert:*' '*:/var'
5911 This command will restore all file systems on the machine `albert' as
5912 well as `/var' file system on all machines.
5914 By default `restore' will start restoring files from the lowest
5915 available dump level (usually zero) and will continue through all
5916 available dump levels. There may be situations where such a thorough
5917 restore is not necessary. For example, you may wish to restore only
5918 files from the recent level one backup. To do so, use `--level'
5919 option, as shown in the example below:
5923 The full list of options accepted by `restore' follows:
5927 Restore all file systems and files specified in `backup-specs'.
5931 Start restoring from the given backup level, instead of the
5936 Set verbosity level. The higher the level is, the more debugging
5937 information will be output during execution. Default LEVEL is
5938 100, which means the highest debugging level.
5942 Display short help message and exit.
5946 Display information about the program's name, version, origin and
5947 legal status, all on standard output, and then exit successfully.
5949 You should start the restore script with the media containing the
5950 first volume of the archive mounted. The script will prompt for other
5951 volumes as they are needed. If the archive is on tape, you don't need
5952 to rewind the tape to to its beginning--if the tape head is positioned
5953 past the beginning of the archive, the script will rewind the tape as
5954 needed. *Note Tape Positioning::, for a discussion of tape positioning.
5956 *Warning:* The script will delete files from the active file
5957 system if they were not in the file system when the archive was
5960 *Note Incremental Dumps::, for an explanation of how the script makes
5964 File: tar.info, Node: Choosing, Next: Date input formats, Prev: Backups, Up: Top
5966 6 Choosing Files and Names for `tar'
5967 ************************************
5969 Certain options to `tar' enable you to specify a name for your archive.
5970 Other options let you decide which files to include or exclude from the
5971 archive, based on when or whether files were modified, whether the file
5972 names do or don't match specified patterns, or whether files are in
5973 specified directories.
5975 This chapter discusses these options in detail.
5979 * file:: Choosing the Archive's Name
5980 * Selecting Archive Members::
5981 * files:: Reading Names from a File
5982 * exclude:: Excluding Some Files
5983 * wildcards:: Wildcards Patterns and Matching
5984 * quoting styles:: Ways of Quoting Special Characters in Names
5985 * transform:: Modifying File and Member Names
5986 * after:: Operating Only on New Files
5987 * recurse:: Descending into Directories
5988 * one:: Crossing File System Boundaries
5991 File: tar.info, Node: file, Next: Selecting Archive Members, Up: Choosing
5993 6.1 Choosing and Naming Archive Files
5994 =====================================
5996 By default, `tar' uses an archive file name that was compiled when it
5997 was built on the system; usually this name refers to some physical tape
5998 drive on the machine. However, the person who installed `tar' on the
5999 system may not have set the default to a meaningful value as far as
6000 most users are concerned. As a result, you will usually want to tell
6001 `tar' where to find (or create) the archive. The `--file=ARCHIVE-NAME'
6002 (`-f ARCHIVE-NAME') option allows you to either specify or name a file
6003 to use as the archive instead of the default archive file location.
6005 `--file=ARCHIVE-NAME'
6007 Name the archive to create or operate on. Use in conjunction with
6010 For example, in this `tar' command,
6012 $ tar -cvf collection.tar blues folk jazz
6014 `collection.tar' is the name of the archive. It must directly follow
6015 the `-f' option, since whatever directly follows `-f' _will_ end up
6016 naming the archive. If you neglect to specify an archive name, you may
6017 end up overwriting a file in the working directory with the archive you
6018 create since `tar' will use this file's name for the archive name.
6020 An archive can be saved as a file in the file system, sent through a
6021 pipe or over a network, or written to an I/O device such as a tape,
6022 floppy disk, or CD write drive.
6024 If you do not name the archive, `tar' uses the value of the
6025 environment variable `TAPE' as the file name for the archive. If that
6026 is not available, `tar' uses a default, compiled-in archive name,
6027 usually that for tape unit zero (i.e., `/dev/tu00').
6029 If you use `-' as an ARCHIVE-NAME, `tar' reads the archive from
6030 standard input (when listing or extracting files), or writes it to
6031 standard output (when creating an archive). If you use `-' as an
6032 ARCHIVE-NAME when modifying an archive, `tar' reads the original
6033 archive from its standard input and writes the entire new archive to
6034 its standard output.
6036 The following example is a convenient way of copying directory
6037 hierarchy from `sourcedir' to `targetdir'.
6039 $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)
6041 The `-C' option allows to avoid using subshells:
6043 $ tar -C sourcedir -cf - . | tar -C targetdir -xpf -
6045 In both examples above, the leftmost `tar' invocation archives the
6046 contents of `sourcedir' to the standard output, while the rightmost one
6047 reads this archive from its standard input and extracts it. The `-p'
6048 option tells it to restore permissions of the extracted files.
6050 To specify an archive file on a device attached to a remote machine,
6053 --file=HOSTNAME:/DEV/FILE-NAME
6055 `tar' will set up the remote connection, if possible, and prompt you
6056 for a username and password. If you use
6057 `--file=@HOSTNAME:/DEV/FILE-NAME', `tar' will attempt to set up the
6058 remote connection using your username as the username on the remote
6061 If the archive file name includes a colon (`:'), then it is assumed
6062 to be a file on another machine. If the archive file is
6063 `USER@HOST:FILE', then FILE is used on the host HOST. The remote host
6064 is accessed using the `rsh' program, with a username of USER. If the
6065 username is omitted (along with the `@' sign), then your user name will
6066 be used. (This is the normal `rsh' behavior.) It is necessary for the
6067 remote machine, in addition to permitting your `rsh' access, to have
6068 the `rmt' program installed (this command is included in the GNU `tar'
6069 distribution and by default is installed under `PREFIX/libexec/rmt',
6070 where PREFIX means your installation prefix). If you need to use a
6071 file whose name includes a colon, then the remote tape drive behavior
6072 can be inhibited by using the `--force-local' option.
6074 When the archive is being created to `/dev/null', GNU `tar' tries to
6075 minimize input and output operations. The Amanda backup system, when
6076 used with GNU `tar', has an initial sizing pass which uses this feature.
6079 File: tar.info, Node: Selecting Archive Members, Next: files, Prev: file, Up: Choosing
6081 6.2 Selecting Archive Members
6082 =============================
6084 "File Name arguments" specify which files in the file system `tar'
6085 operates on, when creating or adding to an archive, or which archive
6086 members `tar' operates on, when reading or deleting from an archive.
6089 To specify file names, you can include them as the last arguments on
6090 the command line, as follows:
6091 tar OPERATION [OPTION1 OPTION2 ...] [FILE NAME-1 FILE NAME-2 ...]
6093 If a file name begins with dash (`-'), precede it with `--add-file'
6094 option to prevent it from being treated as an option.
6096 By default GNU `tar' attempts to "unquote" each file or member name,
6097 replacing "escape sequences" according to the following table:
6099 Escape Replaced with
6100 -----------------------------------------------------------
6101 \a Audible bell (ASCII 7)
6102 \b Backspace (ASCII 8)
6103 \f Form feed (ASCII 12)
6104 \n New line (ASCII 10)
6105 \r Carriage return (ASCII 13)
6106 \t Horizontal tabulation (ASCII 9)
6107 \v Vertical tabulation (ASCII 11)
6109 \N ASCII N (N should be an octal number
6112 A backslash followed by any other symbol is retained.
6114 This default behavior is controlled by the following command line
6118 Enable unquoting input file or member names (default).
6121 Disable unquoting input file or member names.
6123 If you specify a directory name as a file name argument, all the
6124 files in that directory are operated on by `tar'.
6126 If you do not specify files, `tar' behavior differs depending on the
6127 operation mode as described below:
6129 When `tar' is invoked with `--create' (`-c'), `tar' will stop
6130 immediately, reporting the following:
6133 tar: Cowardly refusing to create an empty archive
6134 Try 'tar --help' or 'tar --usage' for more information.
6136 If you specify either `--list' (`-t') or `--extract' (`--get',
6137 `-x'), `tar' operates on all the archive members in the archive.
6139 If run with `--diff' option, tar will compare the archive with the
6140 contents of the current working directory.
6142 If you specify any other operation, `tar' does nothing.
6144 By default, `tar' takes file names from the command line. However,
6145 there are other ways to specify file or member names, or to modify the
6146 manner in which `tar' selects the files or members upon which to
6147 operate. In general, these methods work both for specifying the names
6148 of files and archive members.
6151 File: tar.info, Node: files, Next: exclude, Prev: Selecting Archive Members, Up: Choosing
6153 6.3 Reading Names from a File
6154 =============================
6156 Instead of giving the names of files or archive members on the command
6157 line, you can put the names into a file, and then use the
6158 `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option to `tar'.
6159 Give the name of the file which contains the list of files to include
6160 as the argument to `--files-from'. In the list, the file names should
6161 be separated by newlines. You will frequently use this option when you
6162 have generated the list of files to archive with the `find' utility.
6164 `--files-from=FILE-NAME'
6166 Get names to extract or create from file FILE-NAME.
6168 If you give a single dash as a file name for `--files-from', (i.e.,
6169 you specify either `--files-from=-' or `-T -'), then the file names are
6170 read from standard input.
6172 Unless you are running `tar' with `--create', you can not use both
6173 `--files-from=-' and `--file=-' (`-f -') in the same command.
6175 Any number of `-T' options can be given in the command line.
6177 The following example shows how to use `find' to generate a list of
6178 files smaller than 400K in length and put that list into a file called
6179 `small-files'. You can then use the `-T' option to `tar' to specify
6180 the files from that file, `small-files', to create the archive
6181 `little.tgz'. (The `-z' option to `tar' compresses the archive with
6182 `gzip'; *note gzip:: for more information.)
6184 $ find . -size -400 -print > small-files
6185 $ tar -c -v -z -T small-files -f little.tgz
6187 In the file list given by `-T' option, any file name beginning with `-'
6188 character is considered a `tar' option and is processed accordingly(1).
6189 For example, the common use of this feature is to change to another
6190 directory by specifying `-C' option:
6198 $ tar -c -f foo.tar --files-from list
6200 In this example, `tar' will first switch to `/etc' directory and add
6201 files `passwd' and `hosts' to the archive. Then it will change to
6202 `/lib' directory and will archive the file `libc.a'. Thus, the
6203 resulting archive `foo.tar' will contain:
6210 If you happen to have a file whose name starts with `-', precede it
6211 with `--add-file' option to prevent it from being recognized as an
6212 option. For example: `--add-file=--my-file'.
6218 ---------- Footnotes ----------
6220 (1) Versions of GNU `tar' up to 1.15.1 recognized only `-C' option
6221 in file lists, and only if the option and its argument occupied two
6225 File: tar.info, Node: nul, Up: files
6227 6.3.1 `NUL'-Terminated File Names
6228 ---------------------------------
6230 The `--null' option causes `--files-from=FILE-OF-NAMES' (`-T
6231 FILE-OF-NAMES') to read file names terminated by a `NUL' instead of a
6232 newline, so files whose names contain newlines can be archived using
6236 Only consider `NUL'-terminated file names, instead of files that
6237 terminate in a newline.
6240 Undo the effect of any previous `--null' option.
6242 The `--null' option is just like the one in GNU `xargs' and `cpio',
6243 and is useful with the `-print0' predicate of GNU `find'. In `tar',
6244 `--null' also disables special handling for file names that begin with
6247 This example shows how to use `find' to generate a list of files
6248 larger than 800K in length and put that list into a file called
6249 `long-files'. The `-print0' option to `find' is just like `-print',
6250 except that it separates files with a `NUL' rather than with a newline.
6251 You can then run `tar' with both the `--null' and `-T' options to
6252 specify that `tar' gets the files from that file, `long-files', to
6253 create the archive `big.tgz'. The `--null' option to `tar' will cause
6254 `tar' to recognize the `NUL' separator between files.
6256 $ find . -size +800 -print0 > long-files
6257 $ tar -c -v --null --files-from=long-files --file=big.tar
6259 The `--no-null' option can be used if you need to read both
6260 `NUL'-terminated and newline-terminated files on the same command line.
6261 For example, if `flist' is a newline-terminated file, then the
6262 following command can be used to combine it with the above command:
6264 $ find . -size +800 -print0 |
6265 tar -c -f big.tar --null -T - --no-null -T flist
6267 This example uses short options for typographic reasons, to avoid
6270 GNU `tar' is tries to automatically detect `NUL'-terminated file
6271 lists, so in many cases it is safe to use them even without the
6272 `--null' option. In this case `tar' will print a warning and continue
6273 reading such a file as if `--null' were actually given:
6275 $ find . -size +800 -print0 | tar -c -f big.tar -T -
6276 tar: -: file name read contains nul character
6278 The null terminator, however, remains in effect only for this
6279 particular file, any following `-T' options will assume newline
6280 termination. Of course, the null autodetection applies to these
6281 eventual surplus `-T' options as well.
6284 File: tar.info, Node: exclude, Next: wildcards, Prev: files, Up: Choosing
6286 6.4 Excluding Some Files
6287 ========================
6289 To avoid operating on files whose names match a particular pattern, use
6290 the `--exclude' or `--exclude-from' options.
6293 Causes `tar' to ignore files that match the PATTERN.
6295 The `--exclude=PATTERN' option prevents any file or member whose
6296 name matches the shell wildcard (PATTERN) from being operated on. For
6297 example, to create an archive with all the contents of the directory
6298 `src' except for files whose names end in `.o', use the command `tar
6299 -cf src.tar --exclude='*.o' src'.
6301 You may give multiple `--exclude' options.
6303 `--exclude-from=FILE'
6305 Causes `tar' to ignore files that match the patterns listed in
6308 Use the `--exclude-from' option to read a list of patterns, one per
6309 line, from FILE; `tar' will ignore files matching those patterns. Thus
6310 if `tar' is called as `tar -c -X foo .' and the file `foo' contains a
6311 single line `*.o', no files whose names end in `.o' will be added to
6314 Notice, that lines from FILE are read verbatim. One of the frequent
6315 errors is leaving some extra whitespace after a file name, which is
6316 difficult to catch using text editors.
6318 However, empty lines are OK.
6320 When archiving directories that are under some version control
6321 system (VCS), it is often convenient to read exclusion patterns from
6322 this VCS' ignore files (e.g. `.cvsignore', `.gitignore', etc.) The
6323 following options provide such possibilty:
6325 `--exclude-vcs-ignores'
6326 Before archiving a directory, see if it contains any of the
6327 following files: `cvsignore', `.gitignore', `.bzrignore', or
6328 `.hgignore'. If so, read ignore patterns from these files.
6330 The patterns are treated much as the corresponding VCS would treat
6334 Contains shell-style globbing patterns that apply only to the
6335 directory where this file resides. No comments are allowed
6336 in the file. Empty lines are ignored.
6339 Contains shell-style globbing patterns. Applies to the
6340 directory where `.gitfile' is located and all its
6343 Any line beginning with a `#' is a comment. Backslash escapes
6344 the comment character.
6347 Contains shell globbing-patterns and regular expressions (if
6348 prefixed with `RE:'(1). Patterns affect the directory and
6349 all its subdirectories.
6351 Any line beginning with a `#' is a comment.
6354 Contains posix regular expressions(2). The line `syntax:
6355 glob' switches to shell globbing patterns. The line `syntax:
6356 regexp' switches back. Comments begin with a `#'. Patterns
6357 affect the directory and all its subdirectories.
6359 `--exclude-ignore=FILE'
6360 Before dumping a directory, `tar' checks if it contains FILE. If
6361 so, exclusion patterns are read from this file. The patterns
6362 affect only the directory itself.
6364 `--exclude-ignore-recursive=FILE'
6365 Same as `--exclude-ignore', except that the patterns read affect
6366 both the directory where FILE resides and all its subdirectories.
6369 Exclude files and directories used by following version control
6370 systems: `CVS', `RCS', `SCCS', `SVN', `Arch', `Bazaar',
6371 `Mercurial', and `Darcs'.
6373 As of version 1.28, the following files are excluded:
6375 * `CVS/', and everything under it
6377 * `RCS/', and everything under it
6379 * `SCCS/', and everything under it
6381 * `.git/', and everything under it
6387 * `.svn/', and everything under it
6389 * `.arch-ids/', and everything under it
6391 * `{arch}/', and everything under it
6414 Exclude backup and lock files. This option causes exclusion of
6415 files that match the following shell globbing patterns:
6424 When creating an archive, the `--exclude-caches' option family
6425 causes `tar' to exclude all directories that contain a "cache directory
6426 tag". A cache directory tag is a short file with the well-known name
6427 `CACHEDIR.TAG' and having a standard header specified in
6428 `http://www.brynosaurus.com/cachedir/spec.html'. Various applications
6429 write cache directory tags into directories they use to hold
6430 regenerable, non-precious data, so that such data can be more easily
6431 excluded from backups.
6433 There are three `exclude-caches' options, each providing a different
6434 exclusion semantics:
6437 Do not archive the contents of the directory, but archive the
6438 directory itself and the `CACHEDIR.TAG' file.
6440 `--exclude-caches-under'
6441 Do not archive the contents of the directory, nor the
6442 `CACHEDIR.TAG' file, archive only the directory itself.
6444 `--exclude-caches-all'
6445 Omit directories containing `CACHEDIR.TAG' file entirely.
6447 Another option family, `--exclude-tag', provides a generalization of
6448 this concept. It takes a single argument, a file name to look for.
6449 Any directory that contains this file will be excluded from the dump.
6450 Similarly to `exclude-caches', there are three options in this option
6453 `--exclude-tag=FILE'
6454 Do not dump the contents of the directory, but dump the directory
6455 itself and the FILE.
6457 `--exclude-tag-under=FILE'
6458 Do not dump the contents of the directory, nor the FILE, archive
6459 only the directory itself.
6461 `--exclude-tag-all=FILE'
6462 Omit directories containing FILE file entirely.
6464 Multiple `--exclude-tag*' options can be given.
6466 For example, given this directory:
6477 The `--exclude-tag' will produce the following:
6479 $ tar -cf archive.tar --exclude-tag=tagfile -v dir
6484 tar: dir/folk/: contains a cache directory tag tagfile;
6488 Both the `dir/folk' directory and its tagfile are preserved in the
6489 archive, however the rest of files in this directory are not.
6491 Now, using the `--exclude-tag-under' option will exclude `tagfile'
6492 from the dump, while still preserving the directory itself, as shown in
6495 $ tar -cf archive.tar --exclude-tag-under=tagfile -v dir
6500 ./tar: dir/folk/: contains a cache directory tag tagfile;
6503 Finally, using `--exclude-tag-all' omits the `dir/folk' directory
6506 $ tar -cf archive.tar --exclude-tag-all=tagfile -v dir
6510 ./tar: dir/folk/: contains a cache directory tag tagfile;
6511 directory not dumped
6515 * problems with exclude::
6517 ---------- Footnotes ----------
6519 (1) According to the Bazaar docs, globbing-patterns are Korn-shell
6520 style and regular expressions are perl-style. As of GNU `tar' version
6521 1.28, these are treated as shell-style globs and posix extended
6522 regexps. This will be fixed in future releases.
6524 (2) Support for perl-style regexps will appear in future releases.
6527 File: tar.info, Node: problems with exclude, Up: exclude
6529 Problems with Using the `exclude' Options
6530 -----------------------------------------
6532 Some users find `exclude' options confusing. Here are some common
6535 * The main operating mode of `tar' does not act on a file name
6536 explicitly listed on the command line, if one of its file name
6537 components is excluded. In the example above, if you create an
6538 archive and exclude files that end with `*.o', but explicitly name
6539 the file `dir.o/foo' after all the options have been listed,
6540 `dir.o/foo' will be excluded from the archive.
6542 * You can sometimes confuse the meanings of `--exclude' and
6543 `--exclude-from'. Be careful: use `--exclude' when files to be
6544 excluded are given as a pattern on the command line. Use
6545 `--exclude-from' to introduce the name of a file which contains a
6546 list of patterns, one per line; each of these patterns can exclude
6547 zero, one, or many files.
6549 * When you use `--exclude=PATTERN', be sure to quote the PATTERN
6550 parameter, so GNU `tar' sees wildcard characters like `*'. If you
6551 do not do this, the shell might expand the `*' itself using files
6552 at hand, so `tar' might receive a list of files instead of one
6553 pattern, or none at all, making the command somewhat illegal.
6554 This might not correspond to what you want.
6558 $ tar -c -f ARCHIVE.TAR --exclude '*.o' DIRECTORY
6563 $ tar -c -f ARCHIVE.TAR --exclude *.o DIRECTORY
6565 * You must use use shell syntax, or globbing, rather than `regexp'
6566 syntax, when using exclude options in `tar'. If you try to use
6567 `regexp' syntax to describe files to be excluded, your command
6570 * In earlier versions of `tar', what is now the `--exclude-from'
6571 option was called `--exclude' instead. Now, `--exclude' applies
6572 to patterns listed on the command line and `--exclude-from'
6573 applies to patterns listed in a file.
6577 File: tar.info, Node: wildcards, Next: quoting styles, Prev: exclude, Up: Choosing
6579 6.5 Wildcards Patterns and Matching
6580 ===================================
6582 "Globbing" is the operation by which "wildcard" characters, `*' or `?'
6583 for example, are replaced and expanded into all existing files matching
6584 the given pattern. GNU `tar' can use wildcard patterns for matching
6585 (or globbing) archive members when extracting from or listing an
6586 archive. Wildcard patterns are also used for verifying volume labels
6587 of `tar' archives. This section has the purpose of explaining wildcard
6590 A PATTERN should be written according to shell syntax, using wildcard
6591 characters to effect globbing. Most characters in the pattern stand
6592 for themselves in the matched string, and case is significant: `a' will
6593 match only `a', and not `A'. The character `?' in the pattern matches
6594 any single character in the matched string. The character `*' in the
6595 pattern matches zero, one, or more single characters in the matched
6596 string. The character `\' says to take the following character of the
6597 pattern _literally_; it is useful when one needs to match the `?', `*',
6598 `[' or `\' characters, themselves.
6600 The character `[', up to the matching `]', introduces a character
6601 class. A "character class" is a list of acceptable characters for the
6602 next single character of the matched string. For example, `[abcde]'
6603 would match any of the first five letters of the alphabet. Note that
6604 within a character class, all of the "special characters" listed above
6605 other than `\' lose their special meaning; for example, `[-\\[*?]]'
6606 would match any of the characters, `-', `\', `[', `*', `?', or `]'.
6607 (Due to parsing constraints, the characters `-' and `]' must either
6608 come _first_ or _last_ in a character class.)
6610 If the first character of the class after the opening `[' is `!' or
6611 `^', then the meaning of the class is reversed. Rather than listing
6612 character to match, it lists those characters which are _forbidden_ as
6613 the next single character of the matched string.
6615 Other characters of the class stand for themselves. The special
6616 construction `[A-E]', using an hyphen between two letters, is meant to
6617 represent all characters between A and E, inclusive.
6619 Periods (`.') or forward slashes (`/') are not considered special
6620 for wildcard matches. However, if a pattern completely matches a
6621 directory prefix of a matched string, then it matches the full matched
6622 string: thus, excluding a directory also excludes all the files beneath
6627 * controlling pattern-matching::
6630 File: tar.info, Node: controlling pattern-matching, Up: wildcards
6632 Controlling Pattern-Matching
6633 ----------------------------
6635 For the purposes of this section, we call "exclusion members" all
6636 member names obtained while processing `--exclude' and `--exclude-from'
6637 options, and "inclusion members" those member names that were given in
6638 the command line or read from the file specified with `--files-from'
6641 These two pairs of member lists are used in the following operations:
6642 `--diff', `--extract', `--list', `--update'.
6644 There are no inclusion members in create mode (`--create' and
6645 `--append'), since in this mode the names obtained from the command
6646 line refer to _files_, not archive members.
6648 By default, inclusion members are compared with archive members
6649 literally (1) and exclusion members are treated as globbing patterns.
6657 # Member names are used verbatim:
6658 $ tar -xf foo.tar -v '[remarks]'
6660 # Exclude member names are globbed:
6661 $ tar -xf foo.tar -v --exclude '*.c'
6665 This behavior can be altered by using the following options:
6668 Treat all member names as wildcards.
6671 Treat all member names as literal strings.
6673 Thus, to extract files whose names end in `.c', you can use:
6675 $ tar -xf foo.tar -v --wildcards '*.c'
6679 Notice quoting of the pattern to prevent the shell from interpreting it.
6681 The effect of `--wildcards' option is canceled by `--no-wildcards'.
6682 This can be used to pass part of the command line arguments verbatim
6683 and other part as globbing patterns. For example, the following
6686 $ tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'
6688 instructs `tar' to extract from `foo.tar' all files whose names end in
6689 `.txt' and the file named `[remarks]'.
6691 Normally, a pattern matches a name if an initial subsequence of the
6692 name's components matches the pattern, where `*', `?', and `[...]' are
6693 the usual shell wildcards, `\' escapes wildcards, and wildcards can
6696 Other than optionally stripping leading `/' from names (*note
6697 absolute::), patterns and names are used as-is. For example, trailing
6698 `/' is not trimmed from a user-specified name before deciding whether
6701 However, this matching procedure can be altered by the options listed
6702 below. These options accumulate. For example:
6704 --ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
6706 ignores case when excluding `makefile', but not when excluding `readme'.
6710 If anchored, a pattern must match an initial subsequence of the
6711 name's components. Otherwise, the pattern can match any
6712 subsequence. Default is `--no-anchored' for exclusion members and
6713 `--anchored' inclusion members.
6717 When ignoring case, upper-case patterns match lower-case names and
6718 vice versa. When not ignoring case (the default), matching is
6721 `--wildcards-match-slash'
6722 `--no-wildcards-match-slash'
6723 When wildcards match slash (the default for exclusion members), a
6724 wildcard like `*' in the pattern can match a `/' in the name.
6725 Otherwise, `/' is matched only by `/'.
6728 The `--recursion' and `--no-recursion' options (*note recurse::)
6729 also affect how member patterns are interpreted. If recursion is in
6730 effect, a pattern matches a name if it matches any of the name's parent
6733 The following table summarizes pattern-matching default values:
6735 Members Default settings
6736 --------------------------------------------------------------------------
6737 Inclusion `--no-wildcards --anchored
6738 --no-wildcards-match-slash'
6739 Exclusion `--wildcards --no-anchored
6740 --wildcards-match-slash'
6742 ---------- Footnotes ----------
6744 (1) Notice that earlier GNU `tar' versions used globbing for
6745 inclusion members, which contradicted to UNIX98 specification and was
6746 not documented. *Note Changes::, for more information on this and other
6750 File: tar.info, Node: quoting styles, Next: transform, Prev: wildcards, Up: Choosing
6752 6.6 Quoting Member Names
6753 ========================
6755 When displaying member names, `tar' takes care to avoid ambiguities
6756 caused by certain characters. This is called "name quoting". The
6757 characters in question are:
6759 * Non-printable control characters:
6760 Character ASCII Character name
6761 ---------------------------------------------------------------
6766 \r 13 Carriage return
6767 \t 9 Horizontal tabulation
6768 \v 11 Vertical tabulation
6772 * Single and double quotes (`'' and `"')
6776 The exact way `tar' uses to quote these characters depends on the
6777 "quoting style". The default quoting style, called "escape" (see
6778 below), uses backslash notation to represent control characters, space
6779 and backslash. Using this quoting style, control characters are
6780 represented as listed in column `Character' in the above table, a space
6781 is printed as `\ ' and a backslash as `\\'.
6783 GNU `tar' offers seven distinct quoting styles, which can be selected
6784 using `--quoting-style' option:
6786 `--quoting-style=STYLE'
6787 Sets quoting style. Valid values for STYLE argument are: literal,
6788 shell, shell-always, c, escape, locale, clocale.
6790 These styles are described in detail below. To illustrate their
6791 effect, we will use an imaginary tar archive `arch.tar' containing the
6794 # 1. Contains horizontal tabulation character.
6796 # 2. Contains newline character
6799 # 3. Contains a space
6801 # 4. Contains double quotes
6803 # 5. Contains single quotes
6805 # 6. Contains a backslash character:
6808 Here is how usual `ls' command would have listed them, if they had
6809 existed in the current working directory:
6822 No quoting, display each character as is:
6824 $ tar tf arch.tar --quoting-style=literal
6835 Display characters the same way Bourne shell does: control
6836 characters, except `\t' and `\n', are printed using backslash
6837 escapes, `\t' and `\n' are printed as is, and a single quote is
6838 printed as `\''. If a name contains any quoted characters, it is
6839 enclosed in single quotes. In particular, if a name contains
6840 single quotes, it is printed as several single-quoted strings:
6842 $ tar tf arch.tar --quoting-style=shell
6845 './a'\''single'\''quote'
6853 Same as `shell', but the names are always enclosed in single
6856 $ tar tf arch.tar --quoting-style=shell-always
6859 './a'\''single'\''quote'
6867 Use the notation of the C programming language. All names are
6868 enclosed in double quotes. Control characters are quoted using
6869 backslash notations, double quotes are represented as `\"',
6870 backslash characters are represented as `\\'. Single quotes and
6871 spaces are not quoted:
6873 $ tar tf arch.tar --quoting-style=c
6877 "./a\"double\"quote"
6883 Control characters are printed using backslash notation, a space is
6884 printed as `\ ' and a backslash as `\\'. This is the default
6885 quoting style, unless it was changed when configured the package.
6887 $ tar tf arch.tar --quoting-style=escape
6897 Control characters, single quote and backslash are printed using
6898 backslash notation. All names are quoted using left and right
6899 quotation marks, appropriate to the current locale. If it does not
6900 define quotation marks, use `'' as left and as right quotation
6901 marks. Any occurrences of the right quotation mark in a name are
6902 escaped with `\', for example:
6906 $ tar tf arch.tar --quoting-style=locale
6909 './a\'single\'quote'
6916 Same as `locale', but `"' is used for both left and right
6917 quotation marks, if not provided by the currently selected locale:
6919 $ tar tf arch.tar --quoting-style=clocale
6923 "./a\"double\"quote"
6928 You can specify which characters should be quoted in addition to
6929 those implied by the current quoting style:
6931 `--quote-chars=STRING'
6932 Always quote characters from STRING, even if the selected quoting
6933 style would not quote them.
6935 For example, using `escape' quoting (compare with the usual escape
6938 $ tar tf arch.tar --quoting-style=escape --quote-chars=' "'
6947 To disable quoting of such additional characters, use the following
6950 `--no-quote-chars=STRING'
6951 Remove characters listed in STRING from the list of quoted
6952 characters set by the previous `--quote-chars' option.
6954 This option is particularly useful if you have added `--quote-chars'
6955 to your `TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to disable it for
6956 the current invocation.
6958 Note, that `--no-quote-chars' does _not_ disable those characters
6959 that are quoted by default in the selected quoting style.
6962 File: tar.info, Node: transform, Next: after, Prev: quoting styles, Up: Choosing
6964 6.7 Modifying File and Member Names
6965 ===================================
6967 `Tar' archives contain detailed information about files stored in them
6968 and full file names are part of that information. When storing a file
6969 to an archive, its file name is recorded in it, along with the actual
6970 file contents. When restoring from an archive, a file is created on
6971 disk with exactly the same name as that stored in the archive. In the
6972 majority of cases this is the desired behavior of a file archiver.
6973 However, there are some cases when it is not.
6975 First of all, it is often unsafe to extract archive members with
6976 absolute file names or those that begin with a `../'. GNU `tar' takes
6977 special precautions when extracting such names and provides a special
6978 option for handling them, which is described in *note absolute::.
6980 Secondly, you may wish to extract file names without some leading
6981 directory components, or with otherwise modified names. In other cases
6982 it is desirable to store files under differing names in the archive.
6984 GNU `tar' provides several options for these needs.
6986 `--strip-components=NUMBER'
6987 Strip given NUMBER of leading components from file names before
6990 For example, suppose you have archived whole `/usr' hierarchy to a
6991 tar archive named `usr.tar'. Among other files, this archive contains
6992 `usr/include/stdlib.h', which you wish to extract to the current
6993 working directory. To do so, you type:
6995 $ tar -xf usr.tar --strip=2 usr/include/stdlib.h
6997 The option `--strip=2' instructs `tar' to strip the two leading
6998 components (`usr/' and `include/') off the file name.
7000 If you add the `--verbose' (`-v') option to the invocation above,
7001 you will note that the verbose listing still contains the full file
7002 name, with the two removed components still in place. This can be
7003 inconvenient, so `tar' provides a special option for altering this
7006 `--show-transformed-names'
7007 Display file or member names with all requested transformations
7012 $ tar -xf usr.tar -v --strip=2 usr/include/stdlib.h
7013 usr/include/stdlib.h
7014 $ tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h
7017 Notice that in both cases the file `stdlib.h' is extracted to the
7018 current working directory, `--show-transformed-names' affects only the
7019 way its name is displayed.
7021 This option is especially useful for verifying whether the invocation
7022 will have the desired effect. Thus, before running
7026 it is often advisable to run
7028 $ tar -t -v --show-transformed --strip=N
7030 to make sure the command will produce the intended results.
7032 In case you need to apply more complex modifications to the file
7033 name, GNU `tar' provides a general-purpose transformation option:
7035 `--transform=EXPRESSION'
7036 `--xform=EXPRESSION'
7037 Modify file names using supplied EXPRESSION.
7039 The EXPRESSION is a `sed'-like replace expression of the form:
7041 s/REGEXP/REPLACE/[FLAGS]
7043 where REGEXP is a "regular expression", REPLACE is a replacement for
7044 each file name part that matches REGEXP. Both REGEXP and REPLACE are
7045 described in detail in *note The "s" Command: (sed)The "s" Command.
7047 Any delimiter can be used in lieu of `/', the only requirement being
7048 that it be used consistently throughout the expression. For example,
7049 the following two expressions are equivalent:
7054 Changing delimiters is often useful when the REGEX contains slashes.
7055 For example, it is more convenient to write `s,/,-,' than `s/\//-/'.
7057 As in `sed', you can give several replace expressions, separated by
7060 Supported FLAGS are:
7063 Apply the replacement to _all_ matches to the REGEXP, not just the
7067 Use case-insensitive matching.
7070 REGEXP is an "extended regular expression" (*note Extended regular
7071 expressions: (sed)Extended regexps.).
7074 Only replace the NUMBERth match of the REGEXP.
7076 Note: the POSIX standard does not specify what should happen when
7077 you mix the `g' and NUMBER modifiers. GNU `tar' follows the GNU
7078 `sed' implementation in this regard, so the interaction is defined
7079 to be: ignore matches before the NUMBERth, and then match and
7080 replace all matches from the NUMBERth on.
7083 In addition, several "transformation scope" flags are supported,
7084 that control to what files transformations apply. These are:
7087 Apply transformation to regular archive members.
7090 Do not apply transformation to regular archive members.
7093 Apply transformation to symbolic link targets.
7096 Do not apply transformation to symbolic link targets.
7099 Apply transformation to hard link targets.
7102 Do not apply transformation to hard link targets.
7104 Default is `rsh', which means to apply tranformations to both archive
7105 members and targets of symbolic and hard links.
7107 Default scope flags can also be changed using `flags=' statement in
7108 the transform expression. The flags set this way remain in force until
7109 next `flags=' statement or end of expression, whichever occurs first.
7112 --transform 'flags=S;s|^|/usr/local/|'
7114 Here are several examples of `--transform' usage:
7116 1. Extract `usr/' hierarchy into `usr/local/':
7118 $ tar --transform='s,usr/,usr/local/,' -x -f arch.tar
7120 2. Strip two leading directory components (equivalent to
7121 `--strip-components=2'):
7123 $ tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar
7125 3. Convert each file name to lower case:
7127 $ tar --transform 's/.*/\L&/' -x -f arch.tar
7129 4. Prepend `/prefix/' to each file name:
7131 $ tar --transform 's,^,/prefix/,' -x -f arch.tar
7133 5. Archive the `/lib' directory, prepending `/usr/local' to each
7136 $ tar --transform 's,^,/usr/local/,S' -c -f arch.tar /lib
7138 Notice the use of flags in the last example. The `/lib' directory
7139 often contains many symbolic links to files within it. It may look,
7140 for example, like this:
7143 drwxr-xr-x root/root 0 2008-07-08 16:20 /lib/
7144 -rwxr-xr-x root/root 1250840 2008-05-25 07:44 /lib/libc-2.3.2.so
7145 lrwxrwxrwx root/root 0 2008-06-24 17:12 /lib/libc.so.6 -> libc-2.3.2.so
7148 Using the expression `s,^,/usr/local/,' would mean adding
7149 `/usr/local' to both regular archive members and to link targets. In
7150 this case, `/lib/libc.so.6' would become:
7152 /usr/local/lib/libc.so.6 -> /usr/local/libc-2.3.2.so
7154 This is definitely not desired. To avoid this, the `S' flag is
7155 used, which excludes symbolic link targets from filename
7156 transformations. The result is:
7158 $ tar --transform 's,^,/usr/local/,S', -c -v -f arch.tar \
7159 --show-transformed /lib
7160 drwxr-xr-x root/root 0 2008-07-08 16:20 /usr/local/lib/
7161 -rwxr-xr-x root/root 1250840 2008-05-25 07:44 /usr/local/lib/libc-2.3.2.so
7162 lrwxrwxrwx root/root 0 2008-06-24 17:12 /usr/local/lib/libc.so.6 \
7165 Unlike `--strip-components', `--transform' can be used in any GNU
7166 `tar' operation mode. For example, the following command adds files to
7167 the archive while replacing the leading `usr/' component with `var/':
7169 $ tar -cf arch.tar --transform='s,^usr/,var/,' /
7171 To test `--transform' effect we suggest using
7172 `--show-transformed-names' option:
7174 $ tar -cf arch.tar --transform='s,^usr/,var/,' \
7175 --verbose --show-transformed-names /
7177 If both `--strip-components' and `--transform' are used together,
7178 then `--transform' is applied first, and the required number of
7179 components is then stripped from its result.
7181 You can use as many `--transform' options in a single command line
7182 as you want. The specified expressions will then be applied in order
7183 of their appearance. For example, the following two invocations are
7186 $ tar -cf arch.tar --transform='s,/usr/var,/var/' \
7187 --transform='s,/usr/local,/usr/,'
7188 $ tar -cf arch.tar \
7189 --transform='s,/usr/var,/var/;s,/usr/local,/usr/,'
7192 File: tar.info, Node: after, Next: recurse, Prev: transform, Up: Choosing
7194 6.8 Operating Only on New Files
7195 ===============================
7197 The `--after-date=DATE' (`--newer=DATE', `-N DATE') option causes `tar'
7198 to only work on files whose data modification or status change times
7199 are newer than the DATE given. If DATE starts with `/' or `.', it is
7200 taken to be a file name; the data modification time of that file is
7201 used as the date. If you use this option when creating or appending to
7202 an archive, the archive will only include new files. If you use
7203 `--after-date' when extracting an archive, `tar' will only extract
7204 files newer than the DATE you specify.
7206 If you only want `tar' to make the date comparison based on
7207 modification of the file's data (rather than status changes), then use
7208 the `--newer-mtime=DATE' option.
7210 You may use these options with any operation. Note that these
7211 options differ from the `--update' (`-u') operation in that they allow
7212 you to specify a particular date against which `tar' can compare when
7213 deciding whether or not to archive the files.
7218 Only store files newer than DATE.
7220 Acts on files only if their data modification or status change
7221 times are later than DATE. Use in conjunction with any operation.
7223 If DATE starts with `/' or `.', it is taken to be a file name; the
7224 data modification time of that file is used as the date.
7226 `--newer-mtime=DATE'
7227 Acts like `--after-date', but only looks at data modification
7230 These options limit `tar' to operate only on files which have been
7231 modified after the date specified. A file's status is considered to
7232 have changed if its contents have been modified, or if its owner,
7233 permissions, and so forth, have been changed. (For more information on
7234 how to specify a date, see *note Date input formats::; remember that the
7235 entire date argument must be quoted if it contains any spaces.)
7237 Gurus would say that `--after-date' tests both the data modification
7238 time (`mtime', the time the contents of the file were last modified)
7239 and the status change time (`ctime', the time the file's status was
7240 last changed: owner, permissions, etc.) fields, while `--newer-mtime'
7241 tests only the `mtime' field.
7243 To be precise, `--after-date' checks _both_ `mtime' and `ctime' and
7244 processes the file if either one is more recent than DATE, while
7245 `--newer-mtime' only checks `mtime' and disregards `ctime'. Neither
7246 does it use `atime' (the last time the contents of the file were looked
7249 Date specifiers can have embedded spaces. Because of this, you may
7250 need to quote date arguments to keep the shell from parsing them as
7251 separate arguments. For example, the following command will add to the
7252 archive all the files modified less than two days ago:
7254 $ tar -cf foo.tar --newer-mtime '2 days ago'
7256 When any of these options is used with the option `--verbose' (*note
7257 verbose tutorial::) GNU `tar' will try to convert the specified date
7258 back to its textual representation and compare that with the one given
7259 with the option. If the two dates differ, `tar' will print a warning
7260 saying what date it will use. This is to help user ensure he is using
7261 the right date. For example:
7263 $ tar -c -f archive.tar --after-date='10 days ago' .
7264 tar: Option --after-date: Treating date '10 days ago' as 2006-06-11
7267 *Please Note:* `--after-date' and `--newer-mtime' should not be
7268 used for incremental backups. *Note Incremental Dumps::, for
7269 proper way of creating incremental backups.
7272 File: tar.info, Node: recurse, Next: one, Prev: after, Up: Choosing
7274 6.9 Descending into Directories
7275 ===============================
7277 Usually, `tar' will recursively explore all directories (either those
7278 given on the command line or through the `--files-from' option) for the
7279 various files they contain. However, you may not always want `tar' to
7282 The `--no-recursion' option inhibits `tar''s recursive descent into
7283 specified directories. If you specify `--no-recursion', you can use
7284 the `find' (*note find: (find)Top.) utility for hunting through levels
7285 of directories to construct a list of file names which you could then
7286 pass to `tar'. `find' allows you to be more selective when choosing
7287 which files to archive; see *note files::, for more information on
7288 using `find' with `tar'.
7291 Prevents `tar' from recursively descending directories.
7294 Requires `tar' to recursively descend directories. This is the
7297 When you use `--no-recursion', GNU `tar' grabs directory entries
7298 themselves, but does not descend on them recursively. Many people use
7299 `find' for locating files they want to back up, and since `tar'
7300 _usually_ recursively descends on directories, they have to use the
7301 `-not -type d' test in their `find' invocation (*note Type:
7302 (find)Type.), as they usually do not want all the files in a directory.
7303 They then use the `--files-from' option to archive the files located
7306 The problem when restoring files archived in this manner is that the
7307 directories themselves are not in the archive; so the
7308 `--same-permissions' (`--preserve-permissions', `-p') option does not
7309 affect them--while users might really like it to. Specifying
7310 `--no-recursion' is a way to tell `tar' to grab only the directory
7311 entries given to it, adding no new files on its own. To summarize, if
7312 you use `find' to create a list of files to be stored in an archive,
7315 $ find DIR TESTS | \
7316 tar -cf ARCHIVE -T - --no-recursion
7318 The `--no-recursion' option also applies when extracting: it causes
7319 `tar' to extract only the matched directory entries, not the files
7320 under those directories.
7322 The `--no-recursion' option also affects how globbing patterns are
7323 interpreted (*note controlling pattern-matching::).
7325 The `--no-recursion' and `--recursion' options apply to later
7326 options and operands, and can be overridden by later occurrences of
7327 `--no-recursion' and `--recursion'. For example:
7329 $ tar -cf jams.tar --no-recursion grape --recursion grape/concord
7331 creates an archive with one entry for `grape', and the recursive
7332 contents of `grape/concord', but no entries under `grape' other than
7336 File: tar.info, Node: one, Prev: recurse, Up: Choosing
7338 6.10 Crossing File System Boundaries
7339 ====================================
7341 `tar' will normally automatically cross file system boundaries in order
7342 to archive files which are part of a directory tree. You can change
7343 this behavior by running `tar' and specifying `--one-file-system'.
7344 This option only affects files that are archived because they are in a
7345 directory that is being archived; `tar' will still archive files
7346 explicitly named on the command line or through `--files-from',
7347 regardless of where they reside.
7350 Prevents `tar' from crossing file system boundaries when
7351 archiving. Use in conjunction with any write operation.
7353 The `--one-file-system' option causes `tar' to modify its normal
7354 behavior in archiving the contents of directories. If a file in a
7355 directory is not on the same file system as the directory itself, then
7356 `tar' will not archive that file. If the file is a directory itself,
7357 `tar' will not archive anything beneath it; in other words, `tar' will
7358 not cross mount points.
7360 This option is useful for making full or incremental archival
7361 backups of a file system. If this option is used in conjunction with
7362 `--verbose' (`-v'), files that are excluded are mentioned by name on
7367 * directory:: Changing Directory
7368 * absolute:: Absolute File Names
7371 File: tar.info, Node: directory, Next: absolute, Up: one
7373 6.10.1 Changing the Working Directory
7374 -------------------------------------
7376 To change the working directory in the middle of a list of file names,
7377 either on the command line or in a file specified using `--files-from'
7378 (`-T'), use `--directory' (`-C'). This will change the working
7379 directory to the specified directory after that point in the list.
7381 `--directory=DIRECTORY'
7383 Changes the working directory in the middle of a command line.
7387 $ tar -c -f jams.tar grape prune -C food cherry
7389 will place the files `grape' and `prune' from the current directory
7390 into the archive `jams.tar', followed by the file `cherry' from the
7391 directory `food'. This option is especially useful when you have
7392 several widely separated files that you want to store in the same
7395 Note that the file `cherry' is recorded in the archive under the
7396 precise name `cherry', _not_ `food/cherry'. Thus, the archive will
7397 contain three files that all appear to have come from the same
7398 directory; if the archive is extracted with plain `tar --extract', all
7399 three files will be written in the current directory.
7401 Contrast this with the command,
7403 $ tar -c -f jams.tar grape prune -C food red/cherry
7405 which records the third file in the archive under the name `red/cherry'
7406 so that, if the archive is extracted using `tar --extract', the third
7407 file will be written in a subdirectory named `red'.
7409 You can use the `--directory' option to make the archive independent
7410 of the original name of the directory holding the files. The following
7411 command places the files `/etc/passwd', `/etc/hosts', and `/lib/libc.a'
7412 into the archive `foo.tar':
7414 $ tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a
7416 However, the names of the archive members will be exactly what they were
7417 on the command line: `passwd', `hosts', and `libc.a'. They will not
7418 appear to be related by file name to the original directories where
7419 those files were located.
7421 Note that `--directory' options are interpreted consecutively. If
7422 `--directory' specifies a relative file name, it is interpreted
7423 relative to the then current directory, which might not be the same as
7424 the original current working directory of `tar', due to a previous
7425 `--directory' option.
7427 When using `--files-from' (*note files::), you can put various `tar'
7428 options (including `-C') in the file list. Notice, however, that in
7429 this case the option and its argument may not be separated by
7430 whitespace. If you use short option, its argument must either follow
7431 the option letter immediately, without any intervening whitespace, or
7432 occupy the next line. Otherwise, if you use long option, separate its
7433 argument by an equal sign.
7435 For instance, the file list for the above example will be:
7443 To use it, you would invoke `tar' as follows:
7445 $ tar -c -f foo.tar --files-from list
7447 The interpretation of `--directory' is disabled by `--null' option.
7450 File: tar.info, Node: absolute, Prev: directory, Up: one
7452 6.10.2 Absolute File Names
7453 --------------------------
7455 By default, GNU `tar' drops a leading `/' on input or output, and
7456 complains about file names containing a `..' component. There is an
7457 option that turns off this behavior:
7461 Do not strip leading slashes from file names, and permit file names
7462 containing a `..' file name component.
7464 When `tar' extracts archive members from an archive, it strips any
7465 leading slashes (`/') from the member name. This causes absolute
7466 member names in the archive to be treated as relative file names. This
7467 allows you to have such members extracted wherever you want, instead of
7468 being restricted to extracting the member in the exact directory named
7469 in the archive. For example, if the archive member has the name
7470 `/etc/passwd', `tar' will extract it as if the name were really
7473 File names containing `..' can cause problems when extracting, so
7474 `tar' normally warns you about such files when creating an archive, and
7475 rejects attempts to extracts such files.
7477 Other `tar' programs do not do this. As a result, if you create an
7478 archive whose member names start with a slash, they will be difficult
7479 for other people with a non-GNU `tar' program to use. Therefore, GNU
7480 `tar' also strips leading slashes from member names when putting
7481 members into the archive. For example, if you ask `tar' to add the file
7482 `/bin/ls' to an archive, it will do so, but the member name will be
7485 Symbolic links containing `..' or leading `/' can also cause
7486 problems when extracting, so `tar' normally extracts them last; it may
7487 create empty files as placeholders during extraction.
7489 If you use the `--absolute-names' (`-P') option, `tar' will do none
7490 of these transformations.
7492 To archive or extract files relative to the root directory, specify
7493 the `--absolute-names' (`-P') option.
7495 Normally, `tar' acts on files relative to the working
7496 directory--ignoring superior directory names when archiving, and
7497 ignoring leading slashes when extracting.
7499 When you specify `--absolute-names' (`-P'), `tar' stores file names
7500 including all superior directory names, and preserves leading slashes.
7501 If you only invoked `tar' from the root directory you would never need
7502 the `--absolute-names' option, but using this option may be more
7503 convenient than switching to root.
7506 Preserves full file names (including superior directory names) when
7507 archiving and extracting files.
7510 `tar' prints out a message about removing the `/' from file names.
7511 This message appears once per GNU `tar' invocation. It represents
7512 something which ought to be told; ignoring what it means can cause very
7513 serious surprises, later.
7515 Some people, nevertheless, do not want to see this message. Wanting
7516 to play really dangerously, one may of course redirect `tar' standard
7517 error to the sink. For example, under `sh':
7519 $ tar -c -f archive.tar /home 2> /dev/null
7521 Another solution, both nicer and simpler, would be to change to the `/'
7522 directory first, and then avoid absolute notation. For example:
7524 $ tar -c -f archive.tar -C / home
7526 *Note Integrity::, for some of the security-related implications of
7529 ---------- Footnotes ----------
7531 (1) A side effect of this is that when `--create' is used with
7532 `--verbose' the resulting output is not, generally speaking, the same
7533 as the one you'd get running `tar --list' command. This may be
7534 important if you use some scripts for comparing both outputs. *Note
7535 listing member and file names::, for the information on how to handle
7539 File: tar.info, Node: Date input formats, Next: Formats, Prev: Choosing, Up: Top
7541 7 Date input formats
7542 ********************
7546 Our units of temporal measurement, from seconds on up to months,
7547 are so complicated, asymmetrical and disjunctive so as to make
7548 coherent mental reckoning in time all but impossible. Indeed, had
7549 some tyrannical god contrived to enslave our minds to time, to
7550 make it all but impossible for us to escape subjection to sodden
7551 routines and unpleasant surprises, he could hardly have done
7552 better than handing down our present system. It is like a set of
7553 trapezoidal building blocks, with no vertical or horizontal
7554 surfaces, like a language in which the simplest thought demands
7555 ornate constructions, useless particles and lengthy
7556 circumlocutions. Unlike the more successful patterns of language
7557 and science, which enable us to face experience boldly or at least
7558 level-headedly, our system of temporal calculation silently and
7559 persistently encourages our terror of time.
7561 ... It is as though architects had to measure length in feet,
7562 width in meters and height in ells; as though basic instruction
7563 manuals demanded a knowledge of five different languages. It is
7564 no wonder then that we often look into our own immediate past or
7565 future, last Tuesday or a week from Sunday, with feelings of
7566 helpless confusion. ...
7568 --Robert Grudin, `Time and the Art of Living'.
7570 This section describes the textual date representations that GNU
7571 programs accept. These are the strings you, as a user, can supply as
7572 arguments to the various programs. The C interface (via the
7573 `parse_datetime' function) is not described here.
7577 * General date syntax:: Common rules.
7578 * Calendar date items:: 19 Dec 1994.
7579 * Time of day items:: 9:20pm.
7580 * Time zone items:: EST, PDT, UTC, ...
7581 * Combined date and time of day items:: 1972-09-24T20:02:00,000000-0500.
7582 * Day of week items:: Monday and others.
7583 * Relative items in date strings:: next tuesday, 2 years ago.
7584 * Pure numbers in date strings:: 19931219, 1440.
7585 * Seconds since the Epoch:: @1078100502.
7586 * Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
7587 * Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al.
7590 File: tar.info, Node: General date syntax, Next: Calendar date items, Up: Date input formats
7592 7.1 General date syntax
7593 =======================
7595 A "date" is a string, possibly empty, containing many items separated
7596 by whitespace. The whitespace may be omitted when no ambiguity arises.
7597 The empty string means the beginning of today (i.e., midnight). Order
7598 of the items is immaterial. A date string may contain many flavors of
7601 * calendar date items
7607 * combined date and time of day items
7609 * day of the week items
7615 We describe each of these item types in turn, below.
7617 A few ordinal numbers may be written out in words in some contexts.
7618 This is most useful for specifying day of the week items or relative
7619 items (see below). Among the most commonly used ordinal numbers, the
7620 word `last' stands for -1, `this' stands for 0, and `first' and `next'
7621 both stand for 1. Because the word `second' stands for the unit of
7622 time there is no way to write the ordinal number 2, but for convenience
7623 `third' stands for 3, `fourth' for 4, `fifth' for 5, `sixth' for 6,
7624 `seventh' for 7, `eighth' for 8, `ninth' for 9, `tenth' for 10,
7625 `eleventh' for 11 and `twelfth' for 12.
7627 When a month is written this way, it is still considered to be
7628 written numerically, instead of being "spelled in full"; this changes
7629 the allowed strings.
7631 In the current implementation, only English is supported for words
7632 and abbreviations like `AM', `DST', `EST', `first', `January',
7633 `Sunday', `tomorrow', and `year'.
7635 The output of the `date' command is not always acceptable as a date
7636 string, not only because of the language problem, but also because
7637 there is no standard meaning for time zone items like `IST'. When using
7638 `date' to generate a date string intended to be parsed later, specify a
7639 date format that is independent of language and that does not use time
7640 zone items other than `UTC' and `Z'. Here are some ways to do this:
7642 $ LC_ALL=C TZ=UTC0 date
7643 Mon Mar 1 00:21:42 UTC 2004
7644 $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
7645 2004-03-01 00:21:42Z
7646 $ date --rfc-3339=ns # --rfc-3339 is a GNU extension.
7647 2004-02-29 16:21:42.692722128-08:00
7648 $ date --rfc-2822 # a GNU extension
7649 Sun, 29 Feb 2004 16:21:42 -0800
7650 $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension.
7651 2004-02-29 16:21:42 -0800
7652 $ date +'@%s.%N' # %s and %N are GNU extensions.
7653 @1078100502.692722128
7655 Alphabetic case is completely ignored in dates. Comments may be
7656 introduced between round parentheses, as long as included parentheses
7657 are properly nested. Hyphens not followed by a digit are currently
7658 ignored. Leading zeros on numbers are ignored.
7660 Invalid dates like `2005-02-29' or times like `24:00' are rejected.
7661 In the typical case of a host that does not support leap seconds, a
7662 time like `23:59:60' is rejected even if it corresponds to a valid leap
7666 File: tar.info, Node: Calendar date items, Next: Time of day items, Prev: General date syntax, Up: Date input formats
7668 7.2 Calendar date items
7669 =======================
7671 A "calendar date item" specifies a day of the year. It is specified
7672 differently, depending on whether the month is specified numerically or
7673 literally. All these strings specify the same calendar date:
7675 1972-09-24 # ISO 8601.
7676 72-9-24 # Assume 19xx for 69 through 99,
7677 # 20xx for 00 through 68.
7678 72-09-24 # Leading zeros are ignored.
7679 9/24/72 # Common U.S. writing.
7681 24 Sept 72 # September has a special abbreviation.
7682 24 Sep 72 # Three-letter abbreviations always allowed.
7687 The year can also be omitted. In this case, the last specified year
7688 is used, or the current year if none. For example:
7695 For numeric months, the ISO 8601 format `YEAR-MONTH-DAY' is allowed,
7696 where YEAR is any positive number, MONTH is a number between 01 and 12,
7697 and DAY is a number between 01 and 31. A leading zero must be present
7698 if a number is less than ten. If YEAR is 68 or smaller, then 2000 is
7699 added to it; otherwise, if YEAR is less than 100, then 1900 is added to
7700 it. The construct `MONTH/DAY/YEAR', popular in the United States, is
7701 accepted. Also `MONTH/DAY', omitting the year.
7703 Literal months may be spelled out in full: `January', `February',
7704 `March', `April', `May', `June', `July', `August', `September',
7705 `October', `November' or `December'. Literal months may be abbreviated
7706 to their first three letters, possibly followed by an abbreviating dot.
7707 It is also permitted to write `Sept' instead of `September'.
7709 When months are written literally, the calendar date may be given as
7710 any of the following:
7717 Or, omitting the year: