+++ /dev/null
-This is tar.info, produced by makeinfo version 4.8.90 from tar.texi.
-
- This manual is for GNU `tar' (version 1.20, 14 April 2008), which
-creates and extracts files from archives.
-
- Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003,
-2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
-
- Permission is granted to copy, distribute and/or modify this
- document under the terms of the GNU Free Documentation License,
- Version 1.1 or any later version published by the Free Software
- Foundation; with no Invariant Sections, with the Front-Cover Texts
- being "A GNU Manual," and with the Back-Cover Texts as in (a)
- below. A copy of the license is included in the section entitled
- "GNU Free Documentation License".
-
- (a) The FSF's Back-Cover Text is: "You have the freedom to copy
- and modify this GNU manual. Buying copies from the FSF supports
- it in developing GNU and promoting software freedom."
-
-INFO-DIR-SECTION Archiving
-START-INFO-DIR-ENTRY
-* Tar: (tar). Making tape (or disk) archives.
-END-INFO-DIR-ENTRY
-
-INFO-DIR-SECTION Individual utilities
-START-INFO-DIR-ENTRY
-* tar: (tar)tar invocation. Invoking GNU `tar'.
-END-INFO-DIR-ENTRY
-
-\1f
-File: tar.info, Node: Top, Next: Introduction, Up: (dir)
-
-GNU tar: an archiver tool
-*************************
-
-This manual is for GNU `tar' (version 1.20, 14 April 2008), which
-creates and extracts files from archives.
-
- Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003,
-2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
-
- Permission is granted to copy, distribute and/or modify this
- document under the terms of the GNU Free Documentation License,
- Version 1.1 or any later version published by the Free Software
- Foundation; with no Invariant Sections, with the Front-Cover Texts
- being "A GNU Manual," and with the Back-Cover Texts as in (a)
- below. A copy of the license is included in the section entitled
- "GNU Free Documentation License".
-
- (a) The FSF's Back-Cover Text is: "You have the freedom to copy
- and modify this GNU manual. Buying copies from the FSF supports
- it in developing GNU and promoting software freedom."
-
- The first part of this master menu lists the major nodes in this Info
-document. The rest of the menu lists all the lower level nodes.
-
-* Menu:
-
-* Introduction::
-* Tutorial::
-* tar invocation::
-* operations::
-* Backups::
-* Choosing::
-* Date input formats::
-* Formats::
-* Media::
-
-Appendices
-
-* Changes::
-* Configuring Help Summary::
-* Fixing Snapshot Files::
-* Tar Internals::
-* Genfile::
-* Free Software Needs Free Documentation::
-* Copying This Manual::
-* Index of Command Line Options::
-* Index::
-
- --- The Detailed Node Listing ---
-
-Introduction
-
-* Book Contents:: What this Book Contains
-* Definitions:: Some Definitions
-* What tar Does:: What `tar' Does
-* Naming tar Archives:: How `tar' Archives are Named
-* Authors:: GNU `tar' Authors
-* Reports:: Reporting bugs or suggestions
-
-Tutorial Introduction to `tar'
-
-* assumptions::
-* stylistic conventions::
-* basic tar options:: Basic `tar' Operations and Options
-* frequent operations::
-* Two Frequent Options::
-* create:: How to Create Archives
-* list:: How to List Archives
-* extract:: How to Extract Members from an Archive
-* going further::
-
-Two Frequently Used Options
-
-* file tutorial::
-* verbose tutorial::
-* help tutorial::
-
-How to Create Archives
-
-* prepare for examples::
-* Creating the archive::
-* create verbose::
-* short create::
-* create dir::
-
-How to List Archives
-
-* list dir::
-
-How to Extract Members from an Archive
-
-* extracting archives::
-* extracting files::
-* extract dir::
-* extracting untrusted archives::
-* failing commands::
-
-Invoking GNU `tar'
-
-* Synopsis::
-* using tar options::
-* Styles::
-* All Options::
-* help::
-* defaults::
-* verbose::
-* checkpoints::
-* interactive::
-
-The Three Option Styles
-
-* Long Options:: Long Option Style
-* Short Options:: Short Option Style
-* Old Options:: Old Option Style
-* Mixing:: Mixing Option Styles
-
-All `tar' Options
-
-* Operation Summary::
-* Option Summary::
-* Short Option Summary::
-
-GNU `tar' Operations
-
-* Basic tar::
-* Advanced tar::
-* create options::
-* extract options::
-* backup::
-* Applications::
-* looking ahead::
-
-Advanced GNU `tar' Operations
-
-* Operations::
-* append::
-* update::
-* concatenate::
-* delete::
-* compare::
-
-How to Add Files to Existing Archives: `--append'
-
-* appending files:: Appending Files to an Archive
-* multiple::
-
-Updating an Archive
-
-* how to update::
-
-Options Used by `--create'
-
-* override:: Overriding File Metadata.
-* Ignore Failed Read::
-
-Options Used by `--extract'
-
-* Reading:: Options to Help Read Archives
-* Writing:: Changing How `tar' Writes Files
-* Scarce:: Coping with Scarce Resources
-
-Options to Help Read Archives
-
-* read full records::
-* Ignore Zeros::
-
-Changing How `tar' Writes Files
-
-* Dealing with Old Files::
-* Overwrite Old Files::
-* Keep Old Files::
-* Keep Newer Files::
-* Unlink First::
-* Recursive Unlink::
-* Data Modification Times::
-* Setting Access Permissions::
-* Directory Modification Times and Permissions::
-* Writing to Standard Output::
-* Writing to an External Program::
-* remove files::
-
-Coping with Scarce Resources
-
-* Starting File::
-* Same Order::
-
-Performing Backups and Restoring Files
-
-* Full Dumps:: Using `tar' to Perform Full Dumps
-* Incremental Dumps:: Using `tar' to Perform Incremental Dumps
-* Backup Levels:: Levels of Backups
-* Backup Parameters:: Setting Parameters for Backups and Restoration
-* Scripted Backups:: Using the Backup Scripts
-* Scripted Restoration:: Using the Restore Script
-
-Setting Parameters for Backups and Restoration
-
-* General-Purpose Variables::
-* Magnetic Tape Control::
-* User Hooks::
-* backup-specs example:: An Example Text of `Backup-specs'
-
-Choosing Files and Names for `tar'
-
-* file:: Choosing the Archive's Name
-* Selecting Archive Members::
-* files:: Reading Names from a File
-* exclude:: Excluding Some Files
-* wildcards:: Wildcards Patterns and Matching
-* quoting styles:: Ways of Quoting Special Characters in Names
-* transform:: Modifying File and Member Names
-* after:: Operating Only on New Files
-* recurse:: Descending into Directories
-* one:: Crossing File System Boundaries
-
-Reading Names from a File
-
-* nul::
-
-Excluding Some Files
-
-* problems with exclude::
-
-Wildcards Patterns and Matching
-
-* controlling pattern-matching::
-
-Crossing File System Boundaries
-
-* directory:: Changing Directory
-* absolute:: Absolute File Names
-
-Date input formats
-
-* General date syntax:: Common rules.
-* Calendar date items:: 19 Dec 1994.
-* Time of day items:: 9:20pm.
-* Time zone items:: EST, PDT, GMT.
-* Day of week items:: Monday and others.
-* Relative items in date strings:: next tuesday, 2 years ago.
-* Pure numbers in date strings:: 19931219, 1440.
-* Seconds since the Epoch:: @1078100502.
-* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
-* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
-
-Controlling the Archive Format
-
-* Compression:: Using Less Space through Compression
-* Attributes:: Handling File Attributes
-* Portability:: Making `tar' Archives More Portable
-* cpio:: Comparison of `tar' and `cpio'
-
-Using Less Space through Compression
-
-* gzip:: Creating and Reading Compressed Archives
-* sparse:: Archiving Sparse Files
-
-Making `tar' Archives More Portable
-
-* Portable Names:: Portable Names
-* dereference:: Symbolic Links
-* hard links:: Hard Links
-* old:: Old V7 Archives
-* ustar:: Ustar Archives
-* gnu:: GNU and old GNU format archives.
-* posix:: POSIX archives
-* Checksumming:: Checksumming Problems
-* Large or Negative Values:: Large files, negative time stamps, etc.
-* Other Tars:: How to Extract GNU-Specific Data Using
- Other `tar' Implementations
-
-GNU `tar' and POSIX `tar'
-
-* PAX keywords:: Controlling Extended Header Keywords.
-
-How to Extract GNU-Specific Data Using Other `tar' Implementations
-
-* Split Recovery:: Members Split Between Volumes
-* Sparse Recovery:: Sparse Members
-
-Tapes and Other Archive Media
-
-* Device:: Device selection and switching
-* Remote Tape Server::
-* Common Problems and Solutions::
-* Blocking:: Blocking
-* Many:: Many archives on one tape
-* Using Multiple Tapes:: Using Multiple Tapes
-* label:: Including a Label in the Archive
-* verify::
-* Write Protection::
-
-Blocking
-
-* Format Variations:: Format Variations
-* Blocking Factor:: The Blocking Factor of an Archive
-
-Many Archives on One Tape
-
-* Tape Positioning:: Tape Positions and Tape Marks
-* mt:: The `mt' Utility
-
-Using Multiple Tapes
-
-* Multi-Volume Archives:: Archives Longer than One Tape or Disk
-* Tape Files:: Tape Files
-* Tarcat:: Concatenate Volumes into a Single Archive
-
-
-Tar Internals
-
-* Standard:: Basic Tar Format
-* Extensions:: GNU Extensions to the Archive Format
-* Sparse Formats:: Storing Sparse Files
-* Snapshot Files::
-* Dumpdir::
-
-Storing Sparse Files
-
-* Old GNU Format::
-* PAX 0:: PAX Format, Versions 0.0 and 0.1
-* PAX 1:: PAX Format, Version 1.0
-
-Genfile
-
-* Generate Mode:: File Generation Mode.
-* Status Mode:: File Status Mode.
-* Exec Mode:: Synchronous Execution mode.
-
-Copying This Manual
-
-* GNU Free Documentation License:: License for copying this manual
-
-\1f
-File: tar.info, Node: Introduction, Next: Tutorial, Prev: Top, Up: Top
-
-1 Introduction
-**************
-
-GNU `tar' creates and manipulates "archives" which are actually
-collections of many other files; the program provides users with an
-organized and systematic method for controlling a large amount of data.
-The name "tar" originally came from the phrase "Tape ARchive", but
-archives need not (and these days, typically do not) reside on tapes.
-
-* Menu:
-
-* Book Contents:: What this Book Contains
-* Definitions:: Some Definitions
-* What tar Does:: What `tar' Does
-* Naming tar Archives:: How `tar' Archives are Named
-* Authors:: GNU `tar' Authors
-* Reports:: Reporting bugs or suggestions
-
-\1f
-File: tar.info, Node: Book Contents, Next: Definitions, Up: Introduction
-
-1.1 What this Book Contains
-===========================
-
-The first part of this chapter introduces you to various terms that will
-recur throughout the book. It also tells you who has worked on GNU
-`tar' and its documentation, and where you should send bug reports or
-comments.
-
- The second chapter is a tutorial (*note Tutorial::) which provides a
-gentle introduction for people who are new to using `tar'. It is meant
-to be self contained, not requiring any reading from subsequent
-chapters to make sense. It moves from topic to topic in a logical,
-progressive order, building on information already explained.
-
- Although the tutorial is paced and structured to allow beginners to
-learn how to use `tar', it is not intended solely for beginners. The
-tutorial explains how to use the three most frequently used operations
-(`create', `list', and `extract') as well as two frequently used
-options (`file' and `verbose'). The other chapters do not refer to the
-tutorial frequently; however, if a section discusses something which is
-a complex variant of a basic concept, there may be a cross reference to
-that basic concept. (The entire book, including the tutorial, assumes
-that the reader understands some basic concepts of using a Unix-type
-operating system; *note Tutorial::.)
-
- The third chapter presents the remaining five operations, and
-information about using `tar' options and option syntax.
-
- The other chapters are meant to be used as a reference. Each chapter
-presents everything that needs to be said about a specific topic.
-
- One of the chapters (*note Date input formats::) exists in its
-entirety in other GNU manuals, and is mostly self-contained. In
-addition, one section of this manual (*note Standard::) contains a big
-quote which is taken directly from `tar' sources.
-
- In general, we give both long and short (abbreviated) option names
-at least once in each section where the relevant option is covered, so
-that novice readers will become familiar with both styles. (A few
-options have no short versions, and the relevant sections will indicate
-this.)
-
-\1f
-File: tar.info, Node: Definitions, Next: What tar Does, Prev: Book Contents, Up: Introduction
-
-1.2 Some Definitions
-====================
-
-The `tar' program is used to create and manipulate `tar' archives. An
-"archive" is a single file which contains the contents of many files,
-while still identifying the names of the files, their owner(s), and so
-forth. (In addition, archives record access permissions, user and
-group, size in bytes, and data modification time. Some archives also
-record the file names in each archived directory, as well as other file
-and directory information.) You can use `tar' to "create" a new
-archive in a specified directory.
-
- The files inside an archive are called "members". Within this
-manual, we use the term "file" to refer only to files accessible in the
-normal ways (by `ls', `cat', and so forth), and the term "member" to
-refer only to the members of an archive. Similarly, a "file name" is
-the name of a file, as it resides in the file system, and a "member
-name" is the name of an archive member within the archive.
-
- The term "extraction" refers to the process of copying an archive
-member (or multiple members) into a file in the file system. Extracting
-all the members of an archive is often called "extracting the archive".
-The term "unpack" can also be used to refer to the extraction of many
-or all the members of an archive. Extracting an archive does not
-destroy the archive's structure, just as creating an archive does not
-destroy the copies of the files that exist outside of the archive. You
-may also "list" the members in a given archive (this is often thought
-of as "printing" them to the standard output, or the command line), or
-"append" members to a pre-existing archive. All of these operations
-can be performed using `tar'.
-
-\1f
-File: tar.info, Node: What tar Does, Next: Naming tar Archives, Prev: Definitions, Up: Introduction
-
-1.3 What `tar' Does
-===================
-
-The `tar' program provides the ability to create `tar' archives, as
-well as various other kinds of manipulation. For example, you can use
-`tar' on previously created archives to extract files, to store
-additional files, or to update or list files which were already stored.
-
- Initially, `tar' archives were used to store files conveniently on
-magnetic tape. The name `tar' comes from this use; it stands for
-`t'ape `ar'chiver. Despite the utility's name, `tar' can direct its
-output to available devices, files, or other programs (using pipes).
-`tar' may even access remote devices or files (as archives).
-
- You can use `tar' archives in many ways. We want to stress a few of
-them: storage, backup, and transportation.
-
-Storage
- Often, `tar' archives are used to store related files for
- convenient file transfer over a network. For example, the GNU
- Project distributes its software bundled into `tar' archives, so
- that all the files relating to a particular program (or set of
- related programs) can be transferred as a single unit.
-
- A magnetic tape can store several files in sequence. However, the
- tape has no names for these files; it only knows their relative
- position on the tape. One way to store several files on one tape
- and retain their names is by creating a `tar' archive. Even when
- the basic transfer mechanism can keep track of names, as FTP can,
- the nuisance of handling multiple files, directories, and multiple
- links makes `tar' archives useful.
-
- Archive files are also used for long-term storage. You can think
- of this as transportation from the present into the future. (It
- is a science-fiction idiom that you can move through time as well
- as in space; the idea here is that `tar' can be used to move
- archives in all dimensions, even time!)
-
-Backup
- Because the archive created by `tar' is capable of preserving file
- information and directory structure, `tar' is commonly used for
- performing full and incremental backups of disks. A backup puts a
- collection of files (possibly pertaining to many users and
- projects) together on a disk or a tape. This guards against
- accidental destruction of the information in those files. GNU
- `tar' has special features that allow it to be used to make
- incremental and full dumps of all the files in a file system.
-
-Transportation
- You can create an archive on one system, transfer it to another
- system, and extract the contents there. This allows you to
- transport a group of files from one system to another.
-
-\1f
-File: tar.info, Node: Naming tar Archives, Next: Authors, Prev: What tar Does, Up: Introduction
-
-1.4 How `tar' Archives are Named
-================================
-
-Conventionally, `tar' archives are given names ending with `.tar'.
-This is not necessary for `tar' to operate properly, but this manual
-follows that convention in order to accustom readers to it and to make
-examples more clear.
-
- Often, people refer to `tar' archives as "`tar' files," and archive
-members as "files" or "entries". For people familiar with the
-operation of `tar', this causes no difficulty. However, in this
-manual, we consistently refer to "archives" and "archive members" to
-make learning to use `tar' easier for novice users.
-
-\1f
-File: tar.info, Node: Authors, Next: Reports, Prev: Naming tar Archives, Up: Introduction
-
-1.5 GNU `tar' Authors
-=====================
-
-GNU `tar' was originally written by John Gilmore, and modified by many
-people. The GNU enhancements were written by Jay Fenlason, then Joy
-Kendall, and the whole package has been further maintained by Thomas
-Bushnell, n/BSG, Franc,ois Pinard, Paul Eggert, and finally Sergey
-Poznyakoff with the help of numerous and kind users.
-
- We wish to stress that `tar' is a collective work, and owes much to
-all those people who reported problems, offered solutions and other
-insights, or shared their thoughts and suggestions. An impressive, yet
-partial list of those contributors can be found in the `THANKS' file
-from the GNU `tar' distribution.
-
- Jay Fenlason put together a draft of a GNU `tar' manual, borrowing
-notes from the original man page from John Gilmore. This was withdrawn
-in version 1.11. Thomas Bushnell, n/BSG and Amy Gorin worked on a
-tutorial and manual for GNU `tar'. Franc,ois Pinard put version 1.11.8
-of the manual together by taking information from all these sources and
-merging them. Melissa Weisshaus finally edited and redesigned the book
-to create version 1.12. The book for versions from 1.14 up to 1.20
-were edited by the current maintainer, Sergey Poznyakoff.
-
- For version 1.12, Daniel Hagerty contributed a great deal of
-technical consulting. In particular, he is the primary author of *note
-Backups::.
-
- In July, 2003 GNU `tar' was put on CVS at savannah.gnu.org (see
-`http://savannah.gnu.org/projects/tar'), and active development and
-maintenance work has started again. Currently GNU `tar' is being
-maintained by Paul Eggert, Sergey Poznyakoff and Jeff Bailey.
-
- Support for POSIX archives was added by Sergey Poznyakoff.
-
-\1f
-File: tar.info, Node: Reports, Prev: Authors, Up: Introduction
-
-1.6 Reporting bugs or suggestions
-=================================
-
-If you find problems or have suggestions about this program or manual,
-please report them to `bug-tar@gnu.org'.
-
- When reporting a bug, please be sure to include as much detail as
-possible, in order to reproduce it. .
-
-\1f
-File: tar.info, Node: Tutorial, Next: tar invocation, Prev: Introduction, Up: Top
-
-2 Tutorial Introduction to `tar'
-********************************
-
-This chapter guides you through some basic examples of three `tar'
-operations: `--create', `--list', and `--extract'. If you already know
-how to use some other version of `tar', then you may not need to read
-this chapter. This chapter omits most complicated details about how
-`tar' works.
-
-* Menu:
-
-* assumptions::
-* stylistic conventions::
-* basic tar options:: Basic `tar' Operations and Options
-* frequent operations::
-* Two Frequent Options::
-* create:: How to Create Archives
-* list:: How to List Archives
-* extract:: How to Extract Members from an Archive
-* going further::
-
-\1f
-File: tar.info, Node: assumptions, Next: stylistic conventions, Up: Tutorial
-
-2.1 Assumptions this Tutorial Makes
-===================================
-
-This chapter is paced to allow beginners to learn about `tar' slowly.
-At the same time, we will try to cover all the basic aspects of these
-three operations. In order to accomplish both of these tasks, we have
-made certain assumptions about your knowledge before reading this
-manual, and the hardware you will be using:
-
- * Before you start to work through this tutorial, you should
- understand what the terms "archive" and "archive member" mean
- (*note Definitions::). In addition, you should understand
- something about how Unix-type operating systems work, and you
- should know how to use some basic utilities. For example, you
- should know how to create, list, copy, rename, edit, and delete
- files and directories; how to change between directories; and how
- to figure out where you are in the file system. You should have
- some basic understanding of directory structure and how files are
- named according to which directory they are in. You should
- understand concepts such as standard output and standard input,
- what various definitions of the term `argument' mean, and the
- differences between relative and absolute file names.
-
- * This manual assumes that you are working from your own home
- directory (unless we state otherwise). In this tutorial, you will
- create a directory to practice `tar' commands in. When we show
- file names, we will assume that those names are relative to your
- home directory. For example, my home directory is
- `/home/fsf/melissa'. All of my examples are in a subdirectory of
- the directory named by that file name; the subdirectory is called
- `practice'.
-
- * In general, we show examples of archives which exist on (or can be
- written to, or worked with from) a directory on a hard disk. In
- most cases, you could write those archives to, or work with them
- on any other device, such as a tape drive. However, some of the
- later examples in the tutorial and next chapter will not work on
- tape drives. Additionally, working with tapes is much more
- complicated than working with hard disks. For these reasons, the
- tutorial does not cover working with tape drives. *Note Media::,
- for complete information on using `tar' archives with tape drives.
-
-
-\1f
-File: tar.info, Node: stylistic conventions, Next: basic tar options, Prev: assumptions, Up: Tutorial
-
-2.2 Stylistic Conventions
-=========================
-
-In the examples, `$' represents a typical shell prompt. It precedes
-lines you should type; to make this more clear, those lines are shown
-in `this font', as opposed to lines which represent the computer's
-response; those lines are shown in `this font', or sometimes `like
-this'.
-
-\1f
-File: tar.info, Node: basic tar options, Next: frequent operations, Prev: stylistic conventions, Up: Tutorial
-
-2.3 Basic `tar' Operations and Options
-======================================
-
-`tar' can take a wide variety of arguments which specify and define the
-actions it will have on the particular set of files or the archive.
-The main types of arguments to `tar' fall into one of two classes:
-operations, and options.
-
- Some arguments fall into a class called "operations"; exactly one of
-these is both allowed and required for any instance of using `tar'; you
-may _not_ specify more than one. People sometimes speak of "operating
-modes". You are in a particular operating mode when you have specified
-the operation which specifies it; there are eight operations in total,
-and thus there are eight operating modes.
-
- The other arguments fall into the class known as "options". You are
-not required to specify any options, and you are allowed to specify more
-than one at a time (depending on the way you are using `tar' at that
-time). Some options are used so frequently, and are so useful for
-helping you type commands more carefully that they are effectively
-"required". We will discuss them in this chapter.
-
- You can write most of the `tar' operations and options in any of
-three forms: long (mnemonic) form, short form, and old style. Some of
-the operations and options have no short or "old" forms; however, the
-operations and options which we will cover in this tutorial have
-corresponding abbreviations. We will indicate those abbreviations
-appropriately to get you used to seeing them. (Note that the "old
-style" option forms exist in GNU `tar' for compatibility with Unix
-`tar'. In this book we present a full discussion of this way of
-writing options and operations (*note Old Options::), and we discuss
-the other two styles of writing options (*Note Long Options::, and
-*note Short Options::).
-
- In the examples and in the text of this tutorial, we usually use the
-long forms of operations and options; but the "short" forms produce the
-same result and can make typing long `tar' commands easier. For
-example, instead of typing
-
- tar --create --verbose --file=afiles.tar apple angst aspic
-
-you can type
- tar -c -v -f afiles.tar apple angst aspic
-
-or even
- tar -cvf afiles.tar apple angst aspic
-
-For more information on option syntax, see *note Advanced tar::. In
-discussions in the text, when we name an option by its long form, we
-also give the corresponding short option in parentheses.
-
- The term, "option", can be confusing at times, since "operations"
-are often lumped in with the actual, _optional_ "options" in certain
-general class statements. For example, we just talked about "short and
-long forms of options and operations". However, experienced `tar'
-users often refer to these by shorthand terms such as, "short and long
-options". This term assumes that the "operations" are included, also.
-Context will help you determine which definition of "options" to use.
-
- Similarly, the term "command" can be confusing, as it is often used
-in two different ways. People sometimes refer to `tar' "commands". A
-`tar' "command" is the entire command line of user input which tells
-`tar' what to do -- including the operation, options, and any arguments
-(file names, pipes, other commands, etc.). However, you will also
-sometimes hear the term "the `tar' command". When the word "command"
-is used specifically like this, a person is usually referring to the
-`tar' _operation_, not the whole line. Again, use context to figure
-out which of the meanings the speaker intends.
-
-\1f
-File: tar.info, Node: frequent operations, Next: Two Frequent Options, Prev: basic tar options, Up: Tutorial
-
-2.4 The Three Most Frequently Used Operations
-=============================================
-
-Here are the three most frequently used operations (both short and long
-forms), as well as a brief description of their meanings. The rest of
-this chapter will cover how to use these operations in detail. We will
-present the rest of the operations in the next chapter.
-
-`--create'
-`-c'
- Create a new `tar' archive.
-
-`--list'
-`-t'
- List the contents of an archive.
-
-`--extract'
-`-x'
- Extract one or more members from an archive.
-
-\1f
-File: tar.info, Node: Two Frequent Options, Next: create, Prev: frequent operations, Up: Tutorial
-
-2.5 Two Frequently Used Options
-===============================
-
-To understand how to run `tar' in the three operating modes listed
-previously, you also need to understand how to use two of the options to
-`tar': `--file' (which takes an archive file as an argument) and
-`--verbose'. (You are usually not _required_ to specify either of
-these options when you run `tar', but they can be very useful in making
-things more clear and helping you avoid errors.)
-
-* Menu:
-
-* file tutorial::
-* verbose tutorial::
-* help tutorial::
-
-\1f
-File: tar.info, Node: file tutorial, Next: verbose tutorial, Up: Two Frequent Options
-
-The `--file' Option
--------------------
-
-`--file=ARCHIVE-NAME'
-`-f ARCHIVE-NAME'
- Specify the name of an archive file.
-
- You can specify an argument for the `--file=ARCHIVE-NAME' (`-f
-ARCHIVE-NAME') option whenever you use `tar'; this option determines
-the name of the archive file that `tar' will work on.
-
- If you don't specify this argument, then `tar' will examine the
-environment variable `TAPE'. If it is set, its value will be used as
-the archive name. Otherwise, `tar' will use the default archive,
-determined at the compile time. Usually it is standard output or some
-physical tape drive attached to your machine (you can verify what the
-default is by running `tar --show-defaults', *note defaults::). If
-there is no tape drive attached, or the default is not meaningful, then
-`tar' will print an error message. The error message might look
-roughly like one of the following:
-
- tar: can't open /dev/rmt8 : No such device or address
- tar: can't open /dev/rsmt0 : I/O error
-
-To avoid confusion, we recommend that you always specify an archive file
-name by using `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') when writing
-your `tar' commands. For more information on using the
-`--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option, see *note file::.
-
-\1f
-File: tar.info, Node: verbose tutorial, Next: help tutorial, Prev: file tutorial, Up: Two Frequent Options
-
-The `--verbose' Option
-----------------------
-
-`--verbose'
-`-v'
- Show the files being worked on as `tar' is running.
-
- `--verbose' (`-v') shows details about the results of running `tar'.
-This can be especially useful when the results might not be obvious.
-For example, if you want to see the progress of `tar' as it writes
-files into the archive, you can use the `--verbose' option. In the
-beginning, you may find it useful to use `--verbose' at all times; when
-you are more accustomed to `tar', you will likely want to use it at
-certain times but not at others. We will use `--verbose' at times to
-help make something clear, and we will give many examples both using
-and not using `--verbose' to show the differences.
-
- Each instance of `--verbose' on the command line increases the
-verbosity level by one, so if you need more details on the output,
-specify it twice.
-
- When reading archives (`--list', `--extract', `--diff'), `tar' by
-default prints only the names of the members being extracted. Using
-`--verbose' will show a full, `ls' style member listing.
-
- In contrast, when writing archives (`--create', `--append',
-`--update'), `tar' does not print file names by default. So, a single
-`--verbose' option shows the file names being added to the archive,
-while two `--verbose' options enable the full listing.
-
- For example, to create an archive in verbose mode:
-
- $ tar -cvf afiles.tar apple angst aspic
- apple
- angst
- aspic
-
-Creating the same archive with the verbosity level 2 could give:
-
- $ tar -cvvf afiles.tar apple angst aspic
- -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
- -rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst
- -rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic
-
-This works equally well using short or long forms of options. Using
-long forms, you would simply write out the mnemonic form of the option
-twice, like this:
-
- $ tar --create --verbose --verbose ...
-
-Note that you must double the hyphens properly each time.
-
- Later in the tutorial, we will give examples using
-`--verbose --verbose'.
-
- The full output consists of six fields:
-
- * File type and permissions in symbolic form. These are displayed
- in the same format as the first column of `ls -l' output (*note
- format=verbose: (fileutils)What information is listed.).
-
- * Owner name and group separated by a slash character. If these
- data are not available (for example, when listing a `v7' format
- archive), numeric ID values are printed instead.
-
- * Size of the file, in bytes.
-
- * File modification date in ISO 8601 format.
-
- * File modification time.
-
- * File name. If the name contains any special characters (white
- space, newlines, etc.) these are displayed in an unambiguous form
- using so called "quoting style". For the detailed discussion of
- available styles and on how to use them, see *note quoting
- styles::.
-
- Depending on the file type, the name can be followed by some
- additional information, described in the following table:
-
- `-> LINK-NAME'
- The file or archive member is a "symbolic link" and LINK-NAME
- is the name of file it links to.
-
- `link to LINK-NAME'
- The file or archive member is a "hard link" and LINK-NAME is
- the name of file it links to.
-
- `--Long Link--'
- The archive member is an old GNU format long link. You will
- normally not encounter this.
-
- `--Long Name--'
- The archive member is an old GNU format long name. You will
- normally not encounter this.
-
- `--Volume Header--'
- The archive member is a GNU "volume header" (*note Tape
- Files::).
-
- `--Continued at byte N--'
- Encountered only at the beginning of a multi-volume archive
- (*note Using Multiple Tapes::). This archive member is a
- continuation from the previous volume. The number N gives the
- offset where the original file was split.
-
- `unknown file type C'
- An archive member of unknown type. C is the type character
- from the archive header. If you encounter such a message, it
- means that either your archive contains proprietary member
- types GNU `tar' is not able to handle, or the archive is
- corrupted.
-
-
- For example, here is an archive listing containing most of the
-special suffixes explained above:
-
- V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header--
- -rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at
- byte 32456--
- -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
- lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple
- -rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
- hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues
-
-
-\1f
-File: tar.info, Node: help tutorial, Prev: verbose tutorial, Up: Two Frequent Options
-
-Getting Help: Using the `--help' Option
----------------------------------------
-
-`--help'
- The `--help' option to `tar' prints out a very brief list of all
- operations and option available for the current version of `tar'
- available on your system.
-
-\1f
-File: tar.info, Node: create, Next: list, Prev: Two Frequent Options, Up: Tutorial
-
-2.6 How to Create Archives
-==========================
-
- _(This message will disappear, once this node revised.)_
-
-One of the basic operations of `tar' is `--create' (`-c'), which you
-use to create a `tar' archive. We will explain `--create' first
-because, in order to learn about the other operations, you will find it
-useful to have an archive available to practice on.
-
- To make this easier, in this section you will first create a
-directory containing three files. Then, we will show you how to create
-an _archive_ (inside the new directory). Both the directory, and the
-archive are specifically for you to practice on. The rest of this
-chapter and the next chapter will show many examples using this
-directory and the files you will create: some of those files may be
-other directories and other archives.
-
- The three files you will archive in this example are called `blues',
-`folk', and `jazz'. The archive is called `collection.tar'.
-
- This section will proceed slowly, detailing how to use `--create' in
-`verbose' mode, and showing examples using both short and long forms.
-In the rest of the tutorial, and in the examples in the next chapter,
-we will proceed at a slightly quicker pace. This section moves more
-slowly to allow beginning users to understand how `tar' works.
-
-* Menu:
-
-* prepare for examples::
-* Creating the archive::
-* create verbose::
-* short create::
-* create dir::
-
-\1f
-File: tar.info, Node: prepare for examples, Next: Creating the archive, Up: create
-
-2.6.1 Preparing a Practice Directory for Examples
--------------------------------------------------
-
-To follow along with this and future examples, create a new directory
-called `practice' containing files called `blues', `folk' and `jazz'.
-The files can contain any information you like: ideally, they should
-contain information which relates to their names, and be of different
-lengths. Our examples assume that `practice' is a subdirectory of your
-home directory.
-
- Now `cd' to the directory named `practice'; `practice' is now your
-"working directory". (_Please note_: Although the full file name of
-this directory is `/HOMEDIR/practice', in our examples we will refer to
-this directory as `practice'; the HOMEDIR is presumed.
-
- In general, you should check that the files to be archived exist
-where you think they do (in the working directory) by running `ls'.
-Because you just created the directory and the files and have changed to
-that directory, you probably don't need to do that this time.
-
- It is very important to make sure there isn't already a file in the
-working directory with the archive name you intend to use (in this case,
-`collection.tar'), or that you don't care about its contents. Whenever
-you use `create', `tar' will erase the current contents of the file
-named by `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') if it exists. `tar'
-will not tell you if you are about to overwrite an archive unless you
-specify an option which does this (*note backup::, for the information
-on how to do so). To add files to an existing archive, you need to use
-a different option, such as `--append' (`-r'); see *note append:: for
-information on how to do this.
-
-\1f
-File: tar.info, Node: Creating the archive, Next: create verbose, Prev: prepare for examples, Up: create
-
-2.6.2 Creating the Archive
---------------------------
-
-To place the files `blues', `folk', and `jazz' into an archive named
-`collection.tar', use the following command:
-
- $ tar --create --file=collection.tar blues folk jazz
-
- The order of the arguments is not very important, _when using long
-option forms_. You could also say:
-
- $ tar blues --create folk --file=collection.tar jazz
-
-However, you can see that this order is harder to understand; this is
-why we will list the arguments in the order that makes the commands
-easiest to understand (and we encourage you to do the same when you use
-`tar', to avoid errors).
-
- Note that the sequence `--file=collection.tar' is considered to be
-_one_ argument. If you substituted any other string of characters for
-`collection.tar', then that string would become the name of the
-archive file you create.
-
- The order of the options becomes more important when you begin to use
-short forms. With short forms, if you type commands in the wrong order
-(even if you type them correctly in all other ways), you may end up with
-results you don't expect. For this reason, it is a good idea to get
-into the habit of typing options in the order that makes inherent sense.
-*Note short create::, for more information on this.
-
- In this example, you type the command as shown above: `--create' is
-the operation which creates the new archive (`collection.tar'), and
-`--file' is the option which lets you give it the name you chose. The
-files, `blues', `folk', and `jazz', are now members of the archive,
-`collection.tar' (they are "file name arguments" to the `--create'
-operation. *Note Choosing::, for the detailed discussion on these.)
-Now that they are in the archive, they are called _archive members_,
-not files. (*note members: Definitions.).
-
- When you create an archive, you _must_ specify which files you want
-placed in the archive. If you do not specify any archive members, GNU
-`tar' will complain.
-
- If you now list the contents of the working directory (`ls'), you
-will find the archive file listed as well as the files you saw
-previously:
-
- blues folk jazz collection.tar
-
-Creating the archive `collection.tar' did not destroy the copies of the
-files in the directory.
-
- Keep in mind that if you don't indicate an operation, `tar' will not
-run and will prompt you for one. If you don't name any files, `tar'
-will complain. You must have write access to the working directory, or
-else you will not be able to create an archive in that directory.
-
- _Caution_: Do not attempt to use `--create' (`-c') to add files to
-an existing archive; it will delete the archive and write a new one.
-Use `--append' (`-r') instead. *Note append::.
-
-\1f
-File: tar.info, Node: create verbose, Next: short create, Prev: Creating the archive, Up: create
-
-2.6.3 Running `--create' with `--verbose'
------------------------------------------
-
-If you include the `--verbose' (`-v') option on the command line, `tar'
-will list the files it is acting on as it is working. In verbose mode,
-the `create' example above would appear as:
-
- $ tar --create --verbose --file=collection.tar blues folk jazz
- blues
- folk
- jazz
-
- This example is just like the example we showed which did not use
-`--verbose', except that `tar' generated the remaining lines .
-
- In the rest of the examples in this chapter, we will frequently use
-`verbose' mode so we can show actions or `tar' responses that you would
-otherwise not see, and which are important for you to understand.
-
-\1f
-File: tar.info, Node: short create, Next: create dir, Prev: create verbose, Up: create
-
-2.6.4 Short Forms with `create'
--------------------------------
-
-As we said before, the `--create' (`-c') operation is one of the most
-basic uses of `tar', and you will use it countless times. Eventually,
-you will probably want to use abbreviated (or "short") forms of
-options. A full discussion of the three different forms that options
-can take appears in *note Styles::; for now, here is what the previous
-example (including the `--verbose' (`-v') option) looks like using
-short option forms:
-
- $ tar -cvf collection.tar blues folk jazz
- blues
- folk
- jazz
-
-As you can see, the system responds the same no matter whether you use
-long or short option forms.
-
- One difference between using short and long option forms is that,
-although the exact placement of arguments following options is no more
-specific when using short forms, it is easier to become confused and
-make a mistake when using short forms. For example, suppose you
-attempted the above example in the following way:
-
- $ tar -cfv collection.tar blues folk jazz
-
-In this case, `tar' will make an archive file called `v', containing
-the files `blues', `folk', and `jazz', because the `v' is the closest
-"file name" to the `-f' option, and is thus taken to be the chosen
-archive file name. `tar' will try to add a file called
-`collection.tar' to the `v' archive file; if the file `collection.tar'
-did not already exist, `tar' will report an error indicating that this
-file does not exist. If the file `collection.tar' does already exist
-(e.g., from a previous command you may have run), then `tar' will add
-this file to the archive. Because the `-v' option did not get
-registered, `tar' will not run under `verbose' mode, and will not
-report its progress.
-
- The end result is that you may be quite confused about what happened,
-and possibly overwrite a file. To illustrate this further, we will show
-you how an example we showed previously would look using short forms.
-
- This example,
-
- $ tar blues --create folk --file=collection.tar jazz
-
-is confusing as it is. When shown using short forms, however, it
-becomes much more so:
-
- $ tar blues -c folk -f collection.tar jazz
-
-It would be very easy to put the wrong string of characters immediately
-following the `-f', but doing that could sacrifice valuable data.
-
- For this reason, we recommend that you pay very careful attention to
-the order of options and placement of file and archive names,
-especially when using short option forms. Not having the option name
-written out mnemonically can affect how well you remember which option
-does what, and therefore where different names have to be placed.
-
-\1f
-File: tar.info, Node: create dir, Prev: short create, Up: create
-
-2.6.5 Archiving Directories
----------------------------
-
-You can archive a directory by specifying its directory name as a file
-name argument to `tar'. The files in the directory will be archived
-relative to the working directory, and the directory will be re-created
-along with its contents when the archive is extracted.
-
- To archive a directory, first move to its superior directory. If you
-have followed the previous instructions in this tutorial, you should
-type:
-
- $ cd ..
- $
-
-This will put you into the directory which contains `practice', i.e.,
-your home directory. Once in the superior directory, you can specify
-the subdirectory, `practice', as a file name argument. To store
-`practice' in the new archive file `music.tar', type:
-
- $ tar --create --verbose --file=music.tar practice
-
-`tar' should output:
-
- practice/
- practice/blues
- practice/folk
- practice/jazz
- practice/collection.tar
-
- Note that the archive thus created is not in the subdirectory
-`practice', but rather in the current working directory--the directory
-from which `tar' was invoked. Before trying to archive a directory
-from its superior directory, you should make sure you have write access
-to the superior directory itself, not only the directory you are trying
-archive with `tar'. For example, you will probably not be able to
-store your home directory in an archive by invoking `tar' from the root
-directory; *Note absolute::. (Note also that `collection.tar', the
-original archive file, has itself been archived. `tar' will accept any
-file as a file to be archived, regardless of its content. When
-`music.tar' is extracted, the archive file `collection.tar' will be
-re-written into the file system).
-
- If you give `tar' a command such as
-
- $ tar --create --file=foo.tar .
-
-`tar' will report `tar: ./foo.tar is the archive; not dumped'. This
-happens because `tar' creates the archive `foo.tar' in the current
-directory before putting any files into it. Then, when `tar' attempts
-to add all the files in the directory `.' to the archive, it notices
-that the file `./foo.tar' is the same as the archive `foo.tar', and
-skips it. (It makes no sense to put an archive into itself.) GNU `tar'
-will continue in this case, and create the archive normally, except for
-the exclusion of that one file. (_Please note:_ Other implementations
-of `tar' may not be so clever; they will enter an infinite loop when
-this happens, so you should not depend on this behavior unless you are
-certain you are running GNU `tar'. In general, it is wise to always
-place the archive outside of the directory being dumped.
-
-\1f
-File: tar.info, Node: list, Next: extract, Prev: create, Up: Tutorial
-
-2.7 How to List Archives
-========================
-
-Frequently, you will find yourself wanting to determine exactly what a
-particular archive contains. You can use the `--list' (`-t') operation
-to get the member names as they currently appear in the archive, as
-well as various attributes of the files at the time they were archived.
-For example, you can examine the archive `collection.tar' that you
-created in the last section with the command,
-
- $ tar --list --file=collection.tar
-
-The output of `tar' would then be:
-
- blues
- folk
- jazz
-
-The archive `bfiles.tar' would list as follows:
-
- ./birds
- baboon
- ./box
-
-Be sure to use a `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option just
-as with `--create' (`-c') to specify the name of the archive.
-
- If you use the `--verbose' (`-v') option with `--list', then `tar'
-will print out a listing reminiscent of `ls -l', showing owner, file
-size, and so forth. This output is described in detail in *note
-verbose member listing::.
-
- If you had used `--verbose' (`-v') mode, the example above would
-look like:
-
- $ tar --list --verbose --file=collection.tar folk
- -rw-r--r-- myself user 62 1990-05-23 10:55 folk
-
- It is important to notice that the output of `tar --list --verbose'
-does not necessarily match that produced by `tar --create --verbose'
-while creating the archive. It is because GNU `tar', unless told
-explicitly not to do so, removes some directory prefixes from file
-names before storing them in the archive (*Note absolute::, for more
-information). In other words, in verbose mode GNU `tar' shows "file
-names" when creating an archive and "member names" when listing it.
-Consider this example:
-
- $ tar cfv archive /etc/mail
- tar: Removing leading `/' from member names
- /etc/mail/
- /etc/mail/sendmail.cf
- /etc/mail/aliases
- $ tar tf archive
- etc/mail/
- etc/mail/sendmail.cf
- etc/mail/aliases
-
- This default behavior can sometimes be inconvenient. You can force
-GNU `tar' show member names when creating archive by supplying
-`--show-stored-names' option.
-
-`--show-stored-names'
- Print member (as opposed to _file_) names when creating the
- archive.
-
- You can specify one or more individual member names as arguments when
-using `list'. In this case, `tar' will only list the names of members
-you identify. For example, `tar --list --file=afiles.tar apple' would
-only print `apple'.
-
- Because `tar' preserves file names, these must be specified as they
-appear in the archive (i.e., relative to the directory from which the
-archive was created). Therefore, it is essential when specifying
-member names to `tar' that you give the exact member names. For
-example, `tar --list --file=bfiles.tar birds' would produce an error
-message something like `tar: birds: Not found in archive', because
-there is no member named `birds', only one named `./birds'. While the
-names `birds' and `./birds' name the same file, _member_ names by
-default are compared verbatim.
-
- However, `tar --list --file=bfiles.tar baboon' would respond with
-`baboon', because this exact member name is in the archive file
-`bfiles.tar'. If you are not sure of the exact file name, use
-"globbing patterns", for example:
-
- $ tar --list --file=bfiles.tar --wildcards '*b*'
-
-will list all members whose name contains `b'. *Note wildcards::, for
-a detailed discussion of globbing patterns and related `tar' command
-line options.
-
-* Menu:
-
-* list dir::
-
-\1f
-File: tar.info, Node: list dir, Up: list
-
-Listing the Contents of a Stored Directory
-------------------------------------------
-
-To get information about the contents of an archived directory, use the
-directory name as a file name argument in conjunction with `--list'
-(`-t'). To find out file attributes, include the `--verbose' (`-v')
-option.
-
- For example, to find out about files in the directory `practice', in
-the archive file `music.tar', type:
-
- $ tar --list --verbose --file=music.tar practice
-
- `tar' responds:
-
- drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
- -rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues
- -rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk
- -rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz
- -rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar
-
- When you use a directory name as a file name argument, `tar' acts on
-all the files (including sub-directories) in that directory.
-
-\1f
-File: tar.info, Node: extract, Next: going further, Prev: list, Up: Tutorial
-
-2.8 How to Extract Members from an Archive
-==========================================
-
- _(This message will disappear, once this node revised.)_
-
-Creating an archive is only half the job--there is no point in storing
-files in an archive if you can't retrieve them. The act of retrieving
-members from an archive so they can be used and manipulated as
-unarchived files again is called "extraction". To extract files from
-an archive, use the `--extract' (`--get' or `-x') operation. As with
-`--create', specify the name of the archive with `--file' (`-f')
-option. Extracting an archive does not modify the archive in any way;
-you can extract it multiple times if you want or need to.
-
- Using `--extract', you can extract an entire archive, or specific
-files. The files can be directories containing other files, or not. As
-with `--create' (`-c') and `--list' (`-t'), you may use the short or the
-long form of the operation without affecting the performance.
-
-* Menu:
-
-* extracting archives::
-* extracting files::
-* extract dir::
-* extracting untrusted archives::
-* failing commands::
-
-\1f
-File: tar.info, Node: extracting archives, Next: extracting files, Up: extract
-
-2.8.1 Extracting an Entire Archive
-----------------------------------
-
-To extract an entire archive, specify the archive file name only, with
-no individual file names as arguments. For example,
-
- $ tar -xvf collection.tar
-
-produces this:
-
- -rw-r--r-- me user 28 1996-10-18 16:31 jazz
- -rw-r--r-- me user 21 1996-09-23 16:44 blues
- -rw-r--r-- me user 20 1996-09-23 16:44 folk
-
-\1f
-File: tar.info, Node: extracting files, Next: extract dir, Prev: extracting archives, Up: extract
-
-2.8.2 Extracting Specific Files
--------------------------------
-
-To extract specific archive members, give their exact member names as
-arguments, as printed by `--list' (`-t'). If you had mistakenly
-deleted one of the files you had placed in the archive `collection.tar'
-earlier (say, `blues'), you can extract it from the archive without
-changing the archive's structure. Its contents will be identical to
-the original file `blues' that you deleted.
-
- First, make sure you are in the `practice' directory, and list the
-files in the directory. Now, delete the file, `blues', and list the
-files in the directory again.
-
- You can now extract the member `blues' from the archive file
-`collection.tar' like this:
-
- $ tar --extract --file=collection.tar blues
-
-If you list the files in the directory again, you will see that the file
-`blues' has been restored, with its original permissions, data
-modification times, and owner.(1) (These parameters will be identical
-to those which the file had when you originally placed it in the
-archive; any changes you may have made before deleting the file from
-the file system, however, will _not_ have been made to the archive
-member.) The archive file, `collection.tar', is the same as it was
-before you extracted `blues'. You can confirm this by running `tar'
-with `--list' (`-t').
-
- Remember that as with other operations, specifying the exact member
-name is important. `tar --extract --file=bfiles.tar birds' will fail,
-because there is no member named `birds'. To extract the member named
-`./birds', you must specify `tar --extract --file=bfiles.tar ./birds'.
-If you don't remember the exact member names, use `--list' (`-t') option
-(*note list::). You can also extract those members that match a
-specific "globbing pattern". For example, to extract from `bfiles.tar'
-all files that begin with `b', no matter their directory prefix, you
-could type:
-
- $ tar -x -f bfiles.tar --wildcards --no-anchored 'b*'
-
-Here, `--wildcards' instructs `tar' to treat command line arguments as
-globbing patterns and `--no-anchored' informs it that the patterns
-apply to member names after any `/' delimiter. The use of globbing
-patterns is discussed in detail in *Note wildcards::.
-
- You can extract a file to standard output by combining the above
-options with the `--to-stdout' (`-O') option (*note Writing to Standard
-Output::).
-
- If you give the `--verbose' option, then `--extract' will print the
-names of the archive members as it extracts them.
-
- ---------- Footnotes ----------
-
- (1) This is only accidentally true, but not in general. Whereas
-modification times are always restored, in most cases, one has to be
-root for restoring the owner, and use a special option for restoring
-permissions. Here, it just happens that the restoring user is also the
-owner of the archived members, and that the current `umask' is
-compatible with original permissions.
-
-\1f
-File: tar.info, Node: extract dir, Next: extracting untrusted archives, Prev: extracting files, Up: extract
-
-2.8.3 Extracting Files that are Directories
--------------------------------------------
-
-Extracting directories which are members of an archive is similar to
-extracting other files. The main difference to be aware of is that if
-the extracted directory has the same name as any directory already in
-the working directory, then files in the extracted directory will be
-placed into the directory of the same name. Likewise, if there are
-files in the pre-existing directory with the same names as the members
-which you extract, the files from the extracted archive will replace
-the files already in the working directory (and possible
-subdirectories). This will happen regardless of whether or not the
-files in the working directory were more recent than those extracted
-(there exist, however, special options that alter this behavior *note
-Writing::).
-
- However, if a file was stored with a directory name as part of its
-file name, and that directory does not exist under the working
-directory when the file is extracted, `tar' will create the directory.
-
- We can demonstrate how to use `--extract' to extract a directory
-file with an example. Change to the `practice' directory if you
-weren't there, and remove the files `folk' and `jazz'. Then, go back
-to the parent directory and extract the archive `music.tar'. You may
-either extract the entire archive, or you may extract only the files
-you just deleted. To extract the entire archive, don't give any file
-names as arguments after the archive name `music.tar'. To extract only
-the files you deleted, use the following command:
-
- $ tar -xvf music.tar practice/folk practice/jazz
- practice/folk
- practice/jazz
-
-If you were to specify two `--verbose' (`-v') options, `tar' would have
-displayed more detail about the extracted files, as shown in the
-example below:
-
- $ tar -xvvf music.tar practice/folk practice/jazz
- -rw-r--r-- me user 28 1996-10-18 16:31 practice/jazz
- -rw-r--r-- me user 20 1996-09-23 16:44 practice/folk
-
-Because you created the directory with `practice' as part of the file
-names of each of the files by archiving the `practice' directory as
-`practice', you must give `practice' as part of the file names when you
-extract those files from the archive.
-
-\1f
-File: tar.info, Node: extracting untrusted archives, Next: failing commands, Prev: extract dir, Up: extract
-
-2.8.4 Extracting Archives from Untrusted Sources
-------------------------------------------------
-
-Extracting files from archives can overwrite files that already exist.
-If you receive an archive from an untrusted source, you should make a
-new directory and extract into that directory, so that you don't have
-to worry about the extraction overwriting one of your existing files.
-For example, if `untrusted.tar' came from somewhere else on the
-Internet, and you don't necessarily trust its contents, you can extract
-it as follows:
-
- $ mkdir newdir
- $ cd newdir
- $ tar -xvf ../untrusted.tar
-
- It is also a good practice to examine contents of the archive before
-extracting it, using `--list' (`-t') option, possibly combined with
-`--verbose' (`-v').
-
-\1f
-File: tar.info, Node: failing commands, Prev: extracting untrusted archives, Up: extract
-
-2.8.5 Commands That Will Fail
------------------------------
-
-Here are some sample commands you might try which will not work, and why
-they won't work.
-
- If you try to use this command,
-
- $ tar -xvf music.tar folk jazz
-
-you will get the following response:
-
- tar: folk: Not found in archive
- tar: jazz: Not found in archive
- $
-
-This is because these files were not originally _in_ the parent
-directory `..', where the archive is located; they were in the
-`practice' directory, and their file names reflect this:
-
- $ tar -tvf music.tar
- practice/folk
- practice/jazz
- practice/rock
-
-Likewise, if you try to use this command,
-
- $ tar -tvf music.tar folk jazz
-
-you would get a similar response. Members with those names are not in
-the archive. You must use the correct member names, or wildcards, in
-order to extract the files from the archive.
-
- If you have forgotten the correct names of the files in the archive,
-use `tar --list --verbose' to list them correctly.
-
-\1f
-File: tar.info, Node: going further, Prev: extract, Up: Tutorial
-
-2.9 Going Further Ahead in this Manual
-======================================
-
- _(This message will disappear, once this node revised.)_
-
-\1f
-File: tar.info, Node: tar invocation, Next: operations, Prev: Tutorial, Up: Top
-
-3 Invoking GNU `tar'
-********************
-
- _(This message will disappear, once this node revised.)_
-
-This chapter is about how one invokes the GNU `tar' command, from the
-command synopsis (*note Synopsis::). There are numerous options, and
-many styles for writing them. One mandatory option specifies the
-operation `tar' should perform (*note Operation Summary::), other
-options are meant to detail how this operation should be performed
-(*note Option Summary::). Non-option arguments are not always
-interpreted the same way, depending on what the operation is.
-
- You will find in this chapter everything about option styles and
-rules for writing them (*note Styles::). On the other hand, operations
-and options are fully described elsewhere, in other chapters. Here,
-you will find only synthetic descriptions for operations and options,
-together with pointers to other parts of the `tar' manual.
-
- Some options are so special they are fully described right in this
-chapter. They have the effect of inhibiting the normal operation of
-`tar' or else, they globally alter the amount of feedback the user
-receives about what is going on. These are the `--help' and
-`--version' (*note help::), `--verbose' (*note verbose::) and
-`--interactive' options (*note interactive::).
-
-* Menu:
-
-* Synopsis::
-* using tar options::
-* Styles::
-* All Options::
-* help::
-* defaults::
-* verbose::
-* checkpoints::
-* interactive::
-
-\1f
-File: tar.info, Node: Synopsis, Next: using tar options, Up: tar invocation
-
-3.1 General Synopsis of `tar'
-=============================
-
-The GNU `tar' program is invoked as either one of:
-
- tar OPTION... [NAME]...
- tar LETTER... [ARGUMENT]... [OPTION]... [NAME]...
-
- The second form is for when old options are being used.
-
- You can use `tar' to store files in an archive, to extract them from
-an archive, and to do other types of archive manipulation. The primary
-argument to `tar', which is called the "operation", specifies which
-action to take. The other arguments to `tar' are either "options",
-which change the way `tar' performs an operation, or file names or
-archive members, which specify the files or members `tar' is to act on.
-
- You can actually type in arguments in any order, even if in this
-manual the options always precede the other arguments, to make examples
-easier to understand. Further, the option stating the main operation
-mode (the `tar' main command) is usually given first.
-
- Each NAME in the synopsis above is interpreted as an archive member
-name when the main command is one of `--compare' (`--diff', `-d'),
-`--delete', `--extract' (`--get', `-x'), `--list' (`-t') or `--update'
-(`-u'). When naming archive members, you must give the exact name of
-the member in the archive, as it is printed by `--list'. For
-`--append' (`-r') and `--create' (`-c'), these NAME arguments specify
-the names of either files or directory hierarchies to place in the
-archive. These files or hierarchies should already exist in the file
-system, prior to the execution of the `tar' command.
-
- `tar' interprets relative file names as being relative to the
-working directory. `tar' will make all file names relative (by
-removing leading slashes when archiving or restoring files), unless you
-specify otherwise (using the `--absolute-names' option). *Note
-absolute::, for more information about `--absolute-names'.
-
- If you give the name of a directory as either a file name or a member
-name, then `tar' acts recursively on all the files and directories
-beneath that directory. For example, the name `/' identifies all the
-files in the file system to `tar'.
-
- The distinction between file names and archive member names is
-especially important when shell globbing is used, and sometimes a
-source of confusion for newcomers. *Note wildcards::, for more
-information about globbing. The problem is that shells may only glob
-using existing files in the file system. Only `tar' itself may glob on
-archive members, so when needed, you must ensure that wildcard
-characters reach `tar' without being interpreted by the shell first.
-Using a backslash before `*' or `?', or putting the whole argument
-between quotes, is usually sufficient for this.
-
- Even if NAMEs are often specified on the command line, they can also
-be read from a text file in the file system, using the
-`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option.
-
- If you don't use any file name arguments, `--append' (`-r'),
-`--delete' and `--concatenate' (`--catenate', `-A') will do nothing,
-while `--create' (`-c') will usually yield a diagnostic and inhibit
-`tar' execution. The other operations of `tar' (`--list', `--extract',
-`--compare', and `--update') will act on the entire contents of the
-archive.
-
- Besides successful exits, GNU `tar' may fail for many reasons. Some
-reasons correspond to bad usage, that is, when the `tar' command is
-improperly written. Errors may be encountered later, while
-encountering an error processing the archive or the files. Some errors
-are recoverable, in which case the failure is delayed until `tar' has
-completed all its work. Some errors are such that it would not
-meaningful, or at least risky, to continue processing: `tar' then
-aborts processing immediately. All abnormal exits, whether immediate
-or delayed, should always be clearly diagnosed on `stderr', after a
-line stating the nature of the error.
-
- Possible exit codes of GNU `tar' are summarized in the following
-table:
-
-0
- `Successful termination'.
-
-1
- `Some files differ'. If tar was invoked with `--compare'
- (`--diff', `-d') command line option, this means that some files
- in the archive differ from their disk counterparts (*note
- compare::). If tar was given `--create', `--append' or `--update'
- option, this exit code means that some files were changed while
- being archived and so the resulting archive does not contain the
- exact copy of the file set.
-
-2
- `Fatal error'. This means that some fatal, unrecoverable error
- occurred.
-
- If `tar' has invoked a subprocess and that subprocess exited with a
-nonzero exit code, `tar' exits with that code as well. This can
-happen, for example, if `tar' was given some compression option (*note
-gzip::) and the external compressor program failed. Another example is
-`rmt' failure during backup to the remote device (*note Remote Tape
-Server::).
-
-\1f
-File: tar.info, Node: using tar options, Next: Styles, Prev: Synopsis, Up: tar invocation
-
-3.2 Using `tar' Options
-=======================
-
-GNU `tar' has a total of eight operating modes which allow you to
-perform a variety of tasks. You are required to choose one operating
-mode each time you employ the `tar' program by specifying one, and only
-one operation as an argument to the `tar' command (two lists of four
-operations each may be found at *note frequent operations:: and *note
-Operations::). Depending on circumstances, you may also wish to
-customize how the chosen operating mode behaves. For example, you may
-wish to change the way the output looks, or the format of the files
-that you wish to archive may require you to do something special in
-order to make the archive look right.
-
- You can customize and control `tar''s performance by running `tar'
-with one or more options (such as `--verbose' (`-v'), which we used in
-the tutorial). As we said in the tutorial, "options" are arguments to
-`tar' which are (as their name suggests) optional. Depending on the
-operating mode, you may specify one or more options. Different options
-will have different effects, but in general they all change details of
-the operation, such as archive format, archive name, or level of user
-interaction. Some options make sense with all operating modes, while
-others are meaningful only with particular modes. You will likely use
-some options frequently, while you will only use others infrequently, or
-not at all. (A full list of options is available in *note All
-Options::.)
-
- The `TAR_OPTIONS' environment variable specifies default options to
-be placed in front of any explicit options. For example, if
-`TAR_OPTIONS' is `-v --unlink-first', `tar' behaves as if the two
-options `-v' and `--unlink-first' had been specified before any
-explicit options. Option specifications are separated by whitespace.
-A backslash escapes the next character, so it can be used to specify an
-option containing whitespace or a backslash.
-
- Note that `tar' options are case sensitive. For example, the
-options `-T' and `-t' are different; the first requires an argument for
-stating the name of a file providing a list of NAMEs, while the second
-does not require an argument and is another way to write `--list'
-(`-t').
-
- In addition to the eight operations, there are many options to
-`tar', and three different styles for writing both: long (mnemonic)
-form, short form, and old style. These styles are discussed below.
-Both the options and the operations can be written in any of these three
-styles.
-
-\1f
-File: tar.info, Node: Styles, Next: All Options, Prev: using tar options, Up: tar invocation
-
-3.3 The Three Option Styles
-===========================
-
-There are three styles for writing operations and options to the command
-line invoking `tar'. The different styles were developed at different
-times during the history of `tar'. These styles will be presented
-below, from the most recent to the oldest.
-
- Some options must take an argument. (For example, `--file' (`-f'))
-takes the name of an archive file as an argument. If you do not supply
-an archive file name, `tar' will use a default, but this can be
-confusing; thus, we recommend that you always supply a specific archive
-file name.) Where you _place_ the arguments generally depends on which
-style of options you choose. We will detail specific information
-relevant to each option style in the sections on the different option
-styles, below. The differences are subtle, yet can often be very
-important; incorrect option placement can cause you to overwrite a
-number of important files. We urge you to note these differences, and
-only use the option style(s) which makes the most sense to you until
-you feel comfortable with the others.
-
- Some options _may_ take an argument. Such options may have at most
-long and short forms, they do not have old style equivalent. The rules
-for specifying an argument for such options are stricter than those for
-specifying mandatory arguments. Please, pay special attention to them.
-
-* Menu:
-
-* Long Options:: Long Option Style
-* Short Options:: Short Option Style
-* Old Options:: Old Option Style
-* Mixing:: Mixing Option Styles
-
-\1f
-File: tar.info, Node: Long Options, Next: Short Options, Up: Styles
-
-3.3.1 Long Option Style
------------------------
-
-Each option has at least one "long" (or "mnemonic") name starting with
-two dashes in a row, e.g., `--list'. The long names are more clear than
-their corresponding short or old names. It sometimes happens that a
-single long option has many different names which are synonymous, such
-as `--compare' and `--diff'. In addition, long option names can be
-given unique abbreviations. For example, `--cre' can be used in place
-of `--create' because there is no other long option which begins with
-`cre'. (One way to find this out is by trying it and seeing what
-happens; if a particular abbreviation could represent more than one
-option, `tar' will tell you that that abbreviation is ambiguous and
-you'll know that that abbreviation won't work. You may also choose to
-run `tar --help' to see a list of options. Be aware that if you run
-`tar' with a unique abbreviation for the long name of an option you
-didn't want to use, you are stuck; `tar' will perform the command as
-ordered.)
-
- Long options are meant to be obvious and easy to remember, and their
-meanings are generally easier to discern than those of their
-corresponding short options (see below). For example:
-
- $ tar --create --verbose --blocking-factor=20 --file=/dev/rmt0
-
-gives a fairly good set of hints about what the command does, even for
-those not fully acquainted with `tar'.
-
- Long options which require arguments take those arguments
-immediately following the option name. There are two ways of
-specifying a mandatory argument. It can be separated from the option
-name either by an equal sign, or by any amount of white space
-characters. For example, the `--file' option (which tells the name of
-the `tar' archive) is given a file such as `archive.tar' as argument by
-using any of the following notations: `--file=archive.tar' or `--file
-archive.tar'.
-
- In contrast, optional arguments must always be introduced using an
-equal sign. For example, the `--backup' option takes an optional
-argument specifying backup type. It must be used as
-`--backup=BACKUP-TYPE'.
-
-\1f
-File: tar.info, Node: Short Options, Next: Old Options, Prev: Long Options, Up: Styles
-
-3.3.2 Short Option Style
-------------------------
-
-Most options also have a "short option" name. Short options start with
-a single dash, and are followed by a single character, e.g., `-t'
-(which is equivalent to `--list'). The forms are absolutely identical
-in function; they are interchangeable.
-
- The short option names are faster to type than long option names.
-
- Short options which require arguments take their arguments
-immediately following the option, usually separated by white space. It
-is also possible to stick the argument right after the short option
-name, using no intervening space. For example, you might write
-`-f archive.tar' or `-farchive.tar' instead of using
-`--file=archive.tar'. Both `--file=ARCHIVE-NAME' and `-f ARCHIVE-NAME'
-denote the option which indicates a specific archive, here named
-`archive.tar'.
-
- Short options which take optional arguments take their arguments
-immediately following the option letter, _without any intervening white
-space characters_.
-
- Short options' letters may be clumped together, but you are not
-required to do this (as compared to old options; see below). When
-short options are clumped as a set, use one (single) dash for them all,
-e.g., ``tar' -cvf'. Only the last option in such a set is allowed to
-have an argument(1).
-
- When the options are separated, the argument for each option which
-requires an argument directly follows that option, as is usual for Unix
-programs. For example:
-
- $ tar -c -v -b 20 -f /dev/rmt0
-
- If you reorder short options' locations, be sure to move any
-arguments that belong to them. If you do not move the arguments
-properly, you may end up overwriting files.
-
- ---------- Footnotes ----------
-
- (1) Clustering many options, the last of which has an argument, is a
-rather opaque way to write options. Some wonder if GNU `getopt' should
-not even be made helpful enough for considering such usages as invalid.
-
-\1f
-File: tar.info, Node: Old Options, Next: Mixing, Prev: Short Options, Up: Styles
-
-3.3.3 Old Option Style
-----------------------
-
- _(This message will disappear, once this node revised.)_
-
-Like short options, "old options" are single letters. However, old
-options must be written together as a single clumped set, without
-spaces separating them or dashes preceding them(1). This set of
-letters must be the first to appear on the command line, after the
-`tar' program name and some white space; old options cannot appear
-anywhere else. The letter of an old option is exactly the same letter
-as the corresponding short option. For example, the old option `t' is
-the same as the short option `-t', and consequently, the same as the
-long option `--list'. So for example, the command `tar cv' specifies
-the option `-v' in addition to the operation `-c'.
-
- When options that need arguments are given together with the command,
-all the associated arguments follow, in the same order as the options.
-Thus, the example given previously could also be written in the old
-style as follows:
-
- $ tar cvbf 20 /dev/rmt0
-
-Here, `20' is the argument of `-b' and `/dev/rmt0' is the argument of
-`-f'.
-
- On the other hand, this old style syntax makes it difficult to match
-option letters with their corresponding arguments, and is often
-confusing. In the command `tar cvbf 20 /dev/rmt0', for example, `20'
-is the argument for `-b', `/dev/rmt0' is the argument for `-f', and
-`-v' does not have a corresponding argument. Even using short options
-like in `tar -c -v -b 20 -f /dev/rmt0' is clearer, putting all
-arguments next to the option they pertain to.
-
- If you want to reorder the letters in the old option argument, be
-sure to reorder any corresponding argument appropriately.
-
- This old way of writing `tar' options can surprise even experienced
-users. For example, the two commands:
-
- tar cfz archive.tar.gz file
- tar -cfz archive.tar.gz file
-
-are quite different. The first example uses `archive.tar.gz' as the
-value for option `f' and recognizes the option `z'. The second
-example, however, uses `z' as the value for option `f' -- probably not
-what was intended.
-
- Old options are kept for compatibility with old versions of `tar'.
-
- This second example could be corrected in many ways, among which the
-following are equivalent:
-
- tar -czf archive.tar.gz file
- tar -cf archive.tar.gz -z file
- tar cf archive.tar.gz -z file
-
- As far as we know, all `tar' programs, GNU and non-GNU, support old
-options. GNU `tar' supports them not only for historical reasons, but
-also because many people are used to them. For compatibility with Unix
-`tar', the first argument is always treated as containing command and
-option letters even if it doesn't start with `-'. Thus, `tar c' is
-equivalent to `tar -c': both of them specify the `--create' (`-c')
-command to create an archive.
-
- ---------- Footnotes ----------
-
- (1) Beware that if you precede options with a dash, you are
-announcing the short option style instead of the old option style;
-short options are decoded differently.
-
-\1f
-File: tar.info, Node: Mixing, Prev: Old Options, Up: Styles
-
-3.3.4 Mixing Option Styles
---------------------------
-
-All three styles may be intermixed in a single `tar' command, so long
-as the rules for each style are fully respected(1). Old style options
-and either of the modern styles of options may be mixed within a single
-`tar' command. However, old style options must be introduced as the
-first arguments only, following the rule for old options (old options
-must appear directly after the `tar' command and some white space).
-Modern options may be given only after all arguments to the old options
-have been collected. If this rule is not respected, a modern option
-might be falsely interpreted as the value of the argument to one of the
-old style options.
-
- For example, all the following commands are wholly equivalent, and
-illustrate the many combinations and orderings of option styles.
-
- tar --create --file=archive.tar
- tar --create -f archive.tar
- tar --create -farchive.tar
- tar --file=archive.tar --create
- tar --file=archive.tar -c
- tar -c --file=archive.tar
- tar -c -f archive.tar
- tar -c -farchive.tar
- tar -cf archive.tar
- tar -cfarchive.tar
- tar -f archive.tar --create
- tar -f archive.tar -c
- tar -farchive.tar --create
- tar -farchive.tar -c
- tar c --file=archive.tar
- tar c -f archive.tar
- tar c -farchive.tar
- tar cf archive.tar
- tar f archive.tar --create
- tar f archive.tar -c
- tar fc archive.tar
-
- On the other hand, the following commands are _not_ equivalent to
-the previous set:
-
- tar -f -c archive.tar
- tar -fc archive.tar
- tar -fcarchive.tar
- tar -farchive.tarc
- tar cfarchive.tar
-
-These last examples mean something completely different from what the
-user intended (judging based on the example in the previous set which
-uses long options, whose intent is therefore very clear). The first
-four specify that the `tar' archive would be a file named `-c', `c',
-`carchive.tar' or `archive.tarc', respectively. The first two examples
-also specify a single non-option, NAME argument having the value
-`archive.tar'. The last example contains only old style option letters
-(repeating option `c' twice), not all of which are meaningful (eg., `.',
-`h', or `i'), with no argument value.
-
- ---------- Footnotes ----------
-
- (1) Before GNU `tar' version 1.11.6, a bug prevented intermixing old
-style options with long options in some cases.
-
-\1f
-File: tar.info, Node: All Options, Next: help, Prev: Styles, Up: tar invocation
-
-3.4 All `tar' Options
-=====================
-
-The coming manual sections contain an alphabetical listing of all `tar'
-operations and options, with brief descriptions and cross references to
-more in-depth explanations in the body of the manual. They also
-contain an alphabetically arranged table of the short option forms with
-their corresponding long option. You can use this table as a reference
-for deciphering `tar' commands in scripts.
-
-* Menu:
-
-* Operation Summary::
-* Option Summary::
-* Short Option Summary::
-
-\1f
-File: tar.info, Node: Operation Summary, Next: Option Summary, Up: All Options
-
-3.4.1 Operations
-----------------
-
-`--append'
-`-r'
- Appends files to the end of the archive. *Note append::.
-
-`--catenate'
-`-A'
- Same as `--concatenate'. *Note concatenate::.
-
-`--compare'
-`-d'
- Compares archive members with their counterparts in the file
- system, and reports differences in file size, mode, owner,
- modification date and contents. *Note compare::.
-
-`--concatenate'
-`-A'
- Appends other `tar' archives to the end of the archive. *Note
- concatenate::.
-
-`--create'
-`-c'
- Creates a new `tar' archive. *Note create::.
-
-`--delete'
- Deletes members from the archive. Don't try this on a archive on a
- tape! *Note delete::.
-
-`--diff'
-`-d'
- Same `--compare'. *Note compare::.
-
-`--extract'
-`-x'
- Extracts members from the archive into the file system. *Note
- extract::.
-
-`--get'
-`-x'
- Same as `--extract'. *Note extract::.
-
-`--list'
-`-t'
- Lists the members in an archive. *Note list::.
-
-`--update'
-`-u'
- Adds files to the end of the archive, but only if they are newer
- than their counterparts already in the archive, or if they do not
- already exist in the archive. *Note update::.
-
-
-\1f
-File: tar.info, Node: Option Summary, Next: Short Option Summary, Prev: Operation Summary, Up: All Options
-
-3.4.2 `tar' Options
--------------------
-
-`--absolute-names'
-`-P'
- Normally when creating an archive, `tar' strips an initial `/'
- from member names. This option disables that behavior. *Note
- absolute::.
-
-`--after-date'
- (See `--newer', *note after::)
-
-`--anchored'
- A pattern must match an initial subsequence of the name's
- components. *Note controlling pattern-matching::.
-
-`--atime-preserve'
-`--atime-preserve=replace'
-`--atime-preserve=system'
- Attempt to preserve the access time of files when reading them.
- This option currently is effective only on files that you own,
- unless you have superuser privileges.
-
- `--atime-preserve=replace' remembers the access time of a file
- before reading it, and then restores the access time afterwards.
- This may cause problems if other programs are reading the file at
- the same time, as the times of their accesses will be lost. On
- most platforms restoring the access time also requires `tar' to
- restore the data modification time too, so this option may also
- cause problems if other programs are writing the file at the same
- time. (Tar attempts to detect this situation, but cannot do so
- reliably due to race conditions.) Worse, on most platforms
- restoring the access time also updates the status change time,
- which means that this option is incompatible with incremental
- backups.
-
- `--atime-preserve=system' avoids changing time stamps on files,
- without interfering with time stamp updates caused by other
- programs, so it works better with incremental backups. However,
- it requires a special `O_NOATIME' option from the underlying
- operating and file system implementation, and it also requires
- that searching directories does not update their access times. As
- of this writing (November 2005) this works only with Linux, and
- only with Linux kernels 2.6.8 and later. Worse, there is
- currently no reliable way to know whether this feature actually
- works. Sometimes `tar' knows that it does not work, and if you use
- `--atime-preserve=system' then `tar' complains and exits right
- away. But other times `tar' might think that the option works
- when it actually does not.
-
- Currently `--atime-preserve' with no operand defaults to
- `--atime-preserve=replace', but this may change in the future as
- support for `--atime-preserve=system' improves.
-
- If your operating system does not support
- `--atime-preserve=system', you might be able to preserve access
- times reliably by by using the `mount' command. For example, you
- can mount the file system read-only, or access the file system via
- a read-only loopback mount, or use the `noatime' mount option
- available on some systems. However, mounting typically requires
- superuser privileges and can be a pain to manage.
-
-`--auto-compress'
-`-a'
- During a `--create' operation, enables automatic compressed format
- recognition based on the archive suffix. *Note gzip::.
-
-`--backup=BACKUP-TYPE'
- Rather than deleting files from the file system, `tar' will back
- them up using simple or numbered backups, depending upon
- BACKUP-TYPE. *Note backup::.
-
-`--block-number'
-`-R'
- With this option present, `tar' prints error messages for read
- errors with the block number in the archive file. *Note
- block-number::.
-
-`--blocking-factor=BLOCKING'
-`-b BLOCKING'
- Sets the blocking factor `tar' uses to BLOCKING x 512 bytes per
- record. *Note Blocking Factor::.
-
-`--bzip2'
-`-j'
- This option tells `tar' to read or write archives through `bzip2'.
- *Note gzip::.
-
-`--check-device'
- Check device numbers when creating a list of modified files for
- incremental archiving. This is the default. *Note device
- numbers::, for a detailed description.
-
-`--checkpoint[=NUMBER]'
- This option directs `tar' to print periodic checkpoint messages as
- it reads through the archive. It is intended for when you want a
- visual indication that `tar' is still running, but don't want to
- see `--verbose' output. You can also instruct `tar' to execute a
- list of actions on each checkpoint, see `--checklist-action'
- below. For a detailed description, see *note checkpoints::.
-
-`--checkpoint-action=ACTION'
- Instruct `tar' to execute an action upon hitting a breakpoint.
- Here we give only a brief outline. *Note checkpoints::, for a
- complete description.
-
- The ACTION argument can be one of the following:
-
- bell
- Produce an audible bell on the console.
-
- dot
- .
- Print a single dot on the standard listing stream.
-
- echo
- Display a textual message on the standard error, with the
- status and number of the checkpoint. This is the default.
-
- echo=STRING
- Display STRING on the standard error. Before output, the
- string is subject to meta-character expansion.
-
- exec=COMMAND
- Execute the given COMMAND.
-
- sleep=TIME
- Wait for TIME seconds.
-
- ttyout=STRING
- Output STRING on the current console (`/dev/tty').
-
- Several `--checkpoint-action' options can be specified. The
- supplied actions will be executed in order of their appearance in
- the command line.
-
- Using `--checkpoint-action' without `--checkpoint' assumes default
- checkpoint frequency of one checkpoint per 10 records.
-
-`--check-links'
-`-l'
- If this option was given, `tar' will check the number of links
- dumped for each processed file. If this number does not match the
- total number of hard links for the file, a warning message will be
- output (1).
-
- *Note hard links::.
-
-`--compress'
-`--uncompress'
-`-Z'
- `tar' will use the `compress' program when reading or writing the
- archive. This allows you to directly act on archives while saving
- space. *Note gzip::.
-
-`--confirmation'
- (See `--interactive'.) *Note interactive::.
-
-`--delay-directory-restore'
- Delay setting modification times and permissions of extracted
- directories until the end of extraction. *Note Directory
- Modification Times and Permissions::.
-
-`--dereference'
-`-h'
- When creating a `tar' archive, `tar' will archive the file that a
- symbolic link points to, rather than archiving the symlink. *Note
- dereference::.
-
-`--directory=DIR'
-`-C DIR'
- When this option is specified, `tar' will change its current
- directory to DIR before performing any operations. When this
- option is used during archive creation, it is order sensitive.
- *Note directory::.
-
-`--exclude=PATTERN'
- When performing operations, `tar' will skip files that match
- PATTERN. *Note exclude::.
-
-`--exclude-from=FILE'
-`-X FILE'
- Similar to `--exclude', except `tar' will use the list of patterns
- in the file FILE. *Note exclude::.
-
-`--exclude-caches'
- Exclude from dump any directory containing a valid cache directory
- tag file, but still dump the directory node and the tag file
- itself.
-
- *Note exclude::.
-
-`--exclude-caches-under'
- Exclude from dump any directory containing a valid cache directory
- tag file, but still dump the directory node itself.
-
- *Note exclude::.
-
-`--exclude-caches-all'
- Exclude from dump any directory containing a valid cache directory
- tag file. *Note exclude::.
-
-`--exclude-tag=FILE'
- Exclude from dump any directory containing file named FILE, but
- dump the directory node and FILE itself. *Note exclude::.
-
-`--exclude-tag-under=FILE'
- Exclude from dump the contents of any directory containing file
- named FILE, but dump the directory node itself. *Note exclude::.
-
-`--exclude-tag-all=FILE'
- Exclude from dump any directory containing file named FILE. *Note
- exclude::.
-
-`--exclude-vcs'
- Exclude from dump directories and files, that are internal for some
- widely used version control systems.
-
- *Note exclude::.
-
-`--file=ARCHIVE'
-`-f ARCHIVE'
- `tar' will use the file ARCHIVE as the `tar' archive it performs
- operations on, rather than `tar''s compilation dependent default.
- *Note file tutorial::.
-
-`--files-from=FILE'
-`-T FILE'
- `tar' will use the contents of FILE as a list of archive members
- or files to operate on, in addition to those specified on the
- command-line. *Note files::.
-
-`--force-local'
- Forces `tar' to interpret the file name given to `--file' as a
- local file, even if it looks like a remote tape drive name. *Note
- local and remote archives::.
-
-`--format=FORMAT'
-`-H FORMAT'
- Selects output archive format. FORMAT may be one of the following:
-
- `v7'
- Creates an archive that is compatible with Unix V7 `tar'.
-
- `oldgnu'
- Creates an archive that is compatible with GNU `tar' version
- 1.12 or earlier.
-
- `gnu'
- Creates archive in GNU tar 1.13 format. Basically it is the
- same as `oldgnu' with the only difference in the way it
- handles long numeric fields.
-
- `ustar'
- Creates a POSIX.1-1988 compatible archive.
-
- `posix'
- Creates a POSIX.1-2001 archive.
-
-
- *Note Formats::, for a detailed discussion of these formats.
-
-`--group=GROUP'
- Files added to the `tar' archive will have a group ID of GROUP,
- rather than the group from the source file. GROUP is first decoded
- as a group symbolic name, but if this interpretation fails, it has
- to be a decimal numeric group ID. *Note override::.
-
- Also see the comments for the `--owner=USER' option.
-
-`--gzip'
-`--gunzip'
-`--ungzip'
-`-z'
- This option tells `tar' to read or write archives through `gzip',
- allowing `tar' to directly operate on several kinds of compressed
- archives transparently. *Note gzip::.
-
-`--hard-dereference'
- When creating an archive, dereference hard links and store the
- files they refer to, instead of creating usual hard link members.
-
- *Note hard links::.
-
-`--help'
-`-?'
- `tar' will print out a short message summarizing the operations and
- options to `tar' and exit. *Note help::.
-
-`--ignore-case'
- Ignore case when matching member or file names with patterns.
- *Note controlling pattern-matching::.
-
-`--ignore-command-error'
- Ignore exit codes of subprocesses. *Note Writing to an External
- Program::.
-
-`--ignore-failed-read'
- Do not exit unsuccessfully merely because an unreadable file was
- encountered. *Note Reading::.
-
-`--ignore-zeros'
-`-i'
- With this option, `tar' will ignore zeroed blocks in the archive,
- which normally signals EOF. *Note Reading::.
-
-`--incremental'
-`-G'
- Informs `tar' that it is working with an old GNU-format
- incremental backup archive. It is intended primarily for
- backwards compatibility only. *Note Incremental Dumps::, for a
- detailed discussion of incremental archives.
-
-`--index-file=FILE'
- Send verbose output to FILE instead of to standard output.
-
-`--info-script=SCRIPT-FILE'
-`--new-volume-script=SCRIPT-FILE'
-`-F SCRIPT-FILE'
- When `tar' is performing multi-tape backups, SCRIPT-FILE is run at
- the end of each tape. If SCRIPT-FILE exits with nonzero status,
- `tar' fails immediately. *Note info-script::, for a detailed
- discussion of SCRIPT-FILE.
-
-`--interactive'
-`--confirmation'
-`-w'
- Specifies that `tar' should ask the user for confirmation before
- performing potentially destructive options, such as overwriting
- files. *Note interactive::.
-
-`--keep-newer-files'
- Do not replace existing files that are newer than their archive
- copies when extracting files from an archive.
-
-`--keep-old-files'
-`-k'
- Do not overwrite existing files when extracting files from an
- archive. *Note Keep Old Files::.
-
-`--label=NAME'
-`-V NAME'
- When creating an archive, instructs `tar' to write NAME as a name
- record in the archive. When extracting or listing archives, `tar'
- will only operate on archives that have a label matching the
- pattern specified in NAME. *Note Tape Files::.
-
-`--listed-incremental=SNAPSHOT-FILE'
-`-g SNAPSHOT-FILE'
- During a `--create' operation, specifies that the archive that
- `tar' creates is a new GNU-format incremental backup, using
- SNAPSHOT-FILE to determine which files to backup. With other
- operations, informs `tar' that the archive is in incremental
- format. *Note Incremental Dumps::.
-
-`--lzma'
- This option tells `tar' to read or write archives through `lzma'.
- *Note gzip::.
-
-`--mode=PERMISSIONS'
- When adding files to an archive, `tar' will use PERMISSIONS for
- the archive members, rather than the permissions from the files.
- PERMISSIONS can be specified either as an octal number or as
- symbolic permissions, like with `chmod'. *Note override::.
-
-`--mtime=DATE'
- When adding files to an archive, `tar' will use DATE as the
- modification time of members when creating archives, instead of
- their actual modification times. The value of DATE can be either
- a textual date representation (*note Date input formats::) or a
- name of the existing file, starting with `/' or `.'. In the
- latter case, the modification time of that file is used. *Note
- override::.
-
-`--multi-volume'
-`-M'
- Informs `tar' that it should create or otherwise operate on a
- multi-volume `tar' archive. *Note Using Multiple Tapes::.
-
-`--new-volume-script'
- (see -info-script)
-
-`--newer=DATE'
-`--after-date=DATE'
-`-N'
- When creating an archive, `tar' will only add files that have
- changed since DATE. If DATE begins with `/' or `.', it is taken
- to be the name of a file whose data modification time specifies
- the date. *Note after::.
-
-`--newer-mtime=DATE'
- Like `--newer', but add only files whose contents have changed (as
- opposed to just `--newer', which will also back up files for which
- any status information has changed). *Note after::.
-
-`--no-anchored'
- An exclude pattern can match any subsequence of the name's
- components. *Note controlling pattern-matching::.
-
-`--no-check-device'
- Do not check device numbers when creating a list of modified files
- for incremental archiving. *Note device numbers::, for a detailed
- description.
-
-`--no-delay-directory-restore'
- Modification times and permissions of extracted directories are
- set when all files from this directory have been extracted. This
- is the default. *Note Directory Modification Times and
- Permissions::.
-
-`--no-ignore-case'
- Use case-sensitive matching. *Note controlling pattern-matching::.
-
-`--no-ignore-command-error'
- Print warnings about subprocesses that terminated with a nonzero
- exit code. *Note Writing to an External Program::.
-
-`--no-overwrite-dir'
- Preserve metadata of existing directories when extracting files
- from an archive. *Note Overwrite Old Files::.
-
-`--no-quote-chars=STRING'
- Remove characters listed in STRING from the list of quoted
- characters set by the previous `--quote-chars' option (*note
- quoting styles::).
-
-`--no-recursion'
- With this option, `tar' will not recurse into directories. *Note
- recurse::.
-
-`--no-same-owner'
-`-o'
- When extracting an archive, do not attempt to preserve the owner
- specified in the `tar' archive. This the default behavior for
- ordinary users.
-
-`--no-same-permissions'
- When extracting an archive, subtract the user's umask from files
- from the permissions specified in the archive. This is the
- default behavior for ordinary users.
-
-`--no-unquote'
- Treat all input file or member names literally, do not interpret
- escape sequences. *Note input name quoting::.
-
-`--no-wildcards'
- Do not use wildcards. *Note controlling pattern-matching::.
-
-`--no-wildcards-match-slash'
- Wildcards do not match `/'. *Note controlling pattern-matching::.
-
-`--null'
- When `tar' is using the `--files-from' option, this option
- instructs `tar' to expect file names terminated with NUL, so `tar'
- can correctly work with file names that contain newlines. *Note
- nul::.
-
-`--numeric-owner'
- This option will notify `tar' that it should use numeric user and
- group IDs when creating a `tar' file, rather than names. *Note
- Attributes::.
-
-`-o'
- The function of this option depends on the action `tar' is
- performing. When extracting files, `-o' is a synonym for
- `--no-same-owner', i.e., it prevents `tar' from restoring
- ownership of files being extracted.
-
- When creating an archive, it is a synonym for `--old-archive'.
- This behavior is for compatibility with previous versions of GNU
- `tar', and will be removed in future releases.
-
- *Note Changes::, for more information.
-
-`--occurrence[=NUMBER]'
- This option can be used in conjunction with one of the subcommands
- `--delete', `--diff', `--extract' or `--list' when a list of files
- is given either on the command line or via `-T' option.
-
- This option instructs `tar' to process only the NUMBERth
- occurrence of each named file. NUMBER defaults to 1, so
-
- tar -x -f archive.tar --occurrence filename
-
- will extract the first occurrence of the member `filename' from
- `archive.tar' and will terminate without scanning to the end of
- the archive.
-
-`--old-archive'
- Synonym for `--format=v7'.
-
-`--one-file-system'
- Used when creating an archive. Prevents `tar' from recursing into
- directories that are on different file systems from the current
- directory.
-
-`--overwrite'
- Overwrite existing files and directory metadata when extracting
- files from an archive. *Note Overwrite Old Files::.
-
-`--overwrite-dir'
- Overwrite the metadata of existing directories when extracting
- files from an archive. *Note Overwrite Old Files::.
-
-`--owner=USER'
- Specifies that `tar' should use USER as the owner of members when
- creating archives, instead of the user associated with the source
- file. USER is first decoded as a user symbolic name, but if this
- interpretation fails, it has to be a decimal numeric user ID.
- *Note override::.
-
- This option does not affect extraction from archives.
-
-`--pax-option=KEYWORD-LIST'
- This option is meaningful only with POSIX.1-2001 archives (*note
- posix::). It modifies the way `tar' handles the extended header
- keywords. KEYWORD-LIST is a comma-separated list of keyword
- options. *Note PAX keywords::, for a detailed discussion.
-
-`--portability'
-`--old-archive'
- Synonym for `--format=v7'.
-
-`--posix'
- Same as `--format=posix'.
-
-`--preserve'
- Synonymous with specifying both `--preserve-permissions' and
- `--same-order'. *Note Setting Access Permissions::.
-
-`--preserve-order'
- (See `--same-order'; *note Reading::.)
-
-`--preserve-permissions'
-`--same-permissions'
-`-p'
- When `tar' is extracting an archive, it normally subtracts the
- users' umask from the permissions specified in the archive and uses
- that number as the permissions to create the destination file.
- Specifying this option instructs `tar' that it should use the
- permissions directly from the archive. *Note Setting Access
- Permissions::.
-
-`--quote-chars=STRING'
- Always quote characters from STRING, even if the selected quoting
- style would not quote them (*note quoting styles::).
-
-`--quoting-style=STYLE'
- Set quoting style to use when printing member and file names
- (*note quoting styles::). Valid STYLE values are: `literal',
- `shell', `shell-always', `c', `escape', `locale', and `clocale'.
- Default quoting style is `escape', unless overridden while
- configuring the package.
-
-`--read-full-records'
-`-B'
- Specifies that `tar' should reblock its input, for reading from
- pipes on systems with buggy implementations. *Note Reading::.
-
-`--record-size=SIZE'
- Instructs `tar' to use SIZE bytes per record when accessing the
- archive. *Note Blocking Factor::.
-
-`--recursion'
- With this option, `tar' recurses into directories (default).
- *Note recurse::.
-
-`--recursive-unlink'
- Remove existing directory hierarchies before extracting
- directories of the same name from the archive. *Note Recursive
- Unlink::.
-
-`--remove-files'
- Directs `tar' to remove the source file from the file system after
- appending it to an archive. *Note remove files::.
-
-`--restrict'
- Disable use of some potentially harmful `tar' options. Currently
- this option disables shell invocation from multi-volume menu
- (*note Using Multiple Tapes::).
-
-`--rmt-command=CMD'
- Notifies `tar' that it should use CMD instead of the default
- `/usr/libexec/rmt' (*note Remote Tape Server::).
-
-`--rsh-command=CMD'
- Notifies `tar' that is should use CMD to communicate with remote
- devices. *Note Device::.
-
-`--same-order'
-`--preserve-order'
-`-s'
- This option is an optimization for `tar' when running on machines
- with small amounts of memory. It informs `tar' that the list of
- file arguments has already been sorted to match the order of files
- in the archive. *Note Reading::.
-
-`--same-owner'
- When extracting an archive, `tar' will attempt to preserve the
- owner specified in the `tar' archive with this option present.
- This is the default behavior for the superuser; this option has an
- effect only for ordinary users. *Note Attributes::.
-
-`--same-permissions'
- (See `--preserve-permissions'; *note Setting Access Permissions::.)
-
-`--seek'
-`-n'
- Assume that the archive media supports seeks to arbitrary
- locations. Usually `tar' determines automatically whether the
- archive can be seeked or not. This option is intended for use in
- cases when such recognition fails.
-
-`--show-defaults'
- Displays the default options used by `tar' and exits successfully.
- This option is intended for use in shell scripts. Here is an
- example of what you can see using this option:
-
- $ tar --show-defaults
- --format=gnu -f- -b20 --quoting-style=escape \
- --rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
-
-`--show-omitted-dirs'
- Instructs `tar' to mention the directories it is skipping when
- operating on a `tar' archive. *Note show-omitted-dirs::.
-
-`--show-transformed-names'
-`--show-stored-names'
- Display file or member names after applying any transformations
- (*note transform::). In particular, when used in conjunction with
- one of the archive creation operations it instructs `tar' to list
- the member names stored in the archive, as opposed to the actual
- file names. *Note listing member and file names::.
-
-`--sparse'
-`-S'
- Invokes a GNU extension when adding files to an archive that
- handles sparse files efficiently. *Note sparse::.
-
-`--sparse-version=VERSION'
- Specifies the "format version" to use when archiving sparse files.
- Implies `--sparse'. *Note sparse::. For the description of the
- supported sparse formats, *Note Sparse Formats::.
-
-`--starting-file=NAME'
-`-K NAME'
- This option affects extraction only; `tar' will skip extracting
- files in the archive until it finds one that matches NAME. *Note
- Scarce::.
-
-`--strip-components=NUMBER'
- Strip given NUMBER of leading components from file names before
- extraction. For example, if archive `archive.tar' contained
- `/some/file/name', then running
-
- tar --extract --file archive.tar --strip-components=2
-
- would extract this file to file `name'.
-
- , summary
-
-`--suffix=SUFFIX'
- Alters the suffix `tar' uses when backing up files from the default
- `~'. *Note backup::.
-
-`--tape-length=NUM'
-`-L NUM'
- Specifies the length of tapes that `tar' is writing as being
- NUM x 1024 bytes long. *Note Using Multiple Tapes::.
-
-`--test-label'
- Reads the volume label. If an argument is specified, test whether
- it matches the volume label. *Note --test-label option::.
-
-`--to-command=COMMAND'
- During extraction `tar' will pipe extracted files to the standard
- input of COMMAND. *Note Writing to an External Program::.
-
-`--to-stdout'
-`-O'
- During extraction, `tar' will extract files to stdout rather than
- to the file system. *Note Writing to Standard Output::.
-
-`--totals[=SIGNO]'
- Displays the total number of bytes transferred when processing an
- archive. If an argument is given, these data are displayed on
- request, when signal SIGNO is delivered to `tar'. *Note totals::.
-
-`--touch'
-`-m'
- Sets the data modification time of extracted files to the
- extraction time, rather than the data modification time stored in
- the archive. *Note Data Modification Times::.
-
-`--transform=SED-EXPR'
- Transform file or member names using `sed' replacement expression
- SED-EXPR. For example,
-
- $ tar cf archive.tar --transform 's,^\./,usr/,' .
-
- will add to `archive' files from the current working directory,
- replacing initial `./' prefix with `usr/'. For the detailed
- discussion, *Note transform::.
-
- To see transformed member names in verbose listings, use
- `--show-transformed-names' option (*note show-transformed-names::).
-
-`--uncompress'
- (See `--compress'. *note gzip::)
-
-`--ungzip'
- (See `--gzip'. *note gzip::)
-
-`--unlink-first'
-`-U'
- Directs `tar' to remove the corresponding file from the file
- system before extracting it from the archive. *Note Unlink
- First::.
-
-`--unquote'
- Enable unquoting input file or member names (default). *Note
- input name quoting::.
-
-`--use-compress-program=PROG'
- Instructs `tar' to access the archive through PROG, which is
- presumed to be a compression program of some sort. *Note gzip::.
-
-`--utc'
- Display file modification dates in UTC. This option implies
- `--verbose'.
-
-`--verbose'
-`-v'
- Specifies that `tar' should be more verbose about the operations
- it is performing. This option can be specified multiple times for
- some operations to increase the amount of information displayed.
- *Note verbose::.
-
-`--verify'
-`-W'
- Verifies that the archive was correctly written when creating an
- archive. *Note verify::.
-
-`--version'
- Print information about the program's name, version, origin and
- legal status, all on standard output, and then exit successfully.
- *Note help::.
-
-`--volno-file=FILE'
- Used in conjunction with `--multi-volume'. `tar' will keep track
- of which volume of a multi-volume archive it is working in FILE.
- *Note volno-file::.
-
-`--wildcards'
- Use wildcards when matching member names with patterns. *Note
- controlling pattern-matching::.
-
-`--wildcards-match-slash'
- Wildcards match `/'. *Note controlling pattern-matching::.
-
- ---------- Footnotes ----------
-
- (1) Earlier versions of GNU `tar' understood `-l' as a synonym for
-`--one-file-system'. The current semantics, which complies to UNIX98,
-was introduced with version 1.15.91. *Note Changes::, for more
-information.
-
-\1f
-File: tar.info, Node: Short Option Summary, Prev: Option Summary, Up: All Options
-
-3.4.3 Short Options Cross Reference
------------------------------------
-
-Here is an alphabetized list of all of the short option forms, matching
-them with the equivalent long option.
-
-Short Option Reference
---------------------------------------------------------------------------
--A *note --concatenate::.
--B *note --read-full-records::.
--C *note --directory::.
--F *note --info-script::.
--G *note --incremental::.
--K *note --starting-file::.
--L *note --tape-length::.
--M *note --multi-volume::.
--N *note --newer::.
--O *note --to-stdout::.
--P *note --absolute-names::.
--R *note --block-number::.
--S *note --sparse::.
--T *note --files-from::.
--U *note --unlink-first::.
--V *note --label::.
--W *note --verify::.
--X *note --exclude-from::.
--Z *note --compress::.
--b *note --blocking-factor::.
--c *note --create::.
--d *note --compare::.
--f *note --file::.
--g *note --listed-incremental::.
--h *note --dereference::.
--i *note --ignore-zeros::.
--j *note --bzip2::.
--k *note --keep-old-files::.
--l *note --check-links::.
--m *note --touch::.
--o When creating, *note --no-same-owner::, when extracting --
- *note --portability::.
-
- The later usage is deprecated. It is retained for
- compatibility with the earlier versions of GNU `tar'. In
- future releases `-o' will be equivalent to
- `--no-same-owner' only.
--p *note --preserve-permissions::.
--r *note --append::.
--s *note --same-order::.
--t *note --list::.
--u *note --update::.
--v *note --verbose::.
--w *note --interactive::.
--x *note --extract::.
--z *note --gzip::.
-
-\1f
-File: tar.info, Node: help, Next: defaults, Prev: All Options, Up: tar invocation
-
-3.5 GNU `tar' documentation
-===========================
-
-Being careful, the first thing is really checking that you are using
-GNU `tar', indeed. The `--version' option causes `tar' to print
-information about its name, version, origin and legal status, all on
-standard output, and then exit successfully. For example,
-`tar --version' might print:
-
- tar (GNU tar) 1.20
- Copyright (C) 2008 Free Software Foundation, Inc.
- This is free software. You may redistribute copies of it under the terms
- of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
- There is NO WARRANTY, to the extent permitted by law.
-
- Written by John Gilmore and Jay Fenlason.
-
-The first occurrence of `tar' in the result above is the program name
-in the package (for example, `rmt' is another program), while the
-second occurrence of `tar' is the name of the package itself,
-containing possibly many programs. The package is currently named
-`tar', after the name of the main program it contains(1).
-
- Another thing you might want to do is checking the spelling or
-meaning of some particular `tar' option, without resorting to this
-manual, for once you have carefully read it. GNU `tar' has a short
-help feature, triggerable through the `--help' option. By using this
-option, `tar' will print a usage message listing all available options
-on standard output, then exit successfully, without doing anything else
-and ignoring all other options. Even if this is only a brief summary,
-it may be several screens long. So, if you are not using some kind of
-scrollable window, you might prefer to use something like:
-
- $ tar --help | less
-
-presuming, here, that you like using `less' for a pager. Other popular
-pagers are `more' and `pg'. If you know about some KEYWORD which
-interests you and do not want to read all the `--help' output, another
-common idiom is doing:
-
- tar --help | grep KEYWORD
-
-for getting only the pertinent lines. Notice, however, that some `tar'
-options have long description lines and the above command will list
-only the first of them.
-
- The exact look of the option summary displayed by `tar --help' is
-configurable. *Note Configuring Help Summary::, for a detailed
-description.
-
- If you only wish to check the spelling of an option, running `tar
---usage' may be a better choice. This will display a terse list of
-`tar' option without accompanying explanations.
-
- The short help output is quite succinct, and you might have to get
-back to the full documentation for precise points. If you are reading
-this paragraph, you already have the `tar' manual in some form. This
-manual is available in a variety of forms from
-`http://www.gnu.org/software/tar/manual'. It may be printed out of the
-GNU `tar' distribution, provided you have TeX already installed
-somewhere, and a laser printer around. Just configure the
-distribution, execute the command `make dvi', then print `doc/tar.dvi'
-the usual way (contact your local guru to know how). If GNU `tar' has
-been conveniently installed at your place, this manual is also
-available in interactive, hypertextual form as an Info file. Just call
-`info tar' or, if you do not have the `info' program handy, use the
-Info reader provided within GNU Emacs, calling `tar' from the main Info
-menu.
-
- There is currently no `man' page for GNU `tar'. If you observe such
-a `man' page on the system you are running, either it does not belong
-to GNU `tar', or it has not been produced by GNU. Some package
-maintainers convert `tar --help' output to a man page, using
-`help2man'. In any case, please bear in mind that the authoritative
-source of information about GNU `tar' is this Texinfo documentation.
-
- ---------- Footnotes ----------
-
- (1) There are plans to merge the `cpio' and `tar' packages into a
-single one which would be called `paxutils'. So, who knows if, one of
-this days, the `--version' would not output `tar (GNU paxutils) 3.2'
-
-\1f
-File: tar.info, Node: defaults, Next: verbose, Prev: help, Up: tar invocation
-
-3.6 Obtaining GNU `tar' default values
-======================================
-
-GNU `tar' has some predefined defaults that are used when you do not
-explicitly specify another values. To obtain a list of such defaults,
-use `--show-defaults' option. This will output the values in the form
-of `tar' command line options:
-
- tar --show-defaults
- --format=gnu -f- -b20 --quoting-style=escape
- --rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
-
-Notice, that this option outputs only one line. The example output
-above has been split to fit page boundaries.
-
-The above output shows that this version of GNU `tar' defaults to using
-`gnu' archive format (*note Formats::), it uses standard output as the
-archive, if no `--file' option has been given (*note file tutorial::),
-the default blocking factor is 20 (*note Blocking Factor::). It also
-shows the default locations where `tar' will look for `rmt' and `rsh'
-binaries.
-
-\1f
-File: tar.info, Node: verbose, Next: checkpoints, Prev: defaults, Up: tar invocation
-
-3.7 Checking `tar' progress
-===========================
-
-Typically, `tar' performs most operations without reporting any
-information to the user except error messages. When using `tar' with
-many options, particularly ones with complicated or
-difficult-to-predict behavior, it is possible to make serious mistakes.
-`tar' provides several options that make observing `tar' easier. These
-options cause `tar' to print information as it progresses in its job,
-and you might want to use them just for being more careful about what
-is going on, or merely for entertaining yourself. If you have
-encountered a problem when operating on an archive, however, you may
-need more information than just an error message in order to solve the
-problem. The following options can be helpful diagnostic tools.
-
- Normally, the `--list' (`-t') command to list an archive prints just
-the file names (one per line) and the other commands are silent. When
-used with most operations, the `--verbose' (`-v') option causes `tar'
-to print the name of each file or archive member as it is processed.
-This and the other options which make `tar' print status information
-can be useful in monitoring `tar'.
-
- With `--create' or `--extract', `--verbose' used once just prints
-the names of the files or members as they are processed. Using it
-twice causes `tar' to print a longer listing (*Note verbose member
-listing::, for the description) for each member. Since `--list'
-already prints the names of the members, `--verbose' used once with
-`--list' causes `tar' to print an `ls -l' type listing of the files in
-the archive. The following examples both extract members with long
-list output:
-
- $ tar --extract --file=archive.tar --verbose --verbose
- $ tar xvvf archive.tar
-
- Verbose output appears on the standard output except when an archive
-is being written to the standard output, as with `tar --create --file=-
---verbose' (`tar cfv -', or even `tar cv'--if the installer let
-standard output be the default archive). In that case `tar' writes
-verbose output to the standard error stream.
-
- If `--index-file=FILE' is specified, `tar' sends verbose output to
-FILE rather than to standard output or standard error.
-
- The `--totals' option causes `tar' to print on the standard error
-the total amount of bytes transferred when processing an archive. When
-creating or appending to an archive, this option prints the number of
-bytes written to the archive and the average speed at which they have
-been written, e.g.:
-
- $ tar -c -f archive.tar --totals /home
- Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
-
- When reading an archive, this option displays the number of bytes
-read:
-
- $ tar -x -f archive.tar --totals
- Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
-
- Finally, when deleting from an archive, the `--totals' option
-displays both numbers plus number of bytes removed from the archive:
-
- $ tar --delete -f foo.tar --totals --wildcards '*~'
- Total bytes read: 9543680 (9.2MiB, 201MiB/s)
- Total bytes written: 3829760 (3.7MiB, 81MiB/s)
- Total bytes deleted: 1474048
-
- You can also obtain this information on request. When `--totals' is
-used with an argument, this argument is interpreted as a symbolic name
-of a signal, upon delivery of which the statistics is to be printed:
-
-`--totals=SIGNO'
- Print statistics upon delivery of signal SIGNO. Valid arguments
- are: `SIGHUP', `SIGQUIT', `SIGINT', `SIGUSR1' and `SIGUSR2'.
- Shortened names without `SIG' prefix are also accepted.
-
- Both forms of `--totals' option can be used simultaneously. Thus,
-`tar -x --totals --totals=USR1' instructs `tar' to extract all members
-from its default archive and print statistics after finishing the
-extraction, as well as when receiving signal `SIGUSR1'.
-
- The `--checkpoint' option prints an occasional message as `tar'
-reads or writes the archive. It is designed for those who don't need
-the more detailed (and voluminous) output of `--block-number' (`-R'),
-but do want visual confirmation that `tar' is actually making forward
-progress. By default it prints a message each 10 records read or
-written. This can be changed by giving it a numeric argument after an
-equal sign:
-
- $ tar -c --checkpoint=1000 /var
- tar: Write checkpoint 1000
- tar: Write checkpoint 2000
- tar: Write checkpoint 3000
-
- This example shows the default checkpoint message used by `tar'. If
-you place a dot immediately after the equal sign, it will print a `.'
-at each checkpoint(1). For example:
-
- $ tar -c --checkpoint=.1000 /var
- ...
-
- The `--checkpoint' option provides a flexible mechanism for
-executing arbitrary actions upon hitting checkpoints, see the next
-section (*note checkpoints::), for more information on it.
-
- The `--show-omitted-dirs' option, when reading an archive--with
-`--list' or `--extract', for example--causes a message to be printed
-for each directory in the archive which is skipped. This happens
-regardless of the reason for skipping: the directory might not have
-been named on the command line (implicitly or explicitly), it might be
-excluded by the use of the `--exclude=PATTERN' option, or some other
-reason.
-
- If `--block-number' (`-R') is used, `tar' prints, along with every
-message it would normally produce, the block number within the archive
-where the message was triggered. Also, supplementary messages are
-triggered when reading blocks full of NULs, or when hitting end of file
-on the archive. As of now, if the archive if properly terminated with
-a NUL block, the reading of the file may stop before end of file is
-met, so the position of end of file will not usually show when
-`--block-number' (`-R') is used. Note that GNU `tar' drains the
-archive before exiting when reading the archive from a pipe.
-
- This option is especially useful when reading damaged archives, since
-it helps pinpoint the damaged sections. It can also be used with
-`--list' (`-t') when listing a file-system backup tape, allowing you to
-choose among several backup tapes when retrieving a file later, in
-favor of the tape where the file appears earliest (closest to the front
-of the tape). *Note backup::.
-
- ---------- Footnotes ----------
-
- (1) This is actually a shortcut for `--checkpoint=N
---checkpoint-action=dot'. *Note dot: checkpoints.
-
-\1f
-File: tar.info, Node: checkpoints, Next: interactive, Prev: verbose, Up: tar invocation
-
-3.8 Checkpoints
-===============
-
-A "checkpoint" is a moment of time before writing Nth record to the
-archive (a "write checkpoint"), or before reading Nth record from the
-archive (a "read checkpoint"). Checkpoints allow to periodically
-execute arbitrary actions.
-
- The checkpoint facility is enabled using the following option:
-
-`--checkpoint[=N]'
- Schedule checkpoints before writing or reading each Nth record.
- The default value for N is 10.
-
- A list of arbitrary "actions" can be executed at each checkpoint.
-These actions include: pausing, displaying textual messages, and
-executing arbitrary external programs. Actions are defined using the
-`--checkpoint-action' option.
-
-`--checkpoint-action=ACTION'
- Execute an ACTION at each checkpoint.
-
- The simplest value of ACTION is `echo'. It instructs `tar' to
-display the default message on the standard error stream upon arriving
-at each checkpoint. The default message is (in POSIX locale) `Write
-checkpoint N', for write checkpoints, and `Read checkpoint N', for read
-checkpoints. Here, N represents ordinal number of the checkpoint.
-
- In another locales, translated versions of this message are used.
-
- This is the default action, so running:
-
- $ tar -c --checkpoint=1000 --checkpoint-action=echo /var
-
-is equivalent to:
-
- $ tar -c --checkpoint=1000 /var
-
- The `echo' action also allows to supply a customized message. You
-do so by placing an equals sign and the message right after it, e.g.:
-
- --checkpoint-action="echo=Hit %s checkpoint #%u"
-
- The `%s' and `%u' in the above example are "meta-characters". The
-`%s' meta-character is replaced with the "type" of the checkpoint:
-`write' or `read' (or a corresponding translated version in locales
-other than POSIX). The `%u' meta-character is replaced with the
-ordinal number of the checkpoint. Thus, the above example could
-produce the following output when used with the `--create' option:
-
- tar: Hit write checkpoint #10
- tar: Hit write checkpoint #20
- tar: Hit write checkpoint #30
-
- Aside from meta-character expansion, the message string is subject to
-"unquoting", during which the backslash "escape sequences" are replaced
-with their corresponding ASCII characters (*note escape sequences::).
-E.g. the following action will produce an audible bell and the message
-described above at each checkpoint:
-
- --checkpoint-action='echo=\aHit %s checkpoint #%u'
-
- There is also a special action which produces an audible signal:
-`bell'. It is not equivalent to `echo='\a'', because `bell' sends the
-bell directly to the console (`/dev/tty'), whereas `echo='\a'' sends it
-to the standard error.
-
- The `ttyout=STRING' action outputs STRING to `/dev/tty', so it can
-be used even if the standard output is redirected elsewhere. The
-STRING is subject to the same modifications as with `echo' action. In
-contrast to the latter, `ttyout' does not prepend `tar' executable name
-to the string, nor does it output a newline after it. For example, the
-following action will print the checkpoint message at the same screen
-line, overwriting any previous message:
-
- --checkpoint-action="ttyout=\rHit %s checkpoint #%u"
-
- Another available checkpoint action is `dot' (or `.'). It instructs
-`tar' to print a single dot on the standard listing stream, e.g.:
-
- $ tar -c --checkpoint=1000 --checkpoint-action=dot /var
- ...
-
- For compatibility with previous GNU `tar' versions, this action can
-be abbreviated by placing a dot in front of the checkpoint frequency,
-as shown in the previous section.
-
- Yet another action, `sleep', pauses `tar' for a specified amount of
-seconds. The following example will stop for 30 seconds at each
-checkpoint:
-
- $ tar -c --checkpoint=1000 --checkpoint-action=sleep=30
-
- Finally, the `exec' action executes a given external program. For
-example:
-
- $ tar -c --checkpoint=1000 --checkpoint-action=exec=/sbin/cpoint
-
- This program is executed using `/bin/sh -c', with no additional
-arguments. Its exit code is ignored. It gets a copy of `tar''s
-environment plus the following variables:
-
-`TAR_VERSION'
- GNU `tar' version number.
-
-`TAR_ARCHIVE'
- The name of the archive `tar' is processing.
-
-`TAR_BLOCKING_FACTOR'
- Current blocking factor (*note Blocking::.
-
-`TAR_CHECKPOINT'
- The checkpoint number.
-
-`TAR_SUBCOMMAND'
- A short option describing the operation `tar' is executing *Note
- Operations::, for a complete list of subcommand options.
-
-`TAR_FORMAT'
- Format of the archive being processed. *Note Formats::, for a
- complete list of archive format names.
-
- Any number of actions can be defined, by supplying several
-`--checkpoint-action' options in the command line. For example, the
-command below displays two messages, pauses execution for 30 seconds
-and executes the `/sbin/cpoint' script:
-
- $ tar -c -f arc.tar \
- --checkpoint-action='\aecho=Hit %s checkpoint #%u' \
- --checkpoint-action='echo=Sleeping for 30 seconds' \
- --checkpoint-action='sleep=30' \
- --checkpoint-action='exec=/sbin/cpoint'
-
- This example also illustrates the fact that `--checkpoint-action'
-can be used without `--checkpoint'. In this case, the default
-checkpoint frequency (at each 10th record) is assumed.
-
-\1f
-File: tar.info, Node: interactive, Prev: checkpoints, Up: tar invocation
-
-3.9 Asking for Confirmation During Operations
-=============================================
-
-Typically, `tar' carries out a command without stopping for further
-instructions. In some situations however, you may want to exclude some
-files and archive members from the operation (for instance if disk or
-storage space is tight). You can do this by excluding certain files
-automatically (*note Choosing::), or by performing an operation
-interactively, using the `--interactive' (`-w') option. `tar' also
-accepts `--confirmation' for this option.
-
- When the `--interactive' (`-w') option is specified, before reading,
-writing, or deleting files, `tar' first prints a message for each such
-file, telling what operation it intends to take, then asks for
-confirmation on the terminal. The actions which require confirmation
-include adding a file to the archive, extracting a file from the
-archive, deleting a file from the archive, and deleting a file from
-disk. To confirm the action, you must type a line of input beginning
-with `y'. If your input line begins with anything other than `y',
-`tar' skips that file.
-
- If `tar' is reading the archive from the standard input, `tar' opens
-the file `/dev/tty' to support the interactive communications.
-
- Verbose output is normally sent to standard output, separate from
-other error messages. However, if the archive is produced directly on
-standard output, then verbose output is mixed with errors on `stderr'.
-Producing the archive on standard output may be used as a way to avoid
-using disk space, when the archive is soon to be consumed by another
-process reading it, say. Some people felt the need of producing an
-archive on stdout, still willing to segregate between verbose output
-and error output. A possible approach would be using a named pipe to
-receive the archive, and having the consumer process to read from that
-named pipe. This has the advantage of letting standard output free to
-receive verbose output, all separate from errors.
-
-\1f
-File: tar.info, Node: operations, Next: Backups, Prev: tar invocation, Up: Top
-
-4 GNU `tar' Operations
-**********************
-
-* Menu:
-
-* Basic tar::
-* Advanced tar::
-* create options::
-* extract options::
-* backup::
-* Applications::
-* looking ahead::
-
-\1f
-File: tar.info, Node: Basic tar, Next: Advanced tar, Up: operations
-
-4.1 Basic GNU `tar' Operations
-==============================
-
-The basic `tar' operations, `--create' (`-c'), `--list' (`-t') and
-`--extract' (`--get', `-x'), are currently presented and described in
-the tutorial chapter of this manual. This section provides some
-complementary notes for these operations.
-
-`--create'
-`-c'
- Creating an empty archive would have some kind of elegance. One
- can initialize an empty archive and later use `--append' (`-r')
- for adding all members. Some applications would not welcome
- making an exception in the way of adding the first archive member.
- On the other hand, many people reported that it is dangerously
- too easy for `tar' to destroy a magnetic tape with an empty
- archive(1). The two most common errors are:
-
- 1. Mistakingly using `create' instead of `extract', when the
- intent was to extract the full contents of an archive. This
- error is likely: keys `c' and `x' are right next to each
- other on the QWERTY keyboard. Instead of being unpacked, the
- archive then gets wholly destroyed. When users speak about
- "exploding" an archive, they usually mean something else :-).
-
- 2. Forgetting the argument to `file', when the intent was to
- create an archive with a single file in it. This error is
- likely because a tired user can easily add the `f' key to the
- cluster of option letters, by the mere force of habit,
- without realizing the full consequence of doing so. The
- usual consequence is that the single file, which was meant to
- be saved, is rather destroyed.
-
- So, recognizing the likelihood and the catastrophic nature of these
- errors, GNU `tar' now takes some distance from elegance, and
- cowardly refuses to create an archive when `--create' option is
- given, there are no arguments besides options, and `--files-from'
- (`-T') option is _not_ used. To get around the cautiousness of
- GNU `tar' and nevertheless create an archive with nothing in it,
- one may still use, as the value for the `--files-from' option, a
- file with no names in it, as shown in the following commands:
-
- tar --create --file=empty-archive.tar --files-from=/dev/null
- tar cfT empty-archive.tar /dev/null
-
-`--extract'
-`--get'
-`-x'
- A socket is stored, within a GNU `tar' archive, as a pipe.
-
-``--list' (`-t')'
- GNU `tar' now shows dates as `1996-08-30', while it used to show
- them as `Aug 30 1996'. Preferably, people should get used to ISO
- 8601 dates. Local American dates should be made available again
- with full date localization support, once ready. In the meantime,
- programs not being localizable for dates should prefer
- international dates, that's really the way to go.
-
- Look up `http://www.cl.cam.ac.uk/~mgk25/iso-time.html' if you are
- curious, it contains a detailed explanation of the ISO 8601
- standard.
-
-
- ---------- Footnotes ----------
-
- (1) This is well described in `Unix-haters Handbook', by Simson
-Garfinkel, Daniel Weise & Steven Strassmann, IDG Books, ISBN
-1-56884-203-1.
-
-\1f
-File: tar.info, Node: Advanced tar, Next: create options, Prev: Basic tar, Up: operations
-
-4.2 Advanced GNU `tar' Operations
-=================================
-
-Now that you have learned the basics of using GNU `tar', you may want
-to learn about further ways in which `tar' can help you.
-
- This chapter presents five, more advanced operations which you
-probably won't use on a daily basis, but which serve more specialized
-functions. We also explain the different styles of options and why you
-might want to use one or another, or a combination of them in your `tar'
-commands. Additionally, this chapter includes options which allow you
-to define the output from `tar' more carefully, and provide help and
-error correction in special circumstances.
-
-* Menu:
-
-* Operations::
-* append::
-* update::
-* concatenate::
-* delete::
-* compare::
-
-\1f
-File: tar.info, Node: Operations, Next: append, Up: Advanced tar
-
-4.2.1 The Five Advanced `tar' Operations
-----------------------------------------
-
- _(This message will disappear, once this node revised.)_
-
-In the last chapter, you learned about the first three operations to
-`tar'. This chapter presents the remaining five operations to `tar':
-`--append', `--update', `--concatenate', `--delete', and `--compare'.
-
- You are not likely to use these operations as frequently as those
-covered in the last chapter; however, since they perform specialized
-functions, they are quite useful when you do need to use them. We will
-give examples using the same directory and files that you created in
-the last chapter. As you may recall, the directory is called
-`practice', the files are `jazz', `blues', `folk', `rock', and the two
-archive files you created are `collection.tar' and `music.tar'.
-
- We will also use the archive files `afiles.tar' and `bfiles.tar'.
-The archive `afiles.tar' contains the members `apple', `angst', and
-`aspic'; `bfiles.tar' contains the members `./birds', `baboon', and
-`./box'.
-
- Unless we state otherwise, all practicing you do and examples you
-follow in this chapter will take place in the `practice' directory that
-you created in the previous chapter; see *note prepare for examples::.
-(Below in this section, we will remind you of the state of the examples
-where the last chapter left them.)
-
- The five operations that we will cover in this chapter are:
-
-`--append'
-`-r'
- Add new entries to an archive that already exists.
-
-`--update'
-`-r'
- Add more recent copies of archive members to the end of an
- archive, if they exist.
-
-`--concatenate'
-`--catenate'
-`-A'
- Add one or more pre-existing archives to the end of another
- archive.
-
-`--delete'
- Delete items from an archive (does not work on tapes).
-
-`--compare'
-`--diff'
-`-d'
- Compare archive members to their counterparts in the file system.
-
-\1f
-File: tar.info, Node: append, Next: update, Prev: Operations, Up: Advanced tar
-
-4.2.2 How to Add Files to Existing Archives: `--append'
--------------------------------------------------------
-
- _(This message will disappear, once this node revised.)_
-
-If you want to add files to an existing archive, you don't need to
-create a new archive; you can use `--append' (`-r'). The archive must
-already exist in order to use `--append'. (A related operation is the
-`--update' operation; you can use this to add newer versions of archive
-members to an existing archive. To learn how to do this with
-`--update', *note update::.)
-
- If you use `--append' to add a file that has the same name as an
-archive member to an archive containing that archive member, then the
-old member is not deleted. What does happen, however, is somewhat
-complex. `tar' _allows_ you to have infinite number of files with the
-same name. Some operations treat these same-named members no
-differently than any other set of archive members: for example, if you
-view an archive with `--list' (`-t'), you will see all of those members
-listed, with their data modification times, owners, etc.
-
- Other operations don't deal with these members as perfectly as you
-might prefer; if you were to use `--extract' to extract the archive,
-only the most recently added copy of a member with the same name as four
-other members would end up in the working directory. This is because
-`--extract' extracts an archive in the order the members appeared in
-the archive; the most recently archived members will be extracted last.
-Additionally, an extracted member will _replace_ a file of the same
-name which existed in the directory already, and `tar' will not prompt
-you about this(1). Thus, only the most recently archived member will
-end up being extracted, as it will replace the one extracted before it,
-and so on.
-
- There exists a special option that allows you to get around this
-behavior and extract (or list) only a particular copy of the file.
-This is `--occurrence' option. If you run `tar' with this option, it
-will extract only the first copy of the file. You may also give this
-option an argument specifying the number of copy to be extracted.
-Thus, for example if the archive `archive.tar' contained three copies
-of file `myfile', then the command
-
- tar --extract --file archive.tar --occurrence=2 myfile
-
-would extract only the second copy. *Note --occurrence: Option
-Summary, for the description of `--occurrence' option.
-
- If you want to replace an archive member, use `--delete' to delete
-the member you want to remove from the archive, , and then use
-`--append' to add the member you want to be in the archive. Note that
-you can not change the order of the archive; the most recently added
-member will still appear last. In this sense, you cannot truly
-"replace" one member with another. (Replacing one member with another
-will not work on certain types of media, such as tapes; see *note
-delete:: and *note Media::, for more information.)
-
-* Menu:
-
-* appending files:: Appending Files to an Archive
-* multiple::
-
- ---------- Footnotes ----------
-
- (1) Unless you give it `--keep-old-files' option, or the disk copy
-is newer than the the one in the archive and you invoke `tar' with
-`--keep-newer-files' option
-
-\1f
-File: tar.info, Node: appending files, Next: multiple, Up: append
-
-4.2.2.1 Appending Files to an Archive
-.....................................
-
- _(This message will disappear, once this node revised.)_
-
-The simplest way to add a file to an already existing archive is the
-`--append' (`-r') operation, which writes specified files into the
-archive whether or not they are already among the archived files.
-
- When you use `--append', you _must_ specify file name arguments, as
-there is no default. If you specify a file that already exists in the
-archive, another copy of the file will be added to the end of the
-archive. As with other operations, the member names of the newly added
-files will be exactly the same as their names given on the command
-line. The `--verbose' (`-v') option will print out the names of the
-files as they are written into the archive.
-
- `--append' cannot be performed on some tape drives, unfortunately,
-due to deficiencies in the formats those tape drives use. The archive
-must be a valid `tar' archive, or else the results of using this
-operation will be unpredictable. *Note Media::.
-
- To demonstrate using `--append' to add a file to an archive, create
-a file called `rock' in the `practice' directory. Make sure you are in
-the `practice' directory. Then, run the following `tar' command to add
-`rock' to `collection.tar':
-
- $ tar --append --file=collection.tar rock
-
-If you now use the `--list' (`-t') operation, you will see that `rock'
-has been added to the archive:
-
- $ tar --list --file=collection.tar
- -rw-r--r-- me user 28 1996-10-18 16:31 jazz
- -rw-r--r-- me user 21 1996-09-23 16:44 blues
- -rw-r--r-- me user 20 1996-09-23 16:44 folk
- -rw-r--r-- me user 20 1996-09-23 16:44 rock
-
-\1f
-File: tar.info, Node: multiple, Prev: appending files, Up: append
-
-4.2.2.2 Multiple Members with the Same Name
-...........................................
-
-You can use `--append' (`-r') to add copies of files which have been
-updated since the archive was created. (However, we do not recommend
-doing this since there is another `tar' option called `--update'; *Note
-update::, for more information. We describe this use of `--append'
-here for the sake of completeness.) When you extract the archive, the
-older version will be effectively lost. This works because files are
-extracted from an archive in the order in which they were archived.
-Thus, when the archive is extracted, a file archived later in time will
-replace a file of the same name which was archived earlier, even though
-the older version of the file will remain in the archive unless you
-delete all versions of the file.
-
- Supposing you change the file `blues' and then append the changed
-version to `collection.tar'. As you saw above, the original `blues' is
-in the archive `collection.tar'. If you change the file and append the
-new version of the file to the archive, there will be two copies in the
-archive. When you extract the archive, the older version of the file
-will be extracted first, and then replaced by the newer version when it
-is extracted.
-
- You can append the new, changed copy of the file `blues' to the
-archive in this way:
-
- $ tar --append --verbose --file=collection.tar blues
- blues
-
-Because you specified the `--verbose' option, `tar' has printed the
-name of the file being appended as it was acted on. Now list the
-contents of the archive:
-
- $ tar --list --verbose --file=collection.tar
- -rw-r--r-- me user 28 1996-10-18 16:31 jazz
- -rw-r--r-- me user 21 1996-09-23 16:44 blues
- -rw-r--r-- me user 20 1996-09-23 16:44 folk
- -rw-r--r-- me user 20 1996-09-23 16:44 rock
- -rw-r--r-- me user 58 1996-10-24 18:30 blues
-
-The newest version of `blues' is now at the end of the archive (note
-the different creation dates and file sizes). If you extract the
-archive, the older version of the file `blues' will be replaced by the
-newer version. You can confirm this by extracting the archive and
-running `ls' on the directory.
-
- If you wish to extract the first occurrence of the file `blues' from
-the archive, use `--occurrence' option, as shown in the following
-example:
-
- $ tar --extract -vv --occurrence --file=collection.tar blues
- -rw-r--r-- me user 21 1996-09-23 16:44 blues
-
- *Note Writing::, for more information on `--extract' and *Note
--occurrence: Option Summary, for the description of `--occurrence'
-option.
-
-\1f
-File: tar.info, Node: update, Next: concatenate, Prev: append, Up: Advanced tar
-
-4.2.3 Updating an Archive
--------------------------
-
- _(This message will disappear, once this node revised.)_
-
-In the previous section, you learned how to use `--append' to add a
-file to an existing archive. A related operation is `--update' (`-u').
-The `--update' operation updates a `tar' archive by comparing the date
-of the specified archive members against the date of the file with the
-same name. If the file has been modified more recently than the
-archive member, then the newer version of the file is added to the
-archive (as with `--append').
-
- Unfortunately, you cannot use `--update' with magnetic tape drives.
-The operation will fail.
-
- Both `--update' and `--append' work by adding to the end of the
-archive. When you extract a file from the archive, only the version
-stored last will wind up in the file system, unless you use the
-`--backup' option. *Note multiple::, for a detailed discussion.
-
-* Menu:
-
-* how to update::
-
-\1f
-File: tar.info, Node: how to update, Up: update
-
-4.2.3.1 How to Update an Archive Using `--update'
-.................................................
-
-You must use file name arguments with the `--update' (`-u') operation.
-If you don't specify any files, `tar' won't act on any files and won't
-tell you that it didn't do anything (which may end up confusing you).
-
- To see the `--update' option at work, create a new file,
-`classical', in your practice directory, and some extra text to the
-file `blues', using any text editor. Then invoke `tar' with the
-`update' operation and the `--verbose' (`-v') option specified, using
-the names of all the files in the practice directory as file name
-arguments:
-
- $ tar --update -v -f collection.tar blues folk rock classical
- blues
- classical
- $
-
-Because we have specified verbose mode, `tar' prints out the names of
-the files it is working on, which in this case are the names of the
-files that needed to be updated. If you run `tar --list' and look at
-the archive, you will see `blues' and `classical' at its end. There
-will be a total of two versions of the member `blues'; the one at the
-end will be newer and larger, since you added text before updating it.
-
- (The reason `tar' does not overwrite the older file when updating it
-is because writing to the middle of a section of tape is a difficult
-process. Tapes are not designed to go backward. *Note Media::, for
-more information about tapes.
-
- `--update' (`-u') is not suitable for performing backups for two
-reasons: it does not change directory content entries, and it lengthens
-the archive every time it is used. The GNU `tar' options intended
-specifically for backups are more efficient. If you need to run
-backups, please consult *note Backups::.
-
-\1f
-File: tar.info, Node: concatenate, Next: delete, Prev: update, Up: Advanced tar
-
-4.2.4 Combining Archives with `--concatenate'
----------------------------------------------
-
-Sometimes it may be convenient to add a second archive onto the end of
-an archive rather than adding individual files to the archive. To add
-one or more archives to the end of another archive, you should use the
-`--concatenate' (`--catenate', `-A') operation.
-
- To use `--concatenate', give the first archive with `--file' option
-and name the rest of archives to be concatenated on the command line.
-The members, and their member names, will be copied verbatim from those
-archives to the first one. (1) The new, concatenated archive will be
-called by the same name as the one given with the `--file' option. As
-usual, if you omit `--file', `tar' will use the value of the environment
-variable `TAPE', or, if this has not been set, the default archive name.
-
- To demonstrate how `--concatenate' works, create two small archives
-called `bluesrock.tar' and `folkjazz.tar', using the relevant files
-from `practice':
-
- $ tar -cvf bluesrock.tar blues rock
- blues
- rock
- $ tar -cvf folkjazz.tar folk jazz
- folk
- jazz
-
-If you like, You can run `tar --list' to make sure the archives contain
-what they are supposed to:
-
- $ tar -tvf bluesrock.tar
- -rw-r--r-- melissa user 105 1997-01-21 19:42 blues
- -rw-r--r-- melissa user 33 1997-01-20 15:34 rock
- $ tar -tvf jazzfolk.tar
- -rw-r--r-- melissa user 20 1996-09-23 16:44 folk
- -rw-r--r-- melissa user 65 1997-01-30 14:15 jazz
-
- We can concatenate these two archives with `tar':
-
- $ cd ..
- $ tar --concatenate --file=bluesrock.tar jazzfolk.tar
-
- If you now list the contents of the `bluesrock.tar', you will see
-that now it also contains the archive members of `jazzfolk.tar':
-
- $ tar --list --file=bluesrock.tar
- blues
- rock
- folk
- jazz
-
- When you use `--concatenate', the source and target archives must
-already exist and must have been created using compatible format
-parameters. Notice, that `tar' does not check whether the archives it
-concatenates have compatible formats, it does not even check if the
-files are really tar archives.
-
- Like `--append' (`-r'), this operation cannot be performed on some
-tape drives, due to deficiencies in the formats those tape drives use.
-
- It may seem more intuitive to you to want or try to use `cat' to
-concatenate two archives instead of using the `--concatenate'
-operation; after all, `cat' is the utility for combining files.
-
- However, `tar' archives incorporate an end-of-file marker which must
-be removed if the concatenated archives are to be read properly as one
-archive. `--concatenate' removes the end-of-archive marker from the
-target archive before each new archive is appended. If you use `cat'
-to combine the archives, the result will not be a valid `tar' format
-archive. If you need to retrieve files from an archive that was added
-to using the `cat' utility, use the `--ignore-zeros' (`-i') option.
-*Note Ignore Zeros::, for further information on dealing with archives
-improperly combined using the `cat' shell utility.
-
- ---------- Footnotes ----------
-
- (1) This can cause multiple members to have the same name, for
-information on how this affects reading the archive, *note multiple::.
-
-\1f
-File: tar.info, Node: delete, Next: compare, Prev: concatenate, Up: Advanced tar
-
-4.2.5 Removing Archive Members Using `--delete'
------------------------------------------------
-
- _(This message will disappear, once this node revised.)_
-
-You can remove members from an archive by using the `--delete' option.
-Specify the name of the archive with `--file' (`-f') and then specify
-the names of the members to be deleted; if you list no member names,
-nothing will be deleted. The `--verbose' option will cause `tar' to
-print the names of the members as they are deleted. As with
-`--extract', you must give the exact member names when using `tar
---delete'. `--delete' will remove all versions of the named file from
-the archive. The `--delete' operation can run very slowly.
-
- Unlike other operations, `--delete' has no short form.
-
- This operation will rewrite the archive. You can only use
-`--delete' on an archive if the archive device allows you to write to
-any point on the media, such as a disk; because of this, it does not
-work on magnetic tapes. Do not try to delete an archive member from a
-magnetic tape; the action will not succeed, and you will be likely to
-scramble the archive and damage your tape. There is no safe way
-(except by completely re-writing the archive) to delete files from most
-kinds of magnetic tape. *Note Media::.
-
- To delete all versions of the file `blues' from the archive
-`collection.tar' in the `practice' directory, make sure you are in that
-directory, and then,
-
- $ tar --list --file=collection.tar
- blues
- folk
- jazz
- rock
- $ tar --delete --file=collection.tar blues
- $ tar --list --file=collection.tar
- folk
- jazz
- rock
- $
-
- The `--delete' option has been reported to work properly when `tar'
-acts as a filter from `stdin' to `stdout'.
-
-\1f
-File: tar.info, Node: compare, Prev: delete, Up: Advanced tar
-
-4.2.6 Comparing Archive Members with the File System
-----------------------------------------------------
-
- _(This message will disappear, once this node revised.)_
-
-The `--compare' (`-d'), or `--diff' operation compares specified
-archive members against files with the same names, and then reports
-differences in file size, mode, owner, modification date and contents.
-You should _only_ specify archive member names, not file names. If you
-do not name any members, then `tar' will compare the entire archive.
-If a file is represented in the archive but does not exist in the file
-system, `tar' reports a difference.
-
- You have to specify the record size of the archive when modifying an
-archive with a non-default record size.
-
- `tar' ignores files in the file system that do not have
-corresponding members in the archive.
-
- The following example compares the archive members `rock', `blues'
-and `funk' in the archive `bluesrock.tar' with files of the same name
-in the file system. (Note that there is no file, `funk'; `tar' will
-report an error message.)
-
- $ tar --compare --file=bluesrock.tar rock blues funk
- rock
- blues
- tar: funk not found in archive
-
- The spirit behind the `--compare' (`--diff', `-d') option is to
-check whether the archive represents the current state of files on
-disk, more than validating the integrity of the archive media. For
-this later goal, *Note verify::.
-
-\1f
-File: tar.info, Node: create options, Next: extract options, Prev: Advanced tar, Up: operations
-
-4.3 Options Used by `--create'
-==============================
-
-The previous chapter described the basics of how to use `--create'
-(`-c') to create an archive from a set of files. *Note create::. This
-section described advanced options to be used with `--create'.
-
-* Menu:
-
-* override:: Overriding File Metadata.
-* Ignore Failed Read::
-
-\1f
-File: tar.info, Node: override, Next: Ignore Failed Read, Up: create options
-
-4.3.1 Overriding File Metadata
-------------------------------
-
-As described above, a `tar' archive keeps, for each member it contains,
-its "metadata", such as modification time, mode and ownership of the
-file. GNU `tar' allows to replace these data with other values when
-adding files to the archive. The options described in this section
-affect creation of archives of any type. For POSIX archives, see also
-*note PAX keywords::, for additional ways of controlling metadata,
-stored in the archive.
-
-`--mode=PERMISSIONS'
- When adding files to an archive, `tar' will use PERMISSIONS for
- the archive members, rather than the permissions from the files.
- PERMISSIONS can be specified either as an octal number or as
- symbolic permissions, like with `chmod' (*Note Permissions:
- (fileutils)File permissions. This reference also has useful
- information for those not being overly familiar with the UNIX
- permission system). Using latter syntax allows for more
- flexibility. For example, the value `a+rw' adds read and write
- permissions for everybody, while retaining executable bits on
- directories or on any other file already marked as executable:
-
- $ tar -c -f archive.tar --mode='a+rw' .
-
-`--mtime=DATE'
- When adding files to an archive, `tar' will use DATE as the
- modification time of members when creating archives, instead of
- their actual modification times. The argument DATE can be either
- a textual date representation in almost arbitrary format (*note
- Date input formats::) or a name of the existing file, starting
- with `/' or `.'. In the latter case, the modification time of
- that file will be used.
-
- The following example will set the modification date to 00:00:00
- UTC, January 1, 1970:
-
- $ tar -c -f archive.tar --mtime='1970-01-01' .
-
- When used with `--verbose' (*note verbose tutorial::) GNU `tar'
- will try to convert the specified date back to its textual
- representation and compare it with the one given with `--mtime'
- options. If the two dates differ, `tar' will print a warning
- saying what date it will use. This is to help user ensure he is
- using the right date.
-
- For example:
-
- $ tar -c -f archive.tar -v --mtime=yesterday .
- tar: Option --mtime: Treating date `yesterday' as 2006-06-20
- 13:06:29.152478
- ...
-
-`--owner=USER'
- Specifies that `tar' should use USER as the owner of members when
- creating archives, instead of the user associated with the source
- file. The argument USER can be either an existing user symbolic
- name, or a decimal numeric user ID.
-
- There is no value indicating a missing number, and `0' usually
- means `root'. Some people like to force `0' as the value to offer
- in their distributions for the owner of files, because the `root'
- user is anonymous anyway, so that might as well be the owner of
- anonymous archives. For example:
-
- $ tar -c -f archive.tar --owner=0 .
- # Or:
- $ tar -c -f archive.tar --owner=root .
-
-`--group=GROUP'
- Files added to the `tar' archive will have a group ID of GROUP,
- rather than the group from the source file. The argument GROUP
- can be either an existing group symbolic name, or a decimal
- numeric group ID.
-
-\1f
-File: tar.info, Node: Ignore Failed Read, Prev: override, Up: create options
-
-4.3.2 Ignore Fail Read
-----------------------
-
-`--ignore-failed-read'
- Do not exit with nonzero on unreadable files or directories.
-
-\1f
-File: tar.info, Node: extract options, Next: backup, Prev: create options, Up: operations
-
-4.4 Options Used by `--extract'
-===============================
-
- _(This message will disappear, once this node revised.)_
-
-The previous chapter showed how to use `--extract' to extract an
-archive into the file system. Various options cause `tar' to extract
-more information than just file contents, such as the owner, the
-permissions, the modification date, and so forth. This section
-presents options to be used with `--extract' when certain special
-considerations arise. You may review the information presented in
-*note extract:: for more basic information about the `--extract'
-operation.
-
-* Menu:
-
-* Reading:: Options to Help Read Archives
-* Writing:: Changing How `tar' Writes Files
-* Scarce:: Coping with Scarce Resources
-
-\1f
-File: tar.info, Node: Reading, Next: Writing, Up: extract options
-
-4.4.1 Options to Help Read Archives
------------------------------------
-
- _(This message will disappear, once this node revised.)_
-
-Normally, `tar' will request data in full record increments from an
-archive storage device. If the device cannot return a full record,
-`tar' will report an error. However, some devices do not always return
-full records, or do not require the last record of an archive to be
-padded out to the next record boundary. To keep reading until you
-obtain a full record, or to accept an incomplete record if it contains
-an end-of-archive marker, specify the `--read-full-records' (`-B')
-option in conjunction with the `--extract' or `--list' operations.
-*Note Blocking::.
-
- The `--read-full-records' (`-B') option is turned on by default when
-`tar' reads an archive from standard input, or from a remote machine.
-This is because on BSD Unix systems, attempting to read a pipe returns
-however much happens to be in the pipe, even if it is less than was
-requested. If this option were not enabled, `tar' would fail as soon
-as it read an incomplete record from the pipe.
-
- If you're not sure of the blocking factor of an archive, you can
-read the archive by specifying `--read-full-records' (`-B') and
-`--blocking-factor=512-SIZE' (`-b 512-SIZE'), using a blocking factor
-larger than what the archive uses. This lets you avoid having to
-determine the blocking factor of an archive. *Note Blocking Factor::.
-
-* Menu:
-
-* read full records::
-* Ignore Zeros::
-
-\1f
-File: tar.info, Node: read full records, Next: Ignore Zeros, Up: Reading
-
-Reading Full Records
-....................
-
-`--read-full-records'
-
-`-B'
- Use in conjunction with `--extract' (`--get', `-x') to read an
- archive which contains incomplete records, or one which has a
- blocking factor less than the one specified.
-
-\1f
-File: tar.info, Node: Ignore Zeros, Prev: read full records, Up: Reading
-
-Ignoring Blocks of Zeros
-........................
-
-Normally, `tar' stops reading when it encounters a block of zeros
-between file entries (which usually indicates the end of the archive).
-`--ignore-zeros' (`-i') allows `tar' to completely read an archive
-which contains a block of zeros before the end (i.e., a damaged
-archive, or one that was created by concatenating several archives
-together).
-
- The `--ignore-zeros' (`-i') option is turned off by default because
-many versions of `tar' write garbage after the end-of-archive entry,
-since that part of the media is never supposed to be read. GNU `tar'
-does not write after the end of an archive, but seeks to maintain
-compatibility among archiving utilities.
-
-`--ignore-zeros'
-`-i'
- To ignore blocks of zeros (i.e., end-of-archive entries) which may
- be encountered while reading an archive. Use in conjunction with
- `--extract' or `--list'.
-
-\1f
-File: tar.info, Node: Writing, Next: Scarce, Prev: Reading, Up: extract options
-
-4.4.2 Changing How `tar' Writes Files
--------------------------------------
-
- _(This message will disappear, once this node revised.)_
-
-* Menu:
-
-* Dealing with Old Files::
-* Overwrite Old Files::
-* Keep Old Files::
-* Keep Newer Files::
-* Unlink First::
-* Recursive Unlink::
-* Data Modification Times::
-* Setting Access Permissions::
-* Directory Modification Times and Permissions::
-* Writing to Standard Output::
-* Writing to an External Program::
-* remove files::
-
-\1f
-File: tar.info, Node: Dealing with Old Files, Next: Overwrite Old Files, Up: Writing
-
-Options Controlling the Overwriting of Existing Files
-.....................................................
-
-When extracting files, if `tar' discovers that the extracted file
-already exists, it normally replaces the file by removing it before
-extracting it, to prevent confusion in the presence of hard or symbolic
-links. (If the existing file is a symbolic link, it is removed, not
-followed.) However, if a directory cannot be removed because it is
-nonempty, `tar' normally overwrites its metadata (ownership,
-permission, etc.). The `--overwrite-dir' option enables this default
-behavior. To be more cautious and preserve the metadata of such a
-directory, use the `--no-overwrite-dir' option.
-
- To be even more cautious and prevent existing files from being
-replaced, use the `--keep-old-files' (`-k') option. It causes `tar' to
-refuse to replace or update a file that already exists, i.e., a file
-with the same name as an archive member prevents extraction of that
-archive member. Instead, it reports an error.
-
- To be more aggressive about altering existing files, use the
-`--overwrite' option. It causes `tar' to overwrite existing files and
-to follow existing symbolic links when extracting.
-
- Some people argue that GNU `tar' should not hesitate to overwrite
-files with other files when extracting. When extracting a `tar'
-archive, they expect to see a faithful copy of the state of the file
-system when the archive was created. It is debatable that this would
-always be a proper behavior. For example, suppose one has an archive
-in which `usr/local' is a link to `usr/local2'. Since then, maybe the
-site removed the link and renamed the whole hierarchy from
-`/usr/local2' to `/usr/local'. Such things happen all the time. I
-guess it would not be welcome at all that GNU `tar' removes the whole
-hierarchy just to make room for the link to be reinstated (unless it
-_also_ simultaneously restores the full `/usr/local2', of course!) GNU
-`tar' is indeed able to remove a whole hierarchy to reestablish a
-symbolic link, for example, but _only if_ `--recursive-unlink' is
-specified to allow this behavior. In any case, single files are
-silently removed.
-
- Finally, the `--unlink-first' (`-U') option can improve performance
-in some cases by causing `tar' to remove files unconditionally before
-extracting them.
-
-\1f
-File: tar.info, Node: Overwrite Old Files, Next: Keep Old Files, Prev: Dealing with Old Files, Up: Writing
-
-Overwrite Old Files
-...................
-
-`--overwrite'
- Overwrite existing files and directory metadata when extracting
- files from an archive.
-
- This causes `tar' to write extracted files into the file system
- without regard to the files already on the system; i.e., files
- with the same names as archive members are overwritten when the
- archive is extracted. It also causes `tar' to extract the
- ownership, permissions, and time stamps onto any preexisting files
- or directories. If the name of a corresponding file name is a
- symbolic link, the file pointed to by the symbolic link will be
- overwritten instead of the symbolic link itself (if this is
- possible). Moreover, special devices, empty directories and even
- symbolic links are automatically removed if they are in the way of
- extraction.
-
- Be careful when using the `--overwrite' option, particularly when
- combined with the `--absolute-names' (`-P') option, as this
- combination can change the contents, ownership or permissions of
- any file on your system. Also, many systems do not take kindly to
- overwriting files that are currently being executed.
-
-`--overwrite-dir'
- Overwrite the metadata of directories when extracting files from an
- archive, but remove other files before extracting.
-
-\1f
-File: tar.info, Node: Keep Old Files, Next: Keep Newer Files, Prev: Overwrite Old Files, Up: Writing
-
-Keep Old Files
-..............
-
-`--keep-old-files'
-`-k'
- Do not replace existing files from archive. The
- `--keep-old-files' (`-k') option prevents `tar' from replacing
- existing files with files with the same name from the archive. The
- `--keep-old-files' option is meaningless with `--list' (`-t').
- Prevents `tar' from replacing files in the file system during
- extraction.
-
-\1f
-File: tar.info, Node: Keep Newer Files, Next: Unlink First, Prev: Keep Old Files, Up: Writing
-
-Keep Newer Files
-................
-
-`--keep-newer-files'
- Do not replace existing files that are newer than their archive
- copies. This option is meaningless with `--list' (`-t').
-
-\1f
-File: tar.info, Node: Unlink First, Next: Recursive Unlink, Prev: Keep Newer Files, Up: Writing
-
-Unlink First
-............
-
-`--unlink-first'
-`-U'
- Remove files before extracting over them. This can make `tar' run
- a bit faster if you know in advance that the extracted files all
- need to be removed. Normally this option slows `tar' down
- slightly, so it is disabled by default.
-
-\1f
-File: tar.info, Node: Recursive Unlink, Next: Data Modification Times, Prev: Unlink First, Up: Writing
-
-Recursive Unlink
-................
-
-`--recursive-unlink'
- When this option is specified, try removing files and directory
- hierarchies before extracting over them. _This is a dangerous
- option!_
-
- If you specify the `--recursive-unlink' option, `tar' removes
-_anything_ that keeps you from extracting a file as far as current
-permissions will allow it. This could include removal of the contents
-of a full directory hierarchy.
-
-\1f
-File: tar.info, Node: Data Modification Times, Next: Setting Access Permissions, Prev: Recursive Unlink, Up: Writing
-
-Setting Data Modification Times
-...............................
-
-Normally, `tar' sets the data modification times of extracted files to
-the corresponding times recorded for the files in the archive, but
-limits the permissions of extracted files by the current `umask'
-setting.
-
- To set the data modification times of extracted files to the time
-when the files were extracted, use the `--touch' (`-m') option in
-conjunction with `--extract' (`--get', `-x').
-
-`--touch'
-`-m'
- Sets the data modification time of extracted archive members to
- the time they were extracted, not the time recorded for them in
- the archive. Use in conjunction with `--extract' (`--get', `-x').
-
-\1f
-File: tar.info, Node: Setting Access Permissions, Next: Directory Modification Times and Permissions, Prev: Data Modification Times, Up: Writing
-
-Setting Access Permissions
-..........................
-
-To set the modes (access permissions) of extracted files to those
-recorded for those files in the archive, use `--same-permissions' in
-conjunction with the `--extract' (`--get', `-x') operation.
-
-`--preserve-permissions'
-`--same-permissions'
-`-p'
- Set modes of extracted archive members to those recorded in the
- archive, instead of current umask settings. Use in conjunction
- with `--extract' (`--get', `-x').
-
-\1f
-File: tar.info, Node: Directory Modification Times and Permissions, Next: Writing to Standard Output, Prev: Setting Access Permissions, Up: Writing
-
-Directory Modification Times and Permissions
-............................................
-
-After successfully extracting a file member, GNU `tar' normally
-restores its permissions and modification times, as described in the
-previous sections. This cannot be done for directories, because after
-extracting a directory `tar' will almost certainly extract files into
-that directory and this will cause the directory modification time to
-be updated. Moreover, restoring that directory permissions may not
-permit file creation within it. Thus, restoring directory permissions
-and modification times must be delayed at least until all files have
-been extracted into that directory. GNU `tar' restores directories
-using the following approach.
-
- The extracted directories are created with the mode specified in the
-archive, as modified by the umask of the user, which gives sufficient
-permissions to allow file creation. The meta-information about the
-directory is recorded in the temporary list of directories. When
-preparing to extract next archive member, GNU `tar' checks if the
-directory prefix of this file contains the remembered directory. If it
-does not, the program assumes that all files have been extracted into
-that directory, restores its modification time and permissions and
-removes its entry from the internal list. This approach allows to
-correctly restore directory meta-information in the majority of cases,
-while keeping memory requirements sufficiently small. It is based on
-the fact, that most `tar' archives use the predefined order of members:
-first the directory, then all the files and subdirectories in that
-directory.
-
- However, this is not always true. The most important exception are
-incremental archives (*note Incremental Dumps::). The member order in
-an incremental archive is reversed: first all directory members are
-stored, followed by other (non-directory) members. So, when extracting
-from incremental archives, GNU `tar' alters the above procedure. It
-remembers all restored directories, and restores their meta-data only
-after the entire archive has been processed. Notice, that you do not
-need to specify any special options for that, as GNU `tar'
-automatically detects archives in incremental format.
-
- There may be cases, when such processing is required for normal
-archives too. Consider the following example:
-
- $ tar --no-recursion -cvf archive \
- foo foo/file1 bar bar/file foo/file2
- foo/
- foo/file1
- bar/
- bar/file
- foo/file2
-
- During the normal operation, after encountering `bar' GNU `tar' will
-assume that all files from the directory `foo' were already extracted
-and will therefore restore its timestamp and permission bits. However,
-after extracting `foo/file2' the directory timestamp will be offset
-again.
-
- To correctly restore directory meta-information in such cases, use
-`delay-directory-restore' command line option:
-
-`--delay-directory-restore'
- Delays restoring of the modification times and permissions of
- extracted directories until the end of extraction. This way,
- correct meta-information is restored even if the archive has
- unusual member ordering.
-
-`--no-delay-directory-restore'
- Cancel the effect of the previous `--delay-directory-restore'.
- Use this option if you have used `--delay-directory-restore' in
- `TAR_OPTIONS' variable (*note TAR_OPTIONS::) and wish to
- temporarily disable it.
-
-\1f
-File: tar.info, Node: Writing to Standard Output, Next: Writing to an External Program, Prev: Directory Modification Times and Permissions, Up: Writing
-
-Writing to Standard Output
-..........................
-
-To write the extracted files to the standard output, instead of
-creating the files on the file system, use `--to-stdout' (`-O') in
-conjunction with `--extract' (`--get', `-x'). This option is useful if
-you are extracting files to send them through a pipe, and do not need to
-preserve them in the file system. If you extract multiple members,
-they appear on standard output concatenated, in the order they are
-found in the archive.
-
-`--to-stdout'
-`-O'
- Writes files to the standard output. Use only in conjunction with
- `--extract' (`--get', `-x'). When this option is used, instead of
- creating the files specified, `tar' writes the contents of the
- files extracted to its standard output. This may be useful if you
- are only extracting the files in order to send them through a
- pipe. This option is meaningless with `--list' (`-t').
-
- This can be useful, for example, if you have a tar archive containing
-a big file and don't want to store the file on disk before processing
-it. You can use a command like this:
-
- tar -xOzf foo.tgz bigfile | process
-
- or even like this if you want to process the concatenation of the
-files:
-
- tar -xOzf foo.tgz bigfile1 bigfile2 | process
-
- However, `--to-command' may be more convenient for use with multiple
-files. See the next section.
-
-\1f
-File: tar.info, Node: Writing to an External Program, Next: remove files, Prev: Writing to Standard Output, Up: Writing
-
-Writing to an External Program
-..............................
-
-You can instruct `tar' to send the contents of each extracted file to
-the standard input of an external program:
-
-`--to-command=COMMAND'
- Extract files and pipe their contents to the standard input of
- COMMAND. When this option is used, instead of creating the files
- specified, `tar' invokes COMMAND and pipes the contents of the
- files to its standard output. COMMAND may contain command line
- arguments. The program is executed via `sh -c'. Notice, that
- COMMAND is executed once for each regular file extracted.
- Non-regular files (directories, etc.) are ignored when this option
- is used.
-
- The command can obtain the information about the file it processes
-from the following environment variables:
-
-`TAR_FILETYPE'
- Type of the file. It is a single letter with the following meaning:
-
- f Regular file
- d Directory
- l Symbolic link
- h Hard link
- b Block device
- c Character device
-
- Currently only regular files are supported.
-
-`TAR_MODE'
- File mode, an octal number.
-
-`TAR_FILENAME'
- The name of the file.
-
-`TAR_REALNAME'
- Name of the file as stored in the archive.
-
-`TAR_UNAME'
- Name of the file owner.
-
-`TAR_GNAME'
- Name of the file owner group.
-
-`TAR_ATIME'
- Time of last access. It is a decimal number, representing seconds
- since the epoch. If the archive provides times with nanosecond
- precision, the nanoseconds are appended to the timestamp after a
- decimal point.
-
-`TAR_MTIME'
- Time of last modification.
-
-`TAR_CTIME'
- Time of last status change.
-
-`TAR_SIZE'
- Size of the file.
-
-`TAR_UID'
- UID of the file owner.
-
-`TAR_GID'
- GID of the file owner.
-
- In addition to these variables, `TAR_VERSION' contains the GNU `tar'
-version number.
-
- If COMMAND exits with a non-0 status, `tar' will print an error
-message similar to the following:
-
- tar: 2345: Child returned status 1
-
- Here, `2345' is the PID of the finished process.
-
- If this behavior is not wanted, use `--ignore-command-error':
-
-`--ignore-command-error'
- Ignore exit codes of subprocesses. Notice that if the program
- exits on signal or otherwise terminates abnormally, the error
- message will be printed even if this option is used.
-
-`--no-ignore-command-error'
- Cancel the effect of any previous `--ignore-command-error' option.
- This option is useful if you have set `--ignore-command-error' in
- `TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to temporarily cancel
- it.
-
-\1f
-File: tar.info, Node: remove files, Prev: Writing to an External Program, Up: Writing
-
-Removing Files
-..............
-
-`--remove-files'
- Remove files after adding them to the archive.
-
-\1f
-File: tar.info, Node: Scarce, Prev: Writing, Up: extract options
-
-4.4.3 Coping with Scarce Resources
-----------------------------------
-
- _(This message will disappear, once this node revised.)_
-
-* Menu:
-
-* Starting File::
-* Same Order::
-
-\1f
-File: tar.info, Node: Starting File, Next: Same Order, Up: Scarce
-
-Starting File
-.............
-
-`--starting-file=NAME'
-`-K NAME'
- Starts an operation in the middle of an archive. Use in
- conjunction with `--extract' (`--get', `-x') or `--list' (`-t').
-
- If a previous attempt to extract files failed due to lack of disk
-space, you can use `--starting-file=NAME' (`-K NAME') to start
-extracting only after member NAME of the archive. This assumes, of
-course, that there is now free space, or that you are now extracting
-into a different file system. (You could also choose to suspend `tar',
-remove unnecessary files from the file system, and then restart the
-same `tar' operation. In this case, `--starting-file' is not necessary.
-*Note Incremental Dumps::, *Note interactive::, and *note exclude::.)
-
-\1f
-File: tar.info, Node: Same Order, Prev: Starting File, Up: Scarce
-
-Same Order
-..........
-
-`--same-order'
-`--preserve-order'
-`-s'
- To process large lists of file names on machines with small
- amounts of memory. Use in conjunction with `--compare' (`--diff',
- `-d'), `--list' (`-t') or `--extract' (`--get', `-x').
-
- The `--same-order' (`--preserve-order', `-s') option tells `tar'
-that the list of file names to be listed or extracted is sorted in the
-same order as the files in the archive. This allows a large list of
-names to be used, even on a small machine that would not otherwise be
-able to hold all the names in memory at the same time. Such a sorted
-list can easily be created by running `tar -t' on the archive and
-editing its output.
-
- This option is probably never needed on modern computer systems.
-
-\1f
-File: tar.info, Node: backup, Next: Applications, Prev: extract options, Up: operations
-
-4.5 Backup options
-==================
-
-GNU `tar' offers options for making backups of files before writing new
-versions. These options control the details of these backups. They
-may apply to the archive itself before it is created or rewritten, as
-well as individual extracted members. Other GNU programs (`cp',
-`install', `ln', and `mv', for example) offer similar options.
-
- Backup options may prove unexpectedly useful when extracting archives
-containing many members having identical name, or when extracting
-archives on systems having file name limitations, making different
-members appear has having similar names through the side-effect of name
-truncation. (This is true only if we have a good scheme for truncated
-backup names, which I'm not sure at all: I suspect work is needed in
-this area.) When any existing file is backed up before being
-overwritten by extraction, then clashing files are automatically be
-renamed to be unique, and the true name is kept for only the last file
-of a series of clashing files. By using verbose mode, users may track
-exactly what happens.
-
- At the detail level, some decisions are still experimental, and may
-change in the future, we are waiting comments from our users. So,
-please do not learn to depend blindly on the details of the backup
-features. For example, currently, directories themselves are never
-renamed through using these options, so, extracting a file over a
-directory still has good chances to fail. Also, backup options apply
-to created archives, not only to extracted members. For created
-archives, backups will not be attempted when the archive is a block or
-character device, or when it refers to a remote file.
-
- For the sake of simplicity and efficiency, backups are made by
-renaming old files prior to creation or extraction, and not by copying.
-The original name is restored if the file creation fails. If a
-failure occurs after a partial extraction of a file, both the backup
-and the partially extracted file are kept.
-
-`--backup[=METHOD]'
- Back up files that are about to be overwritten or removed.
- Without this option, the original versions are destroyed.
-
- Use METHOD to determine the type of backups made. If METHOD is
- not specified, use the value of the `VERSION_CONTROL' environment
- variable. And if `VERSION_CONTROL' is not set, use the `existing'
- method.
-
- This option corresponds to the Emacs variable `version-control';
- the same values for METHOD are accepted as in Emacs. This option
- also allows more descriptive names. The valid METHODs are:
-
- `t'
- `numbered'
- Always make numbered backups.
-
- `nil'
- `existing'
- Make numbered backups of files that already have them, simple
- backups of the others.
-
- `never'
- `simple'
- Always make simple backups.
-
-
-`--suffix=SUFFIX'
- Append SUFFIX to each backup file made with `--backup'. If this
- option is not specified, the value of the `SIMPLE_BACKUP_SUFFIX'
- environment variable is used. And if `SIMPLE_BACKUP_SUFFIX' is not
- set, the default is `~', just as in Emacs.
-
-
-\1f
-File: tar.info, Node: Applications, Next: looking ahead, Prev: backup, Up: operations
-
-4.6 Notable `tar' Usages
-========================
-
- _(This message will disappear, once this node revised.)_
-
-You can easily use archive files to transport a group of files from one
-system to another: put all relevant files into an archive on one
-computer system, transfer the archive to another system, and extract
-the contents there. The basic transfer medium might be magnetic tape,
-Internet FTP, or even electronic mail (though you must encode the
-archive with `uuencode' in order to transport it properly by mail).
-Both machines do not have to use the same operating system, as long as
-they both support the `tar' program.
-
- For example, here is how you might copy a directory's contents from
-one disk to another, while preserving the dates, modes, owners and
-link-structure of all the files therein. In this case, the transfer
-medium is a "pipe", which is one a Unix redirection mechanism:
-
- $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)
-
-You can avoid subshells by using `-C' option:
-
- $ tar -C sourcedir -cf - . | tar -C targetdir -xf -
-
-The command also works using short option forms:
-
- $ (cd sourcedir; tar --create --file=- . ) \
- | (cd targetdir; tar --extract --file=-)
- # Or:
- $ tar --directory sourcedir --create --file=- . ) \
- | tar --directory targetdir --extract --file=-
-
-This is one of the easiest methods to transfer a `tar' archive.
-
-\1f
-File: tar.info, Node: looking ahead, Prev: Applications, Up: operations
-
-4.7 Looking Ahead: The Rest of this Manual
-==========================================
-
-You have now seen how to use all eight of the operations available to
-`tar', and a number of the possible options. The next chapter explains
-how to choose and change file and archive names, how to use files to
-store names of other files which you can then call as arguments to
-`tar' (this can help you save time if you expect to archive the same
-list of files a number of times), and so forth.
-
- If there are too many files to conveniently list on the command line,
-you can list the names in a file, and `tar' will read that file. *Note
-files::.
-
- There are various ways of causing `tar' to skip over some files, and
-not archive them. *Note Choosing::.
-
-\1f
-File: tar.info, Node: Backups, Next: Choosing, Prev: operations, Up: Top
-
-5 Performing Backups and Restoring Files
-****************************************
-
- _(This message will disappear, once this node revised.)_
-
-GNU `tar' is distributed along with the scripts which the Free Software
-Foundation uses for performing backups. There is no corresponding
-scripts available yet for doing restoration of files. Even if there is
-a good chance those scripts may be satisfying to you, they are not the
-only scripts or methods available for doing backups and restore. You
-may well create your own, or use more sophisticated packages dedicated
-to that purpose.
-
- Some users are enthusiastic about `Amanda' (The Advanced Maryland
-Automatic Network Disk Archiver), a backup system developed by James da
-Silva `jds@cs.umd.edu' and available on many Unix systems. This is
-free software, and it is available at these places:
-
- http://www.cs.umd.edu/projects/amanda/amanda.html
- ftp://ftp.cs.umd.edu/pub/amanda
-
- This chapter documents both the provided shell scripts and `tar'
-options which are more specific to usage as a backup tool.
-
- To "back up" a file system means to create archives that contain all
-the files in that file system. Those archives can then be used to
-restore any or all of those files (for instance if a disk crashes or a
-file is accidentally deleted). File system "backups" are also called
-"dumps".
-
-* Menu:
-
-* Full Dumps:: Using `tar' to Perform Full Dumps
-* Incremental Dumps:: Using `tar' to Perform Incremental Dumps
-* Backup Levels:: Levels of Backups
-* Backup Parameters:: Setting Parameters for Backups and Restoration
-* Scripted Backups:: Using the Backup Scripts
-* Scripted Restoration:: Using the Restore Script
-
-\1f
-File: tar.info, Node: Full Dumps, Next: Incremental Dumps, Up: Backups
-
-5.1 Using `tar' to Perform Full Dumps
-=====================================
-
- _(This message will disappear, once this node revised.)_
-
-Full dumps should only be made when no other people or programs are
-modifying files in the file system. If files are modified while `tar'
-is making the backup, they may not be stored properly in the archive,
-in which case you won't be able to restore them if you have to. (Files
-not being modified are written with no trouble, and do not corrupt the
-entire archive.)
-
- You will want to use the `--label=ARCHIVE-LABEL' (`-V
-ARCHIVE-LABEL') option to give the archive a volume label, so you can
-tell what this archive is even if the label falls off the tape, or
-anything like that.
-
- Unless the file system you are dumping is guaranteed to fit on one
-volume, you will need to use the `--multi-volume' (`-M') option. Make
-sure you have enough tapes on hand to complete the backup.
-
- If you want to dump each file system separately you will need to use
-the `--one-file-system' option to prevent `tar' from crossing file
-system boundaries when storing (sub)directories.
-
- The `--incremental' (`-G') (*note Incremental Dumps::) option is not
-needed, since this is a complete copy of everything in the file system,
-and a full restore from this backup would only be done onto a completely
-empty disk.
-
- Unless you are in a hurry, and trust the `tar' program (and your
-tapes), it is a good idea to use the `--verify' (`-W') option, to make
-sure your files really made it onto the dump properly. This will also
-detect cases where the file was modified while (or just after) it was
-being archived. Not all media (notably cartridge tapes) are capable of
-being verified, unfortunately.
-
-\1f
-File: tar.info, Node: Incremental Dumps, Next: Backup Levels, Prev: Full Dumps, Up: Backups
-
-5.2 Using `tar' to Perform Incremental Dumps
-============================================
-
-"Incremental backup" is a special form of GNU `tar' archive that stores
-additional metadata so that exact state of the file system can be
-restored when extracting the archive.
-
- GNU `tar' currently offers two options for handling incremental
-backups: `--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') and
-`--incremental' (`-G').
-
- The option `--listed-incremental' instructs tar to operate on an
-incremental archive with additional metadata stored in a standalone
-file, called a "snapshot file". The purpose of this file is to help
-determine which files have been changed, added or deleted since the
-last backup, so that the next incremental backup will contain only
-modified files. The name of the snapshot file is given as an argument
-to the option:
-
-`--listed-incremental=FILE'
-`-g FILE'
- Handle incremental backups with snapshot data in FILE.
-
- To create an incremental backup, you would use
-`--listed-incremental' together with `--create' (*note create::). For
-example:
-
- $ tar --create \
- --file=archive.1.tar \
- --listed-incremental=/var/log/usr.snar \
- /usr
-
- This will create in `archive.1.tar' an incremental backup of the
-`/usr' file system, storing additional metadata in the file
-`/var/log/usr.snar'. If this file does not exist, it will be created.
-The created archive will then be a "level 0 backup"; please see the
-next section for more on backup levels.
-
- Otherwise, if the file `/var/log/usr.snar' exists, it determines
-which files are modified. In this case only these files will be stored
-in the archive. Suppose, for example, that after running the above
-command, you delete file `/usr/doc/old' and create directory
-`/usr/local/db' with the following contents:
-
- $ ls /usr/local/db
- /usr/local/db/data
- /usr/local/db/index
-
- Some time later you create another incremental backup. You will
-then see:
-
- $ tar --create \
- --file=archive.2.tar \
- --listed-incremental=/var/log/usr.snar \
- /usr
- tar: usr/local/db: Directory is new
- usr/local/db/
- usr/local/db/data
- usr/local/db/index
-
-The created archive `archive.2.tar' will contain only these three
-members. This archive is called a "level 1 backup". Notice that
-`/var/log/usr.snar' will be updated with the new data, so if you plan
-to create more `level 1' backups, it is necessary to create a working
-copy of the snapshot file before running `tar'. The above example will
-then be modified as follows:
-
- $ cp /var/log/usr.snar /var/log/usr.snar-1
- $ tar --create \
- --file=archive.2.tar \
- --listed-incremental=/var/log/usr.snar-1 \
- /usr
-
- Incremental dumps depend crucially on time stamps, so the results are
-unreliable if you modify a file's time stamps during dumping (e.g.,
-with the `--atime-preserve=replace' option), or if you set the clock
-backwards.
-
- Metadata stored in snapshot files include device numbers, which,
-obviously are supposed to be a non-volatile values. However, it turns
-out that NFS devices have undependable values when an automounter gets
-in the picture. This can lead to a great deal of spurious redumping in
-incremental dumps, so it is somewhat useless to compare two NFS devices
-numbers over time. The solution implemented currently is to considers
-all NFS devices as being equal when it comes to comparing directories;
-this is fairly gross, but there does not seem to be a better way to go.
-
- Apart from using NFS, there are a number of cases where relying on
-device numbers can cause spurious redumping of unmodified files. For
-example, this occurs when archiving LVM snapshot volumes. To avoid
-this, use `--no-check-device' option:
-
-`--no-check-device'
- Do not rely on device numbers when preparing a list of changed
- files for an incremental dump.
-
-`--check-device'
- Use device numbers when preparing a list of changed files for an
- incremental dump. This is the default behavior. The purpose of
- this option is to undo the effect of the `--no-check-device' if it
- was given in `TAR_OPTIONS' environment variable (*note
- TAR_OPTIONS::).
-
- There is also another way to cope with changing device numbers. It
-is described in detail in *note Fixing Snapshot Files::.
-
- Note that incremental archives use `tar' extensions and may not be
-readable by non-GNU versions of the `tar' program.
-
- To extract from the incremental dumps, use `--listed-incremental'
-together with `--extract' option (*note extracting files::). In this
-case, `tar' does not need to access snapshot file, since all the data
-necessary for extraction are stored in the archive itself. So, when
-extracting, you can give whatever argument to `--listed-incremental',
-the usual practice is to use `--listed-incremental=/dev/null'.
-Alternatively, you can use `--incremental', which needs no arguments.
-In general, `--incremental' (`-G') can be used as a shortcut for
-`--listed-incremental' when listing or extracting incremental backups
-(for more information, regarding this option, *note incremental-op::).
-
- When extracting from the incremental backup GNU `tar' attempts to
-restore the exact state the file system had when the archive was
-created. In particular, it will _delete_ those files in the file
-system that did not exist in their directories when the archive was
-created. If you have created several levels of incremental files, then
-in order to restore the exact contents the file system had when the
-last level was created, you will need to restore from all backups in
-turn. Continuing our example, to restore the state of `/usr' file
-system, one would do(1):
-
- $ tar --extract \
- --listed-incremental=/dev/null \
- --file archive.1.tar
- $ tar --extract \
- --listed-incremental=/dev/null \
- --file archive.2.tar
-
- To list the contents of an incremental archive, use `--list' (*note
-list::), as usual. To obtain more information about the archive, use
-`--listed-incremental' or `--incremental' combined with two `--verbose'
-options(2):
-
- tar --list --incremental --verbose --verbose archive.tar
-
- This command will print, for each directory in the archive, the list
-of files in that directory at the time the archive was created. This
-information is put out in a format which is both human-readable and
-unambiguous for a program: each file name is printed as
-
- X FILE
-
-where X is a letter describing the status of the file: `Y' if the file
-is present in the archive, `N' if the file is not included in the
-archive, or a `D' if the file is a directory (and is included in the
-archive). *Note Dumpdir::, for the detailed description of dumpdirs
-and status codes. Each such line is terminated by a newline character.
-The last line is followed by an additional newline to indicate the end
-of the data.
-
- The option `--incremental' (`-G') gives the same behavior as
-`--listed-incremental' when used with `--list' and `--extract' options.
-When used with `--create' option, it creates an incremental archive
-without creating snapshot file. Thus, it is impossible to create
-several levels of incremental backups with `--incremental' option.
-
- ---------- Footnotes ----------
-
- (1) Notice, that since both archives were created without `-P'
-option (*note absolute::), these commands should be run from the root
-file system.
-
- (2) Two `--verbose' options were selected to avoid breaking usual
-verbose listing output (`--list --verbose') when using in scripts.
-
- Versions of GNU `tar' up to 1.15.1 used to dump verbatim binary
-contents of the DUMPDIR header (with terminating nulls) when
-`--incremental' or `--listed-incremental' option was given, no matter
-what the verbosity level. This behavior, and, especially, the binary
-output it produced were considered inconvenient and were changed in
-version 1.16
-
-\1f
-File: tar.info, Node: Backup Levels, Next: Backup Parameters, Prev: Incremental Dumps, Up: Backups
-
-5.3 Levels of Backups
-=====================
-
-An archive containing all the files in the file system is called a
-"full backup" or "full dump". You could insure your data by creating a
-full dump every day. This strategy, however, would waste a substantial
-amount of archive media and user time, as unchanged files are daily
-re-archived.
-
- It is more efficient to do a full dump only occasionally. To back up
-files between full dumps, you can use "incremental dumps". A "level
-one" dump archives all the files that have changed since the last full
-dump.
-
- A typical dump strategy would be to perform a full dump once a week,
-and a level one dump once a day. This means some versions of files
-will in fact be archived more than once, but this dump strategy makes
-it possible to restore a file system to within one day of accuracy by
-only extracting two archives--the last weekly (full) dump and the last
-daily (level one) dump. The only information lost would be in files
-changed or created since the last daily backup. (Doing dumps more than
-once a day is usually not worth the trouble).
-
- GNU `tar' comes with scripts you can use to do full and level-one
-(actually, even level-two and so on) dumps. Using scripts (shell
-programs) to perform backups and restoration is a convenient and
-reliable alternative to typing out file name lists and `tar' commands
-by hand.
-
- Before you use these scripts, you need to edit the file
-`backup-specs', which specifies parameters used by the backup scripts
-and by the restore script. This file is usually located in
-`/etc/backup' directory. *Note Backup Parameters::, for its detailed
-description. Once the backup parameters are set, you can perform
-backups or restoration by running the appropriate script.
-
- The name of the backup script is `backup'. The name of the restore
-script is `restore'. The following sections describe their use in
-detail.
-
- _Please Note:_ The backup and restoration scripts are designed to be
-used together. While it is possible to restore files by hand from an
-archive which was created using a backup script, and to create an
-archive by hand which could then be extracted using the restore script,
-it is easier to use the scripts. *Note Incremental Dumps::, before
-making such an attempt.
-
-\1f
-File: tar.info, Node: Backup Parameters, Next: Scripted Backups, Prev: Backup Levels, Up: Backups
-
-5.4 Setting Parameters for Backups and Restoration
-==================================================
-
-The file `backup-specs' specifies backup parameters for the backup and
-restoration scripts provided with `tar'. You must edit `backup-specs'
-to fit your system configuration and schedule before using these
-scripts.
-
- Syntactically, `backup-specs' is a shell script, containing mainly
-variable assignments. However, any valid shell construct is allowed in
-this file. Particularly, you may wish to define functions within that
-script (e.g., see `RESTORE_BEGIN' below). For more information about
-shell script syntax, please refer to the definition of the Shell
-Command Language
-(http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
-g_02). See also *note Bash Features: (bashref)Top.
-
- The shell variables controlling behavior of `backup' and `restore'
-are described in the following subsections.
-
-* Menu:
-
-* General-Purpose Variables::
-* Magnetic Tape Control::
-* User Hooks::
-* backup-specs example:: An Example Text of `Backup-specs'
-
-\1f
-File: tar.info, Node: General-Purpose Variables, Next: Magnetic Tape Control, Up: Backup Parameters
-
-5.4.1 General-Purpose Variables
--------------------------------
-
- -- Backup variable: ADMINISTRATOR
- The user name of the backup administrator. `Backup' scripts sends
- a backup report to this address.
-
- -- Backup variable: BACKUP_HOUR
- The hour at which the backups are done. This can be a number from
- 0 to 23, or the time specification in form HOURS:MINUTES, or the
- string `now'.
-
- This variable is used by `backup'. Its value may be overridden
- using `--time' option (*note Scripted Backups::).
-
- -- Backup variable: TAPE_FILE
- The device `tar' writes the archive to. If TAPE_FILE is a remote
- archive (*note remote-dev::), backup script will suppose that your
- `mt' is able to access remote devices. If RSH (*note RSH::) is
- set, `--rsh-command' option will be added to invocations of `mt'.
-
- -- Backup variable: BLOCKING
- The blocking factor `tar' will use when writing the dump archive.
- *Note Blocking Factor::.
-
- -- Backup variable: BACKUP_DIRS
- A list of file systems to be dumped (for `backup'), or restored
- (for `restore'). You can include any directory name in the list
- -- subdirectories on that file system will be included, regardless
- of how they may look to other networked machines. Subdirectories
- on other file systems will be ignored.
-
- The host name specifies which host to run `tar' on, and should
- normally be the host that actually contains the file system.
- However, the host machine must have GNU `tar' installed, and must
- be able to access the directory containing the backup scripts and
- their support files using the same file name that is used on the
- machine where the scripts are run (i.e., what `pwd' will print
- when in that directory on that machine). If the host that contains
- the file system does not have this capability, you can specify
- another host as long as it can access the file system through NFS.
-
- If the list of file systems is very long you may wish to put it in
- a separate file. This file is usually named `/etc/backup/dirs',
- but this name may be overridden in `backup-specs' using `DIRLIST'
- variable.
-
- -- Backup variable: DIRLIST
- The name of the file that contains a list of file systems to backup
- or restore. By default it is `/etc/backup/dirs'.
-
- -- Backup variable: BACKUP_FILES
- A list of individual files to be dumped (for `backup'), or restored
- (for `restore'). These should be accessible from the machine on
- which the backup script is run.
-
- If the list of file systems is very long you may wish to store it
- in a separate file. This file is usually named
- `/etc/backup/files', but this name may be overridden in
- `backup-specs' using `FILELIST' variable.
-
- -- Backup variable: FILELIST
- The name of the file that contains a list of individual files to
- backup or restore. By default it is `/etc/backup/files'.
-
- -- Backup variable: MT
- Full file name of `mt' binary.
-
- -- Backup variable: RSH
- Full file name of `rsh' binary or its equivalent. You may wish to
- set it to `ssh', to improve security. In this case you will have
- to use public key authentication.
-
- -- Backup variable: RSH_COMMAND
- Full file name of `rsh' binary on remote machines. This will be
- passed via `--rsh-command' option to the remote invocation of GNU
- `tar'.
-
- -- Backup variable: VOLNO_FILE
- Name of temporary file to hold volume numbers. This needs to be
- accessible by all the machines which have file systems to be
- dumped.
-
- -- Backup variable: XLIST
- Name of "exclude file list". An "exclude file list" is a file
- located on the remote machine and containing the list of files to
- be excluded from the backup. Exclude file lists are searched in
- /etc/tar-backup directory. A common use for exclude file lists is
- to exclude files containing security-sensitive information (e.g.,
- `/etc/shadow' from backups).
-
- This variable affects only `backup'.
-
- -- Backup variable: SLEEP_TIME
- Time to sleep between dumps of any two successive file systems
-
- This variable affects only `backup'.
-
- -- Backup variable: DUMP_REMIND_SCRIPT
- Script to be run when it's time to insert a new tape in for the
- next volume. Administrators may want to tailor this script for
- their site. If this variable isn't set, GNU `tar' will display
- its built-in prompt, and will expect confirmation from the
- console. For the description of the default prompt, see *note
- change volume prompt::.
-
-
- -- Backup variable: SLEEP_MESSAGE
- Message to display on the terminal while waiting for dump time.
- Usually this will just be some literal text.
-
- -- Backup variable: TAR
- Full file name of the GNU `tar' executable. If this is not set,
- backup scripts will search `tar' in the current shell path.
-
-\1f
-File: tar.info, Node: Magnetic Tape Control, Next: User Hooks, Prev: General-Purpose Variables, Up: Backup Parameters
-
-5.4.2 Magnetic Tape Control
----------------------------
-
-Backup scripts access tape device using special "hook functions".
-These functions take a single argument - the name of the tape device.
-Their names are kept in the following variables:
-
- -- Backup variable: MT_BEGIN
- The name of "begin" function. This function is called before
- accessing the drive. By default it retensions the tape:
-
- MT_BEGIN=mt_begin
-
- mt_begin() {
- mt -f "$1" retension
- }
-
- -- Backup variable: MT_REWIND
- The name of "rewind" function. The default definition is as
- follows:
-
- MT_REWIND=mt_rewind
-
- mt_rewind() {
- mt -f "$1" rewind
- }
-
-
- -- Backup variable: MT_OFFLINE
- The name of the function switching the tape off line. By default
- it is defined as follows:
-
- MT_OFFLINE=mt_offline
-
- mt_offline() {
- mt -f "$1" offl
- }
-
- -- Backup variable: MT_STATUS
- The name of the function used to obtain the status of the archive
- device, including error count. Default definition:
-
- MT_STATUS=mt_status
-
- mt_status() {
- mt -f "$1" status
- }
-
-\1f
-File: tar.info, Node: User Hooks, Next: backup-specs example, Prev: Magnetic Tape Control, Up: Backup Parameters
-
-5.4.3 User Hooks
-----------------
-
-"User hooks" are shell functions executed before and after each `tar'
-invocation. Thus, there are "backup hooks", which are executed before
-and after dumping each file system, and "restore hooks", executed
-before and after restoring a file system. Each user hook is a shell
-function taking four arguments:
-
- -- User Hook Function: hook LEVEL HOST FS FSNAME
- Its arguments are:
-
- LEVEL
- Current backup or restore level.
-
- HOST
- Name or IP address of the host machine being dumped or
- restored.
-
- FS
- Full file name of the file system being dumped or restored.
-
- FSNAME
- File system name with directory separators replaced with
- colons. This is useful, e.g., for creating unique files.
-
- Following variables keep the names of user hook functions
-
- -- Backup variable: DUMP_BEGIN
- Dump begin function. It is executed before dumping the file
- system.
-
- -- Backup variable: DUMP_END
- Executed after dumping the file system.
-
- -- Backup variable: RESTORE_BEGIN
- Executed before restoring the file system.
-
- -- Backup variable: RESTORE_END
- Executed after restoring the file system.
-
-\1f
-File: tar.info, Node: backup-specs example, Prev: User Hooks, Up: Backup Parameters
-
-5.4.4 An Example Text of `Backup-specs'
----------------------------------------
-
-The following is an example of `backup-specs':
-
- # site-specific parameters for file system backup.
-
- ADMINISTRATOR=friedman
- BACKUP_HOUR=1
- TAPE_FILE=/dev/nrsmt0
-
- # Use `ssh' instead of the less secure `rsh'
- RSH=/usr/bin/ssh
- RSH_COMMAND=/usr/bin/ssh
-
- # Override MT_STATUS function:
- my_status() {
- mts -t $TAPE_FILE
- }
- MT_STATUS=my_status
-
- # Disable MT_OFFLINE function
- MT_OFFLINE=:
-
- BLOCKING=124
- BACKUP_DIRS="
- albert:/fs/fsf
- apple-gunkies:/gd
- albert:/fs/gd2
- albert:/fs/gp
- geech:/usr/jla
- churchy:/usr/roland
- albert:/
- albert:/usr
- apple-gunkies:/
- apple-gunkies:/usr
- gnu:/hack
- gnu:/u
- apple-gunkies:/com/mailer/gnu
- apple-gunkies:/com/archive/gnu"
-
- BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
-
-\1f
-File: tar.info, Node: Scripted Backups, Next: Scripted Restoration, Prev: Backup Parameters, Up: Backups
-
-5.5 Using the Backup Scripts
-============================
-
-The syntax for running a backup script is:
-
- backup --level=LEVEL --time=TIME
-
- The `level' option requests the dump level. Thus, to produce a full
-dump, specify `--level=0' (this is the default, so `--level' may be
-omitted if its value is `0'). (1)
-
- The `--time' option determines when should the backup be run. TIME
-may take three forms:
-
-HH:MM
- The dump must be run at HH hours MM minutes.
-
-HH
- The dump must be run at HH hours
-
-now
- The dump must be run immediately.
-
- You should start a script with a tape or disk mounted. Once you
-start a script, it prompts you for new tapes or disks as it needs them.
-Media volumes don't have to correspond to archive files -- a
-multi-volume archive can be started in the middle of a tape that
-already contains the end of another multi-volume archive. The
-`restore' script prompts for media by its archive volume, so to avoid
-an error message you should keep track of which tape (or disk) contains
-which volume of the archive (*note Scripted Restoration::).
-
- The backup scripts write two files on the file system. The first is
-a record file in `/etc/tar-backup/', which is used by the scripts to
-store and retrieve information about which files were dumped. This
-file is not meant to be read by humans, and should not be deleted by
-them. *Note Snapshot Files::, for a more detailed explanation of this
-file.
-
- The second file is a log file containing the names of the file
-systems and files dumped, what time the backup was made, and any error
-messages that were generated, as well as how much space was left in the
-media volume after the last volume of the archive was written. You
-should check this log file after every backup. The file name is
-`log-MM-DD-YYYY-level-N', where MM-DD-YYYY represents current date, and
-N represents current dump level number.
-
- The script also prints the name of each system being dumped to the
-standard output.
-
- Following is the full list of options accepted by `backup' script:
-
-`-l LEVEL'
-`--level=LEVEL'
- Do backup level LEVEL (default 0).
-
-`-f'
-`--force'
- Force backup even if today's log file already exists.
-
-`-v[LEVEL]'
-`--verbose[=LEVEL]'
- Set verbosity level. The higher the level is, the more debugging
- information will be output during execution. Default LEVEL is
- 100, which means the highest debugging level.
-
-`-t START-TIME'
-`--time=START-TIME'
- Wait till TIME, then do backup.
-
-`-h'
-`--help'
- Display short help message and exit.
-
-`-V'
-`--version'
- Display information about the program's name, version, origin and
- legal status, all on standard output, and then exit successfully.
-
- ---------- Footnotes ----------
-
- (1) For backward compatibility, the `backup' will also try to deduce
-the requested dump level from the name of the script itself. If the
-name consists of a string `level-' followed by a single decimal digit,
-that digit is taken as the dump level number. Thus, you may create a
-link from `backup' to `level-1' and then run `level-1' whenever you
-need to create a level one dump.
-
-\1f
-File: tar.info, Node: Scripted Restoration, Prev: Scripted Backups, Up: Backups
-
-5.6 Using the Restore Script
-============================
-
-To restore files that were archived using a scripted backup, use the
-`restore' script. Its usage is quite straightforward. In the simplest
-form, invoke `restore --all', it will then restore all the file systems
-and files specified in `backup-specs' (*note BACKUP_DIRS:
-General-Purpose Variables.).
-
- You may select the file systems (and/or files) to restore by giving
-`restore' list of "patterns" in its command line. For example, running
-
- restore 'albert:*'
-
-will restore all file systems on the machine `albert'. A more
-complicated example:
-
- restore 'albert:*' '*:/var'
-
-This command will restore all file systems on the machine `albert' as
-well as `/var' file system on all machines.
-
- By default `restore' will start restoring files from the lowest
-available dump level (usually zero) and will continue through all
-available dump levels. There may be situations where such a thorough
-restore is not necessary. For example, you may wish to restore only
-files from the recent level one backup. To do so, use `--level'
-option, as shown in the example below:
-
- restore --level=1
-
- The full list of options accepted by `restore' follows:
-
-`-a'
-`--all'
- Restore all file systems and files specified in `backup-specs'
-
-`-l LEVEL'
-`--level=LEVEL'
- Start restoring from the given backup level, instead of the
- default 0.
-
-`-v[LEVEL]'
-`--verbose[=LEVEL]'
- Set verbosity level. The higher the level is, the more debugging
- information will be output during execution. Default LEVEL is
- 100, which means the highest debugging level.
-
-`-h'
-`--help'
- Display short help message and exit.
-
-`-V'
-`--version'
- Display information about the program's name, version, origin and
- legal status, all on standard output, and then exit successfully.
-
- You should start the restore script with the media containing the
-first volume of the archive mounted. The script will prompt for other
-volumes as they are needed. If the archive is on tape, you don't need
-to rewind the tape to to its beginning--if the tape head is positioned
-past the beginning of the archive, the script will rewind the tape as
-needed. *Note Tape Positioning::, for a discussion of tape positioning.
-
- *Warning:* The script will delete files from the active file
- system if they were not in the file system when the archive was
- made.
-
- *Note Incremental Dumps::, for an explanation of how the script makes
-that determination.
-
-\1f
-File: tar.info, Node: Choosing, Next: Date input formats, Prev: Backups, Up: Top
-
-6 Choosing Files and Names for `tar'
-************************************
-
- _(This message will disappear, once this node revised.)_
-
-Certain options to `tar' enable you to specify a name for your archive.
-Other options let you decide which files to include or exclude from
-the archive, based on when or whether files were modified, whether the
-file names do or don't match specified patterns, or whether files are
-in specified directories.
-
- This chapter discusses these options in detail.
-
-* Menu:
-
-* file:: Choosing the Archive's Name
-* Selecting Archive Members::
-* files:: Reading Names from a File
-* exclude:: Excluding Some Files
-* wildcards:: Wildcards Patterns and Matching
-* quoting styles:: Ways of Quoting Special Characters in Names
-* transform:: Modifying File and Member Names
-* after:: Operating Only on New Files
-* recurse:: Descending into Directories
-* one:: Crossing File System Boundaries
-
-\1f
-File: tar.info, Node: file, Next: Selecting Archive Members, Up: Choosing
-
-6.1 Choosing and Naming Archive Files
-=====================================
-
- _(This message will disappear, once this node revised.)_
-
-By default, `tar' uses an archive file name that was compiled when it
-was built on the system; usually this name refers to some physical tape
-drive on the machine. However, the person who installed `tar' on the
-system may not have set the default to a meaningful value as far as
-most users are concerned. As a result, you will usually want to tell
-`tar' where to find (or create) the archive. The `--file=ARCHIVE-NAME'
-(`-f ARCHIVE-NAME') option allows you to either specify or name a file
-to use as the archive instead of the default archive file location.
-
-`--file=ARCHIVE-NAME'
-`-f ARCHIVE-NAME'
- Name the archive to create or operate on. Use in conjunction with
- any operation.
-
- For example, in this `tar' command,
-
- $ tar -cvf collection.tar blues folk jazz
-
-`collection.tar' is the name of the archive. It must directly follow
-the `-f' option, since whatever directly follows `-f' _will_ end up
-naming the archive. If you neglect to specify an archive name, you may
-end up overwriting a file in the working directory with the archive you
-create since `tar' will use this file's name for the archive name.
-
- An archive can be saved as a file in the file system, sent through a
-pipe or over a network, or written to an I/O device such as a tape,
-floppy disk, or CD write drive.
-
- If you do not name the archive, `tar' uses the value of the
-environment variable `TAPE' as the file name for the archive. If that
-is not available, `tar' uses a default, compiled-in archive name,
-usually that for tape unit zero (i.e., `/dev/tu00').
-
- If you use `-' as an ARCHIVE-NAME, `tar' reads the archive from
-standard input (when listing or extracting files), or writes it to
-standard output (when creating an archive). If you use `-' as an
-ARCHIVE-NAME when modifying an archive, `tar' reads the original
-archive from its standard input and writes the entire new archive to
-its standard output.
-
- The following example is a convenient way of copying directory
-hierarchy from `sourcedir' to `targetdir'.
-
- $ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)
-
- The `-C' option allows to avoid using subshells:
-
- $ tar -C sourcedir -cf - . | tar -C targetdir -xpf -
-
- In both examples above, the leftmost `tar' invocation archives the
-contents of `sourcedir' to the standard output, while the rightmost one
-reads this archive from its standard input and extracts it. The `-p'
-option tells it to restore permissions of the extracted files.
-
- To specify an archive file on a device attached to a remote machine,
-use the following:
-
- --file=HOSTNAME:/DEV/FILE-NAME
-
-`tar' will complete the remote connection, if possible, and prompt you
-for a username and password. If you use
-`--file=@HOSTNAME:/DEV/FILE-NAME', `tar' will complete the remote
-connection, if possible, using your username as the username on the
-remote machine.
-
- If the archive file name includes a colon (`:'), then it is assumed
-to be a file on another machine. If the archive file is
-`USER@HOST:FILE', then FILE is used on the host HOST. The remote host
-is accessed using the `rsh' program, with a username of USER. If the
-username is omitted (along with the `@' sign), then your user name will
-be used. (This is the normal `rsh' behavior.) It is necessary for the
-remote machine, in addition to permitting your `rsh' access, to have
-the `rmt' program installed (This command is included in the GNU `tar'
-distribution and by default is installed under `PREFIX/libexec/rmt',
-were PREFIX means your installation prefix). If you need to use a file
-whose name includes a colon, then the remote tape drive behavior can be
-inhibited by using the `--force-local' option.
-
- When the archive is being created to `/dev/null', GNU `tar' tries to
-minimize input and output operations. The Amanda backup system, when
-used with GNU `tar', has an initial sizing pass which uses this feature.
-
-\1f
-File: tar.info, Node: Selecting Archive Members, Next: files, Prev: file, Up: Choosing
-
-6.2 Selecting Archive Members
-=============================
-
-"File Name arguments" specify which files in the file system `tar'
-operates on, when creating or adding to an archive, or which archive
-members `tar' operates on, when reading or deleting from an archive.
-*Note Operations::.
-
- To specify file names, you can include them as the last arguments on
-the command line, as follows:
- tar OPERATION [OPTION1 OPTION2 ...] [FILE NAME-1 FILE NAME-2 ...]
-
- If a file name begins with dash (`-'), precede it with `--add-file'
-option to prevent it from being treated as an option.
-
- By default GNU `tar' attempts to "unquote" each file or member name,
-replacing "escape sequences" according to the following table:
-
-Escape Replaced with
------------------------------------------------------------
-\a Audible bell (ASCII 7)
-\b Backspace (ASCII 8)
-\f Form feed (ASCII 12)
-\n New line (ASCII 10)
-\r Carriage return (ASCII 13)
-\t Horizontal tabulation (ASCII 9)
-\v Vertical tabulation (ASCII 11)
-\? ASCII 127
-\N ASCII N (N should be an octal number
- of up to 3 digits)
-
- A backslash followed by any other symbol is retained.
-
- This default behavior is controlled by the following command line
-option:
-
-`--unquote'
- Enable unquoting input file or member names (default).
-
-`--no-unquote'
- Disable unquoting input file or member names.
-
- If you specify a directory name as a file name argument, all the
-files in that directory are operated on by `tar'.
-
- If you do not specify files, `tar' behavior differs depending on the
-operation mode as described below:
-
- When `tar' is invoked with `--create' (`-c'), `tar' will stop
-immediately, reporting the following:
-
- $ tar cf a.tar
- tar: Cowardly refusing to create an empty archive
- Try `tar --help' or `tar --usage' for more information.
-
- If you specify either `--list' (`-t') or `--extract' (`--get',
-`-x'), `tar' operates on all the archive members in the archive.
-
- If run with `--diff' option, tar will compare the archive with the
-contents of the current working directory.
-
- If you specify any other operation, `tar' does nothing.
-
- By default, `tar' takes file names from the command line. However,
-there are other ways to specify file or member names, or to modify the
-manner in which `tar' selects the files or members upon which to
-operate. In general, these methods work both for specifying the names
-of files and archive members.
-
-\1f
-File: tar.info, Node: files, Next: exclude, Prev: Selecting Archive Members, Up: Choosing
-
-6.3 Reading Names from a File
-=============================
-
-Instead of giving the names of files or archive members on the command
-line, you can put the names into a file, and then use the
-`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option to `tar'.
-Give the name of the file which contains the list of files to include
-as the argument to `--files-from'. In the list, the file names should
-be separated by newlines. You will frequently use this option when you
-have generated the list of files to archive with the `find' utility.
-
-`--files-from=FILE-NAME'
-`-T FILE-NAME'
- Get names to extract or create from file FILE-NAME.
-
- If you give a single dash as a file name for `--files-from', (i.e.,
-you specify either `--files-from=-' or `-T -'), then the file names are
-read from standard input.
-
- Unless you are running `tar' with `--create', you can not use both
-`--files-from=-' and `--file=-' (`-f -') in the same command.
-
- Any number of `-T' options can be given in the command line.
-
- The following example shows how to use `find' to generate a list of
-files smaller than 400K in length and put that list into a file called
-`small-files'. You can then use the `-T' option to `tar' to specify
-the files from that file, `small-files', to create the archive
-`little.tgz'. (The `-z' option to `tar' compresses the archive with
-`gzip'; *note gzip:: for more information.)
-
- $ find . -size -400 -print > small-files
- $ tar -c -v -z -T small-files -f little.tgz
-
-In the file list given by `-T' option, any file name beginning with `-'
-character is considered a `tar' option and is processed accordingly.(1)
-For example, the common use of this feature is to change to another
-directory by specifying `-C' option:
-
- $ cat list
- -C/etc
- passwd
- hosts
- -C/lib
- libc.a
- $ tar -c -f foo.tar --files-from list
-
-In this example, `tar' will first switch to `/etc' directory and add
-files `passwd' and `hosts' to the archive. Then it will change to
-`/lib' directory and will archive the file `libc.a'. Thus, the
-resulting archive `foo.tar' will contain:
-
- $ tar tf foo.tar
- passwd
- hosts
- libc.a
-
-
- Notice that the option parsing algorithm used with `-T' is stricter
-than the one used by shell. Namely, when specifying option arguments,
-you should observe the following rules:
-
- * When using short (single-letter) option form, its argument must
- immediately follow the option letter, without any intervening
- whitespace. For example: `-Cdir'.
-
- * When using long option form, the option argument must be separated
- from the option by a single equal sign. No whitespace is allowed
- on any side of the equal sign. For example: `--directory=dir'.
-
- * For both short and long option forms, the option argument can be
- given on the next line after the option name, e.g.:
-
- --directory
- dir
-
- and
-
- -C
- dir
-
- If you happen to have a file whose name starts with `-', precede it
-with `--add-file' option to prevent it from being recognized as an
-option. For example: `--add-file=--my-file'.
-
-* Menu:
-
-* nul::
-
- ---------- Footnotes ----------
-
- (1) Versions of GNU `tar' up to 1.15.1 recognized only `-C' option
-in file lists, and only if the option and its argument occupied two
-consecutive lines.
-
-\1f
-File: tar.info, Node: nul, Up: files
-
-6.3.1 `NUL' Terminated File Names
----------------------------------
-
-The `--null' option causes `--files-from=FILE-OF-NAMES' (`-T
-FILE-OF-NAMES') to read file names terminated by a `NUL' instead of a
-newline, so files whose names contain newlines can be archived using
-`--files-from'.
-
-`--null'
- Only consider `NUL' terminated file names, instead of files that
- terminate in a newline.
-
- The `--null' option is just like the one in GNU `xargs' and `cpio',
-and is useful with the `-print0' predicate of GNU `find'. In `tar',
-`--null' also disables special handling for file names that begin with
-dash.
-
- This example shows how to use `find' to generate a list of files
-larger than 800K in length and put that list into a file called
-`long-files'. The `-print0' option to `find' is just like `-print',
-except that it separates files with a `NUL' rather than with a newline.
-You can then run `tar' with both the `--null' and `-T' options to
-specify that `tar' get the files from that file, `long-files', to
-create the archive `big.tgz'. The `--null' option to `tar' will cause
-`tar' to recognize the `NUL' separator between files.
-
- $ find . -size +800 -print0 > long-files
- $ tar -c -v --null --files-from=long-files --file=big.tar
-
-\1f
-File: tar.info, Node: exclude, Next: wildcards, Prev: files, Up: Choosing
-
-6.4 Excluding Some Files
-========================
-
- _(This message will disappear, once this node revised.)_
-
-To avoid operating on files whose names match a particular pattern, use
-the `--exclude' or `--exclude-from' options.
-
-`--exclude=PATTERN'
- Causes `tar' to ignore files that match the PATTERN.
-
- The `--exclude=PATTERN' option prevents any file or member whose
-name matches the shell wildcard (PATTERN) from being operated on. For
-example, to create an archive with all the contents of the directory
-`src' except for files whose names end in `.o', use the command `tar
--cf src.tar --exclude='*.o' src'.
-
- You may give multiple `--exclude' options.
-
-`--exclude-from=FILE'
-`-X FILE'
- Causes `tar' to ignore files that match the patterns listed in
- FILE.
-
- Use the `--exclude-from' option to read a list of patterns, one per
-line, from FILE; `tar' will ignore files matching those patterns. Thus
-if `tar' is called as `tar -c -X foo .' and the file `foo' contains a
-single line `*.o', no files whose names end in `.o' will be added to
-the archive.
-
- Notice, that lines from FILE are read verbatim. One of the frequent
-errors is leaving some extra whitespace after a file name, which is
-difficult to catch using text editors.
-
- However, empty lines are OK.
-
-`--exclude-vcs'
- Exclude files and directories used by some version control systems.
-
- As of version 1.20, the following files are excluded:
-
- * `CVS/', and everything under it
-
- * `RCS/', and everything under it
-
- * `SCCS/', and everything under it
-
- * `.git/', and everything under it
-
- * `.gitignore'
-
- * `.cvsignore'
-
- * `.svn/', and everything under it
-
- * `.arch-ids/', and everything under it
-
- * `{arch}/', and everything under it
-
- * `=RELEASE-ID'
-
- * `=meta-update'
-
- * `=update'
-
- When creating an archive, the `--exclude-caches' option family
-causes `tar' to exclude all directories that contain a "cache directory
-tag". A cache directory tag is a short file with the well-known name
-`CACHEDIR.TAG' and having a standard header specified in
-`http://www.brynosaurus.com/cachedir/spec.html'. Various applications
-write cache directory tags into directories they use to hold
-regenerable, non-precious data, so that such data can be more easily
-excluded from backups.
-
- There are three `exclude-caches' options, each providing a different
-exclusion semantics:
-
-`--exclude-caches'
- Do not archive the contents of the directory, but archive the
- directory itself and the `CACHEDIR.TAG' file.
-
-`--exclude-caches-under'
- Do not archive the contents of the directory, nor the
- `CACHEDIR.TAG' file, archive only the directory itself.
-
-`--exclude-caches-all'
- Omit directories containing `CACHEDIR.TAG' file entirely.
-
- Another option family, `--exclude-tag', provides a generalization of
-this concept. It takes a single argument, a file name to look for.
-Any directory that contains this file will be excluded from the dump.
-Similarly to `exclude-caches', there are three options in this option
-family:
-
-`--exclude-tag=FILE'
- Do not dump the contents of the directory, but dump the directory
- itself and the FILE.
-
-`--exclude-tag-under=FILE'
- Do not dump the contents of the directory, nor the FILE, archive
- only the directory itself.
-
-`--exclude-tag-all=FILE'
- Omit directories containing FILE file entirely.
-
- Multiple `--exclude-tag*' options can be given.
-
- For example, given this directory:
-
- $ find dir
- dir
- dir/blues
- dir/jazz
- dir/folk
- dir/folk/tagfile
- dir/folk/sanjuan
- dir/folk/trote
-
- The `--exclude-tag' will produce the following:
-
- $ tar -cf archive.tar --exclude-tag=tagfile -v dir
- dir/
- dir/blues
- dir/jazz
- dir/folk/
- tar: dir/folk/: contains a cache directory tag tagfile;
- contents not dumped
- dir/folk/tagfile
-
- Both the `dir/folk' directory and its tagfile are preserved in the
-archive, however the rest of files in this directory are not.
-
- Now, using the `--exclude-tag-under' option will exclude `tagfile'
-from the dump, while still preserving the directory itself, as shown in
-this example:
-
- $ tar -cf archive.tar --exclude-tag-under=tagfile -v dir
- dir/
- dir/blues
- dir/jazz
- dir/folk/
- ./tar: dir/folk/: contains a cache directory tag tagfile;
- contents not dumped
-
- Finally, using `--exclude-tag-all' omits the `dir/folk' directory
-entirely:
-
- $ tar -cf archive.tar --exclude-tag-all=tagfile -v dir
- dir/
- dir/blues
- dir/jazz
- ./tar: dir/folk/: contains a cache directory tag tagfile;
- directory not dumped
-
-* Menu:
-
-* problems with exclude::
-
-\1f
-File: tar.info, Node: problems with exclude, Up: exclude
-
-Problems with Using the `exclude' Options
------------------------------------------
-
-Some users find `exclude' options confusing. Here are some common
-pitfalls:
-
- * The main operating mode of `tar' does not act on a file name
- explicitly listed on the command line, if one of its file name
- components is excluded. In the example above, if you create an
- archive and exclude files that end with `*.o', but explicitly name
- the file `dir.o/foo' after all the options have been listed,
- `dir.o/foo' will be excluded from the archive.
-
- * You can sometimes confuse the meanings of `--exclude' and
- `--exclude-from'. Be careful: use `--exclude' when files to be
- excluded are given as a pattern on the command line. Use
- `--exclude-from' to introduce the name of a file which contains a
- list of patterns, one per line; each of these patterns can exclude
- zero, one, or many files.
-
- * When you use `--exclude=PATTERN', be sure to quote the PATTERN
- parameter, so GNU `tar' sees wildcard characters like `*'. If you
- do not do this, the shell might expand the `*' itself using files
- at hand, so `tar' might receive a list of files instead of one
- pattern, or none at all, making the command somewhat illegal.
- This might not correspond to what you want.
-
- For example, write:
-
- $ tar -c -f ARCHIVE.TAR --exclude '*.o' DIRECTORY
-
- rather than:
-
- # _Wrong!_
- $ tar -c -f ARCHIVE.TAR --exclude *.o DIRECTORY
-
- * You must use use shell syntax, or globbing, rather than `regexp'
- syntax, when using exclude options in `tar'. If you try to use
- `regexp' syntax to describe files to be excluded, your command
- might fail.
-
- * In earlier versions of `tar', what is now the `--exclude-from'
- option was called `--exclude' instead. Now, `--exclude' applies
- to patterns listed on the command line and `--exclude-from'
- applies to patterns listed in a file.
-
-
-\1f
-File: tar.info, Node: wildcards, Next: quoting styles, Prev: exclude, Up: Choosing
-
-6.5 Wildcards Patterns and Matching
-===================================
-
-"Globbing" is the operation by which "wildcard" characters, `*' or `?'
-for example, are replaced and expanded into all existing files matching
-the given pattern. GNU `tar' can use wildcard patterns for matching
-(or globbing) archive members when extracting from or listing an
-archive. Wildcard patterns are also used for verifying volume labels
-of `tar' archives. This section has the purpose of explaining wildcard
-syntax for `tar'.
-
- A PATTERN should be written according to shell syntax, using wildcard
-characters to effect globbing. Most characters in the pattern stand
-for themselves in the matched string, and case is significant: `a' will
-match only `a', and not `A'. The character `?' in the pattern matches
-any single character in the matched string. The character `*' in the
-pattern matches zero, one, or more single characters in the matched
-string. The character `\' says to take the following character of the
-pattern _literally_; it is useful when one needs to match the `?', `*',
-`[' or `\' characters, themselves.
-
- The character `[', up to the matching `]', introduces a character
-class. A "character class" is a list of acceptable characters for the
-next single character of the matched string. For example, `[abcde]'
-would match any of the first five letters of the alphabet. Note that
-within a character class, all of the "special characters" listed above
-other than `\' lose their special meaning; for example, `[-\\[*?]]'
-would match any of the characters, `-', `\', `[', `*', `?', or `]'.
-(Due to parsing constraints, the characters `-' and `]' must either
-come _first_ or _last_ in a character class.)
-
- If the first character of the class after the opening `[' is `!' or
-`^', then the meaning of the class is reversed. Rather than listing
-character to match, it lists those characters which are _forbidden_ as
-the next single character of the matched string.
-
- Other characters of the class stand for themselves. The special
-construction `[A-E]', using an hyphen between two letters, is meant to
-represent all characters between A and E, inclusive.
-
- Periods (`.') or forward slashes (`/') are not considered special
-for wildcard matches. However, if a pattern completely matches a
-directory prefix of a matched string, then it matches the full matched
-string: thus, excluding a directory also excludes all the files beneath
-it.
-
-* Menu:
-
-* controlling pattern-matching::
-
-\1f
-File: tar.info, Node: controlling pattern-matching, Up: wildcards
-
-Controlling Pattern-Matching
-----------------------------
-
-For the purposes of this section, we call "exclusion members" all
-member names obtained while processing `--exclude' and `--exclude-from'
-options, and "inclusion members" those member names that were given in
-the command line or read from the file specified with `--files-from'
-option.
-
- These two pairs of member lists are used in the following operations:
-`--diff', `--extract', `--list', `--update'.
-
- There are no inclusion members in create mode (`--create' and
-`--append'), since in this mode the names obtained from the command
-line refer to _files_, not archive members.
-
- By default, inclusion members are compared with archive members
-literally (1) and exclusion members are treated as globbing patterns.
-For example:
-
- $ tar tf foo.tar
- a.c
- b.c
- a.txt
- [remarks]
- # Member names are used verbatim:
- $ tar -xf foo.tar -v '[remarks]'
- [remarks]
- # Exclude member names are globbed:
- $ tar -xf foo.tar -v --exclude '*.c'
- a.txt
- [remarks]
-
- This behavior can be altered by using the following options:
-
-`--wildcards'
- Treat all member names as wildcards.
-
-`--no-wildcards'
- Treat all member names as literal strings.
-
- Thus, to extract files whose names end in `.c', you can use:
-
- $ tar -xf foo.tar -v --wildcards '*.c'
- a.c
- b.c
-
-Notice quoting of the pattern to prevent the shell from interpreting it.
-
- The effect of `--wildcards' option is canceled by `--no-wildcards'.
-This can be used to pass part of the command line arguments verbatim
-and other part as globbing patterns. For example, the following
-invocation:
-
- $ tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'
-
-instructs `tar' to extract from `foo.tar' all files whose names end in
-`.txt' and the file named `[remarks]'.
-
- Normally, a pattern matches a name if an initial subsequence of the
-name's components matches the pattern, where `*', `?', and `[...]' are
-the usual shell wildcards, `\' escapes wildcards, and wildcards can
-match `/'.
-
- Other than optionally stripping leading `/' from names (*note
-absolute::), patterns and names are used as-is. For example, trailing
-`/' is not trimmed from a user-specified name before deciding whether
-to exclude it.
-
- However, this matching procedure can be altered by the options listed
-below. These options accumulate. For example:
-
- --ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
-
-ignores case when excluding `makefile', but not when excluding `readme'.
-
-`--anchored'
-`--no-anchored'
- If anchored, a pattern must match an initial subsequence of the
- name's components. Otherwise, the pattern can match any
- subsequence. Default is `--no-anchored' for exclusion members and
- `--anchored' inclusion members.
-
-`--ignore-case'
-`--no-ignore-case'
- When ignoring case, upper-case patterns match lower-case names and
- vice versa. When not ignoring case (the default), matching is
- case-sensitive.
-
-`--wildcards-match-slash'
-`--no-wildcards-match-slash'
- When wildcards match slash (the default for exclusion members), a
- wildcard like `*' in the pattern can match a `/' in the name.
- Otherwise, `/' is matched only by `/'.
-
-
- The `--recursion' and `--no-recursion' options (*note recurse::)
-also affect how member patterns are interpreted. If recursion is in
-effect, a pattern matches a name if it matches any of the name's parent
-directories.
-
- The following table summarizes pattern-matching default values:
-
-Members Default settings
---------------------------------------------------------------------------
-Inclusion `--no-wildcards --anchored
- --no-wildcards-match-slash'
-Exclusion `--wildcards --no-anchored
- --wildcards-match-slash'
-
- ---------- Footnotes ----------
-
- (1) Notice that earlier GNU `tar' versions used globbing for
-inclusion members, which contradicted to UNIX98 specification and was
-not documented. *Note Changes::, for more information on this and other
-changes.
-
-\1f
-File: tar.info, Node: quoting styles, Next: transform, Prev: wildcards, Up: Choosing
-
-6.6 Quoting Member Names
-========================
-
-When displaying member names, `tar' takes care to avoid ambiguities
-caused by certain characters. This is called "name quoting". The
-characters in question are:
-
- * Non-printable control characters:
-
- Character ASCII Character name
- ---------------------------------------------------------------
- \a 7 Audible bell
- \b 8 Backspace
- \f 12 Form feed
- \n 10 New line
- \r 13 Carriage return
- \t 9 Horizontal tabulation
- \v 11 Vertical tabulation
-
- * Space (ASCII 32)
-
- * Single and double quotes (`'' and `"')
-
- * Backslash (`\')
-
- The exact way `tar' uses to quote these characters depends on the
-"quoting style". The default quoting style, called "escape" (see
-below), uses backslash notation to represent control characters, space
-and backslash. Using this quoting style, control characters are
-represented as listed in column `Character' in the above table, a space
-is printed as `\ ' and a backslash as `\\'.
-
- GNU `tar' offers seven distinct quoting styles, which can be selected
-using `--quoting-style' option:
-
-`--quoting-style=STYLE'
- Sets quoting style. Valid values for STYLE argument are: literal,
- shell, shell-always, c, escape, locale, clocale.
-
- These styles are described in detail below. To illustrate their
-effect, we will use an imaginary tar archive `arch.tar' containing the
-following members:
-
- # 1. Contains horizontal tabulation character.
- a tab
- # 2. Contains newline character
- a
- newline
- # 3. Contains a space
- a space
- # 4. Contains double quotes
- a"double"quote
- # 5. Contains single quotes
- a'single'quote
- # 6. Contains a backslash character:
- a\backslash
-
- Here is how usual `ls' command would have listed them, if they had
-existed in the current working directory:
-
- $ ls
- a\ttab
- a\nnewline
- a\ space
- a"double"quote
- a'single'quote
- a\\backslash
-
- Quoting styles:
-
-`literal'
- No quoting, display each character as is:
-
- $ tar tf arch.tar --quoting-style=literal
- ./
- ./a space
- ./a'single'quote
- ./a"double"quote
- ./a\backslash
- ./a tab
- ./a
- newline
-
-`shell'
- Display characters the same way Bourne shell does: control
- characters, except `\t' and `\n', are printed using backslash
- escapes, `\t' and `\n' are printed as is, and a single quote is
- printed as `\''. If a name contains any quoted characters, it is
- enclosed in single quotes. In particular, if a name contains
- single quotes, it is printed as several single-quoted strings:
-
- $ tar tf arch.tar --quoting-style=shell
- ./
- './a space'
- './a'\''single'\''quote'
- './a"double"quote'
- './a\backslash'
- './a tab'
- './a
- newline'
-
-`shell-always'
- Same as `shell', but the names are always enclosed in single
- quotes:
-
- $ tar tf arch.tar --quoting-style=shell-always
- './'
- './a space'
- './a'\''single'\''quote'
- './a"double"quote'
- './a\backslash'
- './a tab'
- './a
- newline'
-
-`c'
- Use the notation of the C programming language. All names are
- enclosed in double quotes. Control characters are quoted using
- backslash notations, double quotes are represented as `\"',
- backslash characters are represented as `\\'. Single quotes and
- spaces are not quoted:
-
- $ tar tf arch.tar --quoting-style=c
- "./"
- "./a space"
- "./a'single'quote"
- "./a\"double\"quote"
- "./a\\backslash"
- "./a\ttab"
- "./a\nnewline"
-
-`escape'
- Control characters are printed using backslash notation, a space is
- printed as `\ ' and a backslash as `\\'. This is the default
- quoting style, unless it was changed when configured the package.
-
- $ tar tf arch.tar --quoting-style=escape
- ./
- ./a space
- ./a'single'quote
- ./a"double"quote
- ./a\\backslash
- ./a\ttab
- ./a\nnewline
-
-`locale'
- Control characters, single quote and backslash are printed using
- backslash notation. All names are quoted using left and right
- quotation marks, appropriate to the current locale. If it does not
- define quotation marks, use ``' as left and `'' as right quotation
- marks. Any occurrences of the right quotation mark in a name are
- escaped with `\', for example:
-
- For example:
-
- $ tar tf arch.tar --quoting-style=locale
- `./'
- `./a space'
- `./a\'single\'quote'
- `./a"double"quote'
- `./a\\backslash'
- `./a\ttab'
- `./a\nnewline'
-
-`clocale'
- Same as `locale', but `"' is used for both left and right
- quotation marks, if not provided by the currently selected locale:
-
- $ tar tf arch.tar --quoting-style=clocale
- "./"
- "./a space"
- "./a'single'quote"
- "./a\"double\"quote"
- "./a\\backslash"
- "./a\ttab"
- "./a\nnewline"
-
- You can specify which characters should be quoted in addition to
-those implied by the current quoting style:
-
-`--quote-chars=STRING'
- Always quote characters from STRING, even if the selected quoting
- style would not quote them.
-
- For example, using `escape' quoting (compare with the usual escape
-listing above):
-
- $ tar tf arch.tar --quoting-style=escape --quote-chars=' "'
- ./
- ./a\ space
- ./a'single'quote
- ./a\"double\"quote
- ./a\\backslash
- ./a\ttab
- ./a\nnewline
-
- To disable quoting of such additional characters, use the following
-option:
-
-`--no-quote-chars=STRING'
- Remove characters listed in STRING from the list of quoted
- characters set by the previous `--quote-chars' option.
-
- This option is particularly useful if you have added `--quote-chars'
-to your `TAR_OPTIONS' (*note TAR_OPTIONS::) and wish to disable it for
-the current invocation.
-
- Note, that `--no-quote-chars' does _not_ disable those characters
-that are quoted by default in the selected quoting style.
-
-\1f
-File: tar.info, Node: transform, Next: after, Prev: quoting styles, Up: Choosing
-
-6.7 Modifying File and Member Names
-===================================
-
-`Tar' archives contain detailed information about files stored in them
-and full file names are part of that information. When storing file to
-an archive, its file name is recorded in the archive along with the
-actual file contents. When restoring from an archive, a file is
-created on disk with exactly the same name as that stored in the
-archive. In the majority of cases this is the desired behavior of a
-file archiver. However, there are some cases when it is not.
-
- First of all, it is often unsafe to extract archive members with
-absolute file names or those that begin with a `../'. GNU `tar' takes
-special precautions when extracting such names and provides a special
-option for handling them, which is described in *note absolute::.
-
- Secondly, you may wish to extract file names without some leading
-directory components, or with otherwise modified names. In other cases
-it is desirable to store files under differing names in the archive.
-
- GNU `tar' provides two options for these needs.
-
-`--strip-components=NUMBER'
- Strip given NUMBER of leading components from file names before
- extraction.
-
- For example, suppose you have archived whole `/usr' hierarchy to a
-tar archive named `usr.tar'. Among other files, this archive contains
-`usr/include/stdlib.h', which you wish to extract to the current
-working directory. To do so, you type:
-
- $ tar -xf usr.tar --strip=2 usr/include/stdlib.h
-
- The option `--strip=2' instructs `tar' to strip the two leading
-components (`usr/' and `include/') off the file name.
-
- If you add to the above invocation `--verbose' (`-v') option, you
-will note that the verbose listing still contains the full file name,
-with the two removed components still in place. This can be
-inconvenient, so `tar' provides a special option for altering this
-behavior:
-
-`--show-transformed-names'
- Display file or member names with all requested transformations
- applied.
-
-For example:
-
- $ tar -xf usr.tar -v --strip=2 usr/include/stdlib.h
- usr/include/stdlib.h
- $ tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h
- stdlib.h
-
- Notice that in both cases the file is `stdlib.h' extracted to the
-current working directory, `--show-transformed-names' affects only the
-way its name is displayed.
-
- This option is especially useful for verifying whether the invocation
-will have the desired effect. Thus, before running
-
- $ tar -x --strip=N
-
-it is often advisable to run
-
- $ tar -t -v --show-transformed --strip=N
-
-to make sure the command will produce the intended results.
-
- In case you need to apply more complex modifications to the file
-name, GNU `tar' provides a general-purpose transformation option:
-
-`--transform=EXPRESSION'
- Modify file names using supplied EXPRESSION.
-
-The EXPRESSION is a `sed'-like replace expression of the form:
-
- s/REGEXP/REPLACE/[FLAGS]
-
-where REGEXP is a "regular expression", REPLACE is a replacement for
-each file name part that matches REGEXP. Both REGEXP and REPLACE are
-described in detail in *note The "s" Command: (sed)The "s" Command.
-
- As in `sed', you can give several replace expressions, separated by
-a semicolon.
-
- Supported FLAGS are:
-
-`g'
- Apply the replacement to _all_ matches to the REGEXP, not just the
- first.
-
-`i'
- Use case-insensitive matching
-
-`x'
- REGEXP is an "extended regular expression" (*note Extended regular
- expressions: (sed)Extended regexps.).
-
-`NUMBER'
- Only replace the NUMBERth match of the REGEXP.
-
- Note: the POSIX standard does not specify what should happen when
- you mix the `g' and NUMBER modifiers. GNU `tar' follows the GNU
- `sed' implementation in this regard, so the interaction is defined
- to be: ignore matches before the NUMBERth, and then match and
- replace all matches from the NUMBERth on.
-
-
- Any delimiter can be used in lieue of `/', the only requirement being
-that it be used consistently throughout the expression. For example,
-the following two expressions are equivalent:
-
- s/one/two/
- s,one,two,
-
- Changing delimiters is often useful when the REGEX contains slashes.
-For example, it is more convenient to write `s,/,-,' than `s/\//-/'.
-
- Here are several examples of `--transform' usage:
-
- 1. Extract `usr/' hierarchy into `usr/local/':
-
- $ tar --transform='s,usr/,usr/local/,' -x -f arch.tar
-
- 2. Strip two leading directory components (equivalent to
- `--strip-components=2'):
-
- $ tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar
-
- 3. Prepend `/prefix/' to each file name:
-
- $ tar --transform 's,^,/prefix/,' -x -f arch.tar
-
- 4. Convert each file name to lower case:
-
- $ tar --transform 's/.*/\L&/' -x -f arch.tar
-
-
- Unlike `--strip-components', `--transform' can be used in any GNU
-`tar' operation mode. For example, the following command adds files to
-the archive while replacing the leading `usr/' component with `var/':
-
- $ tar -cf arch.tar --transform='s,^usr/,var/,' /
-
- To test `--transform' effect we suggest using
-`--show-transformed-names' option:
-
- $ tar -cf arch.tar --transform='s,^usr/,var/,' \
- --verbose --show-transformed-names /
-
- If both `--strip-components' and `--transform' are used together,
-then `--transform' is applied first, and the required number of
-components is then stripped from its result.
-
- You can use as many `--transform' options in a single command line
-as you want. The specified expressions will then be applied in order
-of their appearance. For example, the following two invocations are
-equivalent:
-
- $ tar -cf arch.tar --transform='s,/usr/var,/var/' \
- --transform='s,/usr/local,/usr/,'
- $ tar -cf arch.tar \
- --transform='s,/usr/var,/var/;s,/usr/local,/usr/,'
-
-\1f
-File: tar.info, Node: after, Next: recurse, Prev: transform, Up: Choosing
-
-6.8 Operating Only on New Files
-===============================
-
- _(This message will disappear, once this node revised.)_
-
-The `--after-date=DATE' (`--newer=DATE', `-N DATE') option causes `tar'
-to only work on files whose data modification or status change times
-are newer than the DATE given. If DATE starts with `/' or `.', it is
-taken to be a file name; the data modification time of that file is
-used as the date. If you use this option when creating or appending to
-an archive, the archive will only include new files. If you use
-`--after-date' when extracting an archive, `tar' will only extract
-files newer than the DATE you specify.
-
- If you only want `tar' to make the date comparison based on
-modification of the file's data (rather than status changes), then use
-the `--newer-mtime=DATE' option.
-
- You may use these options with any operation. Note that these
-options differ from the `--update' (`-u') operation in that they allow
-you to specify a particular date against which `tar' can compare when
-deciding whether or not to archive the files.
-
-`--after-date=DATE'
-`--newer=DATE'
-`-N DATE'
- Only store files newer than DATE.
-
- Acts on files only if their data modification or status change
- times are later than DATE. Use in conjunction with any operation.
-
- If DATE starts with `/' or `.', it is taken to be a file name; the
- data modification time of that file is used as the date.
-
-`--newer-mtime=DATE'
- Acts like `--after-date', but only looks at data modification
- times.
-
- These options limit `tar' to operate only on files which have been
-modified after the date specified. A file's status is considered to
-have changed if its contents have been modified, or if its owner,
-permissions, and so forth, have been changed. (For more information on
-how to specify a date, see *note Date input formats::; remember that the
-entire date argument must be quoted if it contains any spaces.)
-
- Gurus would say that `--after-date' tests both the data modification
-time (`mtime', the time the contents of the file were last modified)
-and the status change time (`ctime', the time the file's status was
-last changed: owner, permissions, etc.) fields, while `--newer-mtime'
-tests only the `mtime' field.
-
- To be precise, `--after-date' checks _both_ `mtime' and `ctime' and
-processes the file if either one is more recent than DATE, while
-`--newer-mtime' only checks `mtime' and disregards `ctime'. Neither
-does it use `atime' (the last time the contents of the file were looked
-at).
-
- Date specifiers can have embedded spaces. Because of this, you may
-need to quote date arguments to keep the shell from parsing them as
-separate arguments. For example, the following command will add to the
-archive all the files modified less than two days ago:
-
- $ tar -cf foo.tar --newer-mtime '2 days ago'
-
- When any of these options is used with the option `--verbose' (*note
-verbose tutorial::) GNU `tar' will try to convert the specified date
-back to its textual representation and compare that with the one given
-with the option. If the two dates differ, `tar' will print a warning
-saying what date it will use. This is to help user ensure he is using
-the right date. For example:
-
- $ tar -c -f archive.tar --after-date='10 days ago' .
- tar: Option --after-date: Treating date `10 days ago' as 2006-06-11
- 13:19:37.232434
-
- *Please Note:* `--after-date' and `--newer-mtime' should not be
- used for incremental backups. *Note Incremental Dumps::, for
- proper way of creating incremental backups.
-
-\1f
-File: tar.info, Node: recurse, Next: one, Prev: after, Up: Choosing
-
-6.9 Descending into Directories
-===============================
-
- _(This message will disappear, once this node revised.)_
-
-Usually, `tar' will recursively explore all directories (either those
-given on the command line or through the `--files-from' option) for the
-various files they contain. However, you may not always want `tar' to
-act this way.
-
- The `--no-recursion' option inhibits `tar''s recursive descent into
-specified directories. If you specify `--no-recursion', you can use
-the `find' utility for hunting through levels of directories to
-construct a list of file names which you could then pass to `tar'.
-`find' allows you to be more selective when choosing which files to
-archive; see *note files::, for more information on using `find' with
-`tar', or look.
-
-`--no-recursion'
- Prevents `tar' from recursively descending directories.
-
-`--recursion'
- Requires `tar' to recursively descend directories. This is the
- default.
-
- When you use `--no-recursion', GNU `tar' grabs directory entries
-themselves, but does not descend on them recursively. Many people use
-`find' for locating files they want to back up, and since `tar'
-_usually_ recursively descends on directories, they have to use the
-`-not -type d' test in their `find' invocation (*note Type:
-(find)Type.), as they usually do not want all the files in a directory.
-They then use the `--files-from' option to archive the files located
-via `find'.
-
- The problem when restoring files archived in this manner is that the
-directories themselves are not in the archive; so the
-`--same-permissions' (`--preserve-permissions', `-p') option does not
-affect them--while users might really like it to. Specifying
-`--no-recursion' is a way to tell `tar' to grab only the directory
-entries given to it, adding no new files on its own. To summarize, if
-you use `find' to create a list of files to be stored in an archive,
-use it as follows:
-
- $ find DIR TESTS | \
- tar -cf ARCHIVE -T - --no-recursion
-
- The `--no-recursion' option also applies when extracting: it causes
-`tar' to extract only the matched directory entries, not the files
-under those directories.
-
- The `--no-recursion' option also affects how globbing patterns are
-interpreted (*note controlling pattern-matching::).
-
- The `--no-recursion' and `--recursion' options apply to later
-options and operands, and can be overridden by later occurrences of
-`--no-recursion' and `--recursion'. For example:
-
- $ tar -cf jams.tar --no-recursion grape --recursion grape/concord
-
-creates an archive with one entry for `grape', and the recursive
-contents of `grape/concord', but no entries under `grape' other than
-`grape/concord'.
-
-\1f
-File: tar.info, Node: one, Prev: recurse, Up: Choosing
-
-6.10 Crossing File System Boundaries
-====================================
-
- _(This message will disappear, once this node revised.)_
-
-`tar' will normally automatically cross file system boundaries in order
-to archive files which are part of a directory tree. You can change
-this behavior by running `tar' and specifying `--one-file-system'.
-This option only affects files that are archived because they are in a
-directory that is being archived; `tar' will still archive files
-explicitly named on the command line or through `--files-from',
-regardless of where they reside.
-
-`--one-file-system'
- Prevents `tar' from crossing file system boundaries when
- archiving. Use in conjunction with any write operation.
-
- The `--one-file-system' option causes `tar' to modify its normal
-behavior in archiving the contents of directories. If a file in a
-directory is not on the same file system as the directory itself, then
-`tar' will not archive that file. If the file is a directory itself,
-`tar' will not archive anything beneath it; in other words, `tar' will
-not cross mount points.
-
- This option is useful for making full or incremental archival
-backups of a file system. If this option is used in conjunction with
-`--verbose' (`-v'), files that are excluded are mentioned by name on
-the standard error.
-
-* Menu:
-
-* directory:: Changing Directory
-* absolute:: Absolute File Names
-
-\1f
-File: tar.info, Node: directory, Next: absolute, Up: one
-
-6.10.1 Changing the Working Directory
--------------------------------------
-
-To change the working directory in the middle of a list of file names,
-either on the command line or in a file specified using `--files-from'
-(`-T'), use `--directory' (`-C'). This will change the working
-directory to the specified directory after that point in the list.
-
-`--directory=DIRECTORY'
-`-C DIRECTORY'
- Changes the working directory in the middle of a command line.
-
- For example,
-
- $ tar -c -f jams.tar grape prune -C food cherry
-
-will place the files `grape' and `prune' from the current directory
-into the archive `jams.tar', followed by the file `cherry' from the
-directory `food'. This option is especially useful when you have
-several widely separated files that you want to store in the same
-archive.
-
- Note that the file `cherry' is recorded in the archive under the
-precise name `cherry', _not_ `food/cherry'. Thus, the archive will
-contain three files that all appear to have come from the same
-directory; if the archive is extracted with plain `tar --extract', all
-three files will be written in the current directory.
-
- Contrast this with the command,
-
- $ tar -c -f jams.tar grape prune -C food red/cherry
-
-which records the third file in the archive under the name `red/cherry'
-so that, if the archive is extracted using `tar --extract', the third
-file will be written in a subdirectory named `orange-colored'.
-
- You can use the `--directory' option to make the archive independent
-of the original name of the directory holding the files. The following
-command places the files `/etc/passwd', `/etc/hosts', and `/lib/libc.a'
-into the archive `foo.tar':
-
- $ tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a
-
-However, the names of the archive members will be exactly what they were
-on the command line: `passwd', `hosts', and `libc.a'. They will not
-appear to be related by file name to the original directories where
-those files were located.
-
- Note that `--directory' options are interpreted consecutively. If
-`--directory' specifies a relative file name, it is interpreted
-relative to the then current directory, which might not be the same as
-the original current working directory of `tar', due to a previous
-`--directory' option.
-
- When using `--files-from' (*note files::), you can put various `tar'
-options (including `-C') in the file list. Notice, however, that in
-this case the option and its argument may not be separated by
-whitespace. If you use short option, its argument must either follow
-the option letter immediately, without any intervening whitespace, or
-occupy the next line. Otherwise, if you use long option, separate its
-argument by an equal sign.
-
- For instance, the file list for the above example will be:
-
- -C/etc
- passwd
- hosts
- --directory=/lib
- libc.a
-
-To use it, you would invoke `tar' as follows:
-
- $ tar -c -f foo.tar --files-from list
-
- The interpretation of `--directory' is disabled by `--null' option.
-
-\1f
-File: tar.info, Node: absolute, Prev: directory, Up: one
-
-6.10.2 Absolute File Names
---------------------------
-
- _(This message will disappear, once this node revised.)_
-
-`--absolute-names'
-`-P'
- Do not strip leading slashes from file names, and permit file names
- containing a `..' file name component.
-
- By default, GNU `tar' drops a leading `/' on input or output, and
-complains about file names containing a `..' component. This option
-turns off this behavior.
-
- When `tar' extracts archive members from an archive, it strips any
-leading slashes (`/') from the member name. This causes absolute
-member names in the archive to be treated as relative file names. This
-allows you to have such members extracted wherever you want, instead of
-being restricted to extracting the member in the exact directory named
-in the archive. For example, if the archive member has the name
-`/etc/passwd', `tar' will extract it as if the name were really
-`etc/passwd'.
-
- File names containing `..' can cause problems when extracting, so
-`tar' normally warns you about such files when creating an archive, and
-rejects attempts to extracts such files.
-
- Other `tar' programs do not do this. As a result, if you create an
-archive whose member names start with a slash, they will be difficult
-for other people with a non-GNU `tar' program to use. Therefore, GNU
-`tar' also strips leading slashes from member names when putting
-members into the archive. For example, if you ask `tar' to add the file
-`/bin/ls' to an archive, it will do so, but the member name will be
-`bin/ls'.(1)
-
- If you use the `--absolute-names' (`-P') option, `tar' will do none
-of these transformations.
-
- To archive or extract files relative to the root directory, specify
-the `--absolute-names' (`-P') option.
-
- Normally, `tar' acts on files relative to the working
-directory--ignoring superior directory names when archiving, and
-ignoring leading slashes when extracting.
-
- When you specify `--absolute-names' (`-P'), `tar' stores file names
-including all superior directory names, and preserves leading slashes.
-If you only invoked `tar' from the root directory you would never need
-the `--absolute-names' option, but using this option may be more
-convenient than switching to root.
-
-`--absolute-names'
- Preserves full file names (including superior directory names) when
- archiving files. Preserves leading slash when extracting files.
-
-
- `tar' prints out a message about removing the `/' from file names.
-This message appears once per GNU `tar' invocation. It represents
-something which ought to be told; ignoring what it means can cause very
-serious surprises, later.
-
- Some people, nevertheless, do not want to see this message. Wanting
-to play really dangerously, one may of course redirect `tar' standard
-error to the sink. For example, under `sh':
-
- $ tar -c -f archive.tar /home 2> /dev/null
-
-Another solution, both nicer and simpler, would be to change to the `/'
-directory first, and then avoid absolute notation. For example:
-
- $ (cd / && tar -c -f archive.tar home)
- # or:
- $ tar -c -f archive.tar -C / home
-
- ---------- Footnotes ----------
-
- (1) A side effect of this is that when `--create' is used with
-`--verbose' the resulting output is not, generally speaking, the same
-as the one you'd get running `tar --list' command. This may be
-important if you use some scripts for comparing both outputs. *Note
-listing member and file names::, for the information on how to handle
-this case.
-
-\1f
-File: tar.info, Node: Date input formats, Next: Formats, Prev: Choosing, Up: Top
-
-7 Date input formats
-********************
-
-First, a quote:
-
- Our units of temporal measurement, from seconds on up to months,
- are so complicated, asymmetrical and disjunctive so as to make
- coherent mental reckoning in time all but impossible. Indeed, had
- some tyrannical god contrived to enslave our minds to time, to
- make it all but impossible for us to escape subjection to sodden
- routines and unpleasant surprises, he could hardly have done
- better than handing down our present system. It is like a set of
- trapezoidal building blocks, with no vertical or horizontal
- surfaces, like a language in which the simplest thought demands
- ornate constructions, useless particles and lengthy
- circumlocutions. Unlike the more successful patterns of language
- and science, which enable us to face experience boldly or at least
- level-headedly, our system of temporal calculation silently and
- persistently encourages our terror of time.
-
- ... It is as though architects had to measure length in feet,
- width in meters and height in ells; as though basic instruction
- manuals demanded a knowledge of five different languages. It is
- no wonder then that we often look into our own immediate past or
- future, last Tuesday or a week from Sunday, with feelings of
- helpless confusion. ...
-
- -- Robert Grudin, `Time and the Art of Living'.
-
- This section describes the textual date representations that GNU
-programs accept. These are the strings you, as a user, can supply as
-arguments to the various programs. The C interface (via the `get_date'
-function) is not described here.
-
-* Menu:
-
-* General date syntax:: Common rules.
-* Calendar date items:: 19 Dec 1994.
-* Time of day items:: 9:20pm.
-* Time zone items:: EST, PDT, GMT.
-* Day of week items:: Monday and others.
-* Relative items in date strings:: next tuesday, 2 years ago.
-* Pure numbers in date strings:: 19931219, 1440.
-* Seconds since the Epoch:: @1078100502.
-* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
-* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
-
-\1f
-File: tar.info, Node: General date syntax, Next: Calendar date items, Up: Date input formats
-
-7.1 General date syntax
-=======================
-
-A "date" is a string, possibly empty, containing many items separated
-by whitespace. The whitespace may be omitted when no ambiguity arises.
-The empty string means the beginning of today (i.e., midnight). Order
-of the items is immaterial. A date string may contain many flavors of
-items:
-
- * calendar date items
-
- * time of day items
-
- * time zone items
-
- * day of the week items
-
- * relative items
-
- * pure numbers.
-
-We describe each of these item types in turn, below.
-
- A few ordinal numbers may be written out in words in some contexts.
-This is most useful for specifying day of the week items or relative
-items (see below). Among the most commonly used ordinal numbers, the
-word `last' stands for -1, `this' stands for 0, and `first' and `next'
-both stand for 1. Because the word `second' stands for the unit of
-time there is no way to write the ordinal number 2, but for convenience
-`third' stands for 3, `fourth' for 4, `fifth' for 5, `sixth' for 6,
-`seventh' for 7, `eighth' for 8, `ninth' for 9, `tenth' for 10,
-`eleventh' for 11 and `twelfth' for 12.
-
- When a month is written this way, it is still considered to be
-written numerically, instead of being "spelled in full"; this changes
-the allowed strings.
-
- In the current implementation, only English is supported for words
-and abbreviations like `AM', `DST', `EST', `first', `January',
-`Sunday', `tomorrow', and `year'.
-
- The output of the `date' command is not always acceptable as a date
-string, not only because of the language problem, but also because
-there is no standard meaning for time zone items like `IST'. When using
-`date' to generate a date string intended to be parsed later, specify a
-date format that is independent of language and that does not use time
-zone items other than `UTC' and `Z'. Here are some ways to do this:
-
- $ LC_ALL=C TZ=UTC0 date
- Mon Mar 1 00:21:42 UTC 2004
- $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
- 2004-03-01 00:21:42Z
- $ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension.
- 2004-02-29 16:21:42,692722128-0800
- $ date --rfc-2822 # a GNU extension
- Sun, 29 Feb 2004 16:21:42 -0800
- $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension.
- 2004-02-29 16:21:42 -0800
- $ date +'@%s.%N' # %s and %N are GNU extensions.
- @1078100502.692722128
-
- Alphabetic case is completely ignored in dates. Comments may be
-introduced between round parentheses, as long as included parentheses
-are properly nested. Hyphens not followed by a digit are currently
-ignored. Leading zeros on numbers are ignored.
-
- Invalid dates like `2005-02-29' or times like `24:00' are rejected.
-In the typical case of a host that does not support leap seconds, a
-time like `23:59:60' is rejected even if it corresponds to a valid leap
-second.
-
-\1f
-File: tar.info, Node: Calendar date items, Next: Time of day items, Prev: General date syntax, Up: Date input formats
-
-7.2 Calendar date items
-=======================
-
-A "calendar date item" specifies a day of the year. It is specified
-differently, depending on whether the month is specified numerically or
-literally. All these strings specify the same calendar date:
-
- 1972-09-24 # ISO 8601.
- 72-9-24 # Assume 19xx for 69 through 99,
- # 20xx for 00 through 68.
- 72-09-24 # Leading zeros are ignored.
- 9/24/72 # Common U.S. writing.
- 24 September 1972
- 24 Sept 72 # September has a special abbreviation.
- 24 Sep 72 # Three-letter abbreviations always allowed.
- Sep 24, 1972
- 24-sep-72
- 24sep72
-
- The year can also be omitted. In this case, the last specified year
-is used, or the current year if none. For example:
-
- 9/24
- sep 24
-
- Here are the rules.
-
- For numeric months, the ISO 8601 format `YEAR-MONTH-DAY' is allowed,
-where YEAR is any positive number, MONTH is a number between 01 and 12,
-and DAY is a number between 01 and 31. A leading zero must be present
-if a number is less than ten. If YEAR is 68 or smaller, then 2000 is
-added to it; otherwise, if YEAR is less than 100, then 1900 is added to
-it. The construct `MONTH/DAY/YEAR', popular in the United States, is
-accepted. Also `MONTH/DAY', omitting the year.
-
- Literal months may be spelled out in full: `January', `February',
-`March', `April', `May', `June', `July', `August', `September',
-`October', `November' or `December'. Literal months may be abbreviated
-to their first three letters, possibly followed by an abbreviating dot.
-It is also permitted to write `Sept' instead of `September'.
-
- When months are written literally, the calendar date may be given as
-any of the following:
-
- DAY MONTH YEAR
- DAY MONTH
- MONTH DAY YEAR
- DAY-MONTH-YEAR
-
- Or, omitting the year:
-
- MONTH DAY
-
-\1f
-File: tar.info, Node: Time of day items, Next: Time zone items, Prev: Calendar date items, Up: Date input formats
-
-7.3 Time of day items
-=====================
-
-A "time of day item" in date strings specifies the time on a given day.
-Here are some examples, all of which represent the same time:
-
- 20:02:00.000000
- 20:02
- 8:02pm
- 20:02-0500 # In EST (U.S. Eastern Standard Time).
-
- More generally, the time of day may be given as
-`HOUR:MINUTE:SECOND', where HOUR is a number between 0 and 23, MINUTE
-is a number between 0 and 59, and SECOND is a number between 0 and 59
-possibly followed by `.' or `,' and a fraction containing one or more
-digits. Alternatively, `:SECOND' can be omitted, in which case it is
-taken to be zero. On the rare hosts that support leap seconds, SECOND
-may be 60.
-
- If the time is followed by `am' or `pm' (or `a.m.' or `p.m.'), HOUR
-is restricted to run from 1 to 12, and `:MINUTE' may be omitted (taken
-to be zero). `am' indicates the first half of the day, `pm' indicates
-the second half of the day. In this notation, 12 is the predecessor of
-1: midnight is `12am' while noon is `12pm'. (This is the zero-oriented
-interpretation of `12am' and `12pm', as opposed to the old tradition
-derived from Latin which uses `12m' for noon and `12pm' for midnight.)
-
- The time may alternatively be followed by a time zone correction,
-expressed as `SHHMM', where S is `+' or `-', HH is a number of zone
-hours and MM is a number of zone minutes. You can also separate HH
-from MM with a colon. When a time zone correction is given this way, it
-forces interpretation of the time relative to Coordinated Universal
-Time (UTC), overriding any previous specification for the time zone or
-the local time zone. For example, `+0530' and `+05:30' both stand for
-the time zone 5.5 hours ahead of UTC (e.g., India). The MINUTE part of
-the time of day may not be elided when a time zone correction is used.
-This is the best way to specify a time zone correction by fractional
-parts of an hour.
-
- Either `am'/`pm' or a time zone correction may be specified, but not
-both.
-
-\1f
-File: tar.info, Node: Time zone items, Next: Day of week items, Prev: Time of day items, Up: Date input formats
-
-7.4 Time zone items
-===================
-
-A "time zone item" specifies an international time zone, indicated by a
-small set of letters, e.g., `UTC' or `Z' for Coordinated Universal
-Time. Any included periods are ignored. By following a
-non-daylight-saving time zone by the string `DST' in a separate word
-(that is, separated by some white space), the corresponding daylight
-saving time zone may be specified. Alternatively, a
-non-daylight-saving time zone can be followed by a time zone
-correction, to add the two values. This is normally done only for
-`UTC'; for example, `UTC+05:30' is equivalent to `+05:30'.
-
- Time zone items other than `UTC' and `Z' are obsolescent and are not
-recommended, because they are ambiguous; for example, `EST' has a
-different meaning in Australia than in the United States. Instead,
-it's better to use unambiguous numeric time zone corrections like
-`-0500', as described in the previous section.
-
- If neither a time zone item nor a time zone correction is supplied,
-time stamps are interpreted using the rules of the default time zone
-(*note Specifying time zone rules::).
-
-\1f
-File: tar.info, Node: Day of week items, Next: Relative items in date strings, Prev: Time zone items, Up: Date input formats
-
-7.5 Day of week items
-=====================
-
-The explicit mention of a day of the week will forward the date (only
-if necessary) to reach that day of the week in the future.
-
- Days of the week may be spelled out in full: `Sunday', `Monday',
-`Tuesday', `Wednesday', `Thursday', `Friday' or `Saturday'. Days may
-be abbreviated to their first three letters, optionally followed by a
-period. The special abbreviations `Tues' for `Tuesday', `Wednes' for
-`Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed.
-
- A number may precede a day of the week item to move forward
-supplementary weeks. It is best used in expression like `third
-monday'. In this context, `last DAY' or `next DAY' is also acceptable;
-they move one week before or after the day that DAY by itself would
-represent.
-
- A comma following a day of the week item is ignored.
-
-\1f
-File: tar.info, Node: Relative items in date strings, Next: Pure numbers in date strings, Prev: Day of week items, Up: Date input formats
-
-7.6 Relative items in date strings
-==================================
-
-"Relative items" adjust a date (or the current date if none) forward or
-backward. The effects of relative items accumulate. Here are some
-examples:
-
- 1 year
- 1 year ago
- 3 years
- 2 days
-
- The unit of time displacement may be selected by the string `year'
-or `month' for moving by whole years or months. These are fuzzy units,
-as years and months are not all of equal duration. More precise units
-are `fortnight' which is worth 14 days, `week' worth 7 days, `day'
-worth 24 hours, `hour' worth 60 minutes, `minute' or `min' worth 60
-seconds, and `second' or `sec' worth one second. An `s' suffix on
-these units is accepted and ignored.
-
- The unit of time may be preceded by a multiplier, given as an
-optionally signed number. Unsigned numbers are taken as positively
-signed. No number at all implies 1 for a multiplier. Following a
-relative item by the string `ago' is equivalent to preceding the unit
-by a multiplier with value -1.
-
- The string `tomorrow' is worth one day in the future (equivalent to
-`day'), the string `yesterday' is worth one day in the past (equivalent
-to `day ago').
-
- The strings `now' or `today' are relative items corresponding to
-zero-valued time displacement, these strings come from the fact a
-zero-valued time displacement represents the current time when not
-otherwise changed by previous items. They may be used to stress other
-items, like in `12:00 today'. The string `this' also has the meaning
-of a zero-valued time displacement, but is preferred in date strings
-like `this thursday'.
-
- When a relative item causes the resulting date to cross a boundary
-where the clocks were adjusted, typically for daylight saving time, the
-resulting date and time are adjusted accordingly.
-
- The fuzz in units can cause problems with relative items. For
-example, `2003-07-31 -1 month' might evaluate to 2003-07-01, because
-2003-06-31 is an invalid date. To determine the previous month more
-reliably, you can ask for the month before the 15th of the current
-month. For example:
-
- $ date -R
- Thu, 31 Jul 2003 13:02:39 -0700
- $ date --date='-1 month' +'Last month was %B?'
- Last month was July?
- $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
- Last month was June!
-
- Also, take care when manipulating dates around clock changes such as
-daylight saving leaps. In a few cases these have added or subtracted
-as much as 24 hours from the clock, so it is often wise to adopt
-universal time by setting the `TZ' environment variable to `UTC0'
-before embarking on calendrical calculations.
-
-\1f
-File: tar.info, Node: Pure numbers in date strings, Next: Seconds since the Epoch, Prev: Relative items in date strings, Up: Date input formats
-
-7.7 Pure numbers in date strings
-================================
-
-The precise interpretation of a pure decimal number depends on the
-context in the date string.
-
- If the decimal number is of the form YYYYMMDD and no other calendar
-date item (*note Calendar date items::) appears before it in the date
-string, then YYYY is read as the year, MM as the month number and DD as
-the day of the month, for the specified calendar date.
-
- If the decimal number is of the form HHMM and no other time of day
-item appears before it in the date string, then HH is read as the hour
-of the day and MM as the minute of the hour, for the specified time of
-day. MM can also be omitted.
-
- If both a calendar date and a time of day appear to the left of a
-number in the date string, but no relative item, then the number
-overrides the year.
-
-\1f
-File: tar.info, Node: Seconds since the Epoch, Next: Specifying time zone rules, Prev: Pure numbers in date strings, Up: Date input formats
-
-7.8 Seconds since the Epoch
-===========================
-
-If you precede a number with `@', it represents an internal time stamp
-as a count of seconds. The number can contain an internal decimal
-point (either `.' or `,'); any excess precision not supported by the
-internal representation is truncated toward minus infinity. Such a
-number cannot be combined with any other date item, as it specifies a
-complete time stamp.
-
- Internally, computer times are represented as a count of seconds
-since an epoch--a well-defined point of time. On GNU and POSIX
-systems, the epoch is 1970-01-01 00:00:00 UTC, so `@0' represents this
-time, `@1' represents 1970-01-01 00:00:01 UTC, and so forth. GNU and
-most other POSIX-compliant systems support such times as an extension
-to POSIX, using negative counts, so that `@-1' represents 1969-12-31
-23:59:59 UTC.
-
- Traditional Unix systems count seconds with 32-bit two's-complement
-integers and can represent times from 1901-12-13 20:45:52 through
-2038-01-19 03:14:07 UTC. More modern systems use 64-bit counts of
-seconds with nanosecond subcounts, and can represent all the times in
-the known lifetime of the universe to a resolution of 1 nanosecond.
-
- On most hosts, these counts ignore the presence of leap seconds.
-For example, on most hosts `@915148799' represents 1998-12-31 23:59:59
-UTC, `@915148800' represents 1999-01-01 00:00:00 UTC, and there is no
-way to represent the intervening leap second 1998-12-31 23:59:60 UTC.
-
-\1f
-File: tar.info, Node: Specifying time zone rules, Next: Authors of get_date, Prev: Seconds since the Epoch, Up: Date input formats
-
-7.9 Specifying time zone rules
-==============================
-
-Normally, dates are interpreted using the rules of the current time
-zone, which in turn are specified by the `TZ' environment variable, or
-by a system default if `TZ' is not set. To specify a different set of
-default time zone rules that apply just to one date, start the date
-with a string of the form `TZ="RULE"'. The two quote characters (`"')
-must be present in the date, and any quotes or backslashes within RULE
-must be escaped by a backslash.
-
- For example, with the GNU `date' command you can answer the question
-"What time is it in New York when a Paris clock shows 6:30am on October
-31, 2004?" by using a date beginning with `TZ="Europe/Paris"' as shown
-in the following shell transcript:
-
- $ export TZ="America/New_York"
- $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
- Sun Oct 31 01:30:00 EDT 2004
-
- In this example, the `--date' operand begins with its own `TZ'
-setting, so the rest of that operand is processed according to
-`Europe/Paris' rules, treating the string `2004-10-31 06:30' as if it
-were in Paris. However, since the output of the `date' command is
-processed according to the overall time zone rules, it uses New York
-time. (Paris was normally six hours ahead of New York in 2004, but
-this example refers to a brief Halloween period when the gap was five
-hours.)
-
- A `TZ' value is a rule that typically names a location in the `tz'
-database (http://www.twinsun.com/tz/tz-link.htm). A recent catalog of
-location names appears in the TWiki Date and Time Gateway
-(http://twiki.org/cgi-bin/xtra/tzdate). A few non-GNU hosts require a
-colon before a location name in a `TZ' setting, e.g.,
-`TZ=":America/New_York"'.
-
- The `tz' database includes a wide variety of locations ranging from
-`Arctic/Longyearbyen' to `Antarctica/South_Pole', but if you are at sea
-and have your own private time zone, or if you are using a non-GNU host
-that does not support the `tz' database, you may need to use a POSIX
-rule instead. Simple POSIX rules like `UTC0' specify a time zone
-without daylight saving time; other rules can specify simple daylight
-saving regimes. *Note Specifying the Time Zone with `TZ': (libc)TZ
-Variable.
-
-\1f
-File: tar.info, Node: Authors of get_date, Prev: Specifying time zone rules, Up: Date input formats
-
-7.10 Authors of `get_date'
-==========================
-
-`get_date' was originally implemented by Steven M. Bellovin
-(<smb@research.att.com>) while at the University of North Carolina at
-Chapel Hill. The code was later tweaked by a couple of people on
-Usenet, then completely overhauled by Rich $alz (<rsalz@bbn.com>) and
-Jim Berets (<jberets@bbn.com>) in August, 1990. Various revisions for
-the GNU system were made by David MacKenzie, Jim Meyering, Paul Eggert
-and others.
-
- This chapter was originally produced by Franc,ois Pinard
-(<pinard@iro.umontreal.ca>) from the `getdate.y' source code, and then
-edited by K. Berry (<kb@cs.umb.edu>).
-
-\1f
-File: tar.info, Node: Formats, Next: Media, Prev: Date input formats, Up: Top
-
-8 Controlling the Archive Format
-********************************
-
-Due to historical reasons, there are several formats of tar archives.
-All of them are based on the same principles, but have some subtle
-differences that often make them incompatible with each other.
-
- GNU tar is able to create and handle archives in a variety of
-formats. The most frequently used formats are (in alphabetical order):
-
-gnu
- Format used by GNU `tar' versions up to 1.13.25. This format
- derived from an early POSIX standard, adding some improvements
- such as sparse file handling and incremental archives.
- Unfortunately these features were implemented in a way
- incompatible with other archive formats.
-
- Archives in `gnu' format are able to hold file names of unlimited
- length.
-
-oldgnu
- Format used by GNU `tar' of versions prior to 1.12.
-
-v7
- Archive format, compatible with the V7 implementation of tar. This
- format imposes a number of limitations. The most important of them
- are:
-
- 1. The maximum length of a file name is limited to 99 characters.
-
- 2. The maximum length of a symbolic link is limited to 99
- characters.
-
- 3. It is impossible to store special files (block and character
- devices, fifos etc.)
-
- 4. Maximum value of user or group ID is limited to 2097151
- (7777777 octal)
-
- 5. V7 archives do not contain symbolic ownership information
- (user and group name of the file owner).
-
- This format has traditionally been used by Automake when producing
- Makefiles. This practice will change in the future, in the
- meantime, however this means that projects containing file names
- more than 99 characters long will not be able to use GNU `tar'
- 1.20 and Automake prior to 1.9.
-
-ustar
- Archive format defined by POSIX.1-1988 specification. It stores
- symbolic ownership information. It is also able to store special
- files. However, it imposes several restrictions as well:
-
- 1. The maximum length of a file name is limited to 256
- characters, provided that the file name can be split at a
- directory separator in two parts, first of them being at most
- 155 bytes long. So, in most cases the maximum file name
- length will be shorter than 256 characters.
-
- 2. The maximum length of a symbolic link name is limited to 100
- characters.
-
- 3. Maximum size of a file the archive is able to accommodate is
- 8GB
-
- 4. Maximum value of UID/GID is 2097151.
-
- 5. Maximum number of bits in device major and minor numbers is
- 21.
-
-star
- Format used by Jo"rg Schilling `star' implementation. GNU `tar'
- is able to read `star' archives but currently does not produce
- them.
-
-posix
- Archive format defined by POSIX.1-2001 specification. This is the
- most flexible and feature-rich format. It does not impose any
- restrictions on file sizes or file name lengths. This format is
- quite recent, so not all tar implementations are able to handle it
- properly. However, this format is designed in such a way that any
- tar implementation able to read `ustar' archives will be able to
- read most `posix' archives as well, with the only exception that
- any additional information (such as long file names etc.) will in
- such case be extracted as plain text files along with the files it
- refers to.
-
- This archive format will be the default format for future versions
- of GNU `tar'.
-
-
- The following table summarizes the limitations of each of these
-formats:
-
-Format UID File Size File Name Devn
---------------------------------------------------------------------
-gnu 1.8e19 Unlimited Unlimited 63
-oldgnu 1.8e19 Unlimited Unlimited 63
-v7 2097151 8GB 99 n/a
-ustar 2097151 8GB 256 21
-posix Unlimited Unlimited Unlimited Unlimited
-
- The default format for GNU `tar' is defined at compilation time.
-You may check it by running `tar --help', and examining the last lines
-of its output. Usually, GNU `tar' is configured to create archives in
-`gnu' format, however, future version will switch to `posix'.
-
-* Menu:
-
-* Compression:: Using Less Space through Compression
-* Attributes:: Handling File Attributes
-* Portability:: Making `tar' Archives More Portable
-* cpio:: Comparison of `tar' and `cpio'
-
-\1f
-File: tar.info, Node: Compression, Next: Attributes, Up: Formats
-
-8.1 Using Less Space through Compression
-========================================
-
-* Menu:
-
-* gzip:: Creating and Reading Compressed Archives
-* sparse:: Archiving Sparse Files
-
-\1f
-File: tar.info, Node: gzip, Next: sparse, Up: Compression
-
-8.1.1 Creating and Reading Compressed Archives
-----------------------------------------------
-
-GNU `tar' is able to create and read compressed archives. It supports
-`gzip', `bzip2' and `lzma' compression programs. For backward
-compatibility, it also supports `compress' command, although we
-strongly recommend against using it, because it is by far less
-effective than other compression programs(1).
-
- Creating a compressed archive is simple: you just specify a
-"compression option" along with the usual archive creation commands.
-The compression option is `-z' (`--gzip') to create a `gzip' compressed
-archive, `-j' (`--bzip2') to create a `bzip2' compressed archive,
-`--lzma' to create an LZMA compressed archive and `-Z' (`--compress')
-to use `compress' program. For example:
-
- $ tar cfz archive.tar.gz .
-
- You can also let GNU `tar' select the compression program basing on
-the suffix of the archive file name. This is done using
-`--auto-compress' (`-a') command line option. For example, the
-following invocation will use `bzip2' for compression:
-
- $ tar cfa archive.tar.bz2 .
-
-whereas the following one will use `lzma':
-
- $ tar cfa archive.tar.lzma .
-
- For a complete list of file name suffixes recognized by GNU `tar',
-*note auto-compress::.
-
- Reading compressed archive is even simpler: you don't need to specify
-any additional options as GNU `tar' recognizes its format
-automatically. Thus, the following commands will list and extract the
-archive created in previous example:
-
- # List the compressed archive
- $ tar tf archive.tar.gz
- # Extract the compressed archive
- $ tar xf archive.tar.gz
-
- The only case when you have to specify a decompression option while
-reading the archive is when reading from a pipe or from a tape drive
-that does not support random access. However, in this case GNU `tar'
-will indicate which option you should use. For example:
-
- $ cat archive.tar.gz | tar tf -
- tar: Archive is compressed. Use -z option
- tar: Error is not recoverable: exiting now
-
- If you see such diagnostics, just add the suggested option to the
-invocation of GNU `tar':
-
- $ cat archive.tar.gz | tar tfz -
-
- Notice also, that there are several restrictions on operations on
-compressed archives. First of all, compressed archives cannot be
-modified, i.e., you cannot update (`--update' (`-u')) them or delete
-(`--delete') members from them or add (`--append' (`-r')) members to
-them. Likewise, you cannot append another `tar' archive to a
-compressed archive using `--concatenate' (`-A')). Secondly,
-multi-volume archives cannot be compressed.
-
- The following table summarizes compression options used by GNU `tar'.
-
-`--auto-compress'
-`-a'
- Select a compression program to use by the archive file name
- suffix. The following suffixes are recognized:
-
- Suffix Compression program
- --------------------------------------------------------------
- `.gz' `gzip'
- `.tgz' `gzip'
- `.taz' `gzip'
- `.Z' `compress'
- `.taZ' `compress'
- `.bz2' `bzip2'
- `.tz2' `bzip2'
- `.tbz2' `bzip2'
- `.tbz' `bzip2'
- `.lzma' `lzma'
- `.tlz' `lzma'
-
-`-z'
-`--gzip'
-`--ungzip'
- Filter the archive through `gzip'.
-
- You can use `--gzip' and `--gunzip' on physical devices (tape
- drives, etc.) and remote files as well as on normal files; data to
- or from such devices or remote files is reblocked by another copy
- of the `tar' program to enforce the specified (or default) record
- size. The default compression parameters are used; if you need to
- override them, set `GZIP' environment variable, e.g.:
-
- $ GZIP=--best tar cfz archive.tar.gz subdir
-
- Another way would be to avoid the `--gzip' (`--gunzip',
- `--ungzip', `-z') option and run `gzip' explicitly:
-
- $ tar cf - subdir | gzip --best -c - > archive.tar.gz
-
- About corrupted compressed archives: `gzip''ed files have no
- redundancy, for maximum compression. The adaptive nature of the
- compression scheme means that the compression tables are implicitly
- spread all over the archive. If you lose a few blocks, the dynamic
- construction of the compression tables becomes unsynchronized, and
- there is little chance that you could recover later in the archive.
-
- There are pending suggestions for having a per-volume or per-file
- compression in GNU `tar'. This would allow for viewing the
- contents without decompression, and for resynchronizing
- decompression at every volume or file, in case of corrupted
- archives. Doing so, we might lose some compressibility. But this
- would have make recovering easier. So, there are pros and cons.
- We'll see!
-
-`-j'
-`--bzip2'
- Filter the archive through `bzip2'. Otherwise like `--gzip'.
-
-`--lzma'
- Filter the archive through `lzma'. Otherwise like `--gzip'.
-
-`-Z'
-`--compress'
-`--uncompress'
- Filter the archive through `compress'. Otherwise like `--gzip'.
-
-`--use-compress-program=PROG'
- Use external compression program PROG. Use this option if you
- have a compression program that GNU `tar' does not support. There
- are two requirements to which PROG should comply:
-
- First, when called without options, it should read data from
- standard input, compress it and output it on standard output.
-
- Secondly, if called with `-d' argument, it should do exactly the
- opposite, i.e., read the compressed data from the standard input
- and produce uncompressed data on the standard output.
-
- The `--use-compress-program' option, in particular, lets you
-implement your own filters, not necessarily dealing with
-compression/decompression. For example, suppose you wish to implement
-PGP encryption on top of compression, using `gpg' (*note gpg:
-(gpg)Top.). The following script does that:
-
- #! /bin/sh
- case $1 in
- -d) gpg --decrypt - | gzip -d -c;;
- '') gzip -c | gpg -s ;;
- *) echo "Unknown option $1">&2; exit 1;;
- esac
-
- Suppose you name it `gpgz' and save it somewhere in your `PATH'.
-Then the following command will create a compressed archive signed with
-your private key:
-
- $ tar -cf foo.tar.gpgz --use-compress=gpgz .
-
-Likewise, the following command will list its contents:
-
- $ tar -tf foo.tar.gpgz --use-compress=gpgz .
-
- ---------- Footnotes ----------
-
- (1) It also had patent problems in the past.
-
projects / tar / blobdiff