This is tar.info, produced by makeinfo version 4.13 from tar.texi.
-This manual is for GNU `tar' (version 1.22, 5 March 2009), which
+This manual is for GNU `tar' (version 1.27.1, 24 September 2013), which
creates and extracts files from archives.
- Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003,
-2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
+ Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2013 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".
+ Version 1.3 or any later version published by the Free Software
+ Foundation; with the Invariant Sections being "GNU General Public
+ License", 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."
+ and modify this GNU manual."
INFO-DIR-SECTION Archiving
START-INFO-DIR-ENTRY
GNU tar: an archiver tool
*************************
-This manual is for GNU `tar' (version 1.22, 5 March 2009), which
+This manual is for GNU `tar' (version 1.27.1, 24 September 2013), which
creates and extracts files from archives.
- Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003,
-2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
+ Copyright (C) 1992, 1994-1997, 1999-2001, 2003-2013 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".
+ Version 1.3 or any later version published by the Free Software
+ Foundation; with the Invariant Sections being "GNU General Public
+ License", 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."
+ and modify this GNU manual."
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.
* Date input formats::
* Formats::
* Media::
+* Reliability and security::
Appendices
* Tar Internals::
* Genfile::
* Free Software Needs Free Documentation::
-* Copying This Manual::
+* GNU Free Documentation License::
* Index of Command Line Options::
* Index::
* defaults::
* verbose::
* checkpoints::
+* warnings::
* interactive::
The Three Option Styles
* 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.
+* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al.
Controlling the Archive Format
* gzip:: Creating and Reading Compressed Archives
* sparse:: Archiving Sparse Files
+Creating and Reading Compressed Archives
+
+* lbzip2:: Using lbzip2 with GNU `tar'.
+
Making `tar' Archives More Portable
* Portable Names:: Portable Names
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
+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.
(`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
+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::.)
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.22
+to create version 1.12. The book for versions from 1.14 up to 1.27.1
were edited by the current maintainer, Sergey Poznyakoff.
For version 1.12, Daniel Hagerty contributed a great deal of
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. .
+possible, in order to reproduce it.
\1f
File: tar.info, Node: Tutorial, Next: tar invocation, Prev: Introduction, Up: Top
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
+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
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
+determined at 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
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
+ 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
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.
+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'.
jazz
This example is just like the example we showed which did not use
-`--verbose', except that `tar' generated the remaining lines .
+`--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
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.
+place the archive outside of the directory being dumped.)
\1f
File: tar.info, Node: list, Next: extract, Prev: create, Up: Tutorial
look like:
$ tar --list --verbose --file=collection.tar folk
- -rw-r--r-- myself user 62 1990-05-23 10:55 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'
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
+ $ tar --create --verbose --file archive /etc/mail
+ tar: Removing leading '/' from member names
/etc/mail/
/etc/mail/sendmail.cf
/etc/mail/aliases
- $ tar tf archive
+ $ tar --test --file archive
etc/mail/
etc/mail/sendmail.cf
etc/mail/aliases
`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
+ 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.
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
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
+ -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
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
+ -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
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/blues
practice/folk
practice/jazz
- practice/rock
Likewise, if you try to use this command,
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
* Synopsis::
* using tar options::
* Styles::
-* All Options::
-* help::
-* defaults::
-* verbose::
-* checkpoints::
-* interactive::
+* All Options:: All `tar' Options.
+* help:: Where to Get Help.
+* defaults:: What are the Default Values.
+* verbose:: Checking `tar' progress.
+* checkpoints:: Checkpoints.
+* warnings:: Controlling Warning Messages.
+* interactive:: Asking for Confirmation During Operations.
+* external:: Running External Commands.
\1f
File: tar.info, Node: Synopsis, Next: using tar options, Up: tar invocation
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.
+reasons correspond to bad usage, that is, when the `tar' command line
+is improperly written. Errors may be encountered later, while
+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 be 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:
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
+one operation as an argument to the `tar' command (the corresponding
+options 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
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 must take an argument(1). 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
* Old Options:: Old Option Style
* Mixing:: Mixing Option Styles
+ ---------- Footnotes ----------
+
+ (1) 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.
+
\1f
File: tar.info, Node: Long Options, Next: Short Options, Up: Styles
3.3.3 Old Option Style
----------------------
- _(This message will disappear, once this node revised.)_
+As far as we know, all `tar' programs, GNU and non-GNU, support "old
+options": that is, if the first argument does not start with `-', it is
+assumed to specify option letters. GNU `tar' supports old options not
+only for historical reasons, but also because many people are used to
+them. If the first argument does not start with a dash, you are
+announcing the old option style instead of the short option style; old
+options are decoded differently.
-Like short options, "old options" are single letters. However, old
+ 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'.
+spaces separating them or dashes preceding them. 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.
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.
+ The old style syntax can make 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.
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 -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
=====================
The coming manual sections contain an alphabetical listing of all `tar'
-operations and options, with brief descriptions and cross references to
+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
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::.
+ Deletes members from the archive. Don't try this on an archive on
+ a tape! *Note delete::.
`--diff'
`-d'
`--absolute-names'
`-P'
Normally when creating an archive, `tar' strips an initial `/'
- from member names. This option disables that behavior. *Note
- absolute::.
+ from member names, and when extracting from an archive `tar'
+ treats names specially if they have initial `/' or internal `..'.
+ This option disables that behavior. *Note absolute::.
`--after-date'
(See `--newer', *note after::)
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
+ 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=replace', but this may change in the future as
support for `--atime-preserve=system' improves.
- If your operating system does not support
+ If your operating or file 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
+ times reliably 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.
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'
+ list of actions on each checkpoint, see `--checkpoint-action'
below. For a detailed description, see *note checkpoints::.
`--checkpoint-action=ACTION'
`--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::.
+ When reading or writing a file to be archived, `tar' accesses the
+ file that a symbolic link points to, rather than the symlink
+ itself. *Note dereference::.
`--directory=DIR'
`-C DIR'
When performing operations, `tar' will skip files that match
PATTERN. *Note exclude::.
+`--exclude-backups'
+ Exclude backup and lock files. *Note exclude-backups: exclude.
+
`--exclude-from=FILE'
`-X FILE'
Similar to `--exclude', except `tar' will use the list of patterns
tag file, but still dump the directory node and the tag file
itself.
- *Note exclude::.
+ *Note exclude-caches: exclude.
`--exclude-caches-under'
Exclude from dump any directory containing a valid cache directory
`--exclude-tag=FILE'
Exclude from dump any directory containing file named FILE, but
- dump the directory node and FILE itself. *Note exclude::.
+ dump the directory node and FILE itself. *Note exclude-tag:
+ 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::.
+ named FILE, but dump the directory node itself. *Note
+ exclude-tag-under: exclude.
`--exclude-tag-all=FILE'
Exclude from dump any directory containing file named FILE. *Note
- exclude::.
+ exclude-tag-all: exclude.
`--exclude-vcs'
Exclude from dump directories and files, that are internal for some
widely used version control systems.
- *Note exclude::.
+ *Note exclude-vcs: exclude.
`--file=ARCHIVE'
`-f ARCHIVE'
*Note Formats::, for a detailed discussion of these formats.
+`--full-time'
+ This option instructs `tar' to print file times to their full
+ resolution. Usually this means 1-second resolution, but that
+ depends on the underlying file system. The `--full-time' option
+ takes effect only when detailed output (verbosity level 2 or
+ higher) has been requested using the `--verbose' option, e.g.,
+ when listing or extracting archives:
+
+ $ tar -t -v --full-time -f archive.tar
+
+ or, when creating an archive:
+
+ $ tar -c -vv --full-time -f archive.tar .
+
+ Notice, thar when creating the archive you need to specify
+ `--verbose' twice to get a detailed output (*note verbose
+ tutorial::).
+
`--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::.
+ rather than the group from the source file. GROUP can specify a
+ symbolic name, or a numeric ID, or both as NAME:ID. *Note
+ override::.
Also see the comments for the `--owner=USER' option.
`--ignore-failed-read'
Do not exit unsuccessfully merely because an unreadable file was
- encountered. *Note Reading::.
+ encountered. *Note Ignore Failed Read::.
`--ignore-zeros'
`-i'
`--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.
+`--info-script=COMMAND'
+`--new-volume-script=COMMAND'
+`-F COMMAND'
+ When `tar' is performing multi-tape backups, COMMAND is run at the
+ end of each tape. If it exits with nonzero status, `tar' fails
+ immediately. *Note info-script::, for a detailed discussion of
+ this feature.
`--interactive'
`--confirmation'
performing potentially destructive options, such as overwriting
files. *Note interactive::.
+`--keep-directory-symlink'
+ This option changes the behavior of tar when it encounters a
+ symlink with the same name as the directory that it is about to
+ extract. By default, in this case tar would first remove the
+ symlink and then proceed extracting the directory.
+
+ The `--keep-directory-symlink' option disables this behavior and
+ instructs tar to follow symlinks to directories when extracting
+ from the archive.
+
+ It is mainly intended to provide compatibility with the Slackware
+ installation scripts.
+
`--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::.
+ archive. Return error if such files exist. See also *note
+ --skip-old-files::.
+
+ *Note Keep Old Files::.
`--label=NAME'
`-V NAME'
will only operate on archives that have a label matching the
pattern specified in NAME. *Note Tape Files::.
+`--level=N'
+ Force incremental backup of level N. As of GNU `tar' version
+ 1.27.1, the option `--level=0' truncates the snapshot file,
+ thereby forcing the level 0 dump. Other values of N are
+ effectively ignored. *Note --level=0::, for details and examples.
+
+ The use of this option is valid only in conjunction with the
+ `--listed-incremental' option. *Note Incremental Dumps::, for a
+ detailed description.
+
`--listed-incremental=SNAPSHOT-FILE'
`-g SNAPSHOT-FILE'
During a `--create' operation, specifies that the archive that
operations, informs `tar' that the archive is in incremental
format. *Note Incremental Dumps::.
+`--lzip'
+ This option tells `tar' to read or write archives through `lzip'.
+ *Note gzip::.
+
`--lzma'
This option tells `tar' to read or write archives through `lzma'.
*Note gzip::.
multi-volume `tar' archive. *Note Using Multiple Tapes::.
`--new-volume-script'
- (see -info-script)
+ (see `--info-script')
`--newer=DATE'
`--after-date=DATE'
from the permissions specified in the archive. This is the
default behavior for ordinary users.
+`--no-seek'
+ The archive media does not support seeks to arbitrary locations.
+ Usually `tar' determines automatically whether the archive can be
+ seeked or not. Use this option to disable this mechanism.
+
`--no-unquote'
Treat all input file or member names literally, do not interpret
escape sequences. *Note input name quoting::.
`--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::.
+ file. USER can specify a symbolic name, or a numeric ID, or both
+ as NAME: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.
+ This option enables creation of the archive in POSIX.1-2001 format
+ (*note posix::) and 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'
Specifies that `tar' should reblock its input, for reading from
pipes on systems with buggy implementations. *Note Reading::.
-`--record-size=SIZE'
+`--record-size=SIZE[SUF]'
Instructs `tar' to use SIZE bytes per record when accessing the
- archive. *Note Blocking Factor::.
+ archive. The argument can be suffixed with a "size suffix", e.g.
+ `--record-size=10K' for 10 Kilobytes. *Note size-suffixes::, for
+ a list of valid suffixes. *Note Blocking Factor::, for a detailed
+ description of this option.
`--recursion'
With this option, `tar' recurses into directories (default).
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.
+ cases when such recognition fails. It takes effect only if the
+ archive is open for reading (e.g. with `--list' or `--extract'
+ options).
`--show-defaults'
Displays the default options used by `tar' and exits successfully.
example of what you can see using this option:
$ tar --show-defaults
- --format=gnu -f- -b20 --quoting-style=escape \
+ --format=gnu -f- -b20 --quoting-style=escape
--rmt-command=/usr/libexec/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. *Note defaults::.
+
`--show-omitted-dirs'
Instructs `tar' to mention the directories it is skipping when
operating on a `tar' archive. *Note show-omitted-dirs::.
+`--show-snapshot-field-ranges'
+ Displays the range of values allowed by this version of `tar' for
+ each field in the snapshot file, then exits successfully. *Note
+ Snapshot Files::.
+
`--show-transformed-names'
`--show-stored-names'
Display file or member names after applying any transformations
the member names stored in the archive, as opposed to the actual
file names. *Note listing member and file names::.
+`--skip-old-files'
+ Do not overwrite existing files when extracting files from an
+ archive. *Note Keep Old Files::.
+
+ This option differs from `--keep-old-files' in that it does not
+ treat such files as an error, instead it just silently avoids
+ overwriting them.
+
+ The `--warning=existing-file' option can be used together with
+ this option to produce warning messages about existing old files
+ (*note warnings::).
+
`--sparse'
`-S'
Invokes a GNU extension when adding files to an archive that
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'
+`--tape-length=NUM[SUF]'
+`-L NUM[SUF]'
Specifies the length of tapes that `tar' is writing as being
- NUM x 1024 bytes long. *Note Using Multiple Tapes::.
+ NUM x 1024 bytes long. If optional SUF is given, it specifies a
+ multiplicative factor to be used instead of 1024. For example,
+ `-L2M' means 2 megabytes. *Note size-suffixes::, for a list of
+ allowed suffixes. *Note Using Multiple Tapes::, for a detailed
+ discussion of this option.
`--test-label'
Reads the volume label. If an argument is specified, test whether
`--show-transformed-names' option (*note show-transformed-names::).
`--uncompress'
- (See `--compress'. *note gzip::)
+ (See `--compress', *note gzip::)
`--ungzip'
- (See `--gzip'. *note gzip::)
+ (See `--gzip', *note gzip::)
`--unlink-first'
`-U'
of which volume of a multi-volume archive it is working in FILE.
*Note volno-file::.
+`--warning=KEYWORD'
+ Enable or disable warning messages identified by KEYWORD. The
+ messages are suppressed if KEYWORD is prefixed with `no-'. *Note
+ warnings::.
+
`--wildcards'
Use wildcards when matching member names with patterns. *Note
controlling pattern-matching::.
standard output, and then exit successfully. For example,
`tar --version' might print:
- tar (GNU tar) 1.22
- 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>.
+ tar (GNU tar) 1.27.1
+ Copyright (C) 2013 Free Software Foundation, Inc.
+ License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
+ This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Written by John Gilmore and Jay Fenlason.
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.
+`tar' options 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
(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'
+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
use `--show-defaults' option. This will output the values in the form
of `tar' command line options:
- tar --show-defaults
+ $ tar --show-defaults
--format=gnu -f- -b20 --quoting-style=escape
--rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
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
+--verbose' (`tar cvf -', 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.
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
+on the archive. As of now, if the archive is 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
--checkpoint-action=dot'. *Note dot: checkpoints.
\1f
-File: tar.info, Node: checkpoints, Next: interactive, Prev: verbose, Up: tar invocation
+File: tar.info, Node: checkpoints, Next: warnings, Prev: verbose, Up: tar invocation
3.8 Checkpoints
===============
$ tar -c --checkpoint=1000 --checkpoint-action=sleep=30
- Finally, the `exec' action executes a given external program. For
+ Finally, the `exec' action executes a given external command. 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:
+ The supplied command can be any valid command invocation, with or
+without additional command line arguments. If it does contain
+arguments, don't forget to quote it to prevent it from being split by
+the shell. *Note Running External Commands: external, for more detail.
+
+ The command gets a copy of `tar''s environment plus the following
+variables:
`TAR_VERSION'
GNU `tar' version number.
Format of the archive being processed. *Note Formats::, for a
complete list of archive format names.
+ These environment variables can also be passed as arguments to the
+command, provided that they are properly escaped, for example:
+
+ tar -c -f arc.tar \
+ --checkpoint-action='exec=/sbin/cpoint $TAR_FILENAME'
+
+Notice single quotes to prevent variable names from being expanded by
+the shell when invoking `tar'.
+
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
checkpoint frequency (at each 10th record) is assumed.
\1f
-File: tar.info, Node: interactive, Prev: checkpoints, Up: tar invocation
+File: tar.info, Node: warnings, Next: interactive, Prev: checkpoints, Up: tar invocation
-3.9 Asking for Confirmation During Operations
-=============================================
+3.9 Controlling Warning Messages
+================================
+
+Sometimes, while performing the requested task, GNU `tar' notices some
+conditions that are not exactly errors, but which the user should be
+aware of. When this happens, `tar' issues a "warning message"
+describing the condition. Warning messages are output to the standard
+error and they do not affect the exit code of `tar' command.
+
+ GNU `tar' allows the user to suppress some or all of its warning
+messages:
+
+`--warning=KEYWORD'
+ Control display of the warning messages identified by KEYWORD. If
+ KEYWORD starts with the prefix `no-', such messages are
+ suppressed. Otherwise, they are enabled.
+
+ Multiple `--warning' messages accumulate.
+
+ The tables below list allowed values for KEYWORD along with the
+ warning messages they control.
+
+Keywords controlling `tar' operation
+------------------------------------
+
+all
+ Enable all warning messages. This is the default.
+
+none
+ Disable all warning messages.
+
+filename-with-nuls
+ `%s: file name read contains nul character'
+
+alone-zero-block
+ `A lone zero block at %s'
+
+Keywords applicable for `tar --create'
+--------------------------------------
+
+cachedir
+ `%s: contains a cache directory tag %s; %s'
+
+file-shrank
+ `%s: File shrank by %s bytes; padding with zeros'
+
+xdev
+ `%s: file is on a different filesystem; not dumped'
+
+file-ignored
+ `%s: Unknown file type; file ignored'
+ `%s: socket ignored'
+ `%s: door ignored'
+
+file-unchanged
+ `%s: file is unchanged; not dumped'
+
+ignore-archive
+ `%s: file is the archive; not dumped'
+
+file-removed
+ `%s: File removed before we read it'
+
+file-changed
+ `%s: file changed as we read it'
+
+Keywords applicable for `tar --extract'
+---------------------------------------
+
+timestamp
+ `%s: implausibly old time stamp %s'
+ `%s: time stamp %s is %s s in the future'
+
+contiguous-cast
+ `Extracting contiguous files as regular files'
+
+symlink-cast
+ `Attempting extraction of symbolic links as hard links'
+
+unknown-cast
+ `%s: Unknown file type '%c', extracted as normal file'
+
+ignore-newer
+ `Current %s is newer or same age'
+
+unknown-keyword
+ `Ignoring unknown extended header keyword '%s''
+
+decompress-program
+ Controls verbose description of failures occurring when trying to
+ run alternative decompressor programs (*note alternative
+ decompression programs::). This warning is disabled by default
+ (unless `--verbose' is used). A common example of what you can get
+ when using this warning is:
+
+ $ tar --warning=decompress-program -x -f archive.Z
+ tar (child): cannot run compress: No such file or directory
+ tar (child): trying gzip
+
+ This means that `tar' first tried to decompress `archive.Z' using
+ `compress', and, when that failed, switched to `gzip'.
+
+record-size
+ `Record size = %lu blocks'
+
+Keywords controlling incremental extraction:
+--------------------------------------------
+
+rename-directory
+ `%s: Directory has been renamed from %s'
+ `%s: Directory has been renamed'
+
+new-directory
+ `%s: Directory is new'
+
+xdev
+ `%s: directory is on a different device: not purging'
+
+bad-dumpdir
+ `Malformed dumpdir: 'X' never used'
+
+\1f
+File: tar.info, Node: interactive, Next: external, Prev: warnings, Up: tar invocation
+
+3.10 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
named pipe. This has the advantage of letting standard output free to
receive verbose output, all separate from errors.
+\1f
+File: tar.info, Node: external, Prev: interactive, Up: tar invocation
+
+3.11 Running External Commands
+==============================
+
+Certain GNU `tar' operations imply running external commands that you
+supply on the command line. One of such operations is checkpointing,
+described above (*note checkpoint exec::). Another example of this
+feature is the `-I' option, which allows you to supply the program to
+use for compressing or decompressing the archive (*note
+use-compress-program::).
+
+ Whenever such operation is requested, `tar' first splits the
+supplied command into words much like the shell does. It then treats
+the first word as the name of the program or the shell script to execute
+and the rest of words as its command line arguments. The program,
+unless given as an absolute file name, is searched in the shell's
+`PATH'.
+
+ Any additional information is normally supplied to external commands
+in environment variables, specific to each particular operation. For
+example, the `--checkpoint-action=exec' option, defines the
+`TAR_ARCHIVE' variable to the name of the archive being worked upon.
+You can, should the need be, use these variables in the command line of
+the external command. For example:
+
+ $ tar -x -f archive.tar \
+ --checkpoint=exec='printf "%04d in %32s\r" $TAR_CHECKPOINT $TAR_ARCHIVE'
+
+This command prints for each checkpoint its number and the name of the
+archive, using the same output line on the screen.
+
+ Notice the use of single quotes to prevent variable names from being
+expanded by the shell when invoking `tar'.
+
\1f
File: tar.info, Node: operations, Next: Backups, Prev: tar invocation, Up: Top
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
+ tar -cf empty-archive.tar -T /dev/null
`--extract'
`--get'
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'.
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'.
+`practice', the files are `jazz', `blues', `folk', 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
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
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
+only the most recently added copy of a member with the same name as
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.
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.)
+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:
---------- 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
+ (1) Unless you give it `--keep-old-files' (or `--skip-old-files')
+option, or the disk copy is newer than 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.
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
+ -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
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
+ -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
example:
$ tar --extract -vv --occurrence --file=collection.tar blues
- -rw-r--r-- me user 21 1996-09-23 16:44 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.
+ *Note Writing::, for more information on `--extract' and see *note
+-occurrence: Option Summary, for a 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
`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
+the names of all the files in the `practice' directory as file name
arguments:
$ tar --update -v -f collection.tar blues folk rock classical
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
+ 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.
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
+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.
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
+ -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
+ -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':
---------- Footnotes ----------
- (1) This can cause multiple members to have the same name, for
-information on how this affects reading the archive, *note multiple::.
+ (1) This can cause multiple members to have the same name. For
+information on how this affects reading the archive, see *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,
folk
jazz
rock
- $
The `--delete' option has been reported to work properly when `tar'
acts as a filter from `stdin' to `stdout'.
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.
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::.
+this latter goal, see *note verify::.
\1f
File: tar.info, Node: create options, Next: extract options, Prev: Advanced tar, Up: operations
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.
+ Date input formats::) or a name of an 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:
+ The following example will set the modification date to 00:00:00,
+ January 1, 1970:
$ tar -c -f archive.tar --mtime='1970-01-01' .
For example:
$ tar -c -f archive.tar -v --mtime=yesterday .
- tar: Option --mtime: Treating date `yesterday' as 2006-06-20
+ 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.
+ file.
+
+ If USER contains a colon, it is taken to be of the form NAME:ID
+ where a nonempty NAME specifies the user name and a nonempty ID
+ specifies the decimal numeric user ID. If USER does not contain a
+ colon, it is taken to be a user number if it is one or more
+ decimal digits; otherwise it is taken to be a user name.
+
+ If a name is given but no number, the number is inferred from the
+ current host's user database if possible, and the file's user
+ number is used otherwise. If a number is given but no name, the
+ name is inferred from the number if possible, and an empty name is
+ used otherwise. If both name and number are given, the user
+ database is not consulted, and the name and number need not be
+ valid on the current host.
There is no value indicating a missing number, and `0' usually
means `root'. Some people like to force `0' as the value to offer
anonymous archives. For example:
$ tar -c -f archive.tar --owner=0 .
- # Or:
+
+ 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.
+ rather than the group from the source file. As with `--owner',
+ the argument GROUP can be an existing group symbolic name, or a
+ decimal numeric group ID, or NAME:ID.
\1f
File: tar.info, Node: Ignore Failed Read, Prev: override, Up: create options
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
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
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.
+archive member. Instead, it reports an error. For example:
+
+ $ ls
+ blues
+ $ tar -x -k -f archive.tar
+ tar: blues: Cannot open: File exists
+ tar: Exiting with failure status due to previous errors
+
+ If you wish to preserve old files untouched, but don't want `tar' to
+treat them as errors, use the `--skip-old-files' option. This option
+causes `tar' to silently skip extracting over existing files.
To be more aggressive about altering existing files, use the
`--overwrite' option. It causes `tar' to overwrite existing files and
Keep Old Files
..............
+GNU `tar' provides two options to control its actions in a situation
+when it is about to extract a file which already exists on disk.
+
`--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.
+ Do not replace existing files from archive. When such a file is
+ encountered, `tar' issues an error message. Upon end of
+ extraction, `tar' exits with code 2 (*note exit status::).
+
+`--skip-old-files'
+ Do not replace existing files from archive, but do not treat that
+ as error. Such files are silently skipped and do not affect `tar'
+ exit status.
+
+ Additional verbosity can be obtained using
+ `--warning=existing-file' together with that option (*note
+ warnings::).
\1f
File: tar.info, Node: Keep Newer Files, Next: Unlink First, Prev: Keep Old Files, Up: Writing
again.
To correctly restore directory meta-information in such cases, use
-`delay-directory-restore' command line option:
+the `--delay-directory-restore' command line option:
`--delay-directory-restore'
Delays restoring of the modification times and permissions of
`--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
+ 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.
+ files to its standard output. The COMMAND may contain command
+ line arguments (see *note Running External Commands: external, for
+ more detail).
+
+ 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_ATIME'
Time of last access. It is a decimal number, representing seconds
- since the epoch. If the archive provides times with nanosecond
+ since the Epoch. If the archive provides times with nanosecond
precision, the nanoseconds are appended to the timestamp after a
decimal point.
`TAR_GID'
GID of the file owner.
- In addition to these variables, `TAR_VERSION' contains the GNU `tar'
-version number.
+ Additionally, the following variables contain information about tar
+mode and the archive being processed:
+
+`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_VOLUME'
+ Ordinal number of the volume `tar' is processing.
+
+`TAR_FORMAT'
+ Format of the archive being processed. *Note Formats::, for a
+ complete list of archive format names.
+
+ These variables are defined prior to executing the command, so you
+can pass them as arguments, if you prefer. For example, if the command
+PROC takes the member name and size as its arguments, then you could do:
+
+ $ tar -x -f archive.tar \
+ --to-command='proc $TAR_FILENAME $TAR_SIZE'
+
+Notice single quotes to prevent variable names from being expanded by
+the shell when invoking `tar'.
If COMMAND exits with a non-0 status, `tar' will print an error
message similar to the following:
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::.)
+remove unnecessary files from the file system, and then resume the same
+`tar' operation. In this case, `--starting-file' is not necessary.)
+See also *note interactive::, and *note exclude::.
\1f
File: tar.info, Node: Same Order, Prev: Starting File, Up: Scarce
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.
+members appear as having similar names through the side-effect of name
+truncation.
+
+ 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,
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:
+medium is a "pipe":
$ (cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)
$ tar -C sourcedir -cf - . | tar -C targetdir -xf -
-The command also works using short option forms:
+The command also works using long option forms:
$ (cd sourcedir; tar --create --file=- . ) \
| (cd targetdir; tar --extract --file=-)
- # Or:
- $ tar --directory sourcedir --create --file=- . ) \
+
+or
+
+ $ tar --directory sourcedir --create --file=- . \
| tar --directory targetdir --extract --file=-
This is one of the easiest methods to transfer a `tar' archive.
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.
+GNU `tar' is distributed along with the scripts for performing backups
+and restores. 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
+free software, and it is available from `http://www.amanda.org'.
This chapter documents both the provided shell scripts and `tar'
options which are more specific to usage as a backup tool.
--listed-incremental=/var/log/usr.snar-1 \
/usr
+ You can force `level 0' backups either by removing the snapshot file
+before running `tar', or by supplying the `--level=0' option, e.g.:
+
+ $ tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar-0 \
+ --level=0 \
+ /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
+obviously are supposed to be 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
+numbers over time. The solution implemented currently is to consider
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.
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::).
+(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
`--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
+version 1.16.
\1f
File: tar.info, Node: Backup Levels, Next: Backup Parameters, Prev: Incremental Dumps, Up: Backups
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).
+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
(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
+ If the list of individual files 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 scripts access tape device using special "hook functions".
-These functions take a single argument - the name of the tape device.
+These functions take a single argument -- the name of the tape device.
Their names are kept in the following variables:
-- Backup variable: MT_BEGIN
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
+ Following variables keep the names of user hook functions:
-- Backup variable: DUMP_BEGIN
Dump begin function. It is executed before dumping the file
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 `--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:
The dump must be run at HH hours MM minutes.
HH
- The dump must be run at HH hours
+ The dump must be run at HH hours.
now
The dump must be run immediately.
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' a list of "patterns" in its command line. For example,
+running
restore 'albert:*'
`-a'
`--all'
- Restore all file systems and files specified in `backup-specs'
+ Restore all file systems and files specified in `backup-specs'.
`-l LEVEL'
`--level=LEVEL'
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
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
--file=HOSTNAME:/DEV/FILE-NAME
-`tar' will complete the remote connection, if possible, and prompt you
+`tar' will set up 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.
+`--file=@HOSTNAME:/DEV/FILE-NAME', `tar' will attempt to set up the
+remote connection 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
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'
+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.
+where 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
$ tar cf a.tar
tar: Cowardly refusing to create an empty archive
- Try `tar --help' or `tar --usage' for more information.
+ 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.
`little.tgz'. (The `-z' option to `tar' compresses the archive with
`gzip'; *note gzip:: for more information.)
- $ find . -size -400 -print > small-files
+ $ 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)
+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:
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'.
\1f
File: tar.info, Node: nul, Up: files
-6.3.1 `NUL' Terminated File Names
+6.3.1 `NUL'-Terminated File Names
---------------------------------
The `--null' option causes `--files-from=FILE-OF-NAMES' (`-T
`--files-from'.
`--null'
- Only consider `NUL' terminated file names, instead of files that
+ Only consider `NUL'-terminated file names, instead of files that
terminate in a newline.
`--no-null'
`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
+specify that `tar' gets 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
+ $ find . -size +800 -print0 > long-files
$ tar -c -v --null --files-from=long-files --file=big.tar
The `--no-null' option can be used if you need to read both
-zero-terminated and newline-terminated files on the same command line.
+`NUL'-terminated and newline-terminated files on the same command line.
For example, if `flist' is a newline-terminated file, then the
following command can be used to combine it with the above command:
- $ find . -size +800 -print0 |
+ $ find . -size +800 -print0 |
tar -c -f big.tar --null -T - --no-null -T flist
This example uses short options for typographic reasons, to avoid
very long lines.
- GNU `tar' is able to automatically detect null-terminated file
-lists, so it is safe to use them even without the `--null' option. In
-this case `tar' will print a warning and continue reading such a file
-as if `--null' were actually given:
+ GNU `tar' is tries to automatically detect `NUL'-terminated file
+lists, so in many cases it is safe to use them even without the
+`--null' option. In this case `tar' will print a warning and continue
+reading such a file as if `--null' were actually given:
- $ find . -size +800 -print0 | tar -c -f big.tar -T -
+ $ find . -size +800 -print0 | tar -c -f big.tar -T -
tar: -: file name read contains nul character
The null terminator, however, remains in effect only for this
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.
systems: `CVS', `RCS', `SCCS', `SVN', `Arch', `Bazaar',
`Mercurial', and `Darcs'.
- As of version 1.22, the following files are excluded:
+ As of version 1.27.1, 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
- * `CVS/', and everything under it
+ * `.gitignore'
- * `RCS/', and everything under it
+ * `.cvsignore'
- * `SCCS/', and everything under it
+ * `.svn/', and everything under it
- * `.git/', and everything under it
+ * `.arch-ids/', and everything under it
- * `.gitignore'
+ * `{arch}/', and everything under it
- * `.cvsignore'
+ * `=RELEASE-ID'
- * `.svn/', and everything under it
+ * `=meta-update'
- * `.arch-ids/', and everything under it
+ * `=update'
- * `{arch}/', and everything under it
+ * `.bzr'
- * `=RELEASE-ID'
+ * `.bzrignore'
- * `=meta-update'
+ * `.bzrtags'
- * `=update'
+ * `.hg'
- * `.bzr'
+ * `.hgignore'
- * `.bzrignore'
+ * `.hgrags'
- * `.bzrtags'
+ * `_darcs'
- * `.hg'
+`--exclude-backups'
+ Exclude backup and lock files. This option causes exclusion of
+ files that match the following shell globbing patterns:
- * `.hgignore'
+ .#*
- * `.hgrags'
+ *~
+
+ #*#
- * `_darcs'
When creating an archive, the `--exclude-caches' option family
causes `tar' to exclude all directories that contain a "cache directory
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
+ 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'
+ './'
+ './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
===================================
`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 it, 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
+and full file names are part of that information. When storing a file
+to an archive, its file name is recorded in it, 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.
each file name part that matches REGEXP. Both REGEXP and REPLACE are
described in detail in *note The "s" Command: (sed)The "s" Command.
- Any delimiter can be used in lieue of `/', the only requirement being
+ Any delimiter can be used in lieu of `/', the only requirement being
that it be used consistently throughout the expression. For example,
the following two expressions are equivalent:
first.
`i'
- Use case-insensitive matching
+ Use case-insensitive matching.
`x'
REGEXP is an "extended regular expression" (*note Extended regular
/usr/local/lib/libc.so.6 -> /usr/local/libc-2.3.2.so
- This is definitely not desired. To avoid this, the `S' flag are
+ This is definitely not desired. To avoid this, the `S' flag is
used, which excludes symbolic link targets from filename
transformations. The result is:
--show-transformed /lib
drwxr-xr-x root/root 0 2008-07-08 16:20 /usr/local/lib/
-rwxr-xr-x root/root 1250840 2008-05-25 07:44 /usr/local/lib/libc-2.3.2.so
- lrwxrwxrwx root/root 0 2008-06-24 17:12 /usr/local/lib/libc.so.6 ->
- libc-2.3.2.so
+ lrwxrwxrwx root/root 0 2008-06-24 17:12 /usr/local/lib/libc.so.6 \
+ -> libc-2.3.2.so
Unlike `--strip-components', `--transform' can be used in any GNU
`tar' operation mode. For example, the following command adds files to
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
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
+ 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
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
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.
+the `find' (*note find: (find)Top.) 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'.
`--no-recursion'
Prevents `tar' from recursively descending directories.
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'.
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'.
+file will be written in a subdirectory named `red'.
You can use the `--directory' option to make the archive independent
of the original name of the directory holding the files. The following
6.10.2 Absolute File Names
--------------------------
- _(This message will disappear, once this node revised.)_
+By default, GNU `tar' drops a leading `/' on input or output, and
+complains about file names containing a `..' component. There is an
+option that turns off this behavior:
`--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
`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)
+`bin/ls'(1).
+
+ Symbolic links containing `..' or leading `/' can also cause
+problems when extracting, so `tar' normally extracts them last; it may
+create empty files as placeholders during extraction.
If you use the `--absolute-names' (`-P') option, `tar' will do none
of these transformations.
`--absolute-names'
Preserves full file names (including superior directory names) when
- archiving files. Preserves leading slash when extracting files.
+ archiving and extracting files.
`tar' prints out a message about removing the `/' from file names.
$ tar -c -f archive.tar -C / home
+ *Note Integrity::, for some of the security-related implications of
+using this option.
+
---------- Footnotes ----------
(1) A side effect of this is that when `--create' is used with
future, last Tuesday or a week from Sunday, with feelings of
helpless confusion. ...
- -- Robert Grudin, `Time and the Art of Living'.
+ --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.
+arguments to the various programs. The C interface (via the
+`parse_datetime' 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.
+* Time zone items:: EST, PDT, UTC, ...
+* Combined date and time of day items:: 1972-09-24T20:02:00,000000-0500.
* 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.
+* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al.
\1f
File: tar.info, Node: General date syntax, Next: Calendar date items, Up: Date input formats
* time zone items
+ * combined date and time of day items
+
* day of the week items
* relative items
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-3339=ns # --rfc-3339 is a GNU extension.
+ 2004-02-29 16:21:42.692722128-08:00
$ 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.
both.
\1f
-File: tar.info, Node: Time zone items, Next: Day of week items, Prev: Time of day items, Up: Date input formats
+File: tar.info, Node: Time zone items, Next: Combined date and time of day items, Prev: Time of day items, Up: Date input formats
7.4 Time zone items
===================
(*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
+File: tar.info, Node: Combined date and time of day items, Next: Day of week items, Prev: Time zone items, Up: Date input formats
+
+7.5 Combined date and time of day items
+=======================================
-7.5 Day of week items
+The ISO 8601 date and time of day extended format consists of an ISO
+8601 date, a `T' character separator, and an ISO 8601 time of day.
+This format is also recognized if the `T' is replaced by a space.
+
+ In this format, the time of day should use 24-hour notation.
+Fractional seconds are allowed, with either comma or period preceding
+the fraction. ISO 8601 fractional minutes and hours are not supported.
+Typically, hosts support nanosecond timestamp resolution; excess
+precision is silently discarded.
+
+ Here are some examples:
+
+ 2012-09-24T20:02:00.052-0500
+ 2012-12-31T23:59:59,999999999+1100
+ 1970-01-01 00:00Z
+
+\1f
+File: tar.info, Node: Day of week items, Next: Relative items in date strings, Prev: Combined date and time of day items, Up: Date input formats
+
+7.6 Day of week items
=====================
The explicit mention of a day of the week will forward the date (only
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.22 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
-
projects / debian / tar / blobdiff